mcpico 0.1.0

package/src/help.ts

@@ -0,0 +1,134 @@
+import type { ToolGroup } from "./grouper.js";
+import type { UpstreamTool } from "./discoverer.js";
+
+/**
+ * Generate a human-readable property description from a JSON Schema property definition.
+ */
+function describeProperty(
+  name: string,
+  schema: Record<string, unknown>
+): string {
+  const type = schema.type || "any";
+  const description = schema.description ? ` — ${schema.description}` : "";
+  const isRequired = schema._required ? " (required)" : " (optional)";
+  return `\`${name}\` (${type}${isRequired})${description}`;
+}
+
+/**
+ * Extract property definitions from a JSON Schema object.
+ * Handles both flat and nested properties structures.
+ */
+function extractProperties(
+  inputSchema: Record<string, unknown>
+): { name: string; schema: Record<string, unknown> }[] {
+  const properties = inputSchema.properties as
+    | Record<string, Record<string, unknown>>
+    | undefined;
+  if (!properties) return [];
+
+  const required =
+    (inputSchema.required as string[]) || [];
+
+  return Object.entries(properties).map(([name, schema]) => ({
+    name,
+    schema: { ...schema, _required: required.includes(name) },
+  }));
+}
+
+/**
+ * Generate a human-readable type string from a JSON Schema type.
+ */
+function schemaType(schema: Record<string, unknown>): string {
+  const t = schema.type;
+  if (Array.isArray(t)) return t.join(" | ");
+  if (typeof t === "string") return t;
+  return "any";
+}
+
+/**
+ * Generate an example value for a property based on its schema type.
+ */
+function exampleValue(name: string, schema: Record<string, unknown>): string {
+  const t = schemaType(schema);
+  if (t === "number" || t === "integer") return "42";
+  if (t === "boolean") return "true";
+  // For strings, use the property name as a hint
+  const lower = name.toLowerCase();
+  if (lower.includes("path")) return '"/tmp/example.txt"';
+  if (lower.includes("name")) return '"example-name"';
+  if (lower.includes("id")) return '"abc-123"';
+  if (lower.includes("url") || lower.includes("uri")) return '"https://example.com"';
+  if (lower.includes("content") || lower.includes("text")) return '"Hello, world!"';
+  if (lower.includes("query") || lower.includes("search")) return '"search terms"';
+  return '"value"';
+}
+
+/**
+ * Generate an example command string for a tool.
+ */
+function generateExample(tool: UpstreamTool): string {
+  const props = extractProperties(tool.inputSchema);
+  if (props.length === 0) return tool.name;
+
+  const required = props.filter((p) => p.schema._required);
+  const args: Record<string, string> = {};
+  for (const p of required.slice(0, 3)) {
+    args[p.name] = exampleValue(p.name, p.schema);
+  }
+
+  const argsStr = JSON.stringify(args);
+  // Keep examples compact
+  if (argsStr.length < 80) {
+    return `${tool.name} ${argsStr}`;
+  }
+  return tool.name;
+}
+
+/**
+ * Generate a complete help text for a tool group.
+ */
+export function generateHelpText(group: ToolGroup): string {
+  const lines: string[] = [];
+
+  lines.push(`⚡ MCPico — ${group.groupName}`);
+  lines.push("");
+  lines.push(
+    `Source: ${group.serverName} (${group.tools.length} tool${group.tools.length === 1 ? "" : "s"})`
+  );
+  lines.push("");
+  lines.push("Usage:  <subcommand> {" + '"}key{"}": {"}value{"}' + "}");
+  lines.push(
+    "        Send just 'help' to see this reference again."
+  );
+  lines.push("");
+  lines.push("─".repeat(50));
+  lines.push("");
+
+  for (const tool of group.tools) {
+    lines.push(`  ${tool.name}`);
+    if (tool.description) {
+      lines.push(`    ${tool.description}`);
+    }
+    lines.push("");
+
+    const props = extractProperties(tool.inputSchema);
+    if (props.length > 0) {
+      lines.push("    Parameters:");
+      for (const p of props) {
+        lines.push(`      ${describeProperty(p.name, p.schema)}`);
+      }
+      lines.push("");
+    }
+
+    const example = generateExample(tool);
+    lines.push(`    Example: ${example}`);
+    lines.push("");
+  }
+
+  lines.push("─".repeat(50));
+  lines.push(
+    "Generated by MCPico — auto-updates when upstream tools change."
+  );
+
+  return lines.join("\n");
+}

