@sammorrowdrums/mcpi-ext 0.2.0 → 1.0.0

package/dist/mcp/host-approval.d.ts

@@ -0,0 +1,16 @@
+import type { ExtensionContext } from "@sammorrowdrums/mcpi";
+import type { McpApprovalPrompt, McpApprovalRequest } from "./policy.js";
+type ApprovalContext = Pick<ExtensionContext, "hasUI" | "ui">;
+/**
+ * Bridges policy approval requests to mcpi's explicit user-facing confirmation.
+ *
+ * Mirrors {@link McpiHostElicitation}: without an interactive UI the request is
+ * reported as undecided rather than approved, so nothing is ever silently
+ * enabled.
+ */
+export declare class McpiHostApproval implements McpApprovalPrompt {
+    private context;
+    setContext(context: ApprovalContext | undefined): void;
+    confirm(request: McpApprovalRequest): Promise<boolean | undefined>;
+}
+export {};

package/dist/mcp/host-approval.js

@@ -0,0 +1,19 @@
+/**
+ * Bridges policy approval requests to mcpi's explicit user-facing confirmation.
+ *
+ * Mirrors {@link McpiHostElicitation}: without an interactive UI the request is
+ * reported as undecided rather than approved, so nothing is ever silently
+ * enabled.
+ */
+export class McpiHostApproval {
+    context;
+    setContext(context) {
+        this.context = context;
+    }
+    async confirm(request) {
+        const context = this.context;
+        if (!context?.hasUI)
+            return undefined;
+        return context.ui.confirm(request.title, request.message, request.signal ? { signal: request.signal } : undefined);
+    }
+}

package/dist/mcp/host-elicitation.d.ts

@@ -0,0 +1,19 @@
+import type { ElicitRequestParams, ElicitResult } from "@modelcontextprotocol/client";
+import type { ExtensionContext } from "@sammorrowdrums/mcpi";
+import type { McpElicitationHandler } from "./client-factory.js";
+type ElicitationContext = Pick<ExtensionContext, "hasUI" | "ui">;
+export declare class McpHostElicitationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Bridges MCP form elicitation to mcpi's explicit user-facing UI.
+ *
+ * URL elicitation is intentionally unsupported and is not advertised by the
+ * client. Form requests never receive an implicit approval.
+ */
+export declare class McpiHostElicitation implements McpElicitationHandler {
+    private context;
+    setContext(context: ElicitationContext | undefined): void;
+    elicit(params: ElicitRequestParams): Promise<ElicitResult>;
+}
+export {};

package/dist/mcp/host-elicitation.js

@@ -0,0 +1,94 @@
+export class McpHostElicitationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "McpHostElicitationError";
+    }
+}
+/**
+ * Bridges MCP form elicitation to mcpi's explicit user-facing UI.
+ *
+ * URL elicitation is intentionally unsupported and is not advertised by the
+ * client. Form requests never receive an implicit approval.
+ */
+export class McpiHostElicitation {
+    context;
+    setContext(context) {
+        this.context = context;
+    }
+    async elicit(params) {
+        if (params.mode === "url") {
+            throw new McpHostElicitationError(`MCP URL elicitation is unsupported. Open the requested URL manually only after reviewing it: ${params.url}`);
+        }
+        const context = this.context;
+        if (!context?.hasUI) {
+            throw new McpHostElicitationError("The MCP server requested user input, but mcpi has no interactive UI. Re-run this call in interactive mode; the request was not approved.");
+        }
+        const decision = await context.ui.select(params.message, [
+            "Provide input",
+            "Decline",
+            "Cancel",
+        ]);
+        if (decision === "Decline") {
+            return { action: "decline" };
+        }
+        if (decision !== "Provide input") {
+            return { action: "cancel" };
+        }
+        let draft = JSON.stringify(buildInitialContent(params), null, 2);
+        while (true) {
+            const edited = await context.ui.editor("MCP input required (JSON)", draft);
+            if (edited === undefined) {
+                return { action: "cancel" };
+            }
+            try {
+                const content = JSON.parse(edited);
+                if (!isElicitationContent(content)) {
+                    context.ui.notify("MCP elicitation input must be a JSON object containing primitive values or string arrays.", "error");
+                    draft = edited;
+                    continue;
+                }
+                return { action: "accept", content };
+            }
+            catch {
+                context.ui.notify("MCP elicitation input must be valid JSON.", "error");
+                draft = edited;
+            }
+        }
+    }
+}
+function buildInitialContent(params) {
+    return Object.fromEntries(Object.entries(params.requestedSchema.properties).map(([name, definition]) => [
+        name,
+        initialValue(definition),
+    ]));
+}
+function initialValue(definition) {
+    if (definition.default !== undefined) {
+        return definition.default;
+    }
+    if (definition.type === "boolean") {
+        return false;
+    }
+    if (definition.type === "number" || definition.type === "integer") {
+        return definition.minimum ?? 0;
+    }
+    if (definition.type === "array") {
+        return [];
+    }
+    if ("enum" in definition) {
+        return definition.enum[0] ?? "";
+    }
+    if ("oneOf" in definition) {
+        return definition.oneOf[0]?.const ?? "";
+    }
+    return "";
+}
+function isElicitationContent(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.values(value).every((entry) => typeof entry === "string" ||
+            typeof entry === "number" ||
+            typeof entry === "boolean" ||
+            (Array.isArray(entry) && entry.every((item) => typeof item === "string"))));
+}

