fix(typescript): compile MCP server when the document defines no servers

AS
7h ago
+16-5

Why

With enableMCPServer: true, a TypeScript SDK generated from a document that defines no servers (or only relative ones) fails npm run build:

src/mcp-server/cli/start/impl.ts(23,40): error TS2339: Property 'serverIdx' does not exist on type 'SDKOptions'.
src/mcp-server/server.ts(25,26): error TS2339: Property 'serverIdx' does not exist on type 'SDKOptions'.
src/mcp-server/server.ts(34,5): error TS2353: Object literal may only specify known properties, and 'serverIdx' does not exist in type 'SDKOptions'.

src/lib/config.ts only declares SDKOptions.serverIdx (or SDKOptions.server for named servers) when the document has a server with an absolute URL. The MCP server templates emitted the --server-index flag and the serverIdx pass-through whenever any servers object existed, which is always the case because the generator injects an implicit / server.

What changed

templates/templates/typescriptv2/mcp-server/{cli/start/impl.ts,cli/start/command.ts,server.ts,create-mcp-server.ts}.stmpl now gate the server-selection flag, the serverIdx/server dependency field and its pass-through on the same $hasServers predicate config.ts.stmpl uses. create-mcp-server.ts.stmpl gains that predicate definition.

Generated output is unchanged for documents that define an absolute server. For documents with no servers or only relative servers the MCP server no longer emits the --server-index flag, which never had a valid value there, and compiles.

The mcp-typescript target is not affected: its config.ts always declares serverIdx, and its MCP templates already use the matching predicate.

Testing

  • Minimal document with one GET operation and no servers, enableMCPServer: true, zodVersion: v3: reproduced the three errors above on main; with this change npm run build passes and mcp start --help shows no --server-index.
  • Same document with servers: [/relative-url]: builds.
  • Same document with two absolute servers: generated output is byte-identical before and after this change (outside .speakeasy/), builds, and mcp start --help still lists --server-index.
  • npm run format, make check-template-typescriptv2, make lint: clean.
  • Review SDK not regenerated: the review configuration has enableMCPServer: false, so this path is not exercised there.

Public-safety check

  • This change contains no credentials, customer documents, private repository URLs, private filesystem paths, or unredacted private logs.
  • Title, body, comments, and commit messages name no customers or customer-derived identifiers, private paths or trackers, or workflow provenance, and are understandable without private context (.claude/skills/public-repo-communication/SKILL.md).
  • Generated fixtures and review SDK changes are public-safe.
  • I reviewed git diff --check.

Summary by cubic

Fixes TypeScript compilation of the generated MCP server when the OpenAPI document defines no servers or only relative ones. The MCP templates always emitted the --server-index flag and serverIdx/server pass-through whenever a servers object existed, but config.ts only declares those fields when a server has an absolute URL, so npm run build failed with TS2339/TS2353 errors.

  • MCP server templates now gate the server-selection flag and serverIdx/server pass-through on the same $hasServers predicate config.ts uses.
  • Generated output for documents with absolute servers is unchanged.
  • The mcp-typescript target already used the matching predicate and is unaffected.