Hooks_mcp

开发 Python

🚀 编码代理MCP访问工具

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

🚀 快速开始

使用 uv 进行安装：

uv tool install hooks-mcp

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

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"

启动服务器：

uvx hooks-mcp

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

✨ 主要特性

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

📦 安装指南

安装步骤如下：

使用 uv 进行安装：

uv tool install hooks-mcp

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

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 实现了多项安全措施，有助于提高为代理提供终端命令访问的安全性：

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

安全风险

使用 HooksMCP 存在一些风险：

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

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

起源故事

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

📄 许可证

本项目采用 MIT 许可证。

0 条评论
分类：开发