@sammorrowdrums/mcpi-ext 0.1.0

package/src/mcp/config-loader.test.ts

@@ -0,0 +1,115 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { writeFile, mkdtemp, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { loadMcpConfig } from "./config-loader.js";
+
+describe("loadMcpConfig", () => {
+  let dir: string;
+
+  async function writeConfig(content: string): Promise<string> {
+    dir = await mkdtemp(join(tmpdir(), "mcp-config-test-"));
+    const path = join(dir, "mcp.json");
+    await writeFile(path, content, "utf-8");
+    return path;
+  }
+
+  // Clean up temp dir after each test
+  afterEach(async () => {
+    if (dir) {
+      await rm(dir, { recursive: true, force: true }).catch(() => undefined);
+    }
+  });
+
+  it("returns empty config when file does not exist", async () => {
+    const config = await loadMcpConfig("/tmp/does-not-exist-" + Date.now() + ".json");
+    expect(config).toEqual({ mcpServers: {} });
+  });
+
+  it("loads a valid stdio server config", async () => {
+    const path = await writeConfig(
+      JSON.stringify({
+        mcpServers: {
+          "test-server": {
+            type: "stdio",
+            command: "node",
+            args: ["server.js"],
+            env: { API_KEY: "secret" },
+          },
+        },
+      }),
+    );
+
+    const config = await loadMcpConfig(path);
+    expect(config.mcpServers["test-server"]).toEqual({
+      type: "stdio",
+      command: "node",
+      args: ["server.js"],
+      env: { API_KEY: "secret" },
+    });
+  });
+
+  it("loads a valid remote server config", async () => {
+    const path = await writeConfig(
+      JSON.stringify({
+        mcpServers: {
+          "remote-server": {
+            type: "remote",
+            url: "https://example.com/mcp",
+            headers: { Authorization: "Bearer tok" },
+          },
+        },
+      }),
+    );
+
+    const config = await loadMcpConfig(path);
+    expect(config.mcpServers["remote-server"]).toEqual({
+      type: "remote",
+      url: "https://example.com/mcp",
+      headers: { Authorization: "Bearer tok" },
+    });
+  });
+
+  it("loads mixed server types", async () => {
+    const path = await writeConfig(
+      JSON.stringify({
+        mcpServers: {
+          local: { type: "stdio", command: "python", args: ["-m", "mcp_server"] },
+          cloud: { type: "remote", url: "https://api.example.com/mcp" },
+        },
+      }),
+    );
+
+    const config = await loadMcpConfig(path);
+    expect(Object.keys(config.mcpServers)).toEqual(["local", "cloud"]);
+    expect(config.mcpServers["local"].type).toBe("stdio");
+    expect(config.mcpServers["cloud"].type).toBe("remote");
+  });
+
+  it("throws on invalid JSON", async () => {
+    const path = await writeConfig("not json {{{");
+    await expect(loadMcpConfig(path)).rejects.toThrow("Invalid JSON");
+  });
+
+  it("throws on schema violation (missing required fields)", async () => {
+    const path = await writeConfig(
+      JSON.stringify({
+        mcpServers: {
+          bad: { type: "stdio" }, // missing "command"
+        },
+      }),
+    );
+    await expect(loadMcpConfig(path)).rejects.toThrow("Invalid MCP config");
+  });
+
+  it("throws on unknown server type", async () => {
+    const path = await writeConfig(
+      JSON.stringify({
+        mcpServers: {
+          bad: { type: "websocket", url: "ws://localhost" },
+        },
+      }),
+    );
+    await expect(loadMcpConfig(path)).rejects.toThrow("Invalid MCP config");
+  });
+});

package/src/mcp/config-loader.ts

@@ -0,0 +1,46 @@
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { Value } from "typebox/value";
+import { McpConfig } from "./config.js";
+
+const DEFAULT_CONFIG_PATH = join(homedir(), ".config", "mcpi-ext", "mcp.json");
+
+/**
+ * Load and validate an MCP config file.
+ * Returns an empty config if the file doesn't exist.
+ * Throws on invalid JSON or schema violations.
+ */
+export async function loadMcpConfig(configPath?: string): Promise<McpConfig> {
+  const path = configPath ?? DEFAULT_CONFIG_PATH;
+
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf-8");
+  } catch (err: unknown) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      return { mcpServers: {} };
+    }
+    throw new Error(`Failed to read MCP config at ${path}: ${(err as Error).message}`, {
+      cause: err,
+    });
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`Invalid JSON in MCP config at ${path}`);
+  }
+
+  if (!Value.Check(McpConfig, parsed)) {
+    const errors = Value.Errors(McpConfig, parsed);
+    const details = errors
+      .slice(0, 5)
+      .map((e) => `  ${e.instancePath || "/"}: ${e.message}`)
+      .join("\n");
+    throw new Error(`Invalid MCP config at ${path}:\n${details}`);
+  }
+
+  return parsed;
+}

package/src/mcp/config.ts

@@ -0,0 +1,40 @@
+import { Type, type Static } from "typebox";
+
+/** Configuration for a stdio-based MCP server (spawns a child process). */
+export const StdioServerConfig = Type.Object({
+  type: Type.Literal("stdio"),
+  command: Type.String({ description: "Executable to run" }),
+  args: Type.Optional(Type.Array(Type.String(), { description: "Command-line arguments" })),
+  env: Type.Optional(
+    Type.Record(Type.String(), Type.String(), {
+      description: "Extra environment variables for the child process",
+    }),
+  ),
+  cwd: Type.Optional(Type.String({ description: "Working directory for the child process" })),
+});
+
+/** Configuration for a remote MCP server (Streamable HTTP). */
+export const RemoteServerConfig = Type.Object({
+  type: Type.Literal("remote"),
+  url: Type.String({ description: "HTTP(S) endpoint URL" }),
+  headers: Type.Optional(
+    Type.Record(Type.String(), Type.String(), {
+      description: "Extra HTTP headers (e.g. Authorization)",
+    }),
+  ),
+});
+
+/** A single MCP server entry — either stdio or remote. */
+export const ServerConfig = Type.Union([StdioServerConfig, RemoteServerConfig]);
+
+/** Top-level configuration file schema. */
+export const McpConfig = Type.Object({
+  mcpServers: Type.Record(Type.String(), ServerConfig, {
+    description: "Named MCP server configurations",
+  }),
+});
+
+export type StdioServerConfig = Static<typeof StdioServerConfig>;
+export type RemoteServerConfig = Static<typeof RemoteServerConfig>;
+export type ServerConfig = Static<typeof ServerConfig>;
+export type McpConfig = Static<typeof McpConfig>;

package/src/mcp/index.ts

@@ -0,0 +1,4 @@
+export type { McpConfig, ServerConfig, StdioServerConfig, RemoteServerConfig } from "./config.js";
+export { McpConfig as McpConfigSchema } from "./config.js";
+export { loadMcpConfig } from "./config-loader.js";
+export { McpClientManager, type McpTool } from "./client-manager.js";

package/src/skills/discover.ts

@@ -0,0 +1,81 @@
+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

@@ -0,0 +1,70 @@
+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

@@ -0,0 +1,42 @@
+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/index.ts

@@ -0,0 +1,9 @@
+export { SkillRegistry, type McpSkillMetadata } 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";

package/src/skills/load-skill-tool.ts

@@ -0,0 +1,136 @@
+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

@@ -0,0 +1,143 @@
+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,
+          },
+        };
+      }
+    },
+  };
+}