@mcpmake/core 0.3.6 → 0.4.0

package/dist/emitter/a2a.js

@@ -0,0 +1,366 @@
+/**
+ * A2A (Agent2Agent) output (`--a2a`): wrap a generated MCP server in the published,
+ * stable A2A protocol surface so A2A-speaking clients can discover and drive it.
+ *
+ * Two artifacts are derived deterministically from the project manifest:
+ *
+ *   1. An A2A **AgentCard** (served at `/.well-known/agent.json`) — every value comes
+ *      from the manifest (server name/version, base URL, generated tool list, auth
+ *      schemes). One A2A *skill* is emitted per generated MCP tool, so an A2A client
+ *      sees the same capability surface MCP clients see via `tools/list`.
+ *
+ *   2. A JSON-RPC 2.0 **server-wrapper module** (`src/a2a.ts`) that implements the A2A
+ *      transport methods `message/send` and `tasks/get` and serves the AgentCard. It
+ *      maps an inbound A2A message to an MCP `tools/call` on the SAME generated server
+ *      (via an in-process loopback MCP client — public SDK API only, no internals).
+ *
+ * PURE: a deterministic function of the inputs, with every interpolated value safely
+ * encoded (tool descriptions/names come from the source API and are JSON.stringify'd
+ * into the generated source, so no character can break out of a string literal or the
+ * emitted JSON). No Date.now()/random — identical input yields byte-identical output.
+ *
+ * Conformance: AgentCard fields (name, description, version, url, protocolVersion,
+ * capabilities, defaultInputModes, defaultOutputModes, skills, provider) and the
+ * AgentSkill shape (id, name, description, tags) are the published A2A AgentCard
+ * surface; the JSON-RPC methods `message/send`/`tasks/get` are the stable A2A v0.3.0
+ * transport methods.
+ */
+/** Published, stable A2A protocol version this wrapper targets. */
+export const A2A_PROTOCOL_VERSION = '0.3.0';
+/** The path the AgentCard is served from (the A2A well-known discovery location). */
+export const A2A_AGENT_CARD_PATH = '/.well-known/agent.json';
+/**
+ * Build the A2A AgentCard as a plain object. Every field is derived from the manifest:
+ *   • `name`/`version`            ← serverName/serverVersion
+ *   • `url`                       ← the agent's A2A JSON-RPC endpoint (`<baseUrl>/a2a`)
+ *   • `protocolVersion`           ← the fixed {@link A2A_PROTOCOL_VERSION} constant
+ *   • `skills[]`                  ← one per generated tool (id = tool.name)
+ *   • `provider`                  ← the generator's identity (constant, not API-derived)
+ * No value is invented from outside the manifest.
+ */
+export function buildAgentCard(inputs) {
+    const toolCount = inputs.tools.length;
+    return {
+        name: inputs.serverName,
+        description: `A2A agent wrapping the ${inputs.serverName} MCP server ` +
+            `(${toolCount} tool${toolCount === 1 ? '' : 's'}).`,
+        version: inputs.serverVersion,
+        // The A2A JSON-RPC endpoint this card describes. Derived from the API base URL;
+        // operators override it via the A2A_PUBLIC_URL env var at runtime (see module).
+        url: a2aEndpointUrl(inputs.baseUrl),
+        protocolVersion: A2A_PROTOCOL_VERSION,
+        capabilities: { streaming: true },
+        defaultInputModes: ['application/json', 'text/plain'],
+        defaultOutputModes: ['application/json', 'text/plain'],
+        skills: inputs.tools.map((t) => ({
+            id: t.name,
+            name: t.title || t.name,
+            description: t.description ?? '',
+            tags: [],
+        })),
+        provider: { organization: 'mcpmake', url: 'https://github.com/starkyru/mcpmake-cli' },
+    };
+}
+/** Derive the A2A JSON-RPC endpoint URL from the API base URL (`<base>/a2a`). */
+function a2aEndpointUrl(baseUrl) {
+    const trimmed = baseUrl.replace(/\/+$/, '');
+    return `${trimmed}/a2a`;
+}
+/** The AgentCard as pretty (2-space) JSON — stable key order, deterministic. */
+export function agentCardJson(inputs) {
+    return JSON.stringify(buildAgentCard(inputs), null, 2);
+}
+/**
+ * Generate the `src/a2a.ts` module the server ships when A2A output is enabled.
+ *
+ * The AgentCard is embedded as a JSON-encoded string constant (so any character in a
+ * tool description is inert in the generated source). `registerA2a(server, registerTools)`
+ * stands up an A2A JSON-RPC listener that:
+ *   • GET  /.well-known/agent.json  → returns the AgentCard.
+ *   • POST /a2a (JSON-RPC 2.0):
+ *       - `message/send`  → extracts the tool name + arguments from the A2A Message and
+ *                           dispatches an MCP `tools/call` to the wrapped server, returning
+ *                           the result as an A2A Message (text part) / completed Task.
+ *       - `tasks/get`     → returns the stored Task for a prior `message/send` id.
+ *
+ * Tool dispatch uses an in-process loopback MCP client (`InMemoryTransport`) connected to
+ * a dedicated McpServer that `registerTools` populates — public SDK API only, so it never
+ * reaches into the primary transport's server or any SDK internals.
+ */
+export function buildA2aModule(inputs) {
+    const card = buildAgentCard(inputs);
+    // The full card, JSON-encoded into a single inert string constant.
+    const cardLiteral = JSON.stringify(JSON.stringify(card, null, 2));
+    // The set of valid skill ids (= tool names) the wrapper will accept, JSON-encoded so
+    // each name is inert; used to reject unknown tool requests before dispatch.
+    const skillIdsLiteral = JSON.stringify(card.skills.map((s) => s.id));
+    return `import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import http from 'node:http';
+import crypto from 'node:crypto';
+
+/* The AgentCard, baked at generation time and served at the A2A well-known path.
+ * Embedded as a JSON-encoded string so no source-API text can break out of source. */
+const AGENT_CARD_JSON = ${cardLiteral};
+const AGENT_CARD = JSON.parse(AGENT_CARD_JSON) as {
+  url: string;
+  skills: { id: string }[];
+  [k: string]: unknown;
+};
+const A2A_AGENT_CARD_PATH = ${JSON.stringify(A2A_AGENT_CARD_PATH)};
+const A2A_RPC_PATH = '/a2a';
+const A2A_PROTOCOL_VERSION = ${JSON.stringify(A2A_PROTOCOL_VERSION)};
+/* Valid skill ids = generated tool names. An A2A request naming anything else is
+ * rejected before dispatch (never forwarded to the MCP server). */
+const SKILL_IDS = new Set<string>(${skillIdsLiteral});
+
+type ToolResult = Awaited<ReturnType<Client['callTool']>>;
+
+/* A2A Task store: message/send may answer with a Task that the client later polls via
+ * tasks/get. Kept in-memory and bounded — A2A is a stateless wrapper over MCP tools. */
+interface A2aTask {
+  id: string;
+  contextId: string;
+  status: { state: 'completed' | 'failed'; timestamp: string };
+  artifacts: { artifactId: string; parts: { kind: 'text'; text: string }[] }[];
+}
+const A2A_MAX_TASKS = 1000;
+const tasks = new Map<string, A2aTask>();
+
+function rememberTask(task: A2aTask): void {
+  // Bound the store: drop the oldest entry once at capacity (insertion order).
+  if (tasks.size >= A2A_MAX_TASKS) {
+    const oldest = tasks.keys().next().value;
+    if (oldest !== undefined) tasks.delete(oldest);
+  }
+  tasks.set(task.id, task);
+}
+
+/* Extract a tool name + JSON arguments from an inbound A2A Message. The skill (tool)
+ * name comes from message.metadata.skillId; arguments come from a single DataPart
+ * (kind:'data') or a JSON-encoded TextPart. Returns null when the message is malformed
+ * or names an unknown skill — the caller maps that to a JSON-RPC error. */
+function extractToolCall(
+  message: unknown,
+): { name: string; args: Record<string, unknown> } | null {
+  if (!message || typeof message !== 'object') return null;
+  const meta = (message as { metadata?: unknown }).metadata;
+  const skillId =
+    meta && typeof meta === 'object'
+      ? (meta as { skillId?: unknown }).skillId
+      : undefined;
+  if (typeof skillId !== 'string' || !SKILL_IDS.has(skillId)) return null;
+
+  const parts = (message as { parts?: unknown }).parts;
+  let args: Record<string, unknown> = {};
+  if (Array.isArray(parts)) {
+    for (const part of parts) {
+      if (!part || typeof part !== 'object') continue;
+      const kind = (part as { kind?: unknown }).kind;
+      if (kind === 'data') {
+        const data = (part as { data?: unknown }).data;
+        if (data && typeof data === 'object' && !Array.isArray(data)) {
+          args = data as Record<string, unknown>;
+        }
+      } else if (kind === 'text') {
+        const text = (part as { text?: unknown }).text;
+        if (typeof text === 'string' && text.trim()) {
+          try {
+            const parsed = JSON.parse(text);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+              args = parsed as Record<string, unknown>;
+            }
+          } catch {
+            // A non-JSON text part is treated as having no structured args.
+          }
+        }
+      }
+    }
+  }
+  return { name: skillId, args };
+}
+
+/* Flatten an MCP CallToolResult's content blocks to a single text string for the A2A
+ * Message/artifact. Text blocks are concatenated; non-text blocks are JSON-encoded. */
+function resultToText(result: ToolResult): string {
+  const content = (result as { content?: unknown }).content;
+  if (!Array.isArray(content)) return '';
+  return content
+    .map((block) => {
+      if (block && typeof block === 'object' && (block as { type?: unknown }).type === 'text') {
+        return String((block as { text?: unknown }).text ?? '');
+      }
+      return JSON.stringify(block);
+    })
+    .join('\\n');
+}
+
+function sendJson(res: http.ServerResponse, status: number, body: unknown): void {
+  res.writeHead(status, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify(body));
+}
+
+function rpcResult(id: unknown, result: unknown): Record<string, unknown> {
+  return { jsonrpc: '2.0', id: id ?? null, result };
+}
+
+function rpcError(id: unknown, code: number, message: string): Record<string, unknown> {
+  return { jsonrpc: '2.0', id: id ?? null, error: { code, message } };
+}
+
+const MAX_BODY = 4 * 1024 * 1024; // 4 MB — same cap the MCP HTTP server uses.
+function readBody(req: http.IncomingMessage): Promise<Buffer | null> {
+  return new Promise((resolve) => {
+    const chunks: Buffer[] = [];
+    let total = 0;
+    let settled = false;
+    const done = (v: Buffer | null) => {
+      if (!settled) {
+        settled = true;
+        resolve(v);
+      }
+    };
+    req.on('data', (c: Buffer) => {
+      total += c.length;
+      if (total > MAX_BODY) {
+        done(null);
+        req.destroy();
+        return;
+      }
+      chunks.push(c);
+    });
+    req.on('end', () => done(Buffer.concat(chunks)));
+    req.on('error', () => done(null));
+    req.on('aborted', () => done(null));
+  });
+}
+
+/**
+ * Stand up the A2A wrapper. \`registerTools\` populates a DEDICATED McpServer (the same
+ * registrar the primary server uses), which an in-process MCP client drives — so A2A
+ * dispatch never contends with the primary transport. Returns the listening http.Server
+ * (when A2A_HTTP=true) or undefined; callers can ignore the return value.
+ */
+export async function registerA2a(
+  _server: McpServer,
+  registerTools: (s: McpServer) => void,
+): Promise<http.Server | undefined> {
+  // Dedicated MCP server + loopback client for A2A → tools/call dispatch.
+  const a2aMcpServer = new McpServer({ name: 'a2a-bridge', version: A2A_PROTOCOL_VERSION });
+  registerTools(a2aMcpServer);
+  const client = new Client({ name: 'a2a-bridge-client', version: A2A_PROTOCOL_VERSION });
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  await a2aMcpServer.connect(serverTransport);
+  await client.connect(clientTransport);
+
+  async function handleMessageSend(id: unknown, params: unknown): Promise<Record<string, unknown>> {
+    const message = (params as { message?: unknown })?.message;
+    const call = extractToolCall(message);
+    if (!call) {
+      return rpcError(id, -32602, 'Invalid A2A message: missing or unknown skillId (tool name)');
+    }
+    const result = await client.callTool({ name: call.name, arguments: call.args });
+    const text = resultToText(result);
+    const isError = (result as { isError?: unknown }).isError === true;
+    const taskId = crypto.randomUUID();
+    const contextId = crypto.randomUUID();
+    const task: A2aTask = {
+      id: taskId,
+      contextId,
+      status: {
+        state: isError ? 'failed' : 'completed',
+        // A2A Task timestamps are wall-clock; derived from the request, not baked.
+        timestamp: new Date().toISOString(),
+      },
+      artifacts: [
+        { artifactId: crypto.randomUUID(), parts: [{ kind: 'text', text }] },
+      ],
+    };
+    rememberTask(task);
+    return rpcResult(id, task);
+  }
+
+  function handleTasksGet(id: unknown, params: unknown): Record<string, unknown> {
+    const taskId = (params as { id?: unknown })?.id;
+    if (typeof taskId !== 'string') {
+      return rpcError(id, -32602, 'Invalid tasks/get params: "id" is required');
+    }
+    const task = tasks.get(taskId);
+    if (!task) return rpcError(id, -32001, 'Task not found');
+    return rpcResult(id, task);
+  }
+
+  async function handleRpc(body: unknown): Promise<Record<string, unknown>> {
+    if (!body || typeof body !== 'object' || Array.isArray(body)) {
+      return rpcError(null, -32600, 'Invalid Request');
+    }
+    const id = (body as { id?: unknown }).id;
+    const method = (body as { method?: unknown }).method;
+    const params = (body as { params?: unknown }).params;
+    switch (method) {
+      case 'message/send':
+        return handleMessageSend(id, params);
+      case 'tasks/get':
+        return handleTasksGet(id, params);
+      default:
+        return rpcError(id, -32601, 'Method not found');
+    }
+  }
+
+  // The A2A HTTP listener is opt-in (A2A_HTTP=true) so enabling --a2a never changes a
+  // stdio server's runtime footprint unless the operator wants the A2A endpoint.
+  if (process.env.A2A_HTTP !== 'true') return undefined;
+
+  const port = parseInt(process.env.A2A_PORT ?? '3001', 10);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error('Invalid A2A_PORT value, must be 1-65535');
+  }
+
+  const httpServer = http.createServer(async (req, res) => {
+    try {
+      const url = new URL(req.url ?? '/', \`http://localhost:\${port}\`);
+      const method = req.method ?? 'GET';
+
+      if (url.pathname === A2A_AGENT_CARD_PATH && method === 'GET') {
+        // The agent's own endpoint may be pinned at runtime without rebuilding.
+        const publicUrl = process.env.A2A_PUBLIC_URL;
+        const card = publicUrl ? { ...AGENT_CARD, url: publicUrl } : AGENT_CARD;
+        sendJson(res, 200, card);
+        return;
+      }
+
+      if (url.pathname === A2A_RPC_PATH && method === 'POST') {
+        const raw = await readBody(req);
+        if (raw === null) {
+          sendJson(res, 200, rpcError(null, -32600, 'Request body too large'));
+          return;
+        }
+        let parsed: unknown;
+        try {
+          parsed = JSON.parse(raw.toString('utf-8'));
+        } catch {
+          sendJson(res, 200, rpcError(null, -32700, 'Parse error'));
+          return;
+        }
+        sendJson(res, 200, await handleRpc(parsed));
+        return;
+      }
+
+      res.writeHead(404);
+      res.end('Not found');
+    } catch {
+      if (!res.headersSent) sendJson(res, 200, rpcError(null, -32603, 'Internal error'));
+    }
+  });
+
+  httpServer.listen(port, () => {
+    process.stderr.write(
+      JSON.stringify({ msg: 'A2A wrapper listening', port, card: A2A_AGENT_CARD_PATH }) + '\\n',
+    );
+  });
+  return httpServer;
+}
+`;
+}
+//# sourceMappingURL=a2a.js.map

