apex-code 0.0.1-alpha.8 → 0.0.4

package/dist/core/mcp/connector.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The MCP SDK lives here and nowhere else.
+ *
+ * Everything above this file talks to `McpConnection`, so the lifecycle logic, the
+ * proxy tool, and their tests never import the SDK or start a process. This module is
+ * the boundary where an external protocol becomes an internal type.
+ */
+import type { CredentialStore } from "@earendil-works/pi-ai";
+import type { FetchLike } from "./oauth/discover.ts";
+import type { McpConnection, McpConnector, McpServerConfig } from "./types.ts";
+/**
+ * Authorization for one HTTP connection, in precedence order: a static configured
+ * header, then a named bearer env var, then the credential store's OAuth token.
+ * Later wins, because each later source is the more deliberately configured one.
+ */
+export declare function resolveAuthorizationHeaders(server: McpServerConfig, oauthAuthorization?: string): Record<string, string>;
+export declare function connectMcpServer(server: McpServerConfig, oauthAuthorization?: string): Promise<McpConnection>;
+export interface SessionMcpConnectorOptions {
+    /**
+     * The session's credential store: `AuthStorage` on the host, `SandboxAuthStorage`
+     * in a sandboxed child (reads from the projection, writes through the supervisor
+     * channel). OAuth-configured servers without one fail closed.
+     */
+    credentials?: CredentialStore;
+    now?: () => number;
+    fetch?: FetchLike;
+}
+/**
+ * The session connector: resolves OAuth tokens for servers configured with
+ * `auth: "oauth"`, and behaves exactly like `connectMcpServer` for everything else.
+ * A missing authorization throws before the transport is constructed, so no OAuth
+ * endpoint is ever contacted from a tool call path (spec 2026-09-01-mcp-oauth).
+ */
+export declare function createSessionMcpConnector(options?: SessionMcpConnectorOptions): McpConnector;
+//# sourceMappingURL=connector.d.ts.map

package/dist/core/mcp/connector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector.d.ts","sourceRoot":"","sources":["../../../src/core/mcp/connector.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAI7D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,KAAK,EAA6B,aAAa,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE1G;;;;GAIG;AACH,wBAAgB,2BAA2B,CAC1C,MAAM,EAAE,eAAe,EACvB,kBAAkB,CAAC,EAAE,MAAM,GACzB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOxB;AAwCD,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,eAAe,EAAE,kBAAkB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAqBnH;AAED,MAAM,WAAW,0BAA0B;IAC1C;;;;OAIG;IACH,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,SAAS,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,GAAE,0BAA+B,GAAG,YAAY,CAchG","sourcesContent":["/**\n * The MCP SDK lives here and nowhere else.\n *\n * Everything above this file talks to `McpConnection`, so the lifecycle logic, the\n * proxy tool, and their tests never import the SDK or start a process. This module is\n * the boundary where an external protocol becomes an internal type.\n */\n\nimport type { CredentialStore } from \"@earendil-works/pi-ai\";\nimport { Client, StreamableHTTPClientTransport } from \"@modelcontextprotocol/client\";\nimport { StdioClientTransport } from \"@modelcontextprotocol/client/stdio\";\nimport { APP_NAME, VERSION } from \"../../config.ts\";\nimport type { FetchLike } from \"./oauth/discover.ts\";\nimport { authRequired, ensureFreshServerToken } from \"./oauth/mcp-token.ts\";\nimport type { CachedTool, McpCallResult, McpConnection, McpConnector, McpServerConfig } from \"./types.ts\";\n\n/**\n * Authorization for one HTTP connection, in precedence order: a static configured\n * header, then a named bearer env var, then the credential store's OAuth token.\n * Later wins, because each later source is the more deliberately configured one.\n */\nexport function resolveAuthorizationHeaders(\n\tserver: McpServerConfig,\n\toauthAuthorization?: string,\n): Record<string, string> {\n\tif (server.transport.kind !== \"http\") return {};\n\tconst headers = { ...server.transport.headers };\n\tconst token = server.transport.bearerTokenEnv ? process.env[server.transport.bearerTokenEnv] : undefined;\n\tif (token) headers.Authorization = `Bearer ${token}`;\n\tif (oauthAuthorization) headers.Authorization = oauthAuthorization;\n\treturn headers;\n}\n\nfunction createTransport(server: McpServerConfig, oauthAuthorization?: string) {\n\tif (server.transport.kind === \"stdio\") {\n\t\treturn new StdioClientTransport({\n\t\t\tcommand: server.transport.command,\n\t\t\targs: server.transport.args,\n\t\t\tenv: { ...process.env, ...server.transport.env } as Record<string, string>,\n\t\t\tcwd: server.transport.cwd,\n\t\t});\n\t}\n\n\treturn new StreamableHTTPClientTransport(new URL(server.transport.url), {\n\t\trequestInit: { headers: resolveAuthorizationHeaders(server, oauthAuthorization) },\n\t});\n}\n\n/**\n * Server content arrives as a heterogeneous array. Only text is carried forward; an\n * image or an embedded resource is named rather than dropped silently, so a caller\n * can tell the difference between \"returned nothing\" and \"returned something we do\n * not render yet\".\n */\nfunction toCallResult(raw: unknown): McpCallResult {\n\tconst result = raw as { content?: unknown; isError?: unknown };\n\tconst parts = Array.isArray(result?.content) ? result.content : [];\n\tconst content = parts.map((part) => {\n\t\tconst item = part as { type?: unknown; text?: unknown };\n\t\tif (item?.type === \"text\" && typeof item.text === \"string\") {\n\t\t\treturn { type: \"text\" as const, text: item.text };\n\t\t}\n\t\treturn { type: \"text\" as const, text: `[${String(item?.type ?? \"unknown\")} content omitted]` };\n\t});\n\n\treturn {\n\t\tcontent: content.length > 0 ? content : [{ type: \"text\" as const, text: \"(no content)\" }],\n\t\tisError: result?.isError === true,\n\t};\n}\n\nexport async function connectMcpServer(server: McpServerConfig, oauthAuthorization?: string): Promise<McpConnection> {\n\tconst client = new Client({ name: APP_NAME, version: VERSION });\n\tawait client.connect(createTransport(server, oauthAuthorization));\n\n\treturn {\n\t\tasync listTools(): Promise<CachedTool[]> {\n\t\t\tconst { tools } = await client.listTools();\n\t\t\treturn tools.map((tool) => ({\n\t\t\t\tserver: server.name,\n\t\t\t\tname: tool.name,\n\t\t\t\tdescription: tool.description ?? \"\",\n\t\t\t\tinputSchema: tool.inputSchema,\n\t\t\t}));\n\t\t},\n\t\tasync callTool(name: string, args: unknown): Promise<McpCallResult> {\n\t\t\treturn toCallResult(await client.callTool({ name, arguments: (args ?? {}) as Record<string, unknown> }));\n\t\t},\n\t\tasync close(): Promise<void> {\n\t\t\tawait client.close();\n\t\t},\n\t};\n}\n\nexport interface SessionMcpConnectorOptions {\n\t/**\n\t * The session's credential store: `AuthStorage` on the host, `SandboxAuthStorage`\n\t * in a sandboxed child (reads from the projection, writes through the supervisor\n\t * channel). OAuth-configured servers without one fail closed.\n\t */\n\tcredentials?: CredentialStore;\n\tnow?: () => number;\n\tfetch?: FetchLike;\n}\n\n/**\n * The session connector: resolves OAuth tokens for servers configured with\n * `auth: \"oauth\"`, and behaves exactly like `connectMcpServer` for everything else.\n * A missing authorization throws before the transport is constructed, so no OAuth\n * endpoint is ever contacted from a tool call path (spec 2026-09-01-mcp-oauth).\n */\nexport function createSessionMcpConnector(options: SessionMcpConnectorOptions = {}): McpConnector {\n\treturn async (server) => {\n\t\tif (server.transport.kind === \"http\" && server.auth === \"oauth\") {\n\t\t\tif (!options.credentials) throw authRequired(server.name);\n\t\t\tconst accessToken = await ensureFreshServerToken({\n\t\t\t\tserver,\n\t\t\t\tcredentials: options.credentials,\n\t\t\t\tnow: options.now,\n\t\t\t\tfetch: options.fetch,\n\t\t\t});\n\t\t\treturn connectMcpServer(server, `Bearer ${accessToken}`);\n\t\t}\n\t\treturn connectMcpServer(server);\n\t};\n}\n"]}

package/dist/core/mcp/connector.js