package/dist/mcp/index.d.ts

@@ -0,0 +1,8 @@
+export type { McpConfig, ServerConfig, StdioServerConfig, RemoteServerConfig } from "./config.js";
+export { McpConfig as McpConfigSchema } from "./config.js";
+export { loadMcpConfig } from "./config-loader.js";
+export { isSkillsExtensionEnabled } from "./config.js";
+export { McpClientManager, type McpTool } from "./client-manager.js";
+export { McpPolicy, McpPolicyError, isReadOnlyToolCall, validateToolArguments, type McpApprovalOutcome, type McpApprovalPrompt, type McpApprovalRequest, type McpAuditRecord, type McpCallSource, type McpPolicyDenialReason, type McpPolicyGateway, type McpPolicyOptions, type McpPolicySkill, type McpResourceReadRequest, type McpResourceSource, type McpToolCallRequest, type SkillGrantOutcome, } from "./policy.js";
+export { McpiHostApproval } from "./host-approval.js";
+export { noSkillsExtensionGateway } from "./gateway-defaults.js";

package/dist/mcp/index.js

@@ -0,0 +1,7 @@
+export { McpConfig as McpConfigSchema } from "./config.js";
+export { loadMcpConfig } from "./config-loader.js";
+export { isSkillsExtensionEnabled } from "./config.js";
+export { McpClientManager } from "./client-manager.js";
+export { McpPolicy, McpPolicyError, isReadOnlyToolCall, validateToolArguments, } from "./policy.js";
+export { McpiHostApproval } from "./host-approval.js";
+export { noSkillsExtensionGateway } from "./gateway-defaults.js";

package/dist/mcp/policy.d.ts

