Hooks MCP

🚀 编码代理MCP访问工具

本项目可让编码代理MCP访问代码检查、测试、格式化等功能，只需一个YAML文件即可实现。

🚀 快速开始

1. 使用 uv 进行安装：

uv tool install hooks-mcp

2. 在项目根目录创建一个 文件，用于定义你的工具。例如：

actions:
  - name: "all_tests"
    description: "Run all tests in the project"
    command: "uv run python -m pytest ./tests"
    
  - name: "check_format"
    description: "Check if the source code is formatted correctly"
    command: "uvx ruff format --check ."
    
  - name: "typecheck"
    description: "Typecheck the source code"
    command: "uv run pyright ."

  - name: "test_file"
    description: "Run tests in a specific file or directory"
    command: "python -m pytest $TEST_PATH"
    parameters:
      - name: "TEST_PATH"
        type: "project_file_path"
        description: "Path to test file or directory"

3. 启动服务器：

uvx hooks-mcp

有关更多运行时选项，包括如何在 Cursor、Windsurf 等中运行，请参阅 运行 HooksMCP。

✨ 主要特性

1. 设置简单：只需一个 YAML 文件，就能为你的编码代理创建一个自定义的 MCP 服务器。类似于 package.json 脚本或 Github Actions 工作流，但命令由 MCP 函数触发。将 YAML 文件添加到你的仓库，即可与团队共享。
2. 工具发现：编码代理可以了解哪些开发工具可用，以及它们所需的确切参数。无需再猜测 CLI 字符串。
3. 增强安全性：限制代理可以运行的命令。验证代理生成的参数（例如，确保文件路径在项目内部）。
4. 广泛适用：可在任何支持 MCP 的地方使用，如 Cursor、Windsurf、Cline 等。
5. 速度提升：使用 MCP 可以实现并行执行，生成命令所需的令牌更少，并消除需要迭代的命令中的错误。
6. 其他特性：去除 ANSI 代码/控制字符、加载 .env 文件、定义所需的机密信息而无需提交、支持退出代码/标准输出/标准错误等。

📦 安装指南

安装步骤如下：

1. 使用 uv 进行安装：

uv tool install hooks-mcp

2. 在项目根目录创建一个 hooks_mcp.yaml 文件。
3. 启动服务器：

uvx hooks-mcp

💻 使用示例

基础用法

以下是一个简单的 hooks_mcp.yaml 文件示例：

actions:
  - name: "all_tests"
    description: "Run all tests in the project"
    command: "uv run python -m pytest ./tests"
    
  - name: "check_format"
    description: "Check if the source code is formatted correctly"
    command: "uvx ruff format --check ."
    
  - name: "typecheck"
    description: "Typecheck the source code"
    command: "uv run pyright ."

  - name: "test_file"
    description: "Run tests in a specific file or directory"
    command: "python -m pytest $TEST_PATH"
    parameters:
      - name: "TEST_PATH"
        type: "project_file_path"
        description: "Path to test file or directory"

📚 详细文档

配置文件说明

hooks_mcp.yaml 文件用于定义通过 MCP 服务器公开的工具。 可参考本项目的 hooks_mcp.yaml 作为示例。

顶级字段

• server_name（可选）：MCP 服务器的名称（默认："HooksMCP"）
• server_description（可选）：MCP 服务器的描述（默认："通过 MCP 公开的特定于项目的开发工具"）
• actions（必需）：操作定义数组

操作字段

actions 数组中的每个操作可以有以下字段：

• name（必需）：工具的唯一标识符
• description（必需）：工具功能的可读描述
• command（必需）：要执行的 CLI 命令。可以包含动态参数，如 $TEST_FILE_PATH。
• parameters（可选）：命令中使用的每个参数的定义。
• run_path（可选）：命令应从项目根目录开始执行的相对路径。对于单仓库项目很有用。
• timeout（可选）：命令执行的超时时间（秒）（默认：60 秒）

参数字段

操作的 parameters 数组中的每个参数可以有以下字段：