package/src/index.ts

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+
+/**
+ * MCPico — MCP proxy that bundles flat tool lists into hierarchical subcommand groups.
+ *
+ * Usage:
+ *   mcpico [--config <path>]
+ *
+ * Configuration is read from mcpico.json in the current directory by default.
+ */
+
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { startServer } from "./server.js";
+import type { MCPicoConfig } from "./config.js";
+
+async function main(): Promise<void> {
+  // Parse CLI args
+  const args = process.argv.slice(2);
+  let configPath = "mcpico.json";
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--config" || args[i] === "-c") {
+      configPath = args[i + 1] || configPath;
+      i++;
+    } else if (args[i] === "--version" || args[i] === "-v") {
+      console.log("MCPico v0.1.0");
+      process.exit(0);
+    } else if (args[i] === "--help" || args[i] === "-h") {
+      console.log(`
+MCPico — MCP proxy that bundles flat tool lists into hierarchical subcommand groups.
+
+Usage:
+  mcpico [--config <path>]
+
+Options:
+  --config, -c <path>    Path to config file (default: mcpico.json)
+  --version, -v          Show version
+  --help, -h             Show this help
+
+Config file format (mcpico.json):
+  {
+    "servers": [
+      {
+        "name": "filesystem",
+        "transport": {
+          "type": "stdio",
+          "command": "npx",
+          "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+        }
+      }
+    ],
+    "separator": "_",
+    "groups": {}
+  }
+`);
+      process.exit(0);
+    }
+  }
+
+  // Resolve config path
+  const resolvedPath = resolve(configPath);
+  let config: MCPicoConfig;
+
+  try {
+    const raw = readFileSync(resolvedPath, "utf-8");
+    config = JSON.parse(raw) as MCPicoConfig;
+  } catch (err) {
+    console.error(
+      `Error reading config file "${resolvedPath}":`,
+      (err as Error).message
+    );
+    process.exit(1);
+  }
+
+  // Validate
+  if (!config.servers || !Array.isArray(config.servers) || config.servers.length === 0) {
+    console.error('Config error: "servers" must be a non-empty array');
+    process.exit(1);
+  }
+
+  for (const server of config.servers) {
+    if (!server.name || !server.transport) {
+      console.error(
+        'Config error: each server must have a "name" and "transport"'
+      );
+      process.exit(1);
+    }
+    if (
+      server.transport.type === "stdio" &&
+      !server.transport.command
+    ) {
+      console.error(
+        `Config error: server "${server.name}" missing transport.command`
+      );
+      process.exit(1);
+    }
+  }
+
+  await startServer(config);
+}
+
+main().catch((err) => {
+  console.error("Fatal error:", err);
+  process.exit(1);
+});

package/src/parser.test.ts

