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 許可證。