mcp-orbit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 okahari
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,247 @@
+# mcp-orbit
+
+A lightweight framework for building and connecting [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) servers and clients in Node.js.
+
+Build MCP-compliant tool servers with stdio or HTTP transport, define tools with Zod schemas, and connect to any MCP server from your application.
+
+## Features
+
+- **Server Framework** — Register tools, resources, and prompts with a simple API
+- **Dual Transport** — Stdio (for local/CLI use) and HTTP (for remote servers)
+- **Client Libraries** — Connect to any MCP server (stdio or HTTP) from your app
+- **Zod Integration** — Define tool input schemas with Zod, auto-converted to JSON Schema
+- **Resource System** — RFC 6570 URI templates for dynamic resources
+- **Prompt Registry** — Templated prompts with argument validation
+- **CLI Helpers** — `--stdio` / `--http` argument parsing out of the box
+
+## Install
+
+```bash
+npm install mcp-orbit
+```
+
+## Quick Start
+
+### Build a Tool Server
+
+```typescript
+import { registerTool, startServer, parseArgs, applyPreInit } from "mcp-orbit";
+import { z } from "zod";
+
+// Define a tool with Zod schema
+registerTool({
+  name: "greet",
+  description: "Greet someone by name",
+  inputSchema: z.object({
+    name: z.string().describe("Name of the person to greet"),
+  }),
+  execute: async ({ name }) => ({
+    content: [{ type: "text", text: `Hello, ${name}!` }],
+  }),
+});
+
+// Start the server (auto-detects --stdio or --http from CLI args)
+const config = parseArgs();
+applyPreInit(config);
+const server = startServer(config);
+```
+
+Run it:
+
+```bash
+# Stdio mode (for Claude Desktop, local integrations)
+node dist/index.js --stdio
+
+# HTTP mode (for remote access)
+node dist/index.js --http --http-port=8080
+```
+
+### Connect to an MCP Server
+
+```typescript
+import { StdioMCPClient, HttpMCPClient } from "mcp-orbit";
+
+// Connect to a local stdio server
+const local = new StdioMCPClient({
+  name: "my-plugin",
+  command: "node",
+  args: ["./plugins/my-plugin/dist/index.js", "--stdio"],
+});
+const tools = await local.listTools();
+const result = await local.callTool("greet", { name: "World" });
+
+// Connect to a remote HTTP server
+const remote = new HttpMCPClient({
+  name: "remote-api",
+  url: "https://api.example.com/mcp/",
+  headers: { Authorization: "Bearer sk-..." },
+});
+const remoteTools = await remote.listTools();
+```
+
+## API Reference
+
+### Server
+
+| Export | Description |
+|--------|-------------|
+| `registerTool(tool)` | Register a tool with name, schema, and execute function |
+| `startServer(config)` | Start the MCP server with the given transport config |
+| `createMCPServer()` | Create the underlying MCP SDK Server instance |
+| `executeTool(name, args)` | Execute a registered tool by name |
+| `getTool(name)` | Get a registered tool definition |
+| `getToolCount()` | Number of registered tools |
+| `getToolDefinitions()` | All tool schemas for MCP ListTools |
+| `startHttpServer(port, host, server)` | Start HTTP transport directly |
+| `startStdioServer(server)` | Start stdio transport directly |
+
+### Clients
+
+Both `StdioMCPClient` and `HttpMCPClient` implement the `IMcpClient` interface:
+
+```typescript
+interface IMcpClient {
+  listTools(timeoutMs?: number): Promise<{ tools: MCPToolSchema[] }>;
+  callTool(name: string, args: Record<string, any>, timeoutMs?: number): Promise<MCPToolResponse>;
+  listResources(timeoutMs?: number): Promise<MCPResourceList>;
+  readResource(uri: string, timeoutMs?: number): Promise<MCPResourceContent>;
+  listPrompts(timeoutMs?: number): Promise<MCPPromptList>;
+  getPrompt(name: string, args?: Record<string, any>, timeoutMs?: number): Promise<MCPPromptResponse>;
+  close(): Promise<void>;
+}
+```
+
+#### StdioMCPClient
+
+Spawns a local child process and communicates via stdin/stdout.
+
+```typescript
+const client = new StdioMCPClient({
+  name: "my-server",
+  command: "node",
+  args: ["./server.js", "--stdio"],
+  env: {
+    API_KEY: "${MY_API_KEY}",  // Resolved from process.env
+  },
+  cwd: "./plugins",
+});
+```
+
+Environment variables with `${VAR_NAME}` syntax are automatically resolved from `process.env`.
+
+#### HttpMCPClient
+
+Connects to a remote MCP server over HTTP (Streamable HTTP transport, Protocol 2025-03-26).
+
+```typescript
+const client = new HttpMCPClient({
+  name: "remote",
+  url: "https://api.example.com/mcp/",
+  headers: { Authorization: "Bearer sk-..." },
+  timeout_ms: 15000,
+});
+```
+
+### Resources
+
+Register resources with static URIs or RFC 6570 templates:
+
+```typescript
+import { createAndRegisterResource } from "mcp-orbit";
+
+createAndRegisterResource({
+  uri: "config://app/settings",
+  name: "App Settings",
+  description: "Current application configuration",
+  mimeType: "application/json",
+  read: async () => JSON.stringify({ theme: "dark" }),
+});
+```
+
+### Prompts
+
+Register prompt templates with optional argument validation:
+
+```typescript
+import { createAndRegisterPrompt } from "mcp-orbit";
+import { z } from "zod";
+
+createAndRegisterPrompt({
+  name: "analyze-data",
+  description: "Analyze a dataset",
+  arguments: [
+    { name: "dataset", description: "Dataset name", required: true },
+    { name: "format", description: "Output format", required: false },
+  ],
+  inputSchema: z.object({
+    dataset: z.string(),
+    format: z.enum(["json", "csv"]).default("json"),
+  }),
+  render: async ({ dataset, format }) => ({
+    messages: [
+      { role: "user", content: { type: "text", text: `Analyze ${dataset} as ${format}` } },
+    ],
+  }),
+});
+```
+
+### Utilities
+
+| Export | Description |
+|--------|-------------|
+| `createLogger(scope)` | Scoped, colored console logger |
+| `zodToMcpJsonSchema(schema)` | Convert Zod schema to MCP JSON Schema |
+| `HTTPClient` | Lightweight HTTP client for tool implementations |
+| `parseArgs()` | Parse `--stdio` / `--http` CLI arguments |
+| `applyPreInit(config)` | Configure stderr logging for stdio mode |
+
+## Building Plugins
+
+Create an MCP plugin as a standalone npm package:
+
+```typescript
+// my-plugin/src/index.ts
+import { registerTool, startServer, parseArgs, applyPreInit } from "mcp-orbit";
+import { z } from "zod";
+
+// Register your tools
+registerTool({
+  name: "my_tool",
+  description: "Does something useful",
+  inputSchema: z.object({
+    input: z.string(),
+  }),
+  execute: async ({ input }) => ({
+    content: [{ type: "text", text: `Processed: ${input}` }],
+  }),
+});
+
+// Start server
+const config = parseArgs();
+applyPreInit(config);
+startServer(config);
+```
+
+Then use it as a stdio plugin from any MCP client:
+
+```bash
+node ./node_modules/my-plugin/dist/index.js --stdio
+```
+
+## Transport Modes
+
+| Mode | Flag | Use Case |
+|------|------|----------|
+| Stdio | `--stdio` | Local integrations, Claude Desktop, CLI tools |
+| HTTP | `--http` | Remote servers, multi-client access |
+
+HTTP mode supports session management, bearer token auth, health checks (`/health`), and graceful shutdown.
+
+## Requirements
+
+- Node.js >= 20.0.0
+- TypeScript (recommended)
+
+## License
+
+MIT