package/dist/emitter/a2a.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"a2a.js","sourceRoot":"","sources":["../../src/emitter/a2a.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,mEAAmE;AACnE,MAAM,CAAC,MAAM,oBAAoB,GAAG,OAAO,CAAC;AAE5C,qFAAqF;AACrF,MAAM,CAAC,MAAM,mBAAmB,GAAG,yBAAyB,CAAC;AAwC7D;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,MAAqB;IAClD,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC;IACtC,OAAO;QACL,IAAI,EAAE,MAAM,CAAC,UAAU;QACvB,WAAW,EACT,0BAA0B,MAAM,CAAC,UAAU,cAAc;YACzD,IAAI,SAAS,QAAQ,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI;QACrD,OAAO,EAAE,MAAM,CAAC,aAAa;QAC7B,gFAAgF;QAChF,gFAAgF;QAChF,GAAG,EAAE,cAAc,CAAC,MAAM,CAAC,OAAO,CAAC;QACnC,eAAe,EAAE,oBAAoB;QACrC,YAAY,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE;QACjC,iBAAiB,EAAE,CAAC,kBAAkB,EAAE,YAAY,CAAC;QACrD,kBAAkB,EAAE,CAAC,kBAAkB,EAAE,YAAY,CAAC;QACtD,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAC/B,EAAE,EAAE,CAAC,CAAC,IAAI;YACV,IAAI,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,IAAI;YACvB,WAAW,EAAE,CAAC,CAAC,WAAW,IAAI,EAAE;YAChC,IAAI,EAAE,EAAE;SACT,CAAC,CAAC;QACH,QAAQ,EAAE,EAAE,YAAY,EAAE,SAAS,EAAE,GAAG,EAAE,yCAAyC,EAAE;KACtF,CAAC;AACJ,CAAC;AAED,iFAAiF;AACjF,SAAS,cAAc,CAAC,OAAe;IACrC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC5C,OAAO,GAAG,OAAO,MAAM,CAAC;AAC1B,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,aAAa,CAAC,MAAqB;IACjD,OAAO,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;AACzD,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,cAAc,CAAC,MAAqB;IAClD,MAAM,IAAI,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;IACpC,mEAAmE;IACnE,MAAM,WAAW,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAClE,qFAAqF;IACrF,4EAA4E;IAC5E,MAAM,eAAe,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAErE,OAAO;;;;;;;;0BAQiB,WAAW;;;;;;8BAMP,IAAI,CAAC,SAAS,CAAC,mBAAmB,CAAC;;+BAElC,IAAI,CAAC,SAAS,CAAC,oBAAoB,CAAC;;;oCAG/B,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwPlD,CAAC;AACF,CAAC"}

