@teampitch/mcpx 0.2.1

package/src/openapi.test.ts

@@ -0,0 +1,223 @@
+import { describe, test, expect } from "bun:test";
+
+import { extractTools, buildRequest, type OpenApiTool } from "./openapi.js";
+
+const minimalSpec = {
+  paths: {
+    "/pets": {
+      get: {
+        operationId: "listPets",
+        summary: "List all pets",
+        parameters: [
+          {
+            name: "limit",
+            in: "query" as const,
+            required: false,
+            schema: { type: "integer" },
+          },
+        ],
+      },
+      post: {
+        operationId: "createPet",
+        summary: "Create a pet",
+        requestBody: {
+          content: {
+            "application/json": {
+              schema: {
+                type: "object",
+                properties: {
+                  name: { type: "string" },
+                  tag: { type: "string" },
+                },
+                required: ["name"],
+              },
+            },
+          },
+        },
+      },
+    },
+    "/pets/{petId}": {
+      get: {
+        operationId: "getPet",
+        summary: "Get a pet by ID",
+        parameters: [
+          {
+            name: "petId",
+            in: "path" as const,
+            required: true,
+            schema: { type: "string" },
+          },
+        ],
+      },
+    },
+    "/internal": {
+      get: {
+        // No operationId — should be skipped
+        summary: "Internal endpoint",
+      },
+    },
+  },
+};
+
+describe("extractTools", () => {
+  test("extracts tools from operations with operationId", () => {
+    const tools = extractTools(minimalSpec);
+    expect(tools).toHaveLength(3);
+    expect(tools.map((t) => t.name)).toEqual(["listPets", "createPet", "getPet"]);
+  });
+
+  test("skips operations without operationId", () => {
+    const tools = extractTools(minimalSpec);
+    expect(tools.find((t) => t.name === "Internal endpoint")).toBeUndefined();
+  });
+
+  test("maps path parameters as required", () => {
+    const tools = extractTools(minimalSpec);
+    const getPet = tools.find((t) => t.name === "getPet")!;
+    expect(getPet.inputSchema.required).toEqual(["petId"]);
+    expect((getPet.inputSchema.properties as Record<string, unknown>).petId).toBeTruthy();
+  });
+
+  test("maps query parameters", () => {
+    const tools = extractTools(minimalSpec);
+    const listPets = tools.find((t) => t.name === "listPets")!;
+    expect((listPets.inputSchema.properties as Record<string, unknown>).limit).toBeTruthy();
+  });
+
+  test("maps request body properties", () => {
+    const tools = extractTools(minimalSpec);
+    const createPet = tools.find((t) => t.name === "createPet")!;
+    const props = createPet.inputSchema.properties as Record<string, unknown>;
+    expect(props.name).toBeTruthy();
+    expect(props.tag).toBeTruthy();
+    expect(createPet.inputSchema.required).toContain("name");
+  });
+
+  test("sets correct HTTP method", () => {
+    const tools = extractTools(minimalSpec);
+    expect(tools.find((t) => t.name === "listPets")!.method).toBe("GET");
+    expect(tools.find((t) => t.name === "createPet")!.method).toBe("POST");
+  });
+});
+
+describe("buildRequest", () => {
+  test("substitutes path parameters", () => {
+    const tool: OpenApiTool = {
+      name: "getPet",
+      description: "Get a pet",
+      inputSchema: {},
+      method: "GET",
+      path: "/pets/{petId}",
+      parameterMap: [{ name: "petId", in: "path", required: true }],
+    };
+    const { url } = buildRequest(tool, { petId: "123" }, "https://api.example.com");
+    expect(url).toBe("https://api.example.com/pets/123");
+  });
+
+  test("appends query parameters", () => {
+    const tool: OpenApiTool = {
+      name: "listPets",
+      description: "List pets",
+      inputSchema: {},
+      method: "GET",
+      path: "/pets",
+      parameterMap: [{ name: "limit", in: "query", required: false }],
+    };
+    const { url } = buildRequest(tool, { limit: 10 }, "https://api.example.com");
+    expect(url).toBe("https://api.example.com/pets?limit=10");
+  });
+
+  test("sends body as JSON for POST", () => {
+    const tool: OpenApiTool = {
+      name: "createPet",
+      description: "Create a pet",
+      inputSchema: {},
+      method: "POST",
+      path: "/pets",
+      parameterMap: [
+        { name: "name", in: "body", required: true },
+        { name: "tag", in: "body", required: false },
+      ],
+    };
+    const { url, init } = buildRequest(
+      tool,
+      { name: "Fido", tag: "dog" },
+      "https://api.example.com",
+    );
+    expect(url).toBe("https://api.example.com/pets");
+    expect(init.method).toBe("POST");
+    expect(JSON.parse(init.body as string)).toEqual({
+      name: "Fido",
+      tag: "dog",
+    });
+  });
+
+  test("merges custom headers", () => {
+    const tool: OpenApiTool = {
+      name: "listPets",
+      description: "",
+      inputSchema: {},
+      method: "GET",
+      path: "/pets",
+      parameterMap: [],
+    };
+    const { init } = buildRequest(tool, {}, "https://api.example.com", {
+      Authorization: "Bearer token",
+    });
+    expect((init.headers as Record<string, string>).Authorization).toBe("Bearer token");
+  });
+
+  test("strips trailing slash from baseUrl", () => {
+    const tool: OpenApiTool = {
+      name: "listPets",
+      description: "",
+      inputSchema: {},
+      method: "GET",
+      path: "/pets",
+      parameterMap: [],
+    };
+    const { url } = buildRequest(tool, {}, "https://api.example.com/");
+    expect(url).toBe("https://api.example.com/pets");
+  });
+});
+
+describe("$ref resolution", () => {
+  test("resolves component schema references", () => {
+    const specWithRefs = {
+      paths: {
+        "/pets": {
+          post: {
+            operationId: "createPet",
+            summary: "Create",
+            requestBody: {
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/Pet" },
+                },
+              },
+            },
+          },
+        },
+      },
+      components: {
+        schemas: {
+          Pet: {
+            type: "object",
+            properties: {
+              name: { type: "string" },
+              age: { type: "integer" },
+            },
+            required: ["name"],
+          },
+        },
+      },
+    };
+
+    const tools = extractTools(specWithRefs);
+    expect(tools).toHaveLength(1);
+    const props = tools[0].inputSchema.properties as Record<string, unknown>;
+    expect(props.name).toBeTruthy();
+    expect(props.age).toBeTruthy();
+    expect(tools[0].inputSchema.required).toContain("name");
+  });
+});

