mcp-orbit 0.1.0

package/src/__tests__/tool-registry.basic.test.ts

@@ -0,0 +1,114 @@
+import {describe, it, expect, beforeEach} from "vitest";
+import {z} from "zod";
+import {registerTool, getTool, getToolCount, getToolDefinitions, executeTool} from "../core/server.js";
+import type {Tool} from "../core/types.js";
+
+function createEchoTool(name = "test_echo"): Tool {
+  const inputSchema = z.object({
+    message: z.string().describe("Message to echo"),
+  });
+
+  return {
+    definition: {
+      name,
+      description: "Echo a message back",
+      inputSchema: {
+        type: "object",
+        properties: {message: {type: "string"}},
+        required: ["message"],
+      },
+    },
+    runtimeInputSchema: inputSchema,
+    async execute(args: unknown) {
+      const {message} = inputSchema.parse(args);
+      return {
+        content: [{type: "text", text: message}],
+      };
+    },
+  };
+}
+
+describe("Tool Registry", () => {
+  // Note: tool registry is global (module-level Map), so tools persist across tests.
+  // We use unique names per test to avoid interference.
+
+  it("registers and retrieves a tool", () => {
+    const tool = createEchoTool("reg_retrieve");
+    registerTool(tool);
+
+    const retrieved = getTool("reg_retrieve");
+    expect(retrieved).toBeDefined();
+    expect(retrieved!.definition.name).toBe("reg_retrieve");
+  });
+
+  it("getTool returns undefined for unknown tools", () => {
+    expect(getTool("nonexistent_tool_xyz")).toBeUndefined();
+  });
+
+  it("getToolCount reflects registered tools", () => {
+    const before = getToolCount();
+    registerTool(createEchoTool(`count_test_${Date.now()}`));
+    expect(getToolCount()).toBe(before + 1);
+  });
+
+  it("getToolDefinitions returns all definitions", () => {
+    registerTool(createEchoTool("def_test_a"));
+    registerTool(createEchoTool("def_test_b"));
+
+    const defs = getToolDefinitions();
+    const names = defs.map((d) => d.name);
+    expect(names).toContain("def_test_a");
+    expect(names).toContain("def_test_b");
+  });
+
+  it("overwrites existing tool on re-register", () => {
+    const tool1 = createEchoTool("overwrite_test");
+    tool1.definition.description = "Version 1";
+    registerTool(tool1);
+
+    const tool2 = createEchoTool("overwrite_test");
+    tool2.definition.description = "Version 2";
+    registerTool(tool2);
+
+    const retrieved = getTool("overwrite_test");
+    expect(retrieved!.definition.description).toBe("Version 2");
+  });
+});
+
+describe("Tool Execution", () => {
+  it("executes a tool with valid args", async () => {
+    registerTool(createEchoTool("exec_valid"));
+
+    const result = await executeTool("exec_valid", {message: "hello"});
+    expect(result.content).toHaveLength(1);
+    expect(result.content[0]).toEqual({type: "text", text: "hello"});
+    expect(result.isError).toBeFalsy();
+  });
+
+  it("throws on unknown tool", async () => {
+    await expect(executeTool("unknown_tool_xyz", {})).rejects.toThrow("Unknown tool");
+  });
+
+  it("throws on invalid args (Zod validation)", async () => {
+    registerTool(createEchoTool("exec_invalid"));
+
+    await expect(executeTool("exec_invalid", {message: 123})).rejects.toThrow();
+  });
+
+  it("handles tool execution errors", async () => {
+    const failingTool: Tool = {
+      definition: {
+        name: "exec_failing",
+        description: "Always fails",
+        inputSchema: {type: "object", properties: {}},
+      },
+      runtimeInputSchema: z.object({}),
+      async execute() {
+        throw new Error("Intentional failure");
+      },
+    };
+    registerTool(failingTool);
+
+    await expect(executeTool("exec_failing", {})).rejects.toThrow("Intentional failure");
+  });
+});

