金大哥 - pare MCP 详情

article

README

🚀 Pare

Pare为AI智能体提供可靠、结构化的命令行界面（CLI）输出，避免再解析脆弱的终端文本。

🚀 快速开始

快速设置：

# 1. 配置MCP服务器（非交互式）
npx @paretools/init --client claude-code --preset web

# 2. 向项目添加智能体规则
#    （追加到现有的CLAUDE.md，若为新文件则复制）
cat node_modules/@paretools/init/rules/CLAUDE.md >> CLAUDE.md

# 3. 重启客户端会话

# 4. 验证
npx @paretools/doctor

可用预设：web、python、rust、go、jvm、dotnet、ruby、swift、mobile、devops、full

各客户端的设置指南

| | | | | -------------------------------------------- | ------------------------------------------------ | ----------------------------------------- | | Claude Code | Claude Desktop | Cursor | | VS Code / Copilot | Windsurf | Cline / Roo Code | | OpenAI Codex | Gemini CLI | Zed | | Continue.dev | | |

完整快速入门指南 — 预设、生态系统映射、验证

手动配置 — 所有客户端的配置路径和格式

智能体集成指南 — 规则文件、钩子、CLI到MCP的映射

✨ 主要特性

提供 MCP 服务器，包装常见开发工具（git、npm、docker、测试运行器等），返回干净、经过模式验证的JSON，而非原始终端文本。
消除因解析CLI输出而产生的错误，无论平台、工具版本或语言环境如何，都能返回具有一致字段名的模式验证JSON。
结构化输出显著减少了智能体每次工具调用使用的令牌数量。

📦 安装指南

文档未提及具体的安装步骤，可参考快速开始部分进行配置。

💻 使用示例

基础用法

以 git status 为例：

原始git输出（约118个令牌）：

On branch main
Your branch is ahead of 'origin/main' by 2 commits.
  (use "git push" to publish your local commits)

Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        modified:   src/index.ts
        new file:   src/utils.ts

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   README.md

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        temp.log

Pare结构化输出（约59个令牌）：

{
  "branch": "main",
  "upstream": "origin/main",
  "ahead": 2,
  "staged": [
    { "file": "src/index.ts", "status": "modified" },
    { "file": "src/utils.ts", "status": "added" }
  ],
  "modified": ["README.md"],
  "deleted": [],
  "untracked": ["temp.log"],
  "conflicts": [],
  "clean": false
}

相比之下，令牌减少了50%，且无信息丢失，数据完全类型化。随着输出详细程度的增加，节省的效果更加明显，测试运行器和构建日志可减少80 - 92%。

📚 详细文档

可用服务器（28个包，240个工具）

仅安装与你的技术栈相关的服务器，大多数项目只需要2 - 4个。完整的目录涵盖了广泛的生态系统，因此Pare可以在任何环境中使用。

| 类别 | 服务器 | 工具数量 | 包装的工具 | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----: | -------------------------------------------------------------------------- | | 版本控制 | git, github | 55 | git, gh | | 语言与包管理 | npm, python, cargo, go, deno, bun, nix, dotnet, ruby, swift, jvm | 101 | npm, pip, cargo, go, deno, bun, nix, dotnet, gem, swift, gradle, maven | | 构建、代码检查与测试 | build, lint, test, cmake, bazel | 23 | tsc, esbuild, vite, webpack, eslint, prettier, biome, vitest, pytest, jest | | 基础设施 | docker, k8s, infra, security, remote | 40 | docker, kubectl, helm, terraform, ansible, trivy, ssh | | 实用工具 | search, http, make, process, db | 21 | ripgrep, fd, curl, make, just, psql, mysql, redis, mongosh |

工具模式 — 每个工具的详细响应示例和字段描述。另请参阅 工具响应示例 以获取快速JSON示例。

配置

工具选择

默认情况下，每个Pare服务器会注册其所有工具。如果你不需要某些服务器的工具，或者想限制智能体可用的工具，可以使用环境变量进行过滤。

按服务器过滤 — 限制单个服务器的工具：

# 仅在git服务器中注册status和log工具
PARE_GIT_TOOLS=status,log npx @paretools/git

通用过滤 — 限制所有服务器的工具：

# 仅在任何服务器中注册这些特定工具
PARE_TOOLS=git:status,git:log,npm:install npx @paretools/git

禁用所有工具 — 将环境变量设置为空字符串：

PARE_GIT_TOOLS= npx @paretools/git   # 不注册任何工具

| 环境变量 | 作用范围 | 格式 | 示例 | | --------------------- | ----------- | ----------------- | ------------------------ | | PARE_TOOLS | 所有服务器 | server:tool,... | git:status,npm:install | | PARE_{SERVER}_TOOLS | 单个服务器 | tool,... | status,log,diff |

规则：

无环境变量 = 启用所有工具（默认）
PARE_TOOLS（通用）优先于按服务器设置的变量
服务器名称使用大写，连字符替换为下划线（例如，PARE_MY_SERVER_TOOLS）
逗号周围的空格会被忽略

常见模式：

# 只读git（无push、commit、add、checkout）
PARE_GIT_TOOLS=status,log,diff,branch,show

# 最小化npm
PARE_NPM_TOOLS=install,test,run

# 仅在所有服务器中使用特定工具
PARE_TOOLS=git:status,git:diff,npm:install,test:run

在JSON MCP配置中，通过 env 键进行设置：

{
  "mcpServers": {
    "pare-git": {
      "command": "npx",
      "args": ["-y", "@paretools/git"],
      "env": {
        "PARE_GIT_TOOLS": "status,log,diff,show"
      }
    }
  }
}

故障排除

| 问题 | 解决方案 | | ----------------------------------- | --------------------------------------------------------------------------------------------------- | | npx 未找到 / Windows上的ENOENT错误 | 使用 cmd /c npx 包装器（请参阅客户端设置指南） | | 首次启动缓慢 | 运行 npx -y @paretools/git 一次以进行缓存，或全局安装：npm i -g @paretools/git | | Node.js版本错误 | Pare需要Node.js >= 20 | | NVM/fnm PATH问题 | 使用 npx 的绝对路径：例如，~/.nvm/versions/node/v22/bin/npx | | MCP连接超时 | 为Claude Code设置 MCP_TIMEOUT=30000，或在客户端配置中增加 initTimeout | | 太多工具占用上下文 | 使用工具选择环境变量限制工具，或仅安装所需的服务器 |

🔧 技术细节

每个Pare工具返回两个输出：

content — 供MCP客户端显示的人类可读文本。
structuredContent — 类型化、经过模式验证的JSON，可供智能体直接处理。

这利用了MCP的 structuredContent 和 outputSchema 特性，提供类型安全、经过验证的数据，智能体无需自定义解析即可依赖这些数据。

📄 许可证

MIT

贡献

每个服务器都是一个独立的包。完整指南请参阅 CONTRIBUTING.md。

pare