@sammorrowdrums/mcpi-ext 0.1.0

package/src/tool-cli/constants.ts

@@ -0,0 +1,15 @@
+/** Default port for the tool-cli JSON-RPC server. */
+export const DEFAULT_PORT = 7179;
+
+/** Environment variable to override the default port. */
+export const PORT_ENV_VAR = "TOOL_CLI_PORT";
+
+/** Resolve the port from environment or default. */
+export function resolvePort(): number {
+  const envPort = process.env[PORT_ENV_VAR];
+  if (envPort) {
+    const parsed = parseInt(envPort, 10);
+    if (!isNaN(parsed) && parsed > 0 && parsed < 65536) return parsed;
+  }
+  return DEFAULT_PORT;
+}

package/src/tool-cli/format.test.ts

@@ -0,0 +1,33 @@
+import { describe, it, expect } from "vitest";
+import { formatToolCliForPrompt } from "./format.js";
+
+describe("formatToolCliForPrompt", () => {
+  it("returns empty string when no servers connected", () => {
+    expect(formatToolCliForPrompt(0)).toBe("");
+  });
+
+  it("includes tool-cli usage instructions when servers are connected", () => {
+    const result = formatToolCliForPrompt(2);
+    expect(result).toContain("tool-cli");
+    expect(result).toContain("<tool_cli>");
+    expect(result).toContain("</tool_cli>");
+    expect(result).toContain("--help");
+    expect(result).toContain("<server>");
+    expect(result).toContain("<tool>");
+    expect(result).toContain("2 MCP server(s) currently connected");
+  });
+
+  it("advises preferring skills over tool-cli", () => {
+    const result = formatToolCliForPrompt(1);
+    expect(result).toContain("prefer the skill");
+  });
+
+  it("includes shell chaining and piping examples", () => {
+    const result = formatToolCliForPrompt(1);
+    expect(result).toContain("grep");
+    expect(result).toContain("|");
+    expect(result).toContain("jq");
+    expect(result).toContain("xargs");
+    expect(result).toContain("Prefer piping and chaining");
+  });
+});

package/src/tool-cli/format.ts

@@ -0,0 +1,56 @@
+/**
+ * Format system prompt section advising the agent when and how to use tool-cli.
+ *
+ * Only included when MCP servers are connected. Tells the agent about
+ * progressive discovery via tool-cli as an alternative to skill-based access.
+ */
+export function formatToolCliForPrompt(serverCount: number): string {
+  if (serverCount === 0) return "";
+
+  return `
+
+<tool_cli>
+You have access to \`tool-cli\`, a CLI for discovering and calling MCP server tools progressively.
+
+Use tool-cli when:
+- No skill covers the task you need to do
+- You want to explore what tools are available on a server
+- You need ad-hoc access to an MCP tool without loading a full skill
+
+If a skill exists for the task, prefer the skill — it provides workflow instructions and curated tool access.
+
+Discovery (progressive — only fetch what you need):
+  tool-cli --help                            # List MCP servers with tool counts
+  tool-cli <server>                          # List all tools on a server
+  tool-cli <server> <tool>                   # Show full schema for a tool
+
+Calling tools:
+  tool-cli <server> <tool> '{"key":"value"}' # Call a tool with JSON arguments
+  tool-cli <server> <tool> '{}' --out /tmp/result.json  # Save large output to file
+
+tool-cli outputs plain text or JSON. When a tool provides structured output (typed JSON),
+tool-cli returns it directly as JSON — use \`jq\` to query fields.
+Chain calls, filter, and transform results using pipes and bash idioms:
+
+  # Search across tool results
+  tool-cli myserver search_docs '{"query":"auth"}' | grep -i "token"
+
+  # Query structured JSON output with jq
+  tool-cli myserver list_issues '{"repo":"owner/repo"}' | jq '.[].title'
+
+  # Chain tool calls — feed one result into another
+  tool-cli myserver list_items '{}' | jq -r '.[0].id' | xargs -I{} tool-cli myserver get_item '{"id":"{}"}'
+
+  # Process multiple items
+  for city in London Tokyo Paris; do
+    echo "=== $city ==="; tool-cli weather check_weather '{"city":"'$city'"}';
+  done
+
+  # Combine with standard tools
+  tool-cli myserver export_csv '{"table":"users"}' | sort -t, -k2 | head -20
+
+Prefer piping and chaining over multiple separate tool calls when processing collections or filtering results.
+Errors go to stderr with exit code 1 — use \`&&\` or \`set -e\` for safe chaining.
+${serverCount} MCP server(s) currently connected.
+</tool_cli>`;
+}

