Iteration three: generate a runnable MCP server from the design

New 'MCP server' export emits a complete TypeScript project — static MCP
runtime (stdio) + generated per-operation data. Each tool proxies to its real
OpenAPI operation (path/query/header/body mapping), resources and prompts are
served, and auth is derived from the spec's security scheme. Download the zip,
npm install && npm run dev, and it serves.

Verified: generated against the live API Evangelist OpenAPI, installed the real
@modelcontextprotocol/sdk (1.29), tsc --noEmit clean, and an MCP client drove
it end to end — tools/resources/prompts list, prompt render, and live upstream
tool calls (get_service_info, search_network) returned real API responses.

Also fixed a latent tsc-only Blob typing error in zip.ts (iteration one).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: kinlane

README.md

@@ -15,6 +15,7 @@ An OpenAPI tells developers what your API can do. Agents need more. Toolsmith is
   - an **MCP server design** — tools, resources, prompts, and sampling in the shapes MCP clients see
   - a registry-ready **server.json** ([2025-09-29 schema](https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json)) for the official MCP Registry
   - an **Agent Skills bundle** — one [`SKILL.md`](https://agentskills.io/specification) per skill, zipped by directory, with an [agent-skills-discovery](https://github.com/cloudflare/agent-skills-discovery-rfc) v0.2.0 `index.json` ready for `.well-known/agent-skills/`
+  - a **runnable MCP server** — a complete TypeScript project (official [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk), stdio) where every tool proxies to its real OpenAPI operation with path/query/header/body mapping and auth derived from the spec's security scheme; `npm install && npm run dev` and it serves. The runtime is static; only the operation data is generated, so you can regenerate as the design evolves.
   - the **APIs.json properties** that wire the artifacts to your provider listing
 
 ## Develop

index.html

@@ -82,6 +82,7 @@ <h3>Operations</h3>
             <button class="out-tab is-active" data-out="openapi">Enriched OpenAPI</button>
             <button class="out-tab" data-out="mcp">MCP design</button>
             <button class="out-tab" data-out="serverjson">server.json</button>
+            <button class="out-tab" data-out="scaffold">MCP server</button>
             <button class="out-tab" data-out="skills">Agent Skills</button>
             <button class="out-tab" data-out="apisjson">APIs.json</button>
           </div>

src/engine.ts

@@ -421,3 +421,268 @@ export function emitApisJsonProps(doc: any): any {
     { type: 'AgentSkills', url: 'https://example.com/.well-known/agent-skills/index.json', description: `Agent Skills for working with ${title} competently.` },
   ];
 }
