apex-code 0.0.1-alpha.9 → 0.0.5

package/dist/core/mcp/config.js

@@ -0,0 +1,166 @@
+/**
+ * Reads the ecosystem-standard `{ "mcpServers": { … } }` shape from a project
+ * `.mcp.json` and a global `mcp.json`, project winning per server name.
+ *
+ * Every failure degrades. A malformed file yields no servers and one diagnostic; a
+ * malformed entry drops itself and leaves its siblings intact. A config file is the
+ * first thing a user hand-edits, so a parse error must never take the session down.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { CONFIG_DIR_NAME } from "../../config.js";
+import { ALL_CAPABILITIES } from "../tools/contract.js";
+import { DEFAULT_IDLE_TIMEOUT_MINUTES, DEFAULT_LIFECYCLE, } from "./types.js";
+const LIFECYCLES = ["lazy", "eager", "keep-alive", "lazy-keep-alive"];
+export const PROJECT_CONFIG_FILENAME = ".mcp.json";
+export function globalMcpConfigPath() {
+    return join(homedir(), CONFIG_DIR_NAME, "mcp.json");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stringRecord(value) {
+    if (!isRecord(value))
+        return {};
+    const out = {};
+    for (const [key, item] of Object.entries(value)) {
+        if (typeof item === "string")
+            out[key] = item;
+    }
+    return out;
+}
+function stringArray(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+function parseTransport(entry) {
+    const command = typeof entry.command === "string" ? entry.command : undefined;
+    const url = typeof entry.url === "string" ? entry.url : undefined;
+    if (command && url)
+        return "declares both command and url; exactly one is required";
+    if (command) {
+        return {
+            kind: "stdio",
+            command,
+            args: stringArray(entry.args),
+            env: stringRecord(entry.env),
+            cwd: typeof entry.cwd === "string" ? entry.cwd : undefined,
+        };
+    }
+    if (url) {
+        return {
+            kind: "http",
+            url,
+            headers: stringRecord(entry.headers),
+            bearerTokenEnv: typeof entry.bearerTokenEnv === "string" ? entry.bearerTokenEnv : undefined,
+        };
+    }
+    return "declares neither command nor url";
+}
+/**
+ * An absent `capabilities` is the common case, not an edge case: a config pasted from
+ * another host carries no Apex-specific field. Those servers get the full set, which
+ * keeps them classified (never `UNCLASSIFIED`) without narrowing anything the user
+ * did not ask to narrow.
+ */
+function parseCapabilities(entry, report) {
+    if (!("capabilities" in entry))
+        return ALL_CAPABILITIES;
+    if (!Array.isArray(entry.capabilities)) {
+        report("capabilities is not an array; falling back to the full capability set");
+        return ALL_CAPABILITIES;
+    }
+    const resolved = new Set();
+    const unknown = [];
+    for (const candidate of entry.capabilities) {
+        if (typeof candidate === "string" && ALL_CAPABILITIES.has(candidate)) {
+            resolved.add(candidate);
+        }
+        else {
+            unknown.push(String(candidate));
+        }
+    }
+    if (unknown.length > 0)
+        report(`unknown capabilities dropped: ${unknown.join(", ")}`);
+    return resolved;
+}
+function parseLifecycle(entry, report) {
+    const value = entry.lifecycle;
+    if (value === undefined)
+        return DEFAULT_LIFECYCLE;
+    if (typeof value === "string" && LIFECYCLES.includes(value))
+        return value;
+    report(`unknown lifecycle ${JSON.stringify(value)}; using ${DEFAULT_LIFECYCLE}`);
+    return DEFAULT_LIFECYCLE;
+}
+function parseIdleTimeout(entry) {
+    const value = entry.idleTimeout;
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : DEFAULT_IDLE_TIMEOUT_MINUTES;
+}
+function parseAuth(entry, transport, report) {
+    const value = entry.auth;
+    if (value === undefined)
+        return undefined;
+    if (transport.kind !== "http") {
+        report("auth is only supported on HTTP servers; ignoring");
+        return undefined;
+    }
+    if (value === "oauth")
+        return "oauth";
+    report(`unknown auth ${JSON.stringify(value)}; only "oauth" is supported; ignoring`);
+    return undefined;
+}
+function readServers(path, diagnostics) {
+    const servers = new Map();
+    if (!existsSync(path))
+        return servers;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch (error) {
+        diagnostics.push({
+            path,
+            server: undefined,
+            message: `could not be parsed as JSON: ${error instanceof Error ? error.message : String(error)}`,
+        });
+        return servers;
+    }
+    if (!isRecord(parsed) || !isRecord(parsed.mcpServers)) {
+        diagnostics.push({ path, server: undefined, message: "has no mcpServers object" });
+        return servers;
+    }
+    for (const [name, raw] of Object.entries(parsed.mcpServers)) {
+        if (!isRecord(raw)) {
+            diagnostics.push({ path, server: name, message: "entry is not an object" });
+            continue;
+        }
+        const transport = parseTransport(raw);
+        if (typeof transport === "string") {
+            diagnostics.push({ path, server: name, message: transport });
+            continue;
+        }
+        const report = (message) => diagnostics.push({ path, server: name, message });
+        servers.set(name, {
+            name,
+            transport,
+            auth: parseAuth(raw, transport, report),
+            capabilities: parseCapabilities(raw, report),
+            lifecycle: parseLifecycle(raw, report),
+            idleTimeoutMinutes: parseIdleTimeout(raw),
+        });
+    }
+    return servers;
+}
+export function loadMcpConfig(options = {}) {
+    const diagnostics = [];
+    const globalPath = options.globalPath ?? globalMcpConfigPath();
+    const servers = readServers(globalPath, diagnostics);
+    if (options.projectPath) {
+        for (const [name, config] of readServers(options.projectPath, diagnostics)) {
+            servers.set(name, config);
+        }
+    }
+    return { servers, diagnostics };
+}
+//# sourceMappingURL=config.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/core/mcp/config.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Reads the ecosystem-standard `{ \"mcpServers\": { … } }` shape from a project\n * `.mcp.json` and a global `mcp.json`, project winning per server name.\n *\n * Every failure degrades. A malformed file yields no servers and one diagnostic; a\n * malformed entry drops itself and leaves its siblings intact. A config file is the\n * first thing a user hand-edits, so a parse error must never take the session down.\n */\n\nimport { existsSync, readFileSync } from \"node:fs\";\nimport { homedir } from \"node:os\";\nimport { join } from \"node:path\";\nimport { CONFIG_DIR_NAME } from \"../../config.ts\";\nimport { ALL_CAPABILITIES, type Capability } from \"../tools/contract.ts\";\nimport {\n\tDEFAULT_IDLE_TIMEOUT_MINUTES,\n\tDEFAULT_LIFECYCLE,\n\ttype McpConfig,\n\ttype McpConfigDiagnostic,\n\ttype McpLifecycle,\n\ttype McpServerConfig,\n\ttype McpTransport,\n} from \"./types.ts\";\n\nconst LIFECYCLES: readonly McpLifecycle[] = [\"lazy\", \"eager\", \"keep-alive\", \"lazy-keep-alive\"];\n\nexport const PROJECT_CONFIG_FILENAME = \".mcp.json\";\n\nexport function globalMcpConfigPath(): string {\n\treturn join(homedir(), CONFIG_DIR_NAME, \"mcp.json\");\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction stringRecord(value: unknown): Record<string, string> {\n\tif (!isRecord(value)) return {};\n\tconst out: Record<string, string> = {};\n\tfor (const [key, item] of Object.entries(value)) {\n\t\tif (typeof item === \"string\") out[key] = item;\n\t}\n\treturn out;\n}\n\nfunction stringArray(value: unknown): string[] {\n\treturn Array.isArray(value) ? value.filter((item): item is string => typeof item === \"string\") : [];\n}\n\nfunction parseTransport(entry: Record<string, unknown>): McpTransport | string {\n\tconst command = typeof entry.command === \"string\" ? entry.command : undefined;\n\tconst url = typeof entry.url === \"string\" ? entry.url : undefined;\n\n\tif (command && url) return \"declares both command and url; exactly one is required\";\n\tif (command) {\n\t\treturn {\n\t\t\tkind: \"stdio\",\n\t\t\tcommand,\n\t\t\targs: stringArray(entry.args),\n\t\t\tenv: stringRecord(entry.env),\n\t\t\tcwd: typeof entry.cwd === \"string\" ? entry.cwd : undefined,\n\t\t};\n\t}\n\tif (url) {\n\t\treturn {\n\t\t\tkind: \"http\",\n\t\t\turl,\n\t\t\theaders: stringRecord(entry.headers),\n\t\t\tbearerTokenEnv: typeof entry.bearerTokenEnv === \"string\" ? entry.bearerTokenEnv : undefined,\n\t\t};\n\t}\n\treturn \"declares neither command nor url\";\n}\n\n/**\n * An absent `capabilities` is the common case, not an edge case: a config pasted from\n * another host carries no Apex-specific field. Those servers get the full set, which\n * keeps them classified (never `UNCLASSIFIED`) without narrowing anything the user\n * did not ask to narrow.\n */\nfunction parseCapabilities(entry: Record<string, unknown>, report: (message: string) => void): ReadonlySet<Capability> {\n\tif (!(\"capabilities\" in entry)) return ALL_CAPABILITIES;\n\tif (!Array.isArray(entry.capabilities)) {\n\t\treport(\"capabilities is not an array; falling back to the full capability set\");\n\t\treturn ALL_CAPABILITIES;\n\t}\n\n\tconst resolved = new Set<Capability>();\n\tconst unknown: string[] = [];\n\tfor (const candidate of entry.capabilities) {\n\t\tif (typeof candidate === \"string\" && ALL_CAPABILITIES.has(candidate as Capability)) {\n\t\t\tresolved.add(candidate as Capability);\n\t\t} else {\n\t\t\tunknown.push(String(candidate));\n\t\t}\n\t}\n\tif (unknown.length > 0) report(`unknown capabilities dropped: ${unknown.join(\", \")}`);\n\treturn resolved;\n}\n\nfunction parseLifecycle(entry: Record<string, unknown>, report: (message: string) => void): McpLifecycle {\n\tconst value = entry.lifecycle;\n\tif (value === undefined) return DEFAULT_LIFECYCLE;\n\tif (typeof value === \"string\" && LIFECYCLES.includes(value as McpLifecycle)) return value as McpLifecycle;\n\treport(`unknown lifecycle ${JSON.stringify(value)}; using ${DEFAULT_LIFECYCLE}`);\n\treturn DEFAULT_LIFECYCLE;\n}\n\nfunction parseIdleTimeout(entry: Record<string, unknown>): number {\n\tconst value = entry.idleTimeout;\n\treturn typeof value === \"number\" && Number.isFinite(value) && value >= 0 ? value : DEFAULT_IDLE_TIMEOUT_MINUTES;\n}\n\nfunction parseAuth(\n\tentry: Record<string, unknown>,\n\ttransport: McpTransport,\n\treport: (message: string) => void,\n): \"oauth\" | undefined {\n\tconst value = entry.auth;\n\tif (value === undefined) return undefined;\n\tif (transport.kind !== \"http\") {\n\t\treport(\"auth is only supported on HTTP servers; ignoring\");\n\t\treturn undefined;\n\t}\n\tif (value === \"oauth\") return \"oauth\";\n\treport(`unknown auth ${JSON.stringify(value)}; only \"oauth\" is supported; ignoring`);\n\treturn undefined;\n}\n\nfunction readServers(path: string, diagnostics: McpConfigDiagnostic[]): Map<string, McpServerConfig> {\n\tconst servers = new Map<string, McpServerConfig>();\n\tif (!existsSync(path)) return servers;\n\n\tlet parsed: unknown;\n\ttry {\n\t\tparsed = JSON.parse(readFileSync(path, \"utf-8\"));\n\t} catch (error) {\n\t\tdiagnostics.push({\n\t\t\tpath,\n\t\t\tserver: undefined,\n\t\t\tmessage: `could not be parsed as JSON: ${error instanceof Error ? error.message : String(error)}`,\n\t\t});\n\t\treturn servers;\n\t}\n\n\tif (!isRecord(parsed) || !isRecord(parsed.mcpServers)) {\n\t\tdiagnostics.push({ path, server: undefined, message: \"has no mcpServers object\" });\n\t\treturn servers;\n\t}\n\n\tfor (const [name, raw] of Object.entries(parsed.mcpServers)) {\n\t\tif (!isRecord(raw)) {\n\t\t\tdiagnostics.push({ path, server: name, message: \"entry is not an object\" });\n\t\t\tcontinue;\n\t\t}\n\t\tconst transport = parseTransport(raw);\n\t\tif (typeof transport === \"string\") {\n\t\t\tdiagnostics.push({ path, server: name, message: transport });\n\t\t\tcontinue;\n\t\t}\n\t\tconst report = (message: string) => diagnostics.push({ path, server: name, message });\n\t\tservers.set(name, {\n\t\t\tname,\n\t\t\ttransport,\n\t\t\tauth: parseAuth(raw, transport, report),\n\t\t\tcapabilities: parseCapabilities(raw, report),\n\t\t\tlifecycle: parseLifecycle(raw, report),\n\t\t\tidleTimeoutMinutes: parseIdleTimeout(raw),\n\t\t});\n\t}\n\n\treturn servers;\n}\n\nexport function loadMcpConfig(options: { projectPath?: string; globalPath?: string } = {}): McpConfig {\n\tconst diagnostics: McpConfigDiagnostic[] = [];\n\tconst globalPath = options.globalPath ?? globalMcpConfigPath();\n\n\tconst servers = readServers(globalPath, diagnostics);\n\tif (options.projectPath) {\n\t\tfor (const [name, config] of readServers(options.projectPath, diagnostics)) {\n\t\t\tservers.set(name, config);\n\t\t}\n\t}\n\n\treturn { servers, diagnostics };\n}\n"]}

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":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAIxD,0FAA0F;AAC1F,MAAM,CAAC,MAAM,aAAa,GAAG,eAAe,CAAC;AAE7C,MAAM,YAAY,GAAG,mCAAmC,CAAC;AAEzD,SAAS,MAAM,CAAC,MAAqB,EAA8C;IAClF,OAAO,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;AAAA,CACjE;AAED,6EAA6E;AAC7E,SAAS,kBAAkB,CAAC,SAAiB,EAAgD;IAC5F,MAAM,KAAK,GAAG,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACrC,IAAI,KAAK,IAAI,CAAC,IAAI,KAAK,KAAK,SAAS,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IACnE,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,EAAE,CAAC;AAAA,CAC/E;AAED,SAAS,OAAO,CAAC,WAAmB,EAAE,MAAqB,EAAW;IACrE,IAAI,WAAW,KAAK,aAAa;QAAE,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC1D,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;QAAE,OAAO,KAAK,CAAC;IAElC,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAC5C,IAAI,CAAC,IAAI;QAAE,OAAO,KAAK,CAAC;IACxB,MAAM,CAAC,EAAE,UAAU,EAAE,QAAQ,CAAC,GAAG,IAAI,CAAC;IAEtC,MAAM,MAAM,GAAG,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC/C,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAE1B,IAAI,UAAU,KAAK,MAAM,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAC/C,OAAO,QAAQ,KAAK,GAAG,IAAI,QAAQ,KAAK,MAAM,CAAC,IAAI,CAAC;AAAA,CACpD;AAED,SAAS,WAAW,CAAC,MAAqB,EAAiB;IAC1D,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;QAAE,OAAO,aAAa,CAAC;IAC1C,MAAM,MAAM,GAAG,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC/C,OAAO,MAAM,CAAC,CAAC,CAAC,OAAO,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AAAA,CAC9D;AAED,SAAS,QAAQ,CAAC,WAAmB,EAAU;IAC9C,IAAI,WAAW,KAAK,aAAa;QAAE,OAAO,6DAA6D,CAAC;IAExG,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAC5C,IAAI,CAAC,IAAI;QAAE,OAAO,0BAA0B,WAAW,EAAE,CAAC;IAC1D,MAAM,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,GAAG,IAAI,CAAC;IAC9B,OAAO,IAAI,KAAK,GAAG;QAClB,CAAC,CAAC,4BAA4B,MAAM,cAAc;QAClD,CAAC,CAAC,YAAY,IAAI,aAAa,MAAM,cAAc,CAAC;AAAA,CACrD;AAED;;;;;GAKG;AACH,SAAS,iBAAiB,CAAC,OAAkC,EAA2B;IACvF,MAAM,KAAK,GAAG,IAAI,GAAG,EAAc,CAAC;IACpC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC9B,KAAK,MAAM,UAAU,IAAI,MAAM,CAAC,YAAY;YAAE,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QACpE,IAAI,KAAK,CAAC,IAAI,KAAK,gBAAgB,CAAC,IAAI;YAAE,OAAO,gBAAgB,CAAC;IACnE,CAAC;IACD,OAAO,KAAK,CAAC;AAAA,CACb;AAED,MAAM,UAAU,qBAAqB,CACpC,OAA6C,EACQ;IACrD,OAAO;QACN,YAAY,EAAE,iBAAiB,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;QACjD,UAAU,EAAE;YACX,eAAe,EAAE,KAAK;YACtB,OAAO;YACP,QAAQ;YACR,WAAW;SACX;QACD,OAAO,EAAE,EAAE,iBAAiB,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE;QACxD,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,GAAG,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE;KACjD,CAAC;AAAA,CACF","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"]}