@sammorrowdrums/mcpi-ext 0.2.0 → 0.2.1

package/src/skills/discover.ts

@@ -1,81 +0,0 @@
-import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { parseFrontmatter } from "@sammorrowdrums/mcpi";
-import type { McpSkillMetadata } from "./skill-registry.js";
-
-/**
- * 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.
- */
-export async function discoverSkillsFromServer(
-  client: Client,
-  serverName: string,
-  log: (msg: string) => void = console.error,
-): Promise<McpSkillMetadata[]> {
-  const skills: McpSkillMetadata[] = [];
-
-  let resources: { uri: string; name: string }[];
-  try {
-    const result = await client.listResources();
-    resources = result.resources;
-  } catch {
-    log(
-      `[skills] Server "${serverName}" does not support resources/list, skipping skill discovery`,
-    );
-    return skills;
-  }
-
-  const skillResources = resources.filter(
-    (r) => r.uri.startsWith("skill://") && r.uri.endsWith("/SKILL.md"),
-  );
-
-  if (skillResources.length === 0) return skills;
-
-  for (const resource of skillResources) {
-    try {
-      const result = await client.readResource({ uri: resource.uri });
-      const textContent = result.contents.find(
-        (c): c is { uri: string; text: string } => "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 as Record<string, unknown>;
-      const name = (fm.name as string | undefined) ?? resource.name;
-      const description = (fm.description as string | undefined) ?? "";
-      const allowedTools = parseAllowedTools(fm["allowed-tools"]);
-
-      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 as Error).message}`);
-    }
-  }
-
-  return skills;
-}
-
-function parseAllowedTools(value: unknown): string[] {
-  if (Array.isArray(value)) {
-    return value.filter((v): v is string => typeof v === "string");
-  }
-  return [];
-}

package/src/skills/format.test.ts

@@ -1,70 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { formatMcpSkillsForPrompt } from "./format.js";
-import type { McpSkillMetadata } from "./skill-registry.js";
-
-describe("formatMcpSkillsForPrompt", () => {
-  it("returns empty string for no skills", () => {
-    expect(formatMcpSkillsForPrompt([])).toBe("");
-  });
-
-  it("formats a single skill", () => {
-    const skills: McpSkillMetadata[] = [
-      {
-        name: "weather",
-        description: "Check weather forecasts",
-        uri: "skill://weather/SKILL.md",
-        serverName: "weather-srv",
-        allowedTools: ["check_weather"],
-      },
-    ];
-
-    const result = formatMcpSkillsForPrompt(skills);
-    expect(result).toContain("<available_mcp_skills>");
-    expect(result).toContain("</available_mcp_skills>");
-    expect(result).toContain("<name>weather</name>");
-    expect(result).toContain("<description>Check weather forecasts</description>");
-    expect(result).toContain("<server>weather-srv</server>");
-    expect(result).toContain("load_skill");
-    expect(result).toContain("deferred");
-  });
-
-  it("formats multiple skills", () => {
-    const skills: McpSkillMetadata[] = [
-      {
-        name: "a",
-        description: "Skill A",
-        uri: "skill://a/SKILL.md",
-        serverName: "srv",
-        allowedTools: [],
-      },
-      {
-        name: "b",
-        description: "Skill B",
-        uri: "skill://b/SKILL.md",
-        serverName: "srv",
-        allowedTools: ["tool_b"],
-      },
-    ];
-
-    const result = formatMcpSkillsForPrompt(skills);
-    expect(result).toContain("<name>a</name>");
-    expect(result).toContain("<name>b</name>");
-  });
-
-  it("escapes XML characters", () => {
-    const skills: McpSkillMetadata[] = [
-      {
-        name: "test",
-        description: 'Uses <tags> & "quotes"',
-        uri: "skill://test/SKILL.md",
-        serverName: "srv",
-        allowedTools: [],
-      },
-    ];
-
-    const result = formatMcpSkillsForPrompt(skills);
-    expect(result).toContain("&lt;tags&gt;");
-    expect(result).toContain("&amp;");
-    expect(result).toContain("&quot;quotes&quot;");
-  });
-});

package/src/skills/format.ts

@@ -1,42 +0,0 @@
-import type { McpSkillMetadata } from "./skill-registry.js";
-
-function escapeXml(str: string): string {
-  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.
- */
-export function formatMcpSkillsForPrompt(skills: McpSkillMetadata[]): string {
-  if (skills.length === 0) return "";
-
-  const lines = [
-    "",
-    "",
-    "The following MCP skills provide specialized instructions and tools for specific tasks.",
-    "MCP tools are deferred — they are available but not described in this prompt.",
-    "You MUST call load_skill to get usage instructions before using a skill's tools.",
-    "",
-    "<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/src/skills/load-skill-tool.ts

@@ -1,136 +0,0 @@
-import type { AgentToolResult, ExtensionContext } from "@sammorrowdrums/mcpi";
-import { stripFrontmatter } from "@sammorrowdrums/mcpi";
-import { Type, type Static } from "typebox";
-import type { McpClientManager } from "../mcp/index.js";
-import type { SkillRegistry } from "./skill-registry.js";
-
-const LoadSkillParams = Type.Object({
-  name: Type.String({ description: "Name of the MCP skill to load" }),
-});
-
-type LoadSkillInput = Static<typeof LoadSkillParams>;
-
-export interface LoadSkillDeps {
-  registry: SkillRegistry;
-  mcpManager: McpClientManager;
-  enabledTools: Set<string>;
-}
-
-export interface LoadSkillDetails {
-  skillName: string;
-  serverName?: string;
-  activatedTools?: string[];
-  error?: string;
-}
-
-/**
- * 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 from the MCP server
- * 3. Returns the SKILL.md body (the skill names its tools, and the model
- *    already has their schemas from the deferred tools array)
- */
-export function createLoadSkillTool(deps: LoadSkillDeps) {
-  const { registry, mcpManager, enabledTools } = deps;
-
-  return {
-    name: "load_skill",
-    label: "Load Skill",
-    description: "Load an MCP skill by name. Activates the skill's instructions and tools.",
-    promptSnippet: "Load an MCP skill to get specialized instructions and activate its tools.",
-    parameters: LoadSkillParams,
-
-    async execute(
-      _toolCallId: string,
-      params: LoadSkillInput,
-      _signal: AbortSignal | undefined,
-      _onUpdate: undefined,
-      _ctx: ExtensionContext,
-    ): Promise<AgentToolResult<LoadSkillDetails>> {
-      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 client = mcpManager.getClient(skill.serverName);
-      if (!client) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: `MCP server "${skill.serverName}" is not connected. Cannot load skill "${params.name}".`,
-            },
-          ],
-          details: { skillName: params.name, serverName: skill.serverName, error: "disconnected" },
-        };
-      }
-
-      let body: string;
-      try {
-        const result = await client.readResource({ uri: skill.uri });
-        const textContent = result.contents.find(
-          (c): c is { uri: string; text: string } => "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 as Error).message}`,
-            },
-          ],
-          details: {
-            skillName: params.name,
-            serverName: skill.serverName,
-            error: (err as Error).message,
-          },
-        };
-      }
-
-      // Enable the skill's tools so the tool_call gate allows them
-      for (const t of skill.allowedTools) {
-        enabledTools.add(t);
-      }
-
-      return {
-        content: [
-          {
-            type: "text",
-            text: body,
-          },
-        ],
-        details: {
-          skillName: params.name,
-          serverName: skill.serverName,
-          activatedTools: skill.allowedTools,
-        },
-      };
-    },
-  };
-}

