@evantahler/mcpx 0.17.0 → 0.18.0

package/.claude/skills/mcpx.md

@@ -8,6 +8,26 @@ trigger: when the user wants to interact with external services, APIs, or MCP to
 
 You have access to external tools via `mcpx`. Use this workflow:
 
+## 0. Self-authorize (if needed)
+
+By default, Claude Code prompts the user for every `mcpx exec` call. If the user has approved `Bash(mcpx allow:*)` (you cannot do this yourself — the user must approve it when prompted), you can grant yourself granular permissions before executing:
+
+```bash
+mcpx allow <server> <tool>
+```
+
+This writes a specific pattern to `.claude/settings.local.json`. After that, `mcpx exec <server> <tool>` runs without prompting.
+
+For broader access:
+
+```bash
+mcpx allow <server>                # all tools on a server
+mcpx allow --all-read              # search, info, list, servers, ping, etc.
+mcpx allow --all                   # all mcpx exec calls
+```
+
+**Important:** If the user has not approved `Bash(mcpx allow:*)`, skip this step — Claude Code will prompt the user directly for each `mcpx exec` call instead.
+
 ## 1. Search for tools
 
 ```bash
@@ -152,6 +172,15 @@ mcpx deauth <server>           # remove stored auth
 | `mcpx task get <server> <taskId>`     | Get task status                   |
 | `mcpx task result <server> <taskId>`  | Retrieve completed task result    |
 | `mcpx task cancel <server> <taskId>`  | Cancel a running task             |
+| `mcpx allow <server>`                | Allow agent to exec all tools on a server |
+| `mcpx allow <server> <tools...>`     | Allow specific tools only         |
+| `mcpx allow --all`                   | Allow all mcpx exec calls         |
+| `mcpx allow --all-read`              | Allow read-only commands          |
+| `mcpx allow --list`                  | Show current mcpx permissions     |
+| `mcpx allow --cursor <server>`       | Target Cursor instead of Claude   |
+| `mcpx deny <server>`                 | Remove server permissions         |
+| `mcpx deny --all`                    | Remove all mcpx permissions       |
+| `mcpx deny --cursor <server>`        | Target Cursor instead of Claude   |
 | `mcpx check-update`                  | Check for a newer version of mcpx |
 | `mcpx upgrade`                       | Upgrade mcpx to the latest version|
 
@@ -202,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

@@ -101,6 +101,22 @@ mcpx task list my-server
 
 Some servers request user input mid-operation. mcpx handles this automatically in interactive mode. Use `-N` / `--no-interactive` to decline all elicitation (for scripts/CI), or `--json` to handle elicitation programmatically via stdin/stdout.
 
+## 6. Self-authorize (if needed)
+
+Cursor prompts you for every `mcpx exec` call. You can grant yourself granular permissions:
+
+```bash
+mcpx allow <server> --cursor              # all tools on a server
+mcpx allow <server> <tool> --cursor       # specific tool
+mcpx allow --all-read --cursor            # search, info, list, etc.
+mcpx allow --all --cursor                 # all mcpx exec calls
+mcpx allow --list --cursor                # show current permissions
+mcpx deny <server> --cursor               # revoke server permissions
+mcpx deny --all --cursor                  # revoke all permissions
+```
+
+This writes `Shell(mcpx exec:server:*)` patterns to `.cursor/cli.json`.
+
 ## Authentication
 
 ```bash
@@ -132,7 +148,7 @@ mcpx deauth <server>           # remove stored auth
 | `mcpx index -i`                       | Show index status                 |
 | `mcpx auth <server>`                  | Authenticate with OAuth           |
 | `mcpx auth <server> -s`               | Check token status and TTL        |
-| `mcpx auth <server> -r`              | Force token refresh               |
+| `mcpx auth <server> -r`               | Force token refresh               |
 | `mcpx auth <server> --no-index`       | Authenticate without rebuilding index |
 | `mcpx deauth <server>`                | Remove stored authentication      |
 | `mcpx ping`                           | Check connectivity to all servers |
@@ -152,8 +168,15 @@ mcpx deauth <server>           # remove stored auth
 | `mcpx task get <server> <taskId>`     | Get task status                   |
 | `mcpx task result <server> <taskId>`  | Retrieve completed task result    |
 | `mcpx task cancel <server> <taskId>`  | Cancel a running task             |
