@evantahler/mcpcli 0.1.1

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.

package/README.md

@@ -0,0 +1,432 @@
+# mcpcli
+
+A command-line interface for MCP servers. **curl for MCP.**
+
+Two 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
+
+## Install
+
+```bash
+# Via bun
+bun install -g @evantahler/mcpcli
+
+# Via curl
+curl -fsSL https://raw.githubusercontent.com/evantahler/mcpcli/main/install.sh | bash
+```
+
+The curl installer downloads a pre-built binary — no runtime needed. The bun install method requires [Bun](https://bun.sh).
+
+## Quick Start
+
+```bash
+# List all servers and their tools
+mcpcli
+
+# List with descriptions
+mcpcli -d
+
+# Inspect a server
+mcpcli info github
+
+# Inspect a specific tool
+mcpcli info github/search_repositories
+
+# Call a tool
+mcpcli call github search_repositories '{"query": "mcp server"}'
+
+# Search tools — combines keyword and semantic matching
+mcpcli search "post a ticket to linear"
+
+# Search with only keyword/glob matching (fast, no embeddings)
+mcpcli search -k "*file*"
+
+# Search with only semantic matching
+mcpcli search -q "manage pull requests"
+```
+
+## Commands
+
+| Command                              | Description                                  |
+| ------------------------------------ | -------------------------------------------- |
+| `mcpcli`                             | List all configured servers and tools        |
+| `mcpcli info <server>`               | Show tools for a server                      |
+| `mcpcli info <server>/<tool>`        | Show tool schema                             |
+| `mcpcli search <query>`              | Search tools (keyword + semantic)            |
+| `mcpcli search -k <pattern>`         | Keyword/glob search only                     |
+| `mcpcli search -q <query>`           | Semantic search only                         |
+| `mcpcli index`                       | Build/rebuild the search index               |
+| `mcpcli index -i`                    | Show index status                            |
+| `mcpcli call <server> <tool> [json]` | Validate inputs locally, then execute tool   |
+| `mcpcli call <server>`               | List available tools for a server            |
+| `mcpcli auth <server>`               | Authenticate with an HTTP MCP server (OAuth) |
+| `mcpcli auth <server> -s`            | Check auth status and token TTL              |
+| `mcpcli auth <server> -r`            | Force token refresh                          |
+| `mcpcli deauth <server>`             | Remove stored authentication for a server    |
+
+## Options
+
+| Flag                      | Purpose                                            |
+| ------------------------- | -------------------------------------------------- |
+| `-h, --help`              | Show help                                          |
+| `-V, --version`           | Show version                                       |
+| `-d, --with-descriptions` | Include tool descriptions in list output           |
+| `-c, --config <path>`     | Specify config file location                       |
+| `-v, --verbose`           | Show HTTP request/response headers and timing      |
+| `-S, --show-secrets`      | Show full auth tokens in verbose output (unmasked) |
+| `-j, --json`              | Force JSON output (default when piped)             |
+| `--no-daemon`             | Disable connection pooling                         |
+
+## Configuration
+
+Config lives in `~/.config/mcpcli/` (or the current directory). Three files:
+
+### `servers.json` — MCP Server Definitions
+
+Standard MCP server config format. Supports both stdio and HTTP servers.
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
+      "env": { "API_KEY": "${API_KEY}" },
+      "allowedTools": ["read_file", "list_directory"],
+      "disabledTools": ["delete_file"]
+    },
+    "github": {
+      "url": "https://mcp.github.com"
+    },
+    "internal-api": {
+      "url": "https://mcp.internal.example.com",
+      "headers": { "Authorization": "Bearer ${TOKEN}" }
+    }
+  }
+}
+```
+
+**Stdio servers** — `command` + `args`, spawned as child processes
+**HTTP servers** — `url`, with optional static `headers` for pre-shared tokens. OAuth is auto-discovered at connection time via `.well-known/oauth-authorization-server` — no config needed.
+
+Environment variables are interpolated via `${VAR_NAME}` syntax. Set `MCP_STRICT_ENV=false` to warn instead of error on missing variables.
+
+**Tool filtering:**
+
+- `allowedTools` — glob patterns for tools to expose (whitelist)
+- `disabledTools` — glob patterns for tools to hide (blacklist, takes precedence)
+
+### `auth.json` — OAuth Token Storage (managed automatically)
+
+Stores OAuth tokens for HTTP MCP servers. You don't edit this directly — managed automatically.
+
+```json
+{
+  "github": {
+    "access_token": "gho_xxxx",
+    "refresh_token": "ghr_xxxx",
+    "expires_at": "2026-03-03T12:00:00Z",
+    "token_type": "bearer",
+    "scope": "repo,read:org"
+  },
+  "linear": {
+    "access_token": "lin_xxxx",
+    "refresh_token": "lin_ref_xxxx",
+    "expires_at": "2026-03-04T08:30:00Z",
+    "token_type": "bearer"
+  }
+}
+```
+
+Tokens are automatically refreshed when expired (if a refresh token is available). Any command that connects to a server (`call`, `info`, `search`, listing) will refresh tokens transparently. `mcpcli auth <server> --status` shows current token state and TTL.
+
+### `search.json` — Semantic Search Index (managed automatically)
+
+Contains every discovered tool with metadata for semantic search. Built and updated automatically — any command that connects to a server will detect new/changed tools and re-index them in the background.
+
+```json
+{
+  "version": 1,
+  "indexed_at": "2026-03-03T10:00:00Z",
+  "embedding_model": "Xenova/all-MiniLM-L6-v2",
+  "tools": [
+    {
+      "server": "linear",
+      "tool": "createIssue",
+      "description": "Create a new issue in Linear",
+      "input_schema": { "...": "..." },
+      "scenarios": ["Create a new issue in Linear", "create issue"],
+      "keywords": ["create", "issue"],
+      "embedding": [0.012, -0.034, "..."]
+    }
+  ]
+}
+```
+
+Each tool gets:
+
+- **scenarios** — the tool description plus a keyword phrase derived from the tool name
+- **keywords** — terms extracted by splitting the tool name on `_`, `-`, and camelCase boundaries
+- **embedding** — 384-dim vector for cosine similarity search
+
+Scenarios and keywords are extracted heuristically from tool names and descriptions. Embeddings are generated in-process using `Xenova/all-MiniLM-L6-v2` (~23MB ONNX model, downloaded on first run). No API keys needed.
+
+## Config Resolution Order
+
+1. `MCP_CONFIG_PATH` environment variable
+2. `-c / --config` flag
+3. `./servers.json` (current directory)
+4. `~/.config/mcpcli/servers.json`
+
+## Environment Variables
+
+| Variable             | Purpose                           | Default             |
+| -------------------- | --------------------------------- | ------------------- |
+| `MCP_CONFIG_PATH`    | Config directory path             | `~/.config/mcpcli/` |
+| `MCP_DEBUG`          | Enable debug output               | `false`             |
+| `MCP_TIMEOUT`        | Request timeout (seconds)         | `1800`              |
+| `MCP_CONCURRENCY`    | Parallel server connections       | `5`                 |
+| `MCP_MAX_RETRIES`    | Retry attempts                    | `3`                 |
+| `MCP_STRICT_ENV`     | Error on missing `${VAR}`         | `true`              |
+| `MCP_NO_DAEMON`      | Disable connection pooling        | `false`             |
+| `MCP_DAEMON_TIMEOUT` | Idle connection timeout (seconds) | `60`                |
+
+## Connection Pooling
+
+mcpcli runs a lightweight daemon that keeps MCP server connections warm. Stdio processes stay alive and HTTP connections are reused across invocations. The daemon exits after `MCP_DAEMON_TIMEOUT` seconds of inactivity (default 60s).
+
+Disable with `--no-daemon` or `MCP_NO_DAEMON=true` for one-shot usage.
+
+## OAuth Flow
+
+For HTTP MCP servers that require OAuth:
+
+```bash
+# Start the OAuth flow — opens browser for authorization
+mcpcli auth github
+
+# Check token status
+mcpcli auth github -s
+# => github: authenticated (expires in 47m)
+
+# Force re-authentication
+mcpcli auth github -r
+```
+
+The OAuth flow:
+
+1. Discovers the server's OAuth metadata via `/.well-known/oauth-authorization-server`
+2. Starts a local callback server on a random port
+3. Opens the browser for user authorization
+4. Exchanges the authorization code for tokens
+5. Stores tokens in `auth.json`
+6. Automatically refreshes tokens before they expire on any subsequent command
+
+## Search
+
+`mcpcli search` is a single command that combines keyword matching and semantic vector search. By default, both strategies run and results are merged.
+
+```bash
+# Combined search (default) — keyword hits + semantic matches, merged and ranked
+mcpcli search "send a message to slack"
+# => slack/postMessage          (0.94) Post a message to a channel
+# => slack/sendDirectMessage    (0.87) Send a DM to a user
+# => teams/sendMessage          (0.72) Send a Teams message
+
+# Keyword only — fast glob match against tool names, descriptions, and keywords
+mcpcli search -k "*pull*request*"
+# => github/createPullRequest
+# => github/getPullRequest
+# => github/mergePullRequest
+
+# Semantic only — vector similarity against intent
+mcpcli search -q "review someone's code changes"
+# => github/submitPullRequestReview  (0.91) Submit a PR review
+# => github/getPullRequest           (0.85) Get PR details
+# => github/listPullRequestCommits   (0.78) List commits in a PR
+```
+
+The combined search pipeline:
+
+1. **Keyword match** — glob/substring against tool names, descriptions, and indexed keywords
+2. **Semantic match** — embed the query, cosine similarity against tool embeddings
+3. **Merge & rank** — combine both result sets, deduplicate, sort by score
+4. **Return** — top results with similarity scores
+
+The index updates incrementally — only new or changed tools are re-indexed. The first run indexes everything; subsequent runs are fast.
+
+## Debugging with Verbose Mode
+
+`-v` shows HTTP request/response details, like `curl -v`. Debug output goes to stderr so piping to `jq` still works.
+
+```bash
+# See full HTTP traffic
+mcpcli -v call arcade Gmail_WhoAmI
+
+# > POST https://api.arcade.dev/mcp/evan-coding
+# > authorization: Bearer eyJhbGci...
+# > content-type: application/json
+# > accept: application/json, text/event-stream
+# >
+# {
+#   "method": "tools/call",
+#   "params": {
+#     "name": "Gmail_WhoAmI",
+#     "arguments": {}
+#   }
+# }
+# < 200 OK (142ms)
+# < content-type: application/json
+# < x-request-id: abc123
+# <
+# { "content": [ ... ] }
+
+# Debug on stderr, clean JSON on stdout
+mcpcli -v call arcade Gmail_WhoAmI | jq .
+
+# Show full auth tokens (unmasked)
+mcpcli -v -S call arcade Gmail_WhoAmI
+```
+
+The `>` / `<` convention matches curl — `>` for request, `<` for response. The JSON-RPC body is shown between the request headers and response, without a prefix. Timing is displayed on the response status line.
+
+## Input Validation
+
+`mcpcli call` validates tool arguments locally before sending them to the server. MCP tools advertise a JSON Schema for their inputs — mcpcli uses this to catch errors fast, without a round-trip.
+
+```bash
+# Missing required field — caught locally
+mcpcli call github create_issue '{"title": "bug"}'
+# => error: missing required field "repo" (github/create_issue)
+
+# Wrong type — caught locally
+mcpcli call github create_issue '{"repo": "foo", "title": 123}'
+# => error: "title" must be a string, got number (github/create_issue)
+
+# Valid — sent to server
+mcpcli call github create_issue '{"repo": "foo", "title": "bug"}'
+# => { ... }
+```
+
+Validation covers:
+
+- **Required fields** — errors before sending if any are missing
+- **Type checking** — string, number, boolean, array, object
+- **Enum values** — rejects values not in the allowed set
+- **Nested objects** — validates recursively
+
+If a tool's `inputSchema` is unavailable (some servers don't provide one), the call proceeds without local validation.
+
+## Shell Output & Piping
+
+Output is human-friendly by default, JSON when piped:
+
+```bash
+# Human-readable
+mcpcli info github
+
+# JSON (piped)
+mcpcli info github | jq '.tools[].name'
+
+# Force JSON
+mcpcli info github --json
+```
+
+Tool call results are always JSON, designed for chaining:
+
+```bash
+# Search repos and read the first result
+mcpcli call github search_repositories '{"query":"mcp"}' \
+  | jq -r '.content[0].text | fromjson | .items[0].full_name' \
+  | xargs -I {} mcpcli call github get_file_contents '{"owner":"{}","path":"README.md"}'
+
+# Conditional execution
+mcpcli call filesystem list_directory '{"path":"."}' \
+  | jq -e '.content[0].text | contains("package.json")' \
+  && mcpcli call filesystem read_file '{"path":"./package.json"}'
+```
+
+Stdin works for tool arguments:
+
+```bash
+echo '{"path":"./README.md"}' | mcpcli call filesystem read_file
+
+cat params.json | mcpcli call server tool
+```
+
+## Agent Integration
+
+### Claude Code Skill
+
+mcpcli ships a Claude Code skill at `skills/mcpcli.md` that teaches Claude Code how to discover and use MCP tools. Install it:
+
+```bash
+# Copy the skill to your global Claude Code skills
+cp skills/mcpcli.md ~/.claude/skills/mcpcli.md
+```
+
+Then in any Claude Code session, the agent can use `/mcpcli` or the skill triggers automatically when the agent needs to interact with external services. The skill instructs the agent to:
+
+1. **Search first** — `mcpcli search "<intent>"` to find relevant tools
+2. **Inspect** — `mcpcli info <server>/<tool>` to get the schema before calling
+3. **Call** — `mcpcli call <server> <tool> '<json>'` to execute
+
+This keeps tool schemas out of the system prompt entirely. The agent discovers what it needs on-demand, saving tokens and context window space.
+
+### Raw System Prompt (other agents)
+
+For non-Claude-Code agents, add this to the system prompt:
+
+```
+You have access to MCP tools via the `mcpcli` CLI.
+
+To discover tools:
+  mcpcli search "<what you want to do>"    # combined keyword + semantic
+  mcpcli search -k "<pattern>"             # keyword/glob only
+  mcpcli info <server>/<tool>              # tool schema
+
+To call tools:
+  mcpcli call <server> <tool> '<json args>'
+
+Always search before calling — don't assume tool names.
+```
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Run in development
+bun run dev
+
+# Run tests
+bun test
+
+# Build single binary
+bun run build
+
+# Lint
+bun lint
+```
+
+## Tech Stack
+
+| Layer       | Choice                                                |
+| ----------- | ----------------------------------------------------- |
+| Runtime     | Bun                                                   |
+| Language    | TypeScript                                            |
+| MCP Client  | `@modelcontextprotocol/sdk`                           |
+| CLI Parsing | `commander`                                           |
+| Validation  | `ajv` (JSON Schema)                                   |
+| Embeddings  | `@huggingface/transformers` (Xenova/all-MiniLM-L6-v2) |
+
+## Inspiration
+
+Inspired by [mcp-cli](https://github.com/philschmid/mcp-cli) by Phil Schmid, which nails the core DX of a shell-friendly MCP client. mcpcli extends that foundation with OAuth support for HTTP servers and semantic tool search.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@evantahler/mcpcli",
+  "version": "0.1.1",
+  "description": "A command-line interface for MCP servers. curl for MCP.",
+  "type": "module",
+  "bin": {
+    "mcpcli": "./src/cli.ts"
+  },
+  "files": [
+    "src",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "bun run src/cli.ts",
+    "test": "bun test",
+    "lint": "prettier --check .",
+    "format": "prettier --write .",
+    "build": "bun build --compile --minify --sourcemap ./src/cli.ts --outfile dist/mcpcli"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/evantahler/mcpcli.git"
+  },
+  "keywords": [
+    "mcp",
+    "cli",
+    "model-context-protocol",
+    "ai",
+    "llm",
+    "tools"
+  ],
+  "author": "Evan Tahler",
+  "license": "MIT",
+  "dependencies": {
+    "@huggingface/transformers": "^3.8.1",
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "ajv": "^8.18.0",
+    "ansis": "^4.2.0",
+    "commander": "^14.0.3",
+    "nanospinner": "^1.2.2",
+    "picomatch": "^4.0.3"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/picomatch": "^4.0.2",
+    "prettier": "^3.8.1"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}

package/skills/mcpcli.md

@@ -0,0 +1,85 @@
+---
+name: mcpcli
+description: Discover and use MCP tools via the mcpcli CLI
+trigger: when the user wants to interact with external services, APIs, or MCP tools
+---
+
+# mcpcli — MCP Tool Discovery and Execution
+
+You have access to external tools via `mcpcli`. Use this workflow:
+
+## 1. Search for tools
+
+```bash
+mcpcli search "<what you want to do>"
+```
+
+## 2. Inspect the tool schema
+
+```bash
+mcpcli call <server> <tool>
+```
+
+This shows parameters, types, required fields, and an example payload.
+
+## 3. Call the tool
+
+```bash
+mcpcli call <server> <tool> '<json args>'
+```
+
+## Rules
+
+- Always search before calling — don't assume tool names exist
+- Always inspect the schema before calling — validate you have the right arguments
+- Use `mcpcli search -k` for exact name matching
+- Pipe results through `jq` when you need to extract specific fields
+- Tool call results are always JSON with nested JSON strings auto-parsed
+- Use `-v` for verbose HTTP debugging if a call fails unexpectedly
+
+## Examples
+
+```bash
+# Find tools related to sending messages
+mcpcli search "send a message"
+
+# See what parameters Slack_SendMessage needs
+mcpcli call arcade Slack_SendMessage
+
+# Send a message
+mcpcli call arcade Slack_SendMessage '{"channel":"#general","message":"hello"}'
+
+# Chain commands — search repos and read the first result
+mcpcli call github search_repositories '{"query":"mcp"}' \
+  | jq -r '.content[0].text.items[0].full_name' \
+  | xargs -I {} mcpcli call github get_file_contents '{"owner":"{}","path":"README.md"}'
+
+# Read args from stdin
+echo '{"path":"./README.md"}' | mcpcli call filesystem read_file
+```
+
+## Authentication
+
+Some HTTP servers require OAuth. If you see an "Not authenticated" error:
+
+```bash
+mcpcli auth <server>        # authenticate via browser
+mcpcli auth <server> -s        # check token status
+mcpcli deauth <server>      # remove stored auth
+```
+
+## Available commands
+
+| Command                                | Purpose                            |
+| -------------------------------------- | ---------------------------------- |
+| `mcpcli`                               | List all servers and tools         |
+| `mcpcli -d`                            | List with descriptions             |
+| `mcpcli call <server>`                 | List tools for a server            |
+| `mcpcli call <server> <tool>`          | Show tool help and example payload |
+| `mcpcli call <server> <tool> '<json>'` | Execute a tool                     |
+| `mcpcli info <server>/<tool>`          | Show tool schema                   |
+| `mcpcli search "<query>"`              | Search tools                       |
+| `mcpcli search -k "<pattern>"`         | Keyword/glob search only           |
+| `mcpcli search -q "<query>"`           | Semantic search only               |
+| `mcpcli index`                         | Build/rebuild search index         |
+| `mcpcli auth <server>`                 | Authenticate with OAuth            |

package/src/cli.ts

@@ -0,0 +1,34 @@
+#!/usr/bin/env bun
+
+import { program } from "commander";
+import { registerListCommand } from "./commands/list.ts";
+import { registerInfoCommand } from "./commands/info.ts";
+import { registerSearchCommand } from "./commands/search.ts";
+import { registerCallCommand } from "./commands/call.ts";
+import { registerAuthCommand, registerDeauthCommand } from "./commands/auth.ts";
+import { registerIndexCommand } from "./commands/index.ts";
+
+declare const BUILD_VERSION: string | undefined;
+
+const version = typeof BUILD_VERSION !== "undefined" ? BUILD_VERSION : "0.1.0-dev";
+
+program
+  .name("mcpcli")
+  .description("A command-line interface for MCP servers. curl for MCP.")
+  .version(version)
+  .option("-c, --config <path>", "config directory path")
+  .option("-d, --with-descriptions", "include tool descriptions in output")
+  .option("-j, --json", "force JSON output")
+  .option("-v, --verbose", "show HTTP request/response details")
+  .option("-S, --show-secrets", "show full auth tokens in verbose output")
+  .option("--no-daemon", "disable connection pooling");
+
+registerListCommand(program);
+registerInfoCommand(program);
+registerSearchCommand(program);
+registerCallCommand(program);
+registerAuthCommand(program);
+registerDeauthCommand(program);
+registerIndexCommand(program);
+
+program.parse();