apex-code 0.0.1-alpha.9 → 0.0.5

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"]}

package/dist/core/mcp/metadata-cache.js

@@ -0,0 +1,99 @@
+/**
+ * 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 { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getAgentDir } from "../../config.js";
+const EMPTY = { version: 1, servers: {} };
+const SEPARATOR = "|";
+export function mcpCachePath() {
+    return join(getAgentDir(), "mcp", "metadata.json");
+}
+/**
+ * Everything that can change which tools a server publishes, and nothing that cannot.
+ * A version bump in `args` produces a new key and therefore reads no stale entries,
+ * while `capabilities` or `idleTimeoutMinutes` leave the key alone.
+ */
+function transportIdentity(transport) {
+    if (transport.kind === "stdio") {
+        // Env values, not just keys: a server that switches which token or mode it runs
+        // under can publish a different tool list under the same command line.
+        const env = Object.entries(transport.env)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([key, value]) => `${key}=${value}`)
+            .join(",");
+        return ["stdio", transport.command, transport.args.join(" "), env, transport.cwd ?? ""].join(SEPARATOR);
+    }
+    const headers = Object.entries(transport.headers)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([key, value]) => `${key}=${value}`)
+        .join(",");
+    return ["http", transport.url, headers, transport.bearerTokenEnv ?? ""].join(SEPARATOR);
+}
+/**
+ * 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 function serverCacheKey(server) {
+    const identity = [server.name, transportIdentity(server.transport)].join(SEPARATOR);
+    return createHash("sha256").update(identity).digest("hex").slice(0, 32);
+}
+export class McpMetadataCache {
+    file;
+    path;
+    constructor(path = mcpCachePath()) {
+        this.path = path;
+        this.file = McpMetadataCache.read(path);
+    }
+    static read(path) {
+        if (!existsSync(path))
+            return structuredClone(EMPTY);
+        try {
+            const parsed = JSON.parse(readFileSync(path, "utf-8"));
+            if (parsed?.version !== 1 || typeof parsed.servers !== "object" || parsed.servers === null) {
+                return structuredClone(EMPTY);
+            }
+            return parsed;
+        }
+        catch {
+            return structuredClone(EMPTY);
+        }
+    }
+    get(server) {
+        return this.file.servers[serverCacheKey(server)]?.tools ?? [];
+    }
+    all() {
+        return Object.values(this.file.servers).flatMap((entry) => entry.tools);
+    }
+    set(server, tools) {
+        this.file.servers[serverCacheKey(server)] = { name: server.name, tools: [...tools] };
+    }
+    /** Forget every server absent from `configured`, so a removed server stops appearing in search. */
+    prune(configured) {
+        const live = new Set(configured.map(serverCacheKey));
+        for (const key of Object.keys(this.file.servers)) {
+            if (!live.has(key))
+                delete this.file.servers[key];
+        }
+    }
+    save() {
+        const directory = dirname(this.path);
+        mkdirSync(directory, { recursive: true });
+        const temporary = join(directory, `.metadata.${process.pid}.tmp`);
+        try {
+            writeFileSync(temporary, JSON.stringify(this.file));
+            renameSync(temporary, this.path);
+        }
+        catch {
+            rmSync(temporary, { force: true });
+        }
+    }
+}
+//# sourceMappingURL=metadata-cache.js.map

package/dist/core/mcp/metadata-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata-cache.js","sourceRoot":"","sources":["../../../src/core/mcp/metadata-cache.ts"],"names":[],"mappings":"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","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"]}

package/dist/core/mcp/oauth/authorize.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared entry point for `apex-code mcp auth <server>` and the TUI `/mcp auth`
+ * command. Resolves the named server from the merged MCP config, checks it is an
+ * OAuth-configured HTTP server, and runs the flow. UI-agnostic: callers supply the
+ * line printer and the browser opener.
+ */
+import type { CredentialStore } from "@earendil-works/pi-ai";
+import { runMcpOAuthFlow } from "./flow.ts";
+export interface AuthorizeServerOptions {
+    serverName: string;
+    /** Project root for `.mcp.json` discovery. Default: process.cwd(). */
+    cwd?: string;
+    /** Credential sink. Default: the host store (`AuthStorage.create()`). */
+    credentials?: CredentialStore;
+    openBrowser?: (url: string) => void;
+    /** Injectable flow, for tests. */
+    flow?: typeof runMcpOAuthFlow;
+    log: (line: string) => void;
+}
+export declare function authorizeConfiguredServer(options: AuthorizeServerOptions): Promise<void>;
+//# sourceMappingURL=authorize.d.ts.map

