@sammorrowdrums/mcpi-ext 0.1.0

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

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

@@ -0,0 +1,83 @@
+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();
+  });
+});

package/src/skills/skill-registry.ts

@@ -0,0 +1,69 @@
+/** Metadata for a skill discovered from an MCP server. */
+export interface McpSkillMetadata {
+  /** Skill name from SKILL.md frontmatter. */
+  name: string;
+  /** Short description from SKILL.md frontmatter. */
+  description: string;
+  /** The skill:// URI for the SKILL.md resource. */
+  uri: string;
+  /** Which MCP server this skill came from. */
+  serverName: string;
+  /** Tool names this skill gates via allowed-tools frontmatter. */
+  allowedTools: string[];
+}
+
+/**
+ * Registry for MCP-discovered skills.
+ *
+ * Holds skill metadata discovered from MCP servers. Skills are registered
+ * during MCP connection and looked up when the model invokes load_skill.
+ */
+export class SkillRegistry {
+  private skills = new Map<string, McpSkillMetadata>();
+
+  /** Register a skill. Overwrites any existing skill with the same name. */
+  register(skill: McpSkillMetadata): void {
+    this.skills.set(skill.name, skill);
+  }
+
+  /** Register multiple skills at once. */
+  registerAll(skills: McpSkillMetadata[]): void {
+    for (const skill of skills) {
+      this.register(skill);
+    }
+  }
+
+  /** Get a skill by name. */
+  get(name: string): McpSkillMetadata | undefined {
+    return this.skills.get(name);
+  }
+
+  /** Get all registered skills. */
+  getAll(): McpSkillMetadata[] {
+    return [...this.skills.values()];
+  }
+
+  /** Remove a skill by name. */
+  unregister(name: string): boolean {
+    return this.skills.delete(name);
+  }
+
+  /** Remove all skills from a specific MCP server. */
+  unregisterByServer(serverName: string): void {
+    for (const [name, skill] of this.skills) {
+      if (skill.serverName === serverName) {
+        this.skills.delete(name);
+      }
+    }
+  }
+
+  /** Remove all skills. */
+  clear(): void {
+    this.skills.clear();
+  }
+
+  /** Number of registered skills. */
+  get size(): number {
+    return this.skills.size;
+  }
+}

package/src/test-servers/weather-server.ts