+
+// ---- MCP server scaffold (runnable TypeScript codegen) -------------------------
+// Turn the design into a complete, runnable stdio MCP server that proxies each tool
+// to its real OpenAPI operation. The runtime (src/index.ts) is static; only the
+// operation data and auth (src/operations.ts) are generated from the design.
+export const MCP_SDK_RANGE = '^1.12.0';
+
+// Derive an applyAuth(headers, query) body + .env keys from the OpenAPI security scheme.
+function generateAuth(doc: any): { body: string; env: string[]; note: string } {
+  const schemes = (doc.components?.securitySchemes) || {};
+  const first = Object.values(schemes)[0] as any;
+  const s = first ? deref(doc, first) : null;
+  if (s?.type === 'http' && /^basic$/i.test(s.scheme || '')) {
+    return {
+      body: [
+        '  if (process.env.API_USER && process.env.API_PASS) {',
+        '    const token = Buffer.from(process.env.API_USER + ":" + process.env.API_PASS).toString("base64");',
+        '    headers["authorization"] = "Basic " + token;',
+        '  }',
+      ].join('\n'),
+      env: ['API_USER=', 'API_PASS='],
+      note: 'Basic auth: set `API_USER` and `API_PASS`.',
+    };
+  }
+  if (s?.type === 'apiKey' && s.in === 'header') {
+    return {
+      body: `  if (process.env.API_KEY) headers[${JSON.stringify(String(s.name || 'x-api-key').toLowerCase())}] = process.env.API_KEY;`,
+      env: ['API_KEY='],
+      note: `API key header (\`${s.name}\`): set \`API_KEY\`.`,
+    };
+  }
+  if (s?.type === 'apiKey' && s.in === 'query') {
+    return {
+      body: `  if (process.env.API_KEY) query.set(${JSON.stringify(String(s.name || 'api_key'))}, process.env.API_KEY);`,
+      env: ['API_KEY='],
+      note: `API key query param (\`${s.name}\`): set \`API_KEY\`.`,
+    };
+  }
+  // bearer, oauth2, openIdConnect, or nothing declared → optional bearer token
+  const declared = s?.type === 'http' || s?.type === 'oauth2' || s?.type === 'openIdConnect';
+  return {
+    body: '  if (process.env.API_TOKEN) headers["authorization"] = "Bearer " + process.env.API_TOKEN;',
+    env: ['API_TOKEN='],
+    note: declared
+      ? 'Bearer token: set `API_TOKEN`.'
+      : 'No security scheme was declared in the OpenAPI — the scaffold falls back to an optional `API_TOKEN` bearer. Edit `applyAuth` in `src/operations.ts` if your API differs.',
+  };
+}
+
+const INDEX_TS = `#!/usr/bin/env node
+// Generated by Toolsmith (toolsmith.apicommons.org). This runtime is static — it reads
+// the generated operation data in ./operations.ts and serves it over MCP (stdio),
+// proxying each tool call to the upstream REST API.
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { SERVER, BASE_URL, TOOLS, RESOURCES, PROMPTS, applyAuth } from "./operations.js";
+
+const server = new Server(
+  { name: SERVER.name, version: SERVER.version },
+  { capabilities: { tools: {}, resources: {}, prompts: {} } },
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: TOOLS.map((t) => ({
+    name: t.name,
+    title: t.title,
+    description: t.description,
+    inputSchema: t.inputSchema,
+    annotations: t.annotations,
+  })),
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const tool = TOOLS.find((t) => t.name === req.params.name);
+  if (!tool) return { content: [{ type: "text", text: "Unknown tool: " + req.params.name }], isError: true };
+  try {
+    const text = await callOperation(tool, req.params.arguments || {});
+    return { content: [{ type: "text", text }] };
+  } catch (err) {
+    const msg = err && err.message ? err.message : String(err);
+    return { content: [{ type: "text", text: "Error calling " + tool.name + ": " + msg }], isError: true };
+  }
+});
+
+async function callOperation(tool, args) {
+  let path = tool.path;
+  const query = new URLSearchParams();
+  const headers = { accept: "application/json" };
+  let body;
+  for (const key of Object.keys(args)) {
+    const value = args[key];
+    if (value === undefined || value === null) continue;
+    if (key === "body") { body = JSON.stringify(value); headers["content-type"] = "application/json"; continue; }
+    const param = tool.params.find((p) => p.name === key);
+    const loc = param ? param.in : "query";
+    if (loc === "path") path = path.split("{" + key + "}").join(encodeURIComponent(String(value)));
+    else if (loc === "header") headers[key] = String(value);
+    else query.set(key, String(value));
+  }
+  applyAuth(headers, query);
+  const qs = query.toString();
+  const url = BASE_URL.replace(/\\/+$/, "") + path + (qs ? "?" + qs : "");
+  const resp = await fetch(url, { method: tool.method, headers, body });
+  const text = await resp.text();
+  if (!resp.ok) throw new Error("HTTP " + resp.status + " from " + url + ": " + text.slice(0, 500));
+  return text;
+}
+
+server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+  resources: RESOURCES.map((r) => ({ uri: r.uri, name: r.name, description: r.description, mimeType: r.mimeType })),
+}));
+
+server.setRequestHandler(ReadResourceRequestSchema, async (req) => {
+  const r = RESOURCES.find((x) => x.uri === req.params.uri);
+  if (!r) throw new Error("Unknown resource: " + req.params.uri);
+  if (/^https?:/.test(r.uri)) {
+    const resp = await fetch(r.uri, { headers: { accept: r.mimeType || "text/plain" } });
+    const text = await resp.text();
+    return { contents: [{ uri: r.uri, mimeType: r.mimeType || "text/plain", text }] };
+  }
+  return { contents: [{ uri: r.uri, mimeType: r.mimeType || "text/markdown", text: r.description || "" }] };
+});
+
+server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+  prompts: PROMPTS.map((p) => ({ name: p.name, description: p.description, arguments: p.arguments })),
+}));
+
+server.setRequestHandler(GetPromptRequestSchema, async (req) => {
+  const p = PROMPTS.find((x) => x.name === req.params.name);
+  if (!p) throw new Error("Unknown prompt: " + req.params.name);
+  let text = p.template;
+  const a = req.params.arguments || {};
+  for (const key of Object.keys(a)) text = text.split("{{" + key + "}}").join(String(a[key]));
+  return { description: p.description, messages: [{ role: "user", content: { type: "text", text } }] };
+});
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error(SERVER.name + " MCP server running on stdio — " + TOOLS.length + " tools, " + RESOURCES.length + " resources, " + PROMPTS.length + " prompts.");
+}
+main().catch((err) => { console.error(err); process.exit(1); });
+`;
+
+export function emitServerScaffold(doc: any, ops: Operation[]): { path: string; content: string }[] {
+  const s = getServer(doc);
+  const title = doc.info?.title || 'API';
+  const pkg = kebab(title) || 'api';
+  const baseUrl = doc.servers?.[0]?.url || 'https://api.example.com';
+  const auth = generateAuth(doc);
+
+  const tools: any[] = [];
+  const resources: any[] = []; const seenRes = new Set<string>();
+  const prompts: any[] = []; const seenPrompt = new Set<string>();
+  const sampling: { tool: string; purpose: string }[] = [];
+  for (const op of ops) {
+    const t = getTool(doc, op); if (!t) continue;
+    tools.push({
+      name: t.name, title: t.title || undefined, description: t.description,
+      method: op.method.toUpperCase(), path: op.path,
+      params: op.params.filter((p) => p.name).map((p) => ({ name: p.name, in: p.in || 'query' })),
+      inputSchema: t.inputSchema || { type: 'object' },
+      annotations: t.annotations || {},
+    });
+    for (const r of t.resources || []) { if (!r.uri || seenRes.has(r.uri)) continue; seenRes.add(r.uri); resources.push({ name: r.name, uri: r.uri, description: r.description || '', mimeType: r.mimeType || 'text/markdown' }); }
+    for (const p of t.prompts || []) { let name = p.name || 'prompt'; let n = 2; while (seenPrompt.has(name)) name = `${p.name}-${n++}`; seenPrompt.add(name); prompts.push({ name, description: p.description || '', arguments: p.arguments || [], template: p.template || '' }); }
+    if (t.sampling?.enabled) sampling.push({ tool: t.name, purpose: t.sampling.purpose || '' });
+  }
+
+  const operationsTs = [
+    '// Generated by Toolsmith — operation data + auth for this MCP server.',
+    '// Regenerate from your enriched OpenAPI; hand-edits here will be overwritten.',
+    `export const SERVER = { name: ${JSON.stringify(s.name)}, version: ${JSON.stringify(s.version || '0.1.0')} };`,
+    `export const BASE_URL = process.env.UPSTREAM_BASE_URL || ${JSON.stringify(baseUrl)};`,
+    '',
+    `export const TOOLS = ${JSON.stringify(tools, null, 2)};`,
+    '',
+    `export const RESOURCES = ${JSON.stringify(resources, null, 2)};`,
+    '',
+    `export const PROMPTS = ${JSON.stringify(prompts, null, 2)};`,
+    '',
+    '// Auth derived from the OpenAPI security scheme. ' + auth.note.replace(/`/g, ''),
+    'export function applyAuth(headers, query) {',
+    auth.body,
+    '}',
+    '',
+  ].join('\n');
+
+  const pkgJson = {
+    name: `${pkg}-mcp-server`, version: s.version || '0.1.0', private: true, type: 'module',
+    description: `MCP server for ${title}, generated by Toolsmith.`,
+    bin: { [`${pkg}-mcp`]: 'dist/index.js' },
+    scripts: { dev: 'tsx src/index.ts', build: 'tsc', start: 'node dist/index.js' },
+    engines: { node: '>=18' },
+    dependencies: { '@modelcontextprotocol/sdk': MCP_SDK_RANGE },
+    devDependencies: { typescript: '^5.7.2', tsx: '^4.19.2', '@types/node': '^22.10.0' },
+  };
+
+  const tsconfig = {
+    compilerOptions: { target: 'ES2022', module: 'NodeNext', moduleResolution: 'NodeNext', strict: false, esModuleInterop: true, skipLibCheck: true, outDir: 'dist', types: ['node'] },
+    include: ['src'],
+  };
+
+  const samplingDoc = sampling.length
+    ? ['', '## Sampling', '', 'These tools were designed to use sampling (asking the client\'s model to reason over results). The generated handlers return the raw upstream response; add a sampling round-trip with `server.createMessage(...)` where you want the server to summarize or transform before replying:', '', ...sampling.map((x) => `- \`${x.tool}\`${x.purpose ? ` — ${x.purpose}` : ''}`)].join('\n')
+    : '';
+
+  const readme = [
+    `# ${title} MCP Server`,
+    '',
+    `Generated by [Toolsmith](https://toolsmith.apicommons.org) from the enriched OpenAPI for **${title}**. A stdio [MCP](https://modelcontextprotocol.io) server that proxies each tool to the upstream REST API at \`${baseUrl}\`.`,
+    '',
+    `**${tools.length}** tools · **${resources.length}** resources · **${prompts.length}** prompts.`,
+    '',
+    '## Run',
+    '',
+    '```bash',
+    'npm install',
+    'npm run dev        # tsx src/index.ts (stdio)',
+    '# or: npm run build && npm start',
+    '```',
+    '',
+    '## Auth',
+    '',
+    auth.note,
+    'Copy `.env.example` to `.env` and fill it in (values are read from the environment; set `UPSTREAM_BASE_URL` to override the base URL).',
+    '',
+    '## Use it from a client',
+    '',
+    'Point any MCP client at the built server. For a stdio client config:',
+    '',
+    '```json',
+    JSON.stringify({ mcpServers: { [pkg]: { command: 'node', args: ['dist/index.js'], env: Object.fromEntries(auth.env.map((e) => [e.replace(/=$/, ''), ''])) } } }, null, 2),
+    '```',
+    '',
+    '## Structure',
+    '',
+    '- `src/index.ts` — static MCP runtime (tools/resources/prompts handlers + upstream proxy). Don\'t edit.',
+    '- `src/operations.ts` — generated operation data + `applyAuth`. Regenerate from Toolsmith.',
+    samplingDoc,
+    '',
+    'Regenerate `src/operations.ts` whenever the design changes; `src/index.ts` stays put.',
+    '',
+  ].join('\n');
+
+  const envExample = [`UPSTREAM_BASE_URL=${baseUrl}`, ...auth.env].join('\n') + '\n';
+
+  return [
+    { path: 'package.json', content: JSON.stringify(pkgJson, null, 2) + '\n' },
+    { path: 'tsconfig.json', content: JSON.stringify(tsconfig, null, 2) + '\n' },
+    { path: 'src/index.ts', content: INDEX_TS },
+    { path: 'src/operations.ts', content: operationsTs },
+    { path: '.env.example', content: envExample },
+    { path: '.gitignore', content: 'node_modules\ndist\n.env\n' },
+    { path: 'README.md', content: readme },
+  ];
+}