@@ -0,0 +1,105 @@
+/**
+ * The MCP SDK lives here and nowhere else.
+ *
+ * Everything above this file talks to `McpConnection`, so the lifecycle logic, the
+ * proxy tool, and their tests never import the SDK or start a process. This module is
+ * the boundary where an external protocol becomes an internal type.
+ */
+import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
+import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
+import { APP_NAME, VERSION } from "../../config.js";
+import { authRequired, ensureFreshServerToken } from "./oauth/mcp-token.js";
+/**
+ * Authorization for one HTTP connection, in precedence order: a static configured
+ * header, then a named bearer env var, then the credential store's OAuth token.
+ * Later wins, because each later source is the more deliberately configured one.
+ */
+export function resolveAuthorizationHeaders(server, oauthAuthorization) {
+    if (server.transport.kind !== "http")
+        return {};
+    const headers = { ...server.transport.headers };
+    const token = server.transport.bearerTokenEnv ? process.env[server.transport.bearerTokenEnv] : undefined;
+    if (token)
+        headers.Authorization = `Bearer ${token}`;
+    if (oauthAuthorization)
+        headers.Authorization = oauthAuthorization;
+    return headers;
+}
+function createTransport(server, oauthAuthorization) {
+    if (server.transport.kind === "stdio") {
+        return new StdioClientTransport({
+            command: server.transport.command,
+            args: server.transport.args,
+            env: { ...process.env, ...server.transport.env },
+            cwd: server.transport.cwd,
+        });
+    }
+    return new StreamableHTTPClientTransport(new URL(server.transport.url), {
+        requestInit: { headers: resolveAuthorizationHeaders(server, oauthAuthorization) },
+    });
+}
+/**
+ * Server content arrives as a heterogeneous array. Only text is carried forward; an
+ * image or an embedded resource is named rather than dropped silently, so a caller
+ * can tell the difference between "returned nothing" and "returned something we do
+ * not render yet".
+ */
+function toCallResult(raw) {
+    const result = raw;
+    const parts = Array.isArray(result?.content) ? result.content : [];
+    const content = parts.map((part) => {
+        const item = part;
+        if (item?.type === "text" && typeof item.text === "string") {
+            return { type: "text", text: item.text };
+        }
+        return { type: "text", text: `[${String(item?.type ?? "unknown")} content omitted]` };
+    });
+    return {
+        content: content.length > 0 ? content : [{ type: "text", text: "(no content)" }],
+        isError: result?.isError === true,
+    };
+}
+export async function connectMcpServer(server, oauthAuthorization) {
+    const client = new Client({ name: APP_NAME, version: VERSION });
+    await client.connect(createTransport(server, oauthAuthorization));
+    return {
+        async listTools() {
+            const { tools } = await client.listTools();
+            return tools.map((tool) => ({
+                server: server.name,
+                name: tool.name,
+                description: tool.description ?? "",
+                inputSchema: tool.inputSchema,
+            }));
+        },
+        async callTool(name, args) {
+            return toCallResult(await client.callTool({ name, arguments: (args ?? {}) }));
+        },
+        async close() {
+            await client.close();
+        },
+    };
+}
+/**
+ * The session connector: resolves OAuth tokens for servers configured with
+ * `auth: "oauth"`, and behaves exactly like `connectMcpServer` for everything else.
+ * A missing authorization throws before the transport is constructed, so no OAuth
+ * endpoint is ever contacted from a tool call path (spec 2026-09-01-mcp-oauth).
+ */
+export function createSessionMcpConnector(options = {}) {
+    return async (server) => {
+        if (server.transport.kind === "http" && server.auth === "oauth") {
+            if (!options.credentials)
+                throw authRequired(server.name);
+            const accessToken = await ensureFreshServerToken({
+                server,
+                credentials: options.credentials,
+                now: options.now,
+                fetch: options.fetch,
+            });
+            return connectMcpServer(server, `Bearer ${accessToken}`);
+        }
+        return connectMcpServer(server);
+    };
+}
+//# sourceMappingURL=connector.js.map

package/dist/core/mcp/connector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector.js","sourceRoot":"","sources":["../../../src/core/mcp/connector.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The MCP SDK lives here and nowhere else.\n *\n * Everything above this file talks to `McpConnection`, so the lifecycle logic, the\n * proxy tool, and their tests never import the SDK or start a process. This module is\n * the boundary where an external protocol becomes an internal type.\n */\n\nimport type { CredentialStore } from \"@earendil-works/pi-ai\";\nimport { Client, StreamableHTTPClientTransport } from \"@modelcontextprotocol/client\";\nimport { StdioClientTransport } from \"@modelcontextprotocol/client/stdio\";\nimport { APP_NAME, VERSION } from \"../../config.ts\";\nimport type { FetchLike } from \"./oauth/discover.ts\";\nimport { authRequired, ensureFreshServerToken } from \"./oauth/mcp-token.ts\";\nimport type { CachedTool, McpCallResult, McpConnection, McpConnector, McpServerConfig } from \"./types.ts\";\n\n/**\n * Authorization for one HTTP connection, in precedence order: a static configured\n * header, then a named bearer env var, then the credential store's OAuth token.\n * Later wins, because each later source is the more deliberately configured one.\n */\nexport function resolveAuthorizationHeaders(\n\tserver: McpServerConfig,\n\toauthAuthorization?: string,\n): Record<string, string> {\n\tif (server.transport.kind !== \"http\") return {};\n\tconst headers = { ...server.transport.headers };\n\tconst token = server.transport.bearerTokenEnv ? process.env[server.transport.bearerTokenEnv] : undefined;\n\tif (token) headers.Authorization = `Bearer ${token}`;\n\tif (oauthAuthorization) headers.Authorization = oauthAuthorization;\n\treturn headers;\n}\n\nfunction createTransport(server: McpServerConfig, oauthAuthorization?: string) {\n\tif (server.transport.kind === \"stdio\") {\n\t\treturn new StdioClientTransport({\n\t\t\tcommand: server.transport.command,\n\t\t\targs: server.transport.args,\n\t\t\tenv: { ...process.env, ...server.transport.env } as Record<string, string>,\n\t\t\tcwd: server.transport.cwd,\n\t\t});\n\t}\n\n\treturn new StreamableHTTPClientTransport(new URL(server.transport.url), {\n\t\trequestInit: { headers: resolveAuthorizationHeaders(server, oauthAuthorization) },\n\t});\n}\n\n/**\n * Server content arrives as a heterogeneous array. Only text is carried forward; an\n * image or an embedded resource is named rather than dropped silently, so a caller\n * can tell the difference between \"returned nothing\" and \"returned something we do\n * not render yet\".\n */\nfunction toCallResult(raw: unknown): McpCallResult {\n\tconst result = raw as { content?: unknown; isError?: unknown };\n\tconst parts = Array.isArray(result?.content) ? result.content : [];\n\tconst content = parts.map((part) => {\n\t\tconst item = part as { type?: unknown; text?: unknown };\n\t\tif (item?.type === \"text\" && typeof item.text === \"string\") {\n\t\t\treturn { type: \"text\" as const, text: item.text };\n\t\t}\n\t\treturn { type: \"text\" as const, text: `[${String(item?.type ?? \"unknown\")} content omitted]` };\n\t});\n\n\treturn {\n\t\tcontent: content.length > 0 ? content : [{ type: \"text\" as const, text: \"(no content)\" }],\n\t\tisError: result?.isError === true,\n\t};\n}\n\nexport async function connectMcpServer(server: McpServerConfig, oauthAuthorization?: string): Promise<McpConnection> {\n\tconst client = new Client({ name: APP_NAME, version: VERSION });\n\tawait client.connect(createTransport(server, oauthAuthorization));\n\n\treturn {\n\t\tasync listTools(): Promise<CachedTool[]> {\n\t\t\tconst { tools } = await client.listTools();\n\t\t\treturn tools.map((tool) => ({\n\t\t\t\tserver: server.name,\n\t\t\t\tname: tool.name,\n\t\t\t\tdescription: tool.description ?? \"\",\n\t\t\t\tinputSchema: tool.inputSchema,\n\t\t\t}));\n\t\t},\n\t\tasync callTool(name: string, args: unknown): Promise<McpCallResult> {\n\t\t\treturn toCallResult(await client.callTool({ name, arguments: (args ?? {}) as Record<string, unknown> }));\n\t\t},\n\t\tasync close(): Promise<void> {\n\t\t\tawait client.close();\n\t\t},\n\t};\n}\n\nexport interface SessionMcpConnectorOptions {\n\t/**\n\t * The session's credential store: `AuthStorage` on the host, `SandboxAuthStorage`\n\t * in a sandboxed child (reads from the projection, writes through the supervisor\n\t * channel). OAuth-configured servers without one fail closed.\n\t */\n\tcredentials?: CredentialStore;\n\tnow?: () => number;\n\tfetch?: FetchLike;\n}\n\n/**\n * The session connector: resolves OAuth tokens for servers configured with\n * `auth: \"oauth\"`, and behaves exactly like `connectMcpServer` for everything else.\n * A missing authorization throws before the transport is constructed, so no OAuth\n * endpoint is ever contacted from a tool call path (spec 2026-09-01-mcp-oauth).\n */\nexport function createSessionMcpConnector(options: SessionMcpConnectorOptions = {}): McpConnector {\n\treturn async (server) => {\n\t\tif (server.transport.kind === \"http\" && server.auth === \"oauth\") {\n\t\t\tif (!options.credentials) throw authRequired(server.name);\n\t\t\tconst accessToken = await ensureFreshServerToken({\n\t\t\t\tserver,\n\t\t\t\tcredentials: options.credentials,\n\t\t\t\tnow: options.now,\n\t\t\t\tfetch: options.fetch,\n\t\t\t});\n\t\t\treturn connectMcpServer(server, `Bearer ${accessToken}`);\n\t\t}\n\t\treturn connectMcpServer(server);\n\t};\n}\n"]}

