@teampitch/mcpx 0.2.1

package/src/backends.test.ts

@@ -0,0 +1,205 @@
+import { describe, test, expect } from "bun:test";
+import {
+  generateTypeDefinitions,
+  generateToolListing,
+  sanitizeName,
+  type Backend,
+} from "./backends.js";
+
+// Minimal mock backend factory
+function makeMockBackend(name: string, tools: Backend["tools"]): [string, Backend] {
+  return [
+    name,
+    {
+      name,
+      client: {} as Backend["client"],
+      tools,
+    },
+  ];
+}
+
+describe("sanitizeName", () => {
+  test("leaves alphanumeric and underscores unchanged", () => {
+    expect(sanitizeName("my_tool_name")).toBe("my_tool_name");
+    expect(sanitizeName("tool123")).toBe("tool123");
+  });
+
+  test("replaces hyphens with underscores", () => {
+    expect(sanitizeName("my-tool")).toBe("my_tool");
+  });
+
+  test("replaces dots and slashes with underscores", () => {
+    expect(sanitizeName("some.tool/name")).toBe("some_tool_name");
+  });
+
+  test("replaces spaces with underscores", () => {
+    expect(sanitizeName("my tool")).toBe("my_tool");
+  });
+
+  test("handles already clean name", () => {
+    expect(sanitizeName("cleanName")).toBe("cleanName");
+  });
+
+  test("handles empty string", () => {
+    expect(sanitizeName("")).toBe("");
+  });
+});
+
+describe("generateTypeDefinitions", () => {
+  test("returns header comment for empty backends", () => {
+    const backends = new Map<string, Backend>();
+    const result = generateTypeDefinitions(backends);
+    expect(result).toContain("Available MCP tool functions");
+  });
+
+  test("generates declare function for each tool", () => {
+    const backends = new Map<string, Backend>([
+      makeMockBackend("grafana", [
+        {
+          name: "search_dashboards",
+          description: "Search dashboards",
+          inputSchema: {
+            properties: { query: { type: "string", description: "Search query" } },
+            required: ["query"],
+          },
+        },
+      ]),
+    ]);
+
+    const result = generateTypeDefinitions(backends);
+    expect(result).toContain("declare function grafana_search_dashboards");
+    expect(result).toContain("query: string");
+    expect(result).toContain("Promise<any>");
+  });
+
+  test("marks optional params without required marker", () => {
+    const backends = new Map<string, Backend>([
+      makeMockBackend("mybackend", [
+        {
+          name: "my_tool",
+          description: "A tool",
+          inputSchema: {
+            properties: {
+              required_param: { type: "string" },
+              optional_param: { type: "number" },
+            },
+            required: ["required_param"],
+          },
+        },
+      ]),
+    ]);
+
+    const result = generateTypeDefinitions(backends);
+    expect(result).toContain("required_param: string");
+    expect(result).toContain("optional_param?: number");
+  });
+
+  test("uses any[] for array type params", () => {
+    const backends = new Map<string, Backend>([
+      makeMockBackend("srv", [
+        {
+          name: "bulk_op",
+          description: "Bulk operation",
+          inputSchema: {
+            properties: { items: { type: "array" } },
+            required: ["items"],
+          },
+        },
+      ]),
+    ]);
+
+    const result = generateTypeDefinitions(backends);
+    expect(result).toContain("items: any[]");
+  });
+
+  test("generates entries for multiple backends", () => {
+    const backends = new Map<string, Backend>([
+      makeMockBackend("alpha", [{ name: "do_a", description: "Do A", inputSchema: {} }]),
+      makeMockBackend("beta", [{ name: "do_b", description: "Do B", inputSchema: {} }]),
+    ]);
+
+    const result = generateTypeDefinitions(backends);
+    expect(result).toContain("// === alpha ===");
+    expect(result).toContain("declare function alpha_do_a");
+    expect(result).toContain("// === beta ===");
+    expect(result).toContain("declare function beta_do_b");
+  });
+
+  test("sanitizes hyphens in tool names", () => {
+    const backends = new Map<string, Backend>([
+      makeMockBackend("srv", [
+        { name: "my-hyphenated-tool", description: "A tool", inputSchema: {} },
+      ]),
+    ]);
+
+    const result = generateTypeDefinitions(backends);
+    expect(result).toContain("declare function srv_my_hyphenated_tool");
+  });
+
+  test("includes description snippet (up to 80 chars)", () => {
+    const desc = "A very useful tool that does something important";
+    const backends = new Map<string, Backend>([
+      makeMockBackend("srv", [{ name: "tool", description: desc, inputSchema: {} }]),
+    ]);
+
+    const result = generateTypeDefinitions(backends);
+    expect(result).toContain(desc);
+  });
+});
+
+describe("generateToolListing", () => {
+  test("returns empty string for no backends", () => {
+    const backends = new Map<string, Backend>();
+    expect(generateToolListing(backends)).toBe("");
+  });
+
+  test("lists tool with name and description", () => {
+    const backends = new Map<string, Backend>([
+      makeMockBackend("grafana", [
+        {
+          name: "search_dashboards",
+          description: "Search dashboards by query",
+          inputSchema: {},
+        },
+      ]),
+    ]);
+
+    const result = generateToolListing(backends);
+    expect(result).toContain("grafana_search_dashboards");
+    expect(result).toContain("Search dashboards by query");
+  });
+
+  test("truncates description to 60 chars", () => {
+    const longDesc = "A".repeat(100);
+    const backends = new Map<string, Backend>([
+      makeMockBackend("srv", [{ name: "tool", description: longDesc, inputSchema: {} }]),
+    ]);
+
+    const result = generateToolListing(backends);
+    const line = result.split("\n")[0];
+    // description portion should be 60 chars
+    expect(line).toContain("A".repeat(60));
+    expect(line).not.toContain("A".repeat(61));
+  });
+
+  test("handles tool with no description", () => {
+    const backends = new Map<string, Backend>([
+      makeMockBackend("srv", [{ name: "no_desc_tool", inputSchema: {} }]),
+    ]);
+
+    const result = generateToolListing(backends);
+    expect(result).toContain("srv_no_desc_tool: ");
+  });
+
+  test("generates one line per tool", () => {
+    const backends = new Map<string, Backend>([
+      makeMockBackend("srv", [
+        { name: "tool_a", description: "Tool A", inputSchema: {} },
+        { name: "tool_b", description: "Tool B", inputSchema: {} },
+      ]),
+    ]);
+
+    const lines = generateToolListing(backends).split("\n");
+    expect(lines).toHaveLength(2);
+  });
+});

