@evantahler/mcpx 0.17.1 → 0.18.0

package/.claude/skills/mcpx.md

@@ -231,6 +231,22 @@ mcpx deauth <server>           # remove stored auth
 | `--project` | Install to project location (default)      |
 | `-f, --force` | Overwrite if file already exists         |
 
+## Programmatic Usage (TypeScript SDK)
+
+For agents that don't have shell access (remote, persistent, or isolated agents), mcpx can be used as a TypeScript library:
+
+```typescript
+import { McpxClient } from "@evantahler/mcpx";
+
+const client = new McpxClient();
+const results = await client.search("send a message");
+const tool = await client.info("arcade", "Slack_SendMessage");
+const result = await client.exec("arcade", "Slack_SendMessage", { channel: "#general", message: "hello" });
+await client.close();
+```
+
+The SDK follows the same search → inspect → exec workflow. Server management (add, remove, auth) is still done via the CLI.
+
 ## Environment variables
 
 | Variable          | Purpose                     | Default    |

package/.cursor/rules/mcpx.mdc

@@ -225,6 +225,22 @@ mcpx deauth <server>           # remove stored auth
 | `--project` | Install to project location (default)      |
 | `-f, --force` | Overwrite if file already exists         |
 
+## Programmatic Usage (TypeScript SDK)
+
+For agents that don't have shell access (remote, persistent, or isolated agents), mcpx can be used as a TypeScript library:
+
+```typescript
+import { McpxClient } from "@evantahler/mcpx";
+
+const client = new McpxClient();
+const results = await client.search("send a message");
+const tool = await client.info("arcade", "Slack_SendMessage");
+const result = await client.exec("arcade", "Slack_SendMessage", { channel: "#general", message: "hello" });
+await client.close();
+```
+
+The SDK follows the same search → inspect → exec workflow. Server management (add, remove, auth) is still done via the CLI.
+
 ## Environment variables
 
 | Variable          | Purpose                     | Default    |

package/README.md

