aegis-mcp

aegis-mcp-server

适用于 Aegis Agent 治理规范的 MCP 执行层。

策略为本。运行时执行。每项操作都有记录。

功能介绍

aegis-mcp-server 是一个 MCP 服务，会在每项 Agent 操作发生之前，根据你的 .agentpolicy/ 文件对其进行验证。路径权限、内容扫描、角色边界、质量门禁——全部在运行时执行，不会增加 Agent 的令牌开销。

Agent 不会加载你的治理文件。MCP 服务会将这些文件读入自身的进程内存并静默验证。Agent 调用受治理的工具后，会收到成功响应，或包含具体原因的阻止响应。

快速开始

# Install globally
npm install -g aegis-mcp-server

如果你使用 aegis-cli 生成了策略，.mcp.json 连接配置已经位于项目根目录中。只需安装 MCP 并打开 Agent，它就会自动连接。

首条提示词

在受治理项目中启动新的 Agent 会话时，将此内容用作首条提示词：

Call aegis_policy_summary now. This is your governance contract — it defines your
role, your boundaries, and which tools to use. Do not take any action until you have
called this tool and received confirmation from the user to proceed.

对于初始构建，Aegis CLI 会生成针对项目定制的交接提示词——请改用该提示词。

工作原理

通用模式（默认）

MCP 启动时不会预先分配角色。当 Agent 调用 aegis_policy_summary 时，会收到可用角色列表，其中包括内置的 construction 角色，以及 .agentpolicy/roles/ 中的所有专用角色。Agent 会向用户展示这些角色，由用户选择，然后 Agent 调用 aegis_select_role 来锁定所选角色。此会话剩余时间内的所有执行操作都会使用所选角色。

这是默认行为——除了 aegis init 自动创建的 .mcp.json 外，无需进行任何配置。

构建模式

初始构建和重大重构时，始终可以使用 construction 角色。选中后：

• Agent 拥有完整的代码库访问权限（所有路径均可读写）
• .agentpolicy/ 文件充当蓝图——Agent 会读取章程、治理和角色文件，以了解项目架构、约定和质量标准
• 为提升速度，文件操作通过原生工具而非受治理的工具执行
• MCP 会将构建会话的开始记录到 state/overrides.jsonl，并附上时间戳和 human_confirmed: true
• 构建完成后，Agent 会调用 aegis_complete_task 运行质量门禁并结束构建模式——结束时间戳会与开始记录一同记入日志
• 构建完成后的所有会话都应选择专用角色来执行受治理的操作

构建模式并非绕过治理——Agent 仍会将治理文件作为蓝图并遵循其中的要求。这是一种针对绿地项目构建的速度优化，因为对每个文件都强制执行写入限制会适得其反。

固定模式

如果你已确定启动时要分配的角色：

{
  "mcpServers": {
    "aegis": {
      "command": "aegis-mcp",
      "args": ["--project", ".", "--role", "backend"]
    }
  }
}

MCP 会立即锁定该角色。aegis_policy_summary 会直接返回该角色的边界，并跳过角色选择。

工具

工具	功能	Token 开销
aegis_policy_summary	角色边界和治理摘要（或通用模式下的可用角色）	~200 tokens
aegis_select_role	在通用模式下选择一个角色（包括构建角色）	极低
aegis_check_permissions	预先检查是否允许某项操作	极低
aegis_write_file	经过治理的写入，并验证路径和内容	与普通写入相同
aegis_read_file	经过治理的读取，并验证路径	与普通读取相同
aegis_delete_file	经过治理的删除，并验证路径	极低
aegis_execute	经过治理的命令执行	仅命令输出
aegis_complete_task	运行质量门禁，并在构建模式处于活动状态时将其关闭	仅门禁结果
aegis_request_override	经人工确认后执行被阻止的操作	极低

零 Token 开销

传统方式：将治理文件加载到 Agent 的上下文窗口中。Token 开销会随策略复杂度增加。

Aegis MCP 方式：服务在自身进程内存中加载策略。Agent 调用工具并获取结构化结果。拥有 200 行治理规则的项目，与拥有 20 行规则的项目，Token 开销相同。复杂性由服务承担，而非 Agent。

强制执行

• 治理边界 — writable、read_only、forbidden 路径列表
• 角色范围限定 — Agent 只能访问其角色的可写和可读路径
• 敏感模式检测 — 根据治理定义的正则表达式模式扫描内容（仅检查内容，不基于路径）
• 跨域边界 — 根据共享接口规则验证导入
• 质量门禁验证 — 将 pre_commit 标志映射到 build_commands 并执行
• 覆盖操作日志 — 每个被阻止的操作都会记录到仅追加的 overrides.jsonl 文件中
• 不可变策略 — 指定规则永远不可覆盖
• 构建会话日志 — 记录初始构建的开始和结束时间戳

覆盖协议

当操作被阻止，且治理覆盖行为为 warn_confirm_and_log 时：

1. 被阻止的响应包含 override_token 和具体违反的策略
2. Agent 向用户说明违规情况
3. 如果用户确认，Agent 使用令牌和用户的理由调用 aegis_request_override
4. 操作继续执行 — 覆盖操作会以 human_confirmed: true 记录
5. 立即恢复正常治理 — 覆盖仅为一次性例外

不可变策略（例如 HIPAA 合规、ITAR 数据主权和审计完整性）会返回 override_available: false，且无法覆盖。用户必须通过 aegis init 修改治理规则。

基于同意的治理

Aegis MCP 不会覆盖 Agent 的原生指令。它通过工具描述介绍自身，解释治理为何处于启用状态，并要求 Agent 征求用户许可，以便通过 Aegis 工具处理写入操作。用户的授权是强制执行机制。

用于读取、搜索和浏览代码库的原生工具无需治理门禁即可正常工作。只有写入、删除和执行操作需要通过 Aegis 路由。

架构

Agent ──→ aegis-mcp-server ──→ File System
              │
              ├── Loads .agentpolicy/ into process memory (once)
              ├── Watches for policy changes (auto-reload)
              ├── Validates every tool call against policy
              ├── Returns success or blocked with override option
              └── Logs all enforcement decisions to overrides.jsonl

三个工件，一个治理框架：

• aegis-spec — 治理标准
• aegis-cli — 生成治理规则
• aegis-mcp-server — 强制执行治理规则

许可证

MIT