@corbits/mcp 0.3.1 → 0.4.0

package/dist/extensions/apps.d.ts

@@ -0,0 +1,58 @@
+import type { McpUiResourceMeta, McpUiToolMeta, McpResourceContents } from "../protocol/index.js";
+/** Metadata helpers only: this package does not render or sandbox HTML. */
+export declare function isToolVisibleToModel(meta?: McpUiToolMeta): boolean;
+export declare function assertAppToolCall(options: {
+    tool?: McpUiToolMeta;
+    appServerId: string;
+    targetServerId: string;
+}): void;
+export declare function getAppHostRequirements(meta?: McpUiResourceMeta): {
+    rendererProvided: false;
+    protocolVersion: "2026-01-26";
+    mimeType: "text/html;profile=mcp-app";
+    sandbox: {
+        separateOrigin: true;
+        proxyRequiredForWebHost: true;
+        permissions: readonly ["allow-scripts", "allow-same-origin"];
+    };
+    csp: {
+        connectDomains?: string[];
+        resourceDomains?: string[];
+        frameDomains?: string[];
+        baseUriDomains?: string[];
+    };
+    defaults: {
+        connectSrc: string;
+        resourceSrc: string;
+        frameSrc: string;
+        baseUri: string;
+    };
+    requestedPermissions: {
+        camera?: Record<string, never>;
+        microphone?: Record<string, never>;
+        geolocation?: Record<string, never>;
+        clipboardWrite?: Record<string, never>;
+    };
+    requestedDomain: string | undefined;
+    obligations: readonly ["enforce-declared-csp-without-loosening", "validate-message-origin-and-source", "initialize-before-delivery", "authorize-every-tool-call", "keep-result-meta-out-of-model-context", "user-consent-for-external-navigation"];
+};
+export interface McpAppHost {
+    /** Must implement sandbox, CSP and authenticated message bridge; not a transport flag. */
+    mount(resource: McpResourceContents, requirements: ReturnType<typeof getAppHostRequirements>): Promise<{
+        close(): Promise<void>;
+    }>;
+    authorizeTool(serverId: string, name: string, args: Record<string, unknown>): Promise<void>;
+    callTool(serverId: string, name: string, args: Record<string, unknown>): Promise<unknown>;
+}
+export declare function createAppHostBridge(host: McpAppHost): {
+    mount(resource: McpResourceContents, metadata?: McpUiResourceMeta): Promise<{
+        close(): Promise<void>;
+    }>;
+    call(options: {
+        appServerId: string;
+        targetServerId: string;
+        name: string;
+        arguments: Record<string, unknown>;
+        tool?: McpUiToolMeta;
+    }): Promise<unknown>;
+};

package/dist/extensions/apps.js

@@ -0,0 +1,55 @@
+/** Metadata helpers only: this package does not render or sandbox HTML. */
+export function isToolVisibleToModel(meta) {
+    return meta?.visibility === undefined || meta.visibility.includes("model");
+}
+export function assertAppToolCall(options) {
+    if (!options.appServerId || options.appServerId !== options.targetServerId)
+        throw new Error("Cross-server app tool call prohibited");
+    if (options.tool?.visibility && !options.tool.visibility.includes("app"))
+        throw new Error("Tool is not app-callable");
+}
+export function getAppHostRequirements(meta = {}) {
+    return {
+        rendererProvided: false,
+        protocolVersion: "2026-01-26",
+        mimeType: "text/html;profile=mcp-app",
+        sandbox: {
+            separateOrigin: true,
+            proxyRequiredForWebHost: true,
+            permissions: ["allow-scripts", "allow-same-origin"],
+        },
+        // These are requested constraints, not a CSP header generator or approval.
+        csp: structuredClone(meta.csp ?? {}),
+        defaults: {
+            connectSrc: "'none'",
+            resourceSrc: "'none'",
+            frameSrc: "'none'",
+            baseUri: "'self'",
+        },
+        requestedPermissions: structuredClone(meta.permissions ?? {}),
+        requestedDomain: meta.domain,
+        obligations: [
+            "enforce-declared-csp-without-loosening",
+            "validate-message-origin-and-source",
+            "initialize-before-delivery",
+            "authorize-every-tool-call",
+            "keep-result-meta-out-of-model-context",
+            "user-consent-for-external-navigation",
+        ],
+    };
+}
+export function createAppHostBridge(host) {
+    return {
+        async mount(resource, metadata) {
+            if (!resource.uri.startsWith("ui://") ||
+                resource.mimeType !== "text/html;profile=mcp-app")
+                throw new Error("Unsupported Apps resource");
+            return host.mount(structuredClone(resource), getAppHostRequirements(metadata));
+        },
+        async call(options) {
+            assertAppToolCall(options);
+            await host.authorizeTool(options.targetServerId, options.name, options.arguments);
+            return host.callTool(options.targetServerId, options.name, options.arguments);
+        },
+    };
+}