package/src/__tests__/zod-schema.basic.test.ts

@@ -0,0 +1,105 @@
+import {describe, it, expect} from "vitest";
+import {z} from "zod";
+import {zodToMcpJsonSchema, isZodArray, fixAdditionalProperties} from "../utils/zod-to-mcp-schema.js";
+
+describe("zodToMcpJsonSchema", () => {
+  it("converts a simple object schema", () => {
+    const schema = z.object({
+      name: z.string().describe("A name"),
+      age: z.number().describe("An age"),
+    });
+
+    const result = zodToMcpJsonSchema(schema);
+    expect(result).toHaveProperty("type", "object");
+    expect(result).toHaveProperty("properties.name");
+    expect(result).toHaveProperty("properties.age");
+    expect((result as any).properties.name.type).toBe("string");
+    expect((result as any).properties.age.type).toBe("number");
+  });
+
+  it("includes required fields", () => {
+    const schema = z.object({
+      required: z.string(),
+      optional: z.string().optional(),
+    });
+
+    const result = zodToMcpJsonSchema(schema) as any;
+    expect(result.required).toContain("required");
+    expect(result.required).not.toContain("optional");
+  });
+
+  it("handles enum types", () => {
+    const schema = z.object({
+      color: z.enum(["red", "green", "blue"]),
+    });
+
+    const result = zodToMcpJsonSchema(schema) as any;
+    expect(result.properties.color.enum).toEqual(["red", "green", "blue"]);
+  });
+
+  it("handles nested objects", () => {
+    const schema = z.object({
+      nested: z.object({
+        inner: z.string(),
+      }),
+    });
+
+    const result = zodToMcpJsonSchema(schema) as any;
+    expect(result.properties.nested.type).toBe("object");
+    expect(result.properties.nested.properties.inner.type).toBe("string");
+  });
+
+  it("handles arrays", () => {
+    const schema = z.object({
+      items: z.array(z.string()),
+    });
+
+    const result = zodToMcpJsonSchema(schema) as any;
+    expect(result.properties.items.type).toBe("array");
+    expect(result.properties.items.items.type).toBe("string");
+  });
+
+  it("wraps top-level array schemas in object wrapper", () => {
+    const schema = z.array(z.string());
+
+    const result = zodToMcpJsonSchema(schema) as any;
+    // Array schemas should be wrapped for MCP compliance
+    expect(result.type).toBe("object");
+    expect(result.properties.result).toBeDefined();
+  });
+
+  it("preserves descriptions", () => {
+    const schema = z.object({
+      field: z.string().describe("My description"),
+    });
+
+    const result = zodToMcpJsonSchema(schema) as any;
+    expect(result.properties.field.description).toBe("My description");
+  });
+});
+
+describe("isZodArray", () => {
+  it("detects array schemas", () => {
+    expect(isZodArray(z.array(z.string()))).toBe(true);
+  });
+
+  it("rejects non-array schemas", () => {
+    expect(isZodArray(z.object({}))).toBe(false);
+    expect(isZodArray(z.string())).toBe(false);
+    expect(isZodArray(z.number())).toBe(false);
+  });
+});
+
+describe("fixAdditionalProperties", () => {
+  it("normalizes additionalProperties to boolean", () => {
+    const schema = {type: "object", additionalProperties: {}};
+    const result = fixAdditionalProperties(schema, true);
+    expect(result.additionalProperties).toBe(true);
+  });
+
+  it("preserves existing boolean additionalProperties", () => {
+    const schema = {type: "object", additionalProperties: false};
+    const result = fixAdditionalProperties(schema, true);
+    expect(result.additionalProperties).toBe(false);
+  });
+});

package/src/cli.ts