package/src/skills/mcp-tool-proxy.ts

@@ -1,143 +0,0 @@
-import type { AgentToolResult, ExtensionAPI, ExtensionContext } from "@sammorrowdrums/mcpi";
-import { writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { Type } from "typebox";
-import type { McpClientManager, McpTool } from "../mcp/index.js";
-
-/** Threshold in chars above which tool output is written to a tmp file. */
-const LARGE_OUTPUT_THRESHOLD = 10_000;
-
-interface McpToolProxyDetails {
-  serverName: string;
-  toolName: string;
-  error?: string;
-}
-
-/**
- * Register MCP tools as Pi tool proxies.
- *
- * Each registered tool forwards calls to the MCP server via `client.callTool()`.
- * Uses `Type.Unsafe()` to pass the MCP tool's original JSON Schema through
- * to Pi, preserving property names and types for the model.
- */
-export function registerMcpToolProxies(
-  toolNames: string[],
-  mcpManager: McpClientManager,
-  pi: ExtensionAPI,
-): string[] {
-  const registered: string[] = [];
-  const allTools = mcpManager.getTools();
-
-  // Check which tools are already registered to avoid double-registration
-  const existingTools = new Set(pi.getAllTools().map((t: { name: string }) => t.name));
-
-  for (const name of toolNames) {
-    if (existingTools.has(name)) {
-      registered.push(name);
-      continue;
-    }
-
-    const mcpTool = allTools.find((t) => t.name === name);
-    if (!mcpTool) continue;
-
-    pi.registerTool(createMcpToolProxy(mcpTool, mcpManager));
-    registered.push(name);
-  }
-
-  return registered;
-}
-
-function createMcpToolProxy(mcpTool: McpTool, mcpManager: McpClientManager) {
-  // Pass through the MCP tool's JSON Schema directly via Type.Unsafe()
-  // This preserves the original property names and types for the model
-  const inputSchema = mcpTool.inputSchema;
-  const parameters = Type.Unsafe({
-    type: "object",
-    properties: (inputSchema.properties as Record<string, unknown>) ?? {},
-    required: (inputSchema.required as string[]) ?? [],
-  });
-
-  return {
-    name: mcpTool.name,
-    label: mcpTool.name,
-    description: mcpTool.description ?? `MCP tool from ${mcpTool.serverName}`,
-    deferred: true,
-    parameters,
-
-    async execute(
-      _toolCallId: string,
-      params: Record<string, unknown>,
-      _signal: AbortSignal | undefined,
-      _onUpdate: undefined,
-      _ctx: ExtensionContext,
-    ): Promise<AgentToolResult<McpToolProxyDetails>> {
-      const client = mcpManager.getClient(mcpTool.serverName);
-      if (!client) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: `MCP server "${mcpTool.serverName}" is not connected.`,
-            },
-          ],
-          details: {
-            serverName: mcpTool.serverName,
-            toolName: mcpTool.name,
-            error: "disconnected",
-          },
-        };
-      }
-
-      try {
-        const result = await client.callTool({
-          name: mcpTool.name,
-          arguments: params,
-        });
-
-        // Prefer structuredContent when available
-        let text: string;
-        if (result.structuredContent) {
-          text = JSON.stringify(result.structuredContent, null, 2);
-        } else if (Array.isArray(result.content)) {
-          text = result.content
-            .map((c) => {
-              if (typeof c === "object" && c !== null && "text" in c) {
-                return String((c as { text: unknown }).text);
-              }
-              return JSON.stringify(c);
-            })
-            .join("\n");
-        } else {
-          text = JSON.stringify(result);
-        }
-
-        // Write large outputs to tmp file to avoid bloating context
-        if (text.length > LARGE_OUTPUT_THRESHOLD) {
-          const tmpPath = join(tmpdir(), `mcp-${mcpTool.name}-${Date.now()}.json`);
-          writeFileSync(tmpPath, text, "utf-8");
-          text = `Output too large (${text.length} chars). Written to: ${tmpPath}`;
-        }
-
-        return {
-          content: [{ type: "text" as const, text }],
-          details: { serverName: mcpTool.serverName, toolName: mcpTool.name },
-        };
-      } catch (err) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: `MCP tool "${mcpTool.name}" failed: ${(err as Error).message}`,
-            },
-          ],
-          details: {
-            serverName: mcpTool.serverName,
-            toolName: mcpTool.name,
-            error: (err as Error).message,
-          },
-        };
-      }
-    },
-  };
-}