package/dist/core/mcp/contract.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The tool contract for the `mcp` proxy tool (ADR 0010).
+ *
+ * This module is the reason MCP is built into Apex Code rather than adopted as an
+ * extension. A tool registered from outside the repo cannot supply a contract, so it
+ * resolves `UNCLASSIFIED`: every capability, `ask` by default, and rule matching by
+ * exact serialized arguments. Under that fallback a second call with different
+ * arguments prompts again and no result is ever evictable.
+ *
+ * The grammar is owned here and nowhere else. The permission engine resolves
+ * precedence between rules and never learns what one means.
+ */
+import type { ToolContract } from "../tools/contract.ts";
+import type { McpToolDetails, mcpToolSchema } from "./schema.ts";
+import type { McpServerConfig } from "./types.ts";
+/** Rule covering the metadata actions, which read the local cache and reach no server. */
+export declare const METADATA_RULE = "Mcp(metadata)";
+export declare function createMcpToolContract(servers: ReadonlyMap<string, McpServerConfig>): ToolContract<typeof mcpToolSchema, McpToolDetails>;
+//# sourceMappingURL=contract.d.ts.map

package/dist/core/mcp/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../../src/core/mcp/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAc,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAErE,OAAO,KAAK,EAAE,cAAc,EAAiB,aAAa,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,0FAA0F;AAC1F,eAAO,MAAM,aAAa,kBAAkB,CAAC;AA8D7C,wBAAgB,qBAAqB,CACpC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,GAC3C,YAAY,CAAC,OAAO,aAAa,EAAE,cAAc,CAAC,CAYpD","sourcesContent":["/**\n * The tool contract for the `mcp` proxy tool (ADR 0010).\n *\n * This module is the reason MCP is built into Apex Code rather than adopted as an\n * extension. A tool registered from outside the repo cannot supply a contract, so it\n * resolves `UNCLASSIFIED`: every capability, `ask` by default, and rule matching by\n * exact serialized arguments. Under that fallback a second call with different\n * arguments prompts again and no result is ever evictable.\n *\n * The grammar is owned here and nowhere else. The permission engine resolves\n * precedence between rules and never learns what one means.\n */\n\nimport type { Capability, ToolContract } from \"../tools/contract.ts\";\nimport { ALL_CAPABILITIES } from \"../tools/contract.ts\";\nimport type { McpToolDetails, McpToolParams, mcpToolSchema } from \"./schema.ts\";\nimport type { McpServerConfig } from \"./types.ts\";\n\n/** Rule covering the metadata actions, which read the local cache and reach no server. */\nexport const METADATA_RULE = \"Mcp(metadata)\";\n\nconst RULE_PATTERN = /^Mcp\\(([^():*\\s]+):([^():\\s]+)\\)$/;\n\nfunction isCall(params: McpToolParams): params is McpToolParams & { tool: string } {\n\treturn typeof params.tool === \"string\" && params.tool.length > 0;\n}\n\n/** `<server>:<tool>`, the form the model calls and the form a rule names. */\nfunction splitQualifiedName(qualified: string): { server: string; tool: string } | undefined {\n\tconst index = qualified.indexOf(\":\");\n\tif (index <= 0 || index === qualified.length - 1) return undefined;\n\treturn { server: qualified.slice(0, index), tool: qualified.slice(index + 1) };\n}\n\nfunction matches(ruleContent: string, params: McpToolParams): boolean {\n\tif (ruleContent === METADATA_RULE) return !isCall(params);\n\tif (!isCall(params)) return false;\n\n\tconst rule = RULE_PATTERN.exec(ruleContent);\n\tif (!rule) return false;\n\tconst [, ruleServer, ruleTool] = rule;\n\n\tconst target = splitQualifiedName(params.tool);\n\tif (!target) return false;\n\n\tif (ruleServer !== target.server) return false;\n\treturn ruleTool === \"*\" || ruleTool === target.tool;\n}\n\nfunction ruleForCall(params: McpToolParams): string | null {\n\tif (!isCall(params)) return METADATA_RULE;\n\tconst target = splitQualifiedName(params.tool);\n\treturn target ? `Mcp(${target.server}:${target.tool})` : null;\n}\n\nfunction describe(ruleContent: string): string {\n\tif (ruleContent === METADATA_RULE) return \"Searching and describing MCP tools (no server is contacted)\";\n\n\tconst rule = RULE_PATTERN.exec(ruleContent);\n\tif (!rule) return `Unrecognized MCP rule: ${ruleContent}`;\n\tconst [, server, tool] = rule;\n\treturn tool === \"*\"\n\t\t? `Calling any tool on the \"${server}\" MCP server`\n\t\t: `Calling \"${tool}\" on the \"${server}\" MCP server`;\n}\n\n/**\n * One proxy tool carries one capability set, and that set feeds the delegation\n * ceiling (ADR 0008) and mode resolution. The union across configured servers is the\n * only sound answer: narrower would understate what a call can do, and a fixed full\n * set would ignore what a user took the trouble to declare.\n */\nfunction unionCapabilities(servers: Iterable<McpServerConfig>): ReadonlySet<Capability> {\n\tconst union = new Set<Capability>();\n\tfor (const server of servers) {\n\t\tfor (const capability of server.capabilities) union.add(capability);\n\t\tif (union.size === ALL_CAPABILITIES.size) return ALL_CAPABILITIES;\n\t}\n\treturn union;\n}\n\nexport function createMcpToolContract(\n\tservers: ReadonlyMap<string, McpServerConfig>,\n): ToolContract<typeof mcpToolSchema, McpToolDetails> {\n\treturn {\n\t\tcapabilities: unionCapabilities(servers.values()),\n\t\tpermission: {\n\t\t\tdefaultBehavior: \"ask\",\n\t\t\tmatches,\n\t\t\tdescribe,\n\t\t\truleForCall,\n\t\t},\n\t\tcontext: { resultRecoverable: false, deferSchema: true },\n\t\tevidence: { emits: new Set(), capture: () => [] },\n\t};\n}\n"]}

package/dist/core/mcp/contract.js

@@ -0,0 +1,89 @@
+/**
+ * The tool contract for the `mcp` proxy tool (ADR 0010).
+ *
+ * This module is the reason MCP is built into Apex Code rather than adopted as an
+ * extension. A tool registered from outside the repo cannot supply a contract, so it
+ * resolves `UNCLASSIFIED`: every capability, `ask` by default, and rule matching by
+ * exact serialized arguments. Under that fallback a second call with different
+ * arguments prompts again and no result is ever evictable.
+ *
+ * The grammar is owned here and nowhere else. The permission engine resolves
+ * precedence between rules and never learns what one means.
+ */
+import { ALL_CAPABILITIES } from "../tools/contract.js";
+/** Rule covering the metadata actions, which read the local cache and reach no server. */
+export const METADATA_RULE = "Mcp(metadata)";
+const RULE_PATTERN = /^Mcp\(([^():*\s]+):([^():\s]+)\)$/;
+function isCall(params) {
+    return typeof params.tool === "string" && params.tool.length > 0;
+}
+/** `<server>:<tool>`, the form the model calls and the form a rule names. */
+function splitQualifiedName(qualified) {
+    const index = qualified.indexOf(":");
+    if (index <= 0 || index === qualified.length - 1)
+        return undefined;
+    return { server: qualified.slice(0, index), tool: qualified.slice(index + 1) };
+}
+function matches(ruleContent, params) {
+    if (ruleContent === METADATA_RULE)
+        return !isCall(params);
+    if (!isCall(params))
+        return false;
+    const rule = RULE_PATTERN.exec(ruleContent);
+    if (!rule)
+        return false;
+    const [, ruleServer, ruleTool] = rule;
+    const target = splitQualifiedName(params.tool);
+    if (!target)
+        return false;
+    if (ruleServer !== target.server)
+        return false;
+    return ruleTool === "*" || ruleTool === target.tool;
+}
+function ruleForCall(params) {
+    if (!isCall(params))
+        return METADATA_RULE;
+    const target = splitQualifiedName(params.tool);
+    return target ? `Mcp(${target.server}:${target.tool})` : null;
+}
+function describe(ruleContent) {
+    if (ruleContent === METADATA_RULE)
+        return "Searching and describing MCP tools (no server is contacted)";
+    const rule = RULE_PATTERN.exec(ruleContent);
+    if (!rule)
+        return `Unrecognized MCP rule: ${ruleContent}`;
+    const [, server, tool] = rule;
+    return tool === "*"
+        ? `Calling any tool on the "${server}" MCP server`
+        : `Calling "${tool}" on the "${server}" MCP server`;
+}
+/**
+ * One proxy tool carries one capability set, and that set feeds the delegation
+ * ceiling (ADR 0008) and mode resolution. The union across configured servers is the
+ * only sound answer: narrower would understate what a call can do, and a fixed full
+ * set would ignore what a user took the trouble to declare.
+ */
+function unionCapabilities(servers) {
+    const union = new Set();
+    for (const server of servers) {
+        for (const capability of server.capabilities)
+            union.add(capability);
+        if (union.size === ALL_CAPABILITIES.size)
+            return ALL_CAPABILITIES;
+    }
+    return union;
+}
+export function createMcpToolContract(servers) {
+    return {
+        capabilities: unionCapabilities(servers.values()),
+        permission: {
+            defaultBehavior: "ask",
+            matches,
+            describe,
+            ruleForCall,
+        },
+        context: { resultRecoverable: false, deferSchema: true },
+        evidence: { emits: new Set(), capture: () => [] },
+    };
+}
+//# sourceMappingURL=contract.js.map