src/main.ts

@@ -3,7 +3,7 @@ import {
   parseDoc, operations, coverage, kebab, runChecks,
   getTool, setTool, getSkills, setSkills, getServer, setServer, getRootSkills, setRootSkills,
   draftTool, draftResource, draftPrompt, draftSkill, draftApiSkill, draftServer,
-  emitEnrichedOpenApi, emitMcpDesign, emitServerJson, emitSkillFiles, emitSkillsIndex, emitApisJsonProps,
+  emitEnrichedOpenApi, emitMcpDesign, emitServerJson, emitSkillFiles, emitSkillsIndex, emitApisJsonProps, emitServerScaffold,
   toYaml, toJson,
   type Operation, type ToolDesign, type SkillDesign, type PromptDesign, type Check,
 } from './engine';
@@ -27,7 +27,7 @@ let ops: Operation[] = [];
 let sourceLabel = '';
 let selectedKey = '';
 let mainTab: 'design' | 'source' | 'checks' | 'exports' = 'design';
-let outTab: 'openapi' | 'mcp' | 'serverjson' | 'skills' | 'apisjson' = 'openapi';
+let outTab: 'openapi' | 'mcp' | 'serverjson' | 'scaffold' | 'skills' | 'apisjson' = 'openapi';
 let currentOut = '';
 let saveTimer: number | undefined;
 