@@ -0,0 +1,173 @@
+import { describe, it, expect } from "vitest";
+import { parseCommand } from "./parser.js";
+
+describe("parseCommand", () => {
+  describe("help / empty", () => {
+    it("returns isHelp for empty string", () => {
+      const result = parseCommand("");
+      expect(result.isHelp).toBe(true);
+      expect(result.subcommand).toBeNull();
+      expect(result.args).toEqual({});
+      expect(result.error).toBeNull();
+    });
+
+    it("returns isHelp for whitespace-only string", () => {
+      const result = parseCommand("   ");
+      expect(result.isHelp).toBe(true);
+      expect(result.error).toBeNull();
+    });
+
+    it("returns isHelp for explicit 'help'", () => {
+      const result = parseCommand("help");
+      expect(result.isHelp).toBe(true);
+      expect(result.subcommand).toBeNull();
+      expect(result.args).toEqual({});
+      expect(result.error).toBeNull();
+    });
+
+    it("returns isHelp for 'help' with extra whitespace", () => {
+      const result = parseCommand("  help  ");
+      expect(result.isHelp).toBe(true);
+      expect(result.args).toEqual({});
+    });
+  });
+
+  describe("bare subcommand (no args)", () => {
+    it("parses a single-word subcommand", () => {
+      const result = parseCommand("read_file");
+      expect(result.subcommand).toBe("read_file");
+      expect(result.args).toEqual({});
+      expect(result.isHelp).toBe(false);
+      expect(result.error).toBeNull();
+    });
+
+    it("handles subcommand with trailing whitespace", () => {
+      const result = parseCommand("list_dir  ");
+      expect(result.subcommand).toBe("list_dir");
+      expect(result.args).toEqual({});
+    });
+  });
+
+  describe("JSON args", () => {
+    it("parses simple JSON object args", () => {
+      const result = parseCommand('read_file {"path":"/etc/hosts"}');
+      expect(result.subcommand).toBe("read_file");
+      expect(result.args).toEqual({ path: "/etc/hosts" });
+      expect(result.error).toBeNull();
+    });
+
+    it("parses multiple JSON args", () => {
+      const result = parseCommand(
+        'write_file {"path":"/tmp/out.txt","content":"hello","encoding":"utf-8"}'
+      );
+      expect(result.subcommand).toBe("write_file");
+      expect(result.args).toEqual({
+        path: "/tmp/out.txt",
+        content: "hello",
+        encoding: "utf-8",
+      });
+    });
+
+    it("parses numeric and boolean values", () => {
+      const result = parseCommand(
+        'something {"count":42,"enabled":true,"ratio":3.14}'
+      );
+      expect(result.args).toEqual({
+        count: 42,
+        enabled: true,
+        ratio: 3.14,
+      });
+    });
+
+    it("parses nested JSON objects", () => {
+      const result = parseCommand(
+        'complex {"nested":{"key":"value"},"list":[1,2,3]}'
+      );
+      expect(result.args).toEqual({
+        nested: { key: "value" },
+        list: [1, 2, 3],
+      });
+    });
+
+    it("parses null values", () => {
+      const result = parseCommand('cmd {"key":null}');
+      expect(result.args).toEqual({ key: null });
+    });
+  });
+
+  describe("error handling", () => {
+    it("returns error for malformed JSON", () => {
+      const result = parseCommand('read_file {bad json}');
+      expect(result.error).toContain("Could not parse arguments as JSON");
+      expect(result.args).toEqual({});
+      expect(result.isHelp).toBe(false);
+    });
+
+    it("returns error for JSON array instead of object", () => {
+      const result = parseCommand('read_file ["a","b"]');
+      expect(result.error).toContain("Arguments must be a JSON object");
+      expect(result.args).toEqual({});
+    });
+
+    it("returns error for bare JSON primitive", () => {
+      const result = parseCommand('read_file "just a string"');
+      expect(result.error).toContain("Arguments must be a JSON object");
+    });
+
+    it("returns error for bare JSON number", () => {
+      const result = parseCommand("read_file 42");
+      expect(result.error).toContain("Arguments must be a JSON object");
+    });
+
+    it("returns error for incomplete JSON", () => {
+      const result = parseCommand('read_file {"path":"/tmp');
+      expect(result.error).toContain("Could not parse arguments as JSON");
+    });
+  });
+
+  describe("edge cases", () => {
+    it("handles subcommand with spaces in name (unusual but valid)", () => {
+      // First space splits subcommand from args
+      const result = parseCommand('my tool {"a":1}');
+      expect(result.subcommand).toBe("my");
+      expect(result.args).toEqual({});
+      expect(result.error).toContain("Could not parse arguments");
+    });
+
+    it("handles subcommand followed by empty args", () => {
+      const result = parseCommand("read_file ");
+      expect(result.subcommand).toBe("read_file");
+      expect(result.args).toEqual({});
+      expect(result.error).toBeNull();
+    });
+
+    it("handles subcommand followed by spaces", () => {
+      const result = parseCommand("read_file   ");
+      expect(result.subcommand).toBe("read_file");
+      expect(result.args).toEqual({});
+    });
+
+    it("handles JSON with leading/trailing whitespace in args", () => {
+      const result = parseCommand(
+        'read_file   {"path":"/tmp"}   '
+      );
+      expect(result.subcommand).toBe("read_file");
+      expect(result.args).toEqual({ path: "/tmp" });
+    });
+
+    it("handles empty JSON object", () => {
+      const result = parseCommand("cmd {}");
+      expect(result.subcommand).toBe("cmd");
+      expect(result.args).toEqual({});
+      expect(result.error).toBeNull();
+    });
+
+    it("handles subcommand containing underscores", () => {
+      const result = parseCommand(
+        'filesystem_read_file {"path":"/tmp"}'
+      );
+      expect(result.subcommand).toBe("filesystem_read_file");
+      expect(result.args).toEqual({ path: "/tmp" });
+    });
+  });
+});

package/src/parser.ts

