mcpico 0.1.0

package/dist/server.js

@@ -0,0 +1,212 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod/v4";
+import { validateServerConfig } from "./config.js";
+import { discoverServer, disconnectServer, } from "./discoverer.js";
+import { groupTools } from "./grouper.js";
+import { parseCommand } from "./parser.js";
+import { generateHelpText } from "./help.js";
+import { forwardToolCall } from "./proxy.js";
+/** Helper: create a simple text content result */
+function textResult(text) {
+    return {
+        content: [{ type: "text", text }],
+    };
+}
+/**
+ * Start the MCPico proxy server.
+ *
+ * 1. Validate config
+ * 2. Connect to all upstream servers
+ * 3. Discover and group their tools
+ * 4. Register grouped tools on the MCPico server
+ * 5. Listen for client connections
+ */
+export async function startServer(config) {
+    const separator = config.separator || "_";
+    const servers = [];
+    const allGroups = [];
+    // Validate server configs
+    const validationErrors = [];
+    for (const serverConfig of config.servers) {
+        const err = validateServerConfig(serverConfig);
+        if (err) {
+            validationErrors.push(err);
+        }
+    }
+    if (validationErrors.length > 0) {
+        console.error("Configuration errors:");
+        for (const err of validationErrors) {
+            console.error(`  - ${err}`);
+        }
+        process.exit(1);
+    }
+    // Connect to all upstream servers and discover tools
+    console.error(`MCPico starting with ${config.servers.length} upstream server(s)...`);
+    for (const serverConfig of config.servers) {
+        try {
+            const transportLabel = serverConfig.transport.type === "sse"
+                ? serverConfig.transport.url
+                : serverConfig.transport.command;
+            console.error(`  Connecting to "${serverConfig.name}" (${serverConfig.transport.type}: ${transportLabel})...`);
+            const discovered = await discoverServer(serverConfig.name, serverConfig.transport, serverConfig.connectTimeoutMs);
+            servers.push(discovered);
+            const groups = groupTools(serverConfig.name, discovered.tools, separator, config.groups);
+            console.error(`  → ${discovered.tools.length} tools → ${groups.length} groups: ${groups.map((g) => g.groupName).join(", ")}`);
+            allGroups.push(...groups);
+        }
+        catch (err) {
+            console.error(`  Failed to connect to "${serverConfig.name}":`, err.message);
+        }
+    }
+    if (servers.length === 0) {
+        console.error("No upstream servers connected. Exiting.");
+        process.exit(1);
+    }
+    // Build lookup: groupName → ToolGroup (merged across servers)
+    const mergedGroups = new Map();
+    for (const group of allGroups) {
+        const existing = mergedGroups.get(group.groupName);
+        if (existing) {
+            existing.tools.push(...group.tools);
+            if (!existing.serverName.includes(group.serverName)) {
+                existing.serverName += ` + ${group.serverName}`;
+            }
+        }
+        else {
+            mergedGroups.set(group.groupName, { ...group });
+        }
+    }
+    // Create the MCPico server
+    const server = new McpServer({ name: "MCPico", version: "0.1.0" }, {
+        capabilities: { tools: {}, resources: {}, prompts: {} },
+        instructions: "MCPico bundles upstream MCP tools into hierarchical groups. " +
+            "Use 'help' on any group to discover available subcommands. " +
+            'Format: <subcommand> {"key":"value",...}',
+    });
+    // Register each group as a tool
+    for (const [groupName, group] of mergedGroups) {
+        const toolCount = group.tools.length;
+        const description = [
+            `MCPico ${groupName} — ${toolCount} tool${toolCount === 1 ? "" : "s"}`,
+            `Source: ${group.serverName}`,
+            `Use 'help' to see all subcommands and their parameters.`,
+            `Format: <subcommand> {"key":"value",...}`,
+        ].join(" | ");
+        const helpText = generateHelpText(group);
+        server.registerTool(groupName, {
+            title: `MCPico: ${groupName}`,
+            description,
+            inputSchema: {
+                command: z
+                    .string()
+                    .describe(`Use 'help' for full docs or '<subcommand> {"key":"value",...}' to execute. ` +
+                    `${toolCount} subcommand${toolCount === 1 ? "" : "s"} available.`),
+            },
+        }, async (args) => {
+            const parsed = parseCommand(args.command);
+            if (parsed.isHelp) {
+                return textResult(helpText);
+            }
+            if (parsed.error) {
+                return textResult(parsed.error);
+            }
+            const toolName = parsed.subcommand;
+            const upstreamTool = group.tools.find((t) => t.name === toolName);
+            if (!upstreamTool) {
+                const available = group.tools.map((t) => t.name).join(", ");
+                return textResult(`Unknown subcommand: "${toolName}"\n\nAvailable in ${groupName}: ${available}\n\nUse 'help' for full documentation.`);
+            }
+            const serverForTool = servers.find((s) => s.tools.some((t) => t.name === toolName));
+            if (!serverForTool) {
+                return textResult(`Internal error: could not find upstream server for tool "${toolName}"`);
+            }
+            try {
+                const result = await forwardToolCall(serverForTool, toolName, parsed.args);
+                return result;
+            }
+            catch (err) {
+                return textResult(`Error calling "${toolName}": ${err.message}`);
+            }
+        });
+        console.error(`  Registered group: ${groupName} (${toolCount} tools)`);
+    }
+    // Pass through resources from all upstream servers
+    let resourceCount = 0;
+    for (const upstream of servers) {
+        for (const res of upstream.resources) {
+            const namespacedUri = `mcpico://${upstream.name}/${res.uri}`;
+            const displayName = `${upstream.name}: ${res.name}`;
+            server.registerResource(displayName, namespacedUri, {
+                description: `${res.description || res.name} (from ${upstream.name})`,
+                mimeType: res.mimeType,
+            }, async () => {
+                const result = await upstream.client.readResource({ uri: res.uri });
+                return {
+                    contents: result.contents || [],
+                };
+            });
+            resourceCount++;
+        }
+    }
+    // Pass through prompts from all upstream servers
+    let promptCount = 0;
+    for (const upstream of servers) {
+        for (const prompt of upstream.prompts) {
+            const namespacedName = `${upstream.name}_${prompt.name}`;
+            const argShape = {};
+            for (const arg of prompt.arguments || []) {
+                argShape[arg.name] = z
+                    .string()
+                    .describe(arg.description ||
+                    `Argument: ${arg.name}${arg.required ? " (required)" : ""}`);
+            }
+            server.registerPrompt(namespacedName, {
+                title: `${upstream.name}: ${prompt.name}`,
+                description: `${prompt.description || ""} (from ${upstream.name})`,
+                argsSchema: Object.keys(argShape).length > 0 ? argShape : undefined,
+            }, async (args) => {
+                const promptArgs = {};
+                if (args && typeof args === "object") {
+                    for (const [k, v] of Object.entries(args)) {
+                        promptArgs[k] = String(v);
+                    }
+                }
+                const result = await upstream.client.getPrompt({
+                    name: prompt.name,
+                    arguments: promptArgs,
+                });
+                return {
+                    messages: result.messages || [],
+                };
+            });
+            promptCount++;
+        }
+    }
+    if (resourceCount > 0) {
+        console.error(`  Registered ${resourceCount} resource(s)`);
+    }
+    if (promptCount > 0) {
+        console.error(`  Registered ${promptCount} prompt(s)`);
+    }
+    // Connect to client via stdio
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`MCPico ready — ${mergedGroups.size} group(s), ${servers.length} upstream server(s)`);
+    // Handle shutdown
+    let shuttingDown = false;
+    const shutdown = async () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        console.error("Shutting down...");
+        for (const s of servers) {
+            await disconnectServer(s);
+        }
+        await server.close();
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/mcplico.example.json