package/dist/core/mcp/oauth/authorize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorize.d.ts","sourceRoot":"","sources":["../../../../src/core/mcp/oauth/authorize.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAG7D,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAE5C,MAAM,WAAW,sBAAsB;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,sEAAsE;IACtE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,kCAAkC;IAClC,IAAI,CAAC,EAAE,OAAO,eAAe,CAAC;IAC9B,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5B;AAED,wBAAsB,yBAAyB,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CA0B9F","sourcesContent":["/**\n * Shared entry point for `apex-code mcp auth <server>` and the TUI `/mcp auth`\n * command. Resolves the named server from the merged MCP config, checks it is an\n * OAuth-configured HTTP server, and runs the flow. UI-agnostic: callers supply the\n * line printer and the browser opener.\n */\n\nimport { join } from \"node:path\";\nimport type { CredentialStore } from \"@earendil-works/pi-ai\";\nimport { AuthStorage } from \"../../auth-storage.ts\";\nimport { loadMcpConfig, PROJECT_CONFIG_FILENAME } from \"../config.ts\";\nimport { runMcpOAuthFlow } from \"./flow.ts\";\n\nexport interface AuthorizeServerOptions {\n\tserverName: string;\n\t/** Project root for `.mcp.json` discovery. Default: process.cwd(). */\n\tcwd?: string;\n\t/** Credential sink. Default: the host store (`AuthStorage.create()`). */\n\tcredentials?: CredentialStore;\n\topenBrowser?: (url: string) => void;\n\t/** Injectable flow, for tests. */\n\tflow?: typeof runMcpOAuthFlow;\n\tlog: (line: string) => void;\n}\n\nexport async function authorizeConfiguredServer(options: AuthorizeServerOptions): Promise<void> {\n\tconst { servers } = loadMcpConfig({ projectPath: join(options.cwd ?? process.cwd(), PROJECT_CONFIG_FILENAME) });\n\tconst server = servers.get(options.serverName);\n\tif (!server) {\n\t\tconst names = [...servers.keys()];\n\t\tthrow new Error(\n\t\t\t`MCP server \"${options.serverName}\" is not configured. Configured servers: ${names.join(\", \") || \"none\"}. Add it to .mcp.json first.`,\n\t\t);\n\t}\n\tif (server.transport.kind !== \"http\") {\n\t\tthrow new Error(`MCP server \"${options.serverName}\" is a stdio server; OAuth applies to HTTP servers only.`);\n\t}\n\tif (server.auth !== \"oauth\") {\n\t\tthrow new Error(\n\t\t\t`MCP server \"${options.serverName}\" is not configured for OAuth. Add \"auth\": \"oauth\" to its entry.`,\n\t\t);\n\t}\n\tconst result = await (options.flow ?? runMcpOAuthFlow)({\n\t\tserverName: options.serverName,\n\t\tserverUrl: server.transport.url,\n\t\tcredentials: options.credentials ?? AuthStorage.create(),\n\t\tdeps: { print: options.log, openBrowser: options.openBrowser ?? (() => {}) },\n\t});\n\toptions.log(\n\t\t`Authorized \"${options.serverName}\". Token stored; expires ${new Date(result.expiresAt).toISOString()}.`,\n\t);\n}\n"]}

package/dist/core/mcp/oauth/authorize.js

