@corbits/mcp 0.3.0 → 0.4.0

package/dist/protocol/types.d.ts

@@ -0,0 +1,295 @@
+export declare const MCP_PROTOCOL_VERSION = "2026-07-28";
+export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+export type MetaObject = Record<string, unknown>;
+export type JsonSchema = boolean | Record<string, unknown>;
+export type RequestId = string | number;
+export type McpProtocolEra = "modern" | "legacy";
+export type McpExtensionSettings = Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+export interface McpValidationContext {
+    /** Explicit resources/read result payload budget; independently checked, capped at 16 MiB. */
+    maxDecodedBytes?: number | undefined;
+    era?: McpProtocolEra;
+    protocolVersion?: string;
+    extensions?: readonly string[] | McpExtensionSettings;
+    clientCapabilities?: Record<string, unknown>;
+    serverCapabilities?: Record<string, unknown>;
+    inputSchema?: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+}
+export interface McpRpcError {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+export interface ElicitRequestFormParams {
+    mode?: "form";
+    message: string;
+    requestedSchema: {
+        $schema?: string;
+        type: "object";
+        properties: Record<string, Record<string, unknown>>;
+        required?: string[];
+    };
+}
+export interface ElicitRequestURLParams {
+    mode: "url";
+    message: string;
+    url: string;
+}
+export type ElicitRequestParams = ElicitRequestFormParams | ElicitRequestURLParams;
+export interface ElicitRequest {
+    method: "elicitation/create";
+    params: ElicitRequestParams;
+}
+export interface ElicitResult {
+    action: "accept" | "decline" | "cancel";
+    content?: Record<string, string | number | boolean | string[]>;
+    _meta?: MetaObject;
+}
+/** Deprecated input kinds are recognized but not advertised or executed by this package. */
+export type InputRequest = ElicitRequest | {
+    method: "sampling/createMessage" | "roots/list";
+    params?: Record<string, unknown>;
+};
+export type InputRequests = Record<string, InputRequest>;
+export type InputResponses = Record<string, ElicitResult | Record<string, unknown>>;
+export interface InputRequiredResult {
+    resultType: "input_required";
+    inputRequests?: InputRequests;
+    requestState?: string;
+    _meta?: MetaObject;
+}
+export interface CompleteResult {
+    resultType?: "complete";
+    _meta?: MetaObject;
+    [key: string]: unknown;
+}
+export type TaskStatus = "working" | "input_required" | "completed" | "failed" | "cancelled";
+export interface Task {
+    taskId: string;
+    status: TaskStatus;
+    createdAt: string;
+    lastUpdatedAt: string;
+    ttlMs: number | null;
+    pollIntervalMs?: number;
+    statusMessage?: string;
+}
+export type DetailedTask = (Task & {
+    status: "working" | "cancelled";
+}) | (Task & {
+    status: "input_required";
+    inputRequests: InputRequests;
+}) | (Task & {
+    status: "completed";
+    result: Record<string, unknown>;
+}) | (Task & {
+    status: "failed";
+    error: McpRpcError;
+});
+export type CreateTaskResult = Task & {
+    resultType: "task";
+    _meta?: MetaObject;
+};
+export type GetTaskResult = DetailedTask & {
+    resultType: "complete";
+    _meta?: MetaObject;
+};
+export interface SkillResource {
+    uri: string;
+    digest: string;
+    size: number;
+}
+export interface Skill {
+    uri: string;
+    frontmatter: {
+        name: string;
+        description: string;
+        [key: string]: unknown;
+    };
+    resources: SkillResource[] | "dynamic";
+    _meta?: MetaObject;
+}
+export interface ResourceContents {
+    uri: string;
+    mimeType?: string;
+    _meta?: MetaObject;
+}
+export interface TextResourceContents extends ResourceContents {
+    text: string;
+}
+export interface BlobResourceContents extends ResourceContents {
+    blob: string;
+}
+export type McpResourceContents = TextResourceContents | BlobResourceContents;
+export interface McpUiToolMeta {
+    resourceUri?: string;
+    visibility?: ("model" | "app")[];
+    [key: string]: unknown;
+}
+export interface McpUiResourceMeta {
+    csp?: {
+        connectDomains?: string[];
+        resourceDomains?: string[];
+        frameDomains?: string[];
+        baseUriDomains?: string[];
+    };
+    permissions?: {
+        camera?: Record<string, never>;
+        microphone?: Record<string, never>;
+        geolocation?: Record<string, never>;
+        clipboardWrite?: Record<string, never>;
+    };
+    domain?: string;
+    prefersBorder?: boolean;
+    [key: string]: unknown;
+}
+export interface McpPaginationParams {
+    cursor?: string;
+    _meta?: MetaObject;
+}
+export interface McpRetryParams {
+    inputResponses?: InputResponses;
+    requestState?: string;
+    _meta?: MetaObject;
+}
+export interface McpSubscriptionFilter {
+    toolsListChanged?: boolean;
+    promptsListChanged?: boolean;
+    resourcesListChanged?: boolean;
+    resourceSubscriptions?: readonly string[];
+    taskIds?: readonly string[];
+}
+export interface McpMethodMap {
+    "server/discover": {
+        params: {
+            _meta?: MetaObject;
+        };
+        result: CompleteResult & {
+            supportedVersions: string[];
+            capabilities: Record<string, unknown>;
+        };
+    };
+    "tools/list": {
+        params: McpPaginationParams;
+        result: CompleteResult & {
+            tools: Record<string, unknown>[];
+        };
+    };
+    "tools/call": {
+        params: McpRetryParams & {
+            name: string;
+            arguments?: Record<string, unknown>;
+        };
+        result: CompleteResult | InputRequiredResult | CreateTaskResult;
+    };
+    "prompts/list": {
+        params: McpPaginationParams;
+        result: CompleteResult & {
+            prompts: Record<string, unknown>[];
+        };
+    };
+    "prompts/get": {
+        params: McpRetryParams & {
+            name: string;
+            arguments?: Record<string, string>;
+        };
+        result: CompleteResult | InputRequiredResult;
+    };
+    "resources/list": {
+        params: McpPaginationParams;
+        result: CompleteResult & {
+            resources: Record<string, unknown>[];
+        };
+    };
+    "resources/templates/list": {
+        params: McpPaginationParams;
+        result: CompleteResult & {
+            resourceTemplates: Record<string, unknown>[];
+        };
+    };
+    "resources/read": {
+        params: McpRetryParams & {
+            uri: string;
+        };
+        result: CompleteResult | InputRequiredResult;
+    };
+    "completion/complete": {
+        params: {
+            ref: {
+                type: "ref/prompt";
+                name: string;
+            } | {
+                type: "ref/resource";
+                uri: string;
+            };
+            argument: {
+                name: string;
+                value: string;
+            };
+            context?: {
+                arguments?: Record<string, string>;
+            };
+            _meta?: MetaObject;
+        };
+        result: CompleteResult & {
+            completion: {
+                values: string[];
+                total?: number;
+                hasMore?: boolean;
+            };
+        };
+    };
+    "subscriptions/listen": {
+        params: {
+            notifications: McpSubscriptionFilter;
+            _meta?: MetaObject;
+        };
+        result: CompleteResult;
+    };
+    "tasks/get": {
+        params: {
+            taskId: string;
+            _meta?: MetaObject;
+        };
+        result: GetTaskResult;
+    };
+    "tasks/update": {
+        params: {
+            taskId: string;
+            inputResponses: InputResponses;
+            _meta?: MetaObject;
+        };
+        result: CompleteResult;
+    };
+    "tasks/cancel": {
+        params: {
+            taskId: string;
+            _meta?: MetaObject;
+        };
+        result: CompleteResult;
+    };
+    "skills/list": {
+        params: McpPaginationParams;
+        result: CompleteResult & {
+            skills: Skill[];
+        };
+    };
+    "skills/get": {
+        params: {
+            uri: string;
+            _meta?: MetaObject;
+        };
+        result: CompleteResult & {
+            skill: Skill;
+        };
+    };
+    "resources/directory/read": {
+        params: McpPaginationParams & {
+            uri: string;
+        };
+        result: CompleteResult & {
+            resources: Record<string, unknown>[];
+        };
+    };
+}
+export type McpMethod = keyof McpMethodMap;

package/dist/protocol/types.js

@@ -0,0 +1,3 @@
+// Wire contracts derived from MCP 2026-07-28 schema at
+// 271ecc9accafdd9b83a3c869fa67c22953b2af80 and the extension pins in extensions.ts.
+export const MCP_PROTOCOL_VERSION = "2026-07-28";

package/dist/protocol/ui.d.ts

@@ -0,0 +1,3 @@
+import type { McpUiToolMeta } from "./types.js";
+/** Validate the value of a tool's _meta.ui, preserving future metadata fields. */
+export declare function validateUiToolMeta(value: unknown): McpUiToolMeta;

package/dist/protocol/ui.js

@@ -0,0 +1,18 @@
+import { McpError, McpErrorCode } from "./errors.js";
+import { assertJsonBounds } from "./json-schema.js";
+/** Validate the value of a tool's _meta.ui, preserving future metadata fields. */
+export function validateUiToolMeta(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new McpError("invalid tool UI metadata", undefined, McpErrorCode.InvalidParams);
+    assertJsonBounds(value);
+    const metadata = value;
+    if (metadata.resourceUri !== undefined &&
+        (typeof metadata.resourceUri !== "string" ||
+            !metadata.resourceUri.startsWith("ui://")))
+        throw new McpError("UI resourceUri must use ui://", undefined, McpErrorCode.InvalidParams);
+    if (metadata.visibility !== undefined &&
+        (!Array.isArray(metadata.visibility) ||
+            !metadata.visibility.every((entry) => entry === "model" || entry === "app")))
+        throw new McpError("invalid UI visibility", undefined, McpErrorCode.InvalidParams);
+    return metadata;
+}

package/dist/server/contracts.d.ts

@@ -0,0 +1,67 @@
+import type { McpAuthOperation, McpAuthPolicy, McpIdentity } from "../auth/contracts.js";
+import type { McpExtensionSettings, McpValidationContext, McpMethodMap, McpSubscriptionFilter } from "../protocol/types.js";
+/** Provider values are validated by the shared protocol boundary before transmission. */
+export type McpOperationOutcome = McpMethodMap["tools/call"]["result"];
+export type McpRequestContext = {
+    identity: McpIdentity | null;
+    /** Server policy. A public tool catalog must not ignore this on a private server. */
+    auth: McpAuthPolicy | "public";
+    requestId: string | number;
+    protocolVersion: string;
+    clientCapabilities: Record<string, unknown>;
+    signal: AbortSignal;
+    notify: (method: string, params: Record<string, unknown>) => void;
+    reportProgress: (progress: number, total?: number, message?: string) => void;
+};
+export type McpProvider = {
+    /** Authorization applies to both catalog and execution methods. */
+    resource: string;
+    action: string;
+    /**
+     * Method gate. Undefined uses `resource` and `action`.
+     * Null means this method has no single pair; the provider authorizes each
+     * binding with that binding's own resource and action.
+     * False denies immediately, the same response as `authorize` returning false.
+     */
+    authorization?: (params: Record<string, unknown>) => McpAuthOperation | null | false;
+    /** Private discover succeeds when any of these pairs is allowed. Defaults to resource/action. */
+    authorizationPairs?: readonly McpAuthOperation[];
+    schemas?: (params: Record<string, unknown>) => Pick<McpValidationContext, "inputSchema" | "outputSchema">;
+    /** subscriptions/listen only: accept a supported subset before acknowledgement.
+     * Without this hook no notifications are accepted. Must not emit notifications. */
+    acceptSubscription?: (params: Record<string, unknown>, context: McpRequestContext) => McpSubscriptionFilter | Promise<McpSubscriptionFilter>;
+    handle: (params: Record<string, unknown>, context: McpRequestContext) => McpOperationOutcome | Promise<McpOperationOutcome>;
+};
+/** Only known protocol methods may be registered. Discovery is server-owned. */
+export type McpProviders = Readonly<Record<string, McpProvider>>;
+export type McpLegacyRevision = "2025-11-25" | "2025-06-18" | "2025-03-26";
+export type McpLegacyOptions = {
+    /** Explicitly supported revisions; defaults to all three 2025 Streamable HTTP revisions. */
+    versions?: readonly McpLegacyRevision[];
+    /** Absolute session lifetime, not renewed by traffic. Default: 30 minutes. */
+    sessionTtlMs?: number;
+    /** Per-server bound. Defaults to 1024; host must provide affinity across replicas. */
+    maxSessions?: number;
+};
+export type McpServerOptions = {
+    serverInfo: {
+        name: string;
+        version: string;
+        title?: string;
+    };
+    providers?: McpProviders;
+    /** Required for private servers; public access must be explicitly selected. */
+    auth: McpAuthPolicy | "public";
+    /** Requests with Origin are refused unless explicitly allowed here. */
+    allowedOrigins?: readonly string[];
+    /** Pass the resource-server auth factory challenge to preserve OAuth discovery headers. */
+    challenge?: (status: 401 | 403, scopes?: readonly string[]) => Response;
+    extensions?: McpExtensionSettings;
+    maxRequestBytes?: number;
+    /** Opt-in, identity-bound legacy sessions. Modern requests remain stateless. */
+    legacy?: McpLegacyOptions;
+};
+export type McpServer = {
+    fetch: (request: Request) => Promise<Response>;
+    close: () => Promise<void>;
+};

package/dist/server/contracts.js

@@ -0,0 +1 @@
+export {};

package/dist/server/errors.d.ts

@@ -0,0 +1,6 @@
+/** Both HTTP and SSE errors preserve bounded JSON data, never arbitrary thrown objects. */
+export declare function errorPayload(error: unknown, fallback: string): {
+    data?: {} | null;
+    code: number;
+    message: string;
+};

package/dist/server/errors.js

@@ -0,0 +1,21 @@
+import { McpError, assertJsonBounds } from "../protocol/index.js";
+/** Both HTTP and SSE errors preserve bounded JSON data, never arbitrary thrown objects. */
+export function errorPayload(error, fallback) {
+    if (!(error instanceof McpError))
+        return { code: -32603, message: fallback };
+    let data;
+    if (error.data !== undefined) {
+        try {
+            assertJsonBounds(error.data);
+            data = JSON.parse(JSON.stringify(error.data));
+        }
+        catch {
+            /* Invalid provider error data must not break the response stream. */
+        }
+    }
+    return {
+        code: error.code ?? -32603,
+        message: error.message,
+        ...(data === undefined ? {} : { data }),
+    };
+}

package/dist/server/extensions.d.ts

@@ -0,0 +1,7 @@
+import type { createTaskRuntime } from "../extensions/tasks/index.js";
+import type { createSkillPublisher } from "../extensions/skills/index.js";
+import type { McpProviders } from "./contracts.js";
+/** Runtime owns durable state and input authorization; server owns wire validation. */
+export declare function createTaskProviders(runtime: ReturnType<typeof createTaskRuntime>): McpProviders;
+/** Host explicitly chooses the resource authorization domain for this snapshot. */
+export declare function createSkillProviders(publisher: Awaited<ReturnType<typeof createSkillPublisher>>, resource: string): McpProviders;

package/dist/server/extensions.js

@@ -0,0 +1,61 @@
+import { McpError } from "../protocol/index.js";
+const identity = (context) => {
+    if (!context.identity)
+        throw new McpError("Authenticated extension identity required", 401, -32602);
+    return context.identity;
+};
+/** Runtime owns durable state and input authorization; server owns wire validation. */
+export function createTaskProviders(runtime) {
+    return {
+        "tasks/get": {
+            resource: "mcp:tasks",
+            action: "read",
+            handle: (params, context) => runtime.get(identity(context), String(params.taskId)),
+        },
+        "tasks/update": {
+            resource: "mcp:tasks",
+            action: "update",
+            handle: (params, context) => runtime.submitInput(identity(context), String(params.taskId), params.inputResponses),
+        },
+        "tasks/cancel": {
+            resource: "mcp:tasks",
+            action: "cancel",
+            handle: (params, context) => runtime.cancel(identity(context), String(params.taskId)),
+        },
+    };
+}
+/** Host explicitly chooses the resource authorization domain for this snapshot. */
+export function createSkillProviders(publisher, resource) {
+    const noCursor = (params) => {
+        if (params.cursor !== undefined)
+            throw new McpError("Unknown cursor", 400, -32602);
+    };
+    return {
+        "skills/list": {
+            resource,
+            action: "read",
+            handle: (params) => {
+                noCursor(params);
+                return publisher.list();
+            },
+        },
+        "skills/get": {
+            resource,
+            action: "read",
+            handle: (params) => publisher.get(String(params.uri)),
+        },
+        "resources/read": {
+            resource,
+            action: "read",
+            handle: (params) => publisher.read(String(params.uri)),
+        },
+        "resources/directory/read": {
+            resource,
+            action: "read",
+            handle: (params) => {
+                noCursor(params);
+                return publisher.directoryRead(String(params.uri));
+            },
+        },
+    };
+}

package/dist/server/fixtures.d.ts

@@ -0,0 +1,2 @@
+export declare function rpc(method: string, params?: Record<string, unknown>, headers?: Record<string, string>): Request;
+export declare function result(response: Response): Promise<Record<string, unknown>>;

package/dist/server/fixtures.js

@@ -0,0 +1,34 @@
+export function rpc(method, params = {}, headers = {}) {
+    const name = params.name ?? params.uri ?? params.taskId;
+    return new Request("http://localhost/mcp", {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Accept: "application/json, text/event-stream",
+            "MCP-Protocol-Version": "2026-07-28",
+            "Mcp-Method": method,
+            ...(typeof name === "string" ? { "Mcp-Name": name } : {}),
+            ...headers,
+        },
+        body: JSON.stringify({
+            jsonrpc: "2.0",
+            id: 1,
+            method,
+            params: {
+                ...params,
+                _meta: {
+                    "io.modelcontextprotocol/protocolVersion": "2026-07-28",
+                    "io.modelcontextprotocol/clientInfo": { name: "test", version: "1" },
+                    "io.modelcontextprotocol/clientCapabilities": {},
+                    ...params._meta,
+                },
+            },
+        }),
+    });
+}
+export async function result(response) {
+    if (response.headers.get("content-type")?.includes("application/json"))
+        return (await response.json());
+    const events = (await response.text()).trim().split("\n\n");
+    return JSON.parse(events.at(-1).slice(6));
+}

package/dist/server/legacy.d.ts

@@ -0,0 +1,9 @@
+import { type McpIdentity } from "../auth/contracts.js";
+import type { McpLegacyRevision, McpProviders, McpServerOptions } from "./contracts.js";
+/** Isolated legacy transport. No HTTP+SSE endpoint, GET stream, resumption, MRTR or extensions. */
+export declare function createLegacyServer(options: McpServerOptions, providers: McpProviders): {
+    versions: McpLegacyRevision[];
+    lifecycle(request: Request): Promise<Response>;
+    handle(request: Request, body: unknown, identity: McpIdentity | null): Promise<Response | undefined>;
+    close(): void;
+};