Makefile MCP

Makefile MCP

信頼できる GNU Make のターゲットを AI エージェントに公開します。汎用シェルを公開したり、Make を別のワークフローシステムに置き換えたりすることはありません。

Makefile MCP は、既存の Makefile を型付き MCP ツールに変換します。設定不要で、デフォルトでは安全に実行でき、ガバナンスを設定した場合はデフォルトで拒否します。

Makefile  →  Makefile MCP  →  Codex / Claude / LangChain / Cursor / VS Code / MCP client

脅威モデル

エージェントが侵害されたケースを想定して設計されています。エージェントが読み取るテキストには、プロンプトインジェクションが含まれている可能性があります。Makefile MCP は、最悪のケースを限定的なものにします。乗っ取られたエージェントが実行できるのは、指定したターゲットだけです。値はユーザーが入力したものに限られ、リスクの高いターゲットには人間の承認が必要です。脅威、対策、それを証明するテスト、制限については、脅威モデルをお読みください。

保護される内容	保護されない内容
エージェントは任意のシェルコマンドを実行できず、公開された Make ターゲットのみ実行できます。	悪意のある Makefile や不具合のある Makefile。レシピは信頼されたコードであり、サンドボックス化されません。
設定がない場合、エージェントが実行できるのは test、lint、check、fmt のみです。	オペレーターが公開対象に選んだターゲットが、破壊的な処理を行うこと。
ガバナンスモードでは、型付きで検証済みの入力を使い、許可リストに登録された (context, target) の組み合わせのみ実行されます。	Makefile MCP の外部で付与されたホストまたはコンテナーの権限。
dangerous タスクには、MCP クライアントを介した明示的な人間の承認が必要です。承認がなければ実行されません。	人間の承認なしに確認要求を自動承認する MCP クライアント。
拒否、承認、キャンセルを含む、ガバナンス対象のすべての実行試行を監査ログに記録できます。秘密の入力値はマスキングされます。	入力値と異なる方法でレシピが出力する秘密情報。
承認プロンプトには正確な引数が表示されます。エージェントが指定したテキストによって内容が変更されることはありません。	固定されていない Make コードやスクリプトを編集できるエージェント。レシピを編集することは、シェルを編集するのと同じです。
pin を指定すると、Makefile、そのインクルードファイル、または一覧にあるスクリプトに変更が加わった場合、人間がサーバーを再起動するまでサーバーは停止します。	エージェントが読み取る出力に含まれるプロンプトインジェクション。agent_output: tail または none にすると、その影響を抑えられます。
監査記録はハッシュチェーンで保護され、doctor が編集を報告します。CI テストでは、乗っ取られたエージェントの動作を再現します。	同じユーザー権限で動作するプロセスが、ログ全体とそのチェーンを書き換えること。

詳細については、脅威モデル、SECURITY.md、セキュリティモデルをご覧ください。

クイックスタート

pipx install makefile-mcp        # or: uv tool install makefile-mcp
makefile-mcp serve

次の Makefile があるとします。

test: ## Run tests
	pytest -q

lint: ## Run lint
	ruff check .

Makefile MCP は、make_test と make_lint を MCP ツールとして公開します。ほかのターゲットも一覧表示されますが、ガバナンスを設定するまでは実行できません。

makefile-mcp list
makefile-mcp doctor
makefile-mcp run test
makefile-mcp run test --preview   # GNU Make --dry-run; not a sandbox

1 回だけ使う場合は、uvx makefile-mcp serve を実行します。

Makefile MCPを選ぶ理由

Makefile MCPは意図的に対象を絞っています。リポジトリのMakefileを実行可能な信頼できる情報源として維持しながら、Makefile MCPはエージェント向けの機能境界をガバナンスします。

