内容
mcpx
MCP 服务器的命令行界面。**MCP 的 curl。**
网络上关于 CLI 与 MCP 的争论就像是在讨论竞争对手。[但它们并不是竞争对手。](https://arcade.dev/blog/curl-for-mcp)
有三类用户：
1. **编码代理**（如 Claude Code、Cursor），它们更喜欢使用 shell 而不是维护持久的 MCP 连接 — 这样更利于令牌管理、渐进式工具发现以及在单台机器上跨多个代理共享一个 MCP 服务器池
2. **非编码代理**，它们需要从 TypeScript 以编程方式访问 MCP 工具 — 远程、持久或隔离的代理，没有 shell
3. **MCP 开发者**，他们需要一种快速的方法来发现、调试和测试他们的终端服务器
## 安装
```bash
# 通过 bun（所有平台）
bun install -g @arcadeai/mcpx
# 通过 curl（macOS/Linux）
curl -fsSL https://raw.githubusercontent.com/arcadeai-labs/mcpx/main/install.sh | bash
```
```powershell
# 通过 PowerShell（Windows）
irm https://raw.githubusercontent.com/arcadeai-labs/mcpx/main/install.ps1 | iex
```
curl/PowerShell 安装程序下载预编译的二进制文件 — 不需要运行时。bun 安装方法需要 [Bun](https://bun.sh)。所有平台的二进制文件都可在 [GitHub Releases](https://github.com/arcadeai-labs/mcpx/releases) 页面上找到。
## 快速入门
```bash
# 添加 GitHub MCP 服务器
mcpx add github --url https://mcp.github.com
# 列出所有服务器和工具
mcpx
# 列出带有描述的工具
mcpx -d
# 检查服务器
mcpx info github
# 检查特定工具
mcpx info github search_repositories
# 执行工具（JSON 参数）
mc github search_repositories": "mcp server"}'
# 使用 shell 风格执行工具（ `--之后的参数会根据工具的输入模式进行解析）
mcpx exec github search_repositories -- --query "mcp server 在不指定服务器的情况下执行工具（自动解析）
exec search_repositories '{" "mcp servermcpx exec search_re --query "m"
# 搜索工具 — 结合关键词和语义mcpx search "post linear"
# 仅关键词/通配符搜索（快速，无嵌入）
mcpx search -k "*file*"
# 仅语义搜索
search -q " requests"
# 数量（默认：10）
mcpx search -n "manage pull requests"
```
## 命令
| 命令 | 描述 |
| -------------------------------------- | ------------------------------------------------------ |
| `mcpx` | 列出所有已配置的工具 |
| ` servers` | 列配置的服务器（类型、详细信息） `mcpx info>` | 服务器概述、功能、工具 |
| `mcserver> < | 显示工具模式| `mcpx search>` | 关键词 + 语义） |
| ` search -k <pattern | 仅关键词配符搜索 |
mcpx search -query>` | 仅语义搜索 |
| `mcpx search -n <number> <query>` | 限制结果数量（默认：10） |
| `mcpx index` | 构建/重建搜索索引 |
| `mcpx index -i` | 显示索引状态 |
| `mcpx exec <server> <tool> [json]` | 验证输入本地，然后执行工具 |
| `mcpx exec <tool> [ | 执行工具，则自动解析服务器） |
| `mcpx exec <server> <tool> -- --k=v` | Shell 标志参数（通过工具的输入模式键入） |
| `mcpx exec <server> <tool> -f file` | 从 JSON 文件中读取工具 |
| `mcpx exec <server>` | 列出服务器上可 |
| `mc <server>` MCP 服务器进行身份验证（OAuth） |
| `mcpx auth <server> -s` | 检查身份验证状态和令 |
| `mcpx auth <server> -r` | 强制令牌刷新 |
| `mcpx deauth <server>` | 删除服务器的存储身份验证 |
| `mcpx add <name> --command <cmd>` | 将 stdio MCP 服务器添加到您的配置 |
| `mcpx add [name] --url <url>` | 添加 HTTP MCP 服务器（如果省略，则从 URL 中派生名称） |
| `mcpx remove <name>` | 从您的配置中删除 MCP 服务器 |
| `mcpx ping` | 检查所有已配置服务器的连接 |
| `mcpx ping <server> [server2...]` | 检查特定服务器的连接 |
| `mcpx skill install --claude` | 为 Claude Code 安装 mcpx 技能 |
| `mcpx skill install --cursor` | 为 Cursor 安装 mcpx 规则 |
| `mcpx resource` | 列出所有服务器上的所有资源 |
| `mcpx resource <server>` | 列出服务器的资源 |
| `mcpx resource <server> <uri>` | 读取特定资源 |
| `mcpx prompt` | 列出所有服务器上的所有提示 |
| `mcpx prompt <server>` | 列出服务器的提示 |
| `mcpx prompt <server> <name> [json]` | 获取特定提示 |
| `mcpx exec [server] <tool> --no-wait` | 以异步任务执行，立即返回任务句柄 |
| `mcpx exec [server] <tool> --ttl <ms>` | 设置任务 TTL（毫秒）（默认：60000） |
| `mcpx task list <server>` | 列出服务器上的任务 |
| `mcpx task get <server> <taskId>` | 获取任务状态 |
| `mcpx task result <server> <taskId>` | 检索已完成的任务结果 |
| `mcpx task cancel <server> <taskId>` | 取消正在运行的任务 |
| `mcpx allow <server>` | 允许代理在服务器上执行所有工具 |
| `mcpx allow <server> <tools...>` | 仅允许特定工具 |
| `mcpx allow --all` | 允许所有 mcpx 执行调用 |
| `mcpx allow --all-read` | 允许只读命令（搜索、信息、列表等） |
| `mcpx allow --list` | 显示当前的 mcpx 相关权限 |
| `mcpx allow --cursor <server>` | 为 Cursor 而不是 Claude Code 启用 |
| `mcpx deny <server>` | 删除服务器的权限 |
| `mcpx deny --all` | 删除所有 mcpx 相关权限 |
| `mcpx check-update` | 检查 mcpx 的新版本 |
| `mcpx upgrade` | 升级到最新的 mcpx 版本 |
## 选项
| 标志 | 目的 |
| ------------------------- | -------------------------------------------------------- |
| `-h, --help` | 显示帮助 |
| `-V, --version` | 显示版本 |
| `-d, --with-descriptions` | 在列表输出中包含工具描述 |
| `-c, --config <path>` | 指定配置文件位置 |
| `-v, --verbose` | 显示 HTTP 详细信息和 JSON-RPC 协议消息 |
| `-S, --show-secrets` | 在详细输出中显示完整的身份验证令牌（不掩码） |
| `-j, --json` | 强制 JSON 输出（默认情况下管道输出） |
| `-F, --format <format>` | 输出格式：`json` 或 `markdown` |
| `-N, --no-interactive` | 拒绝服务器的请求（用于脚本使用） |
| `--no-color` | 禁用输出中的 ANSI 颜色 |
| `--force-color` | 强制即使在管道输出时也启用 ANSI 颜色 |
| `-l, --log-level <level>` | 要显示的最低服务器日志级别（默认：`warning`） |
### 输出和颜色
mcpx 会自动检测 stdout/stderr 是否为交互式并进行适配：
- TTY → 彩色、格式化输出（表格、标题、徽章）。
- 非 TTY/管道输出 → JSON。
颜色输出遵循标准环境变量和匹配的标志：
- `NO_COLOR=1` 或 `--no-color` — 禁用 ANSI 颜色。
- `FORCE_COLOR=1` 或 `--force-color` — 启用 ANSI 颜色，即使在管道输出时。
- `--json` / `-j` — JSON 输出，无颜色。
- `CI=true` — 视为非交互式（关闭加载动画）。
服务器日志消息（`notifications/message`）会显示在 stderr 中，并根据日志级别进行颜色编码。有效级别（按严重性递增）：`debug`、`info`、`notice`、`warning`、`error`、`critical`、`alert`、`emergency`。当服务器声明日志记录能力时，mcpx 会发送 `logging/setLevel` 以请求达到配置阈值及以上的消息。
## 管理服务器
通过 CLI 添加和删除服务器 — 无需手动编辑 JSON。
```bash
# 添加 stdio 服务器（ `--` 之后的参数将逐字传递给命令）
mcpx add filesystem --command npx -- -y @modelcontextprotocol/server-filesystem /tmp
# 等效形式：可重复的 `--args`，或单个逗号分隔的 `--args`
mcpx add filesystem --command npx --args -y --args @modelcontextprotocol/server-filesystem --args /tmp
mcpx add filesystem --command npx --args "-y,@modelcontextprotocol/server-filesystem,/tmp"
# 添加带有头的 HTTP 服务器
mcpx add my-api --url https://api.example.com/mcp --header "Authorization:Bearer tok123"
# 使用 `--url` 时，名称是可选的 — 从 URL 的最后一个路径段派生（如果没有，则使用主机名）。
# 以下示例存储在名为“evan-coding”的服务器下。
mcpx add --url https://api.arcade.dev/mcp/evan-coding
# 添加工具过滤（可重复，或逗号分隔）
mcpx add github --url https://mcp.github.com --allowed-tools "search_*" --allowed-tools "get_*"
# 添加旧版 SSE 服务器（显式传输）
mcpx add legacy-api --url https://api.example.com/sse --transport sse
# 添加环境变量（可重复，或逗号分隔）
mcpx add my-server --command node --args server.js --env API_KEY=sk-123 --env DEBUG=true
# 覆盖现有服务器
mcpx add filesystem --command echo --force
# 删除服务器（也清理 auth.json）
mcpx remove filesystem
# 删除但保留存储的身份验证凭据
mcpx remove my-api --keep-auth
# 预览将要删除的内容
mcpx remove my-api --dry-run
```
**`add` 选项：**
| 标志 | 目的 |
| -------------------------- | ---------------------------------------------------------------------- |
| `--command <cmd>` | 命令（stdio 服务器） |
| `--args <arg>` | 命令的参数。可重复，或逗号分隔。 `--` 之后的参数也将追加（仅限stdio）。 |
| `--env <KEY=VAL>` | 环境变量。可重复，或逗号分隔。 |
| `--cwd <dir>` | 命令的工作目录 |
| `--url <url>` | 服务器 URL（HTTP 服务器） |
| `--header <Key:Value>` | HTTP 头。可重复。 |
| `--transport <type>` | 传输：`sse` 或 `streamable-http` |
| `--allowed-tools <pat>` | 允许的工具模式。可重复，或逗号分隔。 |
| `--disabled-tools <pat>` | 禁用的工具模式。可重复，或逗号分隔。 |
| `-f, --force` | 如果服务器已存在，则覆盖 |
| `--no-auth` | 跳过添加后的自动 OAuth |
| `--no-index` | 跳过重建搜索索引 |
**`remove` 选项：**
| 标志 | 目的 |
| ------------- | ------------------------------------------------- |
| `--keep-auth` | 不删除存储的身份验证凭据 |
| `--dry-run` | 显示将要删除的内容而不更改文件 |
## 配置
配置存储在 `~/.mcpx/`（或当前目录）。三个文件：
### `servers.json` — MCP 服务器定义
标准 MCP 服务器配置格式。支持 stdio 和 HTTP 服务器。
```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}" }
},
"legacy-sse": {
"url": "https://legacy.example.com/sse",
"transport": "sse"
}
}
}
```
**stdio 服务器** — `command` + `args`，作为子进程启动
**HTTP 服务器** — `url`，带有可选的静态 `headers` 用于预共享令牌。OAuth 通过 `.well-known/oauth-authorization-server` 在连接时自动发现 — 无需配置。默认情况下，mcpx 尝试 Streamable HTTP 并在服务器不支持时自动回退到旧版 SSE。transport": "sse"` 或 `"transport": "streamable-http"` 以跳过自动检测。
环境变量通过 `${VAR 语法插值。设置 `MCP_ENV=false` 以警告而不是错误处理缺少的变量。
**工具过滤：**
- `allowedTools` — 允许的工具模式（白名单）
- `disabledTools` — 禁用的工具模式（黑名单，优先级更高）
### `auth.json` — OAuth 令牌存储（自动管理）
存储 HTTP MCP 服务器的 OAuth 令牌。您不能直接编辑此文件 — 自动管理。
```json
{
"github": {
"access_token": "gho_ "refresh_tokenghr_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"
}
}
```
令牌在过期时自动刷新（如果有刷新令牌）。任何连接到服务器的命令（`exec`、`info`、`search`，列出）都将在透明地刷新令牌。`mcpx auth <server> --status` 显示当前令牌状态和 TTL。
### `search.json` — 搜索索引（自动
包含每个发现的工具和元数据用于语义搜索。通过 `mcpx index` 构建并自动保持最新 — `mcpx`（默认列表）和 `mcpx index --status` 已经获取每个服务器的实时工具，因此在后台更改/删除的工具并重新索引服务器。
{
"1,
"indexed_at": "2026-03-03T10:00:00Z",
"embedding_model": "Xenova/bge-small-en-v1.5",
"tools": [
{
"server": "linear",
"tool": "createIssue",
"description": "在 Linear 中创建新问题",
"input_schema": { "..." },
"scenarios": ["在 Linear 中创建新问题", "create issue"],
"keywords": ["create", "issue"],
"embedding": [0.012, -0.034, "..."]
}
]
}
```
每个工具都有：
- **scenarios** — 工具描述加上从工具名称派生的关键词短语
- **keywords** — 通过在 `_`、`-` 和 camelCase 边界上拆分工具名称提取的术语
- **embedding** — 384 维向量用于余弦相似性搜索
情景和关键词从工具名称和描述中启发式地提取。嵌入使用 `Xenova/bge-small-en-v1.5` 在进程中生成（~33MB ONNX 模型，首次）。不需要 API。
## 配置解析顺序
1. `MCP_CONFIG_PATH` 环境变量
2. `-c / --config` 标志
3. `./servers.json`（当前目录）
4. `~/.mcpx/servers.json`
## 环境变量
| 变量 | 目的 | 默认值 |
| ----------------- | --------------------------- | ---------- |
| `MCP_CONFIG_PATH` | 配置目录路径 | `~/.mcpx/` |
| `MCP_DEBUG` |调试输出 ` |
MCP_TIMEOUT 请求超时 | ` |
MCP_CONC | 并行服务器连接 | `5`| `M_RETRIES` | 重试尝试 | `3` |
| `MCP_STRICT_ENV` | 错误时缺少 `${VAR}` | `true` |
## OAuth 流
适用于需要 OAuth 的 HTTP MCP 服务器：
```bash
# 启动 OAuth 流 — 打开浏览器进行访问
mcpx auth github
# 检查令牌状态
mcpx auth github -s
# => github: authenticated (expires in 47m)
# 强制重新身份验证
mcpx auth github -r
# 不重建搜索索引进行身份验证
mcpx auth github --no-index
```
OAuth 流：
1. 通过 `/.well-known/oauth-authorization-server` 发现服务器的 OAuth 元数据
2. 启动本地回调服务器以获取授权码
3. 打开浏览器进行用户授权
4. 交换授权码以获取令牌
5. 将令牌存储在 `auth.json` 中
6. 在后续任何命令上自动刷新令牌
## 搜索
`mcpx search` 是一个将关键词匹配和语义向量搜索相结合的单一命令。默认情况下，两种策略都会运行，结果会被合并。
```bash
# 综合搜索（默认）— 关键词命中 + 语义匹配，合并和排名
mcpx search "send a message to slack"
# => slack/postMessage (0.94) 向频道发送消息
# => slack/sendDirectMessage (0.87) 向用户发送直接消息
# => teams/sendMessage (0.72) 发送 Teams 消息
# 仅关键词 — 快速 glob 匹配工具名称、描述和关键词
mcpx search -k "*pull*request*"
# => github/createPullRequest
# => github/getPullRequest
# => github/mergePullRequest
# 仅语义 — 意图向量相似性
mcpx search -q "review someone's code changes"
# => github/submitPullRequestReview (0.91) 提交 PR 审查
# => github/getPullRequest (0.85) 获取 PR 详情
# => github/listPullRequestCommits (0.78) 列出 PR 中的提交
```
综合搜索流程：
1. **关键词匹配** — glob/子字符串匹配工具名称、描述和索引关键词
2. **语义匹配** — 嵌入查询，余弦相似性对抗工具嵌入
3. **合并和排名** — 组合两个结果集，去除重复，按分数排序
4. **返回** — 返回顶部结果及其相似性分数
索引会增量更新 — 只有新的或更改的工具会被重新索引。第一次运行会索引所有内容；后续运行速度很快。
## 任务（异步工具执行）
MCP 服务器可以声明支持 [任务](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/tasks) — 长运行操作，返回任务句柄而不是阻塞直到完成。当工具支持任务时（`execution.taskSupport: "optional"` 或 `"required"`），mcpx 会自动使用任务增强执行。
```bash
# 默认：等待任务完成，显示进度更新
mcpx exec my-server long_running_tool '{"input": "data"}'
# 立即返回任务句柄（适用于脚本）
mcpx exec my-server long_running_tool '{"input": "data"}' --no-wait
# => 任务已创建：task-abc123（状态：working）
# 检查任务状态
mcpx task get my-server task-abc123
# 在任务完成后检索结果
mcpx task result my-server task-abc123
# 列出服务器上的所有任务
mcpx task list my-server
# 取消正在运行的任务
mcpx task cancel my-server task-abc123
```
对于不支持任务的工具，`exec` 的工作方式与以前完全相同 — 无需更改。
## 诱导（服务器请求的用戶輸入）
MCP 服务器可以通过 [诱导](https://modelcontextprotocol.io/specification/draft/client/elicitation) 在操作中途请求用戶輸入。mcpx 支持两种模式：
- **表单模式**：服务器发送一个 JSON 模式，描述输入字段（字符串、数字、布尔值、枚举、多选）。mcpx 在终端中渲染提示，并在返回之前验证输入。
- **URL 模式**：服务器发送一个 URL，供用戶访问（例如，用于身份验证或支付流程）。mcpx 在默认浏览器中打开它。
```bash
# 交互式 — 提示出现在终端中
mcpx exec my-server deploy_tool '{"target": "staging"}'
# 服务器请求输入：确认部署
# *确认 [y/n]: y
# 非交互式 — 拒绝所有诱导（适用于脚本/CI）
mcpx exec my-server deploy_tool '{"target": "staging"}' --no-interactive
# JSON 模式 — 诱导请求作为 JSON 写入 stdout，响应从 stdin 读取（用于编程处理）
echo '{"action":"accept","content":{"confirm":true}}' | \
mcpx exec my-server deploy_tool '{"target": "staging"}' --json
```
## 使用详细模式调试
`-v` 显示 HTTP 请求/响应详细信息（类似于 `curl -v`）和与服务器交换的 JSON-RPC 协议消息。所有调试输出都发送到 stderr，因此管道到 `jq` 仍然有效。
### JSON-RPC 协议跟踪
详细模式跟踪 JSON-RPC 消息的每个传输层 — 请求、响应和通知 — 用于 stdio 和 HTTP 服务器：
```bash
mcpx -v exec mock echo '{"message":"hello"}'
# → 初始化（id：0）
# ← 初始化（id：0）[45ms] — mock-server v1.0
# → notifications/initialized
# → tools/call（id：1）
# ← tools/call（id：1）[12ms] — ok
```
使用 `--json` 时，跟踪输出是 stderr 上的 NDJSON（每个消息一个 JSON 对象）：
```bash
mcpx -v -j exec mock echo '{"message":"hello"}' 2>trace.jsonl
```
### HTTP 流量
对于 HTTP/SSE 服务器，详细模式还显示原始 HTTP 头和计时：
```bash
mcpx -v exec 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": [ ... ] }
# 调试 stderr，输出 JSON
mcpx -v exec arcade Gmail_WhoAmI | jq .
# 显示完整的身份验证令牌（不掩盖）
mcpx -v -S exec arcade Gmail_WhoAmI
```
`>` / `<` 约定与 curl 匹配 — `>` 表示请求，`<` 表示响应。`→` / `←` 箭头显示 JSON-RPC 协议消息，包含方法名称、ID、往返计时和结果摘要。
## 输入验证
`mcpx exec` 在将参数发送到服务器之前在本地验证工具参数。MCP 工具会公布其输入的 JSON 模式 — mcpx 使用此模式快速捕获错误，而无需往返。
```bash
# 缺少必填字段 — 在发送前捕获
mcpx exec github create_issue '{"title": "bug"}'
# => 错误：缺少必填字段 "repo"（github/create_issue）
# 错误类型 — 在本地捕获
mcpx exec github create_issue '{"repo": "foo", "title": 123}'
# => 错误："title" 必须是字符串，得到数字（github/create_issue）
# 有效 — 发送到服务器
mcpx exec github create_issue '{"repo": "foo", "title": "bug"}'
# => { ... }
```
验证涵盖：
- **必填字段** — 如果缺少任何必填字段，则在发送前报错
- **类型检查** — 字符串、数字、布尔值、数组、对象
- **枚举值** — 拒绝不在允许集合中的值
- **嵌套对象** — 递归验证
如果工具的 `inputSchema` 不可用（某些服务器不提供），则执行会继续进行，没有本地验证。
### Shell 标志参数
`--` 分隔符之后的参数使用工具的输入模式进行类型强制。这对于交互式使用非常方便 — 您不需要记住 JSON 引号规则。
```bash
# JSON 形式
mcpx exec github create_issue '{"owner":"arcadeai-labs","repo":"mcpx","title":"bug"}'
# 等效的 shell 标志形式
mcpx exec github create_issue -- --owner arcadeai-labs --repo mcpx --title bug
# --field=value 也有效
mcpx exec github create_issue -- --owner=arcadeai-labs --repo=mcpx --title=bug
# 布尔值
mcpx exec my-server flagit -- --enabled # true
mcpx exec my-server flagit -- --no-enabled # false
# 数组 — 可重复的标志或逗号分隔
mcpx exec my-server tag -- --label bug --label todo
mcpx exec my-server tag -- --label bug,todo
```
类型强制遵循输入模式中的字段 `type`（`string`、`integer`、`number`、`boolean`、`array`）。嵌套对象必须使用 JSON 形式。组合 `--` shell 标志和内联 JSON 参数、`--file` 或 stdin 是不允许的。
## Shell 输出和管道
默认情况下，输出是人类友好的，管道输出是 JSON：
```bash
# 人类可读
mcpx info github
# JSON（管道）
mcpx info github | jq '.tools[].name'
# 强制 JSON
mcpx info github --json
```
### 输出格式 (`--format`)
工具结果（`exec`、`task result`）支持三种输出格式，通过全局 `--format` / `-F` 标志：
| 格式 | 描述 |
| ---------- | ----------------------------------------------------------------------- |
| `json` | 完整的 MCP 协议响应为 JSON（默认） |
| `text` | 从内容块中提取文本，剥离协议包装 |
| `markdown` | 提取文本并使用丰富的终端格式化（颜色、边框）渲染 |
```bash
# 默认 JSON 输出 — 完整的 MCP 响应，包含内容数组
mcpx exec github search_repositories '{"query":"mcp"}'
# Markdown — 丰富的终端渲染，包含颜色和格式化
mcpx exec github search_repositories '{"query":"mcp"}' -F markdown
```
`markdown` 格式从 MCP 内容块中提取文本，并通过 Bun 的内置 markdown 解析器渲染，带有 ANSI 样式 — 标题、粗体/斜体、带有边框的代码块、彩色链接和项目符号列表。JSON 内容被转换为具有标题和项目符号列表的结构化文档。
对于其他命令（`list`、`info`、`search`），`--format json` 强制 JSON 输出，`--format markdown` 使用现有的人类友好格式化。
### 链接工具结果
工具结果默认是 JSON，设计用于链接：
```bash
# 搜索仓库并读取第一个结果
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"}'
# 条件执行
mcpx exec filesystem list_directory '{"path":"."}' \
| jq -e '.content[0].text | contains("package.json")' \
&& mcpx exec filesystem read_file '{"path":"./package.json"}'
```
标准输入和文件输入适用于工具参数：
```bash
# 直接管道 JSON
echo '{"path":"./README.md"}' | mcpx exec filesystem read_file
# 管道来自文件
cat params.json | mcpx exec server tool
# Shell 重定向来自文件
mcpx exec server tool < params.json
# 使用 --file 标志从文件读取参数
mcpx exec filesystem read_file -f params.json
```
## 代理集成
### Claude 代码技能
mcpx 在 `.claude/skills/mcpx.md` 处提供了一个 Claude 代码技能，教导 Claude 代码如何发现和使用 MCP 工具。安装它：
```bash
# 安装到当前项目（.claude/skills/mcpx.md）
mcpx skill install --claude
# 全局安装（~/.claude/skills/mcpx.md）
mcpx skill install --claude --global
# 同时安装到两个位置
mcpx skill install --claude --global --project
# 覆盖现有的技能文件
mcpx skill install --claude --force
```
然后在任何 Claude 代码会话中，代理都可以使用 `/mcpx` 或技能触发器自动与外部服务交互。该技能指示代理：
1. **搜索** — `mcpx search "<intent>"` 查找相关工具
2. **检查** — `mcpx info <server> <tool>` 在调用前获取模式
3. **执行** — `mcpx exec <tool> '<json>'` 执行（或 `mcpx exec <server> <tool> '<json>'` 如果工具名称不明确）
这样，工具模式完全不会出现在系统提示中。代理按需发现所需内容，节省令牌和上下文窗口空间。
### 光标规则
mcpx 在 `.cursor/rules/mcpx.mdc` 处提供了一个光标规则，教导光标如何发现和使用 MCP 工具。安装它：
```bash
# 安装到当前项目（.cursor/rules/mcpx.mdc）
mcpx skill install --cursor
# 全局安装（~/.cursor/rules/mcpx.mdc）
mcpx skill install --cursor --global
# 同时安装 Claude 和 Cursor
mcpx skill install --claude --cursor
# 覆盖现有的规则文件
mcpx skill install --cursor --force
```
### 原始系统提示（其他代理）
对于非 Claude 代码代理，请在系统提示中添加以下内容：
```
您可以通过 `mcpx` CLI 访问 MCP 工具。
要发现工具：
mcpx search "<您要执行的操作>" # 组合关键词 + 语义
mcpx search -k "<模式>" # 仅关键词/通配符
mcpx info <服务器> <工具> # 工具模式
要执行工具：
mcpx exec <工具> '<json 参数>' # 服务器自动解析
mcpx exec <服务器> <工具> '<json 参数>' # 显式服务器
mcpx exec <服务器> <工具> -- --k=v # shell 标志参数（通过模式键入）
mcpx exec <服务器> <工具> -f params.json
在执行前始终搜索 — 不要假设工具名称。
```
### 编程用法（TypeScript SDK）
对于没有 shell 访问权限的代理 — 远程、持久或在 TypeScript 中运行的隔离代理：
```typescript
import { McpxClient } from "@arcadeai/mcpx";
const client = new McpxClient();
// 或：new McpxClient({ configDir: "/path/to/.mcpx" })
// 或：new McpxClient({ servers: { mcpServers: { ... } } })
// 1. 搜索工具
const results = await client.search("send a message");
// 2. 检查工具模式
const tool = await client.info("arcade", "Slack_SendMessage");
// 3. 执行工具
const result = await client.exec("arcade", "Slack_SendMessage", {
channel: "#general",
message: "hello",
});
// 还可用：listTools、listResources、readResource、
// listPrompts、getPrompt、listTasks、getTask、cancelTask、
// getServerInfo、getServerNames、validateToolInput
await client.close();
```
SDK 使用与 CLI 相同的配置文件（`~/.mcpx/servers.json`、`auth.json`、`search.json`）。服务器管理（添加、删除、身份验证）通过 CLI 进行 — SDK 仅限读取。
您也可以直接传递服务器配置，完全绕过文件加载：
```typescript
const client = new McpxClient({
servers: {
mcpServers: {
local: { command: "node", args: ["server.js"] },
remote: { url: "https://mcp.example.com" },
},
},
});
```
#### 工具元数据
`info()` 和 `listTools()` 返回原始的 MCP `Tool`，因此您可以获得服务器声明的所有内容：`name`、`title`、`description`、`inputSchema`、`outputSchema`、`execution.taskSupport` 和 `annotations`。`annotations` 对象承载 MCP 行为提示：
```typescript
const tool = await client.info("github", "delete_repo");
tool?.annotations; // { title?, readOnlyHint?, destructiveHint?, idempotentHint?, openWorldHint? }
```
> ⚠️ 注释是**不受信任的提示** — 根据 MCP 规范，客户端永远不应根据来自不受信任服务器的注释做出工具使用决策。请将下面的批准门槛视为一道防护栏，而不是安全边界。
#### 人机审批门槛
由于 SDK 以非交互方式运行，mcpx 无法提示人类本身 — 相反，您需要提供一个审批回调和一个用于控制哪些工具需要审批的策略。这样，您可以在执行某些**开放世界可写**工具（`openWorldHint: true` 且 `readOnlyHint`）之前要求审批：
```typescript
import { McpxClient, ToolApprovalDeniedError } from "@arcadeai/mcpx";
const client = new McpxClient({
servers: { mcpServers: { github: { url: "https://mcp.github.com" } } },
approvalPolicy: "open-world-writeable", // 默认是 "none"
onApprovalRequired: async ({ server, tool, args, annotations, reason }) => {
// 提示人类，调用审批服务，检查策略等。
return await promptHuman(`Allow ${server}/${tool}? (${reason})`, args);
},
});
// 受限工具等待回调；返回 false 会抛出 ToolApprovalDeniedError。
// 如果工具被阻塞，但未提供 onApprovalRequired 回调，则 exec() 会抛出
// ToolApprovalRequiredError（失败关闭）。
await client.exec("github", "delete_repo", { repo: "old-thing" });
```
`approvalPolicy` 接受：
| 值 | 闸门 |
| ----------------------- | ---------------------------------------------------------------------------------- |
| `"none"` _(默认)_ | 什么也不做 — 现有行为，零开销 |
| `"open-world-writeable"`| 具有 `openWorldHint: true` 且没有 `readOnlyHint` 的工具（未注释的工具通过） |
| `"writeable"` | 任何未明确声明 `readOnlyHint: true` 的工具（也包括未注释的工具） |
| `"all"` | 每次 `exec()` 调用 |
| `(tool, server) => boolean` | 自定义谓词 |
| `Array<…>` | 任意上述组合，通过 OR 组合 |
辅助函数 `isOpenWorldWriteable(tool)` 和 `isWriteable(tool)` 被导出，用于构建自定义谓词，以及 `ToolAnnotations` 类型。`mcpx info <server> <tool>` 还在 CLI 中显示了这些提示。
**按名称阻止特定工具。** 注释集无法区分两个类似的工具 — “创建 PR”和“创建问题”工具看起来都是开放世界的写入。要阻止其中一个但不阻止另一个，请使用自定义谓词形式并匹配 `tool.name` （和 `server`）：
```typescript
const client = new McpxClient({
servers: { mcpServers: { github: { url: "https://mcp.github.com" } } },
// 仅为创建 PR 需要审批 — 问题创建运行自由。
approvalPolicy: (tool, server) => server === "github" && tool.name === "create_pull_request",
onApprovalRequired: async ({ server, tool, args }) => await promptHuman(`Allow ${server}/${tool}?`, args),
});
await client.exec("github", "create_pull_request", { ... }); // 等待审批
await client.exec("github", "create_issue", { ... }); // 立即运行，无需提示
```
确认确切的 `tool.name` — 它必须完全匹配，并且服务器对工具的命名方式不同（例如 `create_pull_request` 与 `github_create_pr`）：
```bash
mcpx search "open pull request" # 查找工具及其服务器
mcpx info github create_pull_request # 确认名称
```
要匹配一组工具，请使用正则表达式（`/pull_request|merge_pr/.test(tool.name)`）；要同时阻止 PR 工具和所有开放世界可写工具，请将它们与数组形式组合：`["open-world-writeable", (tool, server) => …]`。匹配 `tool.name` 是可靠的 — 与注释不同，后者是未经信任的服务器提供的提示。
## 权限（Claude Code 和 Cursor）
像 Claude Code 和 Cursor 这样的 AI 代理会提示用户批准每次 `mcpx exec` 调用。`mcpx allow` 和 `mcpx deny` 管理细粒度权限规则，允许代理在无需广泛访问权限的情况下自行授权使用特定工具。
**关键洞察：** 如果用户允许初始权限模式（安全 - 它只写入本地设置文件），则代理可以按需授予自己对特定工具的访问权限。这是一个选择加入的工作流 - 默认情况下，代理无法自行授权，并会提示用户进行每次 `mcpx exec` 调用。
```bash
# 允许服务器上的所有工具（Claude Code，默认）
mcpx allow github
# 允许 Cursor 而不是 Claude Code
mcpx allow github --cursor
# 只允许特定工具
mcpx allow github search_repositories get_file
# 允许只读命令（搜索、信息、列表、服务器、ping 等）
mcpx allow --all-read
# 允许所有 mcpx exec 调用
mcpx allow --all
# 显示所有范围内的当前权限
mcpx allow --list
mcpx allow --list --cursor
# 预览将要写入的内容
mcpx allow github --dry-run
# 撤销服务器的权限
mcpx deny github
# 撤销所有 mcpx 权限
mcpx deny --all
```
**目标标志** - 默认情况下，权限针对 Claude Code。使用 `--cursor` 而是针对 Cursor：
| 标志 | 模式前缀 | 设置文件 |
| ----------- | -------------- | ----------------------------------------------- |
| _(默认)_ | `Bash(…)` | `.claude/settings.local.json` 等 |
| `--cursor` | `Shell(…)` | `.cursor/cli.json`、`~/.cursor/cli-config.json` |
**作用域标志** 控制权限的写入位置：
| 标志 | Claude Code 文件 | Cursor 文件 | 默认 |
| ----------- | ----------------------------- | --------------------------- | ------- |
| `--local` | `.claude/settings.local.json` | `.cursor/cli.json` | ✓ |
| `--project` | `.claude/settings.json` | `.cursor/cli.json` | |
| `--global` | `~/.claude/settings.json` | `~/.cursor/cli-config.json` | |
**`allow` 选项：**
| 标志 | 目的 |
| ------------ | --------------------------------------------------- |
| `--all` | 允许所有 mcpx exec 调用 |
| `--all-read` | 允许只读命令（搜索、信息、列表等） |
| `--list` | 显示当前与 mcpx 相关的权限 |
| `--cursor` | 目标 Cursor 设置而不是 Claude Code |
| `--local` | 写入本地设置（默认） |
| `--project` | 写入项目设置（共享） |
| `--global` | 写入全局设置 |
| `--dry-run` | 显示模式而不写入 |
**`deny` 选项：**
| 标志 | 目的 |
| ------------ | --------------------------------------------- |
| `--all` | 删除所有与 mcpx 相关的权限 |
| `--all-read` | 删除只读命令权限 |
| `--cursor` | 目标 Cursor 设置而不是 Claude Code |
| `--local` | 写入本地设置（默认） |
| `--project` | 写入项目设置（共享） |
| `--global` | 写入全局设置 |
| `--dry-run` | 显示将被删除的内容 |
## 开发
```bash
# 安装依赖
bun install
# 在开发环境中运行
bun run dev
# 运行测试
bun test
# 构建单个二进制文件
bun run build
# 校验
bun lint
```
## 技术栈
| 层 | 选择 |
| ----------- | ----------------------------------------------------- |
| 运行环境 | Bun |
| 语言 | TypeScript |
| MCP 客户端 | `@modelcontextprotocol/sdk` |
| CLI 解析 | `commander` |
| 验证 | `ajv`（JSON 模式） |
| 嵌入式 | `@huggingface/transformers`（Xenova/bge-small-en-v1.5） |
## 灵感来源
灵感来自 Phil Schmid 的 [mcp-cli](https://github.com/philschmid/mcp-cli)，它完善了 shell 友好型 MCP 客户端的核心 DX。mcpx 在此基础上扩展，增加了对 HTTP 服务器的 OAuth 支持和语义化工具搜索。
## 为什么是 mcpx？
mcpx 是客户端。如果您需要服务器端 - 认证、治理和生产环境工具 - 请查看 [Arcade](https://arcade.dev)。
完整故事：[curl for MCP：为什么编码代理使用 CLI 更开心](https://arcade.dev/blog/curl-for-mcp)
## 许可证
MIT
连接信息
猜你喜欢
暂无推荐服务器