package/src/skills/skill-integration.test.ts

@@ -1,139 +0,0 @@
-import { describe, it, expect, beforeAll, afterAll } from "vitest";
-import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { McpClientManager } from "../mcp/client-manager.js";
-import { SkillRegistry } from "./skill-registry.js";
-import { discoverSkillsFromServer } from "./discover.js";
-import { formatMcpSkillsForPrompt } from "./format.js";
-import { createLoadSkillTool } from "./load-skill-tool.js";
-
-/**
- * Integration test: connect to the test weather server via stdio,
- * discover skills, load a skill, verify tool schemas in result, call a gated tool.
- */
-describe("skill integration (weather server)", () => {
-  const manager = new McpClientManager();
-  const registry = new SkillRegistry();
-  const enabledTools = new Set<string>();
-  let client: Client;
-
-  beforeAll(async () => {
-    await manager.connectAll({
-      mcpServers: {
-        "test-weather": {
-          type: "stdio",
-          command: "node",
-          args: ["dist/test-servers/weather-stdio.js"],
-        },
-      },
-    });
-
-    const c = manager.getClient("test-weather");
-    if (!c) throw new Error("Expected client for test-weather");
-    client = c;
-  });
-
-  afterAll(async () => {
-    await manager.disconnectAll();
-  });
-
-  it("connects and discovers tools", () => {
-    expect(manager.getConnectedServers()).toEqual(["test-weather"]);
-    const tools = manager.getTools();
-    expect(tools.map((t) => t.name).sort()).toEqual([
-      "check_weather_for_city",
-      "check_weekly_forecast_for_city",
-      "echo",
-    ]);
-  });
-
-  it("discovers skill:// resources with frontmatter", async () => {
-    const skills = await discoverSkillsFromServer(client, "test-weather");
-
-    expect(skills).toHaveLength(1);
-    expect(skills[0].name).toBe("weather");
-    expect(skills[0].description).toBe("Check current weather and weekly forecasts for any city");
-    expect(skills[0].allowedTools).toEqual([
-      "check_weather_for_city",
-      "check_weekly_forecast_for_city",
-    ]);
-    expect(skills[0].uri).toBe("skill://weather/SKILL.md");
-    expect(skills[0].serverName).toBe("test-weather");
-
-    registry.registerAll(skills);
-  });
-
-  it("formats skills for system prompt", () => {
-    const prompt = formatMcpSkillsForPrompt(registry.getAll());
-    expect(prompt).toContain("<available_mcp_skills>");
-    expect(prompt).toContain("<name>weather</name>");
-    expect(prompt).toContain("load_skill");
-  });
-
-  it("load_skill returns skill body and reports activated tools", async () => {
-    const tool = createLoadSkillTool({
-      registry,
-      mcpManager: manager,
-      enabledTools,
-    });
-
-    const result = await tool.execute(
-      "call-1",
-      { name: "weather" },
-      undefined,
-      undefined,
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      {} as any,
-    );
-
-    expect(result.details.error).toBeUndefined();
-    expect(result.details.activatedTools).toEqual([
-      "check_weather_for_city",
-      "check_weekly_forecast_for_city",
-    ]);
-    const text = result.content[0];
-    expect(text.type).toBe("text");
-    // Skill body should mention the tools
-    expect("text" in text && text.text).toContain("check_weather_for_city");
-    // Tools should now be in enabledTools set
-    expect(enabledTools.has("check_weather_for_city")).toBe(true);
-    expect(enabledTools.has("check_weekly_forecast_for_city")).toBe(true);
-  });
-
-  it("calls gated tools via MCP client", async () => {
-    const weather = await client.callTool({
-      name: "check_weather_for_city",
-      arguments: { city: "Tokyo" },
-    });
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    expect((weather.content as any)[0].text).toContain("26");
-    expect(weather.structuredContent).toEqual({
-      temperature: 26,
-      conditions: "Sunny",
-      humidity: 55,
-      city: "Tokyo",
-    });
-
-    const forecast = await client.callTool({
-      name: "check_weekly_forecast_for_city",
-      arguments: { city: "London" },
-    });
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    expect((forecast.content as any)[0].text).toContain("London");
-    expect(forecast.structuredContent).toHaveProperty("city", "London");
-    expect(forecast.structuredContent).toHaveProperty("forecast");
-  });
-
-  it("load_skill returns error for unknown skill", async () => {
-    const tool = createLoadSkillTool({
-      registry,
-      mcpManager: manager,
-      enabledTools,
-    });
-
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const result = await tool.execute("call-2", { name: "nope" }, undefined, undefined, {} as any);
-    expect(result.details.error).toBe("not_found");
-    const text = result.content[0];
-    expect("text" in text && text.text).toContain("not found");
-  });
-});