package/dist/extensions/elicitation.d.ts

@@ -0,0 +1,18 @@
+import type { ElicitRequestParams, ElicitRequestFormParams, ElicitRequestURLParams, ElicitResult, InputRequests, InputResponses } from "../protocol/index.js";
+/** Request-aware host semantics shared by direct and durable task input.
+ * Wire shape validation remains owned by the common protocol module.
+ */
+export declare function validateElicitationResponse(request: ElicitRequestParams, response: InputResponses[string]): void;
+export interface McpElicitationHost {
+    form?(request: ElicitRequestFormParams, signal?: AbortSignal): Promise<ElicitResult>;
+    /** Host presents URL and obtains explicit user consent. Opening a URL is not acceptance. */
+    url?(request: ElicitRequestURLParams, signal?: AbortSignal): Promise<ElicitResult>;
+}
+/** Input has already passed the common wire validators. No sampling/roots capability implied. */
+export declare function createElicitationRuntime(host: McpElicitationHost): {
+    capabilities: {
+        url?: {};
+        form?: {};
+    };
+    respond(requests: InputRequests, signal?: AbortSignal): Promise<InputResponses>;
+};

package/dist/extensions/elicitation.js

@@ -0,0 +1,55 @@
+import { validateInstance, validateInputRequests, validateInputResponses, } from "../protocol/index.js";
+/** Request-aware host semantics shared by direct and durable task input.
+ * Wire shape validation remains owned by the common protocol module.
+ */
+export function validateElicitationResponse(request, response) {
+    validateInputResponses({ response });
+    if (request.mode === "url" && response.content !== undefined)
+        throw new Error("URL elicitation cannot return form content");
+    if (response.action !== "accept" && response.content !== undefined)
+        throw new Error("Non-accept elicitation must omit content");
+    if (request.mode !== "url" && response.action === "accept")
+        validateInstance(request.requestedSchema, response.content ?? {});
+}
+/** Input has already passed the common wire validators. No sampling/roots capability implied. */
+export function createElicitationRuntime(host) {
+    return {
+        capabilities: {
+            ...(host.form ? { form: {} } : {}),
+            ...(host.url ? { url: {} } : {}),
+        },
+        async respond(requests, signal) {
+            validateInputRequests(requests);
+            const responses = {};
+            for (const [key, request] of Object.entries(requests)) {
+                signal?.throwIfAborted();
+                if (request.method !== "elicitation/create")
+                    throw new Error(`Unsupported host input: ${request.method}`);
+                const params = request.params;
+                let response;
+                if (params.mode === "url") {
+                    const url = new URL(params.url);
+                    if (url.protocol !== "https:" || url.username || url.password)
+                        throw new Error("Unsafe elicitation URL");
+                    if (!host.url)
+                        throw new Error("URL elicitation host unavailable");
+                    response = await host.url(structuredClone(params), signal);
+                }
+                else {
+                    if (!host.form)
+                        throw new Error("Form elicitation host unavailable");
+                    response = await host.form(structuredClone(params), signal);
+                }
+                validateElicitationResponse(params, response);
+                signal?.throwIfAborted();
+                Object.defineProperty(responses, key, {
+                    value: structuredClone(response),
+                    enumerable: true,
+                    configurable: true,
+                    writable: true,
+                });
+            }
+            return responses;
+        },
+    };
+}