原則	意味
Makeが引き続き権威ある情報源です	ワークフロー用DSL、プラグインコマンド言語、スケジューラー、データベース、または2つ目の実行エンジンを重複して導入しません。
汎用的なシェル機能はありません	エージェントが実行するのは、検出された、または明示的にガバナンスされたMakeターゲットであり、任意のホストコマンドではありません。
Makefileは信頼され、呼び出しは信頼されません	リポジトリの自動化は信頼しますが、呼び出し側が選択したタスクと宣言された値は、認可、検証、制限されます。GNU Make独自の変数／関数のセマンティクスは、インタープリター境界として扱います。
実行経路は1つです	CLI、直接MCPツール、汎用MCPツール、プレビュー、コンテキスト、機能で、同じカタログ、認可、検証、実行機能を共有します。
保守的に検出します	Makefile MCPは、自信を持って分類できるMake構文のみを静的に公開します。曖昧な構文は推測せず、除外します。
Unixランタイムに制限を設けます	フォアグラウンド実行では、入力／出力の制限、タイムアウト／キャンセル時のクリーンアップ、標準入力の分離、プロセスグループの処理、物理コンテキストのロックを行います。

機能／プロパティの全体像と、意図的に採用しなかった代替案については、設計の根拠を参照してください。

アーキテクチャ

                         Makefile
                            |
                    conservative catalog
                            |
              +-------------+-------------+
              |                           |
            auto                       governed
         no config                   .makefile-mcp.yaml
              |                           |
              +-------------+-------------+
                            |
                       Application
                  +---------+---------+
                  |                   |
              MCP direct         MCP generic
                  +---------+---------+
                            |
                         Executor
                            |
                      exact `make -f`

カタログは1つ。実行経路は1つ。CLIとMCPアダプターは薄く保たれています。

アーキテクチャを参照してください。

ガバナンスモード

.makefile-mcp.yamlがない場合、Makefile MCPは自動モードで実行されます。保守的に検出されたすべてのルートターゲットが一覧表示されますが、実行できるのはtest、lint、check、fmtのみで、呼び出し側が制御できるMake変数はありません。--legacy-auto-runを指定すると、従来のすべて実行する動作に戻ります（非推奨）。

明示的なガバナンスに切り替えるには、.makefile-mcp.yamlを追加します。

schema_version: 1

contexts:
  backend:
    directory: backend

tasks:
  test:
    contexts: [root, backend]
    risk: safe

  deploy:
    risk: dangerous
    variables:
      ENV:
        type: enum
        values: [staging, production]
        required: true

capabilities:
  verify: test

audit:
  path: .makefile-mcp/audit.jsonl

pin:
  paths: [scripts]       # freeze Make code and scripts the agent must not change

有効化された(context, target)の組み合わせのみ呼び出せます。dangerousタスクには、追加で人による承認（defaults.require_approval）が必要です。また、auditは呼び出しごとにJSONを1行書き込みます。ガバナンスモード、設定、コンテキストと機能を参照してください。

MCPの提示方法

Makefile MCPは、同じ呼び出し可能なカタログを基に、3種類のMCPの提示方法をサポートしています。要件に最も合う提示方法を選択してください。

makefile-mcp serve --tools direct    # default: one typed tool per callable target
makefile-mcp serve --tools generic   # list_tasks / describe_task / run_task
makefile-mcp serve --tools both      # both views, same execution core

MCPの提示方法とクライアントの設定を参照してください。

セキュリティ

Makefile MCPでは、リポジトリ、Makefile、インクルードされたMakeコード、ラッパースクリプト、プロビジョニング済みツールは、信頼できるオペレーター管理のコードであると想定しています。セキュリティ境界となるのは呼び出しです。MCP／CLIの呼び出し側は、公開されたタスク／コンテキストを選択し、ガバナンスモードでは宣言済みの値を指定します。Makefile MCPはそのリクエストを認可して検証しますが、敵対的なMakefileをサンドボックス化するものではありません。

ランタイムの制限、キャンセル／プロセスグループのクリーンアップ、標準入力の分離、ロックは、主に実行の正確性を確保するためのものです。これらは、Makeをサンドボックス化するものではなく、信頼された自動化に関する障害モードを制限します。組み込みのMCPサーバーはstdio専用です。HTTPリスナー、リモート認証レイヤー、TLS、テナント機能、ネットワークサービスのライフサイクルは、製品内に隠されていません。