package/dist/core/mcp/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../../src/core/mcp/contract.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The tool contract for the `mcp` proxy tool (ADR 0010).\n *\n * This module is the reason MCP is built into Apex Code rather than adopted as an\n * extension. A tool registered from outside the repo cannot supply a contract, so it\n * resolves `UNCLASSIFIED`: every capability, `ask` by default, and rule matching by\n * exact serialized arguments. Under that fallback a second call with different\n * arguments prompts again and no result is ever evictable.\n *\n * The grammar is owned here and nowhere else. The permission engine resolves\n * precedence between rules and never learns what one means.\n */\n\nimport type { Capability, ToolContract } from \"../tools/contract.ts\";\nimport { ALL_CAPABILITIES } from \"../tools/contract.ts\";\nimport type { McpToolDetails, McpToolParams, mcpToolSchema } from \"./schema.ts\";\nimport type { McpServerConfig } from \"./types.ts\";\n\n/** Rule covering the metadata actions, which read the local cache and reach no server. */\nexport const METADATA_RULE = \"Mcp(metadata)\";\n\nconst RULE_PATTERN = /^Mcp\\(([^():*\\s]+):([^():\\s]+)\\)$/;\n\nfunction isCall(params: McpToolParams): params is McpToolParams & { tool: string } {\n\treturn typeof params.tool === \"string\" && params.tool.length > 0;\n}\n\n/** `<server>:<tool>`, the form the model calls and the form a rule names. */\nfunction splitQualifiedName(qualified: string): { server: string; tool: string } | undefined {\n\tconst index = qualified.indexOf(\":\");\n\tif (index <= 0 || index === qualified.length - 1) return undefined;\n\treturn { server: qualified.slice(0, index), tool: qualified.slice(index + 1) };\n}\n\nfunction matches(ruleContent: string, params: McpToolParams): boolean {\n\tif (ruleContent === METADATA_RULE) return !isCall(params);\n\tif (!isCall(params)) return false;\n\n\tconst rule = RULE_PATTERN.exec(ruleContent);\n\tif (!rule) return false;\n\tconst [, ruleServer, ruleTool] = rule;\n\n\tconst target = splitQualifiedName(params.tool);\n\tif (!target) return false;\n\n\tif (ruleServer !== target.server) return false;\n\treturn ruleTool === \"*\" || ruleTool === target.tool;\n}\n\nfunction ruleForCall(params: McpToolParams): string | null {\n\tif (!isCall(params)) return METADATA_RULE;\n\tconst target = splitQualifiedName(params.tool);\n\treturn target ? `Mcp(${target.server}:${target.tool})` : null;\n}\n\nfunction describe(ruleContent: string): string {\n\tif (ruleContent === METADATA_RULE) return \"Searching and describing MCP tools (no server is contacted)\";\n\n\tconst rule = RULE_PATTERN.exec(ruleContent);\n\tif (!rule) return `Unrecognized MCP rule: ${ruleContent}`;\n\tconst [, server, tool] = rule;\n\treturn tool === \"*\"\n\t\t? `Calling any tool on the \"${server}\" MCP server`\n\t\t: `Calling \"${tool}\" on the \"${server}\" MCP server`;\n}\n\n/**\n * One proxy tool carries one capability set, and that set feeds the delegation\n * ceiling (ADR 0008) and mode resolution. The union across configured servers is the\n * only sound answer: narrower would understate what a call can do, and a fixed full\n * set would ignore what a user took the trouble to declare.\n */\nfunction unionCapabilities(servers: Iterable<McpServerConfig>): ReadonlySet<Capability> {\n\tconst union = new Set<Capability>();\n\tfor (const server of servers) {\n\t\tfor (const capability of server.capabilities) union.add(capability);\n\t\tif (union.size === ALL_CAPABILITIES.size) return ALL_CAPABILITIES;\n\t}\n\treturn union;\n}\n\nexport function createMcpToolContract(\n\tservers: ReadonlyMap<string, McpServerConfig>,\n): ToolContract<typeof mcpToolSchema, McpToolDetails> {\n\treturn {\n\t\tcapabilities: unionCapabilities(servers.values()),\n\t\tpermission: {\n\t\t\tdefaultBehavior: \"ask\",\n\t\t\tmatches,\n\t\t\tdescribe,\n\t\t\truleForCall,\n\t\t},\n\t\tcontext: { resultRecoverable: false, deferSchema: true },\n\t\tevidence: { emits: new Set(), capture: () => [] },\n\t};\n}\n"]}

package/dist/core/mcp/mcp-tool.d.ts

@@ -0,0 +1,32 @@
+/**
+ * One tool for every MCP server, instead of one tool per server tool.
+ *
+ * Registering each server tool individually costs 150-300 prompt tokens apiece, and
+ * two ordinary servers would exceed the whole static-prefix budget before a
+ * conversation starts. The proxy costs one announced name and this description,
+ * because its schema defers.
+ *
+ * `search` and `describe` read the disk cache and reach no server. Only a `tool` call
+ * connects, which is what makes discovery free and is why the two have separate
+ * permission rules (ADR 0025).
+ */
+import type { ApexToolDefinition } from "../tools/contract.ts";
+import type { McpMetadataCache } from "./metadata-cache.ts";
+import { type McpToolDetails, mcpToolSchema } from "./schema.ts";
+import type { McpServerManager } from "./server-manager.ts";
+import type { McpServerConfig } from "./types.ts";
+export declare const MCP_TOOL_NAME = "mcp";
+export interface McpToolOptions {
+    servers: ReadonlyMap<string, McpServerConfig>;
+    cache: McpMetadataCache;
+    manager: McpServerManager;
+}
+export declare function createMcpToolDefinition(options: McpToolOptions): ApexToolDefinition<typeof mcpToolSchema, McpToolDetails>;
+export declare function createMcpTool(options: McpToolOptions): import("apex-code-agent-core").AgentTool<import("typebox").TObject<{
+    search: import("typebox").TOptional<import("typebox").TString>;
+    server: import("typebox").TOptional<import("typebox").TString>;
+    describe: import("typebox").TOptional<import("typebox").TString>;
+    tool: import("typebox").TOptional<import("typebox").TString>;
+    args: import("typebox").TOptional<import("typebox").TUnknown>;
+}>, McpToolDetails>;
+//# sourceMappingURL=mcp-tool.d.ts.map

