@evantahler/mcpx 0.15.0

package/.claude/worktrees/elastic-jennings/test/search/keyword.test.ts

@@ -0,0 +1,80 @@
+import { describe, test, expect } from "bun:test";
+import { keywordSearch } from "../../src/search/keyword.ts";
+import type { IndexedTool } from "../../src/config/schemas.ts";
+
+const tools: IndexedTool[] = [
+  {
+    server: "arcade",
+    tool: "Gmail_SendEmail",
+    description: "Send an email message via Gmail",
+    scenarios: ["send an email", "compose a message"],
+    keywords: ["gmail", "send", "email"],
+    embedding: [],
+  },
+  {
+    server: "arcade",
+    tool: "Slack_SendMessage",
+    description: "Send a message to a Slack channel",
+    scenarios: ["send a slack message", "post to channel"],
+    keywords: ["slack", "send", "message"],
+    embedding: [],
+  },
+  {
+    server: "arcade",
+    tool: "Github_CreatePullRequest",
+    description: "Create a pull request on GitHub",
+    scenarios: ["create a PR", "open a pull request"],
+    keywords: ["github", "create", "pull", "request"],
+    embedding: [],
+  },
+];
+
+describe("keywordSearch", () => {
+  test("matches tool name substring", () => {
+    const results = keywordSearch("gmail", tools);
+    expect(results.length).toBeGreaterThan(0);
+    expect(results[0]!.tool).toBe("Gmail_SendEmail");
+  });
+
+  test("matches keywords", () => {
+    const results = keywordSearch("send", tools);
+    expect(results.length).toBe(2);
+    expect(results.map((r) => r.tool)).toContain("Gmail_SendEmail");
+    expect(results.map((r) => r.tool)).toContain("Slack_SendMessage");
+  });
+
+  test("matches description text", () => {
+    const results = keywordSearch("pull request", tools);
+    expect(results.length).toBeGreaterThan(0);
+    expect(results[0]!.tool).toBe("Github_CreatePullRequest");
+  });
+
+  test("glob matching on tool name", () => {
+    const results = keywordSearch("Gmail_*", tools);
+    expect(results.length).toBe(1);
+    expect(results[0]!.tool).toBe("Gmail_SendEmail");
+  });
+
+  test("case insensitive", () => {
+    const results = keywordSearch("SLACK", tools);
+    expect(results.length).toBeGreaterThan(0);
+    expect(results[0]!.tool).toBe("Slack_SendMessage");
+  });
+
+  test("returns empty for no match", () => {
+    const results = keywordSearch("zzzznotfound", tools);
+    expect(results.length).toBe(0);
+  });
+
+  test("results sorted by score descending", () => {
+    const results = keywordSearch("send", tools);
+    for (let i = 1; i < results.length; i++) {
+      expect(results[i]!.score).toBeLessThanOrEqual(results[i - 1]!.score);
+    }
+  });
+
+  test("multi-word query matches better", () => {
+    const results = keywordSearch("send email", tools);
+    expect(results[0]!.tool).toBe("Gmail_SendEmail");
+  });
+});

package/.claude/worktrees/elastic-jennings/test/search/semantic.test.ts

@@ -0,0 +1,32 @@
+import { describe, test, expect } from "bun:test";
+import { cosineSimilarity } from "../../src/search/semantic.ts";
+
+describe("cosineSimilarity", () => {
+  test("identical vectors return 1", () => {
+    const v = [1, 2, 3];
+    expect(cosineSimilarity(v, v)).toBeCloseTo(1.0, 5);
+  });
+
+  test("orthogonal vectors return 0", () => {
+    expect(cosineSimilarity([1, 0], [0, 1])).toBeCloseTo(0.0, 5);
+  });
+
+  test("opposite vectors return -1", () => {
+    expect(cosineSimilarity([1, 0], [-1, 0])).toBeCloseTo(-1.0, 5);
+  });
+
+  test("empty vectors return 0", () => {
+    expect(cosineSimilarity([], [])).toBe(0);
+  });
+
+  test("mismatched lengths return 0", () => {
+    expect(cosineSimilarity([1, 2], [1, 2, 3])).toBe(0);
+  });
+
+  test("normalized vectors", () => {
+    const a = [0.6, 0.8];
+    const b = [0.8, 0.6];
+    const expected = 0.6 * 0.8 + 0.8 * 0.6; // 0.96
+    expect(cosineSimilarity(a, b)).toBeCloseTo(expected, 5);
+  });
+});

package/.claude/worktrees/elastic-jennings/test/validation/schema.test.ts