セキュリティポリシー、報告手順、信頼境界、制限については、**SECURITY.md**を参照してください。実装に関する詳細はdocs/security.mdに記載されています。

意図的なスコープ制限

• Linux/macOS 上の GNU Make が対象です。Windows は現在サポートされていません。
• 信頼できるリポジトリを前提とします。Makefile、インクルードファイル、スクリプト、プロビジョニングされたツールは、運用者が管理するコードです。
• 静的な検出は意図的に保守的であり、GNU Make の完全なパーサーではありません。
• プレビューは GNU Make のドライランであり、サンドボックス化ではありません。Make の評価によって、引き続き副作用が発生する可能性があります。
• 直接ツールの一覧は起動時に登録されます。汎用カタログの呼び出しでは、サポート対象の Makefile の変更を確認できます。
• .makefile-mcp.yaml は起動時のポリシーです。変更を反映するには再起動が必要で、それまではフェイルクローズします。
• 前景で実行されるタスクと、実行時間が制限されたタスクのみが対象です。意図的にデタッチされたデーモンは、Makefile MCP のプロセスグループによる封じ込めモデルの対象外です。
• HTTP サーバー、認証スタック、スケジューラー、ジョブキュー、ワークフローの永続化、プラグイン実行フレームワーク、任意のシェルツールはありません。
• 再読み込みの動作：
  • .makefile-mcp.yaml は起動時のポリシーです。追加、削除、編集した場合は、Makefile MCP を再起動してください。
  • 慣例的な Makefile または追跡対象のリテラルなインクルードが変更されると、Makefile の検出情報が更新されます。
  • 汎用の呼び出しでは、更新されたカタログが直ちに反映されます。
  • 直接ツールの一覧は起動時のスナップショットです。直接ツールの追加や削除には再起動が必要です。既存の直接ツールは、呼び出し時にライブカタログを再確認します。

要件

Python 3.11+ · GNU Make · Linux または macOS

ドキュメント

1. 脅威モデル — エージェントにシェルを使わせるべきでない理由、脅威と対策、ポリシーと監査ログ、保証と制限について説明します。まずはこちらをご覧ください。
2. アーキテクチャ — 実行時のフロー、責任範囲、ライフサイクル、不変条件、依存関係のルールについて説明します。
3. 設計の根拠 — 主要なトレードオフ、製品特性の全体像、意図的に採用しなかった代替案について説明します。
4. CLI リファレンス — コマンド、オプション、結果モデル、ルートの検出、終了コードについて説明します。
5. 設定 — .makefile-mcp.yaml の正式なフィールド、デフォルト値、承認、監査ログ、優先順位について説明します。
6. Make の静的検出 — サポートされる構文、フェイルクローズ動作、インクルード、制限、キャッシュのセマンティクスについて説明します。
7. ガバナンスモード — 明示的な公開、型付き入力、リスクメタデータ、人間による承認、運用モデルについて説明します。
8. MCP の提示形式 — direct、generic、both、スキーマ、結果とエラーのセマンティクス、命名、ライフサイクルについて説明します。
9. コンテキストと機能 — モノレポのスコープ設定、(context, target) の認可、セマンティックマッピングについて説明します。
10. MCP クライアントのセットアップ — Codex、Claude Code、LangChain/LangGraph、Cursor、VS Code、uvx の例を紹介します。
11. セキュリティ — 信頼境界、Make 入力の安全性、任意の文字列、検出、環境とパスの制御、実行範囲について説明します。
12. 開発 — コントリビューターのワークフロー、コードオーナーシップ、リグレッションに関する期待事項、完了の定義について説明します。
13. デプロイ — Docker/stdio によるデプロイ、本番環境のチェックリスト、カスタムツールと Makefile のプロビジョニングについて説明します。
14. リリース — バージョンとタグの契約、クリーンパッケージのスモークテスト、PyPI Trusted Publishing、プロベナンス、GitHub Releases、MCP Registry のメタデータについて説明します。

セキュリティに関する報告：SECURITY.md。 コントリビューション：CONTRIBUTING.md。