package/src/backends.ts

@@ -0,0 +1,159 @@
+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 { BackendConfig } from "./config.js";
+import { createOpenApiBackend } from "./openapi.js";
+
+export interface ToolInfo {
+  name: string;
+  description?: string;
+  inputSchema: Record<string, unknown>;
+}
+
+export interface Backend {
+  name: string;
+  client: Client;
+  tools: ToolInfo[];
+}
+
+/** Connect to a backend MCP server via stdio subprocess */
+async function connectStdio(name: string, config: BackendConfig): Promise<Backend> {
+  if (!config.command) throw new Error(`Backend "${name}" missing command`);
+
+  const transport = new StdioClientTransport({
+    command: config.command,
+    args: config.args ?? [],
+    env: { ...process.env, ...config.env } as Record<string, string>,
+  });
+
+  const client = new Client({ name: `mcpx-${name}`, version: "0.1.0" });
+  await client.connect(transport);
+
+  const { tools } = await client.listTools();
+  const toolInfos: ToolInfo[] = tools.map((t) => ({
+    name: t.name,
+    description: t.description,
+    inputSchema: t.inputSchema as Record<string, unknown>,
+  }));
+
+  console.log(`  ${name}: ${toolInfos.length} tools connected`);
+  return { name, client, tools: toolInfos };
+}
+
+/** Connect to a backend MCP server via HTTP (Streamable HTTP) */
+async function connectHttp(name: string, config: BackendConfig): Promise<Backend> {
+  if (!config.url) throw new Error(`Backend "${name}" missing url`);
+
+  const transport = new StreamableHTTPClientTransport(new URL(config.url), {
+    requestInit: config.headers ? { headers: config.headers } : undefined,
+  });
+
+  const client = new Client({ name: `mcpx-${name}`, version: "0.1.0" });
+  await client.connect(transport);
+
+  const { tools } = await client.listTools();
+  const toolInfos: ToolInfo[] = tools.map((t) => ({
+    name: t.name,
+    description: t.description,
+    inputSchema: t.inputSchema as Record<string, unknown>,
+  }));
+
+  console.log(`  ${name}: ${toolInfos.length} tools connected (http)`);
+  return { name, client, tools: toolInfos };
+}
+
+/** Connect to all configured backends */
+export async function connectBackends(
+  configs: Record<string, BackendConfig>,
+): Promise<Map<string, Backend>> {
+  const backends = new Map<string, Backend>();
+
+  for (const [name, config] of Object.entries(configs)) {
+    try {
+      if (config.transport === "stdio") {
+        const backend = await connectStdio(name, config);
+        backends.set(name, backend);
+      } else if (config.transport === "http") {
+        const backend = await connectHttp(name, config);
+        backends.set(name, backend);
+      } else if (config.transport === "openapi") {
+        const backend = await createOpenApiBackend(name, config);
+        backends.set(name, backend);
+      }
+    } catch (err) {
+      console.error(`  ${name}: failed to connect —`, (err as Error).message);
+    }
+  }
+
+  return backends;
+}
+
+/** Refresh tool lists from a single backend */
+async function refreshBackendTools(backend: Backend): Promise<void> {
+  const { tools } = await backend.client.listTools();
+  backend.tools = tools.map((t) => ({
+    name: t.name,
+    description: t.description,
+    inputSchema: t.inputSchema as Record<string, unknown>,
+  }));
+}
+
+/** Refresh tool lists from all backends */
+export async function refreshAllTools(backends: Map<string, Backend>): Promise<void> {
+  for (const [name, backend] of backends) {
+    try {
+      await refreshBackendTools(backend);
+    } catch (err) {
+      console.error(`  ${name}: tool refresh failed —`, (err as Error).message);
+    }
+  }
+}
+
+/** Generate TypeScript type definitions from all backend tools for the LLM */
+export function generateTypeDefinitions(backends: Map<string, Backend>): string {
+  const lines: string[] = [
+    "// Available MCP tool functions — call these in your execute code",
+    "// Each function returns a Promise<{ content: Array<{ type: string, text: string }> }>",
+    "",
+  ];
+
+  for (const [name, backend] of backends) {
+    lines.push(`// === ${name} ===`);
+    for (const tool of backend.tools) {
+      const params = tool.inputSchema?.properties
+        ? Object.entries(
+            tool.inputSchema.properties as Record<string, { type?: string; description?: string }>,
+          )
+            .map(([k, v]) => {
+              const required = (tool.inputSchema.required as string[] | undefined)?.includes(k);
+              return `${k}${required ? "" : "?"}: ${v.type === "array" ? "any[]" : (v.type ?? "any")}`;
+            })
+            .join(", ")
+        : "";
+      const desc = tool.description ? ` — ${tool.description.slice(0, 80)}` : "";
+      lines.push(
+        `declare function ${name}_${sanitizeName(tool.name)}(args: { ${params} }): Promise<any>;${desc}`,
+      );
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+/** Generate a compact tool listing for the search tool description */
+export function generateToolListing(backends: Map<string, Backend>): string {
+  const lines: string[] = [];
+  for (const [name, backend] of backends) {
+    for (const tool of backend.tools) {
+      const desc = tool.description?.slice(0, 60) ?? "";
+      lines.push(`${name}_${sanitizeName(tool.name)}: ${desc}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+export function sanitizeName(name: string): string {
+  return name.replace(/[^a-zA-Z0-9_]/g, "_");
+}

package/src/config.test.ts

@@ -0,0 +1,149 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { writeFileSync, unlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { loadConfig } from "./config.js";
+
+describe("loadConfig", () => {
+  let tmpFile: string;
+
+  beforeEach(() => {
+    tmpFile = join(tmpdir(), `mcpx-test-${Date.now()}.json`);
+  });
+
+  afterEach(() => {
+    try {
+      unlinkSync(tmpFile);
+    } catch {
+      // ignore if already deleted
+    }
+  });
+
+  test("loads minimal config with defaults", () => {
+    writeFileSync(
+      tmpFile,
+      JSON.stringify({
+        backends: {},
+      }),
+    );
+
+    const config = loadConfig(tmpFile);
+    expect(config.port).toBe(3100);
+    expect(config.authToken).toBeUndefined();
+    expect(config.backends).toEqual({});
+  });
+
+  test("loads port and authToken", () => {
+    writeFileSync(
+      tmpFile,
+      JSON.stringify({
+        port: 4000,
+        authToken: "secret-token",
+        backends: {},
+      }),
+    );
+
+    const config = loadConfig(tmpFile);
+    expect(config.port).toBe(4000);
+    expect(config.authToken).toBe("secret-token");
+  });
+
+  test("interpolates ${VAR} from process.env in authToken", () => {
+    process.env.TEST_AUTH_TOKEN = "from-env-token";
+    writeFileSync(
+      tmpFile,
+      JSON.stringify({
+        authToken: "${TEST_AUTH_TOKEN}",
+        backends: {},
+      }),
+    );
+
+    const config = loadConfig(tmpFile);
+    expect(config.authToken).toBe("from-env-token");
+    delete process.env.TEST_AUTH_TOKEN;
+  });
+
+  test("interpolates ${VAR} in backend env values", () => {
+    process.env.MY_API_KEY = "key-from-env";
+    writeFileSync(
+      tmpFile,
+      JSON.stringify({
+        backends: {
+          myserver: {
+            transport: "stdio",
+            command: "echo",
+            env: {
+              API_KEY: "${MY_API_KEY}",
+              STATIC: "literal-value",
+            },
+          },
+        },
+      }),
+    );
+
+    const config = loadConfig(tmpFile);
+    expect(config.backends.myserver.env?.API_KEY).toBe("key-from-env");
+    expect(config.backends.myserver.env?.STATIC).toBe("literal-value");
+    delete process.env.MY_API_KEY;
+  });
+
+  test("replaces missing env vars with empty string", () => {
+    delete process.env.MISSING_VAR;
+    writeFileSync(
+      tmpFile,
+      JSON.stringify({
+        backends: {
+          srv: {
+            transport: "stdio",
+            command: "echo",
+            env: { KEY: "${MISSING_VAR}" },
+          },
+        },
+      }),
+    );
+
+    const config = loadConfig(tmpFile);
+    expect(config.backends.srv.env?.KEY).toBe("");
+  });
+
+  test("throws on missing file", () => {
+    expect(() => loadConfig("/tmp/does-not-exist-mcpx.json")).toThrow();
+  });
+
+  test("throws on invalid JSON", () => {
+    writeFileSync(tmpFile, "not valid json {{{");
+    expect(() => loadConfig(tmpFile)).toThrow();
+  });
+
+  test("loads empty backends", () => {
+    writeFileSync(tmpFile, JSON.stringify({ backends: {} }));
+    const config = loadConfig(tmpFile);
+    expect(Object.keys(config.backends)).toHaveLength(0);
+  });
+
+  test("loads multiple backends", () => {
+    writeFileSync(
+      tmpFile,
+      JSON.stringify({
+        backends: {
+          grafana: { transport: "stdio", command: "grafana-mcp" },
+          github: { transport: "stdio", command: "github-mcp", args: ["--token", "abc"] },
+        },
+      }),
+    );
+
+    const config = loadConfig(tmpFile);
+    expect(Object.keys(config.backends)).toHaveLength(2);
+    expect(config.backends.grafana.command).toBe("grafana-mcp");
+    expect(config.backends.github.args).toEqual(["--token", "abc"]);
+  });
+
+  test("falls back to MCPX_AUTH_TOKEN env if authToken not in config", () => {
+    process.env.MCPX_AUTH_TOKEN = "env-fallback-token";
+    writeFileSync(tmpFile, JSON.stringify({ backends: {} }));
+
+    const config = loadConfig(tmpFile);
+    expect(config.authToken).toBe("env-fallback-token");
+    delete process.env.MCPX_AUTH_TOKEN;
+  });
+});

package/src/config.ts

@@ -0,0 +1,134 @@
+import { readFileSync } from "node:fs";
+
+export interface BackendConfig {
+  /** Transport: stdio spawns a subprocess, http connects to a remote MCP server, openapi proxies a REST API */
+  transport: "stdio" | "http" | "openapi";
+  /** For stdio: command to run */
+  command?: string;
+  /** For stdio: arguments */
+  args?: string[];
+  /** For http: MCP server URL. For openapi: spec URL. */
+  url?: string;
+  /** For openapi: spec URL (alternative to url) */
+  specUrl?: string;
+  /** For openapi: base URL for API calls (defaults to spec servers[0]) */
+  baseUrl?: string;
+  /** Environment variables for stdio subprocess — supports ${VAR} interpolation from process.env */
+  env?: Record<string, string>;
+  /** HTTP headers for http transport — supports ${VAR} interpolation */
+  headers?: Record<string, string>;
+  /** JWT roles allowed to access this backend */
+  allowedRoles?: string[];
+  /** JWT teams allowed to access this backend */
+  allowedTeams?: string[];
+}
+
+export interface McpxConfig {
+  /** Port to listen on */
+  port: number;
+  /** Bearer token for authentication (optional) */
+  authToken?: string;
+  /** Allow startup with 0 connected backends (default: false) */
+  failOpen?: boolean;
+  /** Interval in seconds to refresh tool lists from backends (0 = disabled) */
+  toolRefreshInterval?: number;
+  /** Auth configuration */
+  auth?: {
+    /** Simple bearer token */
+    bearer?: string;
+    /** JWT verification */
+    jwt?: {
+      /** HMAC symmetric secret */
+      secret?: string;
+      /** JWKS endpoint for asymmetric keys */
+      jwksUrl?: string;
+      /** Expected audience claim */
+      audience?: string;
+      /** Expected issuer claim */
+      issuer?: string;
+    };
+    /** MCP OAuth 2.0 server */
+    oauth?: {
+      /** Issuer URL (e.g. https://mcp.yourcompany.com) */
+      issuer: string;
+      /** Allowed clients with redirect URI patterns */
+      clients: Array<{ name: string; redirectUri: string }>;
+      /** Secret for signing access tokens */
+      tokenSecret: string;
+      /** Access token TTL in minutes */
+      tokenTtlMinutes: number;
+    };
+  };
+  /** Session TTL in minutes for HTTP mode (default: 30) */
+  sessionTtlMinutes?: number;
+  /** Backend MCP servers */
+  backends: Record<string, BackendConfig>;
+}
+
+/** Interpolate ${VAR} references from process.env */
+function interpolate(value: string): string {
+  return value.replace(/\$\{(\w+)\}/g, (_, name) => process.env[name] ?? "");
+}
+
+function interpolateRecord(record: Record<string, string>): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const [k, v] of Object.entries(record)) {
+    result[k] = interpolate(v);
+  }
+  return result;
+}
+
+export function loadConfig(path: string): McpxConfig {
+  const raw = readFileSync(path, "utf-8");
+
+  // Simple YAML-like parser for our config format
+  // For production, use a proper YAML parser — keeping deps minimal for now
+  const parsed = JSON.parse(raw);
+
+  // Normalize auth config (backward compat: authToken → auth.bearer)
+  const legacyAuthToken = parsed.authToken
+    ? interpolate(parsed.authToken)
+    : process.env.MCPX_AUTH_TOKEN;
+
+  const auth = parsed.auth
+    ? {
+        bearer: parsed.auth.bearer ? interpolate(parsed.auth.bearer) : undefined,
+        jwt: parsed.auth.jwt
+          ? {
+              secret: parsed.auth.jwt.secret ? interpolate(parsed.auth.jwt.secret) : undefined,
+              jwksUrl: parsed.auth.jwt.jwksUrl ? interpolate(parsed.auth.jwt.jwksUrl) : undefined,
+              audience: parsed.auth.jwt.audience,
+              issuer: parsed.auth.jwt.issuer,
+            }
+          : undefined,
+        oauth: parsed.auth?.oauth
+          ? {
+              issuer: parsed.auth.oauth.issuer,
+              clients: parsed.auth.oauth.clients ?? [],
+              tokenSecret: interpolate(parsed.auth.oauth.tokenSecret ?? ""),
+              tokenTtlMinutes: parsed.auth.oauth.tokenTtlMinutes ?? 60,
+            }
+          : undefined,
+      }
+    : undefined;
+
+  const config: McpxConfig = {
+    port: parsed.port ?? 3100,
+    authToken: legacyAuthToken,
+    auth,
+    failOpen: parsed.failOpen ?? false,
+    toolRefreshInterval: parsed.toolRefreshInterval ?? 0,
+    sessionTtlMinutes: parsed.sessionTtlMinutes ?? 30,
+    backends: {},
+  };
+
+  for (const [name, backend] of Object.entries(parsed.backends as Record<string, BackendConfig>)) {
+    config.backends[name] = {
+      ...backend,
+      env: backend.env ? interpolateRecord(backend.env) : undefined,
+      headers: backend.headers ? interpolateRecord(backend.headers) : undefined,
+    };
+  }
+
+  return config;
+}