• name（必需）：要替换到命令中的参数名称。例如 TEST_FILE_PATH。
• type（必需）：以下参数类型之一：
  • project_file_path：项目内的本地路径，相对于项目根目录。经过验证，确保它在项目边界内且存在。
  • required_env_var：服务器启动前必须设置的环境变量。调用模型不指定。
  • optional_env_var：可选的环境变量。调用模型不指定。
  • insecure_string：来自模型的任何字符串。不进行验证。使用时需谨慎。
• description（可选）：参数的可读描述
• default（可选）：参数的默认值

参数类型解释

project_file_path

这种参数类型通过验证路径是否在项目边界内来确保安全性：

- name: "test_file"
  description: "Run tests in a specific file"
  command: "python -m pytest $TEST_FILE"
  parameters:
    - name: "TEST_FILE"
      type: "project_file_path"
      description: "Path to test file"
      default: "./tests"

服务器将验证 TEST_FILE 是否在项目内且存在。

required_env_var

这些参数必须在服务器启动前在环境中设置。如果未设置，服务器将在启动时失败，并要求用户设置这些变量。

- name: "deploy"
  description: "Deploy the application"
  command: "deploy-tool --key=$DEPLOY_KEY"
  parameters:
    - name: "DEPLOY_KEY"
      type: "required_env_var"
      description: "Deployment key for the service"

HooksMCP 将从环境中加载环境变量，以及工作目录中的 .env 文件中设置的任何变量。

optional_env_var

与 required_env_var 类似，但为可选：

- name: "build"
  description: "Build the application"
  command: "build-tool"
  parameters:
    - name: "BUILD_FLAGS"
      type: "optional_env_var"
      description: "Additional build flags"

insecure_string

允许来自编码助手的任何字符串输入，不进行验证。使用时需谨慎：

- name: "grep_code"
  description: "Search code for pattern"
  command: "grep -r $PATTERN src/"
  parameters:
    - name: "PATTERN"
      type: "insecure_string"
      description: "Pattern to search for"

运行 HooksMCP

建议使用 uvx 运行 HooksMCP：

# 安装
uv tool install hooks-mcp
# 运行
uvx hooks-mcp 

可选的命令行参数包括：

• --working-directory/-wd：通常是项目根目录的路径。如果不是从项目根目录运行，则需要设置。
• 最后一个参数是 hooks_mcp.yaml 文件的路径，如果不使用默认的 ./hooks_mcp.yaml。

与编码助手一起运行

Cursor

或者打开 此 Cursor 深度链接。

Windsurf/VSCode 等

大多数其他 IDE 使用 mcp.json 的变体。为 HooksMCP 创建一个条目。 注意：确保从项目根目录运行，或者在启动时手动传递工作目录：

{
  "HooksMCP": {
    "command": "uvx",
    "args": [
      "hooks-mcp",
      "--working-directory",
      "."
    ]
  }
}

🔧 技术细节

安全特性

安全优势

HooksMCP 实现了多项安全措施，有助于提高为代理提供终端命令访问的安全性：

1. 命令白名单：你的代理只能运行 hooks_mcp.yaml 中允许的命令，而不是任意的终端命令。
2. 路径参数验证：所有 project_file_path 参数都经过验证，以确保它们：
   • 在项目目录内
   • 在项目中实际存在
3. 环境变量控制：
   • required_env_var 和 optional_env_var 参数由开发人员管理，而不是编码助手。这可以防止编码助手访问敏感变量。
4. 安全命令执行：
   • 使用 Python subprocess.run 并设置 shell=False 以防止 shell 注入
   • 使用 shlex.split 正确分隔命令参数
   • 实现超时机制以防止命令无限运行

安全风险

使用 HooksMCP 存在一些风险：

1. 如果你的代理可以编辑 hooks_mcp.yaml，它可以添加命令，然后通过 MCP 运行这些命令。
2. 如果你的代理可以向项目中添加代码，并且你的任何操作将调用任意代码（如测试运行器），代理可以使用此模式运行任意代码。
3. HooksMCP 可能包含错误或安全问题。

我们不能保证它是完美的，但它可能比给代理无限制的终端访问要好。建议在容器内运行代理。

起源故事

我为自己构建 Kiln 时开发了这个项目。初稿由 Qwen-Coder-405b 编写，然后由我进行编辑。有关提示信息，请参阅 初始提交。

📄 许可证

本项目采用 MIT 许可证。