@@ -0,0 +1,58 @@
+/**
+ * CLI Helpers — shared by all mcp-orbit packages
+ *
+ * parseArgs(): Reads --stdio / --http / --http-port / --http-host from argv
+ *              and PORT / MCP_HTTP_HOST from env.
+ */
+
+import type {ServerConfig, TransportMode} from "./core/server.js";
+
+/**
+ * Parse command line arguments into a ServerConfig.
+ *
+ * Examples:
+ *   node index.js                              → stdio (default, unless PORT is set)
+ *   node index.js --stdio                      → stdio (explicit)
+ *   node index.js --http                       → HTTP on 0.0.0.0:3333 (or PORT)
+ *   node index.js --http --http-port=8080      → HTTP on 0.0.0.0:8080
+ *   node index.js --http --http-host=127.0.0.1 → HTTP on 127.0.0.1:3333
+ *
+ * Environment variables:
+ *   PORT           → auto-enables HTTP mode (Render/Cloud standard)
+ *   MCP_HTTP_HOST  → override host binding (default 0.0.0.0)
+ */
+export function parseArgs(): ServerConfig {
+  const args = process.argv.slice(2);
+
+  let mode: TransportMode = process.env.PORT ? "http" : "stdio";
+  let httpPort: number | undefined = process.env.PORT ? parseInt(process.env.PORT, 10) : undefined;
+  let httpHost: string | undefined = process.env.MCP_HTTP_HOST || "0.0.0.0";
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--http") {
+      mode = "http";
+    } else if (arg === "--stdio") {
+      mode = "stdio";
+    } else if (arg.startsWith("--http-port=")) {
+      httpPort = parseInt(arg.split("=")[1] || "", 10);
+      mode = "http";
+    } else if (arg === "--http-port") {
+      httpPort = parseInt(args[++i] || "", 10);
+      mode = "http";
+    } else if (arg.startsWith("--http-host=")) {
+      httpHost = arg.split("=")[1];
+      mode = "http";
+    } else if (arg === "--http-host") {
+      httpHost = args[++i];
+      mode = "http";
+    }
+  }
+
+  if (mode === "http" && (!httpPort || isNaN(httpPort))) {
+    httpPort = 3333;
+  }
+
+  return {mode, httpPort, httpHost};
+}
+

package/src/clients/mcp-http.ts