@@ -0,0 +1,113 @@
+import { describe, test, expect } from "bun:test";
+import { validateToolInput } from "../../src/validation/schema.ts";
+import type { Tool } from "../../src/config/schemas.ts";
+
+function makeTool(name: string, inputSchema: Record<string, unknown>): Tool {
+  return {
+    name,
+    description: "A test tool",
+    inputSchema: inputSchema as Tool["inputSchema"],
+  };
+}
+
+describe("validateToolInput", () => {
+  test("passes valid input", () => {
+    const tool = makeTool("valid_input", {
+      type: "object",
+      properties: { name: { type: "string" } },
+      required: ["name"],
+    });
+    const result = validateToolInput("s", tool, { name: "hello" });
+    expect(result.valid).toBe(true);
+    expect(result.errors).toHaveLength(0);
+  });
+
+  test("catches missing required field", () => {
+    const tool = makeTool("missing_required", {
+      type: "object",
+      properties: { name: { type: "string" }, age: { type: "number" } },
+      required: ["name", "age"],
+    });
+    const result = validateToolInput("s", tool, { name: "hello" });
+    expect(result.valid).toBe(false);
+    expect(result.errors.length).toBeGreaterThan(0);
+    expect(result.errors[0]!.message).toContain("age");
+  });
+
+  test("catches wrong type", () => {
+    const tool = makeTool("wrong_type", {
+      type: "object",
+      properties: { count: { type: "number" } },
+    });
+    const result = validateToolInput("s", tool, { count: "not a number" });
+    expect(result.valid).toBe(false);
+    expect(result.errors[0]!.message).toContain("number");
+  });
+
+  test("catches invalid enum value", () => {
+    const tool = makeTool("bad_enum", {
+      type: "object",
+      properties: { color: { type: "string", enum: ["red", "blue", "green"] } },
+    });
+    const result = validateToolInput("s", tool, { color: "purple" });
+    expect(result.valid).toBe(false);
+    expect(result.errors[0]!.message).toContain("one of");
+  });
+
+  test("validates nested objects", () => {
+    const tool = makeTool("nested", {
+      type: "object",
+      properties: {
+        user: {
+          type: "object",
+          properties: { email: { type: "string" } },
+          required: ["email"],
+        },
+      },
+    });
+    const result = validateToolInput("s", tool, { user: {} });
+    expect(result.valid).toBe(false);
+    expect(result.errors[0]!.message).toContain("email");
+  });
+
+  test("passes when no schema properties defined", () => {
+    const tool = makeTool("no_props", { type: "object" });
+    const result = validateToolInput("s", tool, { anything: "goes" });
+    expect(result.valid).toBe(true);
+  });
+
+  test("passes with empty input and no required fields", () => {
+    const tool = makeTool("optional_only", {
+      type: "object",
+      properties: { optional: { type: "string" } },
+    });
+    const result = validateToolInput("s", tool, {});
+    expect(result.valid).toBe(true);
+  });
+
+  test("reports multiple errors", () => {
+    const tool = makeTool("multi_error", {
+      type: "object",
+      properties: {
+        name: { type: "string" },
+        age: { type: "number" },
+      },
+      required: ["name", "age"],
+    });
+    const result = validateToolInput("s", tool, {});
+    expect(result.valid).toBe(false);
+    expect(result.errors.length).toBe(2);
+  });
+
+  test("caches compiled validators", () => {
+    const tool = makeTool("cached_tool", {
+      type: "object",
+      properties: { x: { type: "string" } },
+      required: ["x"],
+    });
+    // Call twice — second should use cache
+    validateToolInput("cache_test", tool, { x: "a" });
+    const result = validateToolInput("cache_test", tool, {});
+    expect(result.valid).toBe(false);
+  });
+});

package/.claude/worktrees/elastic-jennings/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  }
+}

package/.cursor/rules/mcpx.mdc

