Hooks MCP

🚀 コーディングエージェントにMCPを介したリンティング、テスト、フォーマットなどの機能を提供する

このプロジェクトは、コーディングエージェントに対して、MCPを介してリンティング、テスト、フォーマットなどの機能へのアクセスを提供します。1つの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などでの実行方法を含む、より詳細な実行オプションについては、running HooksMCP を参照してください。

✨ 主な機能

1. 簡単なセットアップ：1つのYAMLファイルで、コーディングエージェント用のカスタムMCPサーバーを作成できます。package.jsonのスクリプトやGithub Actionsのワークフローに似ていますが、コマンドはMCP関数によってトリガーされます。このYAMLファイルをリポジトリに追加することで、チームメンバーと共有できます。
2. ツールの自動検出：コーディングエージェントは、利用可能な開発ツールとそれらに必要な正確な引数を認識します。CLI文字列の推測が不要になります。
3. セキュリティの向上：エージェントが実行できるコマンドを制限します。エージェントが生成する引数を検証します（例えば、ファイルパスがプロジェクト内にあることを確認します）。
4. MCPが動作する場所ですべて動作：Cursor、Windsurf、Clineなどで動作します。
5. 高速化：MCPを使用することで並列実行が可能になり、コマンド生成に必要なトークンが減り、反復を必要とするコマンドのエラーが排除されます。
6. その他の機能：ANSIコード/制御文字の除去、.env ファイルの読み込み、コミットせずに必要なシークレットを定義する機能、終了コード/stdout/stderrのサポートなど。

📦 インストール

1. uv を使ってインストールします。

uv tool install hooks-mcp

📚 ドキュメント

設定ファイルの仕様

hooks_mcp.yaml ファイルは、MCPサーバーを介して公開されるツールを定義します。

このプロジェクトの hooks_mcp.yaml を例として参照してください。

トップレベルのフィールド

• server_name（オプション）：MCPサーバーの名前（デフォルト："HooksMCP"）
• server_description（オプション）：MCPサーバーの説明（デフォルト："Project-specific development tools exposed via 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 で使用して、シェルインジェクションを防ぎます。
   • shlex.split を使用して、コマンド引数を適切に分割します。
   • タイムアウトを実装して、無限に実行されるコマンドを防ぎます。

セキュリティリスク

HooksMCPを使用するにはいくつかのリスクがあります。

1. エージェントが hooks_mcp.yaml を編集できる場合、それがMCPを介して実行できるコマンドを追加できます。
2. エージェントがプロジェクトにコードを追加でき、アクションのいずれかが任意のコードを呼び出す場合（テストランナーなど）、エージェントはこのパターンを使用して任意のコードを実行できます。
3. HooksMCPにはバグやセキュリティ問題が含まれている可能性があります。

これが完全であることを約束するわけではありませんが、エージェントに無制限のターミナルアクセスを与えるよりは良いでしょう。エージェントをコンテナ内で実行することを常におすすめします。

📄 ライセンス

MIT