-| `mcpx check-update`                  | Check for a newer version of mcpx |
-| `mcpx upgrade`                       | Upgrade mcpx to the latest version|
+| `mcpx allow <server> --cursor`        | Allow exec all tools on a server  |
+| `mcpx allow <server> <tools...> --cursor` | Allow specific tools only    |
+| `mcpx allow --all --cursor`           | Allow all mcpx exec calls         |
+| `mcpx allow --all-read --cursor`      | Allow read-only commands          |
+| `mcpx allow --list --cursor`          | Show current permissions          |
+| `mcpx deny <server> --cursor`         | Remove server permissions         |
+| `mcpx deny --all --cursor`            | Remove all mcpx permissions       |
+| `mcpx check-update`                   | Check for a newer version of mcpx |
+| `mcpx upgrade`                        | Upgrade mcpx to the latest version|
 
 ## Global flags
 
@@ -202,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
 
@@ -104,6 +105,14 @@ mcpx search -n 5 "manage pull requests"
 | `mcpx task get <server> <taskId>`      | Get task status                                        |
 | `mcpx task result <server> <taskId>`   | Retrieve completed task result                         |
 | `mcpx task cancel <server> <taskId>`   | Cancel a running task                                  |
+| `mcpx allow <server>`                  | Allow an agent to exec all tools on a server           |
+| `mcpx allow <server> <tools...>`       | Allow specific tools only                              |
+| `mcpx allow --all`                     | Allow all mcpx exec calls                              |
+| `mcpx allow --all-read`                | Allow read-only commands (search, info, list, etc.)    |
+| `mcpx allow --list`                    | Show current mcpx-related permissions                  |
+| `mcpx allow --cursor <server>`         | Allow for Cursor instead of Claude Code                |
+| `mcpx deny <server>`                   | Remove permissions for a server                        |
+| `mcpx deny --all`                      | Remove all mcpx-related permissions                    |
 | `mcpx check-update`                    | Check for a newer version of mcpx                      |
 | `mcpx upgrade`                         | Upgrade mcpx to the latest version                     |
 
