mcpico 0.1.0

package/src/discoverer.ts

@@ -0,0 +1,148 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import type { TransportConfig } from "./config.js";
+
+/**
+ * Tool metadata from an upstream MCP server.
+ */
+export interface UpstreamTool {
+  name: string;
+  description?: string;
+  inputSchema: Record<string, unknown>;
+}
+
+/**
+ * Resource metadata from an upstream MCP server.
+ */
+export interface UpstreamResource {
+  uri: string;
+  name: string;
+  description?: string;
+  mimeType?: string;
+}
+
+/**
+ * Prompt metadata from an upstream MCP server.
+ */
+export interface UpstreamPrompt {
+  name: string;
+  description?: string;
+  arguments?: Array<{ name: string; description?: string; required?: boolean }>;
+}
+
+/**
+ * Discovered upstream server with its tools, resources, and prompts.
+ */
+export interface DiscoveredServer {
+  name: string;
+  tools: UpstreamTool[];
+  resources: UpstreamResource[];
+  prompts: UpstreamPrompt[];
+  client: Client;
+}
+
+/**
+ * Connect to an upstream MCP server and discover its tools.
+ *
+ * Supports stdio and streamable HTTP transports.
+ * Default connection timeout is 30 seconds.
+ */
+export async function discoverServer(
+  name: string,
+  transportConfig: TransportConfig,
+  connectTimeoutMs: number = 30_000
+): Promise<DiscoveredServer> {
+  let transport;
+
+  if (transportConfig.type === "stdio") {
+    transport = new StdioClientTransport({
+      command: transportConfig.command,
+      args: transportConfig.args,
+      env: transportConfig.env,
+      cwd: transportConfig.cwd,
+    });
+  } else if (transportConfig.type === "sse") {
+    transport = new StreamableHTTPClientTransport(
+      new URL(transportConfig.url)
+    );
+  } else {
+    throw new Error(`Unsupported transport type: ${(transportConfig as TransportConfig).type}`);
+  }
+
+  const client = new Client(
+    { name: `MCPico-${name}`, version: "0.1.0" },
+    { capabilities: {} }
+  );
+
+  // Connect with timeout
+  await withTimeout(
+    client.connect(transport),
+    connectTimeoutMs,
+    `Connection to "${name}" timed out after ${connectTimeoutMs}ms`
+  );
+
+  // Discover tools
+  const toolsResult = await client.listTools();
+  const tools: UpstreamTool[] = (toolsResult.tools || []).map((t) => ({
+    name: t.name,
+    description: t.description,
+    inputSchema: (t.inputSchema as Record<string, unknown>) || {},
+  }));
+
+  // Discover resources (if supported)
+  let resources: UpstreamResource[] = [];
+  try {
+    const resResult = await client.listResources();
+    resources = (resResult.resources || []).map((r) => ({
+      uri: r.uri,
+      name: r.name,
+      description: r.description,
+      mimeType: r.mimeType,
+    }));
+  } catch {
+    // Resources may not be supported by this server
+  }
+
+  // Discover prompts (if supported)
+  let prompts: UpstreamPrompt[] = [];
+  try {
+    const promptResult = await client.listPrompts();
+    prompts = (promptResult.prompts || []).map((p) => ({
+      name: p.name,
+      description: p.description,
+      arguments: (p.arguments || []).map((a) => ({
+        name: a.name,
+        description: a.description,
+        required: a.required,
+      })),
+    }));
+  } catch {
+    // Prompts may not be supported by this server
+  }
+
+  return { name, tools, resources, prompts, client };
+}
+
+/**
+ * Disconnect from an upstream server.
+ */
+export async function disconnectServer(server: DiscoveredServer): Promise<void> {
+  await server.client.close();
+}
+
+/**
+ * Race a promise against a timeout.
+ */
+async function withTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+  errorMessage: string
+): Promise<T> {
+  return Promise.race([
+    promise,
+    new Promise<T>((_, reject) =>
+      setTimeout(() => reject(new Error(errorMessage)), timeoutMs)
+    ),
+  ]);
+}

