概述

Pare 是一个专为 AI 编码代理设计的 MCP（Model Context Protocol）服务器套件，通过包装常见命令行工具并返回结构化 JSON 输出，帮助代理更高效地与开发环境交互。

资料来源：README.md:1-50

核心价值主张

资料来源：packages/shared/CHANGELOG.md:1-30

架构设计

整体架构

graph TD
    subgraph "MCP 客户端"
        A[Claude Code]
        B[其他 AI Agent]
    end
    
    subgraph "Pare MCP 服务器"
        C[@paretools/git]
        D[@paretools/github]
        E[@paretools/npm]
        F[@paretools/test]
        G[@paretools/python]
        H[其他服务器...]
    end
    
    subgraph "底层 CLI 工具"
        I[git]
        J[gh]
        K[npm/pnpm]
        L[pytest]
    end
    
    A --> C
    A --> D
    A --> E
    B --> F
    B --> G
    
    C --> I
    D --> J
    E --> K
    F --> L

Pare 采用模块化服务器架构，每个服务器包负责一个工具领域。所有服务器共享 @paretools/shared 基础库，提供统一的运行机制、类型定义和工具函数。

资料来源：packages/shared/src/index.ts:1-100

服务器包生态

资料来源：packages/shared/CHANGELOG.md:50-80

核心特性

自动紧凑模式（Auto Compact Mode）

当结构化 JSON 输出超过原始 CLI token 计数时，Pare 自动应用紧凑投影策略：

graph LR
    A[JSON 输出] --> B{超过 Token 阈值?}
    B -->|是| C[应用紧凑投影]
    B -->|否| D[保持完整输出]
    C --> E[保留核心字段]
    C --> F[丢弃详细堆栈]
    C --> G[聚合统计信息]

紧凑模式保留的核心字段：

• error / success 状态
• 关键数值（如错误计数、通过/失败测试数）
• 文件路径摘要
• 首条错误信息

紧凑模式丢弃的内容：

• 完整堆栈跟踪
• 逐文件的详细统计
• 冗余的元数据

资料来源：packages/server-docker/CHANGELOG.md:20-40

安全加固

Pare 在 v0.3.0 版本引入了全面的安全改进：

新增安全工具函数：

• assertNoFlagInjection() - 验证参数不包含危险标志
• assertAllowedCommand() - 验证命令在白名单内

资料来源：packages/server-npm/CHANGELOG.md:15-25

跨平台兼容性

Pare 特别关注 Windows 平台的可靠性：

资料来源：packages/shared/CHANGELOG.md:30-50

工具映射表

pare-git 替代方案

使用 pare-git <子命令> 替代原始 git 命令：

资料来源：rules/GEMINI.md:1-30

pare-github 替代方案

资料来源：rules/GEMINI.md:30-60

Python 工具详解

解释器解析顺序

@paretools/python 包按照以下顺序查找 Python 解释器：

graph TD
    A[开始查找] --> B{显式指定 interpreter?}
    B -->|是| C[使用指定解释器]
    B -->|否| D{检测 .venv 目录?}
    D -->|是| E[使用 .venv/bin/python]
    D -->|否| F{检测 venv Scripts?}
    F -->|是| G[使用 venv/Scripts/python]
    F -->|否| H{python 命令存在?}
    H -->|是| I[使用 python]
    H -->|否| J[使用 python3]
    J -->|失败| K[报告错误]

支持的工具：

资料来源：packages/server-python/CHANGELOG.md:15-30

已知限制

在 Windows 系统上，当 Python 工具安装为 Python 模块（如 python -m pytest）而非独立脚本时，工具调用可能失败。

资料来源：社区问题 #891

配置与使用

环境变量配置

MCP 工具命名约定

所有工具遵循 mcp__pare-{package}__{tool} 命名规范：

mcp__pare-git__status
mcp__pare-github__pr-list
mcp__pare-python__pytest

资料来源：packages/server-docker/CHANGELOG.md:1-20

已知问题与限制

高优先级问题

嵌套 Git Worktree 问题

当从嵌套 worktree 调用 pare-git 工具且未指定 path 参数时，工作目录解析可能错误。解决方法是显式传递 path 参数。

资料来源：社区问题 #876

安全审计

Pare 已通过第三方安全审计：

详细审计报告： docs/security/audit-2026-02-12.md

资料来源：SECURITY.md:20-30

版本历史

相关链接

• GitHub 仓库: https://github.com/Dave-London/Pare
• MCP 官方注册: https://modelcontextprotocol.io/
• Smithery 注册: https://smithery.ai/protocol/@paretools

另请参阅

• 安全策略 - 漏洞报告流程和支持版本
• Gemini CLI 规则 - AI 代理使用指南
• @paretools/shared 包文档 - 核心共享库

快速入门指南

Pare 是一套基于 MCP（Model Context Protocol）的开发者工具集合，通过标准化的工具接口为 AI 编程助手提供对各类开发工具的访问能力。本指南将帮助您快速了解 Pare 的架构体系、安装配置方法以及核心使用模式。

项目概述

Pare 项目的核心目标是将常见的开发工具（如 Git、Docker、npm、Python 测试框架等）封装为 MCP 协议兼容的工具，使 AI 代理能够安全、可控地执行开发任务。根据 packages/shared/CHANGELOG.md 的记录，Pare 在 v0.7.0 版本已达到 100 个工具、14 个包 的规模，涵盖了代码管理、构建测试、容器操作等多个领域。

核心架构

Pare 采用工具包（Tool Suite）架构，每个工具包负责一个特定的开发领域。所有工具包统一发布在 @paretools npm 作用域下，确保版本一致性。以下是主要的工具包分类：

资料来源：packages/shared/CHANGELOG.md:1-30

MCP 协议集成

每个工具包都是一个独立的 MCP 服务器实现。根据 packages/shared/CHANGELOG.md 的 v0.3.0 更新记录，所有 9 个服务器均添加了 MCP instructions 字段，用于向 AI 客户端提供更好的工具使用指导。这一设计使得 AI 代理能够自动发现合适的工具并理解其正确的调用方式。

graph TD
    A[AI 代理] -->|MCP 协议| B[MCP 客户端]
    B --> C[@paretools/git]
    B --> D[@paretools/docker]
    B --> E[@paretools/npm]
    B --> F[其他工具包...]
    C --> G[git CLI]
    D --> H[docker CLI]
    E --> I[npm CLI]

安装配置

环境要求

Pare 工具包基于 Node.js 开发，需要确保目标机器满足以下条件：

• Node.js: v18.0.0 或更高版本
• 包管理器: pnpm（推荐）、npm 或 yarn
• 特定工具: 根据所使用的工具包，需要预装对应的 CLI 工具（如 git、docker、python3 等）

安装单个工具包

使用 pnpm 安装特定领域的工具包：

pnpm add @paretools/git
pnpm add @paretools/docker
pnpm add @paretools/npm

或安装所有工具包：

pnpm add @paretools/server-git @paretools/server-docker @paretools/server-npm @paretools/server-python

MCP 服务器配置

每个工具包需要单独配置为 MCP 服务器。根据 docs/setup/claude-code.md 和 docs/setup/cursor.md 的说明，不同的 AI 客户端有不同的配置方式。

#### Claude Code 配置

在 Claude Code 中使用 --mcp 标志启动工具包：

npx @paretools/git --port 3000
npx @paretools/docker --port 3001

资料来源：docs/setup/claude-code.md:1-20

#### Cursor 配置

Cursor IDE 支持通过 MCP 配置文件添加工具包：

{
  "mcpServers": {
    "pare-git": {
      "command": "npx",
      "args": ["@paretools/git"]
    },
    "pare-docker": {
      "command": "npx",
      "args": ["@paretools/docker"]
    }
  }
}

资料来源：docs/setup/cursor.md:1-25

初始化与预设配置

Pare 提供了初始化工具来简化项目配置。根据 packages/init/src/index.ts 的实现，初始化流程支持预设模板和自定义配置。

初始化流程

// packages/init/src/index.ts 中的核心逻辑
interface InitOptions {
  preset?: 'minimal' | 'full' | 'custom';
  workspace: string;
  tools?: string[];
}