package/src/tool-cli/index.ts

@@ -0,0 +1,3 @@
+export { ToolCliRpcServer } from "./rpc-server.js";
+export { formatToolCliForPrompt } from "./format.js";
+export { DEFAULT_PORT, PORT_ENV_VAR, resolvePort } from "./constants.js";

package/src/tool-cli/rpc-client.ts

@@ -0,0 +1,39 @@
+import { resolvePort } from "./constants.js";
+
+interface JsonRpcResponse {
+  jsonrpc: "2.0";
+  result?: unknown;
+  error?: { code: number; message: string; data?: unknown };
+  id: number | string | null;
+}
+
+/**
+ * Send a JSON-RPC 2.0 request to the tool-cli RPC server.
+ * Throws on network errors and JSON-RPC error responses.
+ */
+export async function rpcCall(
+  method: string,
+  params: Record<string, unknown> = {},
+): Promise<unknown> {
+  const port = resolvePort();
+  const url = `http://127.0.0.1:${port}`;
+
+  const response = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      jsonrpc: "2.0",
+      method,
+      params,
+      id: 1,
+    }),
+  });
+
+  const json = (await response.json()) as JsonRpcResponse;
+
+  if (json.error) {
+    throw new Error(json.error.message);
+  }
+
+  return json.result;
+}

package/src/tool-cli/rpc-server.test.ts