@@ -0,0 +1,18 @@
+{
+  "servers": [
+    {
+      "name": "filesystem",
+      "transport": {
+        "type": "stdio",
+        "command": "npx",
+        "args": [
+          "-y",
+          "@modelcontextprotocol/server-filesystem",
+          "/tmp"
+        ]
+      }
+    }
+  ],
+  "separator": "_",
+  "groups": {}
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "mcpico",
+  "version": "0.1.0",
+  "description": "MCPico — MCP proxy that bundles flat tool lists into hierarchical subcommand groups. Pico footprint, maximum discovery.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "mcpico": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "keywords": [
+    "mcp",
+    "proxy",
+    "tools",
+    "context",
+    "hierarchical",
+    "subcommand"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.8.0",
+    "vitest": "^4.1.9"
+  }
+}

package/src/config.test.ts

@@ -0,0 +1,96 @@
+import { describe, it, expect } from "vitest";
+import { validateServerConfig, type ServerConfig } from "./config.js";
+
+describe("validateServerConfig", () => {
+  describe("server name", () => {
+    it("returns error for missing name", () => {
+      const server = { name: "", transport: { type: "stdio" as const, command: "echo" } } as ServerConfig;
+      expect(validateServerConfig(server)).toContain('"name"');
+    });
+
+    it("returns null for valid stdio config", () => {
+      const server: ServerConfig = {
+        name: "test-server",
+        transport: { type: "stdio", command: "echo" },
+      };
+      expect(validateServerConfig(server)).toBeNull();
+    });
+  });
+
+  describe("stdio transport", () => {
+    it("requires command", () => {
+      const server: ServerConfig = {
+        name: "test",
+        transport: { type: "stdio", command: "" },
+      };
+      expect(validateServerConfig(server)).toContain('"command"');
+    });
+
+    it("accepts stdio with optional fields", () => {
+      const server: ServerConfig = {
+        name: "test",
+        transport: {
+          type: "stdio",
+          command: "npx",
+          args: ["-y", "server"],
+          env: { DEBUG: "1" },
+          cwd: "/tmp",
+        },
+      };
+      expect(validateServerConfig(server)).toBeNull();
+    });
+  });
+
+  describe("sse transport", () => {
+    it("requires url", () => {
+      const server: ServerConfig = {
+        name: "test",
+        transport: { type: "sse", url: "" },
+      };
+      expect(validateServerConfig(server)).toContain('"url"');
+    });
+
+    it("validates URL format", () => {
+      const server: ServerConfig = {
+        name: "test",
+        transport: { type: "sse", url: "not-a-valid-url" },
+      };
+      expect(validateServerConfig(server)).toContain("not a valid URL");
+    });
+
+    it("accepts valid HTTP URL", () => {
+      const server: ServerConfig = {
+        name: "test",
+        transport: { type: "sse", url: "http://localhost:8080/mcp" },
+      };
+      expect(validateServerConfig(server)).toBeNull();
+    });
+
+    it("accepts valid HTTPS URL", () => {
+      const server: ServerConfig = {
+        name: "test",
+        transport: { type: "sse", url: "https://mcp.example.com/api" },
+      };
+      expect(validateServerConfig(server)).toBeNull();
+    });
+  });
+
+  describe("unknown transport", () => {
+    it("returns error for unknown transport type", () => {
+      const server = {
+        name: "test",
+        transport: { type: "websocket" },
+      } as unknown as ServerConfig;
+      const err = validateServerConfig(server);
+      expect(err).toContain("unknown transport type");
+      expect(err).toContain("websocket");
+    });
+  });
+
+  describe("missing transport", () => {
+    it("returns error for missing transport", () => {
+      const server = { name: "test" } as ServerConfig;
+      expect(validateServerConfig(server)).toContain('"transport"');
+    });
+  });
+});