@@ -0,0 +1,314 @@
+import type { ReadResourceResult, Resource, ResourceTemplateType } from "@modelcontextprotocol/client";
+import type { DirectoryReadResult, SkillsGetResult, SkillsListResult } from "../skills/sep2640/protocol.js";
+import type { TerminalCallToolResult } from "./call-tool-result.js";
+import type { McpTool } from "./client-manager.js";
+/**
+ * Which execution path asked for an MCP operation. Recorded on every audit
+ * record so a denial can be attributed to the surface that produced it.
+ */
+export type McpCallSource = "proxy" | "code-mode" | "tool-cli";
+/**
+ * Which skill workflow asked for a resource read. Resource authorization is
+ * narrower than tool authorization: only skill discovery and skill loading
+ * currently need it, and each is bound to a single server origin.
+ *
+ * `skills-extension` covers the draft SEP-2640 surface. It is a distinct source
+ * so a read authorized by a skill's declared `resources` set can never be
+ * confused with one authorized by the legacy `skill://…/SKILL.md` convention,
+ * and so the audit log says which contract produced each read.
+ */
+export type McpResourceSource = "skill-discovery" | "skill-load" | "skills-extension" | "tool-cli";
+export type McpPolicyDenialReason = "server_not_connected" | "tool_not_discovered" | "tool_gated" | "invalid_arguments" | "permission_denied" | "approval_declined" | "approval_unavailable" | "cancelled" | "resource_not_discovered" | "resource_origin_mismatch"
+/** The server never declared the skills extension, so its methods are off-limits. */
+ | "extension_not_declared"
+/** The server declared the extension but not `directoryRead`. */
+ | "directory_read_unavailable";
+export interface McpPolicyErrorInit {
+    reason: McpPolicyDenialReason;
+    message: string;
+    source: McpCallSource | McpResourceSource;
+    serverName: string;
+    toolName?: string;
+    uri?: string;
+    alternatives?: readonly string[];
+}
+/** A denial raised by the policy boundary before any upstream MCP request. */
+export declare class McpPolicyError extends Error {
+    readonly reason: McpPolicyDenialReason;
+    readonly source: McpCallSource | McpResourceSource;
+    readonly serverName: string;
+    readonly toolName?: string;
+    readonly uri?: string;
+    readonly alternatives: readonly string[];
+    constructor(init: McpPolicyErrorInit);
+}
+export type McpApprovalOutcome = "granted" | "reused" | "declined" | "unavailable";
+export interface McpAuditRecord {
+    readonly id: string;
+    readonly source: McpCallSource | McpResourceSource;
+    readonly operation: "tool" | "resource" | "resource-list" | "resource-templates" | "skill-grant" | "skill-list" | "skill-get" | "skill-directory";
+    readonly serverName: string;
+    readonly toolName?: string;
+    readonly uri?: string;
+    readonly decision: "allowed" | "denied";
+    readonly reason?: McpPolicyDenialReason;
+    readonly approval?: McpApprovalOutcome;
+    readonly timestampMs: number;
+}
+/** Describes a pending confirmation so hosts can render an accurate prompt. */
+export interface McpApprovalRequest {
+    readonly kind: "tool-call" | "skill-grant";
+    readonly source: McpCallSource;
+    readonly serverName: string;
+    readonly toolName?: string;
+    readonly skillName?: string;
+    readonly grantedTools?: readonly string[];
+    readonly title: string;
+    readonly message: string;
+    readonly signal?: AbortSignal;
+}
+/**
+ * Host confirmation seam. Returning `undefined` means no decision could be
+ * obtained (no interactive UI, or the prompt was cancelled); it is never
+ * treated as approval.
+ */
+export interface McpApprovalPrompt {
+    confirm(request: McpApprovalRequest): Promise<boolean | undefined>;
+}
+/** The upstream surface the policy is allowed to dispatch to. */
+export interface McpPolicyGateway {
+    getConnectedServers(): string[];
+    getToolsForServer(name: string): McpTool[];
+    callTool(serverName: string, toolName: string, args: Record<string, unknown>, signal?: AbortSignal): Promise<TerminalCallToolResult>;
+    listResources(serverName: string, signal?: AbortSignal): Promise<Resource[]>;
+    listResourceTemplates(serverName: string, signal?: AbortSignal): Promise<ResourceTemplateType[]>;
+    readResource(serverName: string, uri: string, signal?: AbortSignal): Promise<ReadResourceResult>;
+    /**
+     * The settings a server declared for one MCP extension in its `initialize`
+     * response, or `undefined` when it did not declare that extension at all.
+     *
+     * Read fresh on every call rather than cached as a boolean: the policy asks
+     * this immediately before each extension request so a reconnect that drops
+     * the extension cannot leave a stale "enabled" flag behind.
+     */
+    getExtensionCapability(serverName: string, extensionName: string): Record<string, unknown> | undefined;
+    /** Draft SEP-2640 `skills/list`. */
+    requestSkillsList(serverName: string, cursor?: string, signal?: AbortSignal): Promise<SkillsListResult>;
+    /** Draft SEP-2640 `skills/get`. */
+    requestSkillsGet(serverName: string, uri: string, signal?: AbortSignal): Promise<SkillsGetResult>;
+    /** Draft SEP-2640 `resources/directory/read`. */
+    requestDirectoryRead(serverName: string, uri: string, cursor?: string, signal?: AbortSignal): Promise<DirectoryReadResult>;
+}
+export interface McpToolCallRequest {
+    source: McpCallSource;
+    serverName: string;
+    toolName: string;
+    args: Record<string, unknown>;
+    signal?: AbortSignal;
+}
+export interface McpResourceReadRequest {
+    source: McpResourceSource;
+    serverName: string;
+    uri: string;
+    /**
+     * Required for `skills-extension` reads: which skill's declared `resources`
+     * set authorizes this URI. Naming the skill is what keeps the allowlist
+     * per-skill instead of pooling every declared file on the server.
+     */
+    skillUri?: string;
+    signal?: AbortSignal;
+}
+export interface McpResourceListRequest {
+    source: "tool-cli";
+    serverName: string;
+    signal?: AbortSignal;
+}
+/** Minimum skill shape the policy needs; mirrors `McpSkillMetadata`. */
+export interface McpPolicySkill {
+    readonly name: string;
+    readonly uri: string;
+    readonly serverName: string;
+    readonly allowedTools: readonly string[];
+    /**
+     * A digest over the exact content this grant covers, when the origin can
+     * supply one (SEP-2640 servers can; the legacy `skill://` convention cannot).
+     *
+     * Folding it into the grant key is what makes an approval content-bound: if a
+     * later listing rotates a digest, adds a file, or drops one, the key changes,
+     * the prior approval no longer matches, and the user is asked again rather
+     * than having yesterday's consent silently applied to today's bytes.
+     */
+    readonly contentFingerprint?: string;
+}
+export type SkillGrantOutcome = {
+    readonly status: "granted";
+    readonly activatedTools: readonly string[];
+} | {
+    readonly status: "reused";
+    readonly activatedTools: readonly string[];
+} | {
+    readonly status: "declined";
+    readonly message: string;
+} | {
+    readonly status: "unavailable";
+    readonly message: string;
+};
+export interface McpPolicyOptions {
+    gateway: McpPolicyGateway;
+    approvals?: McpApprovalPrompt;
+    /** Bounded audit ring buffer size. */
+    auditLimit?: number;
+    onAudit?: (record: McpAuditRecord) => void;
+}
+/**
+ * The single MCP policy and dispatch boundary.
+ *
+ * Every execution path — deferred/direct proxy tools, Code Mode dispatch,
+ * tool-cli provider RPC, and skill resource reads — crosses this class exactly
+ * once per operation. Discovery, gating, argument validation, permission
+ * semantics, approval, cancellation, and audit all happen here, and nothing
+ * reaches an MCP server without passing through `dispatchToolCall` /
+ * `dispatchResourceRead` below.
+ */
+export declare class McpPolicy {
+    private readonly gateway;
+    private readonly approvals;
+    private readonly auditLimit;
+    private readonly onAudit;
+    /** Tools that require an approved skill grant before any path may call them. */
+    private readonly gatedTools;
+    /** Tools unlocked by an approved, activated skill grant. */
+    private readonly enabledTools;
+    /** Approved skill grant keys, bound to server origin plus grant content. */
+    private readonly approvedGrants;
+    /** Skill URIs registered per server origin, for `skill-load` authorization. */
+    private readonly skillUrisByServer;
+    /** URIs a server itself listed in the current discovery pass. */
+    private readonly discoveredUrisByServer;
+    /**
+     * Per-skill SEP-2640 resource allowlists, keyed by `serverName\0skillUri`.
+     *
+     * A skill's declared `resources` set is the *only* thing that authorizes a
+     * `skills-extension` read. Storing it per skill rather than per server means a
+     * file listed by skill A cannot be read while "loading" skill B.
+     */
+    private readonly extensionResourceUris;
+    private readonly audit;
+    private sequence;
+    constructor(options: McpPolicyOptions);
+    /** Register discovered skills so their tools are gated and their URIs bound. */
+    registerSkills(skills: readonly McpPolicySkill[]): void;
+    /**
+     * Bind a SEP-2640 skill's declared resource URIs so they become readable
+     * under the `skills-extension` source — and nothing else does.
+     *
+     * The set replaces any previous one for that skill, so a rotated listing
+     * narrows access immediately instead of accumulating stale grants.
+     */
+    registerSkillResources(serverName: string, skillUri: string, resourceUris: readonly string[]): void;
+    /** Every tool name currently gated behind an unapproved skill grant. */
+    getGatedToolNames(): string[];
+    /** Skills that gate `toolName`, for actionable block messages. */
+    getGatingSkills(toolName: string): string[];
+    /** True when a tool is discovered but still requires an approved skill grant. */
+    isGated(toolName: string): boolean;
+    reset(): void;
+    getVisibleServers(): string[];
+    /**
+     * The exact discovered schema set a discovery surface may see. Gated tools
+     * are omitted entirely, so a surface cannot learn a hidden tool's name or
+     * schema and then try to call it.
+     */
+    getVisibleTools(serverName: string): McpTool[];
+    /**
+     * Activate an MCP-origin skill's `allowed-tools` grant.
+     *
+     * The grant is origin- and content-bound: the key covers the server name, the
+     * skill URI, and a digest of the exact tool list being granted. A previously
+     * approved identical grant is reused without re-prompting, so no path ever
+     * asks the user twice for the same authority. Declined, cancelled, and
+     * unavailable outcomes all leave the tools gated.
+     */
+    activateSkillGrant(skill: McpPolicySkill, signal?: AbortSignal): Promise<SkillGrantOutcome>;
+    /**
+     * Authorize and dispatch a tool call. Every execution path funnels here, and
+     * upstream is reached only after all checks below pass.
+     */
+    callTool(request: McpToolCallRequest): Promise<TerminalCallToolResult>;
+    /**
+     * The server's declared settings for the draft skills extension, or
+     * `undefined` when it did not declare it.
+     *
+     * Resolved fresh on every call. The extension is negotiated in `initialize`,
+     * but a reconnect can change the answer, and caching "this server supports
+     * skills" would let a stale yes outlive the negotiation that produced it.
+     */
+    getSkillsExtension(serverName: string): Record<string, unknown> | undefined;
+    /** True when the server declared `directoryRead: true` on the extension. */
+    supportsSkillDirectoryRead(serverName: string): boolean;
+    /**
+     * Draft SEP-2640 `skills/list`.
+     *
+     * Refused unless the server declared the extension: an undeclared method is
+     * not a method this host is entitled to probe for.
+     */
+    listMcpSkills(serverName: string, cursor?: string, signal?: AbortSignal): Promise<SkillsListResult>;
+    /** Draft SEP-2640 `skills/get`. */
+    getMcpSkill(serverName: string, uri: string, signal?: AbortSignal): Promise<SkillsGetResult>;
+    /**
+     * Draft SEP-2640 `resources/directory/read`.
+     *
+     * Refused when the server declared the extension without `directoryRead`.
+     * The setting defaults to false, so silence means no.
+     */
+    readSkillDirectory(serverName: string, uri: string, cursor?: string, signal?: AbortSignal): Promise<DirectoryReadResult>;
+    /**
+     * List the resources visible to tool-cli.
+     *
+     * `skill://` is a separate authorization domain: those resources carry
+     * workflow instructions and grants, so they remain reachable only through
+     * skill discovery/load and can never be enumerated through the shell bridge.
+     */
+    listResources(request: McpResourceListRequest): Promise<Resource[]>;
+    /** List policy-visible resource templates for tool-cli. */
+    listResourceTemplates(request: McpResourceListRequest): Promise<ResourceTemplateType[]>;
+    /**
+     * List a server's skill resources and remember them as this pass's discovery
+     * candidates. Only URIs seen here become readable under `skill-discovery`.
+     */
+    listSkillResources(serverName: string, signal?: AbortSignal): Promise<Resource[]>;
+    /**
+     * Authorize and dispatch a resource read using the same policy discipline as
+     * tool calls: origin binding, discovery, cancellation, and audit.
+     */
+    readResource(request: McpResourceReadRequest): Promise<ReadResourceResult>;
+    getAuditLog(): readonly McpAuditRecord[];
+    private enableTools;
+    private allowedReadUris;
+    private isSkillOwnedResource;
+    private findOtherOrigin;
+    /**
+     * Refuse an extension method unless the server is connected and declared the
+     * extension. Records the denial before throwing, like every other refusal.
+     */
+    private assertSkillsExtension;
+    private denyExtension;
+    private requestApproval;
+    private record;
+}
+/**
+ * A tool call is treated as read-only only when the server explicitly declares
+ * it read-only and does not also declare it destructive. This is the same
+ * predicate Code Mode uses for dispatch eligibility.
+ */
+export declare function isReadOnlyToolCall(tool: McpTool): boolean;
+/**
+ * Conservative, dependency-free structural validation of tool arguments.
+ *
+ * It rejects only what a server's own declared schema unambiguously forbids —
+ * missing required properties, undeclared properties under
+ * `additionalProperties: false`, and clearly mismatched primitive types — so
+ * schemas using `$ref`, `allOf`, or other composition keywords are not
+ * incorrectly refused. Returns a message when invalid, otherwise `undefined`.
+ */
+export declare function validateToolArguments(schema: McpTool["inputSchema"] | undefined, args: unknown): string | undefined;