package/dist/core/mcp/mcp-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-tool.d.ts","sourceRoot":"","sources":["../../../src/core/mcp/mcp-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAG/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,OAAO,EAAE,KAAK,cAAc,EAAsB,aAAa,EAAE,MAAM,aAAa,CAAC;AACrF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EAAc,eAAe,EAAE,MAAM,YAAY,CAAC;AAE9D,eAAO,MAAM,aAAa,QAAQ,CAAC;AAwCnC,MAAM,WAAW,cAAc;IAC9B,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC9C,KAAK,EAAE,gBAAgB,CAAC;IACxB,OAAO,EAAE,gBAAgB,CAAC;CAC1B;AAED,wBAAgB,uBAAuB,CACtC,OAAO,EAAE,cAAc,GACrB,kBAAkB,CAAC,OAAO,aAAa,EAAE,cAAc,CAAC,CA0I1D;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,cAAc;;;;;;oBAEpD","sourcesContent":["/**\n * One tool for every MCP server, instead of one tool per server tool.\n *\n * Registering each server tool individually costs 150-300 prompt tokens apiece, and\n * two ordinary servers would exceed the whole static-prefix budget before a\n * conversation starts. The proxy costs one announced name and this description,\n * because its schema defers.\n *\n * `search` and `describe` read the disk cache and reach no server. Only a `tool` call\n * connects, which is what makes discovery free and is why the two have separate\n * permission rules (ADR 0025).\n */\n\nimport type { AgentToolResult } from \"apex-code-agent-core\";\nimport type { ApexToolDefinition } from \"../tools/contract.ts\";\nimport { wrapToolDefinition } from \"../tools/tool-definition-wrapper.ts\";\nimport { createMcpToolContract } from \"./contract.ts\";\nimport type { McpMetadataCache } from \"./metadata-cache.ts\";\nimport { McpOAuthRefreshError, McpOAuthRequiredError } from \"./oauth/mcp-token.ts\";\nimport { type McpToolDetails, type McpToolParams, mcpToolSchema } from \"./schema.ts\";\nimport type { McpServerManager } from \"./server-manager.ts\";\nimport type { CachedTool, McpServerConfig } from \"./types.ts\";\n\nexport const MCP_TOOL_NAME = \"mcp\";\n\nconst MAX_RESULTS = 25;\n\nconst DESCRIPTION =\n\t\"Use tools provided by configured MCP servers. \" +\n\t'Search with {\"search\":\"keyword\"}, list one server with {\"server\":\"name\"}, ' +\n\t'see a tool\\'s full schema with {\"describe\":\"server:tool\"}, ' +\n\t'and call one with {\"tool\":\"server:tool\",\"args\":{...}}. ' +\n\t\"Search and describe read a local cache and never start a server, so discovery is free. \" +\n\t\"Always describe a tool before calling it for the first time.\";\n\nfunction text(body: string): AgentToolResult<McpToolDetails>[\"content\"] {\n\treturn [{ type: \"text\", text: body }];\n}\n\nfunction qualified(tool: CachedTool): string {\n\treturn `${tool.server}:${tool.name}`;\n}\n\n/** Substring scoring, weighted to the name, which is what the model searched for. */\nfunction score(tool: CachedTool, needle: string): number {\n\tconst name = qualified(tool).toLowerCase();\n\tconst description = tool.description.toLowerCase();\n\tif (name === needle) return 100;\n\tif (name.includes(needle)) return 50;\n\tif (description.includes(needle)) return 10;\n\treturn 0;\n}\n\nfunction renderList(tools: readonly CachedTool[]): string {\n\treturn tools.map((tool) => `${qualified(tool)}: ${tool.description}`).join(\"\\n\");\n}\n\nfunction nearest(tools: readonly CachedTool[], target: string): CachedTool[] {\n\tconst needle = target.toLowerCase();\n\tconst stem = needle.slice(0, Math.max(3, Math.floor(needle.length * 0.6)));\n\treturn tools.filter((tool) => qualified(tool).toLowerCase().includes(stem)).slice(0, 5);\n}\n\nexport interface McpToolOptions {\n\tservers: ReadonlyMap<string, McpServerConfig>;\n\tcache: McpMetadataCache;\n\tmanager: McpServerManager;\n}\n\nexport function createMcpToolDefinition(\n\toptions: McpToolOptions,\n): ApexToolDefinition<typeof mcpToolSchema, McpToolDetails> {\n\tconst { servers, cache, manager } = options;\n\n\treturn {\n\t\tname: MCP_TOOL_NAME,\n\t\tlabel: \"mcp\",\n\t\tdescription: DESCRIPTION,\n\t\tpromptSnippet: \"Call tools on configured MCP servers\",\n\t\tparameters: mcpToolSchema,\n\t\tcontract: createMcpToolContract(servers),\n\t\tasync execute(_id, params: McpToolParams): Promise<AgentToolResult<McpToolDetails>> {\n\t\t\tif (params.tool) return callTool(params.tool, params.args);\n\t\t\tif (params.describe) return describeTool(params.describe);\n\t\t\tif (params.search !== undefined) return searchTools(params.search, params.server);\n\t\t\tif (params.server) return listServer(params.server);\n\n\t\t\treturn {\n\t\t\t\tcontent: text('Provide one of \"search\", \"server\", \"describe\", or \"tool\".'),\n\t\t\t\tdetails: { action: \"search\", server: undefined, tool: undefined },\n\t\t\t};\n\t\t},\n\t};\n\n\tfunction searchTools(needle: string, serverFilter?: string): AgentToolResult<McpToolDetails> {\n\t\tconst pool = serverFilter ? cache.all().filter((tool) => tool.server === serverFilter) : cache.all();\n\t\tconst lowered = needle.toLowerCase();\n\t\tconst ranked = pool\n\t\t\t.map((tool) => ({ tool, rank: score(tool, lowered) }))\n\t\t\t.filter((entry) => entry.rank > 0)\n\t\t\t.sort((a, b) => b.rank - a.rank)\n\t\t\t.slice(0, MAX_RESULTS)\n\t\t\t.map((entry) => entry.tool);\n\n\t\treturn {\n\t\t\tcontent: text(\n\t\t\t\tranked.length > 0\n\t\t\t\t\t? renderList(ranked)\n\t\t\t\t\t: `No cached MCP tool matches \"${needle}\". Configured servers: ${[...servers.keys()].join(\", \") || \"none\"}.`,\n\t\t\t),\n\t\t\tdetails: { action: \"search\", server: serverFilter, tool: undefined },\n\t\t};\n\t}\n\n\tfunction listServer(name: string): AgentToolResult<McpToolDetails> {\n\t\tif (!servers.has(name)) {\n\t\t\treturn {\n\t\t\t\tcontent: text(\n\t\t\t\t\t`MCP server \"${name}\" is not configured. Configured servers: ${[...servers.keys()].join(\", \") || \"none\"}.`,\n\t\t\t\t),\n\t\t\t\tdetails: { action: \"list\", server: name, tool: undefined },\n\t\t\t};\n\t\t}\n\n\t\tconst tools = cache.all().filter((tool) => tool.server === name);\n\t\treturn {\n\t\t\tcontent: text(\n\t\t\t\ttools.length > 0\n\t\t\t\t\t? renderList(tools)\n\t\t\t\t\t: `No cached tools for \"${name}\" yet. Tools are cached the first time the server is called, so call a known tool on it, or set \"lifecycle\": \"eager\" for this server in .mcp.json to have them cached at startup.`,\n\t\t\t),\n\t\t\tdetails: { action: \"list\", server: name, tool: undefined },\n\t\t};\n\t}\n\n\tfunction describeTool(target: string): AgentToolResult<McpToolDetails> {\n\t\tconst found = cache.all().find((tool) => qualified(tool) === target);\n\t\tif (!found) {\n\t\t\tconst suggestions = nearest(cache.all(), target);\n\t\t\treturn {\n\t\t\t\tcontent: text(\n\t\t\t\t\tsuggestions.length > 0\n\t\t\t\t\t\t? `No cached tool named \"${target}\". Did you mean:\\n${renderList(suggestions)}`\n\t\t\t\t\t\t: `No cached tool named \"${target}\". Search with {\"search\":\"keyword\"}.`,\n\t\t\t\t),\n\t\t\t\tdetails: { action: \"describe\", server: undefined, tool: target },\n\t\t\t};\n\t\t}\n\n\t\treturn {\n\t\t\tcontent: text(\n\t\t\t\t`${qualified(found)}\\n${found.description}\\n\\nInput schema:\\n${JSON.stringify(found.inputSchema, null, 2)}`,\n\t\t\t),\n\t\t\tdetails: { action: \"describe\", server: found.server, tool: target },\n\t\t};\n\t}\n\n\tasync function callTool(target: string, args: unknown): Promise<AgentToolResult<McpToolDetails>> {\n\t\tconst separator = target.indexOf(\":\");\n\t\tconst details: McpToolDetails = { action: \"call\", server: undefined, tool: target };\n\t\tif (separator <= 0) {\n\t\t\treturn { content: text(`Tool must be qualified as \"server:tool\". Received \"${target}\".`), details };\n\t\t}\n\n\t\tconst serverName = target.slice(0, separator);\n\t\tconst toolName = target.slice(separator + 1);\n\t\tdetails.server = serverName;\n\n\t\tif (!servers.has(serverName)) {\n\t\t\treturn {\n\t\t\t\tcontent: text(\n\t\t\t\t\t`MCP server \"${serverName}\" is not configured. Configured servers: ${[...servers.keys()].join(\", \") || \"none\"}.`,\n\t\t\t\t),\n\t\t\t\tdetails,\n\t\t\t};\n\t\t}\n\n\t\ttry {\n\t\t\tconst result = await manager.withConnection(serverName, async (connection) => {\n\t\t\t\t// An empty list is a fact about the server, not a failed read. Keeping the\n\t\t\t\t// previous entry would leave search advertising tools that no longer exist.\n\t\t\t\tconst fresh = await connection.listTools();\n\t\t\t\tcache.set(servers.get(serverName) as McpServerConfig, fresh);\n\t\t\t\tcache.save();\n\t\t\t\treturn connection.callTool(toolName, args);\n\t\t\t});\n\n\t\t\t// `AgentToolResult` has no error flag; a server-reported failure is marked in\n\t\t\t// the text so the model can see it failed without the turn being aborted.\n\t\t\tconst content = result.isError\n\t\t\t\t? text(`Tool reported an error:\\n${result.content.map((part) => part.text).join(\"\\n\")}`)\n\t\t\t\t: result.content;\n\t\t\treturn { content, details };\n\t\t} catch (error) {\n\t\t\t// OAuth failures already carry the one action that helps (`apex-code mcp auth\n\t\t\t// <server>`); the generic \"unavailable\" wrapper would bury it.\n\t\t\tif (error instanceof McpOAuthRequiredError || error instanceof McpOAuthRefreshError) {\n\t\t\t\treturn { content: text(error.message), details };\n\t\t\t}\n\t\t\t// A failed server is reported, not retried: the manager holds it in `failed`\n\t\t\t// with a backoff window so one broken server cannot cost every call a spawn.\n\t\t\treturn {\n\t\t\t\tcontent: text(\n\t\t\t\t\t`MCP server \"${serverName}\" is unavailable: ${error instanceof Error ? error.message : String(error)}`,\n\t\t\t\t),\n\t\t\t\tdetails,\n\t\t\t};\n\t\t}\n\t}\n}\n\nexport function createMcpTool(options: McpToolOptions) {\n\treturn wrapToolDefinition(createMcpToolDefinition(options));\n}\n"]}