@@ -0,0 +1,171 @@
+/**
+ * Test MCP weather server — exposes a weather skill with gated tools.
+ *
+ * Registers:
+ * - skill://weather/SKILL.md — a skill resource with frontmatter
+ * - check_weather_for_city — current weather (gated by skill)
+ * - check_weekly_forecast_for_city — 7-day forecast (gated by skill)
+ * - echo — ungated baseline tool
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+const SKILL_CONTENT = `---
+name: weather
+description: Check current weather and weekly forecasts for any city
+allowed-tools:
+  - check_weather_for_city
+  - check_weekly_forecast_for_city
+---
+
+# Weather Forecasting Skill
+
+Use the weather tools to look up conditions for any city.
+
+- **check_weather_for_city** — returns current temperature, conditions, and humidity
+- **check_weekly_forecast_for_city** — returns a 7-day forecast summary
+
+Always confirm the city name with the user before calling.
+`;
+
+const WEATHER_DATA: Record<string, { temp: number; conditions: string; humidity: number }> = {
+  london: { temp: 14, conditions: "Cloudy", humidity: 78 },
+  tokyo: { temp: 26, conditions: "Sunny", humidity: 55 },
+  "new york": { temp: 22, conditions: "Partly cloudy", humidity: 62 },
+  sydney: { temp: 19, conditions: "Clear", humidity: 45 },
+};
+
+const FORECAST_DATA: Record<string, string> = {
+  london:
+    "Mon 13°C Rain | Tue 14°C Cloudy | Wed 15°C Cloudy | Thu 12°C Rain | Fri 14°C Sunny | Sat 16°C Sunny | Sun 15°C Cloudy",
+  tokyo:
+    "Mon 27°C Sunny | Tue 28°C Sunny | Wed 25°C Rain | Thu 24°C Cloudy | Fri 26°C Sunny | Sat 27°C Sunny | Sun 26°C Partly cloudy",
+  "new york":
+    "Mon 23°C Sunny | Tue 24°C Sunny | Wed 20°C Thunderstorms | Thu 18°C Cloudy | Fri 21°C Sunny | Sat 22°C Sunny | Sun 23°C Clear",
+  sydney:
+    "Mon 18°C Clear | Tue 20°C Sunny | Wed 19°C Cloudy | Thu 17°C Rain | Fri 18°C Cloudy | Sat 21°C Sunny | Sun 20°C Clear",
+};
+
+export function createWeatherServer(): McpServer {
+  const server = new McpServer(
+    { name: "test-weather-server", version: "0.1.0" },
+    { capabilities: { resources: {} } },
+  );
+
+  // Skill resource
+  server.registerResource(
+    "weather-skill",
+    "skill://weather/SKILL.md",
+    {
+      description: "Weather forecasting skill instructions",
+      mimeType: "text/markdown",
+    },
+    async () => ({
+      contents: [
+        {
+          uri: "skill://weather/SKILL.md",
+          text: SKILL_CONTENT,
+          mimeType: "text/markdown",
+        },
+      ],
+    }),
+  );
+
+  // Tool: current weather (gated by skill)
+  server.registerTool(
+    "check_weather_for_city",
+    {
+      description: "Get current weather conditions for a city",
+      inputSchema: { city: z.string().describe("City name, e.g. 'London'") },
+      outputSchema: {
+        temperature: z.number().describe("Temperature in Celsius"),
+        conditions: z.string().describe("Weather conditions description"),
+        humidity: z.number().describe("Humidity percentage"),
+        city: z.string().describe("City name"),
+      },
+      annotations: { readOnlyHint: true },
+    },
+    async ({ city }) => {
+      const data = WEATHER_DATA[city.toLowerCase()];
+      if (!data) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `No weather data available for "${city}". Try: London, Tokyo, New York, or Sydney.`,
+            },
+          ],
+        };
+      }
+      const structuredContent = {
+        temperature: data.temp,
+        conditions: data.conditions,
+        humidity: data.humidity,
+        city,
+      };
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Weather in ${city}: ${data.conditions}, ${data.temp}°C, humidity ${data.humidity}%`,
+          },
+        ],
+        structuredContent,
+      };
+    },
+  );
+
+  // Tool: weekly forecast (gated by skill)
+  server.registerTool(
+    "check_weekly_forecast_for_city",
+    {
+      description: "Get a 7-day weather forecast for a city",
+      inputSchema: { city: z.string().describe("City name, e.g. 'Tokyo'") },
+      outputSchema: {
+        city: z.string().describe("City name"),
+        forecast: z.string().describe("7-day forecast summary"),
+      },
+      annotations: { readOnlyHint: true },
+    },
+    async ({ city }) => {
+      const forecast = FORECAST_DATA[city.toLowerCase()];
+      if (!forecast) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `No forecast data available for "${city}". Try: London, Tokyo, New York, or Sydney.`,
+            },
+          ],
+        };
+      }
+      const structuredContent = { city, forecast };
+      return {
+        content: [{ type: "text" as const, text: `Forecast for ${city}: ${forecast}` }],
+        structuredContent,
+      };
+    },
+  );
+
+  // Ungated tool (always available, not behind a skill)
+  server.registerTool(
+    "echo",
+    {
+      description: "Echoes back the input message",
+      inputSchema: { message: z.string() },
+      outputSchema: {
+        echo: z.string().describe("The echoed message"),
+      },
+      annotations: { readOnlyHint: true },
+    },
+    async ({ message }) => {
+      const structuredContent = { echo: message };
+      return {
+        content: [{ type: "text" as const, text: `Echo: ${message}` }],
+        structuredContent,
+      };
+    },
+  );
+
+  return server;
+}

package/src/test-servers/weather-stdio.ts

@@ -0,0 +1,11 @@
+/**
+ * stdio entrypoint for the test weather server.
+ * Run with: node dist/test-servers/weather-stdio.js
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createWeatherServer } from "./weather-server.js";
+
+const server = createWeatherServer();
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error("Test weather server running on stdio");

package/src/tool-cli/cli.ts

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+
+import { writeFileSync } from "node:fs";
+import { rpcCall } from "./rpc-client.js";
+
+interface ServerInfo {
+  name: string;
+  toolCount: number;
+  examples: string[];
+}
+
+interface ToolSummary {
+  name: string;
+  description: string;
+  hasStructuredOutput: boolean;
+}
+
+interface ToolDetails {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  outputSchema?: Record<string, unknown>;
+  annotations?: Record<string, unknown>;
+}
+
+async function main(): Promise<void> {
+  const rawArgs = process.argv.slice(2);
+
+  // Extract --out <file> flag (can appear anywhere)
+  let outFile: string | undefined;
+  const args: string[] = [];
+  for (let i = 0; i < rawArgs.length; i++) {
+    if (rawArgs[i] === "--out" && i + 1 < rawArgs.length) {
+      outFile = rawArgs[++i];
+    } else {
+      args.push(rawArgs[i]);
+    }
+  }
+
+  try {
+    // No args or --help → list servers
+    if (args.length === 0 || (args.length === 1 && isHelp(args[0]))) {
+      await listServers();
+      return;
+    }
+
+    const server = args[0];
+
+    // <server> --help or just <server> → list tools
+    if (args.length === 1 || (args.length === 2 && isHelp(args[1]))) {
+      await listTools(server);
+      return;
+    }
+
+    const tool = args[1];
+
+    // <server> <tool> --help or just <server> <tool> → describe tool
+    if (args.length === 2 || (args.length === 3 && isHelp(args[2]))) {
+      await describeTool(server, tool);
+      return;
+    }
+
+    // <server> <tool> <json-args> → call tool
+    await callTool(server, tool, args[2], outFile);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (message.includes("ECONNREFUSED") || message.includes("fetch failed")) {
+      console.error("Error: tool-cli server not running. Is mcpi-ext loaded?");
+    } else {
+      console.error(`Error: ${message}`);
+    }
+    process.exit(1);
+  }
+}
+
+async function listServers(): Promise<void> {
+  const result = (await rpcCall("listServers")) as { servers: ServerInfo[] };
+  const { servers } = result;
+
+  if (servers.length === 0) {
+    console.log("No MCP servers connected.");
+    return;
+  }
+
+  console.log("Available servers:");
+  for (const s of servers) {
+    const examples = s.examples.length > 0 ? ` (e.g. ${s.examples.join(", ")})` : "";
+    console.log(`  ${s.name.padEnd(20)} ${s.toolCount} tool(s)${examples}`);
+  }
+  console.log("");
+  console.log("Use: tool-cli <server> to list tools");
+}
+
+async function listTools(server: string): Promise<void> {
+  const result = (await rpcCall("listTools", { server })) as {
+    server: string;
+    tools: ToolSummary[];
+  };
+
+  if (result.tools.length === 0) {
+    console.log(`${server} — no tools`);
+    return;
+  }
+
+  console.log(`${server} — ${result.tools.length} tool(s):`);
+  for (const t of result.tools) {
+    const badge = t.hasStructuredOutput ? " [json]" : "";
+    console.log(`  ${t.name.padEnd(30)} ${t.description}${badge}`);
+  }
+  console.log("");
+  console.log("Use: tool-cli <server> <tool> for full schema");
+}
+
+async function describeTool(server: string, tool: string): Promise<void> {
+  const result = (await rpcCall("describeTool", { server, tool })) as ToolDetails;
+
+  console.log(`${result.name} — ${result.description}`);
+  console.log("");
+  console.log("Input schema:");
+  console.log(formatSchema(result.inputSchema));
+
+  if (result.outputSchema) {
+    console.log("");
+    console.log("Output schema (structured JSON output):");
+    console.log(formatSchema(result.outputSchema));
+  }
+
+  if (result.annotations && Object.keys(result.annotations).length > 0) {
+    console.log("");
+    console.log("Annotations:");
+    for (const [key, val] of Object.entries(result.annotations)) {
+      console.log(`  ${key}: ${JSON.stringify(val)}`);
+    }
+  }
+
+  console.log("");
+  console.log(`Use: tool-cli ${server} ${tool} '{"key":"value"}' to call`);
+}
+
+async function callTool(
+  server: string,
+  tool: string,
+  argsJson: string,
+  outFile?: string,
+): Promise<void> {
+  let toolArgs: Record<string, unknown>;
+  try {
+    toolArgs = JSON.parse(argsJson) as Record<string, unknown>;
+  } catch {
+    console.error(`Error: invalid JSON arguments: ${argsJson}`);
+    process.exit(1);
+  }
+
+  const result = (await rpcCall("callTool", { server, tool, arguments: toolArgs })) as {
+    content: unknown[];
+    isError?: boolean;
+    structuredContent?: Record<string, unknown>;
+  };
+
+  if (result.isError) {
+    // Error content goes to stderr so stdout stays clean for piping
+    if (result.structuredContent) {
+      console.error(JSON.stringify(result.structuredContent, null, 2));
+    } else if (result.content) {
+      for (const item of result.content) {
+        const entry = item as Record<string, unknown>;
+        if (entry.type === "text") {
+          console.error(entry.text);
+        } else {
+          console.error(JSON.stringify(entry, null, 2));
+        }
+      }
+    }
+    process.exit(1);
+    return;
+  }
+
+  const output = formatOutput(result.structuredContent, result.content);
+  if (!output) return;
+
+  if (outFile) {
+    writeFileSync(outFile, output, "utf-8");
+    console.log(`Written to: ${outFile}`);
+  } else {
+    console.log(output);
+  }
+}
+
+/** Build the output string from structured or raw content. */
+function formatOutput(structuredContent?: Record<string, unknown>, content?: unknown[]): string {
+  if (structuredContent) {
+    return JSON.stringify(structuredContent, null, 2);
+  }
+  if (content) {
+    const parts: string[] = [];
+    for (const item of content) {
+      const entry = item as Record<string, unknown>;
+      if (entry.type === "text") {
+        parts.push(entry.text as string);
+      } else {
+        parts.push(JSON.stringify(entry, null, 2));
+      }
+    }
+    return parts.join("\n");
+  }
+  return "";
+}
+
+/** Format a JSON Schema as a compact, readable summary. */
+function formatSchema(schema: Record<string, unknown>): string {
+  const props = schema.properties as Record<string, Record<string, unknown>> | undefined;
+  const required = (schema.required as string[]) ?? [];
+
+  if (!props || Object.keys(props).length === 0) {
+    return "  (no parameters)";
+  }
+
+  const lines: string[] = [];
+  for (const [name, prop] of Object.entries(props)) {
+    const type = (prop.type as string) ?? "unknown";
+    const req = required.includes(name) ? ", required" : "";
+    const desc = prop.description ? `: ${prop.description as string}` : "";
+    lines.push(`  ${name} (${type}${req})${desc}`);
+  }
+  return lines.join("\n");
+}
+
+function isHelp(arg: string): boolean {
+  return arg === "--help" || arg === "-h";
+}
+
+void main();