@@ -0,0 +1,193 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { ToolCliRpcServer } from "./rpc-server.js";
+import type { McpClientManager } from "../mcp/index.js";
+
+/** Minimal mock of McpClientManager for RPC server testing. */
+function createMockManager(): McpClientManager {
+  const tools = [
+    {
+      name: "get_weather",
+      description: "Get current weather for a city",
+      inputSchema: {
+        type: "object",
+        properties: { city: { type: "string", description: "City name" } },
+        required: ["city"],
+      },
+      annotations: { readOnlyHint: true },
+      serverName: "weather",
+    },
+    {
+      name: "set_alarm",
+      description: "Set a weather alarm",
+      inputSchema: {
+        type: "object",
+        properties: {
+          city: { type: "string" },
+          threshold: { type: "number" },
+        },
+        required: ["city", "threshold"],
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      serverName: "weather",
+    },
+    {
+      name: "search_docs",
+      description: "Search documentation",
+      inputSchema: {
+        type: "object",
+        properties: { query: { type: "string", description: "Search query" } },
+        required: ["query"],
+      },
+      outputSchema: {
+        type: "object",
+        properties: { results: { type: "array" } },
+      },
+      annotations: { readOnlyHint: true },
+      serverName: "docs",
+    },
+  ];
+
+  return {
+    getConnectedServers: () => ["weather", "docs"],
+    getToolsForServer: (name: string) => tools.filter((t) => t.serverName === name),
+    getTools: () => tools,
+    getClient: (name: string) => {
+      if (name === "weather" || name === "docs") {
+        return {
+          callTool: async (params: { name: string; arguments?: Record<string, unknown> }) => ({
+            content: [{ type: "text", text: `Called ${params.name}` }],
+          }),
+        };
+      }
+      return undefined;
+    },
+  } as unknown as McpClientManager;
+}
+
+// Use port 0 so the OS assigns a free port — avoids collisions when src + dist tests run together
+describe("ToolCliRpcServer", () => {
+  let server: ToolCliRpcServer;
+  let port: number;
+
+  beforeAll(async () => {
+    const manager = createMockManager();
+    server = new ToolCliRpcServer(manager, 0);
+    await server.start();
+    port = server.getPort();
+  });
+
+  afterAll(async () => {
+    await server.stop();
+  });
+
+  async function rpc(method: string, params: Record<string, unknown> = {}): Promise<unknown> {
+    const res = await fetch(`http://127.0.0.1:${port}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ jsonrpc: "2.0", method, params, id: 1 }),
+    });
+    return res.json();
+  }
+
+  it("lists connected servers with tool counts", async () => {
+    const resp = (await rpc("listServers")) as {
+      result: { servers: { name: string; toolCount: number; examples: string[] }[] };
+    };
+    const { servers } = resp.result;
+    expect(servers).toHaveLength(2);
+
+    const weather = servers.find((s) => s.name === "weather");
+    expect(weather).toBeDefined();
+    expect(weather?.toolCount).toBe(2);
+    expect(weather?.examples.length).toBeGreaterThan(0);
+
+    const docs = servers.find((s) => s.name === "docs");
+    expect(docs).toBeDefined();
+    expect(docs?.toolCount).toBe(1);
+  });
+
+  it("lists tools for a specific server", async () => {
+    const resp = (await rpc("listTools", { server: "weather" })) as {
+      result: { server: string; tools: { name: string; description: string }[] };
+    };
+    expect(resp.result.server).toBe("weather");
+    expect(resp.result.tools).toHaveLength(2);
+    expect(resp.result.tools[0].name).toBe("get_weather");
+    expect(resp.result.tools[1].name).toBe("set_alarm");
+  });
+
+  it("describes a tool with full schema", async () => {
+    const resp = (await rpc("describeTool", { server: "weather", tool: "get_weather" })) as {
+      result: {
+        name: string;
+        description: string;
+        inputSchema: Record<string, unknown>;
+        annotations: Record<string, unknown>;
+      };
+    };
+    expect(resp.result.name).toBe("get_weather");
+    expect(resp.result.description).toBe("Get current weather for a city");
+    expect(resp.result.inputSchema).toHaveProperty("properties");
+    expect(resp.result.annotations).toEqual({ readOnlyHint: true });
+  });
+
+  it("calls a tool and returns result", async () => {
+    const resp = (await rpc("callTool", {
+      server: "weather",
+      tool: "get_weather",
+      arguments: { city: "London" },
+    })) as {
+      result: { content: { type: string; text: string }[] };
+    };
+    expect(resp.result.content).toHaveLength(1);
+    expect(resp.result.content[0].text).toBe("Called get_weather");
+  });
+
+  it("returns error for unknown server", async () => {
+    const resp = (await rpc("listTools", { server: "nonexistent" })) as {
+      error: { code: number; message: string };
+    };
+    expect(resp.error).toBeDefined();
+    expect(resp.error.code).toBe(-32602);
+    expect(resp.error.message).toContain("not found");
+  });
+
+  it("returns error for unknown tool", async () => {
+    const resp = (await rpc("describeTool", { server: "weather", tool: "nonexistent" })) as {
+      error: { code: number; message: string };
+    };
+    expect(resp.error).toBeDefined();
+    expect(resp.error.message).toContain("not found");
+  });
+
+  it("returns error for unknown method", async () => {
+    const resp = (await rpc("unknownMethod")) as {
+      error: { code: number; message: string };
+    };
+    expect(resp.error).toBeDefined();
+    expect(resp.error.code).toBe(-32601);
+  });
+
+  it("returns error for missing required params", async () => {
+    const resp = (await rpc("listTools", {})) as {
+      error: { code: number; message: string };
+    };
+    expect(resp.error).toBeDefined();
+    expect(resp.error.code).toBe(-32602);
+  });
+
+  it("rejects non-POST requests", async () => {
+    const res = await fetch(`http://127.0.0.1:${port}`, { method: "GET" });
+    expect(res.status).toBe(405);
+  });
+
+  it("handles malformed JSON gracefully", async () => {
+    const res = await fetch(`http://127.0.0.1:${port}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: "not json at all",
+    });
+    const json = (await res.json()) as { error: { code: number } };
+    expect(json.error.code).toBe(-32700);
+  });
+});

package/src/tool-cli/rpc-server.ts

@@ -0,0 +1,287 @@
+import http from "node:http";
+import type { McpClientManager, McpTool } from "../mcp/index.js";
+import { resolvePort } from "./constants.js";
+
+interface JsonRpcRequest {
+  jsonrpc: "2.0";
+  method: string;
+  params?: Record<string, unknown>;
+  id: number | string | null;
+}
+
+interface JsonRpcResponse {
+  jsonrpc: "2.0";
+  result?: unknown;
+  error?: { code: number; message: string; data?: unknown };
+  id: number | string | null;
+}
+
+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>;
+}
+
+export type { ServerInfo, ToolSummary, ToolDetails };
+
+/**
+ * JSON-RPC 2.0 server that exposes MCP tool discovery and execution.
+ *
+ * Methods:
+ * - listServers → server names + tool counts + random examples
+ * - listTools(server) → tool names + descriptions
+ * - describeTool(server, tool) → full schema
+ * - callTool(server, tool, arguments) → execute and return result
+ */
+export class ToolCliRpcServer {
+  private server: http.Server | null = null;
+  private port: number;
+
+  constructor(
+    private mcpManager: McpClientManager,
+    port?: number,
+  ) {
+    this.port = port ?? resolvePort();
+  }
+
+  /** Start the HTTP server. Resolves once listening. */
+  async start(log?: (msg: string) => void): Promise<void> {
+    if (this.server) return;
+
+    const MAX_BODY_SIZE = 1024 * 1024; // 1 MB
+
+    const server = http.createServer((req, res) => {
+      if (req.method !== "POST") {
+        res.writeHead(405, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(rpcError(null, -32600, "Only POST accepted")));
+        return;
+      }
+
+      let body = "";
+      let aborted = false;
+
+      req.on("error", () => {
+        aborted = true;
+      });
+
+      req.on("data", (chunk: Buffer) => {
+        if (aborted) return;
+        body += chunk.toString();
+        if (body.length > MAX_BODY_SIZE) {
+          aborted = true;
+          res.writeHead(413, { "Content-Type": "application/json" });
+          res.end(JSON.stringify(rpcError(null, -32600, "Request too large")));
+          req.destroy();
+        }
+      });
+
+      req.on("end", () => {
+        if (aborted) return;
+        void this.handleBody(body)
+          .then((response) => {
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify(response));
+          })
+          .catch(() => {
+            try {
+              res.writeHead(500, { "Content-Type": "application/json" });
+              res.end(JSON.stringify(rpcError(null, -32603, "Internal error")));
+            } catch {
+              res.end();
+            }
+          });
+      });
+    });
+
+    return new Promise<void>((resolve, reject) => {
+      server.once("error", (err) => {
+        this.server = null;
+        reject(err);
+      });
+      server.listen(this.port, "127.0.0.1", () => {
+        this.server = server;
+        log?.(`[tool-cli] RPC server listening on 127.0.0.1:${this.port}`);
+        resolve();
+      });
+    });
+  }
+
+  /** Stop the HTTP server. */
+  async stop(): Promise<void> {
+    const server = this.server;
+    if (!server) return;
+    this.server = null;
+
+    return new Promise<void>((resolve) => {
+      server.close(() => resolve());
+    });
+  }
+
+  /** Returns the port the server is listening on (resolved after start for port 0). */
+  getPort(): number {
+    if (this.server) {
+      const addr = this.server.address();
+      if (addr && typeof addr === "object") return addr.port;
+    }
+    return this.port;
+  }
+
+  private async handleBody(body: string): Promise<JsonRpcResponse> {
+    let parsed: JsonRpcRequest;
+    try {
+      parsed = JSON.parse(body) as JsonRpcRequest;
+    } catch {
+      return rpcError(null, -32700, "Parse error");
+    }
+
+    if (parsed.jsonrpc !== "2.0" || !parsed.method) {
+      return rpcError(parsed.id ?? null, -32600, "Invalid Request");
+    }
+
+    try {
+      const result = await this.dispatch(parsed.method, parsed.params ?? {});
+      return { jsonrpc: "2.0", result, id: parsed.id ?? null };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      const code = err instanceof RpcMethodError ? err.code : -32603;
+      return rpcError(parsed.id ?? null, code, message);
+    }
+  }
+
+  private async dispatch(method: string, params: Record<string, unknown>): Promise<unknown> {
+    switch (method) {
+      case "listServers":
+        return this.listServers();
+      case "listTools":
+        return this.listTools(params);
+      case "describeTool":
+        return this.describeTool(params);
+      case "callTool":
+        return this.callTool(params);
+      default:
+        throw new RpcMethodError(-32601, `Method not found: ${method}`);
+    }
+  }
+
+  private listServers(): { servers: ServerInfo[] } {
+    const serverNames = this.mcpManager.getConnectedServers();
+    const servers: ServerInfo[] = serverNames.map((name) => {
+      const tools = this.mcpManager.getToolsForServer(name);
+      return {
+        name,
+        toolCount: tools.length,
+        examples: pickRandomExamples(tools, 3),
+      };
+    });
+    return { servers };
+  }
+
+  private listTools(params: Record<string, unknown>): { server: string; tools: ToolSummary[] } {
+    const server = requireString(params, "server");
+    this.assertServerExists(server);
+    const tools = this.mcpManager.getToolsForServer(server);
+    return {
+      server,
+      tools: tools.map((t) => ({
+        name: t.name,
+        description: t.description ?? "(no description)",
+        hasStructuredOutput: t.outputSchema != null,
+      })),
+    };
+  }
+
+  private describeTool(params: Record<string, unknown>): ToolDetails {
+    const server = requireString(params, "server");
+    const toolName = requireString(params, "tool");
+    this.assertServerExists(server);
+
+    const tool = this.mcpManager.getToolsForServer(server).find((t) => t.name === toolName);
+    if (!tool) {
+      throw new RpcMethodError(-32602, `Tool "${toolName}" not found on server "${server}"`);
+    }
+
+    return {
+      name: tool.name,
+      description: tool.description ?? "(no description)",
+      inputSchema: tool.inputSchema,
+      outputSchema: tool.outputSchema,
+      annotations: tool.annotations,
+    };
+  }
+
+  private async callTool(params: Record<string, unknown>): Promise<{
+    content: unknown[];
+    isError?: boolean;
+    structuredContent?: Record<string, unknown>;
+  }> {
+    const server = requireString(params, "server");
+    const toolName = requireString(params, "tool");
+    this.assertServerExists(server);
+
+    const client = this.mcpManager.getClient(server);
+    if (!client) {
+      throw new RpcMethodError(-32603, `No client for server "${server}"`);
+    }
+
+    const toolArgs = (params.arguments as Record<string, unknown>) ?? {};
+
+    const result = await client.callTool({ name: toolName, arguments: toolArgs });
+    return {
+      content: result.content as unknown[],
+      isError: result.isError === true ? true : undefined,
+      structuredContent: result.structuredContent as Record<string, unknown> | undefined,
+    };
+  }
+
+  private assertServerExists(server: string): void {
+    if (!this.mcpManager.getConnectedServers().includes(server)) {
+      throw new RpcMethodError(
+        -32602,
+        `Server "${server}" not found. Connected: ${this.mcpManager.getConnectedServers().join(", ") || "(none)"}`,
+      );
+    }
+  }
+}
+
+class RpcMethodError extends Error {
+  constructor(
+    public code: number,
+    message: string,
+  ) {
+    super(message);
+    this.name = "RpcMethodError";
+  }
+}
+
+function rpcError(id: number | string | null, code: number, message: string): JsonRpcResponse {
+  return { jsonrpc: "2.0", error: { code, message }, id };
+}
+
+function requireString(params: Record<string, unknown>, key: string): string {
+  const val = params[key];
+  if (typeof val !== "string" || val.length === 0) {
+    throw new RpcMethodError(-32602, `Missing or invalid parameter: "${key}" (string required)`);
+  }
+  return val;
+}
+
+/** Pick up to `n` random tool names from a list. */
+function pickRandomExamples(tools: McpTool[], n: number): string[] {
+  if (tools.length <= n) return tools.map((t) => t.name);
+  const shuffled = [...tools].sort(() => Math.random() - 0.5);
+  return shuffled.slice(0, n).map((t) => t.name);
+}

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "lib": ["ES2022"],
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "resolveJsonModule": true,
+    "types": ["node"]
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}