Skip to content

Commit 4374f3c

Browse files
fix(cli,mcp): name the MCP server objectstack in os dev's banner, from the constant the served SKILL.md reads (#25425)
<!-- claude-projects-attribution: {"github_login":"os-sales"} --> _Requested by **Sales** · [project thread](https://claude.ai/code/project/chan_01D5bWFY3rFzgJcytD5gD4Uu?thread=cmsg_01D5bWFY3rFzgJcytD5gD4UuDWJsBGQpadCH8JR2xZQ5re)_ Part of #25341 (the `domain:cli` half: the boot banner and the served SKILL.md). The console's Connect an Agent snippets are objectstack-ai/objectui#13357; this PR leaves that half alone. Clause-②: no Metadata-protocol: none ## What changed The maintainer's ruling (hotcrm#2194 T2-U22, ruling record `6354968262`) says to use one server name in both places. This PR uses the platform constant **`objectstack`**: - `packages/mcp/src/skill-md.ts` exports `OBJECTSTACK_MCP_SERVER_NAME = 'objectstack'`, re-exported from `@objectstack/mcp`. The served SKILL.md's `claude mcp add --transport http NAME URL` now reads it. - `packages/cli/src/commands/dev.ts`: `printMcpConnectHint` reads the same constant and drops its `name` option. The call site no longer passes `path.basename(process.cwd()) || 'objectstack'`, which is where `hotcrm` came from. ## Why this name and not the app's declared name The issue allowed either the app's name or the deployment's. Today no producer reads a declared app name: - The banner used the **folder** name. - The skill route (`packages/runtime/src/domains/mcp.ts`) calls `renderSkill({ mcpUrl })` and has no app identity in reach. The skill is generic across every app a key can reach (ADR-0036 Amendment C). - objectui#13357 records that discovery serves no server name for the console to read. Using the app's name would need a new served field in both the skill route and discovery. That is a contract addition, out of scope for an S card. The console snippets already say `objectstack`, so with this PR all three surfaces agree, and objectui#13357 has nothing to change. ## Pins - `packages/cli/src/commands/dev-mcp-connect-hint-origin.test.ts`, new block "the Connect row names the server the way the served SKILL.md does": - drives both producers (`printMcpConnectHint` and `renderSkillMarkdown`) and asserts that each `claude mcp add` names `OBJECTSTACK_MCP_SERVER_NAME`; - a source pin asserts that dev.ts imports the constant and has no `basename(process.cwd())`. - The existing Connect-row expectations now read `objectstack`. - `packages/mcp/src/skill-md.test.ts`: the skill's connect command names the exported constant. ## Verification (head `ed39dfa362`) - Build: `pnpm --filter '@objectstack/cli^...' build`. VERDICT command-exit 0. - `@objectstack/mcp`: `pnpm --filter @objectstack/mcp test` passed (42 files, 533 tests). Its typecheck is green. - `@objectstack/cli`: `pnpm --filter @objectstack/cli build`, then `vitest run --project unit` passed (326 files, 4804 tests). Its typecheck is green. - The integration layer is left to CI. No integration-tier or spawn-entry file changed. - `pnpm lint`: VERDICT command-exit 0. - `dispatch-gates --ran`: 67 derived, 65 run with exit 0, 2 NOT MEASURED, 0 UNRUN. The two NOT MEASURED gates: - `check:dual-build-cjs-loads` - `check:i18n-coverage` Both exited 3 with PREREQUISITE NOT MET: they need packages outside this closure built, and this local run did not build them. CI runs both on a fresh build. ## Acceptance notes - Docs examples (`content/docs/ai/connect-mcp.mdx`, `content/docs/getting-started/build-with-claude-code.mdx`, the blog post) name the server `my-app` / `support-desk`. In a user-typed command that name is the user's own choice, so this PR leaves them as they are. - `MCPServerRuntime`'s default handshake name (`mcp-server-runtime.ts`, `name: 'objectstack'`) is a separate literal with the same value, outside this card's file surface. - If you registered the server under the folder name from an earlier banner, that entry keeps working. The changeset gives the one-line cleanup. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01CxBKycaiUpA1yGx1XyoGqX --- _Generated by [Claude Code](https://claude.ai/code/session_01CxBKycaiUpA1yGx1XyoGqX)_ Co-authored-by: Claude <noreply@anthropic.com>
1 parent d0a1361 commit 4374f3c

6 files changed

Lines changed: 98 additions & 26 deletions

File tree

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
'@objectstack/mcp': patch
3+
'@objectstack/cli': patch
4+
---
5+
6+
fix(cli,mcp): `os dev`'s boot banner and the served SKILL.md name the MCP server the same way
7+
8+
Clause-②: no
9+
Metadata-protocol: none
10+
11+
`os dev`'s "connect a coding agent" block printed `claude mcp add --transport http FOLDER URL`, where FOLDER was the basename of the directory `os dev` ran in. The served `SKILL.md` (`GET /api/v1/mcp/skill`) and the console's Connect an Agent snippets name the server `objectstack`. So one endpoint ended up in an agent's config under two names, depending on which instructions were followed.
12+
13+
Both producers now read one exported constant, `OBJECTSTACK_MCP_SERVER_NAME` (`'objectstack'`), from `@objectstack/mcp`. The banner's `Connect` row prints `claude mcp add --transport http objectstack URL`. If you registered the server under the folder name from an earlier banner, that entry keeps working. Remove it with `claude mcp remove FOLDER` if you also added it as `objectstack`.
14+
15+
`printMcpConnectHint` no longer takes a `name` option.

‎packages/cli/src/commands/dev-mcp-connect-hint-origin.test.ts‎

Lines changed: 46 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@ import { readFileSync } from 'node:fs';
3434
import { dirname, resolve } from 'node:path';
3535
import { fileURLToPath } from 'node:url';
3636
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
37+
import { OBJECTSTACK_MCP_SERVER_NAME, renderSkillMarkdown } from '@objectstack/mcp';
3738
import { printMcpConnectHint } from './dev.js';
3839
import { AUTH_BASE_URL_ENV_NAMES, resolveAuthBaseUrl } from './serve.js';
3940
import { printServerReady, type ServerReadyOptions } from '../utils/format.js';
@@ -90,12 +91,12 @@ describe('os dev MCP connect hint — origin (#16734)', () => {
9091
* child's banner (its own call site's expression, verbatim) and then the
9192
* parent's connect hint, both told the port the server ACTUALLY bound.
9293
*/
93-
const boot = (boundPort: number, name = 'hotcrm', boundProtocol: 'http' | 'https' = 'http') => {
94+
const boot = (boundPort: number, boundProtocol: 'http' | 'https' = 'http') => {
9495
printServerReady({
9596
...bannerOpts,
9697
externalBaseOrigin: resolveAuthBaseUrl(boundPort, boundProtocol).baseOrigin,
9798
});
98-
printMcpConnectHint({ boundPort, name, boundProtocol });
99+
printMcpConnectHint({ boundPort, boundProtocol });
99100
return lines.join('\n');
100101
};
101102

@@ -111,9 +112,9 @@ describe('os dev MCP connect hint — origin (#16734)', () => {
111112
* derived protocol leaked into the default, and it cannot pass by both legs
112113
* being broken in the same direction.
113114
*/
114-
const bootWithoutProtocolArg = (boundPort: number, name = 'hotcrm') => {
115+
const bootWithoutProtocolArg = (boundPort: number) => {
115116
printServerReady({ ...bannerOpts, externalBaseOrigin: resolveAuthBaseUrl(boundPort).baseOrigin });
116-
printMcpConnectHint({ boundPort, name });
117+
printMcpConnectHint({ boundPort });
117118
return lines.join('\n');
118119
};
119120

@@ -129,7 +130,7 @@ describe('os dev MCP connect hint — origin (#16734)', () => {
129130
expect(output).toContain('Endpoint https://localhost:4443/api/v1/mcp');
130131
expect(output).toContain('Skill https://localhost:4443/api/v1/mcp/skill');
131132
expect(output).toContain(
132-
'Connect claude mcp add --transport http hotcrm https://localhost:4443/api/v1/mcp',
133+
'Connect claude mcp add --transport http objectstack https://localhost:4443/api/v1/mcp',
133134
);
134135

135136
// The reported symptom, stated as the absence it is: the bound socket
@@ -162,13 +163,13 @@ describe('os dev MCP connect hint — origin (#16734)', () => {
162163
// ── Acceptance 2 — the negative control ─────────────────────────────────
163164
describe('with OS_AUTH_URL unset, the hint still prints the LISTEN origin', () => {
164165
it('names the bound port on an ordinary local boot', () => {
165-
const output = boot(3000, 'my-app');
166+
const output = boot(3000);
166167

167168
expect(output).toContain('MCP: http://localhost:3000/api/v1/mcp');
168169
expect(output).toContain('Endpoint http://localhost:3000/api/v1/mcp');
169170
expect(output).toContain('Skill http://localhost:3000/api/v1/mcp/skill');
170171
expect(output).toContain(
171-
'Connect claude mcp add --transport http my-app http://localhost:3000/api/v1/mcp',
172+
'Connect claude mcp add --transport http objectstack http://localhost:3000/api/v1/mcp',
172173
);
173174
expect(mcpOrigins(output)).toEqual(['http://localhost:3000']);
174175
});
@@ -177,11 +178,11 @@ describe('os dev MCP connect hint — origin (#16734)', () => {
177178
// The case the surrounding code exists to handle. A fix that reached for
178179
// a canonical origin instead of the resolver would print :3000 here, or
179180
// nothing at all; both are worse than the behaviour being repaired.
180-
const output = boot(3001, 'my-app');
181+
const output = boot(3001);
181182

182183
expect(output).toContain('Endpoint http://localhost:3001/api/v1/mcp');
183184
expect(output).toContain(
184-
'Connect claude mcp add --transport http my-app http://localhost:3001/api/v1/mcp',
185+
'Connect claude mcp add --transport http objectstack http://localhost:3001/api/v1/mcp',
185186
);
186187
expect(output).not.toContain('3000');
187188
expect(mcpOrigins(output)).toEqual(['http://localhost:3001']);
@@ -231,13 +232,13 @@ describe('os dev MCP connect hint — origin (#16734)', () => {
231232
// Every chain variable is deleted by `beforeEach`, so the only thing
232233
// that can produce `https` here is the listener protocol reaching the
233234
// resolver's built-in tail.
234-
const output = boot(3000, 'hotcrm', 'https');
235+
const output = boot(3000, 'https');
235236

236237
expect(output).toContain('MCP: https://localhost:3000/api/v1/mcp');
237238
expect(output).toContain('Endpoint https://localhost:3000/api/v1/mcp');
238239
expect(output).toContain('Skill https://localhost:3000/api/v1/mcp/skill');
239240
expect(output).toContain(
240-
'Connect claude mcp add --transport http hotcrm https://localhost:3000/api/v1/mcp',
241+
'Connect claude mcp add --transport http objectstack https://localhost:3000/api/v1/mcp',
241242
);
242243
// The plain-http address must not appear anywhere in a TLS boot's output:
243244
// it is the one address a client on this port cannot reach.
@@ -246,14 +247,14 @@ describe('os dev MCP connect hint — origin (#16734)', () => {
246247
});
247248

248249
it("follows dev's auto-shifted port under TLS too", () => {
249-
expect(mcpOrigins(boot(3001, 'hotcrm', 'https'))).toEqual(['https://localhost:3001']);
250+
expect(mcpOrigins(boot(3001, 'https'))).toEqual(['https://localhost:3001']);
250251
});
251252

252253
it('acceptance 3: `OS_AUTH_URL` still WINS over the derived https origin', () => {
253254
// The override direction that matters in practice: a developer
254255
// terminating TLS locally but reached through a tunnel on another host.
255256
process.env.OS_AUTH_URL = 'https://tunnel.example.com';
256-
expect(mcpOrigins(boot(3000, 'hotcrm', 'https'))).toEqual(['https://tunnel.example.com']);
257+
expect(mcpOrigins(boot(3000, 'https'))).toEqual(['https://tunnel.example.com']);
257258
});
258259

259260
it('acceptance 3, the awkward direction: an http OS_AUTH_URL wins as well', () => {
@@ -262,17 +263,17 @@ describe('os dev MCP connect hint — origin (#16734)', () => {
262263
// plain http, or in a test harness, that is a deliberate statement about
263264
// a different hop, and a default has no standing to overrule it.
264265
process.env.OS_AUTH_URL = 'http://proxied.example.com';
265-
expect(mcpOrigins(boot(3000, 'hotcrm', 'https'))).toEqual(['http://proxied.example.com']);
266+
expect(mcpOrigins(boot(3000, 'https'))).toEqual(['http://proxied.example.com']);
266267
});
267268

268269
it('the rest of the configured chain keeps its precedence under TLS', () => {
269270
process.env.OS_BASE_URL = 'https://base.example.com';
270-
expect(mcpOrigins(boot(3000, 'hotcrm', 'https'))).toEqual(['https://base.example.com']);
271+
expect(mcpOrigins(boot(3000, 'https'))).toEqual(['https://base.example.com']);
271272
});
272273

273274
it('an unusable value stays unusable — TLS does not manufacture an origin', () => {
274275
process.env.OS_AUTH_URL = '';
275-
const output = boot(3000, 'hotcrm', 'https');
276+
const output = boot(3000, 'https');
276277
expect(mcpOrigins(output)).toEqual([]);
277278
expect(output).not.toContain('claude mcp add');
278279
expect(output).not.toContain('https://localhost:3000');
@@ -283,10 +284,10 @@ describe('os dev MCP connect hint — origin (#16734)', () => {
283284
describe('without the flags the output is byte-for-byte what it was', () => {
284285
it('the no-flag boot equals the boot that never passes a protocol at all', () => {
285286
// Leg A: the call shape this file used before `--cert`/`--key` existed.
286-
const before = bootWithoutProtocolArg(3000, 'my-app');
287+
const before = bootWithoutProtocolArg(3000);
287288
lines.length = 0;
288289
// Leg B: the same boot through today's call shape, no flags given.
289-
const after = boot(3000, 'my-app', 'http');
290+
const after = boot(3000, 'http');
290291

291292
expect(after).toBe(before);
292293
// And the byte the two legs are about: still plain http, on the bound port.
@@ -296,17 +297,17 @@ describe('os dev MCP connect hint — origin (#16734)', () => {
296297
it('the two legs also agree on an auto-shifted port and an ephemeral one', () => {
297298
for (const port of [3001, 45064]) {
298299
lines.length = 0;
299-
const before = bootWithoutProtocolArg(port, 'my-app');
300+
const before = bootWithoutProtocolArg(port);
300301
lines.length = 0;
301-
expect(boot(port, 'my-app', 'http')).toBe(before);
302+
expect(boot(port, 'http')).toBe(before);
302303
}
303304
});
304305

305306
it('and the legs DISCRIMINATE — the https leg differs from both', () => {
306307
// Without this, two legs that both silently produced nothing would pass.
307-
const plain = bootWithoutProtocolArg(3000, 'my-app');
308+
const plain = bootWithoutProtocolArg(3000);
308309
lines.length = 0;
309-
const tls = boot(3000, 'my-app', 'https');
310+
const tls = boot(3000, 'https');
310311

311312
expect(tls).not.toBe(plain);
312313
expect(mcpOrigins(plain)).toEqual(['http://localhost:3000']);
@@ -355,4 +356,27 @@ describe('os dev MCP connect hint — origin (#16734)', () => {
355356
}
356357
});
357358
});
359+
360+
// ── One server name for one endpoint ────────────────────────────────────
361+
describe('the Connect row names the server the way the served SKILL.md does', () => {
362+
/** The `<name>` of every `claude mcp add --transport http <name> <url>` in a text. */
363+
const connectNames = (text: string): string[] =>
364+
[...text.matchAll(/claude mcp add --transport http (\S+) /g)].map((m) => m[1]);
365+
366+
it('both producers print the one exported name', () => {
367+
const banner = connectNames(boot(3000));
368+
const skill = connectNames(renderSkillMarkdown({ mcpUrl: 'http://localhost:3000/api/v1/mcp' }));
369+
370+
expect(banner).toEqual([OBJECTSTACK_MCP_SERVER_NAME]);
371+
expect(skill).toEqual([OBJECTSTACK_MCP_SERVER_NAME]);
372+
});
373+
374+
it('dev reads that constant and derives no name of its own', () => {
375+
// The name used to be the folder `os dev` ran in, so a `hotcrm/` checkout
376+
// registered the server as `hotcrm` while the skill said `objectstack`.
377+
expect(DEV_SOURCE).toContain("import { OBJECTSTACK_MCP_SERVER_NAME } from '@objectstack/mcp';");
378+
expect(DEV_SOURCE).toContain('claude mcp add --transport http ${OBJECTSTACK_MCP_SERVER_NAME} ');
379+
expect(DEV_SOURCE).not.toMatch(/basename\(process\.cwd\(\)\)/);
380+
});
381+
});
358382
});

‎packages/cli/src/commands/dev.ts‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ import {
3333
} from '../utils/artifact-precedence.js';
3434
import { artifactObjectNames } from '../utils/stack-collections.js';
3535
import { readEnvWithDeprecation, isMcpServerEnabled } from '@objectstack/types';
36+
import { OBJECTSTACK_MCP_SERVER_NAME } from '@objectstack/mcp';
3637
// The ONE port contract, shared with `start` and with the `serve` child this
3738
// command spawns (#12673). ⛔ Nothing about ports is declared in this file —
3839
// no range, no reader, no wording; a second copy of the bound is exactly what
@@ -179,17 +180,25 @@ export function prepareDevDatabaseDirectory(
179180
* fixes it. A connect COMMAND has no paths-only form, so the honest output
180181
* here is no block at all: falling back to the bound socket would reprint, on
181182
* the same screen, the exact address the banner just refused to print.
183+
*
184+
* ## The server name is not this process's to choose
185+
*
186+
* ⛔ The `Connect` row names the server {@link OBJECTSTACK_MCP_SERVER_NAME},
187+
* the same constant the served `SKILL.md` (`GET /api/v1/mcp/skill`) reads. It
188+
* used to be the current folder's basename, so one endpoint was registered as
189+
* the folder's name from the banner and as `objectstack` from the skill and
190+
* the console: two entries for one server in the agent's config.
182191
*/
183192
export function printMcpConnectHint(
184-
opts: { boundPort: number | string; name: string; boundProtocol?: ListenerProtocol },
193+
opts: { boundPort: number | string; boundProtocol?: ListenerProtocol },
185194
): void {
186195
const { baseOrigin } = resolveAuthBaseUrl(opts.boundPort, opts.boundProtocol ?? 'http');
187196
if (baseOrigin === null) return;
188197
console.log();
189198
console.log(chalk.cyan(' 🤖 MCP server — connect a coding agent:'));
190199
console.log(` Endpoint ${baseOrigin}/api/v1/mcp`);
191200
console.log(` Skill ${baseOrigin}/api/v1/mcp/skill`);
192-
console.log(chalk.dim(` Connect claude mcp add --transport http ${opts.name} ${baseOrigin}/api/v1/mcp`));
201+
console.log(chalk.dim(` Connect claude mcp add --transport http ${OBJECTSTACK_MCP_SERVER_NAME} ${baseOrigin}/api/v1/mcp`));
193202
console.log(chalk.dim(' Disable OS_MCP_SERVER_ENABLED=false'));
194203
}
195204

@@ -841,7 +850,6 @@ export default class Dev extends Command {
841850
// prints and this block cannot name two different deployments.
842851
printMcpConnectHint({
843852
boundPort: actual,
844-
name: path.basename(process.cwd()) || 'objectstack',
845853
// ⭐ From THIS process's own flags, which are the same flags it
846854
// forwarded to the child — so the scheme the hint prints and the
847855
// scheme the child bound cannot part company (#16804).

‎packages/mcp/src/index.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ export {
3030
renderSkillMarkdown,
3131
OBJECTSTACK_SKILL_NAME,
3232
OBJECTSTACK_SKILL_DESCRIPTION,
33+
OBJECTSTACK_MCP_SERVER_NAME,
3334
} from './skill-md.js';
3435
export type { RenderSkillOptions } from './skill-md.js';
3536
// The `skill` metadata type (`SkillSchema`) → MCP `prompts` primitive (#3905).

‎packages/mcp/src/skill-md.test.ts‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ import {
66
renderSkillMarkdown,
77
OBJECTSTACK_SKILL_NAME,
88
OBJECTSTACK_SKILL_DESCRIPTION,
9+
OBJECTSTACK_MCP_SERVER_NAME,
910
} from './skill-md.js';
1011

1112
/** Pull the YAML frontmatter block (between the first two `---` lines). */
@@ -33,6 +34,16 @@ describe('renderSkillMarkdown', () => {
3334
expect(md).not.toContain('<YOUR_ENV_MCP_URL>');
3435
});
3536

37+
it('names the MCP server in its connect command by the one exported constant', () => {
38+
// `os dev`'s boot banner reads the same constant (packages/cli
39+
// dev-mcp-connect-hint-origin.test.ts pins that half), so one endpoint is
40+
// never registered under two names.
41+
expect(OBJECTSTACK_MCP_SERVER_NAME).toBe('objectstack');
42+
const md = renderSkillMarkdown({ mcpUrl: 'https://acme.objectos.app/api/v1/mcp' });
43+
const names = [...md.matchAll(/claude mcp add --transport http (\S+) /g)].map((m) => m[1]);
44+
expect(names).toEqual([OBJECTSTACK_MCP_SERVER_NAME]);
45+
});
46+
3647
it('falls back to a clearly-marked placeholder when no URL is given', () => {
3748
expect(renderSkillMarkdown()).toContain('<YOUR_ENV_MCP_URL>');
3849
});

‎packages/mcp/src/skill-md.ts‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,19 @@
3232

3333
/** Skill identity (mirrors the `SKILL.md` YAML frontmatter). */
3434
export const OBJECTSTACK_SKILL_NAME = 'objectstack';
35+
/**
36+
* The name every connect snippet this platform prints gives the MCP server
37+
* (the `<name>` in `claude mcp add --transport http <name> <url>`).
38+
*
39+
* ONE name for one endpoint: the served `SKILL.md` below and `os dev`'s boot
40+
* banner (`printMcpConnectHint` in `@objectstack/cli`) both read this
41+
* constant, so a reader who follows either never registers the same server
42+
* twice under two names. It is deliberately the platform's name, not the app
43+
* folder's or the manifest's: the served skill is generic across every app
44+
* the caller's key can reach (ADR-0036 Amendment C), and neither the skill
45+
* route nor discovery serves an app name a console snippet could read.
46+
*/
47+
export const OBJECTSTACK_MCP_SERVER_NAME = 'objectstack';
3548
export const OBJECTSTACK_SKILL_DESCRIPTION =
3649
'Query and modify data in an ObjectStack app over MCP — discover objects, ' +
3750
'read and filter records, and create/update/delete under your own ' +
@@ -107,7 +120,7 @@ intersection of the consent scopes you grant and your own permissions/RLS (it
107120
can never exceed either). Example (Claude Code):
108121
109122
\`\`\`
110-
claude mcp add --transport http objectstack ${url}
123+
claude mcp add --transport http ${OBJECTSTACK_MCP_SERVER_NAME} ${url}
111124
\`\`\`
112125
113126
**API key (headless: CI, scripts, agents without a browser).** Send an

0 commit comments

Comments
 (0)