@@ -0,0 +1,32 @@
+/**
+ * Shared entry point for `apex-code mcp auth <server>` and the TUI `/mcp auth`
+ * command. Resolves the named server from the merged MCP config, checks it is an
+ * OAuth-configured HTTP server, and runs the flow. UI-agnostic: callers supply the
+ * line printer and the browser opener.
+ */
+import { join } from "node:path";
+import { AuthStorage } from "../../auth-storage.js";
+import { loadMcpConfig, PROJECT_CONFIG_FILENAME } from "../config.js";
+import { runMcpOAuthFlow } from "./flow.js";
+export async function authorizeConfiguredServer(options) {
+    const { servers } = loadMcpConfig({ projectPath: join(options.cwd ?? process.cwd(), PROJECT_CONFIG_FILENAME) });
+    const server = servers.get(options.serverName);
+    if (!server) {
+        const names = [...servers.keys()];
+        throw new Error(`MCP server "${options.serverName}" is not configured. Configured servers: ${names.join(", ") || "none"}. Add it to .mcp.json first.`);
+    }
+    if (server.transport.kind !== "http") {
+        throw new Error(`MCP server "${options.serverName}" is a stdio server; OAuth applies to HTTP servers only.`);
+    }
+    if (server.auth !== "oauth") {
+        throw new Error(`MCP server "${options.serverName}" is not configured for OAuth. Add "auth": "oauth" to its entry.`);
+    }
+    const result = await (options.flow ?? runMcpOAuthFlow)({
+        serverName: options.serverName,
+        serverUrl: server.transport.url,
+        credentials: options.credentials ?? AuthStorage.create(),
+        deps: { print: options.log, openBrowser: options.openBrowser ?? (() => { }) },
+    });
+    options.log(`Authorized "${options.serverName}". Token stored; expires ${new Date(result.expiresAt).toISOString()}.`);
+}
+//# sourceMappingURL=authorize.js.map

package/dist/core/mcp/oauth/authorize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorize.js","sourceRoot":"","sources":["../../../../src/core/mcp/oauth/authorize.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAc5C,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAAC,OAA+B,EAAiB;IAC/F,MAAM,EAAE,OAAO,EAAE,GAAG,aAAa,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,EAAE,uBAAuB,CAAC,EAAE,CAAC,CAAC;IAChH,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/C,IAAI,CAAC,MAAM,EAAE,CAAC;QACb,MAAM,KAAK,GAAG,CAAC,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;QAClC,MAAM,IAAI,KAAK,CACd,eAAe,OAAO,CAAC,UAAU,4CAA4C,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,MAAM,8BAA8B,CACrI,CAAC;IACH,CAAC;IACD,IAAI,MAAM,CAAC,SAAS,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,eAAe,OAAO,CAAC,UAAU,0DAA0D,CAAC,CAAC;IAC9G,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CACd,eAAe,OAAO,CAAC,UAAU,kEAAkE,CACnG,CAAC;IACH,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,eAAe,CAAC,CAAC;QACtD,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,SAAS,EAAE,MAAM,CAAC,SAAS,CAAC,GAAG;QAC/B,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,WAAW,CAAC,MAAM,EAAE;QACxD,IAAI,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,GAAG,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,CAAC,GAAG,EAAE,CAAC,EAAC,CAAC,CAAC,EAAE;KAC5E,CAAC,CAAC;IACH,OAAO,CAAC,GAAG,CACV,eAAe,OAAO,CAAC,UAAU,4BAA4B,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,GAAG,CACxG,CAAC;AAAA,CACF","sourcesContent":["/**\n * Shared entry point for `apex-code mcp auth <server>` and the TUI `/mcp auth`\n * command. Resolves the named server from the merged MCP config, checks it is an\n * OAuth-configured HTTP server, and runs the flow. UI-agnostic: callers supply the\n * line printer and the browser opener.\n */\n\nimport { join } from \"node:path\";\nimport type { CredentialStore } from \"@earendil-works/pi-ai\";\nimport { AuthStorage } from \"../../auth-storage.ts\";\nimport { loadMcpConfig, PROJECT_CONFIG_FILENAME } from \"../config.ts\";\nimport { runMcpOAuthFlow } from \"./flow.ts\";\n\nexport interface AuthorizeServerOptions {\n\tserverName: string;\n\t/** Project root for `.mcp.json` discovery. Default: process.cwd(). */\n\tcwd?: string;\n\t/** Credential sink. Default: the host store (`AuthStorage.create()`). */\n\tcredentials?: CredentialStore;\n\topenBrowser?: (url: string) => void;\n\t/** Injectable flow, for tests. */\n\tflow?: typeof runMcpOAuthFlow;\n\tlog: (line: string) => void;\n}\n\nexport async function authorizeConfiguredServer(options: AuthorizeServerOptions): Promise<void> {\n\tconst { servers } = loadMcpConfig({ projectPath: join(options.cwd ?? process.cwd(), PROJECT_CONFIG_FILENAME) });\n\tconst server = servers.get(options.serverName);\n\tif (!server) {\n\t\tconst names = [...servers.keys()];\n\t\tthrow new Error(\n\t\t\t`MCP server \"${options.serverName}\" is not configured. Configured servers: ${names.join(\", \") || \"none\"}. Add it to .mcp.json first.`,\n\t\t);\n\t}\n\tif (server.transport.kind !== \"http\") {\n\t\tthrow new Error(`MCP server \"${options.serverName}\" is a stdio server; OAuth applies to HTTP servers only.`);\n\t}\n\tif (server.auth !== \"oauth\") {\n\t\tthrow new Error(\n\t\t\t`MCP server \"${options.serverName}\" is not configured for OAuth. Add \"auth\": \"oauth\" to its entry.`,\n\t\t);\n\t}\n\tconst result = await (options.flow ?? runMcpOAuthFlow)({\n\t\tserverName: options.serverName,\n\t\tserverUrl: server.transport.url,\n\t\tcredentials: options.credentials ?? AuthStorage.create(),\n\t\tdeps: { print: options.log, openBrowser: options.openBrowser ?? (() => {}) },\n\t});\n\toptions.log(\n\t\t`Authorized \"${options.serverName}\". Token stored; expires ${new Date(result.expiresAt).toISOString()}.`,\n\t);\n}\n"]}