package/src/skills/skill-registry.test.ts

@@ -1,83 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { SkillRegistry, type McpSkillMetadata } from "./skill-registry.js";
-
-function makeSkill(overrides: Partial<McpSkillMetadata> = {}): McpSkillMetadata {
-  return {
-    name: "test-skill",
-    description: "A test skill",
-    uri: "skill://test/SKILL.md",
-    serverName: "test-server",
-    allowedTools: ["tool_a"],
-    ...overrides,
-  };
-}
-
-describe("SkillRegistry", () => {
-  it("registers and retrieves a skill", () => {
-    const reg = new SkillRegistry();
-    const skill = makeSkill();
-    reg.register(skill);
-
-    expect(reg.get("test-skill")).toEqual(skill);
-    expect(reg.size).toBe(1);
-  });
-
-  it("getAll returns all registered skills", () => {
-    const reg = new SkillRegistry();
-    reg.register(makeSkill({ name: "a" }));
-    reg.register(makeSkill({ name: "b" }));
-
-    expect(reg.getAll()).toHaveLength(2);
-  });
-
-  it("overwrites on duplicate name", () => {
-    const reg = new SkillRegistry();
-    reg.register(makeSkill({ description: "first" }));
-    reg.register(makeSkill({ description: "second" }));
-
-    expect(reg.size).toBe(1);
-    expect(reg.get("test-skill")?.description).toBe("second");
-  });
-
-  it("unregister removes by name", () => {
-    const reg = new SkillRegistry();
-    reg.register(makeSkill());
-
-    expect(reg.unregister("test-skill")).toBe(true);
-    expect(reg.get("test-skill")).toBeUndefined();
-    expect(reg.unregister("test-skill")).toBe(false);
-  });
-
-  it("unregisterByServer removes all skills from a server", () => {
-    const reg = new SkillRegistry();
-    reg.register(makeSkill({ name: "a", serverName: "srv1" }));
-    reg.register(makeSkill({ name: "b", serverName: "srv1" }));
-    reg.register(makeSkill({ name: "c", serverName: "srv2" }));
-
-    reg.unregisterByServer("srv1");
-
-    expect(reg.size).toBe(1);
-    expect(reg.get("c")).toBeDefined();
-  });
-
-  it("registerAll registers multiple skills", () => {
-    const reg = new SkillRegistry();
-    reg.registerAll([makeSkill({ name: "x" }), makeSkill({ name: "y" })]);
-
-    expect(reg.size).toBe(2);
-  });
-
-  it("clear removes everything", () => {
-    const reg = new SkillRegistry();
-    reg.registerAll([makeSkill({ name: "a" }), makeSkill({ name: "b" })]);
-
-    reg.clear();
-    expect(reg.size).toBe(0);
-    expect(reg.getAll()).toEqual([]);
-  });
-
-  it("get returns undefined for unknown name", () => {
-    const reg = new SkillRegistry();
-    expect(reg.get("nonexistent")).toBeUndefined();
-  });
-});