package/dist/extensions/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./skills/index.js";
+export * from "./tasks/index.js";
+export * from "./apps.js";
+export * from "./elicitation.js";
+export * from "./maturity.js";

package/dist/extensions/index.js

@@ -0,0 +1,5 @@
+export * from "./skills/index.js";
+export * from "./tasks/index.js";
+export * from "./apps.js";
+export * from "./elicitation.js";
+export * from "./maturity.js";

package/dist/extensions/maturity.d.ts

@@ -0,0 +1,44 @@
+export declare const extensionMaturity: Readonly<{
+    tasks: {
+        readonly id: "io.modelcontextprotocol/tasks";
+        readonly coreRevision: "2026-07-28";
+        readonly extensionRevision: "2026-07-28";
+        readonly sourceCommit: "b3d28aceaa6d49f5f92258e3d06b61ad6f111e84";
+        readonly maturity: "stable";
+        readonly enabledByDefault: false;
+    };
+    skills: {
+        readonly id: "io.modelcontextprotocol/skills";
+        readonly coreRevision: "2026-07-28";
+        readonly extensionRevision: "stable";
+        readonly sourceCommit: "c1aa87e4c381c82b99aa37471d0eae4ab50f9985";
+        readonly maturity: "stable";
+        readonly enabledByDefault: false;
+    };
+    apps: {
+        readonly id: "io.modelcontextprotocol/ui";
+        readonly coreRevision: "2026-07-28";
+        readonly extensionRevision: "2026-01-26";
+        readonly sourceCommit: "266a9e3b70dbd4a4f0546dda95da2a2c1a8be4b7";
+        readonly maturity: "released";
+        readonly enabledByDefault: false;
+    };
+}>;
+/** Negotiating a wire extension does not supply a renderer, approvals or durability. */
+export declare function supportedHostExtensions(options: {
+    tasks?: {
+        durableStore: boolean;
+        recoverableExecutor: boolean;
+        inputHandler: boolean;
+    };
+    skills?: {
+        verifiedLoader: boolean;
+        contextProvenance: boolean;
+        executionGate: boolean;
+    };
+    apps?: {
+        sandboxRenderer: boolean;
+        cspEnforcement: boolean;
+        authenticatedBridge: boolean;
+    };
+}): string[];

package/dist/extensions/maturity.js

@@ -0,0 +1,24 @@
+/** Upstream maturity, not transport support or a claim about host deployment. */
+import { MCP_EXTENSIONS, MCP_EXT_TASKS, MCP_EXT_SKILLS, MCP_EXT_UI, } from "../protocol/index.js";
+export const extensionMaturity = Object.freeze({
+    tasks: MCP_EXTENSIONS[MCP_EXT_TASKS],
+    skills: MCP_EXTENSIONS[MCP_EXT_SKILLS],
+    apps: MCP_EXTENSIONS[MCP_EXT_UI],
+});
+/** Negotiating a wire extension does not supply a renderer, approvals or durability. */
+export function supportedHostExtensions(options) {
+    const ids = [];
+    if (options.tasks?.durableStore === true &&
+        options.tasks.recoverableExecutor === true &&
+        options.tasks.inputHandler === true)
+        ids.push(extensionMaturity.tasks.id);
+    if (options.skills?.verifiedLoader === true &&
+        options.skills.contextProvenance === true &&
+        options.skills.executionGate === true)
+        ids.push(extensionMaturity.skills.id);
+    if (options.apps?.sandboxRenderer === true &&
+        options.apps.cspEnforcement === true &&
+        options.apps.authenticatedBridge === true)
+        ids.push(extensionMaturity.apps.id);
+    return ids;
+}

package/dist/extensions/skills/contracts.d.ts