@@ -4,10 +4,11 @@ A command-line interface for MCP servers. **curl for MCP.**
 
 The internet is debating CLI vs MCP like they're competitors. [They're not.](https://arcade.dev/blog/curl-for-mcp)
 
-Two audiences:
+Three audiences:
 
-1. **AI/LLM agents** that prefer shelling out over maintaining persistent MCP connections — better for token management, progressive tool discovery, and sharing a single pool of MCP servers across multiple agents on one machine
-2. **MCP developers** who need a fast way to discover, debug, and test their servers from the terminal
+1. **Coding agents** (Claude Code, Cursor) that prefer shelling out over maintaining persistent MCP connections — better for token management, progressive tool discovery, and sharing a single pool of MCP servers across multiple agents on one machine
+2. **Non-coding agents** that need programmatic access to MCP tools from TypeScript — remote, persistent, or isolated agents that don't have a shell
+3. **MCP developers** who need a fast way to discover, debug, and test their servers from the terminal
 
 ## Install
 
@@ -635,6 +636,51 @@ To execute tools:
 Always search before executing — don't assume tool names.
 ```
 
+### Programmatic Usage (TypeScript SDK)
+
+For agents that don't have shell access — remote, persistent, or isolated agents running in TypeScript:
+
+```typescript
+import { McpxClient } from "@evantahler/mcpx";
+
+const client = new McpxClient();
+// or: new McpxClient({ configDir: "/path/to/.mcpx" })
+// or: new McpxClient({ servers: { mcpServers: { ... } } })
+
+// 1. Search for tools
+const results = await client.search("send a message");
+
+// 2. Inspect the tool schema
+const tool = await client.info("arcade", "Slack_SendMessage");
+
+// 3. Execute the tool
+const result = await client.exec("arcade", "Slack_SendMessage", {
+  channel: "#general",
+  message: "hello",
+});
+
+// Also available: listTools, listResources, readResource,
+// listPrompts, getPrompt, listTasks, getTask, cancelTask,
+// getServerInfo, getServerNames, validateToolInput
+
+await client.close();
+```
+
+The SDK uses the same config files as the CLI (`~/.mcpx/servers.json`, `auth.json`, `search.json`). Server management (add, remove, auth) is done via the CLI — the SDK is read-only.
+
+You can also pass server config directly, bypassing file loading entirely:
+
+```typescript
+const client = new McpxClient({
+  servers: {
+    mcpServers: {
+      local: { command: "node", args: ["server.js"] },
+      remote: { url: "https://mcp.example.com" },
+    },
+  },
+});
+```
+
 ## Permissions (Claude Code & Cursor)
 
 AI agents like Claude Code and Cursor prompt users to approve each `mcpx exec` call. `mcpx allow` and `mcpx deny` manage fine-grained permission rules so agents can self-authorize specific tools without broad access.

package/package.json

@@ -1,8 +1,14 @@
 {
   "name": "@evantahler/mcpx",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "A command-line interface for MCP servers. curl for MCP.",
   "type": "module",
+  "exports": {
+    ".": "./src/sdk.ts",
+    "./cli": "./src/cli.ts"
+  },
+  "main": "./src/sdk.ts",
+  "types": "./src/sdk.ts",
   "bin": {
     "mcpx": "./src/cli.ts"
   },

package/src/sdk.ts

@@ -0,0 +1,310 @@
+import type {
+  CallToolResult,
+  GetTaskResult,
+  ListTasksResult,
+  CancelTaskResult,
+} from "@modelcontextprotocol/sdk/types.js";
+import { ServerManager } from "./client/manager.ts";
+import type {
+  ServerManagerOptions,
+  ToolWithServer,
+  ResourceWithServer,
+  PromptWithServer,
+  ServerInfo,
+  ServerError,
+} from "./client/manager.ts";
+import { loadConfig } from "./config/loader.ts";
+import type {
+  Tool,
+  Resource,
+  Prompt,
+  ServerConfig,
+  StdioServerConfig,
+  HttpServerConfig,
+  ServersFile,
+  AuthFile,
+  AuthEntry,
+  SearchIndex,
+  Config,
+} from "./config/schemas.ts";
+import { search } from "./search/index.ts";
+import type { SearchResult, SearchOptions } from "./search/index.ts";
+import { validateToolInput } from "./validation/schema.ts";
+import type { ValidationResult, ValidationError } from "./validation/schema.ts";
+
+// Re-export types for SDK consumers
+export type {
+  // MCP SDK types
+  CallToolResult,
+  GetTaskResult,
+  ListTasksResult,
+  CancelTaskResult,
+  // Config types
+  Tool,
+  Resource,
+  Prompt,
+  ServerConfig,
+  StdioServerConfig,
+  HttpServerConfig,
+  ServersFile,
+  AuthFile,
+  AuthEntry,
+  SearchIndex,
+  Config,
+  // Manager types
+  ToolWithServer,
+  ResourceWithServer,
+  PromptWithServer,
+  ServerInfo,
+  ServerError,
+  // Search types
+  SearchResult,
+  SearchOptions,
+  // Validation types
+  ValidationResult,
+  ValidationError,
+};
+
+export interface McpxClientOptions {
+  /** Path to config directory. Defaults to ~/.mcpx or MCP_CONFIG_PATH env var. */
+  configDir?: string;
+  /** Inline server config — bypasses file loading when provided. */
+  servers?: ServersFile;
+  /** Inline auth config — bypasses file loading when provided. */
+  auth?: AuthFile;
+  /** Inline search index — bypasses file loading when provided. */
+  searchIndex?: SearchIndex;
+  /** Max concurrent server connections. Default: 5 */
+  concurrency?: number;
+  /** Request timeout in ms. Default: 1_800_000 (30 min) */
+  timeout?: number;
+  /** Max retries per operation. Default: 3 */
+  maxRetries?: number;
+  /** Enable verbose/trace logging. Default: false */
+  verbose?: boolean;
+}
+
+export class McpxClient {
+  private options: McpxClientOptions;
+  private manager: ServerManager | undefined;
+  private searchIndex: SearchIndex | undefined;
+  private connectPromise: Promise<void> | undefined;
+
+  constructor(options: McpxClientOptions = {}) {
+    this.options = options;
+  }
+
+  /** Ensure config is loaded and ServerManager is ready. Idempotent. */
+  private async ensureConnected(): Promise<ServerManager> {
+    if (this.manager) return this.manager;
+
+    if (!this.connectPromise) {
+      this.connectPromise = this.init();
+    }
+    await this.connectPromise;
+    return this.manager!;
+  }
+
+  private async init(): Promise<void> {
+    let servers: ServersFile;
+    let auth: AuthFile;
+    let configDir: string;
+    let searchIndex: SearchIndex;
+
+    if (this.options.servers) {
+      // Inline config — no file loading
+      servers = this.options.servers;
+      auth = this.options.auth ?? {};
+      configDir = this.options.configDir ?? "/tmp";
+      searchIndex = this.options.searchIndex ?? {
+        version: 1,
+        indexed_at: "",
+        embedding_model: "",
+        tools: [],
+      };
+    } else {
+      // Load from disk
+      const config = await loadConfig({ configFlag: this.options.configDir });
+      servers = config.servers;
+      auth = config.auth;
+      configDir = config.configDir;
+      searchIndex = config.searchIndex;
+    }
+
+    this.searchIndex = searchIndex;
+
+    const managerOpts: ServerManagerOptions = {
+      servers,
+      configDir,
+      auth,
+      concurrency: this.options.concurrency,
+      verbose: this.options.verbose,
+      timeout: this.options.timeout,
+      maxRetries: this.options.maxRetries,
+      logLevel: "emergency", // suppress server log messages from writing to stderr
+      noInteractive: true, // agents can't fill elicitation forms
+    };
+
+    this.manager = new ServerManager(managerOpts);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Core workflow: search → info → exec
+  // ---------------------------------------------------------------------------
+
+  /** Search for tools by keyword and/or semantic similarity. Requires a pre-built index (run `mcpx index` via CLI). */
+  async search(query: string, options?: SearchOptions): Promise<SearchResult[]> {
+    await this.ensureConnected();
+    if (!this.searchIndex || this.searchIndex.tools.length === 0) {
+      throw new Error("No search index found. Build one with: mcpx index");
+    }
+    return search(query, this.searchIndex, options);
+  }
+
+  /** Get a tool's schema (name, description, inputSchema). */
+  async info(server: string, tool: string): Promise<Tool | undefined> {
+    const manager = await this.ensureConnected();
+    return manager.getToolSchema(server, tool);
+  }
+
+  /** Execute a tool and return the result. */
+  async exec(
+    server: string,
+    tool: string,
+    args?: Record<string, unknown>,
+  ): Promise<CallToolResult> {
+    const manager = await this.ensureConnected();
+    return manager.callTool(server, tool, args ?? {}) as Promise<CallToolResult>;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Tools
+  // ---------------------------------------------------------------------------
+
+  /** List tools, optionally filtered to a single server. */
+  async listTools(server?: string): Promise<ToolWithServer[]> {
+    const manager = await this.ensureConnected();
+    if (server) {
+      const tools = await manager.listTools(server);
+      return tools.map((tool) => ({ server, tool }));
+    }
+    const { tools } = await manager.getAllTools();
+    return tools;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Validation
+  // ---------------------------------------------------------------------------
+
+  /** Validate arguments against a tool's inputSchema. */
+  async validateToolInput(
+    server: string,
+    toolName: string,
+    args: Record<string, unknown>,
+  ): Promise<ValidationResult> {
+    const tool = await this.info(server, toolName);
+    if (!tool) {
+      return { valid: false, errors: [{ path: "(root)", message: `Tool not found: ${toolName}` }] };
+    }
+    return validateToolInput(server, tool, args);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Resources
+  // ---------------------------------------------------------------------------
+
+  /** List resources, optionally filtered to a single server. */
+  async listResources(server?: string): Promise<ResourceWithServer[]> {
+    const manager = await this.ensureConnected();
+    if (server) {
+      const resources = await manager.listResources(server);
+      return resources.map((resource) => ({ server, resource }));
+    }
+    const { resources } = await manager.getAllResources();
+    return resources;
+  }
+
+  /** Read a specific resource by URI. */
+  async readResource(server: string, uri: string): Promise<unknown> {
+    const manager = await this.ensureConnected();
+    return manager.readResource(server, uri);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Prompts
+  // ---------------------------------------------------------------------------
+
+  /** List prompts, optionally filtered to a single server. */
+  async listPrompts(server?: string): Promise<PromptWithServer[]> {
+    const manager = await this.ensureConnected();
+    if (server) {
+      const prompts = await manager.listPrompts(server);
+      return prompts.map((prompt) => ({ server, prompt }));
+    }
+    const { prompts } = await manager.getAllPrompts();
+    return prompts;
+  }
+
+  /** Get a specific prompt by name, optionally with arguments. */
+  async getPrompt(server: string, name: string, args?: Record<string, string>): Promise<unknown> {
+    const manager = await this.ensureConnected();
+    return manager.getPrompt(server, name, args);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Tasks
+  // ---------------------------------------------------------------------------
+
+  /** List tasks on a server. */
+  async listTasks(server: string, cursor?: string): Promise<ListTasksResult> {
+    const manager = await this.ensureConnected();
+    return manager.listTasks(server, cursor);
+  }
+
+  /** Get the status of a task. */
+  async getTask(server: string, taskId: string): Promise<GetTaskResult> {
+    const manager = await this.ensureConnected();
+    return manager.getTask(server, taskId);
+  }
+
+  /** Retrieve the result of a completed task. */
+  async getTaskResult(server: string, taskId: string): Promise<CallToolResult> {
+    const manager = await this.ensureConnected();
+    return manager.getTaskResult(server, taskId);
+  }
+
+  /** Cancel a running task. */
+  async cancelTask(server: string, taskId: string): Promise<CancelTaskResult> {
+    const manager = await this.ensureConnected();
+    return manager.cancelTask(server, taskId);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Server info
+  // ---------------------------------------------------------------------------
+
+  /** Get server info (version, capabilities, instructions). */
+  async getServerInfo(server: string): Promise<ServerInfo> {
+    const manager = await this.ensureConnected();
+    return manager.getServerInfo(server);
+  }
+
+  /** Get all configured server names. */
+  async getServerNames(): Promise<string[]> {
+    const manager = await this.ensureConnected();
+    return manager.getServerNames();
+  }
+
+  // ---------------------------------------------------------------------------
+  // Lifecycle
+  // ---------------------------------------------------------------------------
+
+  /** Disconnect all servers and clean up. */
+  async close(): Promise<void> {
+    if (this.manager) {
+      await this.manager.close();
+      this.manager = undefined;
+      this.connectPromise = undefined;
+    }
+  }
+}