package/dist/core/mcp/oauth/discover.d.ts

@@ -0,0 +1,27 @@
+/**
+ * OAuth discovery for MCP servers: the `WWW-Authenticate` challenge, protected-resource
+ * metadata (RFC 9728), and authorization-server metadata (RFC 8414), in the order the
+ * MCP authorization spec expects.
+ *
+ * Metadata URLs must be https. The one exception is loopback, because the authorization
+ * code flow itself speaks loopback http and local development servers ride on it.
+ */
+export type FetchLike = typeof fetch;
+export declare class OAuthDiscoveryError extends Error {
+}
+export interface AuthorizationServerMetadata {
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+    registrationEndpoint: string | undefined;
+}
+export declare function oauthErrorMessage(error: unknown): string;
+/** Pulls `resource_metadata` out of a `WWW-Authenticate: Bearer …` challenge, if present. */
+export declare function parseWwwAuthenticate(value: string | undefined): {
+    resourceMetadata?: string;
+};
+export declare function discoverAuthorizationServer(options: {
+    serverUrl: string;
+    wwwAuthenticate?: string;
+    fetch?: FetchLike;
+}): Promise<AuthorizationServerMetadata>;
+//# sourceMappingURL=discover.d.ts.map

package/dist/core/mcp/oauth/discover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../../../../src/core/mcp/oauth/discover.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,SAAS,GAAG,OAAO,KAAK,CAAC;AAErC,qBAAa,mBAAoB,SAAQ,KAAK;CAAG;AAEjD,MAAM,WAAW,2BAA2B;IAC3C,qBAAqB,EAAE,MAAM,CAAC;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,oBAAoB,EAAE,MAAM,GAAG,SAAS,CAAC;CACzC;AAKD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAExD;AAMD,+FAA6F;AAC7F,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG;IAAE,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAE,CAM7F;AAkDD,wBAAsB,2BAA2B,CAAC,OAAO,EAAE;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,SAAS,CAAC;CAClB,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAsCvC","sourcesContent":["/**\n * OAuth discovery for MCP servers: the `WWW-Authenticate` challenge, protected-resource\n * metadata (RFC 9728), and authorization-server metadata (RFC 8414), in the order the\n * MCP authorization spec expects.\n *\n * Metadata URLs must be https. The one exception is loopback, because the authorization\n * code flow itself speaks loopback http and local development servers ride on it.\n */\n\nexport type FetchLike = typeof fetch;\n\nexport class OAuthDiscoveryError extends Error {}\n\nexport interface AuthorizationServerMetadata {\n\tauthorizationEndpoint: string;\n\ttokenEndpoint: string;\n\tregistrationEndpoint: string | undefined;\n}\n\nconst PRM_WELL_KNOWN = \".well-known/oauth-protected-resource\";\nconst AS_WELL_KNOWN = \".well-known/oauth-authorization-server\";\n\nexport function oauthErrorMessage(error: unknown): string {\n\treturn error instanceof Error ? error.message : String(error);\n}\n\nfunction isLoopback(url: URL): boolean {\n\treturn url.hostname === \"127.0.0.1\" || url.hostname === \"localhost\" || url.hostname === \"::1\";\n}\n\n/** Pulls `resource_metadata` out of a `WWW-Authenticate: Bearer …` challenge, if present. */\nexport function parseWwwAuthenticate(value: string | undefined): { resourceMetadata?: string } {\n\tif (!value) return {};\n\tconst challenge = /^Bearer\\s+(.*)$/i.exec(value.trim());\n\tif (!challenge) return {};\n\tconst resourceMetadata = /resource_metadata\\s*=\\s*\"([^\"]+)\"/i.exec(challenge[1])?.[1];\n\treturn resourceMetadata ? { resourceMetadata } : {};\n}\n\n/** RFC 9728: the well-known URI is inserted before the path, with the bare origin as fallback. */\nfunction wellKnownUrls(resource: URL, suffix: string): URL[] {\n\tconst pathAware = new URL(resource);\n\tpathAware.pathname = `/${suffix}${resource.pathname === \"/\" ? \"\" : resource.pathname}`;\n\tconst origin = new URL(resource);\n\torigin.pathname = `/${suffix}`;\n\treturn [pathAware, origin];\n}\n\nasync function fetchJson(url: URL, fetch: FetchLike): Promise<Record<string, unknown>> {\n\tif (url.protocol !== \"https:\" && !isLoopback(url)) {\n\t\tthrow new OAuthDiscoveryError(`OAuth metadata URLs must be https (loopback excepted): ${url}`);\n\t}\n\tlet response: Response;\n\ttry {\n\t\tresponse = await fetch(url, { redirect: \"error\" });\n\t} catch (error) {\n\t\tthrow new OAuthDiscoveryError(`could not fetch OAuth metadata from ${url}: ${oauthErrorMessage(error)}`);\n\t}\n\tif (!response.ok) throw new OAuthDiscoveryError(`OAuth metadata at ${url} answered HTTP ${response.status}`);\n\ttry {\n\t\tconst parsed: unknown = await response.json();\n\t\tif (typeof parsed !== \"object\" || parsed === null) throw new Error(\"not an object\");\n\t\treturn parsed as Record<string, unknown>;\n\t} catch {\n\t\tthrow new OAuthDiscoveryError(`OAuth metadata at ${url} is not a JSON object`);\n\t}\n}\n\nfunction requireEndpoint(metadata: Record<string, unknown>, key: string, label: string): string {\n\tconst value = metadata[key];\n\tif (typeof value !== \"string\" || value === \"\") {\n\t\tthrow new OAuthDiscoveryError(`authorization server metadata is missing ${label}`);\n\t}\n\treturn value;\n}\n\nfunction toAuthorizationServerMetadata(raw: Record<string, unknown>): AuthorizationServerMetadata {\n\treturn {\n\t\tauthorizationEndpoint: requireEndpoint(raw, \"authorization_endpoint\", \"an authorization endpoint\"),\n\t\ttokenEndpoint: requireEndpoint(raw, \"token_endpoint\", \"a token endpoint\"),\n\t\tregistrationEndpoint:\n\t\t\ttypeof raw.registration_endpoint === \"string\" && raw.registration_endpoint !== \"\"\n\t\t\t\t? raw.registration_endpoint\n\t\t\t\t: undefined,\n\t};\n}\n\nexport async function discoverAuthorizationServer(options: {\n\tserverUrl: string;\n\twwwAuthenticate?: string;\n\tfetch?: FetchLike;\n}): Promise<AuthorizationServerMetadata> {\n\tconst fetch = options.fetch ?? globalThis.fetch;\n\tconst serverUrl = new URL(options.serverUrl);\n\tif (serverUrl.protocol !== \"https:\" && !isLoopback(serverUrl)) {\n\t\tthrow new OAuthDiscoveryError(`an OAuth-protected MCP server must be https or loopback: ${options.serverUrl}`);\n\t}\n\n\tlet authorizationServers: URL[] = [];\n\tconst fromChallenge = parseWwwAuthenticate(options.wwwAuthenticate).resourceMetadata;\n\tconst prmCandidates = fromChallenge ? [new URL(fromChallenge)] : wellKnownUrls(serverUrl, PRM_WELL_KNOWN);\n\tfor (const candidate of prmCandidates) {\n\t\ttry {\n\t\t\tconst prm = await fetchJson(candidate, fetch);\n\t\t\tif (Array.isArray(prm.authorization_servers)) {\n\t\t\t\tauthorizationServers = prm.authorization_servers\n\t\t\t\t\t.filter((entry): entry is string => typeof entry === \"string\")\n\t\t\t\t\t.map((entry) => new URL(entry));\n\t\t\t\tbreak;\n\t\t\t}\n\t\t} catch (error) {\n\t\t\t// An explicit challenge URL is the server speaking; do not silently skip it.\n\t\t\tif (fromChallenge !== undefined && candidate.href === fromChallenge) throw error;\n\t\t}\n\t}\n\n\tconst asCandidates = authorizationServers.length > 0 ? authorizationServers : [serverUrl];\n\tlet lastError: unknown;\n\tfor (const candidate of asCandidates) {\n\t\ttry {\n\t\t\tconst wellKnown = new URL(`/${AS_WELL_KNOWN}`, candidate.origin);\n\t\t\treturn toAuthorizationServerMetadata(await fetchJson(wellKnown, fetch));\n\t\t} catch (error) {\n\t\t\tlastError = error;\n\t\t}\n\t}\n\tthrow lastError instanceof OAuthDiscoveryError\n\t\t? lastError\n\t\t: new OAuthDiscoveryError(`no authorization server metadata found for ${options.serverUrl}`);\n}\n"]}