初始化工具会根据用户选择的预设自动配置相应的工具包，并生成所需的配置文件。packages/init/src/lib/presets.ts 定义了预设模板的具体参数。

资料来源：packages/init/src/index.ts:1-50

预设模板

核心使用模式

路径参数

大多数 Pare 工具支持可选的 path 参数来指定工作目录。根据 packages/shared/CHANGELOG.md v0.20.0 的更新说明，当 path 参数省略时，仓库级别的工具将操作服务器当前的工作目录。

// 推荐：显式指定路径
{ path: "/path/to/repo" }

// 可选：使用当前工作目录
{ /* path 未指定 */ }

资料来源：packages/shared/CHANGELOG.md:1-10

紧凑输出模式

为减少 LLM 上下文中的 token 消耗，所有工具支持 compact 参数。紧凑模式会精简输出字段，移除冗余信息：

// 标准模式
{ "file": "src/index.ts", "status": "modified", "additions": 10, "deletions": 5, "message": "..." }

// 紧凑模式
{ "file": "src/index.ts", "status": "M", "+": 10, "-": 5 }

延迟工具加载

当环境变量 PARE_LAZY=true 时，Pare 采用延迟工具注册策略。根据 packages/server-db/CHANGELOG.md 的说明，核心工具在启动时加载，而扩展工具则按需加载。这一机制通过新增的 discover-tools 元工具实现。

常见问题与已知限制

已知的社区问题

根据 GitHub Issues 记录，以下是用户经常遇到的问题：

资料来源：GitHub Issues 社区上下文

安全考虑

根据 SECURITY.md 的安全政策，Pare 项目已进行安全审计：

• 2026 年 2 月审计：发现 18 个问题，其中 14 个已修复，4 个接受风险
• 参数注入防护：Git 参数和构建命令使用白名单验证
• 报告流程：请通过 GitHub 私有漏洞报告功能提交安全问题，切勿公开 issue

资料来源：SECURITY.md:1-30

Python 环境检测

根据 v0.20.0 的更新说明，Python 工具的解析器优先级为：

1. 显式指定的 interpreter 参数
2. 检测 .venv/ 虚拟环境
3. 系统 python 命令
4. 回退到 python3

在 macOS 等没有 python 别名的系统上，确保安装 python3 并正确配置 PATH。

资料来源：packages/shared/CHANGELOG.md:1-15

进阶配置

自定义超时设置

构建和安装操作默认使用较长的超时时间：

MCP 服务器工厂

@paretools/server-db v0.11.1 引入了 createServer() 工厂函数，提取了通用的 MCP 服务器样板代码，简化自定义工具包的开发。

参见

• Git 工具详细文档
• Docker 工具详细文档
• Python 工具详细文档
• 安全策略
• 发布说明

概述

Pare 是一个 MCP（Model Context Protocol）工具集合，提供 28 个 npm 包、240 个工具，涵盖版本控制、语言运行时、构建系统等多个领域。本页面详细说明 Pare 工具的配置选项，包括环境变量、工具注册行为、路径解析规则、安全验证以及超时设置等核心配置机制。

Pare 的配置系统设计遵循以下原则：声明式输入模式（通过 Zod schema 定义）、路径权威性（path 参数优先于进程工作目录）以及安全注入防护（通过白名单和正则验证阻止恶意输入）。资料来源：packages/shared/src/input-schemas.ts:1-50

核心配置架构

graph TD
    A[MCP 客户端请求] --> B{环境变量检查}
    B --> C[PARE_LAZY 设置]
    B --> D[PATH 参数解析]
    B --> E[安全验证层]
    
    C -->|true| F[延迟工具注册]
    C -->|false| G[全量工具注册]
    
    D --> H[工作目录解析]
    H --> I[Git 仓库根目录定位]
    
    E --> J[flag 注入检测]
    E --> K[命令白名单验证]
    
    F --> L[discover-tools 元工具]
    G --> M[全部工具就绪]
    
    I --> N[repo-scoped 工具执行]
    J -->|检测到注入| O[拒绝请求]
    K -->|非白名单命令| O
    K -->|白名单内| P[执行命令]

环境变量配置

延迟工具注册模式

PARE_LAZY 环境变量控制工具的注册策略。当设置为 true 时，核心工具在服务器启动时注册，而扩展工具则延迟注册，仅在通过 discover-tools 元工具发现时才加载。这种机制显著降低了 LLM 提示中工具架构的 token 消耗。资料来源：packages/server-db/CHANGELOG.md:1-15

graph LR
    A[PARE_LAZY=true] --> B[启动时注册核心工具]
    B --> C[LLM 调用 discover-tools]
    C --> D[动态加载扩展工具]
    D --> E[工具注册表更新]
    
    F[PARE_LAZY=false] --> G[启动时注册全部工具]
    G --> H[立即可用]

路径解析权威性

path 参数在所有仓库作用域工具中具有最高优先级。当省略 path 时，工具操作的是服务器的当前工作目录，而非调用进程的目录。资料来源：packages/shared/CHANGELOG.md:1-10

此设计解决了从嵌套 git worktree 调用工具时的路径歧义问题。社区问题 #876 记录了相关 bug：当从嵌套 worktree 调用 pare-git 工具而未指定 path 时，工具会错误地解析到其他仓库根目录。

工具输入模式配置

标准输入字段

所有 Pare 工具共享一组标准输入字段，这些字段在 input-schemas.ts 中统一声明。资料来源：packages/shared/src/input-schemas.ts:1-80

// 路径输入模式示例
const repoPathInput = z
  .string()
  .max(INPUT_LIMITS.PATH_MAX)
  .optional()
  .describe("Working directory for the operation (default: server's cwd)");

// 紧凑输出模式示例
const compactInput = z
  .boolean()
  .optional()
  .default(false)
  .describe("Reduce token output by omitting non-essential fields");

语言特定配置

#### Python 解释器配置

Python 工具链支持多层解释器解析顺序和虚拟环境自动检测。资料来源：packages/server-python/src/python-test.ts:1-100

解析优先级（从高到低）：

1. 显式指定：interpreter 参数直接传入的路径
2. 虚拟环境检测：查找 .venv/、venv/、env/ 等标准目录
3. PATH 查找：依次尝试 python、python3
4. 模块模式回退：使用 python -m <tool> 调用

graph TD
    A[Python 工具调用] --> B{interpreter 参数?}
    B -->|是| C[使用指定解释器]
    B -->|否| D{虚拟环境目录?}
    D -->|.venv/| E[激活虚拟环境]
    D -->|venv/| E
    D -->|env/| E
    D -->|无| F{python 命令?}
    F -->|是| G[使用 python]
    F -->|否| H{python3 命令?}
    H -->|是| I[使用 python3]
    H -->|否| J[尝试 python -m 模式]
    
    C --> K[执行工具]
    E --> K
    G --> K
    I --> K
    J --> K

社区问题 #884 记录了 pare-test 在 macOS 上因缺少 python 命令而失败的问题，当前已通过自动回退到 python3 解决。

仓库作用域参数

#### Git 工具配置

Git 相关工具支持以下通用参数：资料来源：packages/server-git/src/tools/worktree.ts:1-50

Worktree 工具特殊参数：

⚠️ 已知问题 #906：listVerbose=true 与 porcelain 不能同时使用，因为 git worktree list --verbose 和 --porcelain 选项互斥。当前实现默认传递 --porcelain，导致 verbose 模式失败。

#### GitHub 工具配置

GitHub 工具通过 gh CLI 封装，支持仓库上下文和分页控制。资料来源：packages/server-github/src/tools/release-list.ts:1-60

安全配置

命令注入防护

Pare 在所有用户输入点实施严格的注入防护。资料来源：packages/shared/src/validation.ts:1-100

#### Ref/Branch 参数验证

所有 ref 和 branch 相关参数必须通过 assertNoFlagInjection 验证，拒绝以 - 开头的输入：

export function assertNoFlagInjection(value: string, fieldName: string): void {
  if (value.startsWith("-")) {
    throw new Error(`${fieldName} cannot start with '-' to prevent flag injection`);
  }
}

#### 构建命令白名单

