Warden MCP

MCP管理员

Warden MCP是一个用于编码代理的计划治理MCP服务器。它使代理遵守具体的执行计划，明确进度，并通过完成关卡检查阻止过早的“完成”索赔。

Claude Code、Auggie和大多数编码代理的最快设置

如果你只想为支持MCP的编码代理进行最简单的本地安装，请使用npm：

npm install -g warden-mcp
warden-mcp health

然后添加此MCP服务器条目：

{
  "mcpServers": {
    "warden": {
      "command": "warden-mcp",
      "args": []
    }
  }
}

客户端连接后，按顺序调用这些工具：

1. get_agent_guide
2. health_check
3. get_status

如果您的客户端支持Claude Code风格的本地MCP配置，则相同 warden-mcp 入口也应该在那里工作。这包括直接使用Claude Code和与Claude兼容的设置，如Auggie风格的本地MCP流。

安装

Claude Code插件市场（git仓库）

如果你更喜欢Claude Code的插件流，这个存储库会提供一个repo根插件和市场入口。

1. 在Claude Code中，运行 /plugin marketplace add https://github.com/Blu3Ph4ntom/warden-mcp
2. 打开 /plugin，安装 warden-mcp，并为您的项目或会话启用它

该插件启动Warden npx -y warden-mcp，因此Claude Code在首次运行时下载已发布的npm包，而不需要单独的全局安装。

此插件现在为Claude Code和兼容客户端提供了三层：

• MCP工具服务器(.mcp.json)
• 生命周期挂钩(hooks/hooks.json)用于强制完成门控
• 便利命令文件(commands/warden-start.md, commands/warden-next.md, commands/warden-finish.md)

钩子是重要的部分： Stop，客户打电话给典狱长的终点门，在所需工作完成时被阻止停车。

共享市场挂钩配置有意使用保守的事件子集，该子集也在Augment兼容的客户端中加载。更丰富的克劳德生命周期事件，如 TaskCompleted 和 SubagentStop 不被视为可移植默认值。

为了获得最可靠的强制模式，请确保 warden-mcp 也可以在您的 PATH （例如通过 npm install -g warden-mcp 或释放的二进制文件）。钩子先试试当地的 warden-mcp 二进制，只能回退到 npx -y warden-mcp 如果需要的话。

安装或更新插件后，重新启动Claude Code，以便重新加载钩子配置。

推荐给大多数编码代理用户：npm

这是Claude Code、Auggie、Cursor、Windsurf、Codex和其他本地MCP客户端最简单的路径。

npm install -g warden-mcp

验证安装：

warden-mcp health

通过Go进行本地安装

先决条件：转到1.24+

go install github.com/Blu3Ph4ntom/warden-mcp/cmd/warden-mcp@latest

然后确保您的Go bin目录已打开 PATH 并验证二进制文件是否可用：

warden-mcp health

通过npm原生安装

如果你更喜欢通过npm安装，发布的包会下载正确的原生包 warden-mcp 在安装过程中为您的平台提供二进制文件。

npm install -g warden-mcp

或者：

npx warden-mcp health

现在这是一个 真实的本地安装路径npm用户不需要Go，但安装程序确实需要对包版本的匹配GitHub Release资产进行网络访问。

编码代理快速入门

1. 安装 warden-mcp 使用npm或Go。
2. 添加 warden-mcp 作为客户端配置中的本地MCP服务器。
3. 如果您的客户可以设置环境变量，请设置 WARDEN_WORKSPACE_ROOT 到您的repo根目录。
4. 连接后，呼叫 get_agent_guide那么 health_check那么 get_status.

如果你的客户端还没有自定义的启动流程，那么这个流程运行良好：

{ "command": "warden-mcp", "args": [] }

MCP管理员提供什么

• 严格的计划初始化和验证
• 任务更新和下一步选择
• 重置、优先级排序和对账流程
• 允许在完工前完成大门执法
• 计划导入/导出/存档实用程序

监狱长与MCP交谈 标准，因此大多数本地MCP客户端都可以通过简单的命令项启动它：

{ "command": "warden-mcp", "args": [] }

当在没有CLI参数的情况下启动时， warden-mcp 现在默认为MCP服务器(serve)模式，因此本地MCP客户端可以直接调用该命令。

工具表面

当前的公共MCP工具有：

• init_plan, health_check, get_agent_guide, validate_plan, edit_plan
• get_status, get_next_task, prioritize_tasks
• update_task, reset_task, request_finish
• list_plans, import_plan, export_plan, archive_plan
• reconcile_plan

对于大多数客户来说，连接后的第一个帮助电话是 get_agent_guide 或 health_check，随后 get_status.

典型工作流程

1. 安装 warden-mcp 并将其连接为MCP服务器。
2. 跑 get_agent_guide 或 health_check那么 get_status，以确认活动计划上下文。
3. 使用创建或导入计划 init_plan 或 import_plan.
4. 使用 get_next_task 和 update_task 随着工作的进展。
5. 使用 validate_plan 和 reconcile_plan 经过手动编辑或漂移后。
6. 呼叫 request_finish 只有当计划真正完成时。

默认情况下，存储库计划通常位于 .agent/PLAN.md.

如果 warden-mcp 从不安全的操作系统目录（如Windows）启动 System32，它现在失败关闭，而不是默默地重用共享回退工作区。在编码代理设置中，设置 WARDEN_WORKSPACE_ROOT 到您的项目根目录，这样计划解决方案就固定在仓库中。如果您故意需要非代理工作流的传统共享回退，请选择 WARDEN_ALLOW_UNSAFE_WORKSPACE_FALLBACK=1.