package/dist/__tests__/helpers/test-server.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=test-server.d.ts.map

package/dist/__tests__/helpers/test-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-server.d.ts","sourceRoot":"","sources":["../../../src/__tests__/helpers/test-server.ts"],"names":[],"mappings":""}

package/dist/__tests__/helpers/test-server.js

@@ -0,0 +1,27 @@
+/**
+ * Minimal test server for stdio roundtrip tests.
+ * Registers one echo tool and starts in stdio mode.
+ */
+import { z } from "zod";
+import { registerTool, startServer } from "../../core/server.js";
+import { zodToMcpJsonSchema } from "../../utils/zod-to-mcp-schema.js";
+const inputSchema = z.object({
+    message: z.string().describe("Message to echo back"),
+});
+const tool = {
+    definition: {
+        name: "roundtrip_echo",
+        description: "Echo for roundtrip test",
+        inputSchema: zodToMcpJsonSchema(inputSchema),
+    },
+    runtimeInputSchema: inputSchema,
+    async execute(args) {
+        const { message } = inputSchema.parse(args);
+        return {
+            content: [{ type: "text", text: `echo: ${message}` }],
+        };
+    },
+};
+registerTool(tool);
+startServer({ mode: "stdio", serverName: "test-roundtrip-server", serverVersion: "0.0.1" });
+//# sourceMappingURL=test-server.js.map