构建工具使用白名单机制，仅允许预定义的 24 种构建工具。资料来源：packages/server-build/src/build-run.ts:1-50

Git 参数限制

超时配置

默认超时设置

不同类型的操作有不同的默认超时时间。资料来源：packages/server-build/CHANGELOG.md:1-30

自定义超时

集成测试时超时设置会对齐 Windows CI 的可靠性要求，确保跨平台行为一致。

紧凑输出模式

compact 参数用于减少 LLM 上下文中的 token 消耗，通过省略非必要字段实现。资料来源：packages/shared/CHANGELOG.md:1-20

各包紧凑模式差异

令牌节省示例

graph LR
    A[git status 原始输出] --> B[~120 tokens]
    A --> C[结构化输出]
    C --> D[~59 tokens]
    B -.->|节省 50%| D
    
    E[测试运行日志] --> F[~500+ tokens]
    E --> G[紧凑 JSON]
    G --> H[~40 tokens]
    F -.->|节省 92%| H

常见配置问题

问题排查矩阵

Git 相关已知问题

Python 相关已知问题

See Also

• Architecture Overview — Pare 系统架构概览
• Tool Reference — 所有工具详细文档
• Security Policy — 安全策略与漏洞报告
• Changelog — 版本变更记录
• Python Interpreter Resolution — Python 解释器解析详解

概述

@paretools/git 是 Pare MCP 工具套件中专注于版本控制的服务器包，通过 MCP（Model Context Protocol）协议封装 Git 命令行工具，将传统的文本输出转换为结构化的 JSON 数据格式。

核心价值

资料来源：README.md

架构设计

组件结构

graph TD
    A[MCP Client / AI Agent] --> B[server-git]
    B --> C[Tool Handlers]
    C --> D[git-runner]
    D --> E[Git CLI]
    E --> D
    D --> F[Output Parser]
    F --> G[structuredContent JSON]
    G --> A
    
    C --> C1[status]
    C --> C2[stash-list]
    C --> C3[worktree]
    C --> C4[blame]
    C --> Cn[...其他工具]

工具执行流程

sequenceDiagram
    participant Client
    participant Server as server-git
    participant Runner as git-runner
    participant Parser
    participant Git
    
    Client->>Server: MCP 工具调用 (e.g., status)
    Server->>Runner: 执行 Git 命令
    Runner->>Git: git status --porcelain
    Git-->>Runner: 原始输出
    Runner->>Parser: 解析输出
    Parser-->>Runner: 结构化数据
    Runner-->>Server: structuredContent
    Server-->>Client: MCP 响应

资料来源：packages/server-git/src/lib/git-runner.ts

核心工具列表

@paretools/git 提供 55 个 Git 相关工具，覆盖版本控制的各个方面：

版本控制操作

暂存与提交

远程操作

工作流工具

历史与追踪

高级操作

资料来源：packages/server-git/src/index.ts

主要工具详解

status 工具

查看 Git 工作区状态，返回结构化的分支和文件变更信息。

// 调用示例
{
  tool: "pare-git",
  action: "status",
  arguments: {
    path: "/path/to/repo"
  }
}

输出结构：

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

资料来源：docs/tool-schemas/git/status.md

stash-list 工具

列出当前仓库中的所有 stash 暂存项。

// 调用示例
{
  tool: "pare-git",
  action: "stash-list",
  arguments: {
    path: "/path/to/repo"
  }
}

输出结构：

{
  "stashes": [
    {
      "index": 0,
      "reference": "stash@{0}",
      "message": "WIP on main: abc1234 Commit message",
      "author": {
        "name": "Author Name",
        "email": "[email protected]"
      },
      "date": "2026-06-15T10:30:00Z"
    }
  ]
}

⚠️ 已知问题：当前实现中所有 stash 条目的索引都报告为 stash@{0}，而非递增的 stash@{0}, stash@{1}, stash@{2} 等。详情请参阅 Issue #908。

资料来源：packages/server-git/src/tools/stash-list.ts

worktree 工具

管理 Git 工作树，支持列出、添加和移除工作树。

// 列出所有工作树
{
  tool: "pare-git",
  action: "worktree",
  arguments: {
    action: "list",
    path: "/path/to/repo"
  }
}

// 添加新工作树
{
  tool: "pare-git",
  action: "worktree",
  arguments: {
    action: "add",
    path: "/path/to/repo",
    branch: "feature-branch",
    directory: "/path/to/worktree"
  }
}

list 输出结构：

{
  "worktrees": [
    {
      "path": "/path/to/main-worktree",
      "branch": "main",
      "head": "abc1234",
      "isMain": true
    },
    {
      "path": "/path/to/feature-worktree",
      "branch": "feature-branch",
      "head": "def5678",
      "isMain": false
    }
  ]
}

⚠️ 已知问题：当 listVerbose=true 时，工作树列表工具会失败，错误信息为 "options '--verbose' and '--porcelain' cannot be used together"。这是因为内部实现同时传递了这两个互斥的选项。详情请参阅 Issue #906。

资料来源：packages/server-git/src/tools/worktree.ts

安全机制

参数注入防护

@paretools/git 实现了多层安全防护，防止恶意输入导致的命令注入攻击。

#### 分支/引用参数验证

所有接受分支名或引用作为参数的函数都会经过 assertNoFlagInjection 验证：

// 阻止以 - 开头的参数，防止注入
assertNoFlagInjection(ref);

这可以防止以下攻击：

• --version → 被阻止
• --help; rm -rf ~ → 分号后的内容被阻止
• -u origin → 被阻止

#### 构建命令白名单

对于涉及构建操作的工具（如 hooks），使用 assertAllowedCommand 进行白名单验证：

// 仅允许已知的 24 种构建工具
const KNOWN_BUILD_TOOLS = [
  'npm', 'pnpm', 'yarn', 'bun',
  'cargo', 'go', 'gradle', 'maven',
  'make', 'cmake', 'meson',
  // ... 共 24 种
];

资料来源：packages/server-git/CHANGELOG.md

路径解析与工作目录

工作目录解析逻辑

当 Git 工具未指定 path 参数时，会在服务器的启动目录（launch directory）下解析仓库，而非调用者的当前工作目录。

graph LR
    A[调用者进程] -->|cwd: /worktrees/feature|
    B[server-git 进程] -->|启动目录: /projects/main|
    B --> C[解析到 /projects/main]
    
    A1[调用者进程] -->|cwd: /worktrees/feature|
    D[显式 path 参数] -->|path: /worktrees/feature|
    D --> E[解析到正确仓库]

⚠️ 重要提示：从嵌套的 Git worktree 中调用工具时，如果不显式传递 path 参数，工具会在父仓库而非当前 worktree 中执行操作。这可能导致意外的行为。始终建议显式传递 path 参数以确保操作的正确性。

资料来源：@paretools/[email protected]

正确的使用方式

// ✅ 正确：显式指定路径
{
  tool: "pare-git",
  action: "status",
  arguments: {
    path: process.cwd()  // 传递调用者的当前目录
  }
}

// ⚠️ 注意：如果在嵌套 worktree 中调用且不传 path
// 工具将在父仓库根目录执行，而非当前 worktree

输出模式

structuredContent 与 content 的区别

每个 Git 工具返回两个输出字段：

MCP 客户端可使用 structuredContent 直接获取类型化的数据，无需解析文本。

输出模式选项

某些工具支持不同的输出模式：

{
  tool: "pare-git",
  action: "diff",
  arguments: {
    path: "/repo",
    mode: "compact"  // compact | full | minimal
  }
}

• compact：最小化输出，仅包含关键信息
• full：完整输出，包含所有可用字段
• minimal：极简输出，用于高 Token 敏感场景

与其他工具的集成

GitHub 工具协同

Git 工具与 @paretools/github 工具配合使用，可实现完整的代码协作工作流：

graph LR
    A[pare-git] -->|branch, commit, push|
    B[pare-github] -->|pr-create, pr-view|
    C[CI/CD] -->|run-list, run-view|
    
    A --> D[本地开发]
    B --> E[PR 管理]
    C --> F[持续集成]

工具映射规则

根据项目规则，应优先使用 Pare MCP 工具而非原始 CLI：

资料来源：rules/GEMINI.md