如果MCP客户端发送了从不安全的操作系统目录扩展的虚假绝对默认计划路径，例如 C:\\Windows\\System32\\.agent\\PLAN.md，管理员将忽略不安全的绝对默认值，并解决活动工作区计划路径。

MCP客户端设置示例

克劳德代码(.mcp.json)

这是Claude Code本地MCP使用的主要复制/粘贴设置：

如果您从上面的Claude市场流程安装了repo插件，则可以跳过此手动配置并使用该插件。

如果你想要没有市场插件的硬完成护栏，请在下面添加MCP服务器配置，并复制仓库的 hooks/ 在Claude项目/插件设置目录中。仅MCP是咨询性的；钩子是用来执行的 request_finish 在停止之前。

{
  "mcpServers": {
    "warden": {
      "command": "warden-mcp",
      "args": []
    }
  }
}

如果Claude Code允许您为服务器附加环境变量，这是最安全的仓库本地变量：

{
  "mcpServers": {
    "warden": {
      "command": "warden-mcp",
      "args": [],
      "env": {
        "WARDEN_WORKSPACE_ROOT": "${workspaceFolder}"
      }
    }
  }
}

Auggie/Claude兼容的本地MCP设置

如果Auggie使用与Claude Code兼容的本地MCP流，请使用相同的 warden-mcp 命令输入如上所示。重要的部分仍然是：

{ "command": "warden-mcp", "args": [] }

如果Auggie公开了MCP服务器的环境变量，请设置 WARDEN_WORKSPACE_ROOT 这样Warden就可以将活动计划存储在仓库中，而不会重用另一个工作区的活动计划。

在Auggie中，预期Warden将显示为MCP工具/函数，而不是斜线命令。使用工具调用，如 get_agent_guide, health_check，以及 get_status.

硬停止拦截需要类似于Claude Code的生命周期钩子 Stop 挂钩支撑。增强兼容客户端似乎接受 SessionStart 和 Stop，但不是每个Claude特定的生命周期事件。如果客户端完全缺乏停止拦截，它可以使用Warden工具，但不能完全强制遵守完成门。

Claude代码强制模式行为

当插件挂钩处于活动状态时，Claude Code应该：

1. 注入一个启动提醒，表明监狱长执法处于活动状态，
2. 呼叫监狱长 Stop,
3. 阻止完成，如果 request_finish 说 can_finish: false，以及
4. 把克劳德推回下一个需要完成的任务。

如果您希望在自动执行之外还有一个可见的引导路径，请在安装后使用插件的Warden命令文件。

如果执法似乎不活跃：

• 插件更新后重启Claude Code，
• 运行带有调试日志的Claude Code并检查加载的钩子，
• 确认 warden-mcp health --plan .agent/PLAN.md 在你的壳中工作，
• 如果没有，请安装 warden-mcp 全局或将发布的二进制文件放在您的 PATH.

Codex CLI(~/.codex/config.toml)

[mcp_servers.warden]
command = "warden-mcp"
args = []

光标(mcp.json 服务器条目）

{
  "warden": {
    "command": "warden-mcp",
    "args": []
  }
}

风帆冲浪(mcp_config.json)

{
  "mcpServers": {
    "warden": {
      "command": "warden-mcp",
      "args": []
    }
  }
}

OpenCode(opencode.json)

{
  "mcp": {
    "warden": {
      "type": "local",
      "command": ["warden-mcp"]
    }
  }
}

通用/自定义MCP JSON

{
  "mcpServers": {
    "warden": {
      "command": "warden-mcp",
      "args": []
    }
  }
}

如果您的客户端支持环境变量，请以该客户端的本机格式将它们与命令一起添加。

对于基本上任何具有本地MCP支持的编码代理，服务器合同都是相同的：

{ "command": "warden-mcp", "args": [] }

建议安装后的首次调用始终是：

• get_agent_guide
• health_check
• get_status

释放包装

对于每个npm版本，首先发布匹配的GitHub release资产：

• warden-mcp__windows_amd64.exe
• warden-mcp__windows_arm64.exe
• warden-mcp__darwin_amd64
• warden-mcp__darwin_arm64
• warden-mcp__linux_amd64
• warden-mcp__linux_arm64
• warden-mcp__checksums.txt

使用以下命令从repo根生成它们：

npm run build:release

故障排除

• warden-mcp: command not found：确保您的Go bin目录已打开 PATH，然后使用验证安装 warden-mcp health.
• npm install无法获取本机二进制文件：run npm rebuild warden-mcp 或者在发布匹配的GitHub Release资产后重新安装。
• 客户端打开了错误的工作区或将计划存储在repo:set之外 WARDEN_WORKSPACE_ROOT 到MCP服务器配置中的项目根目录。Warden现在默认拒绝不安全的发射根，而不是回到共享的家庭工作区。
• Auggie或其他兼容Claude的客户端请求本地MCP命令：use warden-mcp 没有参数。
• 客户端已连接，但工作流程似乎不清楚：运行 get_agent_guide那么 health_check那么 get_status，并确保存储库具有有效的计划文件。
• 手动计划编辑导致漂移：使用 validate_plan 和 reconcile_plan 在继续之前。

发展

从存储库根目录：

go test ./...
npm test
npm run build:release

许可证

麻省理工学院