@@ -0,0 +1,78 @@
+/**
+ * Result of parsing a command string.
+ */
+export interface ParsedCommand {
+  /** The subcommand name (maps to an upstream tool name) */
+  subcommand: string | null;
+  /** Parsed arguments to pass to the upstream tool */
+  args: Record<string, unknown>;
+  /** Whether this is a help request */
+  isHelp: boolean;
+  /** Error message if parsing failed */
+  error: string | null;
+}
+
+/**
+ * Parse a command string from the model.
+ *
+ * Format: `<subcommand> <json_args>`
+ *
+ * - Empty string or "help" → isHelp = true
+ * - "read_file" → subcommand = "read_file", args = {}
+ * - 'read_file {"path":"/etc/hosts"}' → subcommand = "read_file", args = {path: "/etc/hosts"}
+ * - "list_dir" → subcommand = "list_dir", args = {}
+ *
+ * Error handling:
+ * - If JSON is malformed, returns error message
+ * - If no subcommand given, returns isHelp = true
+ */
+export function parseCommand(rawCommand: string): ParsedCommand {
+  const trimmed = rawCommand.trim();
+
+  // Empty or explicit help
+  if (!trimmed || trimmed === "help") {
+    return { subcommand: null, args: {}, isHelp: true, error: null };
+  }
+
+  // Find the first space to split subcommand from args
+  const spaceIdx = trimmed.indexOf(" ");
+
+  if (spaceIdx === -1) {
+    // No args — just a subcommand
+    return {
+      subcommand: trimmed,
+      args: {},
+      isHelp: trimmed === "help",
+      error: null,
+    };
+  }
+
+  const subcommand = trimmed.slice(0, spaceIdx).trim();
+  const argsStr = trimmed.slice(spaceIdx + 1).trim();
+
+  // Empty args after subcommand
+  if (!argsStr) {
+    return { subcommand, args: {}, isHelp: false, error: null };
+  }
+
+  // Try JSON parse
+  try {
+    const args = JSON.parse(argsStr);
+    if (typeof args !== "object" || Array.isArray(args)) {
+      return {
+        subcommand,
+        args: {},
+        isHelp: false,
+        error: "Arguments must be a JSON object, e.g. {\"key\":\"value\"}",
+      };
+    }
+    return { subcommand, args: args as Record<string, unknown>, isHelp: false, error: null };
+  } catch {
+    return {
+      subcommand,
+      args: {},
+      isHelp: false,
+      error: `Could not parse arguments as JSON: "${argsStr}". Use format: <subcommand> {"key":"value",...}`,
+    };
+  }
+}

package/src/proxy.test.ts

@@ -0,0 +1,77 @@
+import { describe, it, expect, vi } from "vitest";
+import { forwardToolCall } from "./proxy.js";
+import type { DiscoveredServer } from "./discoverer.js";
+
+describe("forwardToolCall", () => {
+  it("calls client.callTool with the correct tool name and arguments", async () => {
+    const callTool = vi.fn().mockResolvedValue({
+      content: [{ type: "text", text: "success" }],
+    });
+
+    const server = {
+      client: { callTool },
+    } as unknown as DiscoveredServer;
+
+    const result = await forwardToolCall(server, "read_file", {
+      path: "/tmp/test.txt",
+    });
+
+    expect(callTool).toHaveBeenCalledWith({
+      name: "read_file",
+      arguments: { path: "/tmp/test.txt" },
+    });
+    expect(result).toEqual({
+      content: [{ type: "text", text: "success" }],
+    });
+  });
+
+  it("passes through errors from the upstream server", async () => {
+    const callTool = vi
+      .fn()
+      .mockRejectedValue(new Error("Upstream connection failed"));
+
+    const server = {
+      client: { callTool },
+    } as unknown as DiscoveredServer;
+
+    await expect(
+      forwardToolCall(server, "bad_tool", {})
+    ).rejects.toThrow("Upstream connection failed");
+  });
+
+  it("handles empty arguments", async () => {
+    const callTool = vi.fn().mockResolvedValue({
+      content: [{ type: "text", text: "ok" }],
+    });
+
+    const server = {
+      client: { callTool },
+    } as unknown as DiscoveredServer;
+
+    await forwardToolCall(server, "status", {});
+    expect(callTool).toHaveBeenCalledWith({
+      name: "status",
+      arguments: {},
+    });
+  });
+
+  it("handles nested arguments", async () => {
+    const callTool = vi.fn().mockResolvedValue({
+      content: [],
+    });
+
+    const server = {
+      client: { callTool },
+    } as unknown as DiscoveredServer;
+
+    await forwardToolCall(server, "complex", {
+      nested: { key: "value" },
+      array: [1, 2, 3],
+    });
+
+    expect(callTool).toHaveBeenCalledWith({
+      name: "complex",
+      arguments: { nested: { key: "value" }, array: [1, 2, 3] },
+    });
+  });
+});

package/src/proxy.ts

@@ -0,0 +1,16 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { DiscoveredServer } from "./discoverer.js";
+
+/**
+ * Forward a tool call to an upstream MCP server and return the result.
+ */
+export async function forwardToolCall(
+  server: DiscoveredServer,
+  toolName: string,
+  args: Record<string, unknown>
+): Promise<CallToolResult> {
+  return server.client.callTool({
+    name: toolName,
+    arguments: args,
+  }) as Promise<CallToolResult>;
+}