package/src/grouper.test.ts

@@ -0,0 +1,202 @@
+import { describe, it, expect } from "vitest";
+import { groupTools, type ToolGroup } from "./grouper.js";
+import type { UpstreamTool } from "./discoverer.js";
+
+function makeTool(name: string, description?: string): UpstreamTool {
+  return { name, description, inputSchema: {} };
+}
+
+function groupNames(groups: ToolGroup[]): string[] {
+  return groups.map((g) => g.groupName);
+}
+
+function toolNames(group: ToolGroup): string[] {
+  return group.tools.map((t) => t.name);
+}
+
+describe("groupTools", () => {
+  describe("prefix-based grouping", () => {
+    it("groups tools by underscore prefix", () => {
+      const tools = [
+        makeTool("filesystem_read_file"),
+        makeTool("filesystem_write_file"),
+        makeTool("filesystem_list_dir"),
+      ];
+      const groups = groupTools("test-server", tools);
+
+      expect(groups).toHaveLength(1);
+      expect(groups[0].groupName).toBe("filesystem");
+      expect(toolNames(groups[0])).toEqual([
+        "filesystem_read_file",
+        "filesystem_write_file",
+        "filesystem_list_dir",
+      ]);
+    });
+
+    it("groups tools with different prefixes into separate groups", () => {
+      const tools = [
+        makeTool("fs_read"),
+        makeTool("fs_write"),
+        makeTool("db_query"),
+        makeTool("db_insert"),
+      ];
+      const groups = groupTools("test-server", tools);
+
+      expect(groups).toHaveLength(2);
+      expect(groupNames(groups)).toEqual(
+        expect.arrayContaining(["fs", "db"])
+      );
+    });
+
+    it("uses custom separator", () => {
+      const tools = [
+        makeTool("github.create_issue"),
+        makeTool("github.list_repos"),
+      ];
+      const groups = groupTools("test-server", tools, ".");
+
+      expect(groups).toHaveLength(1);
+      expect(groups[0].groupName).toBe("github");
+    });
+
+    it("puts tools without prefix into server-named group", () => {
+      const tools = [
+        makeTool("read"),
+        makeTool("write"),
+        makeTool("filesystem_list"),
+      ];
+      const groups = groupTools("my-server", tools);
+
+      const defaultGroup = groups.find(
+        (g) => g.groupName === "my-server"
+      );
+      expect(defaultGroup).toBeDefined();
+      expect(toolNames(defaultGroup!)).toEqual(["read", "write"]);
+    });
+
+    it("handles mixed prefixed and unprefixed tools", () => {
+      const tools = [
+        makeTool("help"),
+        makeTool("status"),
+        makeTool("fs_read"),
+      ];
+      const groups = groupTools("test-server", tools);
+
+      expect(groups).toHaveLength(2);
+      const fsGroup = groups.find((g) => g.groupName === "fs");
+      const defaultGroup = groups.find(
+        (g) => g.groupName === "test-server"
+      );
+      expect(fsGroup).toBeDefined();
+      expect(defaultGroup).toBeDefined();
+      expect(toolNames(defaultGroup!)).toEqual(["help", "status"]);
+    });
+  });
+
+  describe("explicit overrides", () => {
+    it("applies group overrides", () => {
+      const tools = [
+        makeTool("custom_tool_a"),
+        makeTool("custom_tool_b"),
+      ];
+      const groups = groupTools("test-server", tools, "_", {
+        my_group: ["custom_tool_a", "custom_tool_b"],
+      });
+
+      expect(groups).toHaveLength(1);
+      expect(groups[0].groupName).toBe("my_group");
+      expect(toolNames(groups[0])).toEqual([
+        "custom_tool_a",
+        "custom_tool_b",
+      ]);
+    });
+
+    it("mixes overrides with prefix-based grouping", () => {
+      const tools = [
+        makeTool("special_tool"),
+        makeTool("fs_read"),
+        makeTool("fs_write"),
+      ];
+      const groups = groupTools("test-server", tools, "_", {
+        special: ["special_tool"],
+      });
+
+      expect(groups).toHaveLength(2);
+      const specialGroup = groups.find((g) => g.groupName === "special");
+      const fsGroup = groups.find((g) => g.groupName === "fs");
+      expect(specialGroup).toBeDefined();
+      expect(fsGroup).toBeDefined();
+      expect(toolNames(specialGroup!)).toEqual(["special_tool"]);
+    });
+
+    it("overridden tools are removed from prefix groups", () => {
+      // "special_fs_read" would normally go in "special" prefix group,
+      // but override puts it in "custom" instead
+      const tools = [
+        makeTool("special_fs_read"),
+        makeTool("special_fs_write"),
+      ];
+      const groups = groupTools("test-server", tools, "_", {
+        custom: ["special_fs_read"],
+      });
+
+      const customGroup = groups.find((g) => g.groupName === "custom");
+      const specialGroup = groups.find(
+        (g) => g.groupName === "special"
+      );
+      expect(customGroup).toBeDefined();
+      expect(specialGroup).toBeDefined();
+      expect(toolNames(customGroup!)).toEqual(["special_fs_read"]);
+      expect(toolNames(specialGroup!)).toEqual(["special_fs_write"]);
+    });
+  });
+
+  describe("edge cases", () => {
+    it("returns empty array for no tools", () => {
+      const groups = groupTools("test-server", []);
+      expect(groups).toEqual([]);
+    });
+
+    it("handles tools with separator at start (no prefix)", () => {
+      const tools = [makeTool("_read")];
+      const groups = groupTools("test-server", tools);
+      // Prefix index is 0, which is <= 0, so no prefix
+      expect(groups).toHaveLength(1);
+      expect(groups[0].groupName).toBe("test-server");
+    });
+
+    it("handles tools with separator at end (no suffix)", () => {
+      const tools = [makeTool("read_")];
+      const groups = groupTools("test-server", tools);
+      // Separator index is at last char, so no valid suffix
+      expect(groups).toHaveLength(1);
+      expect(groups[0].groupName).toBe("test-server");
+    });
+
+    it("sets serverName on all groups", () => {
+      const tools = [
+        makeTool("fs_read"),
+        makeTool("unprefixed"),
+      ];
+      const groups = groupTools("my-server", tools);
+      for (const g of groups) {
+        expect(g.serverName).toBe("my-server");
+      }
+    });
+
+    it("handles multiple separators in tool name (takes first)", () => {
+      const tools = [makeTool("prefix_sub_sub")];
+      const groups = groupTools("test-server", tools);
+      expect(groups).toHaveLength(1);
+      expect(groups[0].groupName).toBe("prefix");
+    });
+
+    it("groups single-tool prefix correctly", () => {
+      const tools = [makeTool("solo_tool")];
+      const groups = groupTools("test-server", tools);
+      expect(groups).toHaveLength(1);
+      expect(groups[0].groupName).toBe("solo");
+      expect(groups[0].tools).toHaveLength(1);
+    });
+  });
+});