已知问题与限制

Issue #908: stash-list 索引问题

问题描述：stash-list 工具将所有 stash 条目标记为 stash@{0}，而非递增的索引。

影响范围：使用 stash 索引进行恢复或删除操作的场景。

临时解决方案：手动在 stash 消息中查找目标 stash 的实际位置。

Issue #906: worktree listVerbose 冲突

问题描述：worktree 工具在 list 模式下设置 listVerbose=true 时崩溃。

影响范围：需要详细工作树信息的用户。

临时解决方案：使用默认模式（listVerbose=false）获取基本信息。

Issue #876: 嵌套 Worktree 路径解析

问题描述：从嵌套 worktree 调用时，不传 path 参数会导致操作在错误的仓库中执行。

影响范围：在多仓库 monorepo 或嵌套 worktree 环境中使用 Git 工具。

临时解决方案：始终显式传递 path 参数为 process.cwd() 或目标仓库路径。

Schema 定义

通用输入 Schema

interface RepoPathInput {
  path?: string;  // 可选，默认使用服务器启动目录
}

interface StashListInput extends RepoPathInput {}

interface WorktreeListInput extends RepoPathInput {
  listVerbose?: boolean;  // 是否显示详细模式（当前有 bug）
}

输出 Schema

interface GitStatusOutput {
  branch: string;
  upstream: string | null;
  ahead: number;
  behind: number;
  staged: FileChange[];
  modified: string[];
  deleted: string[];
  untracked: string[];
  conflicts: string[];
  clean: boolean;
}

interface StashListOutput {
  stashes: StashEntry[];
}

interface StashEntry {
  index: number;
  reference: string;
  message: string;
  author: { name: string; email: string };
  date: string;
}

资料来源：packages/server-git/src/schemas/index.ts

安装与配置

依赖要求

• Node.js >= 18.0.0
• Git CLI 已安装并在 PATH 中可用
• MCP 客户端（如 Claude Desktop、Cursor 等）

安装步骤

# 通过 npm 安装
npm install @paretools/git

# 或使用 pnpm
pnpm add @paretools/git

MCP 配置示例

{
  "mcpServers": {
    "pare-git": {
      "command": "npx",
      "args": ["-y", "@paretools/git"],
      "env": {
        "PARE_GIT_TIMEOUT": "30000"
      }
    }
  }
}

参见

• GitHub Tools — GitHub CLI 封装工具
• 搜索工具 — ripgrep 和 fd 封装工具
• 测试工具 — 自动化测试运行器
• 构建工具 — 构建系统封装
• Linting 工具 — 代码质量检查工具

概述

GitHub Tools 是 Pare 项目中用于与 GitHub API 和 GitHub CLI (gh) 交互的 MCP（Model Context Protocol）服务器工具集。该工具包封装了 gh 命令行工具的 JSON 输出模式，将传统的文本输出转换为结构化的 JSON 数据格式，显著减少 AI 代理在处理 GitHub 数据时的 token 消耗。

根据项目文档，GitHub Tools 在标准文本模式下可能产生约 120 个 token，而使用 Pare 的结构化输出仅需约 59 个 token，节省约 50% 的 token 消耗。对于测试运行器和构建日志等更冗长的输出场景，节省比例可达到 80-92%。

资料来源：README.md

架构设计

核心组件

GitHub Tools 采用分层架构设计，主要包含以下核心组件：

资料来源：packages/server-github/src/index.ts

数据流架构

graph TD
    A[MCP 客户端请求] --> B[index.ts 入口]
    B --> C[工具路由]
    C --> D[gh-runner 命令执行]
    D --> E[gh CLI 进程]
    E --> F[JSON 输出解析]
    F --> G[parsers.ts 验证]
    G --> H[结构化结果返回]
    H --> I[MCP 响应]
    
    D -->|参数构建| J[path-validation.ts]
    J -->|路径验证| D

工具注册机制

GitHub Tools 支持懒加载工具注册机制。当环境变量 PARE_LAZY=true 时，仅核心工具在启动时注册，扩展工具通过 discover-tools 元工具按需加载。这一机制可减少 AI 代理提示中的 token 消耗。

资料来源：packages/server-db/CHANGELOG.md

工具目录

Pull Request 相关工具

#### pr-diff 工具参数说明

资料来源：docs/tool-schemas/github/pr-diff.md

Issue 相关工具

#### issue-list 工具参数说明

资料来源：docs/tool-schemas/github/issue-list.md

其他工具

#### release-list 工具参数

inputSchema: {
  limit: z.coerce.number().optional().default(30),
  repo: z.string().optional(),
  excludeDrafts: z.boolean().optional(),
  excludePreReleases: z.boolean().optional(),
  order: z.enum(["asc", "desc"]).optional(),
  path: repoPathInput,
  compact: compactInput,
}

资料来源：packages/server-github/src/tools/release-list.ts:15-36

配置与路径处理

路径参数权威性

path 参数是 GitHub 工具确定仓库位置的主要依据。当 path 参数被省略时，工具会使用服务器进程的当前工作目录（process.cwd()）。显式传递 path 参数可确保工具操作正确的仓库。

资料来源：packages/shared/CHANGELOG.md

输入验证

GitHub Tools 对输入参数实施了严格的验证机制：

• flag 注入防护：阻止以 - 开头的 ref/branch 参数，防止命令注入攻击
• 路径验证：使用 assertNoFlagInjection 和 assertAllowedCommand 验证工具函数
• 字符串长度限制：使用 INPUT_LIMITS.SHORT_STRING_MAX 限制输入长度

if (repo) assertNoFlagInjection(repo, "repo");

资料来源：packages/server-github/src/tools/release-list.ts:34

MCP 工具注解

GitHub Tools 集成了 MCP 工具注解，帮助 AI 代理理解工具行为和安全性特征：

annotations: { readOnlyHint: true, openWorldHint: true }

资料来源：packages/server-github/src/tools/release-list.ts:11-12

已知问题与限制

空输出解析问题

问题编号：#905

当 gh 命令返回零结果时，部分解析器会因空 stdout 而崩溃。gh CLI 在匹配零结果时退出码为 0，但输出为空字符串（而非 []）。直接执行 JSON.parse(json) 会导致 Unexpected end of JSON input 错误。

受影响函数：parseLabelList 及 10 个其他 parse* 函数

状态：问题已确认，需要修复

资料来源：社区问题 #905

pr-diff 参数不生效问题

问题编号：#907

pr-diff 工具忽略 full=true 和 nameOnly=true 参数，始终返回相同的文件级别统计数组（包含 file、status、additions、deletions），不返回补丁内容或纯文件名列表。

复现命令：

pr-diff number=904 full=true
# 返回 {"files":[{file, status, additions, deletions}]}（仅统计，无补丁）

状态：问题已确认

资料来源：社区问题 #907

解析器空安全问题

解析器模块需要处理以下边界情况：

• 空 stdout 响应
• 非 JSON 格式的错误输出
• 部分 JSON 数据截断
• gh CLI 进程异常退出

// 建议的防护模式
const raw = json.trim() ? JSON.parse(json) : fallbackValue;

资料来源：packages/server-github/src/lib/parsers.ts

使用示例

基本使用场景

// 查看 PR 详情
{
  tool: "pare-github_pr-view",
  params: {
    number: 123,
    repo: "owner/repo"
  }
}

// 列出 Open 状态的 Issue
{
  tool: "pare-github_issue-list",
  params: {
    state: "open",
    limit: 50,
    labels: "bug,help wanted"
  }
}

与 Claude Code 集成

GitHub Tools 可通过 MCP 协议与 Claude Code 等 AI 代理集成，典型配置如下：

{
  "mcpServers": {
    "pare-github": {
      "command": "npx",
      "args": ["-y", "@paretools/github"]
    }
  }
}

安全考量

命令注入防护

v0.3.0 版本引入了增强的安全机制：

• Git 参数注入防护：阻止 ref/branch 参数以 - 开头
• 构建命令白名单：仅允许 24 种已知构建工具
• 新增验证工具：assertNoFlagInjection() 和 assertAllowedCommand()

资料来源：packages/server-github/CHANGELOG.md

安全审计