package/src/config.ts

@@ -0,0 +1,76 @@
+/**
+ * Transport configuration for connecting to an upstream MCP server.
+ */
+export type TransportConfig =
+  | {
+      type: "stdio";
+      command: string;
+      args?: string[];
+      env?: Record<string, string>;
+      cwd?: string;
+    }
+  | {
+      type: "sse";
+      /** Full URL to the MCP Streamable HTTP endpoint (e.g. "https://mcp.example.com/mcp") */
+      url: string;
+    };
+
+/**
+ * Server configuration entry.
+ */
+export interface ServerConfig {
+  /** Friendly name used as the tool group namespace */
+  name: string;
+  /** Transport to connect to this upstream server */
+  transport: TransportConfig;
+  /** Connection timeout in milliseconds (default: 30000) */
+  connectTimeoutMs?: number;
+}
+
+/**
+ * Tool grouping override — map group names to explicit tool lists.
+ */
+export interface GroupOverrides {
+  [groupName: string]: string[];
+}
+
+/**
+ * Full MCPico configuration.
+ */
+export interface MCPicoConfig {
+  /** Upstream MCP servers to proxy */
+  servers: ServerConfig[];
+  /** Separator used for prefix-based tool grouping (default: "_") */
+  separator?: string;
+  /** Explicit group overrides — tools not listed here are auto-grouped */
+  groups?: GroupOverrides;
+}
+
+/**
+ * Validate server config and return a user-friendly error message, or null if valid.
+ */
+export function validateServerConfig(server: ServerConfig): string | null {
+  if (!server.name || typeof server.name !== "string") {
+    return 'Each server must have a non-empty "name" (string)';
+  }
+  if (!server.transport) {
+    return `Server "${server.name}": missing "transport"`;
+  }
+  if (server.transport.type === "stdio") {
+    if (!server.transport.command) {
+      return `Server "${server.name}": stdio transport requires "command"`;
+    }
+  } else if (server.transport.type === "sse") {
+    if (!server.transport.url) {
+      return `Server "${server.name}": sse transport requires "url"`;
+    }
+    try {
+      new URL(server.transport.url);
+    } catch {
+      return `Server "${server.name}": sse transport "url" is not a valid URL: "${server.transport.url}"`;
+    }
+  } else {
+    return `Server "${server.name}": unknown transport type "${(server.transport as Record<string, string>).type}". Supported: stdio, sse`;
+  }
+  return null;
+}

