@corbits/mcp 0.3.1 → 0.4.0

package/dist/server.js

@@ -0,0 +1,406 @@
+import { errorPayload } from "./server/errors.js";
+import { createLegacyServer } from "./server/legacy.js";
+import { createResourceBudget } from "./protocol/resource-budget.js";
+import { validateMcpIdentity } from "./auth/contracts.js";
+import { MCP_PROTOCOL_VERSION, MCP_EXT_TASKS, MCP_EXT_SKILLS, methodDescriptor, validateExtensionSettings, negotiateExtensions, McpError, validateRequest, validateJsonRpcRequest, validateRequestHeaders, validateResult, validateNotification, record as protocolRecord, } from "./protocol/index.js";
+export { createTaskProviders, createSkillProviders, } from "./server/extensions.js";
+export { createToolProviders } from "./server/tools.js";
+const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value
+    : {};
+function methodAuthorization(provider, params) {
+    return provider.authorization
+        ? provider.authorization(params)
+        : { resource: provider.resource, action: provider.action };
+}
+/** Pairs a private discover check may satisfy. No providers means mcp:server/discover. */
+function discoverAuthorizations(providers) {
+    const pairs = [];
+    const seen = new Set();
+    for (const provider of Object.values(providers)) {
+        const listed = provider.authorizationPairs ?? [
+            { resource: provider.resource, action: provider.action },
+        ];
+        for (const pair of listed) {
+            const key = `${pair.resource}\0${pair.action}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            pairs.push(pair);
+        }
+    }
+    if (pairs.length === 0)
+        pairs.push({ resource: "mcp:server", action: "discover" });
+    return pairs;
+}
+/** Stateless modern endpoint with an independently gated legacy session transport. */
+export function createMcpServer(options) {
+    const providers = Object.freeze({ ...options.providers });
+    const extensions = validateExtensionSettings(options.extensions ?? {});
+    for (const [extension, methods] of [
+        [MCP_EXT_TASKS, ["tasks/get", "tasks/update", "tasks/cancel"]],
+        [MCP_EXT_SKILLS, ["skills/list", "skills/get", "resources/read"]],
+    ]) {
+        if (extensions[extension] && methods.some((method) => !providers[method]))
+            throw new Error(`Missing providers for ${extension}`);
+    }
+    if (extensions[MCP_EXT_SKILLS]?.directoryRead === true &&
+        !providers["resources/directory/read"])
+        throw new Error("Missing directory read provider");
+    const active = new Set();
+    let closed = false;
+    const capabilities = {};
+    for (const method of Object.keys(providers)) {
+        if (method === "server/discover")
+            throw new Error("Discovery is server-owned");
+        const descriptor = methodDescriptor(method);
+        if (!descriptor)
+            throw new Error(`Unknown provider method: ${method}`);
+        if (descriptor.extension && !options.extensions?.[descriptor.extension])
+            throw new Error(`Extension not enabled: ${descriptor.extension}`);
+        if (descriptor.capability)
+            capabilities[descriptor.capability] = {};
+        const family = method.split("/")[0];
+        if (family === "tools" || family === "prompts" || family === "resources")
+            capabilities[family] = {};
+        if (family === "completion")
+            capabilities.completions = {};
+    }
+    if (Object.keys(extensions).length)
+        capabilities.extensions = extensions;
+    const legacy = options.legacy
+        ? createLegacyServer(options, providers)
+        : undefined;
+    return {
+        async fetch(request) {
+            const origin = request.headers.get("origin");
+            if (origin && !options.allowedOrigins?.includes(origin))
+                return new Response(null, { status: 403 });
+            if (closed)
+                return new Response(null, { status: 503 });
+            if (request.method !== "POST") {
+                if (legacy &&
+                    request.headers.get("MCP-Protocol-Version") !==
+                        MCP_PROTOCOL_VERSION &&
+                    (request.method === "DELETE" || request.headers.has("Mcp-Session-Id")))
+                    return legacy.lifecycle(request);
+                return new Response(null, { status: 405, headers: { Allow: "POST" } });
+            }
+            if (request.headers.get("content-type")?.split(";")[0]?.trim() !==
+                "application/json")
+                return new Response(null, { status: 415 });
+            const accept = request.headers.get("accept") ?? "";
+            if (!accept.includes("application/json") ||
+                !accept.includes("text/event-stream"))
+                return new Response(null, { status: 406 });
+            let id;
+            try {
+                const authenticated = options.auth === "public"
+                    ? null
+                    : await options.auth.authenticate(request);
+                if (closed)
+                    return new Response(null, { status: 503 });
+                if (options.auth !== "public" && !authenticated)
+                    return (options.challenge?.(401) ?? new Response(null, { status: 401 }));
+                const identity = authenticated === null ? null : validateMcpIdentity(authenticated);
+                const limit = options.maxRequestBytes ?? 1024 * 1024;
+                const reader = request.body?.getReader();
+                if (!reader)
+                    throw new McpError("Missing request body", 400, -32600);
+                const chunks = [];
+                let size = 0;
+                while (true) {
+                    const chunk = await reader.read();
+                    if (chunk.done)
+                        break;
+                    size += chunk.value.byteLength;
+                    if (size > limit) {
+                        await reader.cancel();
+                        throw new McpError("Request too large", 413, -32600);
+                    }
+                    chunks.push(chunk.value);
+                }
+                const bytes = new Uint8Array(size);
+                let offset = 0;
+                for (const chunk of chunks) {
+                    bytes.set(chunk, offset);
+                    offset += chunk.byteLength;
+                }
+                let parsed;
+                try {
+                    parsed = JSON.parse(new TextDecoder().decode(bytes));
+                }
+                catch {
+                    throw new McpError("Invalid JSON", 400, -32700);
+                }
+                const readableId = record(parsed).id;
+                if (typeof readableId === "string" ||
+                    (typeof readableId === "number" && Number.isSafeInteger(readableId)))
+                    id = readableId;
+                const compatibility = await legacy?.handle(request, parsed, identity);
+                if (closed)
+                    return new Response(null, { status: 503 });
+                if (compatibility)
+                    return compatibility;
+                const envelope = validateJsonRpcRequest(parsed);
+                id = envelope.id;
+                const params = record(envelope.params);
+                const meta = record(params._meta);
+                if (envelope.method !== "server/discover") {
+                    const gated = providers[envelope.method];
+                    if (gated) {
+                        const pair = methodAuthorization(gated, params);
+                        if (pair !== null && options.auth !== "public" && identity) {
+                            const permitted = pair !== false &&
+                                (await options.auth.authorize(identity, pair));
+                            if (closed)
+                                return new Response(null, { status: 503 });
+                            if (!permitted)
+                                return (options.challenge?.(403) ??
+                                    new Response(null, { status: 403 }));
+                        }
+                    }
+                }
+                const validation = {
+                    era: "modern",
+                    protocolVersion: MCP_PROTOCOL_VERSION,
+                    clientCapabilities: record(meta["io.modelcontextprotocol/clientCapabilities"]),
+                    serverCapabilities: capabilities,
+                    extensions: negotiateExtensions(extensions, record(record(meta["io.modelcontextprotocol/clientCapabilities"])
+                        .extensions)),
+                    ...providers[envelope.method]?.schemas?.(params),
+                    // Explicit Skills publication supports bounded resource payloads only.
+                    maxDecodedBytes: envelope.method === "resources/read" && extensions[MCP_EXT_SKILLS]
+                        ? 16 * 1024 * 1024
+                        : undefined,
+                };
+                validateRequestHeaders(request.headers, envelope.method, params, validation);
+                validateRequest(envelope.method, params, validation);
+                if (envelope.method === "server/discover") {
+                    if (options.auth !== "public") {
+                        let permitted = false;
+                        for (const pair of discoverAuthorizations(providers)) {
+                            if (identity && (await options.auth.authorize(identity, pair))) {
+                                permitted = true;
+                                break;
+                            }
+                        }
+                        if (closed)
+                            return new Response(null, { status: 503 });
+                        if (!permitted)
+                            return (options.challenge?.(403) ?? new Response(null, { status: 403 }));
+                    }
+                    const result = validateResult(envelope.method, {
+                        resultType: "complete",
+                        supportedVersions: [
+                            MCP_PROTOCOL_VERSION,
+                            ...(legacy?.versions ?? []),
+                        ],
+                        capabilities,
+                        _meta: {
+                            "io.modelcontextprotocol/serverInfo": options.serverInfo,
+                        },
+                    }, validation);
+                    return Response.json({ jsonrpc: "2.0", id, result }, { headers: { "Cache-Control": "no-store" } });
+                }
+                const provider = providers[envelope.method];
+                if (!provider)
+                    throw new McpError("Method not found", 404, -32601);
+                const controller = new AbortController();
+                active.add(controller);
+                const abort = () => controller.abort(request.signal.reason);
+                request.signal.addEventListener("abort", abort, { once: true });
+                if (request.signal.aborted)
+                    abort();
+                const requestId = id;
+                const subscription = envelope.method === "subscriptions/listen";
+                let acceptedFilter;
+                const correlate = (payload) => subscription
+                    ? {
+                        ...payload,
+                        _meta: {
+                            ...(payload._meta === undefined
+                                ? {}
+                                : protocolRecord(payload._meta)),
+                            "io.modelcontextprotocol/subscriptionId": requestId,
+                        },
+                    }
+                    : payload;
+                let ended = false;
+                let lastProgress = -Infinity;
+                const encoder = new TextEncoder();
+                const stream = new ReadableStream({
+                    start(sink) {
+                        const send = (message) => {
+                            if (!ended) {
+                                const wire = encoder.encode(`data: ${JSON.stringify(message)}\n\n`);
+                                if (validation.maxDecodedBytes !== undefined &&
+                                    record(message).result !== undefined) {
+                                    const budget = createResourceBudget(validation.maxDecodedBytes, true);
+                                    budget.push(wire);
+                                    budget.finish();
+                                }
+                                sink.enqueue(wire);
+                            }
+                        };
+                        const finish = () => {
+                            if (!ended) {
+                                ended = true;
+                                sink.close();
+                            }
+                        };
+                        controller.signal.addEventListener("abort", finish, { once: true });
+                        if (controller.signal.aborted)
+                            finish();
+                        const context = {
+                            identity,
+                            auth: options.auth,
+                            requestId,
+                            protocolVersion: MCP_PROTOCOL_VERSION,
+                            clientCapabilities: validation.clientCapabilities ?? {},
+                            signal: controller.signal,
+                            reportProgress(progress, total, message) {
+                                const token = meta.progressToken;
+                                if (subscription ||
+                                    token === undefined ||
+                                    controller.signal.aborted)
+                                    return;
+                                if (progress <= lastProgress)
+                                    throw new McpError("Progress must increase", 500, -32603);
+                                const notification = {
+                                    progressToken: token,
+                                    progress,
+                                    ...(total === undefined ? {} : { total }),
+                                    ...(message === undefined ? {} : { message }),
+                                };
+                                validateNotification("notifications/progress", notification, validation);
+                                lastProgress = progress;
+                                send({
+                                    jsonrpc: "2.0",
+                                    method: "notifications/progress",
+                                    params: notification,
+                                });
+                            },
+                            notify(method, notification) {
+                                if (envelope.method !== "subscriptions/listen")
+                                    throw new Error("Change notifications require subscriptions/listen");
+                                if (acceptedFilter === undefined)
+                                    throw new Error("Subscription is not yet acknowledged");
+                                const outgoing = correlate(notification);
+                                validateNotification(method, outgoing, validation);
+                                const filter = acceptedFilter;
+                                const listFlag = {
+                                    "notifications/tools/list_changed": "toolsListChanged",
+                                    "notifications/prompts/list_changed": "promptsListChanged",
+                                    "notifications/resources/list_changed": "resourcesListChanged",
+                                }[method];
+                                const permitted = listFlag
+                                    ? filter[listFlag] === true
+                                    : method === "notifications/resources/updated"
+                                        ? Array.isArray(filter.resourceSubscriptions) &&
+                                            filter.resourceSubscriptions.includes(String(notification.uri))
+                                        : method === "notifications/tasks"
+                                            ? Array.isArray(filter.taskIds) &&
+                                                filter.taskIds.includes(String(notification.taskId))
+                                            : false;
+                                if (!permitted)
+                                    return;
+                                send({ jsonrpc: "2.0", method, params: outgoing });
+                            },
+                        };
+                        void Promise.resolve()
+                            .then(async () => {
+                            controller.signal.throwIfAborted();
+                            if (subscription) {
+                                const requested = structuredClone(record(params.notifications));
+                                const accepted = structuredClone((await provider.acceptSubscription?.(params, context)) ??
+                                    {});
+                                controller.signal.throwIfAborted();
+                                const acknowledged = correlate({ notifications: accepted });
+                                validateNotification("notifications/subscriptions/acknowledged", acknowledged, validation);
+                                for (const [key, value] of Object.entries(accepted)) {
+                                    const wanted = requested[key];
+                                    if (Array.isArray(value)
+                                        ? !Array.isArray(wanted) ||
+                                            value.some((item) => !wanted.includes(item))
+                                        : value === true && wanted !== true) {
+                                        throw new McpError("Accepted subscription exceeds requested filter", 500, -32603);
+                                    }
+                                }
+                                acceptedFilter = accepted;
+                                send({
+                                    jsonrpc: "2.0",
+                                    method: "notifications/subscriptions/acknowledged",
+                                    params: acknowledged,
+                                });
+                            }
+                            return provider.handle(params, context);
+                        })
+                            .then((result) => {
+                            const outgoing = {
+                                jsonrpc: "2.0",
+                                id: requestId,
+                                result: validateResult(envelope.method, correlate({
+                                    ...protocolRecord(result),
+                                    resultType: result.resultType === undefined
+                                        ? "complete"
+                                        : result.resultType,
+                                }), validation),
+                            };
+                            send(outgoing);
+                        })
+                            .catch((error) => {
+                            send({
+                                jsonrpc: "2.0",
+                                id: requestId,
+                                error: errorPayload(error, "Provider execution failed"),
+                            });
+                        })
+                            .finally(() => {
+                            active.delete(controller);
+                            request.signal.removeEventListener("abort", abort);
+                            controller.signal.removeEventListener("abort", finish);
+                            finish();
+                        });
+                    },
+                    cancel(reason) {
+                        ended = true;
+                        controller.abort(reason);
+                        active.delete(controller);
+                        request.signal.removeEventListener("abort", abort);
+                    },
+                });
+                return new Response(stream, {
+                    headers: {
+                        "Content-Type": "text/event-stream",
+                        "Cache-Control": "no-store",
+                        "X-Accel-Buffering": "no",
+                    },
+                });
+            }
+            catch (error) {
+                const known = error instanceof McpError;
+                return Response.json({
+                    jsonrpc: "2.0",
+                    ...(id === undefined ? {} : { id }),
+                    error: errorPayload(error, "Request failed"),
+                }, {
+                    status: known
+                        ? (error.status ?? (error.code === -32601 ? 404 : 400))
+                        : 500,
+                    headers: { "Cache-Control": "no-store" },
+                });
+            }
+        },
+        async close() {
+            closed = true;
+            legacy?.close();
+            for (const controller of active)
+                controller.abort();
+            active.clear();
+        },
+    };
+}
+export { createSkillPublisher } from "./extensions/skills/index.js";
+export { createTaskRuntime, validateTaskRecord, } from "./extensions/tasks/index.js";
+export { createMcpResourceServerAuth } from "./auth/resource-server.js";

package/dist/sidecar-bundle.d.ts

@@ -1,5 +1,7 @@
 import { type AnnotatedToolFactory, type BaseEnv } from "@intx/agent";
 import { type McpTool } from "./client.js";
+import type { McpHostServices } from "./interchange/client/contracts.js";
+export { shapeMcpContent } from "./interchange/client/projection.js";
 /** The consumer key a host matches a credential binding against. */
 export declare const SIDECAR_BUNDLE_ID = "@corbits/mcp/sidecar-bundle";
 type MediatedFetch = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
@@ -32,19 +34,17 @@ export interface McpBoundServer {
     readonly allowWithoutAsk?: readonly string[];
 }
 export interface McpServersConfig {
+    /** Explicit host lifecycle and presentation services. */
+    readonly host?: McpHostServices;
     readonly servers: readonly McpBoundServer[];
-    /** Per-request bound on `initialize` and `tools/call`; defaults to 60s. */
+    /** Per-request bound on connect and `tools/call`; defaults to 60s. */
     readonly timeoutMs?: number;
+    /** Extension ids advertised on every request. Off unless listed. */
+    readonly extensions?: readonly string[];
 }
-/**
- * MCP results are never interpreted: text blocks come back as their text so
- * the model reads prose, and anything else is handed over verbatim as JSON.
- */
-export declare function shapeMcpContent(content: unknown): string;
 /**
  * The sidecar bundle: one `@intx/agent` tool per catalog entry, named
  * `<handle>.<tool>` so each is grantable on its own. Synchronous, with
  * static definitions — the catalog is already in hand.
  */
 export declare function mcpServers(config: McpServersConfig): AnnotatedToolFactory<McpServersEnv>;
-export {};

package/dist/sidecar-bundle.js

@@ -11,8 +11,11 @@
 // point at which this bundle could do a `tools/list` round trip.
 import { defineTool, } from "@intx/agent";
 import { type } from "arktype";
-import { DEFAULT_TIMEOUT_MS, mcpCallTool, mcpInitialize, McpToolSchema, } from "./client.js";
-import { assertCatalogNames, assertServers, isAskExempt, qualifiedName, toolDescription, } from "./naming.js";
+import { DEFAULT_TIMEOUT_MS, mcpCallTool, mcpConnect, McpToolSchema, } from "./client.js";
+import { assertCatalogNames, assertServers, isAskExempt, isModelVisible, qualifiedName, toolDescription, } from "./naming.js";
+import { assertHostExtensions, hostClientOptions, } from "./interchange/client/capabilities.js";
+import { projectToolResult } from "./interchange/client/projection.js";
+export { shapeMcpContent } from "./interchange/client/projection.js";
 /** The consumer key a host matches a credential binding against. */
 export const SIDECAR_BUNDLE_ID = "@corbits/mcp/sidecar-bundle";
 const BoundServerSchema = type({
@@ -24,6 +27,7 @@ const BoundServerSchema = type({
 const ConfigSchema = type({
     servers: BoundServerSchema.array(),
     "timeoutMs?": "number > 0",
+    "extensions?": "string[]",
 });
 /** Validate at construction: a malformed deploy config is a deploy bug, not a
  * tool error the model should see. */
@@ -42,20 +46,6 @@ function assertConfig(config) {
         throw new Error(`invalid @corbits/mcp server config: ${cause instanceof Error ? cause.message : String(cause)}`);
     }
 }
-const TextBlock = type({ type: "'text'", text: "string" }).array();
-/**
- * MCP results are never interpreted: text blocks come back as their text so
- * the model reads prose, and anything else is handed over verbatim as JSON.
- */
-export function shapeMcpContent(content) {
-    if (typeof content === "string")
-        return content;
-    const blocks = TextBlock(content);
-    if (!(blocks instanceof type.errors)) {
-        return blocks.map((block) => block.text).join("\n");
-    }
-    return JSON.stringify(content);
-}
 /** A mediated handle resolves a relative path against the origin it is pinned
  * to, so the bundle passes the server's path and never names a host. */
 function requestPath(url) {
@@ -70,9 +60,10 @@ function requestPath(url) {
 export function mcpServers(config) {
     assertConfig(config);
     const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-    const entries = config.servers.flatMap((server) => server.tools.map((tool) => ({
-        server,
-        tool,
+    assertHostExtensions(config.extensions, config.host);
+    const entries = config.servers.flatMap((server) => server.tools.filter(isModelVisible).map((tool) => ({
+        server: { ...server },
+        tool: structuredClone(tool),
         qualified: qualifiedName(server.handle, tool.name),
     })));
     const definitions = entries.map(({ qualified, tool, server }) => ({
@@ -108,11 +99,16 @@ export function mcpServers(config) {
                         throw new Error(`the "${runtime.server.handle}" credential is a ${credential.kind} handle; an MCP server needs an http one`);
                     }
                     const mediated = (input, init) => credential.fetch(input, init);
-                    const session = await mcpInitialize(requestPath(runtime.server.url), {
+                    const opts = {
                         fetch: mediated,
                         timeoutMs,
-                    });
-                    return { fetch: mediated, session };
+                        ...hostClientOptions(config.host, config.extensions),
+                        ...(config.extensions !== undefined
+                            ? { extensions: config.extensions }
+                            : {}),
+                    };
+                    const session = await mcpConnect(requestPath(runtime.server.url), opts);
+                    return { ...opts, session };
                 })().catch((cause) => {
                     runtime.ready = undefined;
                     runtime.handle = undefined;
@@ -133,17 +129,28 @@ export function mcpServers(config) {
                         };
                     }
                     try {
-                        const client = await connect(runtime);
-                        const result = await mcpCallTool(requestPath(found.server.url), found.tool.name, call.arguments, { ...client, timeoutMs, signal }).catch((cause) => {
+                        const context = {
+                            server: found.server.handle,
+                            url: requestPath(found.server.url),
+                            tool: found.qualified,
+                            callId: call.id,
+                            signal,
+                        };
+                        await config.host?.validateCatalog?.(context, found.tool);
+                        const client = {
+                            ...(await connect(runtime)),
+                            signal,
+                            inputSchema: found.tool.inputSchema,
+                            ...(found.tool.outputSchema === undefined
+                                ? {}
+                                : { outputSchema: found.tool.outputSchema }),
+                        };
+                        const result = await mcpCallTool(requestPath(found.server.url), found.tool.name, call.arguments, client).catch((cause) => {
                             // The session may have expired; the next call opens a new one.
                             runtime.ready = undefined;
                             throw cause;
                         });
-                        return {
-                            callId: call.id,
-                            isError: result.isError === true,
-                            content: shapeMcpContent(result.content),
-                        };
+                        return await projectToolResult(context, result, client, config.host);
                     }
                     catch (cause) {
                         // One server's failure is that server's tool error, never the

package/dist/test-server.js

@@ -72,12 +72,21 @@ export function startTestMcpServer(opts = {}) {
                     return new Response("bad request", { status: 400 });
                 }
                 if (params.name === "echo") {
-                    return reply({ content: params.arguments.text });
+                    return reply({
+                        content: [{ type: "text", text: String(params.arguments.text) }],
+                    });
                 }
                 if (params.name === "delete_thing") {
-                    return reply({ content: `deleted ${String(params.arguments.id)}` });
+                    return reply({
+                        content: [
+                            { type: "text", text: `deleted ${String(params.arguments.id)}` },
+                        ],
+                    });
                 }
-                return reply({ content: `unknown tool ${params.name}`, isError: true });
+                return reply({
+                    content: [{ type: "text", text: `unknown tool ${params.name}` }],
+                    isError: true,
+                });
             }
             return new Response("not found", { status: 404 });
         },

package/dist/tool.d.ts

@@ -1,5 +1,6 @@
 import { type AnnotatedToolFactory, type BaseEnv } from "@intx/agent";
 import type { CredentialCapability } from "@intx/types";
+import type { McpHostServices } from "./interchange/client/contracts.js";
 export interface McpServerConfig {
     /** Namespace prefix for this server's tools: `<name>.<remote-tool-name>`. */
     name: string;
@@ -17,6 +18,8 @@ export interface McpToolsEnv extends BaseEnv {
 }
 export interface McpToolsOptions {
     servers: McpServerConfig[];
+    /** Explicit host lifecycle and presentation services. */
+    host?: McpHostServices;
     /**
      * `<server>.<tool>` names allowed to float below the `ask` floor onto
      * `allow` from a resolved `allow` grant. Every generated tool starts
@@ -27,6 +30,11 @@ export interface McpToolsOptions {
     allowWithoutAsk?: string[];
     /** Per-request bound on every MCP round trip; defaults to 60s. */
     timeoutMs?: number;
+    /**
+     * Extension ids advertised on every request. Off unless listed. Tools stay
+     * the only grantable unit; extensions are not projected into tools.
+     */
+    extensions?: readonly string[];
 }
 /**
  * Discover every server's tool catalog and build the `@corbits/mcp` tool