package/dist/core/mcp/mcp-tool.js

@@ -0,0 +1,171 @@
+/**
+ * One tool for every MCP server, instead of one tool per server tool.
+ *
+ * Registering each server tool individually costs 150-300 prompt tokens apiece, and
+ * two ordinary servers would exceed the whole static-prefix budget before a
+ * conversation starts. The proxy costs one announced name and this description,
+ * because its schema defers.
+ *
+ * `search` and `describe` read the disk cache and reach no server. Only a `tool` call
+ * connects, which is what makes discovery free and is why the two have separate
+ * permission rules (ADR 0025).
+ */
+import { wrapToolDefinition } from "../tools/tool-definition-wrapper.js";
+import { createMcpToolContract } from "./contract.js";
+import { McpOAuthRefreshError, McpOAuthRequiredError } from "./oauth/mcp-token.js";
+import { mcpToolSchema } from "./schema.js";
+export const MCP_TOOL_NAME = "mcp";
+const MAX_RESULTS = 25;
+const DESCRIPTION = "Use tools provided by configured MCP servers. " +
+    'Search with {"search":"keyword"}, list one server with {"server":"name"}, ' +
+    'see a tool\'s full schema with {"describe":"server:tool"}, ' +
+    'and call one with {"tool":"server:tool","args":{...}}. ' +
+    "Search and describe read a local cache and never start a server, so discovery is free. " +
+    "Always describe a tool before calling it for the first time.";
+function text(body) {
+    return [{ type: "text", text: body }];
+}
+function qualified(tool) {
+    return `${tool.server}:${tool.name}`;
+}
+/** Substring scoring, weighted to the name, which is what the model searched for. */
+function score(tool, needle) {
+    const name = qualified(tool).toLowerCase();
+    const description = tool.description.toLowerCase();
+    if (name === needle)
+        return 100;
+    if (name.includes(needle))
+        return 50;
+    if (description.includes(needle))
+        return 10;
+    return 0;
+}
+function renderList(tools) {
+    return tools.map((tool) => `${qualified(tool)}: ${tool.description}`).join("\n");
+}
+function nearest(tools, target) {
+    const needle = target.toLowerCase();
+    const stem = needle.slice(0, Math.max(3, Math.floor(needle.length * 0.6)));
+    return tools.filter((tool) => qualified(tool).toLowerCase().includes(stem)).slice(0, 5);
+}
+export function createMcpToolDefinition(options) {
+    const { servers, cache, manager } = options;
+    return {
+        name: MCP_TOOL_NAME,
+        label: "mcp",
+        description: DESCRIPTION,
+        promptSnippet: "Call tools on configured MCP servers",
+        parameters: mcpToolSchema,
+        contract: createMcpToolContract(servers),
+        async execute(_id, params) {
+            if (params.tool)
+                return callTool(params.tool, params.args);
+            if (params.describe)
+                return describeTool(params.describe);
+            if (params.search !== undefined)
+                return searchTools(params.search, params.server);
+            if (params.server)
+                return listServer(params.server);
+            return {
+                content: text('Provide one of "search", "server", "describe", or "tool".'),
+                details: { action: "search", server: undefined, tool: undefined },
+            };
+        },
+    };
+    function searchTools(needle, serverFilter) {
+        const pool = serverFilter ? cache.all().filter((tool) => tool.server === serverFilter) : cache.all();
+        const lowered = needle.toLowerCase();
+        const ranked = pool
+            .map((tool) => ({ tool, rank: score(tool, lowered) }))
+            .filter((entry) => entry.rank > 0)
+            .sort((a, b) => b.rank - a.rank)
+            .slice(0, MAX_RESULTS)
+            .map((entry) => entry.tool);
+        return {
+            content: text(ranked.length > 0
+                ? renderList(ranked)
+                : `No cached MCP tool matches "${needle}". Configured servers: ${[...servers.keys()].join(", ") || "none"}.`),
+            details: { action: "search", server: serverFilter, tool: undefined },
+        };
+    }
+    function listServer(name) {
+        if (!servers.has(name)) {
+            return {
+                content: text(`MCP server "${name}" is not configured. Configured servers: ${[...servers.keys()].join(", ") || "none"}.`),
+                details: { action: "list", server: name, tool: undefined },
+            };
+        }
+        const tools = cache.all().filter((tool) => tool.server === name);
+        return {
+            content: text(tools.length > 0
+                ? renderList(tools)
+                : `No cached tools for "${name}" yet. Tools are cached the first time the server is called, so call a known tool on it, or set "lifecycle": "eager" for this server in .mcp.json to have them cached at startup.`),
+            details: { action: "list", server: name, tool: undefined },
+        };
+    }
+    function describeTool(target) {
+        const found = cache.all().find((tool) => qualified(tool) === target);
+        if (!found) {
+            const suggestions = nearest(cache.all(), target);
+            return {
+                content: text(suggestions.length > 0
+                    ? `No cached tool named "${target}". Did you mean:\n${renderList(suggestions)}`
+                    : `No cached tool named "${target}". Search with {"search":"keyword"}.`),
+                details: { action: "describe", server: undefined, tool: target },
+            };
+        }
+        return {
+            content: text(`${qualified(found)}\n${found.description}\n\nInput schema:\n${JSON.stringify(found.inputSchema, null, 2)}`),
+            details: { action: "describe", server: found.server, tool: target },
+        };
+    }
+    async function callTool(target, args) {
+        const separator = target.indexOf(":");
+        const details = { action: "call", server: undefined, tool: target };
+        if (separator <= 0) {
+            return { content: text(`Tool must be qualified as "server:tool". Received "${target}".`), details };
+        }
+        const serverName = target.slice(0, separator);
+        const toolName = target.slice(separator + 1);
+        details.server = serverName;
+        if (!servers.has(serverName)) {
+            return {
+                content: text(`MCP server "${serverName}" is not configured. Configured servers: ${[...servers.keys()].join(", ") || "none"}.`),
+                details,
+            };
+        }
+        try {
+            const result = await manager.withConnection(serverName, async (connection) => {
+                // An empty list is a fact about the server, not a failed read. Keeping the
+                // previous entry would leave search advertising tools that no longer exist.
+                const fresh = await connection.listTools();
+                cache.set(servers.get(serverName), fresh);
+                cache.save();
+                return connection.callTool(toolName, args);
+            });
+            // `AgentToolResult` has no error flag; a server-reported failure is marked in
+            // the text so the model can see it failed without the turn being aborted.
+            const content = result.isError
+                ? text(`Tool reported an error:\n${result.content.map((part) => part.text).join("\n")}`)
+                : result.content;
+            return { content, details };
+        }
+        catch (error) {
+            // OAuth failures already carry the one action that helps (`apex-code mcp auth
+            // <server>`); the generic "unavailable" wrapper would bury it.
+            if (error instanceof McpOAuthRequiredError || error instanceof McpOAuthRefreshError) {
+                return { content: text(error.message), details };
+            }
+            // A failed server is reported, not retried: the manager holds it in `failed`
+            // with a backoff window so one broken server cannot cost every call a spawn.
+            return {
+                content: text(`MCP server "${serverName}" is unavailable: ${error instanceof Error ? error.message : String(error)}`),
+                details,
+            };
+        }
+    }
+}
+export function createMcpTool(options) {
+    return wrapToolDefinition(createMcpToolDefinition(options));
+}
+//# sourceMappingURL=mcp-tool.js.map