package/dist/__tests__/helpers/test-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-server.js","sourceRoot":"","sources":["../../../src/__tests__/helpers/test-server.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AACtB,OAAO,EAAC,YAAY,EAAE,WAAW,EAAC,MAAM,sBAAsB,CAAC;AAC/D,OAAO,EAAC,kBAAkB,EAAC,MAAM,kCAAkC,CAAC;AAGpE,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,sBAAsB,CAAC;CACrD,CAAC,CAAC;AAEH,MAAM,IAAI,GAAS;IACjB,UAAU,EAAE;QACV,IAAI,EAAE,gBAAgB;QACtB,WAAW,EAAE,yBAAyB;QACtC,WAAW,EAAE,kBAAkB,CAAC,WAAW,CAAe;KAC3D;IACD,kBAAkB,EAAE,WAAW;IAC/B,KAAK,CAAC,OAAO,CAAC,IAAa;QACzB,MAAM,EAAC,OAAO,EAAC,GAAG,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC1C,OAAO;YACL,OAAO,EAAE,CAAC,EAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,OAAO,EAAE,EAAC,CAAC;SACpD,CAAC;IACJ,CAAC;CACF,CAAC;AAEF,YAAY,CAAC,IAAI,CAAC,CAAC;AAEnB,WAAW,CAAC,EAAC,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,uBAAuB,EAAE,aAAa,EAAE,OAAO,EAAC,CAAC,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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 } 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 declare function parseArgs(): ServerConfig;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAC,YAAY,EAAgB,MAAM,kBAAkB,CAAC;AAElE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,IAAI,YAAY,CAiCxC"}

package/dist/cli.js