package/src/grouper.ts

@@ -0,0 +1,96 @@
+import type { GroupOverrides } from "./config.js";
+import type { UpstreamTool } from "./discoverer.js";
+
+/**
+ * A group of related tools from an upstream server.
+ */
+export interface ToolGroup {
+  /** Group name (e.g., "filesystem") */
+  groupName: string;
+  /** Source server name */
+  serverName: string;
+  /** Tools in this group */
+  tools: UpstreamTool[];
+}
+
+/**
+ * Extract the prefix from a tool name using the given separator.
+ * Returns null if no prefix detected.
+ */
+function extractPrefix(
+  toolName: string,
+  separator: string
+): string | null {
+  const idx = toolName.indexOf(separator);
+  if (idx <= 0) return null;
+  const prefix = toolName.slice(0, idx);
+  // Must have a non-empty suffix too
+  if (idx >= toolName.length - 1) return null;
+  return prefix;
+}
+
+/**
+ * Group tools from an upstream server by prefix.
+ *
+ * Strategy:
+ * 1. If explicit group overrides exist, apply them first.
+ * 2. For remaining tools, extract prefix using separator.
+ * 3. Tools without a prefix go into the server's default group.
+ */
+export function groupTools(
+  serverName: string,
+  tools: UpstreamTool[],
+  separator: string = "_",
+  overrides?: GroupOverrides
+): ToolGroup[] {
+  const groups = new Map<string, UpstreamTool[]>();
+  const ungrouped: UpstreamTool[] = [];
+
+  // Build override lookup: toolName → forcedGroupName
+  const overrideMap = new Map<string, string>();
+  if (overrides) {
+    for (const [group, toolNames] of Object.entries(overrides)) {
+      for (const tn of toolNames) {
+        overrideMap.set(tn, group);
+      }
+    }
+  }
+
+  for (const tool of tools) {
+    // Check explicit override
+    const forcedGroup = overrideMap.get(tool.name);
+    if (forcedGroup) {
+      const existing = groups.get(forcedGroup) || [];
+      existing.push(tool);
+      groups.set(forcedGroup, existing);
+      continue;
+    }
+
+    // Try prefix extraction
+    const prefix = extractPrefix(tool.name, separator);
+    if (prefix) {
+      const existing = groups.get(prefix) || [];
+      existing.push(tool);
+      groups.set(prefix, existing);
+    } else {
+      ungrouped.push(tool);
+    }
+  }
+
+  // Tools without a prefix or override go into their own group per server
+  const result: ToolGroup[] = [];
+  for (const [groupName, groupTools] of groups) {
+    result.push({ groupName, serverName, tools: groupTools });
+  }
+
+  if (ungrouped.length > 0) {
+    // Put ungrouped tools in a group named after the server
+    result.push({
+      groupName: serverName,
+      serverName,
+      tools: ungrouped,
+    });
+  }
+
+  return result;
+}

