@sammorrowdrums/mcpi-ext 0.2.0 → 1.0.0

package/dist/skills/discover.js

@@ -0,0 +1,85 @@
+import { parseFrontmatter } from "@sammorrowdrums/mcpi";
+/**
+ * Discover skills from a connected MCP server by reading its resources.
+ *
+ * Looks for resources with `skill://` URIs ending in `/SKILL.md`,
+ * reads each one, and parses YAML frontmatter for skill metadata.
+ *
+ * All resource I/O goes through the shared policy boundary, so a server can
+ * only ever surface its own skill resources.
+ */
+export async function discoverSkillsFromServer(policy, serverName, log = console.error, signal) {
+    const skills = [];
+    let skillResources;
+    try {
+        skillResources = await policy.listSkillResources(serverName, signal);
+    }
+    catch {
+        log(`[skills] Server "${serverName}" does not support resources/list, skipping skill discovery`);
+        return skills;
+    }
+    if (skillResources.length === 0)
+        return skills;
+    for (const resource of skillResources) {
+        try {
+            const result = await policy.readResource({
+                source: "skill-discovery",
+                serverName,
+                uri: resource.uri,
+                ...(signal ? { signal } : {}),
+            });
+            const textContent = result.contents.find((c) => "text" in c);
+            if (!textContent) {
+                log(`[skills] Skill resource ${resource.uri} returned no text content, skipping`);
+                continue;
+            }
+            const parsed = parseFrontmatter(textContent.text);
+            const fm = parsed.frontmatter;
+            const name = fm.name ?? resource.name;
+            const description = fm.description ?? "";
+            const allowedTools = parseAllowedTools(fm);
+            if (!name) {
+                log(`[skills] Skill at ${resource.uri} has no name, skipping`);
+                continue;
+            }
+            skills.push({
+                name,
+                description,
+                uri: resource.uri,
+                serverName,
+                allowedTools,
+            });
+            log(`[skills] Discovered skill "${name}" from "${serverName}" (${allowedTools.length} gated tools)`);
+        }
+        catch (err) {
+            log(`[skills] Failed to read skill ${resource.uri}: ${err.message}`);
+        }
+    }
+    return skills.sort((left, right) => compareStrings(left.name, right.name));
+}
+function compareStrings(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+/**
+ * Parse tool names from frontmatter, supporting both formats:
+ * - Current: `allowed-tools: [tool_a, tool_b]` (YAML array)
+ * - Proposed spec: `metadata.io.modelcontextprotocol/tools: "tool_a tool_b"` (space-separated)
+ *
+ * Prefers the proposed spec format when both are present.
+ */
+function parseAllowedTools(fm) {
+    // Proposed spec format: metadata.io.modelcontextprotocol/tools (space-separated string)
+    const metadata = fm.metadata;
+    if (metadata) {
+        const specTools = metadata["io.modelcontextprotocol/tools"];
+        if (typeof specTools === "string" && specTools.trim().length > 0) {
+            return specTools.trim().split(/\s+/);
+        }
+    }
+    // Current format: allowed-tools (YAML array)
+    const legacy = fm["allowed-tools"];
+    if (Array.isArray(legacy)) {
+        return legacy.filter((v) => typeof v === "string");
+    }
+    return [];
+}

package/dist/skills/format.d.ts

@@ -0,0 +1,13 @@
+import type { McpSkillMetadata } from "./skill-registry.js";
+/**
+ * Format MCP-discovered skills for inclusion in the system prompt.
+ *
+ * Produces XML matching Pi's native `formatSkillsForPrompt` structure,
+ * but references the `load_skill` tool instead of `read` and uses
+ * `mcp:<serverName>` as the location.
+ *
+ * This is the catalogue of what exists. Which kind of task suits a skill at all
+ * is decided by the `<execution_routing>` section, which reports skill
+ * availability whether or not any were discovered.
+ */
+export declare function formatMcpSkillsForPrompt(skills: McpSkillMetadata[]): string;

package/dist/skills/format.js

@@ -0,0 +1,42 @@
+function escapeXml(str) {
+    return str
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}
+/**
+ * Format MCP-discovered skills for inclusion in the system prompt.
+ *
+ * Produces XML matching Pi's native `formatSkillsForPrompt` structure,
+ * but references the `load_skill` tool instead of `read` and uses
+ * `mcp:<serverName>` as the location.
+ *
+ * This is the catalogue of what exists. Which kind of task suits a skill at all
+ * is decided by the `<execution_routing>` section, which reports skill
+ * availability whether or not any were discovered.
+ */
+export function formatMcpSkillsForPrompt(skills) {
+    if (skills.length === 0)
+        return "";
+    const lines = [
+        "",
+        "",
+        "Use when a task matches one of the domain workflows these MCP skills document.",
+        "Call load_skill with the skill's name to read its instructions before working through it.",
+        "MCP tools are deferred — registered for dispatch but not described in this prompt. A skill's",
+        "declared tools are enabled only after you approve its grant; declining leaves them locked.",
+        "",
+        "<available_mcp_skills>",
+    ];
+    for (const skill of skills) {
+        lines.push("  <skill>");
+        lines.push(`    <name>${escapeXml(skill.name)}</name>`);
+        lines.push(`    <description>${escapeXml(skill.description)}</description>`);
+        lines.push(`    <server>${escapeXml(skill.serverName)}</server>`);
+        lines.push("  </skill>");
+    }
+    lines.push("</available_mcp_skills>");
+    return lines.join("\n");
+}

package/dist/skills/index.d.ts

@@ -0,0 +1,6 @@
+export { SkillRegistry, type McpSkillMetadata, type SkillNameCollision } from "./skill-registry.js";
+export { formatMcpSkillsForPrompt } from "./format.js";
+export { createLoadSkillTool, type LoadSkillDeps, type LoadSkillDetails, } from "./load-skill-tool.js";
+export { discoverSkillsFromServer } from "./discover.js";
+export { registerMcpToolProxies } from "./mcp-tool-proxy.js";
+export { SKILLS_EXTENSION_NAME, SKILLS_EXTENSION_REVISION, SKILLS_EXTENSION_STATUS, SkillsExtensionClient, describeNegotiation, discoverSkillsViaExtension, loadSkillDocument, readSkillResource, skillsExtensionDiagnostic, type Sep2640DiscoveryResult, type SkillEntry, type SkillsListing, } from "./sep2640/index.js";

package/dist/skills/index.js

@@ -0,0 +1,6 @@
+export { SkillRegistry } from "./skill-registry.js";
+export { formatMcpSkillsForPrompt } from "./format.js";
+export { createLoadSkillTool, } from "./load-skill-tool.js";
+export { discoverSkillsFromServer } from "./discover.js";
+export { registerMcpToolProxies } from "./mcp-tool-proxy.js";
+export { SKILLS_EXTENSION_NAME, SKILLS_EXTENSION_REVISION, SKILLS_EXTENSION_STATUS, SkillsExtensionClient, describeNegotiation, discoverSkillsViaExtension, loadSkillDocument, readSkillResource, skillsExtensionDiagnostic, } from "./sep2640/index.js";

package/dist/skills/load-skill-tool.d.ts

@@ -0,0 +1,56 @@
+import type { AgentToolResult, ExtensionContext } from "@sammorrowdrums/mcpi";
+import { Type, type Static } from "typebox";
+import type { McpPolicy } from "../mcp/policy.js";
+import type { SkillsExtensionClient } from "./sep2640/client.js";
+import type { SkillRegistry } from "./skill-registry.js";
+declare const LoadSkillParams: Type.TObject<{
+    name: Type.TString;
+}>;
+type LoadSkillInput = Static<typeof LoadSkillParams>;
+export interface LoadSkillDeps {
+    registry: SkillRegistry;
+    policy: McpPolicy;
+    /**
+     * Client for the draft skills extension.
+     *
+     * Required to load a skill discovered over SEP-2640: that contract only holds
+     * if the digests are re-fetched at load time, so a skill with no client to
+     * ask is refused rather than loaded unverified.
+     */
+    skillsClient?: SkillsExtensionClient;
+}
+export interface LoadSkillDetails {
+    skillName: string;
+    serverName?: string;
+    activatedTools?: string[];
+    error?: string;
+    /** True when the content was verified against SEP-2640 digests. */
+    verified?: boolean;
+    /** True when the server's resource set changed since discovery. */
+    resourceSetRotated?: boolean;
+}
+/**
+ * Create the load_skill tool definition.
+ *
+ * When the model calls this tool, it:
+ * 1. Looks up the skill in the registry
+ * 2. Reads the full SKILL.md content through the shared policy boundary
+ * 3. Asks the user to approve the skill's `allowed-tools` grant
+ * 4. Returns the SKILL.md body (the skill names its tools, and the model
+ *    already has their schemas from the deferred tools array)
+ *
+ * The grant is requested before the body is returned, so a server cannot use
+ * skill instructions to influence a pending authorization decision. A declined
+ * or unavailable approval leaves every gated tool locked.
+ */
+export declare function createLoadSkillTool(deps: LoadSkillDeps): {
+    name: string;
+    label: string;
+    description: string;
+    promptSnippet: string;
+    parameters: Type.TObject<{
+        name: Type.TString;
+    }>;
+    execute(_toolCallId: string, params: LoadSkillInput, signal: AbortSignal | undefined, _onUpdate: undefined, _ctx: ExtensionContext): Promise<AgentToolResult<LoadSkillDetails>>;
+};
+export {};

package/dist/skills/load-skill-tool.js

@@ -0,0 +1,183 @@
+import { stripFrontmatter } from "@sammorrowdrums/mcpi";
+import { Type } from "typebox";
+import { loadSkillDocument, SkillFetchBudget } from "./sep2640/load.js";
+import { resourceSetFingerprint } from "./sep2640/protocol.js";
+const LoadSkillParams = Type.Object({
+    name: Type.String({ description: "Name of the MCP skill to load" }),
+});
+/**
+ * Create the load_skill tool definition.
+ *
+ * When the model calls this tool, it:
+ * 1. Looks up the skill in the registry
+ * 2. Reads the full SKILL.md content through the shared policy boundary
+ * 3. Asks the user to approve the skill's `allowed-tools` grant
+ * 4. Returns the SKILL.md body (the skill names its tools, and the model
+ *    already has their schemas from the deferred tools array)
+ *
+ * The grant is requested before the body is returned, so a server cannot use
+ * skill instructions to influence a pending authorization decision. A declined
+ * or unavailable approval leaves every gated tool locked.
+ */
+export function createLoadSkillTool(deps) {
+    const { registry, policy, skillsClient } = deps;
+    return {
+        name: "load_skill",
+        label: "Load Skill",
+        description: "Use when a task matches an MCP skill's documented workflow and you need its instructions. Returns the skill body and requests approval to enable the tools it declares; the tools stay locked unless that grant is approved.",
+        promptSnippet: "Use when a task matches an MCP skill's workflow: returns its instructions and, once you approve the grant, enables the tools it declares.",
+        parameters: LoadSkillParams,
+        async execute(_toolCallId, params, signal, _onUpdate, _ctx) {
+            const skill = registry.get(params.name);
+            if (!skill) {
+                const available = registry
+                    .getAll()
+                    .map((s) => s.name)
+                    .join(", ");
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Skill "${params.name}" not found. Available skills: ${available || "(none)"}`,
+                        },
+                    ],
+                    details: { skillName: params.name, error: "not_found" },
+                };
+            }
+            const verifiable = skill.origin === "sep2640";
+            if (verifiable && !skillsClient) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Skill "${params.name}" was discovered over the draft skills extension, but no extension client is available to verify it. Refusing to load unverified content.`,
+                        },
+                    ],
+                    details: {
+                        skillName: params.name,
+                        serverName: skill.serverName,
+                        error: "verification_unavailable",
+                        verified: false,
+                    },
+                };
+            }
+            let body;
+            let entry;
+            let rotated = false;
+            try {
+                if (verifiable && skillsClient) {
+                    // Re-fetch the entry so verification uses the digests the server is
+                    // publishing now, not the ones it published at discovery.
+                    entry = await skillsClient.getSkill(skill.serverName, skill.uri, signal);
+                    const fingerprint = resourceSetFingerprint(entry);
+                    rotated =
+                        skill.contentFingerprint !== undefined && skill.contentFingerprint !== fingerprint;
+                    policy.registerSkillResources(skill.serverName, entry.uri, entry.resources === "dynamic" ? [] : entry.resources.map((ref) => ref.uri));
+                    const document = await loadSkillDocument({
+                        policy,
+                        entry,
+                        serverName: skill.serverName,
+                        budget: new SkillFetchBudget(),
+                        ...(signal ? { signal } : {}),
+                    });
+                    body = stripFrontmatter(document.text);
+                }
+                else {
+                    const result = await policy.readResource({
+                        source: "skill-load",
+                        serverName: skill.serverName,
+                        uri: skill.uri,
+                        ...(signal ? { signal } : {}),
+                    });
+                    const textContent = result.contents.find((c) => "text" in c);
+                    if (!textContent) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `Skill "${params.name}" returned no text content.`,
+                                },
+                            ],
+                            details: {
+                                skillName: params.name,
+                                serverName: skill.serverName,
+                                error: "no_content",
+                            },
+                        };
+                    }
+                    body = stripFrontmatter(textContent.text);
+                }
+            }
+            catch (err) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Failed to read skill "${params.name}" from server "${skill.serverName}": ${err.message}`,
+                        },
+                    ],
+                    details: {
+                        skillName: params.name,
+                        serverName: skill.serverName,
+                        error: err.message,
+                        verified: false,
+                    },
+                };
+            }
+            // Approval is bound to the resource set the server just published. A
+            // rotated set produces a different grant key, so a previously approved
+            // skill is re-prompted instead of inheriting the old answer.
+            const grantSubject = entry ? withFreshContent(skill, entry) : skill;
+            const grant = await policy.activateSkillGrant(grantSubject, signal);
+            if (grant.status === "granted" || grant.status === "reused") {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: body,
+                        },
+                    ],
+                    details: {
+                        skillName: params.name,
+                        serverName: skill.serverName,
+                        activatedTools: [...grant.activatedTools],
+                        verified: verifiable,
+                        resourceSetRotated: rotated,
+                    },
+                };
+            }
+            return {
+                content: [{ type: "text", text: grant.message }],
+                details: {
+                    skillName: params.name,
+                    serverName: skill.serverName,
+                    activatedTools: [],
+                    error: grant.status === "declined" ? "approval_declined" : "approval_unavailable",
+                    verified: verifiable,
+                    resourceSetRotated: rotated,
+                },
+            };
+        },
+    };
+}
+/**
+ * Rebuild skill metadata from the entry the server just served.
+ *
+ * Both the gated tool names and the content fingerprint come from the verified
+ * entry rather than the discovery-time copy, so an `allowed-tools` list that
+ * grew since discovery cannot ride in on an approval the user gave for a
+ * smaller one.
+ */
+function withFreshContent(skill, entry) {
+    const declared = entry.frontmatter["allowed-tools"];
+    const allowedTools = Array.isArray(declared)
+        ? declared.filter((value) => typeof value === "string")
+        : typeof declared === "string" && declared.trim().length > 0
+            ? declared.trim().split(/\s+/)
+            : [];
+    return {
+        ...skill,
+        allowedTools,
+        contentFingerprint: resourceSetFingerprint(entry),
+    };
+}

package/dist/skills/mcp-tool-proxy.d.ts

@@ -0,0 +1,7 @@
+import type { ExtensionAPI } from "@sammorrowdrums/mcpi";
+import type { McpClientManager } from "../mcp/client-manager.js";
+import type { McpPolicy } from "../mcp/policy.js";
+/**
+ * Register MCP tools as deferred mcpi proxies backed by the shared policy boundary.
+ */
+export declare function registerMcpToolProxies(toolNames: string[], manager: McpClientManager, policy: McpPolicy, pi: ExtensionAPI): string[];

package/dist/skills/mcp-tool-proxy.js

@@ -0,0 +1,41 @@
+import { Type } from "typebox";
+import { renderTerminalCallToolResult } from "../mcp/call-tool-result.js";
+/**
+ * Register MCP tools as deferred mcpi proxies backed by the shared policy boundary.
+ */
+export function registerMcpToolProxies(toolNames, manager, policy, pi) {
+    const registered = [];
+    const existingTools = new Set(pi.getAllTools().map((tool) => tool.name));
+    const toolsByName = new Map(manager.getTools().map((tool) => [tool.name, tool]));
+    for (const name of toolNames) {
+        if (existingTools.has(name)) {
+            registered.push(name);
+            continue;
+        }
+        const tool = toolsByName.get(name);
+        if (!tool)
+            continue;
+        pi.registerTool(createMcpToolProxy(policy, tool));
+        registered.push(name);
+    }
+    return registered;
+}
+function createMcpToolProxy(policy, tool) {
+    return {
+        name: tool.name,
+        label: tool.name,
+        description: tool.description ?? `MCP tool from ${tool.serverName}`,
+        deferred: true,
+        parameters: Type.Unsafe(tool.inputSchema),
+        async execute(_toolCallId, params, signal, _onUpdate, _ctx) {
+            const terminal = await policy.callTool({
+                source: "proxy",
+                serverName: tool.serverName,
+                toolName: tool.name,
+                args: params,
+                ...(signal ? { signal } : {}),
+            });
+            return renderTerminalCallToolResult(terminal);
+        },
+    };
+}

package/dist/skills/sep2640/client.d.ts

@@ -0,0 +1,91 @@
+import type { McpPolicy } from "../../mcp/policy.js";
+import { type DirectoryResource, type SkillEntry } from "./protocol.js";
+/** What a listing pass observed, including why it may be incomplete. */
+export interface SkillsListing {
+    /** Entries that passed pre-fetch validation. */
+    readonly skills: SkillEntry[];
+    /**
+     * Entries the server returned that this host refused to consider, with the
+     * reason. Surfaced rather than silently dropped so a malformed skill is
+     * visible instead of just missing.
+     */
+    readonly rejected: {
+        readonly uri: string;
+        readonly reason: string;
+    }[];
+    /**
+     * True when the server had more pages than this host was willing to walk.
+     *
+     * SEP-2640 forbids treating a listing as proof of what a server has; this
+     * flag is how that uncertainty travels with the data instead of being
+     * flattened into "these are the skills".
+     */
+    readonly truncated: boolean;
+    /** Whether this listing came from the in-memory freshness cache. */
+    readonly fromCache: boolean;
+}
+export interface SkillsExtensionClientOptions {
+    readonly policy: McpPolicy;
+    /** Injectable clock; defaults to `Date.now`. */
+    readonly now?: () => number;
+}
+/**
+ * A client for the draft SEP-2640 skills extension.
+ *
+ * Every request goes through {@link McpPolicy}, which re-checks the negotiated
+ * capability immediately before dispatch. This class therefore never caches
+ * "server X supports skills" — it caches only listing *content*, and only when
+ * the server asked it to with terms this host is willing to honour.
+ */
+export declare class SkillsExtensionClient {
+    private readonly policy;
+    private readonly now;
+    private readonly listCache;
+    constructor(options: SkillsExtensionClientOptions);
+    /** True when the server declared the extension on the live connection. */
+    supports(serverName: string): boolean;
+    /** True when the server additionally declared `directoryRead: true`. */
+    supportsDirectoryRead(serverName: string): boolean;
+    /** The declared extension settings, for diagnostics. */
+    capability(serverName: string): Record<string, unknown> | undefined;
+    /**
+     * Walk `skills/list` to completion, validating each entry before it is
+     * admitted.
+     *
+     * Pagination stops at {@link MAX_SKILL_LIST_PAGES}; the result is then marked
+     * `truncated` rather than presented as the whole set. A server that returns
+     * the same cursor twice is also treated as truncated, which stops a cursor
+     * loop from becoming an unbounded request stream.
+     */
+    listSkills(serverName: string, signal?: AbortSignal): Promise<SkillsListing>;
+    /**
+     * Fetch one skill's authoritative entry with `skills/get`.
+     *
+     * Always goes to the server: `skills/get` is what re-establishes current
+     * digests after a verification failure, so serving it from cache would defeat
+     * the recovery path the spec defines.
+     */
+    getSkill(serverName: string, uri: string, signal?: AbortSignal): Promise<SkillEntry>;
+    /**
+     * Enumerate a skill directory, when the server declared `directoryRead`.
+     *
+     * Directory listings are navigational only. Nothing they return becomes
+     * readable: a file is readable because the skill entry lists it with a
+     * digest, and a directory cannot add entries to that list.
+     */
+    readDirectory(serverName: string, uri: string, signal?: AbortSignal): Promise<DirectoryResource[]>;
+    /** Drop cached listings; call on disconnect or reset. */
+    clearCache(serverName?: string): void;
+    private readCache;
+    /**
+     * Cache a listing only when the server asked for it in terms this host
+     * understands.
+     *
+     * `cacheScope`'s value set is defined by SEP-2549, not SEP-2640, so an
+     * unrecognised scope is treated as "do not cache" rather than guessed at. A
+     * truncated listing is never cached, because caching an incomplete answer is
+     * exactly the "empty listing means no skills" mistake the spec warns against,
+     * just with a longer lifetime.
+     */
+    private writeCache;
+}