package/dist/emitter/code-writer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"code-writer.d.ts","sourceRoot":"","sources":["../../src/emitter/code-writer.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAKD,wBAAsB,cAAc,CAClC,KAAK,EAAE,QAAQ,EAAE,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAC5D,OAAO,CAAC,IAAI,CAAC,CAmEf"}
+{"version":3,"file":"code-writer.d.ts","sourceRoot":"","sources":["../../src/emitter/code-writer.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAKD,wBAAsB,cAAc,CAClC,KAAK,EAAE,QAAQ,EAAE,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAC5D,OAAO,CAAC,IAAI,CAAC,CAuFf"}

package/dist/emitter/code-writer.js

@@ -8,13 +8,30 @@ export async function writeCodeUnits(units, outputDir, options) {
     const resolvedOutputDir = resolve(outputDir);
     // Resolve + traversal-guard every unit up front so a malicious relative path
     // can never escape the output dir, and so we fail before touching the disk.
-    const planned = units.map((unit) => {
+    const resolved = units.map((unit) => {
         const absPath = resolve(outputDir, unit.filePath);
         if (!absPath.startsWith(resolvedOutputDir + '/') && absPath !== resolvedOutputDir) {
             throw new Error(`Path traversal detected: ${unit.filePath} resolves outside output directory`);
         }
         return { absPath, unit };
     });
+    // Defense-in-depth: collapse units that resolve to the SAME absolute path so
+    // the force/atomic path never stages one temp once but renames it twice
+    // (→ ENOENT on the second rename). Two site tools sharing a generated
+    // filename is the known trigger; the tool-generator now keeps them distinct,
+    // but a future collision must not crash or silently drop a file. Last writer
+    // wins, first-occurrence order is preserved, and every drop is warned once —
+    // a no-op when there are no collisions.
+    const byPath = new Map();
+    for (const entry of resolved) {
+        const existing = byPath.get(entry.absPath);
+        if (existing) {
+            logger.warn(`Duplicate output path: ${entry.unit.filePath} overwrites ${existing.unit.filePath} ` +
+                `(both resolve to the same file) — keeping the last.`);
+        }
+        byPath.set(entry.absPath, entry);
+    }
+    const planned = [...byPath.values()];
     if (options.dryRun) {
         for (const { unit } of planned) {
             logger.info(`[dry-run] Would write: ${unit.filePath}`);

package/dist/emitter/code-writer.js.map

@@ -1 +1 @@
-{"version":3,"file":"code-writer.js","sourceRoot":"","sources":["../../src/emitter/code-writer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"code-writer.js","sourceRoot":"","sources":["../../src/emitter/code-writer.ts"],"names":[],"mappings":"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"}

package/dist/emitter/composite-tools.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Composite tools (`compositeTools:` in `.mcpmake.yaml`): one MCP tool that
+ * orchestrates several EXISTING generated tools in sequence, threading data
+ * between them. Opt-in — absent config emits nothing.
+ *
+ * A composite is declared as an ordered list of steps. Each step names an
+ * existing generated tool (by its MCP tool name) and an argument map (`with`)
+ * whose values are either:
+ *   • a literal (string / number / boolean),
+ *   • `{ $input: <name> }` — a value the composite tool takes as its OWN input,
+ *   • `{ $step: [i] }`      — the whole JSON result of an earlier step i, or
+ *   • `{ $step: [i, field] }` — a top-level `field` of an earlier step i's result.
+ * The composite's `returns` (default: the last step) selects which step result
+ * is returned. The composite's inputSchema is the set of distinct `$input` names
+ * referenced across every step — each a `z.string()` for v1 (documented limit).
+ *
+ * The generated handler runs the steps IN ORDER. It invokes each step's
+ * underlying request by calling that step's existing generated tool through an
+ * in-process MCP loopback client (InMemoryTransport + Client.callTool) — the
+ * SAME public-SDK pattern `a2a.ts` uses. This reuses each tool's real request
+ * logic verbatim (method, path template, param mapping, auth, jq filtering); no
+ * HTTP is reinvented here. Each step's parsed JSON result is stored so later
+ * steps and `returns` can reference it.
+ *
+ * PURE: a deterministic function of the inputs. Every interpolated value (tool
+ * names, input names, field names, literals) is JSON.stringify'd into the
+ * generated source, so no character from the (untrusted) config can break out of
+ * a string literal. No Date.now()/random — identical input → byte-identical output.
+ */
+import type { ToolDefinition } from '../types/index.js';
+/** A literal value usable directly as a step argument. */
+export type CompositeLiteral = string | number | boolean;
+/** A reference to one of the composite tool's own inputs. */
+export interface CompositeInputRef {
+    $input: string;
+}
+/**
+ * A reference to a prior step's result. `[i]` is the whole result of step i;
+ * `[i, field]` is the top-level `field` of step i's result.
+ */
+export interface CompositeStepRef {
+    $step: [number] | [number, string];
+}
+/** A resolved value for a step argument or the composite's `returns`. */
+export type CompositeValue = CompositeLiteral | CompositeInputRef | CompositeStepRef;
+/** One step of a composite tool: invoke `tool` with the resolved `with` map. */
+export interface CompositeStepSpec {
+    /** The MCP tool name of an EXISTING generated tool to invoke. */
+    tool: string;
+    /** Argument-name → value map for this step's tool call. */
+    with?: Record<string, CompositeValue>;
+}
+/** A composite-tool declaration (one entry under `compositeTools:`). */
+export interface CompositeToolSpec {
+    name: string;
+    description?: string;
+    steps: CompositeStepSpec[];
+    /** Which step's result the composite returns. Default: the last step. */
+    returns?: CompositeStepRef;
+}
+/** Thrown when a composite-tool declaration is invalid (surfaced at build time). */
+export declare class CompositeToolError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parse + validate the raw `compositeTools` value from `.mcpmake.yaml` into typed
+ * specs. Throws a {@link CompositeToolError} (clear, build-time) on any malformed
+ * entry. Loosely-typed input (the YAML loader returns `unknown`) is checked here.
+ */
+export declare function parseCompositeToolSpecs(raw: unknown): CompositeToolSpec[];
+export interface CompositeBuildResult {
+    /** The distinct `$input` names referenced across all steps (inputSchema keys), sorted. */
+    inputNames: string[];
+}
+/**
+ * Validate a single composite spec against the set of existing tool names and
+ * derive its build result (the `$input` names that form its inputSchema). Throws
+ * a {@link CompositeToolError} on any invalid reference. Validation rules:
+ *   • every step's `tool` must be an existing generated tool name;
+ *   • a `$step: [i]` may reference only an EARLIER step (i < current step index)
+ *     and a valid step index (0 ≤ i);
+ *   • `returns` must reference a valid step index (0 ≤ i < steps.length);
+ *   • the composite name must not collide with an existing tool name.
+ */
+export declare function validateCompositeTool(spec: CompositeToolSpec, existingToolNames: ReadonlySet<string>): CompositeBuildResult;
+/**
+ * Build the `src/composite-tools.ts` module that registers every composite tool.
+ * Validates each spec against the existing tool names first (throws a
+ * {@link CompositeToolError} on any invalid reference). Returns the module
+ * source.
+ *
+ * The handler dispatches each step through an in-process MCP loopback client
+ * (the same `InMemoryTransport` + `Client.callTool` pattern as `a2a.ts`), so the
+ * step's real generated request logic runs — no HTTP is reinvented. The
+ * `registerTools` callback (passed by the server entry) populates the dedicated
+ * loopback server with the same tool surface the primary server exposes.
+ */
+export declare function buildCompositeToolsModule(specs: readonly CompositeToolSpec[], tools: readonly ToolDefinition[]): string;
+//# sourceMappingURL=composite-tools.d.ts.map

package/dist/emitter/composite-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composite-tools.d.ts","sourceRoot":"","sources":["../../src/emitter/composite-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD,0DAA0D;AAC1D,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAEzD,6DAA6D;AAC7D,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpC;AAED,yEAAyE;AACzE,MAAM,MAAM,cAAc,GAAG,gBAAgB,GAAG,iBAAiB,GAAG,gBAAgB,CAAC;AAErF,gFAAgF;AAChF,MAAM,WAAW,iBAAiB;IAChC,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CACvC;AAED,wEAAwE;AACxE,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,yEAAyE;IACzE,OAAO,CAAC,EAAE,gBAAgB,CAAC;CAC5B;AAED,oFAAoF;AACpF,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAuBD;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,OAAO,GAAG,iBAAiB,EAAE,CAMzE;AA4ED,MAAM,WAAW,oBAAoB;IACnC,0FAA0F;IAC1F,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,iBAAiB,EACvB,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAAC,GACrC,oBAAoB,CAuCtB;AAqGD;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,SAAS,iBAAiB,EAAE,EACnC,KAAK,EAAE,SAAS,cAAc,EAAE,GAC/B,MAAM,CAkIR"}