@@ -0,0 +1,192 @@
+/**
+ * HTTP MCP Client (Protocol 2025-03-26)
+ *
+ * Modern MCP client using StreamableHTTPClientTransport
+ * Features:
+ * - Session management with automatic reconnection
+ * - Bearer token authentication via custom headers
+ * - Type-safe tool execution
+ * - Resource & Prompt management
+ * - Connection pooling & caching
+ *
+ * Based on MCP SDK:
+ * @see @modelcontextprotocol/sdk/client/streamableHttp
+ */
+
+import {Client} from "@modelcontextprotocol/sdk/client/index.js";
+import {StreamableHTTPClientTransport} from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import type {
+  McpHttpServerConfig,
+  MCPToolSchema,
+  MCPToolResponse,
+  MCPResourceList,
+  MCPResourceContent,
+  MCPPromptList,
+  MCPPromptResponse,
+  IMcpClient,
+} from "./types.js";
+
+export class HttpMCPClient implements IMcpClient {
+  private clientCache = new Map<string, Client>();
+  private connectionPromises = new Map<string, Promise<Client>>();
+  private readonly serverConfig: McpHttpServerConfig;
+
+  // Event handlers (exposed from underlying MCP SDK Client)
+  public onerror?: (error: Error) => void;
+  public onclose?: () => void;
+
+  constructor(serverConfig: McpHttpServerConfig) {
+    this.serverConfig = serverConfig;
+  }
+
+  // ============================================================================
+  // TOOLS
+  // ============================================================================
+
+  async listTools(timeoutMs = 15000): Promise<{tools: MCPToolSchema[]}> {
+    const client = await this.getOrCreateClient(this.serverConfig, timeoutMs);
+    const resp = (await client.listTools({}, {timeout: timeoutMs} as any)) as any;
+
+    const tools: MCPToolSchema[] = Array.isArray(resp?.tools)
+      ? resp.tools.map((tool: any) => ({
+          name: tool.name,
+          description: tool.description,
+          input_schema: tool.input_schema ?? tool.inputSchema ?? {type: "object", properties: {}},
+          tags: tool.tags ?? tool._meta?.tags,
+        }))
+      : [];
+
+    return {tools};
+  }
+
+  async callTool(toolName: string, args: Record<string, any>, timeoutMs = 15000): Promise<MCPToolResponse> {
+    const client = await this.getOrCreateClient(this.serverConfig, timeoutMs);
+
+    const response = (await client.callTool(
+      {
+        name: toolName,
+        arguments: args,
+      },
+      undefined,
+      {timeout: timeoutMs} as any,
+    )) as any;
+
+    return {
+      content: Array.isArray(response?.content) ? response.content : [],
+      isError: response?.isError ?? false,
+      structuredContent: response?.structuredContent,
+      _meta: response?._meta,
+    };
+  }
+
+  // ============================================================================
+  // RESOURCES
+  // ============================================================================
+
+  async listResources(timeoutMs = 15000): Promise<MCPResourceList> {
+    const client = await this.getOrCreateClient(this.serverConfig, timeoutMs);
+    const response = (await client.listResources({}, {timeout: timeoutMs} as any)) as any;
+    return {
+      resources: response.resources || [],
+    };
+  }
+
+  async readResource(uri: string, timeoutMs = 15000): Promise<MCPResourceContent> {
+    const client = await this.getOrCreateClient(this.serverConfig, timeoutMs);
+    const response = (await client.readResource({uri}, {timeout: timeoutMs} as any)) as any;
+    return {
+      contents: response.contents || [],
+    };
+  }
+
+  // ============================================================================
+  // PROMPTS
+  // ============================================================================
+
+  async listPrompts(timeoutMs = 15000): Promise<MCPPromptList> {
+    const client = await this.getOrCreateClient(this.serverConfig, timeoutMs);
+    const response = (await client.listPrompts({}, {timeout: timeoutMs} as any)) as any;
+    return {
+      prompts: response.prompts || [],
+    };
+  }
+
+  async getPrompt(name: string, args?: Record<string, any>, timeoutMs = 15000): Promise<MCPPromptResponse> {
+    const client = await this.getOrCreateClient(this.serverConfig, timeoutMs);
+    const response = (await client.getPrompt({name, arguments: args}, {timeout: timeoutMs} as any)) as any;
+    return {
+      messages: response.messages || [],
+    };
+  }
+
+  // ============================================================================
+  // PRIVATE HELPERS
+  // ============================================================================
+
+  private async createClient(server: McpHttpServerConfig, timeoutMs: number): Promise<Client> {
+    const client = new Client({name: "mcp-orbit-client", version: "1.0.0"});
+
+    // Wire up event handlers from SDK Client to our wrapper
+    client.onerror = (error) => {
+      this.onerror?.(error);
+    };
+
+    client.onclose = () => {
+      this.onclose?.();
+    };
+
+    const baseUrl = new URL(server.url);
+
+    // Create Streamable HTTP transport with optional authentication
+    const transport = new StreamableHTTPClientTransport(baseUrl, {
+      // Add custom headers (e.g., Authorization) to all requests
+      requestInit: server.headers
+        ? {
+            headers: server.headers,
+          }
+        : undefined,
+    });
+
+    await client.connect(transport, {timeout: timeoutMs} as any);
+    return client;
+  }
+
+  private async getOrCreateClient(server: McpHttpServerConfig, timeoutMs: number): Promise<Client> {
+    const key = this.getServerKey(server);
+
+    const existing = this.clientCache.get(key);
+    if (existing) {
+      return existing;
+    }
+
+    const pending = this.connectionPromises.get(key);
+    if (pending !== undefined) {
+      return pending;
+    }
+
+    const connectPromise = this.createClient(server, timeoutMs)
+      .then((client) => {
+        this.connectionPromises.delete(key);
+        this.clientCache.set(key, client);
+        return client;
+      })
+      .catch((error) => {
+        this.connectionPromises.delete(key);
+        throw error;
+      });
+
+    this.connectionPromises.set(key, connectPromise);
+    return connectPromise;
+  }
+
+  private getServerKey(config: McpHttpServerConfig): string {
+    return `streamable-http:${config.url}`;
+  }
+
+  async close(): Promise<void> {
+    const closePromises = Array.from(this.clientCache.values()).map((client) => client.close().catch(() => undefined));
+    this.clientCache.clear();
+    this.connectionPromises.clear();
+    await Promise.all(closePromises);
+  }
+}