项目于 2026 年 2 月进行了安全审计，发现 18 个问题，其中 14 个已修复，4 个被接受为风险。

资料来源：SECURITY.md

错误处理

gh-runner 错误处理

gh-runner 模块负责捕获和处理 gh CLI 执行过程中的错误：

graph TD
    A[gh 命令执行] --> B{执行成功?}
    B -->|是| C[返回 JSON 输出]
    B -->|否| D[捕获 stderr]
    D --> E{是预期错误?}
    E -->|是| F[返回空数组/默认值]
    E -->|否| G[抛出异常]

常见错误码

性能特性

超时配置

构建和安装操作（Docker、npm、cargo、go）的默认超时时间已延长至 5 分钟，以适应长时间运行的操作。

Token 优化

GitHub Tools 通过以下方式减少 token 消耗：

• 结构化 JSON 输出替代纯文本
• 紧凑模式（compact: true）减少冗余字段
• 移除不必要的元数据（如 resolved URLs、fileCount、unpackedSize）

资料来源：packages/shared/CHANGELOG.md

版本历史

相关资源

• Pare 主项目文档
• @paretools/shared 文档
• GitHub CLI 官方文档
• MCP 协议规范

参见

• Git 工具 - 本地 Git 操作
• 测试工具 - 测试运行与报告
• 构建工具 - 构建系统集成

概述

Python Tools 是 Pare 项目中专注于 Python 生态系统的 MCP 服务器包，提供了 8 个结构化、令牌高效的 Python 工具输出，专为 AI 代理设计。相比原始 CLI 输出，可减少高达 65% 的令牌消耗。

资料来源：packages/server-python/README.md

核心价值

资料来源：packages/shared/CHANGELOG.md

工具列表

完整的 8 个 Python 工具

资料来源：packages/server-python/README.md

Python 解释器解析机制

解析顺序

Python Tools 实现了智能的 Python 解释器解析机制，支持多层回退策略：

graph TD
    A[开始解析 Python 解释器] --> B{显式指定 interpreter?}
    B -->|是| C[使用指定的解释器路径]
    B -->|否| D{项目目录中有 .venv?}
    D -->|是| E[使用 .venv/bin/python]
    D -->|否| F{系统中是否有 python?}
    F -->|是| G[使用 python 命令]
    F -->|否| H[使用 python3 命令]
    H --> I{python3 -m 工具可用?}
    I -->|是| J[使用 python3 -m 工具名]
    I -->|否| K[返回错误: 工具未找到]
    C --> L[解析成功]
    E --> L
    G --> L
    J --> L
    K --> M[报告工具不可用]

资料来源：packages/shared/src/python.ts

虚拟环境检测

系统按以下优先级检测虚拟环境：

1. 显式指定 — 通过 interpreter 参数传入的完整路径
2. 项目 .venv — 检测项目根目录下的 .venv/ 目录
3. 系统 Python — 使用 PATH 中的 python 命令
4. python3 回退 — 当 python 不可用时使用 python3
5. python -m 模式 — 作为最后手段，使用模块方式调用

资料来源：packages/shared/CHANGELOG.md - v0.19.1

工具执行流程

统一执行架构

graph LR
    A[MCP 客户端请求] --> B[Python Runner]
    B --> C{工具类型}
    C -->|标准命令| D[直接执行工具]
    C -->|Python 模块| E[python -m 模块名]
    D --> F[捕获 stdout/stderr]
    E --> F
    F --> G[JSON Schema 验证]
    G --> H[结构化输出]
    H --> I[MCP 响应]

pytest 工具详解

输入参数

资料来源：packages/server-python/src/tools/pytest.ts

输出结构

interface PytestResult {
  exitCode: number;
  passed: number;
  failed: number;
  skipped: number;
  tests: Array<{
    name: string;
    status: "passed" | "failed" | "skipped";
    duration?: number;
    message?: string;
  }>;
}

ruff 工具详解

ruff-check 输出结构

Diagnostic 结构

资料来源：packages/server-python/src/tools/ruff.ts

pip 工具详解

pip-install 参数

资料来源：packages/server-python/src/tools/pip.ts

配置与使用

MCP 客户端配置

{
  "mcpServers": {
    "pare-python": {
      "command": "npx",
      "args": ["-y", "@paretools/python"]
    }
  }
}

环境变量

已知问题与解决方案

Windows 用户站点 Scripts 问题

问题描述：在 Windows 系统上，当 pytest、ruff-check、ruff-format 作为 Python 模块安装到用户站点 Scripts 目录时，工具可能返回 "Command not found" 错误。

影响版本：所有版本（截至 v0.20.0）

解决方案：

1. 使用显式 interpreter 参数指定 Python 路径
2. 确保工具在系统 PATH 中可用
3. 考虑使用 python -m pytest 模式作为回退

资料来源：GitHub Issue #891

macOS python 命令缺失

问题描述：在 macOS 系统上，默认可能只有 python3 而没有 python 命令。

解决方案：系统已实现自动回退机制，会依次尝试：

1. python 命令
2. python3 命令
3. python3 -m <tool> 模式

资料来源：GitHub Issue #884

安全特性

命令注入防护

Python Tools 实现了多层安全验证：

1. 参数白名单 — 只允许已知的 pip/pytest/ruff 参数
2. 路径验证 — 防止路径遍历攻击
3. 输入限制 — Zod schema 对所有字符串/数组参数设置大小限制
4. 标志注入检测 — 使用 assertNoFlagInjection 验证用户输入

资料来源：packages/server-python/src/index.ts

版本历史

资料来源：packages/server-python/CHANGELOG.md

相关链接

• 主项目仓库
• @paretools/python npm 包
• GitHub Issues - Python 相关
• Pare 文档首页

概述

Docker Tools 是 Pare 项目中专门用于封装 Docker CLI 操作的 MCP（Model Context Protocol）服务器包。其核心目标是为 AI 代理提供结构化、令牌高效的 Docker 输出，与原生 docker CLI 相比可节省高达 95% 的令牌使用量。

资料来源：packages/server-docker/README.md

该工具包属于 Pare 套件的一部分，后者是一个包含多个 MCP 服务器的集合，旨在为 AI 编程代理提供统一的开发工具接口。

工具列表

Docker Tools 当前提供 9 个核心工具，涵盖容器生命周期管理的完整流程：

资料来源：packages/server-docker/README.md

架构设计

组件结构

graph TD
    A[MCP 客户端] --> B[@paretools/docker 服务器]
    B --> C[docker-runner 执行器]
    B --> D[validation 验证器]
    B --> E[schemas 数据模式]
    
    C --> F[docker CLI]
    D --> G[安全检查]
    E --> H[输出格式化]
    
    H --> I[结构化 JSON 输出]
    F --> J[原始输出]
    
    G -->|阻止危险挂载| K[/, /etc, /var/run/docker.sock]

执行流程

sequenceDiagram
    participant M as MCP 客户端
    participant D as docker-runner
    participant V as validation
    participant S as schemas
    participant CLI as docker CLI
    
    M->>D: 调用 Docker 工具
    D->>V: 验证输入参数
    V->>V: 检查危险挂载卷
    V->>V: 验证 flag 注入
    V-->>D: 验证通过
    D->>CLI: 执行 docker 命令
    CLI-->>D: 返回原始输出
    D->>S: 格式化输出
    S-->>M: 结构化 JSON

核心功能详解

容器管理工具

#### ps（容器列表）

ps 工具用于列出 Docker 容器，返回包含状态、端口映射和运行状态的结构化数据。与原始 docker ps 输出相比，经过结构化处理后更易于 AI 代理解析和理解。

#### run（运行容器）

run 工具封装了 docker run 命令，提供结构化的执行结果。参数验证确保容器启动的安全性。

#### exec（容器内执行）

exec 工具允许在运行中的容器内执行命令，适用于调试和交互式操作场景。

镜像管理工具

#### build（构建镜像）

build 工具封装 docker build 操作，返回构建结果包括镜像 ID、构建耗时和任何错误信息。

资料来源：docs/tool-schemas/docker/build.md

#### pull（拉取镜像）

pull 工具从镜像仓库拉取镜像并返回镜像摘要信息，支持版本管理和镜像更新。