package/dist/core/mcp/mcp-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-tool.js","sourceRoot":"","sources":["../../../src/core/mcp/mcp-tool.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * One tool for every MCP server, instead of one tool per server tool.\n *\n * Registering each server tool individually costs 150-300 prompt tokens apiece, and\n * two ordinary servers would exceed the whole static-prefix budget before a\n * conversation starts. The proxy costs one announced name and this description,\n * because its schema defers.\n *\n * `search` and `describe` read the disk cache and reach no server. Only a `tool` call\n * connects, which is what makes discovery free and is why the two have separate\n * permission rules (ADR 0025).\n */\n\nimport type { AgentToolResult } from \"apex-code-agent-core\";\nimport type { ApexToolDefinition } from \"../tools/contract.ts\";\nimport { wrapToolDefinition } from \"../tools/tool-definition-wrapper.ts\";\nimport { createMcpToolContract } from \"./contract.ts\";\nimport type { McpMetadataCache } from \"./metadata-cache.ts\";\nimport { McpOAuthRefreshError, McpOAuthRequiredError } from \"./oauth/mcp-token.ts\";\nimport { type McpToolDetails, type McpToolParams, mcpToolSchema } from \"./schema.ts\";\nimport type { McpServerManager } from \"./server-manager.ts\";\nimport type { CachedTool, McpServerConfig } from \"./types.ts\";\n\nexport const MCP_TOOL_NAME = \"mcp\";\n\nconst MAX_RESULTS = 25;\n\nconst DESCRIPTION =\n\t\"Use tools provided by configured MCP servers. \" +\n\t'Search with {\"search\":\"keyword\"}, list one server with {\"server\":\"name\"}, ' +\n\t'see a tool\\'s full schema with {\"describe\":\"server:tool\"}, ' +\n\t'and call one with {\"tool\":\"server:tool\",\"args\":{...}}. ' +\n\t\"Search and describe read a local cache and never start a server, so discovery is free. \" +\n\t\"Always describe a tool before calling it for the first time.\";\n\nfunction text(body: string): AgentToolResult<McpToolDetails>[\"content\"] {\n\treturn [{ type: \"text\", text: body }];\n}\n\nfunction qualified(tool: CachedTool): string {\n\treturn `${tool.server}:${tool.name}`;\n}\n\n/** Substring scoring, weighted to the name, which is what the model searched for. */\nfunction score(tool: CachedTool, needle: string): number {\n\tconst name = qualified(tool).toLowerCase();\n\tconst description = tool.description.toLowerCase();\n\tif (name === needle) return 100;\n\tif (name.includes(needle)) return 50;\n\tif (description.includes(needle)) return 10;\n\treturn 0;\n}\n\nfunction renderList(tools: readonly CachedTool[]): string {\n\treturn tools.map((tool) => `${qualified(tool)}: ${tool.description}`).join(\"\\n\");\n}\n\nfunction nearest(tools: readonly CachedTool[], target: string): CachedTool[] {\n\tconst needle = target.toLowerCase();\n\tconst stem = needle.slice(0, Math.max(3, Math.floor(needle.length * 0.6)));\n\treturn tools.filter((tool) => qualified(tool).toLowerCase().includes(stem)).slice(0, 5);\n}\n\nexport interface McpToolOptions {\n\tservers: ReadonlyMap<string, McpServerConfig>;\n\tcache: McpMetadataCache;\n\tmanager: McpServerManager;\n}\n\nexport function createMcpToolDefinition(\n\toptions: McpToolOptions,\n): ApexToolDefinition<typeof mcpToolSchema, McpToolDetails> {\n\tconst { servers, cache, manager } = options;\n\n\treturn {\n\t\tname: MCP_TOOL_NAME,\n\t\tlabel: \"mcp\",\n\t\tdescription: DESCRIPTION,\n\t\tpromptSnippet: \"Call tools on configured MCP servers\",\n\t\tparameters: mcpToolSchema,\n\t\tcontract: createMcpToolContract(servers),\n\t\tasync execute(_id, params: McpToolParams): Promise<AgentToolResult<McpToolDetails>> {\n\t\t\tif (params.tool) return callTool(params.tool, params.args);\n\t\t\tif (params.describe) return describeTool(params.describe);\n\t\t\tif (params.search !== undefined) return searchTools(params.search, params.server);\n\t\t\tif (params.server) return listServer(params.server);\n\n\t\t\treturn {\n\t\t\t\tcontent: text('Provide one of \"search\", \"server\", \"describe\", or \"tool\".'),\n\t\t\t\tdetails: { action: \"search\", server: undefined, tool: undefined },\n\t\t\t};\n\t\t},\n\t};\n\n\tfunction searchTools(needle: string, serverFilter?: string): AgentToolResult<McpToolDetails> {\n\t\tconst pool = serverFilter ? cache.all().filter((tool) => tool.server === serverFilter) : cache.all();\n\t\tconst lowered = needle.toLowerCase();\n\t\tconst ranked = pool\n\t\t\t.map((tool) => ({ tool, rank: score(tool, lowered) }))\n\t\t\t.filter((entry) => entry.rank > 0)\n\t\t\t.sort((a, b) => b.rank - a.rank)\n\t\t\t.slice(0, MAX_RESULTS)\n\t\t\t.map((entry) => entry.tool);\n\n\t\treturn {\n\t\t\tcontent: text(\n\t\t\t\tranked.length > 0\n\t\t\t\t\t? renderList(ranked)\n\t\t\t\t\t: `No cached MCP tool matches \"${needle}\". Configured servers: ${[...servers.keys()].join(\", \") || \"none\"}.`,\n\t\t\t),\n\t\t\tdetails: { action: \"search\", server: serverFilter, tool: undefined },\n\t\t};\n\t}\n\n\tfunction listServer(name: string): AgentToolResult<McpToolDetails> {\n\t\tif (!servers.has(name)) {\n\t\t\treturn {\n\t\t\t\tcontent: text(\n\t\t\t\t\t`MCP server \"${name}\" is not configured. Configured servers: ${[...servers.keys()].join(\", \") || \"none\"}.`,\n\t\t\t\t),\n\t\t\t\tdetails: { action: \"list\", server: name, tool: undefined },\n\t\t\t};\n\t\t}\n\n\t\tconst tools = cache.all().filter((tool) => tool.server === name);\n\t\treturn {\n\t\t\tcontent: text(\n\t\t\t\ttools.length > 0\n\t\t\t\t\t? renderList(tools)\n\t\t\t\t\t: `No cached tools for \"${name}\" yet. Tools are cached the first time the server is called, so call a known tool on it, or set \"lifecycle\": \"eager\" for this server in .mcp.json to have them cached at startup.`,\n\t\t\t),\n\t\t\tdetails: { action: \"list\", server: name, tool: undefined },\n\t\t};\n\t}\n\n\tfunction describeTool(target: string): AgentToolResult<McpToolDetails> {\n\t\tconst found = cache.all().find((tool) => qualified(tool) === target);\n\t\tif (!found) {\n\t\t\tconst suggestions = nearest(cache.all(), target);\n\t\t\treturn {\n\t\t\t\tcontent: text(\n\t\t\t\t\tsuggestions.length > 0\n\t\t\t\t\t\t? `No cached tool named \"${target}\". Did you mean:\\n${renderList(suggestions)}`\n\t\t\t\t\t\t: `No cached tool named \"${target}\". Search with {\"search\":\"keyword\"}.`,\n\t\t\t\t),\n\t\t\t\tdetails: { action: \"describe\", server: undefined, tool: target },\n\t\t\t};\n\t\t}\n\n\t\treturn {\n\t\t\tcontent: text(\n\t\t\t\t`${qualified(found)}\\n${found.description}\\n\\nInput schema:\\n${JSON.stringify(found.inputSchema, null, 2)}`,\n\t\t\t),\n\t\t\tdetails: { action: \"describe\", server: found.server, tool: target },\n\t\t};\n\t}\n\n\tasync function callTool(target: string, args: unknown): Promise<AgentToolResult<McpToolDetails>> {\n\t\tconst separator = target.indexOf(\":\");\n\t\tconst details: McpToolDetails = { action: \"call\", server: undefined, tool: target };\n\t\tif (separator <= 0) {\n\t\t\treturn { content: text(`Tool must be qualified as \"server:tool\". Received \"${target}\".`), details };\n\t\t}\n\n\t\tconst serverName = target.slice(0, separator);\n\t\tconst toolName = target.slice(separator + 1);\n\t\tdetails.server = serverName;\n\n\t\tif (!servers.has(serverName)) {\n\t\t\treturn {\n\t\t\t\tcontent: text(\n\t\t\t\t\t`MCP server \"${serverName}\" is not configured. Configured servers: ${[...servers.keys()].join(\", \") || \"none\"}.`,\n\t\t\t\t),\n\t\t\t\tdetails,\n\t\t\t};\n\t\t}\n\n\t\ttry {\n\t\t\tconst result = await manager.withConnection(serverName, async (connection) => {\n\t\t\t\t// An empty list is a fact about the server, not a failed read. Keeping the\n\t\t\t\t// previous entry would leave search advertising tools that no longer exist.\n\t\t\t\tconst fresh = await connection.listTools();\n\t\t\t\tcache.set(servers.get(serverName) as McpServerConfig, fresh);\n\t\t\t\tcache.save();\n\t\t\t\treturn connection.callTool(toolName, args);\n\t\t\t});\n\n\t\t\t// `AgentToolResult` has no error flag; a server-reported failure is marked in\n\t\t\t// the text so the model can see it failed without the turn being aborted.\n\t\t\tconst content = result.isError\n\t\t\t\t? text(`Tool reported an error:\\n${result.content.map((part) => part.text).join(\"\\n\")}`)\n\t\t\t\t: result.content;\n\t\t\treturn { content, details };\n\t\t} catch (error) {\n\t\t\t// OAuth failures already carry the one action that helps (`apex-code mcp auth\n\t\t\t// <server>`); the generic \"unavailable\" wrapper would bury it.\n\t\t\tif (error instanceof McpOAuthRequiredError || error instanceof McpOAuthRefreshError) {\n\t\t\t\treturn { content: text(error.message), details };\n\t\t\t}\n\t\t\t// A failed server is reported, not retried: the manager holds it in `failed`\n\t\t\t// with a backoff window so one broken server cannot cost every call a spawn.\n\t\t\treturn {\n\t\t\t\tcontent: text(\n\t\t\t\t\t`MCP server \"${serverName}\" is unavailable: ${error instanceof Error ? error.message : String(error)}`,\n\t\t\t\t),\n\t\t\t\tdetails,\n\t\t\t};\n\t\t}\n\t}\n}\n\nexport function createMcpTool(options: McpToolOptions) {\n\treturn wrapToolDefinition(createMcpToolDefinition(options));\n}\n"]}