package/src/openapi.ts

@@ -0,0 +1,253 @@
+import type { Backend, ToolInfo } from "./backends.js";
+import type { BackendConfig } from "./config.js";
+
+interface OpenApiSpec {
+  paths: Record<string, Record<string, OpenApiOperation>>;
+  servers?: Array<{ url: string }>;
+  components?: { schemas?: Record<string, unknown> };
+}
+
+interface OpenApiOperation {
+  operationId?: string;
+  summary?: string;
+  description?: string;
+  parameters?: OpenApiParameter[];
+  requestBody?: { content?: { "application/json"?: { schema?: unknown } } };
+}
+
+interface OpenApiParameter {
+  name: string;
+  in: "path" | "query" | "header";
+  required?: boolean;
+  schema?: { type?: string; description?: string };
+  description?: string;
+}
+
+interface ParameterMapping {
+  name: string;
+  in: "path" | "query" | "header" | "body";
+  required: boolean;
+}
+
+export interface OpenApiTool {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  method: string;
+  path: string;
+  parameterMap: ParameterMapping[];
+}
+
+/** Fetch and parse an OpenAPI 3.x spec */
+export async function loadOpenApiSpec(specUrl: string): Promise<OpenApiSpec> {
+  const res = await fetch(specUrl);
+  if (!res.ok) throw new Error(`Failed to fetch OpenAPI spec: ${res.status}`);
+  return res.json();
+}
+
+/** Resolve a $ref to a schema definition */
+function resolveRef(ref: string, spec: OpenApiSpec): unknown {
+  const path = ref.replace("#/", "").split("/");
+  let current: unknown = spec;
+  for (const segment of path) {
+    current = (current as Record<string, unknown>)?.[segment];
+  }
+  return current ?? {};
+}
+
+/** Recursively resolve $ref in a schema */
+function resolveSchema(schema: unknown, spec: OpenApiSpec): unknown {
+  if (!schema || typeof schema !== "object") return schema;
+  if (Array.isArray(schema)) return schema.map((item) => resolveSchema(item, spec));
+  const obj = schema as Record<string, unknown>;
+  if (obj.$ref && typeof obj.$ref === "string") {
+    return resolveSchema(resolveRef(obj.$ref, spec), spec);
+  }
+  const resolved: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (typeof v === "object" && v !== null) {
+      resolved[k] = resolveSchema(v, spec);
+    } else {
+      resolved[k] = v;
+    }
+  }
+  return resolved;
+}
+
+/** Extract MCP tools from an OpenAPI spec */
+export function extractTools(spec: OpenApiSpec): OpenApiTool[] {
+  const tools: OpenApiTool[] = [];
+
+  for (const [path, methods] of Object.entries(spec.paths ?? {})) {
+    for (const [method, operation] of Object.entries(methods)) {
+      if (!operation.operationId) continue;
+
+      const parameterMap: ParameterMapping[] = [];
+      const properties: Record<string, unknown> = {};
+      const required: string[] = [];
+
+      // Path, query, header parameters
+      for (const param of operation.parameters ?? []) {
+        parameterMap.push({
+          name: param.name,
+          in: param.in,
+          required: param.required ?? param.in === "path",
+        });
+        properties[param.name] = {
+          type: param.schema?.type ?? "string",
+          description: param.description ?? param.schema?.description,
+        };
+        if (param.required || param.in === "path") {
+          required.push(param.name);
+        }
+      }
+
+      // Request body
+      const bodySchema = operation.requestBody?.content?.["application/json"]?.schema;
+      if (bodySchema) {
+        const resolved = resolveSchema(bodySchema, spec) as Record<string, unknown>;
+        if (resolved.properties) {
+          const bodyProps = resolved.properties as Record<string, unknown>;
+          const bodyRequired = (resolved.required as string[]) ?? [];
+          for (const [name, prop] of Object.entries(bodyProps)) {
+            parameterMap.push({
+              name,
+              in: "body",
+              required: bodyRequired.includes(name),
+            });
+            properties[name] = prop;
+            if (bodyRequired.includes(name)) {
+              required.push(name);
+            }
+          }
+        }
+      }
+
+      tools.push({
+        name: operation.operationId,
+        description: operation.summary ?? operation.description?.slice(0, 120) ?? "",
+        inputSchema: {
+          type: "object",
+          properties,
+          ...(required.length > 0 ? { required } : {}),
+        },
+        method: method.toUpperCase(),
+        path,
+        parameterMap,
+      });
+    }
+  }
+
+  return tools;
+}
+
+/** Build an HTTP request from a tool call */
+export function buildRequest(
+  tool: OpenApiTool,
+  args: Record<string, unknown>,
+  baseUrl: string,
+  headers?: Record<string, string>,
+): { url: string; init: RequestInit } {
+  let path = tool.path;
+  const queryParams = new URLSearchParams();
+  const bodyFields: Record<string, unknown> = {};
+  const reqHeaders: Record<string, string> = { ...headers };
+
+  for (const mapping of tool.parameterMap) {
+    const value = args[mapping.name];
+    if (value === undefined) continue;
+
+    if (mapping.in === "path") {
+      path = path.replace(`{${mapping.name}}`, encodeURIComponent(String(value)));
+    } else if (mapping.in === "query") {
+      queryParams.set(mapping.name, String(value));
+    } else if (mapping.in === "header") {
+      reqHeaders[mapping.name] = String(value);
+    } else if (mapping.in === "body") {
+      bodyFields[mapping.name] = value;
+    }
+  }
+
+  const queryString = queryParams.toString();
+  const url = `${baseUrl.replace(/\/$/, "")}${path}${queryString ? `?${queryString}` : ""}`;
+
+  const init: RequestInit = {
+    method: tool.method,
+    headers: reqHeaders,
+  };
+
+  if (Object.keys(bodyFields).length > 0 && tool.method !== "GET") {
+    init.body = JSON.stringify(bodyFields);
+    reqHeaders["Content-Type"] = "application/json";
+  }
+
+  return { url, init };
+}
+
+/** Execute an OpenAPI tool call */
+async function executeOpenApiTool(
+  tool: OpenApiTool,
+  args: Record<string, unknown>,
+  baseUrl: string,
+  headers?: Record<string, string>,
+): Promise<unknown> {
+  const { url, init } = buildRequest(tool, args, baseUrl, headers);
+  const res = await fetch(url, init);
+  const contentType = res.headers.get("content-type") ?? "";
+
+  if (!res.ok) {
+    const body = contentType.includes("json") ? await res.json() : await res.text();
+    return { error: `HTTP ${res.status}`, body };
+  }
+
+  return contentType.includes("json") ? res.json() : res.text();
+}
+
+/** Create a Backend from an OpenAPI spec — no MCP client needed */
+export async function createOpenApiBackend(name: string, config: BackendConfig): Promise<Backend> {
+  const specUrl = config.specUrl ?? config.url;
+  if (!specUrl) throw new Error(`Backend "${name}" missing specUrl or url`);
+
+  const baseUrl = config.baseUrl ?? specUrl.replace(/\/[^/]*$/, "");
+  const spec = await loadOpenApiSpec(specUrl);
+  const openApiTools = extractTools(spec);
+
+  console.log(`  ${name}: ${openApiTools.length} tools from OpenAPI spec`);
+
+  const tools: ToolInfo[] = openApiTools.map((t) => ({
+    name: t.name,
+    description: t.description,
+    inputSchema: t.inputSchema,
+  }));
+
+  // Proxy client that routes callTool to HTTP requests
+  const toolMap = new Map(openApiTools.map((t) => [t.name, t]));
+  const client = {
+    callTool: async (params: { name: string; arguments?: Record<string, unknown> }) => {
+      const tool = toolMap.get(params.name);
+      if (!tool)
+        return {
+          content: [{ type: "text", text: `Unknown tool: ${params.name}` }],
+        };
+      const result = await executeOpenApiTool(
+        tool,
+        params.arguments ?? {},
+        baseUrl,
+        config.headers,
+      );
+      return {
+        content: [
+          {
+            type: "text",
+            text: typeof result === "string" ? result : JSON.stringify(result, null, 2),
+          },
+        ],
+      };
+    },
+    listTools: async () => ({ tools: tools.map((t) => ({ ...t })) }),
+    close: async () => {},
+    connect: async () => {},
+  };
+
+  return { name, client: client as Backend["client"], tools };
+}