#### images（镜像列表）

images 工具列出本地所有镜像，包含仓库名、标签和大小信息。

日志管理

#### logs（获取日志）

logs 工具以结构化行数组形式返回容器日志，便于 AI 代理进行日志分析和问题诊断。

Docker Compose 支持

#### compose-up（启动服务）

compose-up 工具启动 Docker Compose 定义的服务集，返回每个服务的启动状态。

资料来源：docs/tool-schemas/docker/compose-up.md

#### compose-down（停止服务）

compose-down 工具停止 Docker Compose 服务，确保资源正确释放。

安全性设计

Docker Tools 在 v0.6.0 版本中引入了多项安全加固措施：

危险挂载卷阻止

系统会阻止以下危险路径的挂载：

资料来源：packages/server-docker/CHANGELOG.md

Flag 注入防护

所有 args[] 数组都会经过 Flag 注入验证，确保恶意命令无法通过参数注入方式执行。

错误消息清理

错误消息经过清理处理，防止路径信息泄露到输出中，保护系统内部结构不被暴露。

输出格式与令牌优化

自动紧凑模式

Docker Tools 支持自动紧凑模式（compact 参数，默认为 true）。当结构化 JSON 输出的令牌数超过原始 CLI 输出时，系统会自动应用紧凑投影，保留关键字段而丢弃详细信息的部分（如堆栈跟踪、详细诊断信息）。

令牌节省

通过结构化输出和自动压缩，Docker Tools 相比原生 docker CLI 可节省 高达 95% 的令牌使用量。

日志输出限制

为防止无界令牌消耗，logs 工具的完整模式输出设有上限。容器 ID 会被截断为 12 个字符，时间戳采用相对格式显示。

资料来源：packages/server-docker/CHANGELOG.md

配置与使用

快速开始

npx -y @paretools/docker

MCP 客户端配置

在 Claude Desktop 或其他 MCP 客户端中添加以下配置：

{
  "mcpServers": {
    "pare-docker": {
      "command": "npx",
      "args": ["-y", "@paretools/docker"]
    }
  }
}

工具调用示例

// 构建镜像
{
  tool: "mcp__pare-docker__build",
  args: {
    contextPath: "./docker",
    tag: "myapp:latest"
  }
}

// 运行容器
{
  tool: "mcp__pare-docker__run",
  args: {
    image: "nginx:latest",
    name: "web-server",
    ports: [{ host: 8080, container: 80 }]
  }
}

// 获取日志
{
  tool: "mcp__pare-docker__logs",
  args: {
    container: "web-server",
    tail: 100
  }
}

版本历史

资料来源：packages/server-docker/CHANGELOG.md

已知问题与限制

v0.18.1 之前版本

在 v0.18.1 之前的版本中，错误消息可能包含内部路径信息，存在信息泄露风险。建议升级至 v0.18.1 或更高版本以获取安全修复。

集成测试时序

某些 Windows CI 环境下的集成测试可能因时序问题失败，建议在本地开发时适当调整超时设置。

依赖关系

graph LR
    A[@paretools/docker] --> B[@paretools/shared]
    B --> C[zod]
    B --> D[run]
    
    A --> E[docker CLI]

Docker Tools 依赖以下核心包：

• @paretools/[email protected] — 共享工具和验证逻辑
• zod — 输入参数验证
• run — 命令执行封装（超时从 30s 提升至 60s）

故障排除

常见问题

调试建议

1. 验证 Docker 状态：运行 docker ps 确认守护进程可用
2. 检查镜像存在：使用 images 工具列出本地镜像
3. 查看日志：使用 logs 工具获取详细执行日志
4. 简化参数：移除可选参数以隔离问题

参见

• Git Tools — Git 版本控制工具集
• Python Tools — Python 开发环境工具集
• GitHub Tools — GitHub CLI 封装工具集
• Search Tools — 代码搜索工具集
• Pare 项目主页 — 完整项目文档

概述

Test Runner Tools（Pare 测试运行工具）是 @paretools/test 包提供的核心功能集，封装了多种测试框架的统一接口。该工具包通过自动检测项目类型和配置，智能选择合适的测试运行器，并以结构化 JSON 格式返回结果，从而大幅减少 LLM 上下文中的令牌消耗。

核心设计目标包括：

• 自动检测：无需手动指定测试框架，工具自动识别项目使用的测试技术栈
• 统一输出：无论底层使用何种测试框架，输出格式保持一致
• 令牌优化：相比原始测试输出，可节省 80-92% 的令牌消耗
• 跨平台兼容：支持 macOS、Windows、Linux 等主流操作系统

资料来源：packages/server-test/src/index.ts:1-50

概述

Pare 是一个 MCP（Model Context Protocol）工具服务器集合，提供 100+ 工具，横跨 14 个 npm 包。这些工具通过统一的架构模式包装外部 CLI 工具（如 git、docker、npm、pytest 等），为 AI 代理提供标准化的编程接口。

系统架构的核心设计目标包括：

• 安全性：通过参数白名单和注入检测防止命令注入攻击
• 可发现性：为每个工具提供 MCP instructions 字段以提升 AI 代理的工具发现能力
• 可扩展性：通过工厂模式和标准化接口支持新工具的快速添加
• 可靠性：统一的错误处理、超时管理和输出格式化

资料来源：SECURITY.md

核心组件架构

包结构概览

Pare 项目采用 monorepo 结构，主要包含以下类型的包：

资料来源：packages/server-db/CHANGELOG.md

共享核心包架构

@paretools/shared 是整个生态系统的基石，提供所有服务器包共享的基础设施：