package/dist/core/mcp/oauth/discover.js

@@ -0,0 +1,116 @@
+/**
+ * OAuth discovery for MCP servers: the `WWW-Authenticate` challenge, protected-resource
+ * metadata (RFC 9728), and authorization-server metadata (RFC 8414), in the order the
+ * MCP authorization spec expects.
+ *
+ * Metadata URLs must be https. The one exception is loopback, because the authorization
+ * code flow itself speaks loopback http and local development servers ride on it.
+ */
+export class OAuthDiscoveryError extends Error {
+}
+const PRM_WELL_KNOWN = ".well-known/oauth-protected-resource";
+const AS_WELL_KNOWN = ".well-known/oauth-authorization-server";
+export function oauthErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function isLoopback(url) {
+    return url.hostname === "127.0.0.1" || url.hostname === "localhost" || url.hostname === "::1";
+}
+/** Pulls `resource_metadata` out of a `WWW-Authenticate: Bearer …` challenge, if present. */
+export function parseWwwAuthenticate(value) {
+    if (!value)
+        return {};
+    const challenge = /^Bearer\s+(.*)$/i.exec(value.trim());
+    if (!challenge)
+        return {};
+    const resourceMetadata = /resource_metadata\s*=\s*"([^"]+)"/i.exec(challenge[1])?.[1];
+    return resourceMetadata ? { resourceMetadata } : {};
+}
+/** RFC 9728: the well-known URI is inserted before the path, with the bare origin as fallback. */
+function wellKnownUrls(resource, suffix) {
+    const pathAware = new URL(resource);
+    pathAware.pathname = `/${suffix}${resource.pathname === "/" ? "" : resource.pathname}`;
+    const origin = new URL(resource);
+    origin.pathname = `/${suffix}`;
+    return [pathAware, origin];
+}
+async function fetchJson(url, fetch) {
+    if (url.protocol !== "https:" && !isLoopback(url)) {
+        throw new OAuthDiscoveryError(`OAuth metadata URLs must be https (loopback excepted): ${url}`);
+    }
+    let response;
+    try {
+        response = await fetch(url, { redirect: "error" });
+    }
+    catch (error) {
+        throw new OAuthDiscoveryError(`could not fetch OAuth metadata from ${url}: ${oauthErrorMessage(error)}`);
+    }
+    if (!response.ok)
+        throw new OAuthDiscoveryError(`OAuth metadata at ${url} answered HTTP ${response.status}`);
+    try {
+        const parsed = await response.json();
+        if (typeof parsed !== "object" || parsed === null)
+            throw new Error("not an object");
+        return parsed;
+    }
+    catch {
+        throw new OAuthDiscoveryError(`OAuth metadata at ${url} is not a JSON object`);
+    }
+}
+function requireEndpoint(metadata, key, label) {
+    const value = metadata[key];
+    if (typeof value !== "string" || value === "") {
+        throw new OAuthDiscoveryError(`authorization server metadata is missing ${label}`);
+    }
+    return value;
+}
+function toAuthorizationServerMetadata(raw) {
+    return {
+        authorizationEndpoint: requireEndpoint(raw, "authorization_endpoint", "an authorization endpoint"),
+        tokenEndpoint: requireEndpoint(raw, "token_endpoint", "a token endpoint"),
+        registrationEndpoint: typeof raw.registration_endpoint === "string" && raw.registration_endpoint !== ""
+            ? raw.registration_endpoint
+            : undefined,
+    };
+}
+export async function discoverAuthorizationServer(options) {
+    const fetch = options.fetch ?? globalThis.fetch;
+    const serverUrl = new URL(options.serverUrl);
+    if (serverUrl.protocol !== "https:" && !isLoopback(serverUrl)) {
+        throw new OAuthDiscoveryError(`an OAuth-protected MCP server must be https or loopback: ${options.serverUrl}`);
+    }
+    let authorizationServers = [];
+    const fromChallenge = parseWwwAuthenticate(options.wwwAuthenticate).resourceMetadata;
+    const prmCandidates = fromChallenge ? [new URL(fromChallenge)] : wellKnownUrls(serverUrl, PRM_WELL_KNOWN);
+    for (const candidate of prmCandidates) {
+        try {
+            const prm = await fetchJson(candidate, fetch);
+            if (Array.isArray(prm.authorization_servers)) {
+                authorizationServers = prm.authorization_servers
+                    .filter((entry) => typeof entry === "string")
+                    .map((entry) => new URL(entry));
+                break;
+            }
+        }
+        catch (error) {
+            // An explicit challenge URL is the server speaking; do not silently skip it.
+            if (fromChallenge !== undefined && candidate.href === fromChallenge)
+                throw error;
+        }
+    }
+    const asCandidates = authorizationServers.length > 0 ? authorizationServers : [serverUrl];
+    let lastError;
+    for (const candidate of asCandidates) {
+        try {
+            const wellKnown = new URL(`/${AS_WELL_KNOWN}`, candidate.origin);
+            return toAuthorizationServerMetadata(await fetchJson(wellKnown, fetch));
+        }
+        catch (error) {
+            lastError = error;
+        }
+    }
+    throw lastError instanceof OAuthDiscoveryError
+        ? lastError
+        : new OAuthDiscoveryError(`no authorization server metadata found for ${options.serverUrl}`);
+}
+//# sourceMappingURL=discover.js.map

