@corbits/mcp 0.3.1 → 0.4.1

package/dist/server/legacy.js

@@ -0,0 +1,435 @@
+import { validateMcpIdentity } from "../auth/contracts.js";
+import { MCP_PROTOCOL_VERSION, McpError, validateLegacyInitialize, validateJsonRpcRequest, validateRequest, validateRequestHeaders, validateResult, validateNotification, record, } from "../protocol/index.js";
+import { errorPayload } from "./errors.js";
+const REVISIONS = [
+    "2025-11-25",
+    "2025-06-18",
+    "2025-03-26",
+];
+const METHODS = new Set([
+    "tools/list",
+    "tools/call",
+    "prompts/list",
+    "prompts/get",
+    "resources/list",
+    "resources/templates/list",
+    "resources/read",
+    "completion/complete",
+]);
+const json = (value, status = 200, headers = {}) => Response.json(value, {
+    status,
+    headers: { "Cache-Control": "no-store", ...headers },
+});
+const failed = (error, id) => ({
+    jsonrpc: "2.0",
+    id: id ?? null,
+    error: errorPayload(error, "Legacy request failed"),
+});
+const partition = (identity) => identity === null
+    ? "public"
+    : JSON.stringify([
+        identity.tenantId,
+        identity.principalId,
+        identity.authorizationContextId,
+    ]);
+/** Isolated legacy transport. No HTTP+SSE endpoint, GET stream, resumption, MRTR or extensions. */
+export function createLegacyServer(options, providers) {
+    const configured = options.legacy?.versions ?? REVISIONS;
+    if (!configured.length ||
+        configured.some((version) => !REVISIONS.includes(version)))
+        throw new Error("Unsupported legacy revision");
+    const versions = REVISIONS.filter((version) => configured.includes(version));
+    const ttl = options.legacy?.sessionTtlMs ?? 30 * 60_000;
+    const maxSessions = options.legacy?.maxSessions ?? 1024;
+    if (!Number.isSafeInteger(ttl) ||
+        ttl <= 0 ||
+        ttl > 2_147_483_647 ||
+        !Number.isSafeInteger(maxSessions) ||
+        maxSessions <= 0)
+        throw new Error("Invalid legacy session limits");
+    let closed = false;
+    function assertOpen() {
+        if (closed)
+            throw new McpError("Legacy server is closed", 503, -32603);
+    }
+    const sessions = new Map();
+    const capabilities = {};
+    for (const method of METHODS)
+        if (providers[method]) {
+            const family = method.split("/")[0];
+            capabilities[family === "completion" ? "completions" : family] = {};
+        }
+    function remove(id, session) {
+        session.closed = true;
+        clearTimeout(session.timer);
+        sessions.delete(id);
+        for (const controller of session.active.values())
+            controller.abort();
+        session.active.clear();
+    }
+    function lookup(request, identity) {
+        const id = request.headers.get("Mcp-Session-Id");
+        if (!id)
+            throw new McpError("Session ID required", 400, -32600);
+        const session = sessions.get(id);
+        if (session && session.expires <= Date.now())
+            remove(id, session);
+        if (!session ||
+            !sessions.has(id) ||
+            partition(session.identity) !== partition(identity))
+            throw new McpError("Session not found", 404, -32600);
+        const version = request.headers.get("MCP-Protocol-Version");
+        if ((version !== null && version !== session.version) ||
+            (version === null && session.version !== "2025-03-26"))
+            throw new McpError("Protocol version does not match session", 400, -32600);
+        return [id, session];
+    }
+    async function authorized(identity, resource, action) {
+        return (options.auth === "public" ||
+            (identity !== null &&
+                (await options.auth.authorize(identity, { resource, action }))));
+    }
+    function validation(session, method, params) {
+        return {
+            era: "legacy",
+            protocolVersion: session.version,
+            extensions: {},
+            clientCapabilities: session.capabilities,
+            serverCapabilities: capabilities,
+            ...providers[method]?.schemas?.(params),
+        };
+    }
+    function notification(message, session) {
+        const params = message.params ?? {};
+        if (message.method !== "notifications/initialized" &&
+            message.method !== "notifications/cancelled")
+            throw new McpError("Unsupported notification", 400, -32601);
+        validateNotification(message.method, params, {
+            era: "legacy",
+            extensions: {},
+        });
+        if (message.method === "notifications/initialized")
+            session.initialized = true;
+        else
+            session.active.get(params.requestId)?.abort();
+    }
+    async function run(message, request, session, identity, send) {
+        const id = message.id;
+        let controller;
+        let abortListener;
+        try {
+            if (session.used.has(id))
+                throw new McpError("Request ID already used in session", 400, -32600);
+            if (session.used.size >= 10_000)
+                throw new McpError("Session request limit reached; initialize a new session", 429, -32600);
+            session.used.add(id);
+            if (message.method === "ping")
+                return { jsonrpc: "2.0", id, result: {} };
+            if (!session.initialized)
+                throw new McpError("Session not initialized", 400, -32600);
+            if (!METHODS.has(message.method) || !providers[message.method])
+                throw new McpError("Method not available in legacy mode", 404, -32601);
+            const provider = providers[message.method];
+            const params = message.params ?? {};
+            const pair = provider.authorization
+                ? provider.authorization(params)
+                : { resource: provider.resource, action: provider.action };
+            controller = new AbortController();
+            session.active.set(id, controller);
+            if (session.expires <= Date.now() || session.closed)
+                controller.abort();
+            const signal = controller.signal;
+            signal.throwIfAborted();
+            const cancelled = new Promise((_resolve, reject) => {
+                abortListener = () => reject(new McpError("Request cancelled", undefined, -32603));
+                signal.addEventListener("abort", abortListener, { once: true });
+            });
+            if ((pair === false && options.auth !== "public") ||
+                (pair !== null &&
+                    pair !== false &&
+                    !(await Promise.race([
+                        authorized(identity, pair.resource, pair.action),
+                        cancelled,
+                    ]))))
+                throw new McpError("Operation forbidden", 403, -32602);
+            const context = validation(session, message.method, params);
+            validateRequest(message.method, params, context);
+            validateRequestHeaders(request.headers, message.method, params, context);
+            let lastProgress = -Infinity;
+            const providerContext = {
+                identity,
+                auth: options.auth,
+                requestId: id,
+                protocolVersion: session.version,
+                clientCapabilities: session.capabilities,
+                signal,
+                notify() {
+                    throw new McpError("Legacy change notifications are not supported", 400, -32601);
+                },
+                reportProgress(progress, total, message) {
+                    const token = params._meta === undefined
+                        ? undefined
+                        : record(params._meta).progressToken;
+                    if (token === undefined || 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, context);
+                    lastProgress = progress;
+                    send({
+                        jsonrpc: "2.0",
+                        method: "notifications/progress",
+                        params: notification,
+                    });
+                },
+            };
+            signal.throwIfAborted();
+            const result = await Promise.race([
+                Promise.resolve().then(() => {
+                    signal.throwIfAborted();
+                    return provider.handle(params, providerContext);
+                }),
+                cancelled,
+            ]);
+            const validated = validateResult(message.method, result, context);
+            // Ordinary results only; the shared validator rejects task/MRTR before projection.
+            const { resultType: _type, ttlMs: _ttl, cacheScope: _cache, ...ordinary } = validated;
+            if (session.version === "2025-03-26") {
+                // Structured tool output and resource links arrived in 2025-06-18.
+                // Preserve their information in text for March clients rather than emit
+                // a newer content discriminator or silently discard structured data.
+                const content = (value) => {
+                    const block = record(value);
+                    return block.type === "resource_link"
+                        ? {
+                            type: "text",
+                            text: `${String(block.name)}: ${String(block.uri)}`,
+                        }
+                        : block;
+                };
+                if (Array.isArray(ordinary.content)) {
+                    const compatibleContent = ordinary.content.map(content);
+                    if (ordinary.structuredContent !== undefined)
+                        compatibleContent.push({
+                            type: "text",
+                            text: JSON.stringify(ordinary.structuredContent),
+                        });
+                    ordinary.content = compatibleContent;
+                }
+                if (Array.isArray(ordinary.messages))
+                    ordinary.messages = ordinary.messages.map((value) => {
+                        const message = record(value);
+                        return { ...message, content: content(message.content) };
+                    });
+                delete ordinary.structuredContent;
+                if (Array.isArray(ordinary.tools))
+                    ordinary.tools = ordinary.tools.map((tool) => {
+                        const { outputSchema: _output, ...definition } = record(tool);
+                        return definition;
+                    });
+            }
+            return { jsonrpc: "2.0", id, result: ordinary };
+        }
+        catch (error) {
+            return failed(error, id);
+        }
+        finally {
+            if (controller && abortListener)
+                controller.signal.removeEventListener("abort", abortListener);
+            if (controller)
+                session.active.delete(id);
+        }
+    }
+    return {
+        versions,
+        async lifecycle(request) {
+            try {
+                assertOpen();
+                const rawIdentity = options.auth === "public"
+                    ? null
+                    : await options.auth.authenticate(request);
+                assertOpen();
+                if (options.auth !== "public" && !rawIdentity)
+                    return (options.challenge?.(401) ?? new Response(null, { status: 401 }));
+                const identity = rawIdentity === null ? null : validateMcpIdentity(rawIdentity);
+                const [id, session] = lookup(request, identity);
+                if (request.method === "DELETE") {
+                    remove(id, session);
+                    return new Response(null, { status: 204 });
+                }
+                return new Response(null, {
+                    status: 405,
+                    headers: { Allow: "POST, DELETE" },
+                });
+            }
+            catch (error) {
+                return json(failed(error), error instanceof McpError ? (error.status ?? 400) : 500);
+            }
+        },
+        async handle(request, body, identity) {
+            const entries = Array.isArray(body) ? body : [body];
+            const modern = request.headers.get("MCP-Protocol-Version") === MCP_PROTOCOL_VERSION ||
+                entries.some((entry) => {
+                    if (entry === null || typeof entry !== "object")
+                        return false;
+                    const params = entry.params;
+                    if (params === null || typeof params !== "object")
+                        return false;
+                    const meta = params._meta;
+                    return (meta !== null &&
+                        typeof meta === "object" &&
+                        meta["io.modelcontextprotocol/protocolVersion"] === MCP_PROTOCOL_VERSION);
+                });
+            if (modern)
+                return undefined;
+            const first = entries[0];
+            const initializing = first !== null &&
+                typeof first === "object" &&
+                first.method === "initialize";
+            if (!initializing &&
+                !request.headers.has("Mcp-Session-Id") &&
+                request.headers.has("Mcp-Method"))
+                return undefined;
+            let id;
+            try {
+                assertOpen();
+                if (initializing && !Array.isArray(body)) {
+                    const message = validateJsonRpcRequest(body);
+                    id = message.id;
+                    if (request.headers.has("Mcp-Session-Id"))
+                        throw new McpError("Initialize must start a new session", 400, -32600);
+                    const headerVersion = request.headers.get("MCP-Protocol-Version");
+                    if (headerVersion !== null &&
+                        !versions.some((version) => version === headerVersion))
+                        throw new McpError("Unsupported legacy protocol header", 400, -32600);
+                    const params = validateLegacyInitialize(message.params);
+                    const permitted = await authorized(identity, "mcp:server", "initialize");
+                    assertOpen();
+                    if (!permitted)
+                        return (options.challenge?.(403) ?? new Response(null, { status: 403 }));
+                    for (const [id, session] of sessions)
+                        if (session.expires <= Date.now())
+                            remove(id, session);
+                    if (sessions.size >= maxSessions)
+                        throw new McpError("Legacy session capacity reached", 503, -32603);
+                    const version = versions.find((version) => version === params.protocolVersion) ??
+                        versions[0];
+                    const sessionId = crypto.randomUUID();
+                    const session = {
+                        identity,
+                        version,
+                        capabilities: params.capabilities,
+                        initialized: false,
+                        closed: false,
+                        used: new Set([id]),
+                        active: new Map(),
+                        expires: Date.now() + ttl,
+                        timer: setTimeout(() => {
+                            const current = sessions.get(sessionId);
+                            if (current)
+                                remove(sessionId, current);
+                        }, ttl),
+                    };
+                    session.timer.unref();
+                    sessions.set(sessionId, session);
+                    return json({
+                        jsonrpc: "2.0",
+                        id,
+                        result: {
+                            protocolVersion: version,
+                            capabilities,
+                            serverInfo: options.serverInfo,
+                        },
+                    }, 200, { "Mcp-Session-Id": sessionId });
+                }
+                const [, session] = lookup(request, identity);
+                if (Array.isArray(body) &&
+                    (session.version !== "2025-03-26" || body.length === 0))
+                    throw new McpError("Batch unsupported for this revision", 400, -32600);
+                if (entries.some((entry) => entry !== null &&
+                    typeof entry === "object" &&
+                    entry.method === "initialize"))
+                    throw new McpError("Initialize cannot be batched or repeated", 400, -32600);
+                // This shim never issues server-to-client requests, so unsolicited responses
+                // cannot be accepted (including the March response-batch shape).
+                if (entries.some((entry) => entry !== null &&
+                    typeof entry === "object" &&
+                    (Object.hasOwn(entry, "result") || Object.hasOwn(entry, "error"))))
+                    throw new McpError("Unsolicited JSON-RPC response", 400, -32600);
+                const messages = entries.map((entry) => {
+                    try {
+                        return { message: validateJsonRpcRequest(entry, true) };
+                    }
+                    catch (error) {
+                        return { error: failed(error) };
+                    }
+                });
+                if (!Array.isArray(body) && messages[0]?.error)
+                    return json(messages[0].error, 400);
+                if (!messages.some((item) => item.error || (item.message && "id" in item.message))) {
+                    for (const item of messages)
+                        if (item.message)
+                            notification(item.message, session);
+                    return new Response(null, { status: 202 });
+                }
+                let disconnected = false;
+                const stream = new ReadableStream({
+                    start(sink) {
+                        const send = (value) => {
+                            if (!disconnected)
+                                sink.enqueue(new TextEncoder().encode(`data: ${JSON.stringify(value)}\n\n`));
+                        };
+                        void Promise.all(messages.map(async (item) => {
+                            if (item.error) {
+                                send(item.error);
+                                return;
+                            }
+                            if (!item.message)
+                                return;
+                            if (!("id" in item.message)) {
+                                try {
+                                    notification(item.message, session);
+                                }
+                                catch {
+                                    /* Notifications never receive JSON-RPC responses. */
+                                }
+                                return;
+                            }
+                            send(await run(item.message, request, session, identity, send));
+                        })).finally(() => {
+                            if (!disconnected) {
+                                disconnected = true;
+                                sink.close();
+                            }
+                        });
+                    },
+                    // In legacy HTTP a lost connection is NOT a cancellation notification.
+                    cancel() {
+                        disconnected = true;
+                    },
+                });
+                return new Response(stream, {
+                    headers: {
+                        "Content-Type": "text/event-stream",
+                        "Cache-Control": "no-store",
+                        "X-Accel-Buffering": "no",
+                    },
+                });
+            }
+            catch (error) {
+                return json(failed(error, id), error instanceof McpError ? (error.status ?? 400) : 500);
+            }
+        },
+        close() {
+            closed = true;
+            for (const [id, session] of sessions)
+                remove(id, session);
+        },
+    };
+}