package/src/discoverer.test.ts

@@ -0,0 +1,222 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import type { TransportConfig } from "./config.js";
+
+// Create mock instances for the Client class
+const mockConnect = vi.fn();
+const mockClose = vi.fn();
+let listToolsResult = { tools: [] };
+let listResourcesRejects = true;
+let listResourcesResult = { resources: [] };
+let listPromptsRejects = true;
+let listPromptsResult = { prompts: [] };
+
+// Mock the MCP SDK modules
+vi.mock("@modelcontextprotocol/sdk/client/index.js", () => ({
+  Client: class {
+    connect = mockConnect;
+    close = mockClose;
+    listTools = () => Promise.resolve(listToolsResult);
+    listResources = () =>
+      listResourcesRejects
+        ? Promise.reject(new Error("Not supported"))
+        : Promise.resolve(listResourcesResult);
+    listPrompts = () =>
+      listPromptsRejects
+        ? Promise.reject(new Error("Not supported"))
+        : Promise.resolve(listPromptsResult);
+    callTool = vi.fn().mockResolvedValue({
+      content: [{ type: "text", text: "result" }],
+    });
+    readResource = vi.fn().mockResolvedValue({ contents: [] });
+    getPrompt = vi.fn().mockResolvedValue({ messages: [] });
+  },
+}));
+
+vi.mock("@modelcontextprotocol/sdk/client/stdio.js", () => ({
+  StdioClientTransport: class {
+    constructor(..._args: unknown[]) {}
+  },
+}));
+
+vi.mock("@modelcontextprotocol/sdk/client/streamableHttp.js", () => ({
+  StreamableHTTPClientTransport: class {
+    constructor(..._args: unknown[]) {}
+  },
+}));
+
+import {
+  discoverServer,
+  disconnectServer,
+  type DiscoveredServer,
+} from "./discoverer.js";
+
+describe("discoverServer", () => {
+  const stdioTransport: TransportConfig = {
+    type: "stdio",
+    command: "npx",
+    args: ["-y", "test-server"],
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    listToolsResult = { tools: [] };
+    listResourcesRejects = true;
+    listResourcesResult = { resources: [] };
+    listPromptsRejects = true;
+    listPromptsResult = { prompts: [] };
+  });
+
+  it("connects to upstream and discovers tools", async () => {
+    listToolsResult = {
+      tools: [
+        {
+          name: "read_file",
+          description: "Read a file",
+          inputSchema: { type: "object" },
+        },
+        {
+          name: "write_file",
+          description: "Write a file",
+          inputSchema: { type: "object" },
+        },
+      ],
+    };
+
+    const server = await discoverServer("test-server", stdioTransport);
+
+    expect(server.name).toBe("test-server");
+    expect(server.tools).toHaveLength(2);
+    expect(server.tools[0].name).toBe("read_file");
+    expect(server.tools[0].description).toBe("Read a file");
+    expect(server.tools[0].inputSchema).toEqual({ type: "object" });
+    expect(mockConnect).toHaveBeenCalled();
+  });
+
+  it("handles tools without descriptions or schemas", async () => {
+    listToolsResult = {
+      tools: [{ name: "simple_tool" }],
+    };
+
+    const server = await discoverServer("test-server", stdioTransport);
+
+    expect(server.tools).toHaveLength(1);
+    expect(server.tools[0].name).toBe("simple_tool");
+    expect(server.tools[0].inputSchema).toEqual({});
+  });
+
+  it("discovers resources when supported", async () => {
+    listToolsResult = { tools: [] };
+    listResourcesRejects = false;
+    listResourcesResult = {
+      resources: [
+        {
+          uri: "file:///tmp/test.txt",
+          name: "test.txt",
+          description: "A test file",
+          mimeType: "text/plain",
+        },
+      ],
+    };
+
+    const server = await discoverServer("test-server", stdioTransport);
+
+    expect(server.resources).toHaveLength(1);
+    expect(server.resources[0].uri).toBe("file:///tmp/test.txt");
+    expect(server.resources[0].name).toBe("test.txt");
+    expect(server.resources[0].mimeType).toBe("text/plain");
+  });
+
+  it("discovers prompts when supported", async () => {
+    listToolsResult = { tools: [] };
+    listPromptsRejects = false;
+    listPromptsResult = {
+      prompts: [
+        {
+          name: "greeting",
+          description: "Generate a greeting",
+          arguments: [
+            { name: "name", description: "Who to greet", required: true },
+          ],
+        },
+      ],
+    };
+
+    const server = await discoverServer("test-server", stdioTransport);
+
+    expect(server.prompts).toHaveLength(1);
+    expect(server.prompts[0].name).toBe("greeting");
+    expect(server.prompts[0].arguments).toHaveLength(1);
+    expect(server.prompts[0].arguments![0].name).toBe("name");
+    expect(server.prompts[0].arguments![0].required).toBe(true);
+  });
+
+  it("returns empty arrays when resources/prompts are not supported", async () => {
+    listToolsResult = { tools: [] };
+    listResourcesRejects = true;
+    listPromptsRejects = true;
+
+    const server = await discoverServer("test-server", stdioTransport);
+
+    expect(server.resources).toEqual([]);
+    expect(server.prompts).toEqual([]);
+  });
+
+  it("handles empty tools response gracefully", async () => {
+    listToolsResult = {};
+
+    const server = await discoverServer("test-server", stdioTransport);
+
+    expect(server.tools).toEqual([]);
+  });
+
+  describe("sse transport", () => {
+    const sseTransport: TransportConfig = {
+      type: "sse",
+      url: "https://mcp.example.com/api",
+    };
+
+    it("connects via SSE transport", async () => {
+      listToolsResult = {
+        tools: [{ name: "remote_tool", description: "Remote tool", inputSchema: {} }],
+      };
+
+      const server = await discoverServer("sse-server", sseTransport);
+
+      expect(server.name).toBe("sse-server");
+      expect(server.tools).toHaveLength(1);
+      expect(server.tools[0].name).toBe("remote_tool");
+      expect(mockConnect).toHaveBeenCalled();
+    });
+  });
+
+  describe("timeout", () => {
+    it("rejects after timeout when connection hangs", async () => {
+      // Simulate a connection that never resolves
+      mockConnect.mockImplementationOnce(() => new Promise(() => {}));
+
+      await expect(
+        discoverServer("slow-server", stdioTransport, 100)
+      ).rejects.toThrow("timed out");
+    });
+
+    it("succeeds when connection is fast enough", async () => {
+      listToolsResult = { tools: [{ name: "fast", inputSchema: {} }] };
+
+      const server = await discoverServer("fast-server", stdioTransport, 5000);
+
+      expect(server.tools).toHaveLength(1);
+    });
+  });
+});
+
+describe("disconnectServer", () => {
+  it("calls client.close()", async () => {
+    const close = vi.fn().mockResolvedValue(undefined);
+    const server = {
+      client: { close },
+    } as unknown as DiscoveredServer;
+
+    await disconnectServer(server);
+    expect(close).toHaveBeenCalled();
+  });
+});