@@ -0,0 +1,165 @@
+---
+description: Discover and use MCP tools via the mcpx CLI
+globs:
+alwaysApply: true
+---
+
+# mcpx — MCP Tool Discovery and Execution
+
+You have access to external tools via `mcpx`. Use this workflow:
+
+## 1. Search for tools
+
+```bash
+mcpx search "<what you want to do>"
+```
+
+## 2. Inspect the tool schema
+
+```bash
+mcpx info <server> <tool>
+```
+
+This shows parameters, types, required fields, and the full JSON Schema.
+
+## 3. Execute the tool
+
+```bash
+mcpx exec <server> <tool> '<json args>'
+mcpx exec <server> <tool> -f params.json
+```
+
+## Rules
+
+- Always search before executing — don't assume tool names exist
+- Always inspect the schema before executing — validate you have the right arguments
+- Use `mcpx search -k` for exact name matching
+- Pipe results through `jq` when you need to extract specific fields
+- Use `-v` for verbose debugging (HTTP details + JSON-RPC protocol messages) if an exec fails unexpectedly
+- Use `-l debug` to see all server log messages, or `-l error` for errors only
+
+## Examples
+
+```bash
+# Find tools related to sending messages
+mcpx search "send a message"
+
+# See what parameters Slack_SendMessage needs
+mcpx info arcade Slack_SendMessage
+
+# Send a message
+mcpx exec arcade Slack_SendMessage '{"channel":"#general","message":"hello"}'
+
+# Chain commands — search repos and read the first result
+mcpx exec github search_repositories '{"query":"mcp"}' \
+  | jq -r '.content[0].text | fromjson | .items[0].full_name' \
+  | xargs -I {} mcpx exec github get_file_contents '{"owner":"{}","path":"README.md"}'
+
+# Read args from stdin
+echo '{"path":"./README.md"}' | mcpx exec filesystem read_file
+
+# Pipe from a file
+cat params.json | mcpx exec server tool
+
+# Read args from a file with --file flag
+mcpx exec filesystem read_file -f params.json
+```
+
+## 4. Long-running tools (Tasks)
+
+Some tools support async execution via MCP Tasks. mcpx auto-detects this and uses task-augmented execution when available.
+
+```bash
+# Default: waits for the task to complete, showing progress
+mcpx exec my-server long_running_tool '{"input": "data"}'
+
+# Return immediately with a task handle (for scripting/polling)
+mcpx exec my-server long_running_tool '{"input": "data"}' --no-wait
+
+# Check task status
+mcpx task get my-server <taskId>
+
+# Retrieve the result once complete
+mcpx task result my-server <taskId>
+
+# List all tasks on a server
+mcpx task list my-server
+
+# Cancel a running task
+mcpx task cancel my-server <taskId>
+```
+
+For tools that don't support tasks, `exec` works exactly as before.
+
+## 5. Elicitation (Server-Requested Input)
+
+Some servers request user input mid-operation (e.g., confirmations, auth flows). mcpx handles this automatically:
+
+```bash
+# Interactive — prompts appear in the terminal
+mcpx exec my-server deploy_tool '{"target": "staging"}'
+# Server requests input: Confirm deployment
+#   *Confirm [y/n]: y
+
+# Non-interactive — decline all elicitation (for scripts/CI)
+mcpx exec my-server deploy_tool '{"target": "staging"}' --no-interactive
+
+# JSON mode — read/write elicitation as JSON via stdin/stdout
+echo '{"action":"accept","content":{"confirm":true}}' | \
+  mcpx exec my-server deploy_tool '{"target": "staging"}' --json
+```
+
+## Authentication
+
+Some HTTP servers require OAuth. If you see an "Not authenticated" error:
+
+```bash
+mcpx auth <server>        # authenticate via browser
+mcpx auth <server> -s     # check token status and TTL
+mcpx auth <server> -r     # force token refresh
+mcpx deauth <server>      # remove stored auth
+```
+
+## Available commands
+
+| Command                                | Purpose                           |
+| -------------------------------------- | --------------------------------- |
+| `mcpx`                               | List all servers and tools        |
+| `mcpx servers`                       | List servers (name, type, detail) |
+| `mcpx -d`                            | List with descriptions            |
+| `mcpx info <server>`                 | Server overview (version, capabilities, tools) |
+| `mcpx info <server> <tool>`          | Show tool schema                  |
+| `mcpx exec <server>`                 | List tools for a server           |
+| `mcpx exec <server> <tool> '<json>'` | Execute a tool                    |
+| `mcpx exec <server> <tool> -f file`  | Execute with args from file       |
+| `mcpx search "<query>"`              | Search tools (keyword + semantic) |
+| `mcpx search -k "<pattern>"`         | Keyword/glob search only          |
+| `mcpx search -q "<query>"`           | Semantic search only              |
+| `mcpx search -n <number> "<query>"`  | Limit number of results (default: 10) |
+| `mcpx index`                         | Build/rebuild search index        |
+| `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 deauth <server>`               | Remove stored authentication      |
+| `mcpx ping`                          | Check connectivity to all servers |
+| `mcpx ping <server> [server2...]`    | Check specific server(s)          |
+| `mcpx add <name> --command <cmd>`    | Add a stdio MCP server            |
+| `mcpx add <name> --url <url>`        | Add an HTTP MCP server            |
+| `mcpx add <name> --url <url> --transport sse` | Add a legacy SSE server  |
+| `mcpx remove <name>`                 | Remove an MCP server              |
+| `mcpx skill install --claude`        | Install mcpx skill for Claude   |
+| `mcpx skill install --cursor`        | Install mcpx rule for Cursor    |
+| `mcpx resource`                     | List all resources across servers |
+| `mcpx resource <server>`            | List resources for a server       |
+| `mcpx resource <server> <uri>`      | Read a specific resource          |
+| `mcpx prompt`                       | List all prompts across servers   |
+| `mcpx prompt <server>`              | List prompts for a server         |
+| `mcpx prompt <server> <name> '<json>'` | Get a specific prompt          |
+| `mcpx exec <server> <tool> --no-wait` | Execute as async task, return handle |
+| `mcpx exec <server> <tool> --ttl <ms>` | Set task TTL (default: 60000) |
+| `mcpx -N exec <server> <tool> ...`  | Decline elicitation (non-interactive) |
+| `mcpx task list <server>`            | List tasks on a server          |
+| `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           |

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Evan Tahler
+
+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.