Makefile MCP

Makefile MCP

向 AI Agent 提供可信的 GNU Make 目标，而不暴露通用 shell，也不以其他工作流系统取代 Make。

Makefile MCP 将现有的 Makefile 转换为类型化 MCP 工具。它默认零配置且可安全运行，并且在受管控模式下默认拒绝。

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

威胁模型

设计时假设 Agent 已遭入侵：它读取的任何文本都可能包含提示注入。Makefile MCP 将最坏情况控制在有限范围内。被劫持的 Agent 只能运行你列出的目标，并使用你输入的值；有风险的目标则需要人工批准。请阅读威胁模型，了解威胁、控制措施、验证这些措施的测试以及相关限制。

受保护的内容	不受保护的内容
Agent 无法运行任意 shell 命令，只能运行已公开的 Make 目标。	恶意或有缺陷的 Makefile：其中的配方属于可信代码，不在沙箱中运行。
未配置时，Agent 只能运行 test、lint、check 和 fmt。	操作者选择公开的目标本身可能执行破坏性操作。
受管控模式下，只能运行允许列表中的 (context, target) 组合，并且输入值经过类型检查和验证。	Makefile MCP 之外授予的主机或容器权限。
dangerous 任务需要通过 MCP 客户端获得明确的人工批准；未批准则不运行。	自动批准请求而无需人工介入的 MCP 客户端。
每次受管控的运行尝试（无论被拒绝、批准还是取消）都可以写入审计日志，并屏蔽敏感输入。	配方以不同于输入值的形式打印出来的秘密。
批准提示会显示准确参数；Agent 提供的文本无法改变它。	能编辑未固定版本的 Make 代码或脚本的 Agent：编辑配方就等同于编写 shell 命令。
使用 pin 后，只要 Makefile、其包含文件或列出的脚本有任何改动，服务就会停止，直到人工重启。	Agent 读取的输出中包含的提示注入；agent_output: tail 或 none 可缩小其影响范围。
审计记录采用哈希链；doctor 会报告改动。CI 测试会重放被劫持的 Agent。	同一用户下的进程重写整个日志及其哈希链。

详情请见：威胁模型、SECURITY.md 和安全模型。

快速开始

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

假设：

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

一次性使用：uvx makefile-mcp serve。

Why Makefile MCP

Makefile MCP 有意保持精简：仓库的 Makefile 仍是可执行的事实来源，而 Makefile MCP 则提供受治理、面向 Agent 的能力边界。

原则	含义
Make 保持权威性	不引入重复的工作流 DSL、插件命令语言、调度器、数据库或第二套执行引擎。
不提供通用 Shell 能力	Agent 调用发现的或明确受治理的 Make 目标，而非任意主机命令。
信任 Makefile，不信任调用请求	仓库自动化可信；调用方选择的任务和声明的值需经过授权、验证并受到限制。GNU Make 自身的变量／函数语义被视为解释器边界。
单一执行路径	CLI、直接 MCP 工具、通用 MCP 工具、预览、上下文和能力共用同一目录、授权、验证和执行器。
保守发现	Makefile MCP 仅静态公开其能够有把握分类的 Make 语法；对有歧义的构造不做猜测，直接省略。
受限的 Unix 运行时	前台执行具有受限的输入／输出、超时／取消清理、stdin 隔离、进程组处理和物理上下文锁定。

请参阅设计原理，了解完整的能力／属性映射，以及有意未纳入的替代方案。

架构

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

一个目录。一条执行路径。精简的 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。请参阅受治理模式、配置以及上下文与能力。

MCP 呈现方式

Makefile MCP 支持通过同一个可调用目录提供三种 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 进行沙箱隔离。

运行时限制、取消／进程组清理、stdin 隔离和锁定主要是执行正确性属性。它们用于限制可信自动化可能出现的故障模式，而不是将 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 服务、认证栈、调度器、作业队列、工作流持久化、插件执行框架或任意 Shell 工具。
• 重新加载行为：
  • .makefile-mcp.yaml 是启动策略。添加、移除或编辑该文件后，请重启 Makefile MCP。
  • 当约定的 Makefile 或受跟踪的字面包含项发生变更时，Makefile 发现结果会刷新。
  • 通用调用会立即看到刷新的目录。
  • 直接工具清单是启动时的快照：添加或移除直接工具需要重启。调用现有的直接工具时，仍会重新检查实时目录。

要求

Python 3.11+ · GNU Make · Linux 或 macOS

文档

1. 威胁模型 — 为什么不应给 Agent 提供 shell、威胁与控制措施、策略和审计日志、保证与限制。从这里开始。
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。