@@ -398,12 +398,18 @@ function emitOut() {
     openapi: 'Your OpenAPI with the agent layer embedded — x-mcp on each operation, x-agent-skills alongside, x-mcp-server at the root.',
     mcp: 'The MCP server design — tools, resources, prompts, and sampling in the shapes clients see. Hand this to whoever builds or generates the server.',
     serverjson: 'A registry-ready server.json (2025-09-29 schema) for publishing to the official MCP Registry.',
+    scaffold: 'A complete, runnable TypeScript MCP server — each tool wired to its OpenAPI operation, with resources, prompts, and auth from the spec. Download the project, then npm install && npm run dev.',
     skills: 'One SKILL.md per skill, each in its own directory, plus an agent-skills-discovery index.json (v0.2.0, the format apis.io serves at .well-known/agent-skills/). Download bundles it all as a zip.',
     apisjson: 'APIs.json property entries wiring these artifacts to your provider listing (swap in your real URLs).',
   };
   if (outTab === 'openapi') currentOut = emitEnrichedOpenApi(doc);
   else if (outTab === 'mcp') currentOut = toJson(emitMcpDesign(doc, ops));
   else if (outTab === 'serverjson') currentOut = toJson(emitServerJson(doc));
+  else if (outTab === 'scaffold') {
+    const files = emitServerScaffold(doc, ops);
+    const hasTool = ops.some((o) => coverage(doc, o).tool);
+    currentOut = hasTool ? files.map((f) => `━━ ${f.path} ━━\n${f.content}`).join('\n') : 'No MCP tools designed yet — draft some on the Design tab, then generate the server.';
+  }
   else if (outTab === 'skills') {
     const files = emitSkillFiles(doc, ops);
     currentOut = files.length
@@ -417,6 +423,11 @@ function emitOut() {
 function downloadOut() {
   if (!doc) return;
   const base = kebab(doc.info?.title || 'api');
+  if (outTab === 'scaffold') {
+    if (!ops.some((o) => coverage(doc, o).tool)) return;
+    const blob = makeZip(emitServerScaffold(doc, ops).map((f) => ({ path: `${base}-mcp-server/${f.path}`, content: f.content })));
+    dl(blob, `${base}-mcp-server.zip`); return;
+  }
   if (outTab === 'skills') {
     const files = emitSkillFiles(doc, ops); if (!files.length) return;
     const blob = makeZip([
@@ -438,7 +449,7 @@ function about() {
     <h2>Forge the agent layer of your API</h2>
     <p>An OpenAPI tells developers what your API can do. Agents need more: an <strong>MCP tool</strong> for each operation with an honest input schema and behavior annotations, the <strong>resources</strong> and <strong>prompts</strong> that give it context, <strong>sampling</strong> guidance where the server should lean on the client's model — and <strong>Agent Skills</strong> that teach an agent to apply each tool competently.</p>
     <p>Toolsmith is the workbench for that layer. Load an OpenAPI (the API Evangelist and APIs.io APIs are one click away), <strong>draft</strong> a design for every operation deterministically, then refine each tool, resource, prompt, and skill by hand. The design lives inside your OpenAPI as <code>x-mcp</code> and <code>x-agent-skills</code> extensions, so the enriched contract is the single artifact of record.</p>
-    <p>Export the <strong>enriched OpenAPI</strong>, an <strong>MCP server design</strong>, a registry-ready <strong>server.json</strong>, an <strong>Agent Skills bundle</strong>, and the <strong>APIs.json properties</strong> that wire it all to your provider listing. It pairs with <a href="https://contextgate.apicommons.org" target="_blank" rel="noopener">Context Gate</a> and the <a href="https://validator.apicommons.org" target="_blank" rel="noopener">Validator</a>.</p>
+    <p>Export the <strong>enriched OpenAPI</strong>, an <strong>MCP server design</strong>, a registry-ready <strong>server.json</strong>, an <strong>Agent Skills bundle</strong>, and the <strong>APIs.json properties</strong> that wire it all to your provider listing — or generate a <strong>complete, runnable MCP server</strong> in TypeScript, every tool wired to its OpenAPI operation, ready to <code>npm install &amp;&amp; npm run dev</code>. It pairs with <a href="https://contextgate.apicommons.org" target="_blank" rel="noopener">Context Gate</a> and the <a href="https://validator.apicommons.org" target="_blank" rel="noopener">Validator</a>.</p>
     <p class="muted small">Runs entirely in your browser — your API definitions never leave the page. Work is saved locally as you edit.</p>
   </div>`;
   document.body.appendChild(el);