graph TD
    subgraph "shared/src 核心模块"
        A[server.ts] --> B[createServer 工厂函数]
        C[runner.ts] --> D[工具执行器]
        E[types.ts] --> F[统一类型定义]
        G[validation.ts] --> H[安全验证工具]
        I[output.ts] --> J[输出格式化]
        K[strict-input.ts] --> L[输入验证]
    end
    
    B --> M[标准化 MCP Server]
    D --> M
    H --> D
    J --> D
    L --> D
    
    M --> N[@paretools/* 各服务器包]

#### 核心模块职责

资料来源：packages/shared/src/server.ts

Server 工厂模式

createServer 架构

v0.11.1 版本引入了 createServer() 工厂函数，将通用的 MCP server 样板代码提取到共享模块中：

graph LR
    A[工具定义数组] --> B[createServer 配置]
    B --> C{延迟加载模式?}
    C -->|是 PARE_LAZY=true| D[仅注册核心工具]
    C -->|否| E[注册所有工具]
    D --> F[discover-tools 元工具]
    F --> G[按需加载扩展工具]
    E --> H[MCP Server 就绪]
    G --> H

延迟加载机制

当环境变量 PARE_LAZY=true 时，系统采用懒加载策略：

• 启动时：仅注册核心工具，减少 LLM 提示中的 token 消耗
• 运行时：通过 discover-tools 元工具按需发现和加载扩展工具
• 优势：显著降低 AI 代理获取工具列表时的 token 开销

资料来源：packages/server-db/CHANGELOG.md

安全架构

命令注入防护

v0.3.0 版本实现了全面的安全加固：

#### assertNoFlagInjection

验证用户提供的字符串参数不以 - 开头，防止攻击者通过注入标志来修改命令行为：

// 伪代码示例
function assertNoFlagInjection(input: string, paramName: string): void {
  if (input.startsWith('-')) {
    throw new Error(`${paramName} cannot start with '-': ${input}`);
  }
}

#### assertAllowedCommand

通过白名单机制限制允许执行的构建/安装工具：

const ALLOWED_BUILD_TOOLS = [
  'npm', 'pnpm', 'yarn', 'bun',
  'docker', 'podman',
  'cargo', 'go', 'gradle', 'maven',
  // ... 共 24 种工具
];

function assertAllowedCommand(cmd: string): void {
  if (!ALLOWED_BUILD_TOOLS.includes(cmd)) {
    throw new Error(`Command not allowed: ${cmd}`);
  }
}

资料来源：packages/shared/src/validation.ts

MCP 工具注解

所有工具都配备标准化的 MCP 注解，帮助 AI 代理理解工具行为：

工具执行流程

标准工具调用流程

sequenceDiagram
    participant AI as AI Agent
    participant MCP as MCP Client
    participant Server as @paretools/* Server
    participant Runner as runner.ts
    participant Tool as 具体工具实现
    participant CLI as 外部 CLI

    AI->>MCP: 调用工具 (e.g., mcp__pare-git__status)
    MCP->>Server: 转发请求
    Server->>Runner: runTool(toolName, args)
    Runner->>Tool: 执行工具逻辑
    Tool->>CLI: 调用外部命令
    CLI-->>Tool: 返回结果
    Tool-->>Runner: 格式化输出
    Runner-->>Server: 统一响应格式
    Server-->>MCP: MCP Response
    MCP-->>AI: 解析结果

输出格式化

output.ts 模块负责将各种 CLI 输出转换为统一格式：

// 紧凑模式：减少 token 消耗
// 完整模式：保留所有详细信息
// 自定义模式：根据工具类型定制输出结构

工具包架构

Git 工具集 (@paretools/git)

提供 20+ git 操作工具，包括：

#### 工作树列表问题

⚠️ 已知问题 (#906)：调用 worktree 工具时设置 listVerbose=true 会导致冲突错误：

fatal: options '--verbose' and '--porcelain' cannot be used together

这是因为实现同时传递了 --porcelain 和 --verbose 标志，而 git 不支持这种组合。

资料来源：packages/server-git/src/tools/worktree.ts

#### 暂存列表索引问题

⚠️ 已知问题 (#908)：stash-list 工具将所有暂存条目都标记为 stash@{0}，而不是递增的 stash@{0}、stash@{1}、stash@{2} 等。

GitHub 工具集 (@paretools/github)

封装 gh CLI，提供 GitHub API 操作：

#### PR Diff 选项问题

⚠️ 已知问题 (#907)：pr-diff 工具忽略 full=true 和 nameOnly=true 参数，总是返回文件级统计信息，从不返回补丁内容或文件名列表。

Python 工具集 (@paretools/python)

提供 Python 相关开发工具：

#### Python 工具已知问题

⚠️ Windows 模块问题 (#891)：在 Windows 上，当工具安装为 Python 模块而非 PATH 命令时，pytest、ruff-check、ruff-format 可能失败。

⚠️ Python 解释器检测 (#884)：pare-test 在 macOS 等没有 python 命令但有 python3 的系统上可能失败。

路径解析机制

path 参数权威性

v0.20.0 版本明确了 path 参数的权威性规则：

graph TD
    A[工具调用] --> B{path 参数存在?}
    B -->|是| C[使用提供的 path]
    B -->|否| D{从嵌套 worktree 调用?}
    D -->|是| E[可能使用错误的 cwd]
    D -->|否| F[使用 server cwd]
    C --> G[正确的仓库上下文]
    E -.->|已知问题 #876| G
    F --> G

⚠️ 已知问题 (#876)：从嵌套 git worktree 调用工具时，如果未提供显式 path 参数，工具可能使用错误的仓库根目录。

资料来源：packages/server-github/src/tools/release-list.ts

配置与环境变量

核心环境变量

MCP 服务器配置

// server.ts 中的标准化配置
interface ServerConfig {
  name: string;           // 服务器名称
  version: string;        // 版本号
  tools: Tool[];          // 工具定义
  instructions?: string;   // AI 代理指导
  mcpName?: string;        // MCP 注册表名称
}

解析器安全

空输出处理

⚠️ 已知问题 (#905)：多个 parse* 函数在 CLI 返回空输出（而非 []）时会崩溃。问题出现在：

• gh label list --search <term> 无匹配结果时返回空 stdout
• 10+ 个解析器使用 JSON.parse(json) 而未检查空输入

// 不安全的模式
const raw = JSON.parse(json);  // json 为空时会崩溃

// 安全的模式
const raw = json.trim() ? JSON.parse(json) : [];

超时配置

操作超时策略

资料来源：packages/server-lint/CHANGELOG.md

版本演进

故障排除

常见问题

NPM Token 更新

⚠️ 维护提醒：GitHub NPM_TOKEN secret 需要每 90 天续期。下次续期日期：2026-08-26。

资料来源：GitHub Issue #866

相关文档

• 安全策略 - 漏洞报告流程和支持版本
• 工具使用指南 - 详细的工具调用示例
• 开发指南 - 如何添加新工具
• 包列表 - 所有 @paretools 包索引

概述

Pare 是一套面向 AI Agent 的 MCP（Model Context Protocol）工具集合，通过标准化接口为 AI 提供操作系统和开发工具的操作能力。该项目采用 monorepo 结构，包含 14 个 npm 包，涵盖语言运行时、构建系统、容器化工具和版本控制等核心开发场景。

资料来源：packages/shared/CHANGELOG.md

架构设计

MCP 服务器架构

Pare 采用独立 MCP 服务器设计，每个服务器专注于特定工具领域。这种模块化架构允许 AI Agent 按需加载工具，减少不必要的上下文开销。

graph TD
    A[AI Agent] --> B[MCP Client]
    B --> C[pare-git]
    B --> D[pare-docker]
    B --> E[pare-github]
    B --> F[pare-python]
    B --> G[pare-npm]
    B --> H[pare-cargo]
    B --> I[pare-http]
    
    C --> J[Git Operations]
    D --> K[Docker Operations]
    E --> L[GitHub CLI Operations]
    F --> M[Python/pip/pytest/ruff]
    G --> N[npm/pnpm/yarn]
    H --> O[Rust/Cargo]
    I --> P[curl wrappers]

资料来源：packages/server-git/CHANGELOG.md

工具命名规范

所有 MCP 工具遵循统一命名约定：mcp__pare-<domain>__<action>，其中：

资料来源：rules/CONVENTIONS.md

核心服务器包

包列表与工具数量

资料来源：packages/shared/CHANGELOG.md

集成配置

环境变量

Pare 支持以下环境变量用于配置行为：

资料来源：hooks/README.md

懒加载模式

启用 PARE_LAZY=true 后，服务器仅在启动时注册核心工具，扩展工具通过 discover-tools 元工具按需发现和加载。此功能可显著减少 LLM 提示词中的工具架构开销。

资料来源：packages/server-db/CHANGELOG.md

工具使用示例

Git 工具

// 列出所有分支
await mcp__pare-git__branch({ action: "list" });

// 创建新分支
await mcp__pare-git__branch({ 
  action: "create",
  name: "feature/new-feature",
  path: "/path/to/repo"
});

// 查看提交历史
await mcp__pare-git__log({ 
  action: "list",
  maxCount: 10,
  format: "oneline"
});

Docker 工具

// 运行容器
await mcp__pare-docker__run({
  image: "node:20-alpine",
  command: ["node", "-v"]
});

// 查看运行中的容器
await mcp__pare-docker__ps({ all: false });

// 查看容器日志
await mcp__pare-docker__logs({
  container: "my-container-id",
  tail: 100
});

GitHub 工具

// 列出 Pull Requests
await mcp__pare-github__pr_list({
  state: "open",
  limit: 10
});

// 查看 PR 详情
await mcp__pare-github__pr_view({
  number: 123,
  comments: true
});

// 创建 Issue
await mcp__pare-github__issue_create({
  title: "Bug: 修复登录问题",
  body: "详细的问题描述...",
  labels: ["bug", "priority-high"]
});

资料来源：docs/tool-response-examples.md

安全特性

命令注入防护

Pare 在 v0.3.0 中引入了全面的安全加固措施：

• Git 参数注入防护：阻止以 - 开头的 ref/branch 参数
• 构建命令白名单：仅允许 24 种已知的构建工具
• 验证工具：assertNoFlagInjection() 和 assertAllowedCommand()

// 不安全的输入会被阻止
await mcp__pare-git__branch({
  action: "create",
  name: "feature; rm -rf /"  // 被阻止
});

资料来源：packages/server-git/CHANGELOG.md

MCP 工具注解

所有工具都包含安全注解，帮助 AI 理解工具行为：

资料来源：packages/server-git/CHANGELOG.md

AI Agent 工作流

推荐工作流

graph LR
    A[Agent Task] --> B[Discovery: 发现可用工具]
    B --> C[Plan: 规划工具调用序列]
    C --> D[Execute: 执行 MCP 调用]
    D --> E[Parse: 解析工具响应]
    E --> F[Validate: 验证结果正确性]
    F --> G{完成?}
    G -->|是| H[返回结果]
    G -->|否| C

Agent 提示词配置

Pare 为所有服务器添加了 instructions 字段，用于向 AI 客户端提供更精确的工具使用指导：

{
  name: "pare-git",
  description: "Git operations for version control",
  instructions: "Use git tools for version control tasks. Always specify path parameter when operating on specific repositories.",
  tools: [...]
}

资料来源：packages/server-git/CHANGELOG.md

已知限制与问题

社区报告的问题

资料来源：社区议题

常见故障排查

#### Python 工具找不到命令

问题：Windows 上 pytest、ruff 等工具报错 "Command not found"。

原因：这些工具安装为 Python 模块而非可执行文件。

解决方案：使用 python -m pytest 或 python -m ruff 形式调用。

资料来源：问题 #891

#### Git 工具操作错误的仓库

问题：从嵌套 worktree 调用 git 工具时，操作了错误的仓库。

原因：path 参数未指定时使用服务器默认工作目录。

解决方案：始终显式传递 path 参数指定目标仓库。

资料来源：问题 #876

#### 空结果导致解析失败

问题：GitHub 工具在查询返回空结果时崩溃。

原因：部分 gh 命令在无结果时输出空 stdout 而非 []。

解决方案：已在 #903/#904 中修复了 parseLabelList，其他解析器修复进行中。

资料来源：问题 #905

Claude Code 集成

钩子脚本

Pare 提供了 pare-prefer-mcp.sh 钩子脚本，用于在 Claude Code 中优先使用 MCP 工具而非 shell 命令：

#!/bin/bash
# hooks/pare-prefer-mcp.sh
# 当 MCP 服务器提供等效工具时，优先使用 MCP 版本

资料来源：hooks/pare-prefer-mcp.sh

代理配置示例

// claude_desktop_config.json
{
  "mcpServers": {
    "pare-git": {
      "command": "npx",
      "args": ["-y", "@paretools/git"]
    },
    "pare-github": {
      "command": "npx",
      "args": ["-y", "@paretools/github"]
    },
    "pare-python": {
      "command": "npx",
      "args": ["-y", "@paretools/python"]
    }
  }
}

扩展阅读

• CLAUDE.md - Claude Code 项目规则
• CONVENTIONS.md - 代码规范和约定
• 工具响应示例 - 各工具的响应格式说明

Pitfall Log / 踩坑日志

项目：dave-london/pare

摘要：发现 17 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：Renew NPM_TOKEN before August 26, 2026。

1. 安全/权限坑 · 来源证据：Renew NPM_TOKEN before August 26, 2026

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Renew NPM_TOKEN before August 26, 2026
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_54641627ecff4e69be15ff36eed7a387 | https://github.com/Dave-London/Pare/issues/866 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

2. 身份坑 · 仓库名和安装名不一致

• 严重度：medium
• 证据强度：runtime_trace
• 发现：仓库名 pare 与安装入口 @paretools/npm 不完全一致。
• 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
• 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。
• 复现命令：npx @paretools/npm
• 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。
• 证据：identity.distribution | mcp_registry:io.github.Dave-London/npm:0.8.0 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.Dave-London%2Fnpm/versions/0.8.0 | repo=pare; install=@paretools/npm

3. 安装坑 · 来源证据：Nightly suite failure — 2026-05-28

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Nightly suite failure — 2026-05-28
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_0055539ad4314d8bb47021f15b060fa3 | https://github.com/Dave-London/Pare/issues/895 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

4. 安装坑 · 来源证据：[pare-test] Auto-detect venv + fall back to python3 when python is missing

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[pare-test] Auto-detect venv + fall back to python3 when python is missing
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_cb3a4a9195ef4c4982904c6db8b41dae | https://github.com/Dave-London/Pare/issues/884 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

5. 配置坑 · 来源证据：github parsers: empty stdout on zero results crashes 10 more parse* functions (sibling of #903)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：github parsers: empty stdout on zero results crashes 10 more parse* functions (sibling of #903)
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_5d1dd81a40084b6c80c536e93f03898b | https://github.com/Dave-London/Pare/issues/905 | 来源类型 github_issue 暴露的待验证使用条件。

6. 配置坑 · 来源证据：pare-git worktree: listVerbose=true on `list` fails — "options '--verbose' and '--porcelain' cannot be used together"

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：pare-git worktree: listVerbose=true on list fails — "options '--verbose' and '--porcelain' cannot be used together"
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_c31213f7d41d4d82ad4e5295b99d4d76 | https://github.com/Dave-London/Pare/issues/906 | 来源类型 github_issue 暴露的待验证使用条件。

7. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | mcp_registry:io.github.Dave-London/npm:0.8.0 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.Dave-London%2Fnpm/versions/0.8.0 | README/documentation is current enough for a first validation pass.

8. 运行坑 · 来源证据：pare-git stash-list: all entries reported with index stash@{0} instead of 0/1/2

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：pare-git stash-list: all entries reported with index stash@{0} instead of 0/1/2
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_f9de30f482b84bf48362f1a69d7bbb56 | https://github.com/Dave-London/Pare/issues/908 | 来源类型 github_issue 暴露的待验证使用条件。

9. 运行坑 · 来源证据：pare-git: cwd resolution wrong when called from a nested worktree without explicit `path` arg

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：pare-git: cwd resolution wrong when called from a nested worktree without explicit path arg
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_b89f4be8df5246d0b2423d0bb13d39e4 | https://github.com/Dave-London/Pare/issues/876 | 来源类型 github_issue 暴露的待验证使用条件。

10. 运行坑 · 来源证据：pare-github pr-diff: full=true and nameOnly=true return only file stats, no patch/filenames

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：pare-github pr-diff: full=true and nameOnly=true return only file stats, no patch/filenames
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_ae87316305eb458c8c50f896426ee6cd | https://github.com/Dave-London/Pare/issues/907 | 来源类型 github_issue 暴露的待验证使用条件。

11. 运行坑 · 社区讨论暴露的待验证问题：Your self-hosted AI agents can match closed-source models - I ... - Reddit

• 严重度：medium
• 证据强度：source_linked
• 发现：Your self-hosted AI agents can match closed-source models - I ... - Reddit 24 Nov 2025 · Looking for open-source knowledge management tool ... Let's compare 5 Open-Source AI Agent Tools that everyone cannot stop talking about on Reddit.
• 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。
• 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。
• 证据：social_signal:reddit | ssig_4fefa11ceedb46d4af5e2ff44e7709e1 | https://www.reddit.com/r/selfhosted/comments/1p5q8f1/your_selfhosted_ai_agents_can_match_closedsource/ | Your self-hosted AI agents can match closed-source models - I ... - Reddit

12. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | mcp_registry:io.github.Dave-London/npm:0.8.0 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.Dave-London%2Fnpm/versions/0.8.0 | last_activity_observed missing

13. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | mcp_registry:io.github.Dave-London/npm:0.8.0 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.Dave-London%2Fnpm/versions/0.8.0 | no_demo; severity=medium

14. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | mcp_registry:io.github.Dave-London/npm:0.8.0 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.Dave-London%2Fnpm/versions/0.8.0 | no_demo; severity=medium

15. 安全/权限坑 · 来源证据：pare-python tools (pytest/ruff-check/ruff-format) fail "Command not found" when tool is a python module / on user-site…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：pare-python tools (pytest/ruff-check/ruff-format) fail "Command not found" when tool is a python module / on user-site Scripts (Windows)
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_716ce8621d7243deaf982ad0fc944772 | https://github.com/Dave-London/Pare/issues/891 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

16. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | mcp_registry:io.github.Dave-London/npm:0.8.0 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.Dave-London%2Fnpm/versions/0.8.0 | issue_or_pr_quality=unknown

17. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | mcp_registry:io.github.Dave-London/npm:0.8.0 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.Dave-London%2Fnpm/versions/0.8.0 | release_recency=unknown