package/dist/core/mcp/oauth/discover.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover.js","sourceRoot":"","sources":["../../../../src/core/mcp/oauth/discover.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * OAuth discovery for MCP servers: the `WWW-Authenticate` challenge, protected-resource\n * metadata (RFC 9728), and authorization-server metadata (RFC 8414), in the order the\n * MCP authorization spec expects.\n *\n * Metadata URLs must be https. The one exception is loopback, because the authorization\n * code flow itself speaks loopback http and local development servers ride on it.\n */\n\nexport type FetchLike = typeof fetch;\n\nexport class OAuthDiscoveryError extends Error {}\n\nexport interface AuthorizationServerMetadata {\n\tauthorizationEndpoint: string;\n\ttokenEndpoint: string;\n\tregistrationEndpoint: string | undefined;\n}\n\nconst PRM_WELL_KNOWN = \".well-known/oauth-protected-resource\";\nconst AS_WELL_KNOWN = \".well-known/oauth-authorization-server\";\n\nexport function oauthErrorMessage(error: unknown): string {\n\treturn error instanceof Error ? error.message : String(error);\n}\n\nfunction isLoopback(url: URL): boolean {\n\treturn url.hostname === \"127.0.0.1\" || url.hostname === \"localhost\" || url.hostname === \"::1\";\n}\n\n/** Pulls `resource_metadata` out of a `WWW-Authenticate: Bearer …` challenge, if present. */\nexport function parseWwwAuthenticate(value: string | undefined): { resourceMetadata?: string } {\n\tif (!value) return {};\n\tconst challenge = /^Bearer\\s+(.*)$/i.exec(value.trim());\n\tif (!challenge) return {};\n\tconst resourceMetadata = /resource_metadata\\s*=\\s*\"([^\"]+)\"/i.exec(challenge[1])?.[1];\n\treturn resourceMetadata ? { resourceMetadata } : {};\n}\n\n/** RFC 9728: the well-known URI is inserted before the path, with the bare origin as fallback. */\nfunction wellKnownUrls(resource: URL, suffix: string): URL[] {\n\tconst pathAware = new URL(resource);\n\tpathAware.pathname = `/${suffix}${resource.pathname === \"/\" ? \"\" : resource.pathname}`;\n\tconst origin = new URL(resource);\n\torigin.pathname = `/${suffix}`;\n\treturn [pathAware, origin];\n}\n\nasync function fetchJson(url: URL, fetch: FetchLike): Promise<Record<string, unknown>> {\n\tif (url.protocol !== \"https:\" && !isLoopback(url)) {\n\t\tthrow new OAuthDiscoveryError(`OAuth metadata URLs must be https (loopback excepted): ${url}`);\n\t}\n\tlet response: Response;\n\ttry {\n\t\tresponse = await fetch(url, { redirect: \"error\" });\n\t} catch (error) {\n\t\tthrow new OAuthDiscoveryError(`could not fetch OAuth metadata from ${url}: ${oauthErrorMessage(error)}`);\n\t}\n\tif (!response.ok) throw new OAuthDiscoveryError(`OAuth metadata at ${url} answered HTTP ${response.status}`);\n\ttry {\n\t\tconst parsed: unknown = await response.json();\n\t\tif (typeof parsed !== \"object\" || parsed === null) throw new Error(\"not an object\");\n\t\treturn parsed as Record<string, unknown>;\n\t} catch {\n\t\tthrow new OAuthDiscoveryError(`OAuth metadata at ${url} is not a JSON object`);\n\t}\n}\n\nfunction requireEndpoint(metadata: Record<string, unknown>, key: string, label: string): string {\n\tconst value = metadata[key];\n\tif (typeof value !== \"string\" || value === \"\") {\n\t\tthrow new OAuthDiscoveryError(`authorization server metadata is missing ${label}`);\n\t}\n\treturn value;\n}\n\nfunction toAuthorizationServerMetadata(raw: Record<string, unknown>): AuthorizationServerMetadata {\n\treturn {\n\t\tauthorizationEndpoint: requireEndpoint(raw, \"authorization_endpoint\", \"an authorization endpoint\"),\n\t\ttokenEndpoint: requireEndpoint(raw, \"token_endpoint\", \"a token endpoint\"),\n\t\tregistrationEndpoint:\n\t\t\ttypeof raw.registration_endpoint === \"string\" && raw.registration_endpoint !== \"\"\n\t\t\t\t? raw.registration_endpoint\n\t\t\t\t: undefined,\n\t};\n}\n\nexport async function discoverAuthorizationServer(options: {\n\tserverUrl: string;\n\twwwAuthenticate?: string;\n\tfetch?: FetchLike;\n}): Promise<AuthorizationServerMetadata> {\n\tconst fetch = options.fetch ?? globalThis.fetch;\n\tconst serverUrl = new URL(options.serverUrl);\n\tif (serverUrl.protocol !== \"https:\" && !isLoopback(serverUrl)) {\n\t\tthrow new OAuthDiscoveryError(`an OAuth-protected MCP server must be https or loopback: ${options.serverUrl}`);\n\t}\n\n\tlet authorizationServers: URL[] = [];\n\tconst fromChallenge = parseWwwAuthenticate(options.wwwAuthenticate).resourceMetadata;\n\tconst prmCandidates = fromChallenge ? [new URL(fromChallenge)] : wellKnownUrls(serverUrl, PRM_WELL_KNOWN);\n\tfor (const candidate of prmCandidates) {\n\t\ttry {\n\t\t\tconst prm = await fetchJson(candidate, fetch);\n\t\t\tif (Array.isArray(prm.authorization_servers)) {\n\t\t\t\tauthorizationServers = prm.authorization_servers\n\t\t\t\t\t.filter((entry): entry is string => typeof entry === \"string\")\n\t\t\t\t\t.map((entry) => new URL(entry));\n\t\t\t\tbreak;\n\t\t\t}\n\t\t} catch (error) {\n\t\t\t// An explicit challenge URL is the server speaking; do not silently skip it.\n\t\t\tif (fromChallenge !== undefined && candidate.href === fromChallenge) throw error;\n\t\t}\n\t}\n\n\tconst asCandidates = authorizationServers.length > 0 ? authorizationServers : [serverUrl];\n\tlet lastError: unknown;\n\tfor (const candidate of asCandidates) {\n\t\ttry {\n\t\t\tconst wellKnown = new URL(`/${AS_WELL_KNOWN}`, candidate.origin);\n\t\t\treturn toAuthorizationServerMetadata(await fetchJson(wellKnown, fetch));\n\t\t} catch (error) {\n\t\t\tlastError = error;\n\t\t}\n\t}\n\tthrow lastError instanceof OAuthDiscoveryError\n\t\t? lastError\n\t\t: new OAuthDiscoveryError(`no authorization server metadata found for ${options.serverUrl}`);\n}\n"]}