package/src/help.test.ts

@@ -0,0 +1,197 @@
+import { describe, it, expect } from "vitest";
+import { generateHelpText } from "./help.js";
+import type { ToolGroup } from "./grouper.js";
+import type { UpstreamTool } from "./discoverer.js";
+
+function makeTool(overrides: Partial<UpstreamTool> = {}): UpstreamTool {
+  return {
+    name: "test_tool",
+    description: "A test tool",
+    inputSchema: {
+      type: "object",
+      properties: {
+        param1: { type: "string", description: "First parameter" },
+      },
+      required: ["param1"],
+    },
+    ...overrides,
+  };
+}
+
+function makeGroup(overrides: Partial<ToolGroup> = {}): ToolGroup {
+  return {
+    groupName: "test",
+    serverName: "test-server",
+    tools: [makeTool()],
+    ...overrides,
+  };
+}
+
+describe("generateHelpText", () => {
+  it("includes group name in header", () => {
+    const text = generateHelpText(makeGroup({ groupName: "filesystem" }));
+    expect(text).toContain("MCPico — filesystem");
+  });
+
+  it("includes server name", () => {
+    const text = generateHelpText(
+      makeGroup({ serverName: "my-server" })
+    );
+    expect(text).toContain("my-server");
+  });
+
+  it("shows correct tool count", () => {
+    const text = generateHelpText(makeGroup());
+    expect(text).toContain("1 tool");
+  });
+
+  it("shows plural for multiple tools", () => {
+    const group = makeGroup({
+      tools: [makeTool({ name: "tool_a" }), makeTool({ name: "tool_b" })],
+    });
+    const text = generateHelpText(group);
+    expect(text).toContain("2 tools");
+  });
+
+  it("includes usage instructions", () => {
+    const text = generateHelpText(makeGroup());
+    expect(text).toContain("Usage:");
+    expect(text).toContain("<subcommand>");
+    expect(text).toContain("Send just 'help'");
+  });
+
+  it("lists each tool by name", () => {
+    const group = makeGroup({
+      tools: [
+        makeTool({ name: "read_file", description: "Read a file" }),
+        makeTool({ name: "write_file", description: "Write a file" }),
+      ],
+    });
+    const text = generateHelpText(group);
+    expect(text).toContain("read_file");
+    expect(text).toContain("Read a file");
+    expect(text).toContain("write_file");
+    expect(text).toContain("Write a file");
+  });
+
+  it("shows tool description", () => {
+    const text = generateHelpText(
+      makeGroup({
+        tools: [makeTool({ description: "Does something useful" })],
+      })
+    );
+    expect(text).toContain("Does something useful");
+  });
+
+  it("shows parameters section for tools with properties", () => {
+    const text = generateHelpText(makeGroup());
+    expect(text).toContain("Parameters:");
+    expect(text).toContain("param1");
+    expect(text).toContain("(string");
+    expect(text).toContain("(required)");
+    expect(text).toContain("First parameter");
+  });
+
+  it("marks optional parameters", () => {
+    const tool = makeTool({
+      inputSchema: {
+        type: "object",
+        properties: {
+          optional_param: { type: "string", description: "Not required" },
+        },
+        required: [],
+      },
+    });
+    const text = generateHelpText(makeGroup({ tools: [tool] }));
+    expect(text).toContain("(optional)");
+  });
+
+  it("does not show Parameters section for tools without properties", () => {
+    const tool = makeTool({
+      inputSchema: { type: "object", properties: {} },
+    });
+    const text = generateHelpText(makeGroup({ tools: [tool] }));
+    expect(text).not.toContain("Parameters:");
+  });
+
+  it("generates examples for tools with parameters", () => {
+    const tool = makeTool({
+      inputSchema: {
+        type: "object",
+        properties: {
+          path: { type: "string", description: "File path" },
+        },
+        required: ["path"],
+      },
+    });
+    const text = generateHelpText(makeGroup({ tools: [tool] }));
+    expect(text).toContain("Example:");
+    expect(text).toContain("/tmp/example.txt");
+  });
+
+  it("shows bare subcommand for parameterless tools", () => {
+    const tool = makeTool({
+      inputSchema: { type: "object", properties: {} },
+    });
+    const text = generateHelpText(makeGroup({ tools: [tool] }));
+    expect(text).toContain("Example:");
+    expect(text).toContain(tool.name);
+  });
+
+  it("includes footer", () => {
+    const text = generateHelpText(makeGroup());
+    expect(text).toContain("Generated by MCPico");
+  });
+
+  it("handles tools without descriptions", () => {
+    const tool = makeTool({ description: undefined });
+    const text = generateHelpText(makeGroup({ tools: [tool] }));
+    expect(text).toContain(tool.name);
+    // Should not crash — tool is still listed
+  });
+
+  it("generates smart example values for known parameter names", () => {
+    const tool = makeTool({
+      name: "search",
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "Search query" },
+          limit: { type: "integer", description: "Max results" },
+          url: { type: "string", description: "Target URL" },
+        },
+        required: ["query", "limit", "url"],
+      },
+    });
+    const text = generateHelpText(makeGroup({ tools: [tool] }));
+    expect(text).toContain("search terms");
+    expect(text).toContain("42");
+    expect(text).toContain("https://example.com");
+  });
+
+  it("handles tools with a mix of required and optional params in example", () => {
+    const tool = makeTool({
+      name: "write",
+      inputSchema: {
+        type: "object",
+        properties: {
+          path: { type: "string" },
+          content: { type: "string" },
+          encoding: { type: "string" },
+        },
+        required: ["path"],
+      },
+    });
+    const text = generateHelpText(makeGroup({ tools: [tool] }));
+    // Example should show the required param
+    expect(text).toContain("path");
+    expect(text).toContain("/tmp/example.txt");
+  });
+
+  it("handles tools with no inputSchema", () => {
+    const tool = makeTool({ inputSchema: {} });
+    const text = generateHelpText(makeGroup({ tools: [tool] }));
+    expect(text).toContain(tool.name);
+    // Should not crash
+  });
+});