package/src/clients/mcp-stdio.ts

@@ -0,0 +1,209 @@
+/**
+ * Stdio MCP Client
+ *
+ * Client for connecting to MCP servers via stdio (local child process)
+ * Features:
+ * - Client caching & connection pooling
+ * - Type-safe tool execution
+ * - Resource & Prompt management
+ */
+
+import {Client} from "@modelcontextprotocol/sdk/client/index.js";
+import {StdioClientTransport} from "@modelcontextprotocol/sdk/client/stdio.js";
+import type {
+  McpStdioServerConfig,
+  MCPToolSchema,
+  MCPToolResponse,
+  MCPResourceList,
+  MCPResourceContent,
+  MCPPromptList,
+  MCPPromptResponse,
+  IMcpClient,
+} from "./types.js";
+
+export class StdioMCPClient implements IMcpClient {
+  private clientCache = new Map<string, Client>();
+  private connectionPromises = new Map<string, Promise<Client>>();
+  private readonly serverConfig: McpStdioServerConfig;
+
+  // Event handlers (exposed from underlying MCP SDK Client)
+  public onerror?: (error: Error) => void;
+  public onclose?: () => void;
+
+  constructor(serverConfig: McpStdioServerConfig) {
+    this.serverConfig = serverConfig;
+  }
+
+  // ============================================================================
+  // TOOLS
+  // ============================================================================
+
+  async listTools(timeoutMs = 15000): Promise<{tools: MCPToolSchema[]}> {
+    const client = await this.getOrCreateClient(this.serverConfig, timeoutMs);
+    const resp = (await client.listTools({}, {timeout: timeoutMs} as any)) as any;
+
+    const tools: MCPToolSchema[] = Array.isArray(resp?.tools)
+      ? resp.tools.map((tool: any) => ({
+          name: tool.name,
+          description: tool.description,
+          input_schema: tool.input_schema ?? tool.inputSchema ?? {type: "object", properties: {}},
+          tags: tool.tags ?? tool._meta?.tags,
+        }))
+      : [];
+
+    return {tools};
+  }
+
+  async callTool(toolName: string, args: Record<string, any>, timeoutMs = 15000): Promise<MCPToolResponse> {
+    const client = await this.getOrCreateClient(this.serverConfig, timeoutMs);
+
+    const response = (await client.callTool(
+      {
+        name: toolName,
+        arguments: args,
+      },
+      undefined,
+      {timeout: timeoutMs} as any,
+    )) as any;
+
+    return {
+      content: Array.isArray(response?.content) ? response.content : [],
+      isError: response?.isError ?? false,
+      structuredContent: response?.structuredContent,
+      _meta: response?._meta,
+    };
+  }
+
+  // ============================================================================
+  // RESOURCES
+  // ============================================================================
+
+  async listResources(timeoutMs = 15000): Promise<MCPResourceList> {
+    const client = await this.getOrCreateClient(this.serverConfig, timeoutMs);
+    const response = (await client.listResources({}, {timeout: timeoutMs} as any)) as any;
+    return {
+      resources: response.resources || [],
+    };
+  }
+
+  async readResource(uri: string, timeoutMs = 15000): Promise<MCPResourceContent> {
+    const client = await this.getOrCreateClient(this.serverConfig, timeoutMs);
+    const response = (await client.readResource({uri}, {timeout: timeoutMs} as any)) as any;
+    return {
+      contents: response.contents || [],
+    };
+  }
+
+  // ============================================================================
+  // PROMPTS
+  // ============================================================================
+
+  async listPrompts(timeoutMs = 15000): Promise<MCPPromptList> {
+    const client = await this.getOrCreateClient(this.serverConfig, timeoutMs);
+    const response = (await client.listPrompts({}, {timeout: timeoutMs} as any)) as any;
+    return {
+      prompts: response.prompts || [],
+    };
+  }
+
+  async getPrompt(name: string, args?: Record<string, any>, timeoutMs = 15000): Promise<MCPPromptResponse> {
+    const client = await this.getOrCreateClient(this.serverConfig, timeoutMs);
+    const response = (await client.getPrompt({name, arguments: args}, {timeout: timeoutMs} as any)) as any;
+    return {
+      messages: response.messages || [],
+    };
+  }
+
+  // ============================================================================
+  // PRIVATE HELPERS
+  // ============================================================================
+
+  /**
+   * Resolve environment variable placeholders like ${VAR_NAME}
+   * @param value - String that may contain placeholders
+   * @param env - Current environment variables to resolve from
+   * @returns Resolved string with placeholders replaced
+   */
+  private resolveEnvPlaceholders(value: string, env: Record<string, string>): string {
+    return value.replace(/\$\{([^}]+)\}/g, (match, varName) => {
+      return env[varName] || match; // Replace with env value or keep placeholder if not found
+    });
+  }
+
+  private async createClient(server: McpStdioServerConfig, timeoutMs: number): Promise<Client> {
+    const client = new Client({name: "mcp-orbit-client", version: "1.0.0"});
+
+    // Wire up event handlers from SDK Client to our wrapper
+    client.onerror = (error) => {
+      this.onerror?.(error);
+    };
+
+    client.onclose = () => {
+      this.onclose?.();
+    };
+
+    // Build env: start with current process.env, then overlay server.env
+    const env: Record<string, string> = {};
+    for (const [key, value] of Object.entries(process.env)) {
+      if (value !== undefined) {
+        env[key] = value;
+      }
+    }
+
+    // Resolve placeholders in server.env values
+    if (server.env) {
+      for (const [key, value] of Object.entries(server.env)) {
+        env[key] = this.resolveEnvPlaceholders(value, env);
+      }
+    }
+
+    const transport = new StdioClientTransport({
+      command: server.command,
+      args: server.args,
+      env,
+      cwd: server.cwd,
+      stderr: "pipe", // Use "pipe" instead of "inherit" for proper error event handling
+    });
+    await client.connect(transport, {timeout: timeoutMs} as any);
+    return client;
+  }
+
+  private async getOrCreateClient(server: McpStdioServerConfig, timeoutMs: number): Promise<Client> {
+    const key = this.getServerKey(server);
+
+    const existing = this.clientCache.get(key);
+    if (existing) {
+      return existing;
+    }
+
+    const pending = this.connectionPromises.get(key);
+    if (pending !== undefined) {
+      return pending;
+    }
+
+    const connectPromise = this.createClient(server, timeoutMs)
+      .then((client) => {
+        this.connectionPromises.delete(key);
+        this.clientCache.set(key, client);
+        return client;
+      })
+      .catch((error) => {
+        this.connectionPromises.delete(key);
+        throw error;
+      });
+
+    this.connectionPromises.set(key, connectPromise);
+    return connectPromise;
+  }
+
+  private getServerKey(config: McpStdioServerConfig): string {
+    return `stdio:${config.command}:${config.args?.join(",")}`;
+  }
+
+  async close(): Promise<void> {
+    const closePromises = Array.from(this.clientCache.values()).map((client) => client.close().catch(() => undefined));
+    this.clientCache.clear();
+    this.connectionPromises.clear();
+    await Promise.all(closePromises);
+  }
+}