@@ -627,6 +636,127 @@ 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.
+
+**Key insight:** If the user allows the initial permission pattern once (safe — it only writes to local settings files), the agent can then grant itself access to specific tools as needed. This is an opt-in workflow — by default, agents cannot self-authorize and will prompt the user for each `mcpx exec` call.
+
+```bash
+# Allow all tools on a server (Claude Code, default)
+mcpx allow github
+
+# Allow for Cursor instead
+mcpx allow github --cursor
+
+# Allow specific tools only
+mcpx allow github search_repositories get_file
+
+# Allow read-only commands (search, info, list, servers, ping, etc.)
+mcpx allow --all-read
+
+# Allow all mcpx exec calls
+mcpx allow --all
+
+# Show current permissions across all scopes
+mcpx allow --list
+mcpx allow --list --cursor
+
+# Preview what would be written
+mcpx allow github --dry-run
+
+# Revoke a server's permissions
+mcpx deny github
+
+# Revoke all mcpx permissions
+mcpx deny --all
+```
+
+**Target flag** — by default, permissions target Claude Code. Use `--cursor` to target Cursor instead:
+
+| Flag        | Pattern prefix | Settings files                                  |
+| ----------- | -------------- | ----------------------------------------------- |
+| _(default)_ | `Bash(…)`      | `.claude/settings.local.json`, etc.             |
+| `--cursor`  | `Shell(…)`     | `.cursor/cli.json`, `~/.cursor/cli-config.json` |
+
+**Scope flags** control where the permission is written:
+
+| Flag        | Claude Code file              | Cursor file                 | Default |
+| ----------- | ----------------------------- | --------------------------- | ------- |
+| `--local`   | `.claude/settings.local.json` | `.cursor/cli.json`          | ✓       |
+| `--project` | `.claude/settings.json`       | `.cursor/cli.json`          |         |
+| `--global`  | `~/.claude/settings.json`     | `~/.cursor/cli-config.json` |         |
+
+**`allow` options:**
+
+| Flag         | Purpose                                             |
+| ------------ | --------------------------------------------------- |
+| `--all`      | Allow all mcpx exec calls                           |
+| `--all-read` | Allow read-only commands (search, info, list, etc.) |
+| `--list`     | Show current mcpx-related permissions               |
+| `--cursor`   | Target Cursor settings instead of Claude Code       |
+| `--local`    | Write to local settings (default)                   |
+| `--project`  | Write to project settings (shared)                  |
+| `--global`   | Write to global settings                            |
+| `--dry-run`  | Show patterns without writing                       |
+
+**`deny` options:**
+
+| Flag         | Purpose                                       |
+| ------------ | --------------------------------------------- |
+| `--all`      | Remove all mcpx-related permissions           |
+| `--all-read` | Remove read-only command permissions          |
+| `--cursor`   | Target Cursor settings instead of Claude Code |
+| `--local`    | Write to local settings (default)             |
+| `--project`  | Write to project settings (shared)            |
+| `--global`   | Write to global settings                      |
+| `--dry-run`  | Show what would be removed                    |
+
 ## Development
 
 ```bash

package/package.json

@@ -1,8 +1,14 @@
 {
   "name": "@evantahler/mcpx",
-  "version": "0.17.0",
+  "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/cli.ts

@@ -15,6 +15,8 @@ import { registerResourceCommand } from "./commands/resource.ts";
 import { registerPromptCommand } from "./commands/prompt.ts";
 import { registerServersCommand } from "./commands/servers.ts";
 import { registerTaskCommand } from "./commands/task.ts";
+import { registerAllowCommand } from "./commands/allow.ts";
+import { registerDenyCommand } from "./commands/deny.ts";
 import { registerCheckUpdateCommand } from "./commands/check-update.ts";
 import { registerUpgradeCommand } from "./commands/upgrade.ts";
 import { maybeCheckForUpdate } from "./update/background.ts";
@@ -53,6 +55,8 @@ registerResourceCommand(program);
 registerPromptCommand(program);
 registerServersCommand(program);
 registerTaskCommand(program);
+registerAllowCommand(program);
+registerDenyCommand(program);
 registerCheckUpdateCommand(program);
 registerUpgradeCommand(program);
 

package/src/commands/allow.ts

@@ -0,0 +1,163 @@
+import type { Command } from "commander";
+import { bold, cyan, dim, green, yellow } from "ansis";
+import {
+  type Client,
+  type Scope,
+  resolveSettingsPath,
+  readClientSettings,
+  writeClientSettings,
+  execPattern,
+  readOnlyPatterns,
+  allExecPattern,
+  allowCommandPattern,
+  denyCommandPattern,
+  addPatterns,
+  getMcpxPatterns,
+} from "../lib/client-settings.ts";
+import { formatOutput } from "../output/format-output.ts";
+import type { FormatOptions } from "../output/formatter.ts";
+
+export function registerAllowCommand(program: Command) {
+  program
+    .command("allow")
+    .description("add permission rules for mcpx commands (Claude Code or Cursor)")
+    .argument("[server]", "server name to allow")
+    .argument("[tools...]", "specific tool names to allow")
+    .option("--all", "allow all mcpx exec calls")
+    .option("--all-read", "allow read-only commands (search, info, list, servers, ping, etc.)")
+    .option("--list", "show current mcpx-related permissions")
+    .option("--cursor", "target Cursor settings instead of Claude Code")
+    .option("--local", "write to local settings (default)")
+    .option("--project", "write to project settings (shared)")
+    .option("--global", "write to global settings")
+    .option("--dry-run", "show patterns without writing")
+    .action(
+      async (
+        server: string | undefined,
+        tools: string[],
+        options: {
+          all?: boolean;
+          allRead?: boolean;
+          list?: boolean;
+          cursor?: boolean;
+          local?: boolean;
+          project?: boolean;
+          global?: boolean;
+          dryRun?: boolean;
+        },
+      ) => {
+        const formatOptions: FormatOptions = { json: program.opts().json };
+        const client: Client = options.cursor ? "cursor" : "claude";
+
+        // --list mode: show current permissions across all scopes
+        if (options.list) {
+          // Cursor maps local and project to the same file, so only show unique scopes
+          const scopes: Scope[] =
+            client === "cursor" ? ["local", "global"] : ["local", "project", "global"];
+          const results: { scope: Scope; path: string; patterns: string[] }[] = [];
+
+          for (const scope of scopes) {
+            const path = resolveSettingsPath(scope, client);
+            const settings = await readClientSettings(path);
+            const patterns = getMcpxPatterns(settings, client);
+            results.push({ scope, path, patterns });
+          }
+
+          console.log(
+            formatOutput(
+              results.map((r) => ({ scope: r.scope, path: r.path, patterns: r.patterns })),
+              () => {
+                const lines: string[] = [];
+                for (const r of results) {
+                  lines.push(bold(`${r.scope}`) + dim(` (${r.path})`));
+                  if (r.patterns.length === 0) {
+                    lines.push(`  ${dim("(none)")}`);
+                  } else {
+                    for (const p of r.patterns) {
+                      lines.push(`  ${green("✓")} ${p}`);
+                    }
+                  }
+                  lines.push("");
+                }
+                return lines.join("\n").trimEnd();
+              },
+              formatOptions,
+            ),
+          );
+          return;
+        }
+
+        // Build the list of patterns to add
+        const patterns: string[] = [];
+
+        if (options.all) {
+          patterns.push(allExecPattern(client));
+        }
+
+        if (options.allRead) {
+          patterns.push(...readOnlyPatterns(client));
+        }
+
+        if (server && tools.length > 0) {
+          for (const tool of tools) {
+            patterns.push(execPattern(server, tool, client));
+          }
+        } else if (server) {
+          patterns.push(execPattern(server, undefined, client));
+        }
+
+        if (patterns.length === 0) {
+          console.error("error: specify a server, --all, or --all-read. See 'mcpx allow --help'.");
+          process.exit(1);
+        }
+
+        // Always include allow/deny command patterns so the agent can self-manage
+        patterns.push(allowCommandPattern(client));
+        patterns.push(denyCommandPattern(client));
+
+        const scope: Scope = options.global ? "global" : options.project ? "project" : "local";
+        const path = resolveSettingsPath(scope, client);
+
+        if (options.dryRun) {
+          console.log(
+            formatOutput(
+              { scope, path, patterns },
+              () => {
+                const lines: string[] = [];
+                lines.push(bold("Dry run") + dim(` — would write to ${path}:`));
+                for (const p of patterns) {
+                  lines.push(`  ${yellow("+")} ${p}`);
+                }
+                return lines.join("\n");
+              },
+              formatOptions,
+            ),
+          );
+          return;
+        }
+
+        const settings = await readClientSettings(path);
+        const { settings: updated, added } = addPatterns(settings, patterns);
+        await writeClientSettings(path, updated);
+
+        console.log(
+          formatOutput(
+            { scope, path, added, total: (updated.permissions?.allow ?? []).length },
+            () => {
+              const lines: string[] = [];
+              if (added.length === 0) {
+                lines.push(dim("All patterns already present — no changes."));
+              } else {
+                lines.push(bold(`Added ${added.length} permission(s)`) + dim(` → ${path}`));
+                for (const p of added) {
+                  lines.push(`  ${green("+")} ${p}`);
+                }
+              }
+              return lines.join("\n");
+            },
+            formatOptions,
+          ),
+        );
+      },
+    );
+}

package/src/commands/deny.ts

@@ -0,0 +1,134 @@
+import type { Command } from "commander";
+import { bold, dim, green, red, yellow } from "ansis";
+import {
+  type Client,
+  type Scope,
+  resolveSettingsPath,
+  readClientSettings,
+  writeClientSettings,
+  execPattern,
+  readOnlyPatterns,
+  allExecPattern,
+  removePatterns,
+  removeAllMcpxPatterns,
+  getServerPatterns,
+} from "../lib/client-settings.ts";
+import { formatOutput } from "../output/format-output.ts";
+import type { FormatOptions } from "../output/formatter.ts";
+
+export function registerDenyCommand(program: Command) {
+  program
+    .command("deny")
+    .description("remove permission rules for mcpx commands (Claude Code or Cursor)")
+    .argument("[server]", "server name to deny")
+    .argument("[tools...]", "specific tool names to deny")
+    .option("--all", "remove all mcpx-related permissions")
+    .option("--all-read", "remove read-only command permissions")
+    .option("--cursor", "target Cursor settings instead of Claude Code")
+    .option("--local", "write to local settings (default)")
+    .option("--project", "write to project settings (shared)")
+    .option("--global", "write to global settings")
+    .option("--dry-run", "show what would be removed")
+    .action(
+      async (
+        server: string | undefined,
+        tools: string[],
+        options: {
+          all?: boolean;
+          allRead?: boolean;
+          cursor?: boolean;
+          local?: boolean;
+          project?: boolean;
+          global?: boolean;
+          dryRun?: boolean;
+        },
+      ) => {
+        const formatOptions: FormatOptions = { json: program.opts().json };
+        const client: Client = options.cursor ? "cursor" : "claude";
+        const scope: Scope = options.global ? "global" : options.project ? "project" : "local";
+        const path = resolveSettingsPath(scope, client);
+        const settings = await readClientSettings(path);
+
+        let result: { settings: typeof settings; removed: string[] };
+
+        if (options.all) {
+          // Remove all mcpx-related patterns
+          result = removeAllMcpxPatterns(settings, client);
+        } else {
+          // Build the list of patterns to remove
+          const patterns: string[] = [];
+
+          if (options.allRead) {
+            patterns.push(...readOnlyPatterns(client));
+          }
+
+          if (server && tools.length > 0) {
+            for (const tool of tools) {
+              patterns.push(execPattern(server, tool, client));
+            }
+          } else if (server) {
+            // Remove the server-level pattern AND all tool-specific patterns for this server
+            patterns.push(execPattern(server, undefined, client));
+            patterns.push(...getServerPatterns(settings, server, client));
+          }
+
+          if (patterns.length === 0) {
+            console.error("error: specify a server, --all, or --all-read. See 'mcpx deny --help'.");
+            process.exit(1);
+          }
+
+          result = removePatterns(settings, patterns);
+        }
+
+        if (options.dryRun) {
+          console.log(
+            formatOutput(
+              { scope, path, wouldRemove: result.removed },
+              () => {
+                const lines: string[] = [];
+                lines.push(bold("Dry run") + dim(` — would remove from ${path}:`));
+                if (result.removed.length === 0) {
+                  lines.push(`  ${dim("(no matching patterns found)")}`);
+                } else {
+                  for (const p of result.removed) {
+                    lines.push(`  ${yellow("-")} ${p}`);
+                  }
+                }
+                return lines.join("\n");
+              },
+              formatOptions,
+            ),
+          );
+          return;
+        }
+
+        await writeClientSettings(path, result.settings);
+
+        console.log(
+          formatOutput(
+            {
+              scope,
+              path,
+              removed: result.removed,
+              total: (result.settings.permissions?.allow ?? []).length,
+            },
+            () => {
+              const lines: string[] = [];
+              if (result.removed.length === 0) {
+                lines.push(dim("No matching patterns found — no changes."));
+              } else {
+                lines.push(
+                  bold(`Removed ${result.removed.length} permission(s)`) + dim(` → ${path}`),
+                );
+                for (const p of result.removed) {
+                  lines.push(`  ${red("-")} ${p}`);
+                }
+              }
+              return lines.join("\n");
+            },
+            formatOptions,
+          ),
+        );
+      },
+    );
+}

package/src/lib/client-settings.ts

@@ -0,0 +1,210 @@
+import { join } from "path";
+import { homedir } from "os";
+import { readFile, mkdir, writeFile } from "fs/promises";
+
+export type Client = "claude" | "cursor";
+export type Scope = "local" | "project" | "global";
+
+export interface ClientSettings {
+  permissions?: {
+    allow?: string[];
+    deny?: string[];
+  };
+  [key: string]: unknown;
+}
+
+function prefix(client: Client): string {
+  return client === "claude" ? "Bash" : "Shell";
+}
+
+/** Resolve the settings file path for a given scope and client */
+export function resolveSettingsPath(scope: Scope, client: Client = "claude"): string {
+  if (client === "cursor") {
+    switch (scope) {
+      case "local":
+      case "project":
+        return join(process.cwd(), ".cursor", "cli.json");
+      case "global":
+        return join(homedir(), ".cursor", "cli-config.json");
+    }
+  }
+
+  switch (scope) {
+    case "local":
+      return join(process.cwd(), ".claude", "settings.local.json");
+    case "project":
+      return join(process.cwd(), ".claude", "settings.json");
+    case "global":
+      return join(homedir(), ".claude", "settings.json");
+  }
+}
+
+/** Read client settings from a file, returning empty settings if the file doesn't exist */
+export async function readClientSettings(path: string): Promise<ClientSettings> {
+  try {
+    const content = await readFile(path, "utf-8");
+    return JSON.parse(content) as ClientSettings;
+  } catch {
+    return {};
+  }
+}
+
+/** Write client settings to a file, creating parent directories as needed */
+export async function writeClientSettings(path: string, settings: ClientSettings): Promise<void> {
+  const dir = join(path, "..");
+  await mkdir(dir, { recursive: true });
+  await writeFile(path, JSON.stringify(settings, null, 2) + "\n", "utf-8");
+}
+
+/** Generate a permission pattern for mcpx exec with a specific server and optional tool */
+export function execPattern(server: string, tool?: string, client: Client = "claude"): string {
+  const p = prefix(client);
+  if (tool) {
+    return `${p}(mcpx exec:${server}:${tool}:*)`;
+  }
+  return `${p}(mcpx exec:${server}:*)`;
+}
+
+/** Read-only mcpx commands that are safe to allow broadly */
+const READ_ONLY_COMMANDS = [
+  "search",
+  "info",
+  "servers",
+  "ping",
+  "resource",
+  "prompt",
+  "task",
+  "index",
+];
+
+/** Generate patterns for all read-only mcpx commands */
+export function readOnlyPatterns(client: Client = "claude"): string[] {
+  const p = prefix(client);
+  return READ_ONLY_COMMANDS.map((cmd) => `${p}(mcpx ${cmd}:*)`);
+}
+
+/** Generate the broad allow-all pattern for mcpx exec */
+export function allExecPattern(client: Client = "claude"): string {
+  return `${prefix(client)}(mcpx exec:*)`;
+}
+
+/** Generate the allow pattern for mcpx allow itself */
+export function allowCommandPattern(client: Client = "claude"): string {
+  return `${prefix(client)}(mcpx allow:*)`;
+}
+
+/** Generate the allow pattern for mcpx deny itself */
+export function denyCommandPattern(client: Client = "claude"): string {
+  return `${prefix(client)}(mcpx deny:*)`;
+}
+
+/** Check if a permission pattern is mcpx-related */
+export function isMcpxPattern(pattern: string, client: Client = "claude"): boolean {
+  return pattern.startsWith(`${prefix(client)}(mcpx `);
+}
+
+/** Add patterns to settings, deduplicating. Returns the updated settings and list of newly added patterns. */
+export function addPatterns(
+  settings: ClientSettings,
+  patterns: string[],
+): { settings: ClientSettings; added: string[] } {
+  const existing = new Set(settings.permissions?.allow ?? []);
+  const added: string[] = [];
+
+  for (const p of patterns) {
+    if (!existing.has(p)) {
+      existing.add(p);
+      added.push(p);
+    }
+  }
+
+  return {
+    settings: {
+      ...settings,
+      permissions: {
+        ...settings.permissions,
+        allow: [...existing],
+      },
+    },
+    added,
+  };
+}
+
+/** Remove specific patterns from settings. Returns the updated settings and list of removed patterns. */
+export function removePatterns(
+  settings: ClientSettings,
+  patterns: string[],
+): { settings: ClientSettings; removed: string[] } {
+  const existing = settings.permissions?.allow ?? [];
+  const toRemove = new Set(patterns);
+  const removed: string[] = [];
+  const remaining: string[] = [];
+
+  for (const p of existing) {
+    if (toRemove.has(p)) {
+      removed.push(p);
+    } else {
+      remaining.push(p);
+    }
+  }
+
+  return {
+    settings: {
+      ...settings,
+      permissions: {
+        ...settings.permissions,
+        allow: remaining,
+      },
+    },
+    removed,
+  };
+}
+
+/** Remove all mcpx-related patterns from settings. Returns the updated settings and list of removed patterns. */
+export function removeAllMcpxPatterns(
+  settings: ClientSettings,
+  client: Client = "claude",
+): {
+  settings: ClientSettings;
+  removed: string[];
+} {
+  const existing = settings.permissions?.allow ?? [];
+  const removed: string[] = [];
+  const remaining: string[] = [];
+
+  for (const p of existing) {
+    if (isMcpxPattern(p, client)) {
+      removed.push(p);
+    } else {
+      remaining.push(p);
+    }
+  }
+
+  return {
+    settings: {
+      ...settings,
+      permissions: {
+        ...settings.permissions,
+        allow: remaining,
+      },
+    },
+    removed,
+  };
+}
+
+/** Extract all mcpx-related patterns from settings */
+export function getMcpxPatterns(settings: ClientSettings, client: Client = "claude"): string[] {
+  return (settings.permissions?.allow ?? []).filter((p) => isMcpxPattern(p, client));
+}
+
+/** Get all mcpx-related patterns for a specific server */
+export function getServerPatterns(
+  settings: ClientSettings,
+  server: string,
+  client: Client = "claude",
+): string[] {
+  const p = prefix(client);
+  return getMcpxPatterns(settings, client).filter(
+    (pat) => pat.startsWith(`${p}(mcpx exec:${server}:`) || pat === `${p}(mcpx exec:${server}:*)`,
+  );
+}

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;
+    }
+  }
+}