package/src/stdio.ts

@@ -0,0 +1,176 @@
+// Entrypoint for stdio mode — Claude Code runs this directly as a subprocess
+// Usage: mcpx stdio mcpx.json
+// Or: bunx mcpx stdio mcpx.json
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+import {
+  connectBackends,
+  generateTypeDefinitions,
+  generateToolListing,
+  refreshAllTools,
+  type Backend,
+} from "./backends.js";
+import { loadConfig } from "./config.js";
+import { executeCode } from "./executor.js";
+
+export async function startStdioServer(configPath: string): Promise<void> {
+  const config = loadConfig(configPath);
+
+  // In stdio mode, log to stderr so stdout stays clean for MCP protocol
+  process.stderr.write(`mcpx stdio starting...\n`);
+  process.stderr.write(`  config: ${configPath}\n`);
+  process.stderr.write(`  backends: ${Object.keys(config.backends).join(", ")}\n`);
+
+  const backends = await connectBackends(config.backends);
+
+  if (backends.size === 0 && !config.failOpen) {
+    process.stderr.write("No backends connected. Use failOpen: true to start anyway.\n");
+    process.exit(1);
+  }
+
+  if (backends.size === 0) {
+    process.stderr.write("Warning: no backends connected (failOpen mode)\n");
+  }
+
+  let typeDefs = generateTypeDefinitions(backends);
+  let toolListing = generateToolListing(backends);
+  const totalTools = Array.from(backends.values()).reduce((sum, b) => sum + b.tools.length, 0);
+
+  process.stderr.write(
+    `\n${totalTools} tools from ${backends.size} backends -> 2 Code Mode tools\n`,
+  );
+
+  // Periodic tool refresh
+  if (config.toolRefreshInterval && config.toolRefreshInterval > 0) {
+    setInterval(async () => {
+      try {
+        await refreshAllTools(backends);
+        typeDefs = generateTypeDefinitions(backends);
+        toolListing = generateToolListing(backends);
+      } catch (err) {
+        process.stderr.write(`Tool refresh failed: ${(err as Error).message}\n`);
+      }
+    }, config.toolRefreshInterval * 1000);
+  }
+
+  const server = createMcpServer(backends, typeDefs, toolListing);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  process.stderr.write("mcpx stdio ready\n");
+}
+
+function createMcpServer(
+  backends: Map<string, Backend>,
+  typeDefs: string,
+  toolListing: string,
+): McpServer {
+  const server = new McpServer({
+    name: "mcpx",
+    version: "0.1.0",
+  });
+
+  server.tool(
+    "search",
+    `Search available tools across all connected MCP servers. Returns type definitions for matched tools.
+
+Available tools:
+${toolListing}`,
+    {
+      query: z.string().describe("Search query — tool name, backend name, or keyword"),
+    },
+    async ({ query }) => {
+      const q = query.toLowerCase();
+      const matched: string[] = [];
+
+      for (const [name, backend] of backends) {
+        for (const tool of backend.tools) {
+          const fullName = `${name}_${tool.name}`;
+          const desc = tool.description?.toLowerCase() ?? "";
+          if (
+            fullName.toLowerCase().includes(q) ||
+            desc.includes(q) ||
+            name.toLowerCase().includes(q)
+          ) {
+            const params = tool.inputSchema?.properties
+              ? JSON.stringify(tool.inputSchema.properties, null, 2)
+              : "{}";
+            matched.push(`### ${fullName}\n${tool.description ?? ""}\nParameters: ${params}`);
+          }
+        }
+      }
+
+      if (matched.length === 0) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `No tools found matching "${query}". Available backends: ${Array.from(backends.keys()).join(", ")}`,
+            },
+          ],
+        };
+      }
+
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Found ${matched.length} tools:\n\n${matched.join("\n\n")}`,
+          },
+        ],
+      };
+    },
+  );
+
+  server.tool(
+    "execute",
+    `Execute JavaScript code that calls MCP tools. The code runs in a V8 isolate.
+
+Write an async function body. Available tool functions (call with await):
+${typeDefs}
+
+Example (namespace style):
+  const result = await grafana.searchDashboards({ query: "pods" });
+  return result;
+
+Example (classic style):
+  const result = await grafana_search_dashboards({ query: "pods" });
+  return result;`,
+    { code: z.string().describe("JavaScript async function body to execute") },
+    async ({ code }) => {
+      const result = await executeCode(code, backends);
+
+      if (result.isErr()) {
+        const e = result.error;
+        let msg = e.kind === "runtime" ? `Execution failed with code ${e.code}` : e.message;
+        if (e.kind === "parse" && e.snippet) {
+          msg += `\n\n${e.snippet}`;
+        }
+        return {
+          content: [{ type: "text" as const, text: `Error: ${msg}` }],
+          isError: true,
+        };
+      }
+
+      const val = result.value.value;
+      const text = typeof val === "string" ? val : JSON.stringify(val, null, 2);
+      const logText =
+        result.value.logs.length > 0
+          ? `\n\n--- Console Output ---\n${result.value.logs.map((l) => `[${l.level}] ${l.args.map((a) => (typeof a === "string" ? a : JSON.stringify(a))).join(" ")}`).join("\n")}`
+          : "";
+
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: text + logText,
+          },
+        ],
+      };
+    },
+  );
+
+  return server;
+}