@@ -0,0 +1,56 @@
+/**
+ * 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.
+ */
+/**
+ * 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() {
+    const args = process.argv.slice(2);
+    let mode = process.env.PORT ? "http" : "stdio";
+    let httpPort = process.env.PORT ? parseInt(process.env.PORT, 10) : undefined;
+    let httpHost = 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 };
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,SAAS;IACvB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAEnC,IAAI,IAAI,GAAkB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;IAC9D,IAAI,QAAQ,GAAuB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACjG,IAAI,QAAQ,GAAuB,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,SAAS,CAAC;IAE1E,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACpB,IAAI,GAAG,KAAK,QAAQ,EAAE,CAAC;YACrB,IAAI,GAAG,MAAM,CAAC;QAChB,CAAC;aAAM,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YAC7B,IAAI,GAAG,OAAO,CAAC;QACjB,CAAC;aAAM,IAAI,GAAG,CAAC,UAAU,CAAC,cAAc,CAAC,EAAE,CAAC;YAC1C,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;YACjD,IAAI,GAAG,MAAM,CAAC;QAChB,CAAC;aAAM,IAAI,GAAG,KAAK,aAAa,EAAE,CAAC;YACjC,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;YACzC,IAAI,GAAG,MAAM,CAAC;QAChB,CAAC;aAAM,IAAI,GAAG,CAAC,UAAU,CAAC,cAAc,CAAC,EAAE,CAAC;YAC1C,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YAC7B,IAAI,GAAG,MAAM,CAAC;QAChB,CAAC;aAAM,IAAI,GAAG,KAAK,aAAa,EAAE,CAAC;YACjC,QAAQ,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;YACrB,IAAI,GAAG,MAAM,CAAC;QAChB,CAAC;IACH,CAAC;IAED,IAAI,IAAI,KAAK,MAAM,IAAI,CAAC,CAAC,QAAQ,IAAI,KAAK,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC;QACtD,QAAQ,GAAG,IAAI,CAAC;IAClB,CAAC;IAED,OAAO,EAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAC,CAAC;AACpC,CAAC"}

package/dist/clients/mcp-http.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 type { McpHttpServerConfig, MCPToolSchema, MCPToolResponse, MCPResourceList, MCPResourceContent, MCPPromptList, MCPPromptResponse, IMcpClient } from "./types.js";
+export declare class HttpMCPClient implements IMcpClient {
+    private clientCache;
+    private connectionPromises;
+    private readonly serverConfig;
+    onerror?: (error: Error) => void;
+    onclose?: () => void;
+    constructor(serverConfig: McpHttpServerConfig);
+    listTools(timeoutMs?: number): Promise<{
+        tools: MCPToolSchema[];
+    }>;
+    callTool(toolName: string, args: Record<string, any>, timeoutMs?: number): Promise<MCPToolResponse>;
+    listResources(timeoutMs?: number): Promise<MCPResourceList>;
+    readResource(uri: string, timeoutMs?: number): Promise<MCPResourceContent>;
+    listPrompts(timeoutMs?: number): Promise<MCPPromptList>;
+    getPrompt(name: string, args?: Record<string, any>, timeoutMs?: number): Promise<MCPPromptResponse>;
+    private createClient;
+    private getOrCreateClient;
+    private getServerKey;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=mcp-http.d.ts.map

package/dist/clients/mcp-http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-http.d.ts","sourceRoot":"","sources":["../../src/clients/mcp-http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EACV,mBAAmB,EACnB,aAAa,EACb,eAAe,EACf,eAAe,EACf,kBAAkB,EAClB,aAAa,EACb,iBAAiB,EACjB,UAAU,EACX,MAAM,YAAY,CAAC;AAEpB,qBAAa,aAAc,YAAW,UAAU;IAC9C,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,kBAAkB,CAAsC;IAChE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAsB;IAG5C,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACjC,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;gBAEhB,YAAY,EAAE,mBAAmB;IAQvC,SAAS,CAAC,SAAS,SAAQ,GAAG,OAAO,CAAC;QAAC,KAAK,EAAE,aAAa,EAAE,CAAA;KAAC,CAAC;IAgB/D,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,SAAS,SAAQ,GAAG,OAAO,CAAC,eAAe,CAAC;IAwBlG,aAAa,CAAC,SAAS,SAAQ,GAAG,OAAO,CAAC,eAAe,CAAC;IAQ1D,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,SAAQ,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAYzE,WAAW,CAAC,SAAS,SAAQ,GAAG,OAAO,CAAC,aAAa,CAAC;IAQtD,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,SAAS,SAAQ,GAAG,OAAO,CAAC,iBAAiB,CAAC;YAY1F,YAAY;YA4BZ,iBAAiB;IA4B/B,OAAO,CAAC,YAAY;IAId,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAM7B"}

package/dist/clients/mcp-http.js

@@ -0,0 +1,148 @@
+/**
+ * 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";
+export class HttpMCPClient {
+    clientCache = new Map();
+    connectionPromises = new Map();
+    serverConfig;
+    // Event handlers (exposed from underlying MCP SDK Client)
+    onerror;
+    onclose;
+    constructor(serverConfig) {
+        this.serverConfig = serverConfig;
+    }
+    // ============================================================================
+    // TOOLS
+    // ============================================================================
+    async listTools(timeoutMs = 15000) {
+        const client = await this.getOrCreateClient(this.serverConfig, timeoutMs);
+        const resp = (await client.listTools({}, { timeout: timeoutMs }));
+        const tools = Array.isArray(resp?.tools)
+            ? resp.tools.map((tool) => ({
+                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, args, timeoutMs = 15000) {
+        const client = await this.getOrCreateClient(this.serverConfig, timeoutMs);
+        const response = (await client.callTool({
+            name: toolName,
+            arguments: args,
+        }, undefined, { timeout: timeoutMs }));
+        return {
+            content: Array.isArray(response?.content) ? response.content : [],
+            isError: response?.isError ?? false,
+            structuredContent: response?.structuredContent,
+            _meta: response?._meta,
+        };
+    }
+    // ============================================================================
+    // RESOURCES
+    // ============================================================================
+    async listResources(timeoutMs = 15000) {
+        const client = await this.getOrCreateClient(this.serverConfig, timeoutMs);
+        const response = (await client.listResources({}, { timeout: timeoutMs }));
+        return {
+            resources: response.resources || [],
+        };
+    }
+    async readResource(uri, timeoutMs = 15000) {
+        const client = await this.getOrCreateClient(this.serverConfig, timeoutMs);
+        const response = (await client.readResource({ uri }, { timeout: timeoutMs }));
+        return {
+            contents: response.contents || [],
+        };
+    }
+    // ============================================================================
+    // PROMPTS
+    // ============================================================================
+    async listPrompts(timeoutMs = 15000) {
+        const client = await this.getOrCreateClient(this.serverConfig, timeoutMs);
+        const response = (await client.listPrompts({}, { timeout: timeoutMs }));
+        return {
+            prompts: response.prompts || [],
+        };
+    }
+    async getPrompt(name, args, timeoutMs = 15000) {
+        const client = await this.getOrCreateClient(this.serverConfig, timeoutMs);
+        const response = (await client.getPrompt({ name, arguments: args }, { timeout: timeoutMs }));
+        return {
+            messages: response.messages || [],
+        };
+    }
+    // ============================================================================
+    // PRIVATE HELPERS
+    // ============================================================================
+    async createClient(server, timeoutMs) {
+        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 });
+        return client;
+    }
+    async getOrCreateClient(server, timeoutMs) {
+        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;
+    }
+    getServerKey(config) {
+        return `streamable-http:${config.url}`;
+    }
+    async close() {
+        const closePromises = Array.from(this.clientCache.values()).map((client) => client.close().catch(() => undefined));
+        this.clientCache.clear();
+        this.connectionPromises.clear();
+        await Promise.all(closePromises);
+    }
+}
+//# sourceMappingURL=mcp-http.js.map

package/dist/clients/mcp-http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-http.js","sourceRoot":"","sources":["../../src/clients/mcp-http.ts"],"names":[],"mappings":"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"}

package/dist/clients/mcp-stdio.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 type { McpStdioServerConfig, MCPToolSchema, MCPToolResponse, MCPResourceList, MCPResourceContent, MCPPromptList, MCPPromptResponse, IMcpClient } from "./types.js";
+export declare class StdioMCPClient implements IMcpClient {
+    private clientCache;
+    private connectionPromises;
+    private readonly serverConfig;
+    onerror?: (error: Error) => void;
+    onclose?: () => void;
+    constructor(serverConfig: McpStdioServerConfig);
+    listTools(timeoutMs?: number): Promise<{
+        tools: MCPToolSchema[];
+    }>;
+    callTool(toolName: string, args: Record<string, any>, timeoutMs?: number): Promise<MCPToolResponse>;
+    listResources(timeoutMs?: number): Promise<MCPResourceList>;
+    readResource(uri: string, timeoutMs?: number): Promise<MCPResourceContent>;
+    listPrompts(timeoutMs?: number): Promise<MCPPromptList>;
+    getPrompt(name: string, args?: Record<string, any>, timeoutMs?: number): Promise<MCPPromptResponse>;
+    /**
+     * 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;
+    private createClient;
+    private getOrCreateClient;
+    private getServerKey;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=mcp-stdio.d.ts.map

package/dist/clients/mcp-stdio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-stdio.d.ts","sourceRoot":"","sources":["../../src/clients/mcp-stdio.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EACV,oBAAoB,EACpB,aAAa,EACb,eAAe,EACf,eAAe,EACf,kBAAkB,EAClB,aAAa,EACb,iBAAiB,EACjB,UAAU,EACX,MAAM,YAAY,CAAC;AAEpB,qBAAa,cAAe,YAAW,UAAU;IAC/C,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,kBAAkB,CAAsC;IAChE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAuB;IAG7C,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACjC,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;gBAEhB,YAAY,EAAE,oBAAoB;IAQxC,SAAS,CAAC,SAAS,SAAQ,GAAG,OAAO,CAAC;QAAC,KAAK,EAAE,aAAa,EAAE,CAAA;KAAC,CAAC;IAgB/D,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,SAAS,SAAQ,GAAG,OAAO,CAAC,eAAe,CAAC;IAwBlG,aAAa,CAAC,SAAS,SAAQ,GAAG,OAAO,CAAC,eAAe,CAAC;IAQ1D,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,SAAQ,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAYzE,WAAW,CAAC,SAAS,SAAQ,GAAG,OAAO,CAAC,aAAa,CAAC;IAQtD,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,SAAS,SAAQ,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAYxG;;;;;OAKG;IACH,OAAO,CAAC,sBAAsB;YAMhB,YAAY;YAsCZ,iBAAiB;IA4B/B,OAAO,CAAC,YAAY;IAId,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAM7B"}