@@ -0,0 +1,53 @@
+import type { Skill } from "../../protocol/index.js";
+/** Host-assigned identities, never serverInfo.name or a bearer token. */
+export interface McpSkillOrigin {
+    serverId: string;
+    tenantId: string;
+    principalId: string;
+    authorizationContextId: string;
+}
+export interface HeldSkill {
+    readonly origin: Readonly<McpSkillOrigin>;
+    readonly entry: Readonly<Skill>;
+    readonly identity: string;
+    readonly fingerprint: string;
+}
+export interface SkillApprovalReceipt {
+    identity: string;
+    fingerprint: string;
+    /** Explicit user consent to this skill, not to nested skills. */
+    approved: true;
+    execution: boolean;
+}
+export interface VerifiedSkillBytes {
+    held: HeldSkill;
+    uri: string;
+    bytes: Uint8Array;
+    /** Always untrusted MCP data; integrity is not authorship or trust. */
+    trust: "untrusted-mcp";
+}
+export interface McpSkillHostPolicy {
+    approve(held: HeldSkill): Promise<SkillApprovalReceipt>;
+    /** Install an all-code-execution-tool gate before admitting context. */
+    openActingWindow(held: HeldSkill, approval: SkillApprovalReceipt, guards: {
+        assertExecutionApproved(): void;
+    }): Promise<{
+        admit(content: VerifiedSkillBytes): Promise<void>;
+        /** Must remove context before returning; do not shorten the acting window. */
+        removeContext(): Promise<void>;
+        close(): Promise<void>;
+    }>;
+}
+export interface SkillLease {
+    readonly held: HeldSkill;
+    read(uri: string): Promise<VerifiedSkillBytes>;
+    /** Re-check for every host code-execution call; never widens existing grants. */
+    assertExecutionApproved(): void;
+    release(): Promise<void>;
+}
+export interface SkillSource {
+    /** Must use the origin's mediated transport and shared protocol validation. */
+    get(origin: McpSkillOrigin, uri: string): Promise<Skill>;
+    /** Decode a single matching resources/read text/blob to raw bytes. Enforce maxBytes while streaming. */
+    read(origin: McpSkillOrigin, uri: string, maxBytes: number): Promise<Uint8Array>;
+}

package/dist/extensions/skills/contracts.js

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

package/dist/extensions/skills/index.d.ts

@@ -0,0 +1,52 @@
+import type { Skill } from "../../protocol/index.js";
+import type { HeldSkill, McpSkillHostPolicy, McpSkillOrigin, SkillLease, SkillSource, VerifiedSkillBytes } from "./contracts.js";
+export type * from "./contracts.js";
+export declare const SKILL_LIMITS: Readonly<{
+    resources: 512;
+    bytes: 16777216;
+}>;
+export declare function parseSkillFrontmatter(bytes: Uint8Array, uri: string): Skill["frontmatter"];
+export declare function createSkillLoader(source: SkillSource, host?: McpSkillHostPolicy): {
+    hold: (origin: McpSkillOrigin, entry: Skill) => Promise<HeldSkill>;
+    verify: (held: HeldSkill, uri?: string) => Promise<VerifiedSkillBytes>;
+    activate: (held: HeldSkill) => Promise<SkillLease>;
+    get(origin: McpSkillOrigin, uri: string): Promise<HeldSkill>;
+    clear(): void;
+};
+/** In-memory immutable snapshot publisher. Host must authorize all methods using the same identity. */
+export declare function createSkillPublisher(publications: readonly {
+    uri: string;
+    files: ReadonlyMap<string, Uint8Array>;
+}[]): Promise<{
+    list(): {
+        resultType: "complete";
+        ttlMs: number;
+        cacheScope: "private";
+        skills: Skill[];
+    };
+    get(uri: string): {
+        resultType: "complete";
+        ttlMs: number;
+        cacheScope: "private";
+        skill: Skill;
+    };
+    read(uri: string): {
+        resultType: "complete";
+        ttlMs: number;
+        cacheScope: "private";
+        contents: {
+            uri: string;
+            blob: string;
+        }[];
+    };
+    directoryRead(uri: string): {
+        resultType: "complete";
+        ttlMs: number;
+        cacheScope: "private";
+        resources: {
+            uri: string;
+            name: string;
+            mimeType?: string;
+        }[];
+    };
+}>;