package/dist/core/mcp/metadata-cache.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Persistent MCP tool metadata, so search and describe answer without a running
+ * server. Everything the cache holds is producible from a past connection, which is
+ * what makes "no server needed to search" a property rather than a convention.
+ *
+ * One file for every server, not one per server: the whole cache is read once at
+ * session start and written whole, and a handful of servers never makes that costly.
+ */
+import type { CachedTool, McpServerConfig } from "./types.ts";
+export declare function mcpCachePath(): string;
+/**
+ * The name is part of the key, not only the launch spec. Two servers can share a
+ * command (the same binary run twice under different names) and would otherwise
+ * collide, the second silently overwriting the first's cached tools.
+ */
+export declare function serverCacheKey(server: McpServerConfig): string;
+export declare class McpMetadataCache {
+    private file;
+    private readonly path;
+    constructor(path?: string);
+    private static read;
+    get(server: McpServerConfig): CachedTool[];
+    all(): CachedTool[];
+    set(server: McpServerConfig, tools: readonly CachedTool[]): void;
+    /** Forget every server absent from `configured`, so a removed server stops appearing in search. */
+    prune(configured: readonly McpServerConfig[]): void;
+    save(): void;
+}
+//# sourceMappingURL=metadata-cache.d.ts.map

package/dist/core/mcp/metadata-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata-cache.d.ts","sourceRoot":"","sources":["../../../src/core/mcp/metadata-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAgB,MAAM,YAAY,CAAC;AAW5E,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAwBD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAG9D;AAED,qBAAa,gBAAgB;IAC5B,OAAO,CAAC,IAAI,CAAY;IACxB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAE9B,YAAY,IAAI,GAAE,MAAuB,EAGxC;IAED,OAAO,CAAC,MAAM,CAAC,IAAI;IAanB,GAAG,CAAC,MAAM,EAAE,eAAe,GAAG,UAAU,EAAE,CAEzC;IAED,GAAG,IAAI,UAAU,EAAE,CAElB;IAED,GAAG,CAAC,MAAM,EAAE,eAAe,EAAE,KAAK,EAAE,SAAS,UAAU,EAAE,GAAG,IAAI,CAE/D;IAED,mGAAmG;IACnG,KAAK,CAAC,UAAU,EAAE,SAAS,eAAe,EAAE,GAAG,IAAI,CAKlD;IAED,IAAI,IAAI,IAAI,CAUX;CACD","sourcesContent":["/**\n * Persistent MCP tool metadata, so search and describe answer without a running\n * server. Everything the cache holds is producible from a past connection, which is\n * what makes \"no server needed to search\" a property rather than a convention.\n *\n * One file for every server, not one per server: the whole cache is read once at\n * session start and written whole, and a handful of servers never makes that costly.\n */\n\nimport { createHash } from \"node:crypto\";\nimport { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from \"node:fs\";\nimport { dirname, join } from \"node:path\";\nimport { getAgentDir } from \"../../config.ts\";\nimport type { CachedTool, McpServerConfig, McpTransport } from \"./types.ts\";\n\ninterface CacheFile {\n\tversion: 1;\n\tservers: Record<string, { name: string; tools: CachedTool[] }>;\n}\n\nconst EMPTY: CacheFile = { version: 1, servers: {} };\n\nconst SEPARATOR = \"|\";\n\nexport function mcpCachePath(): string {\n\treturn join(getAgentDir(), \"mcp\", \"metadata.json\");\n}\n\n/**\n * Everything that can change which tools a server publishes, and nothing that cannot.\n * A version bump in `args` produces a new key and therefore reads no stale entries,\n * while `capabilities` or `idleTimeoutMinutes` leave the key alone.\n */\nfunction transportIdentity(transport: McpTransport): string {\n\tif (transport.kind === \"stdio\") {\n\t\t// Env values, not just keys: a server that switches which token or mode it runs\n\t\t// under can publish a different tool list under the same command line.\n\t\tconst env = Object.entries(transport.env)\n\t\t\t.sort(([a], [b]) => a.localeCompare(b))\n\t\t\t.map(([key, value]) => `${key}=${value}`)\n\t\t\t.join(\",\");\n\t\treturn [\"stdio\", transport.command, transport.args.join(\" \"), env, transport.cwd ?? \"\"].join(SEPARATOR);\n\t}\n\tconst headers = Object.entries(transport.headers)\n\t\t.sort(([a], [b]) => a.localeCompare(b))\n\t\t.map(([key, value]) => `${key}=${value}`)\n\t\t.join(\",\");\n\treturn [\"http\", transport.url, headers, transport.bearerTokenEnv ?? \"\"].join(SEPARATOR);\n}\n\n/**\n * The name is part of the key, not only the launch spec. Two servers can share a\n * command (the same binary run twice under different names) and would otherwise\n * collide, the second silently overwriting the first's cached tools.\n */\nexport function serverCacheKey(server: McpServerConfig): string {\n\tconst identity = [server.name, transportIdentity(server.transport)].join(SEPARATOR);\n\treturn createHash(\"sha256\").update(identity).digest(\"hex\").slice(0, 32);\n}\n\nexport class McpMetadataCache {\n\tprivate file: CacheFile;\n\tprivate readonly path: string;\n\n\tconstructor(path: string = mcpCachePath()) {\n\t\tthis.path = path;\n\t\tthis.file = McpMetadataCache.read(path);\n\t}\n\n\tprivate static read(path: string): CacheFile {\n\t\tif (!existsSync(path)) return structuredClone(EMPTY);\n\t\ttry {\n\t\t\tconst parsed = JSON.parse(readFileSync(path, \"utf-8\")) as CacheFile;\n\t\t\tif (parsed?.version !== 1 || typeof parsed.servers !== \"object\" || parsed.servers === null) {\n\t\t\t\treturn structuredClone(EMPTY);\n\t\t\t}\n\t\t\treturn parsed;\n\t\t} catch {\n\t\t\treturn structuredClone(EMPTY);\n\t\t}\n\t}\n\n\tget(server: McpServerConfig): CachedTool[] {\n\t\treturn this.file.servers[serverCacheKey(server)]?.tools ?? [];\n\t}\n\n\tall(): CachedTool[] {\n\t\treturn Object.values(this.file.servers).flatMap((entry) => entry.tools);\n\t}\n\n\tset(server: McpServerConfig, tools: readonly CachedTool[]): void {\n\t\tthis.file.servers[serverCacheKey(server)] = { name: server.name, tools: [...tools] };\n\t}\n\n\t/** Forget every server absent from `configured`, so a removed server stops appearing in search. */\n\tprune(configured: readonly McpServerConfig[]): void {\n\t\tconst live = new Set(configured.map(serverCacheKey));\n\t\tfor (const key of Object.keys(this.file.servers)) {\n\t\t\tif (!live.has(key)) delete this.file.servers[key];\n\t\t}\n\t}\n\n\tsave(): void {\n\t\tconst directory = dirname(this.path);\n\t\tmkdirSync(directory, { recursive: true });\n\t\tconst temporary = join(directory, `.metadata.${process.pid}.tmp`);\n\t\ttry {\n\t\t\twriteFileSync(temporary, JSON.stringify(this.file));\n\t\t\trenameSync(temporary, this.path);\n\t\t} catch {\n\t\t\trmSync(temporary, { force: true });\n\t\t}\n\t}\n}\n"]}