package/dist/server/tools.d.ts

@@ -0,0 +1,17 @@
+import type { McpAuthPolicy } from "../auth/contracts.js";
+import type { McpOperationOutcome, McpProviders, McpRequestContext } from "./contracts.js";
+export type McpToolBinding = {
+    definition: {
+        name: string;
+        description?: string;
+        inputSchema: Record<string, unknown>;
+        outputSchema?: Record<string, unknown>;
+        [key: string]: unknown;
+    };
+    resource: string;
+    action: string;
+    visible?: (context: McpRequestContext) => boolean;
+    execute: (args: Record<string, unknown>, context: McpRequestContext, params: Record<string, unknown>) => McpOperationOutcome | Promise<McpOperationOutcome>;
+};
+/** Finite catalog; authorization is rechecked even after successful discovery. */
+export declare function createToolProviders(tools: readonly McpToolBinding[], auth: McpAuthPolicy | "public"): McpProviders;

package/dist/server/tools.js

@@ -0,0 +1,93 @@
+import { McpError, validateSchema, validateInstance, } from "../protocol/index.js";
+function activePolicy(providerAuth, serverAuth) {
+    if (providerAuth === "public")
+        return serverAuth;
+    if (serverAuth === "public" || serverAuth === providerAuth)
+        return providerAuth;
+    return {
+        authorize: async (identity, operation) => (await providerAuth.authorize(identity, operation)) &&
+            (await serverAuth.authorize(identity, operation)),
+    };
+}
+/** Finite catalog; authorization is rechecked even after successful discovery. */
+export function createToolProviders(tools, auth) {
+    const byName = new Map();
+    for (const tool of tools) {
+        if (byName.has(tool.definition.name))
+            throw new Error(`Duplicate tool: ${tool.definition.name}`);
+        validateSchema(tool.definition.inputSchema);
+        if (tool.definition.outputSchema)
+            validateSchema(tool.definition.outputSchema);
+        byName.set(tool.definition.name, tool);
+    }
+    const authorizationPairs = [...byName.values()].map((tool) => ({
+        resource: tool.resource,
+        action: tool.action,
+    }));
+    const fallback = authorizationPairs[0] ?? {
+        resource: "mcp:server",
+        action: "discover",
+    };
+    const allowed = async (tool, context) => {
+        const policy = activePolicy(auth, context.auth);
+        return ((tool.visible?.(context) ?? true) &&
+            (policy === "public" ||
+                (context.identity !== null &&
+                    (await policy.authorize(context.identity, {
+                        resource: tool.resource,
+                        action: tool.action,
+                    })))));
+    };
+    return {
+        "tools/list": {
+            resource: fallback.resource,
+            action: fallback.action,
+            authorizationPairs,
+            authorization: () => null,
+            async handle(params, context) {
+                if (params.cursor !== undefined)
+                    throw new McpError("Unknown cursor", 400, -32602);
+                const visible = [];
+                for (const tool of byName.values())
+                    if (await allowed(tool, context))
+                        visible.push(tool.definition);
+                return { tools: visible };
+            },
+        },
+        "tools/call": {
+            resource: fallback.resource,
+            action: fallback.action,
+            authorizationPairs,
+            authorization(params) {
+                const tool = byName.get(String(params.name));
+                // Null would skip the gate and reveal whether the name is in the catalog.
+                return tool ? { resource: tool.resource, action: tool.action } : false;
+            },
+            schemas(params) {
+                const definition = byName.get(String(params.name))?.definition;
+                return definition
+                    ? {
+                        inputSchema: definition.inputSchema,
+                        ...(definition.outputSchema
+                            ? { outputSchema: definition.outputSchema }
+                            : {}),
+                    }
+                    : {};
+            },
+            async handle(params, context) {
+                const tool = byName.get(String(params.name));
+                if (!tool || !(await allowed(tool, context)))
+                    throw new McpError("Tool unavailable", 403, -32602);
+                const args = (params.arguments ?? {});
+                validateInstance(tool.definition.inputSchema, args);
+                const result = await tool.execute(args, context, params);
+                if ((result.resultType === undefined ||
+                    result.resultType === "complete") &&
+                    result.isError !== true &&
+                    tool.definition.outputSchema)
+                    validateInstance(tool.definition.outputSchema, result.structuredContent);
+                return result;
+            },
+        },
+    };
+}

package/dist/server.d.ts

@@ -0,0 +1,14 @@
+import type { McpServerOptions, McpServer } from "./server/contracts.js";
+export type * from "./server/contracts.js";
+export { createTaskProviders, createSkillProviders, } from "./server/extensions.js";
+export { createToolProviders } from "./server/tools.js";
+export type { McpToolBinding } from "./server/tools.js";
+/** Stateless modern endpoint with an independently gated legacy session transport. */
+export declare function createMcpServer(options: McpServerOptions): McpServer;
+export { createSkillPublisher } from "./extensions/skills/index.js";
+export type * from "./extensions/skills/contracts.js";
+export { createTaskRuntime, validateTaskRecord, } from "./extensions/tasks/index.js";
+export type * from "./extensions/tasks/contracts.js";
+export { createMcpResourceServerAuth } from "./auth/resource-server.js";
+export type { McpResourceServerOptions } from "./auth/resource-server.js";
+export type { McpAuthPolicy, McpIdentity } from "./auth/contracts.js";