Evolith Architecture Governance

@beyondnet/evolith-mcp

Evolith MCP Gateway — 一流的模型上下文协议服务

双语导航： 西班牙语版本

将 MCP 服务与 CLI 解耦。它是一款一流的产品，将 MCP 工具作为 Gateway 暴露，并与 @beyondnet/evolith-core（可复用的业务逻辑层）通信，而不是通过 Shell 调用 CLI 子进程。

---

目录

1. 架构图
2. 传输方式
3. 安装和配置
4. 身份验证
5. 可用工具（55）
6. 可用资源（12 + 动态资源）
7. 可用提示词（8）
8. 变更操作
9. 内部架构
10. Agent 使用场景
11. 客户端配置
12. SmartCLI 集成
13. 扩展指南
14. 可观测性
15. 最佳实践
16. 故障排除

---

架构图

sequenceDiagram
    participant Agent as "AI Agent<br/>(Cursor, Claude Desktop, Custom)"
    participant Gateway as "MCP Gateway<br/>@beyondnet/evolith-mcp"
    participant Core as "Business Logic<br/>@beyondnet/evolith-core"
    participant FS as "File System"
    participant Git as "Git"

    Note over Agent,Gateway: Transport: stdio (local) or Streamable HTTP (remote)

    Agent->>+Gateway: tools/call { name: "evolith-validate", args: { path: "/repo" } }

    Gateway->>Gateway: 1. Generate correlationId (evl-xxx)
    Gateway->>Gateway: 2. Lookup tool in ToolRegistry
    Gateway->>Gateway: 3. ABAC authorization check
    Gateway->>Gateway: 4. Start timing + structured log (Pino)

    Gateway->>+Core: ValidateSatelliteUseCase.execute({ satellitePath })
    Core->>+FS: Read evolith.yaml, rulesets/
    FS-->>-Core: Configuration + rule definitions

    Core->>+Git: Check ADR history, phase state
    Git-->>-Core: Phase & commit data

    Core->>Core: Evaluate rules (Native + OPA)
    Core-->>-Gateway: ValidationResult { status, issues }

    Gateway->>Gateway: 5. Wrap in SuccessEnvelope { success, data, meta }
    Gateway->>Gateway: 6. Audit log + completion duration

    Gateway-->>-Agent: { content: [{ type: "text", text: "{...}" }] }

    Note over Agent,Gateway: All errors wrapped in ErrorEnvelope with EvolithErrorCode

---

传输方式

传输方式	用途	命令
stdio（JSON-RPC 2.0）	本地 Agent、Cursor、Claude Desktop	evolith-mcp serve
Streamable HTTP（官方 MCP SDK）	远程 Agent、可扩展性	evolith-mcp serve --transport http --port 49100

默认端口为 3000（main.ts：使用 env PORT 或 --port，未设置时回退到 3000）。示例中使用的 49100 是任意值，并非默认端口。

日志始终写入 stderr（Pino），因为 stdout 保留给 stdio 传输的 JSON-RPC 流。

---

安装和配置

安装

# From the monorepo
npm install @beyondnet/evolith-mcp

# Or globally
npm install -g @beyondnet/evolith-mcp

用法

# stdio (default) — for Cursor, Claude Desktop, etc.
evolith-mcp serve

# HTTP — for remote integration
evolith-mcp serve --transport http --port 49100

环境变量

变量	默认值	描述
TRANSPORT	stdio	活动传输方式：stdio 或 http
PORT	3000	HTTP 传输的端口
MCP_HTTP_HOST	0.0.0.0	HTTP 服务的绑定主机。仅本地使用时，请使用 127.0.0.1
EVOLITH_API_KEY	—	HTTP 传输的身份验证 API 密钥
EVOLITH_MCP_ALLOW_NO_AUTH	false	仅限 HTTP。 允许 HTTP 在没有 API 密钥的情况下启动（仅限非生产环境）。在 production 环境和 stdio 传输中会被忽略（启动时会发出警告）
JWT_SECRET	—	可选密钥；除 API 密钥外，还用于验证 Bearer JWT（HS256）
NODE_ENV	development	在 production 环境中，HTTP 必须启用身份验证
LOG_LEVEL	info	Pino 日志级别：trace、debug、info、warn、error
REDIS_URL	—	资源缓存的 Redis URL（例如 redis://localhost:6379）。缓存为可选项。
OTEL_EXPORTER_OTLP_ENDPOINT	—	用于追踪的 OpenTelemetry 端点
OTEL_SERVICE_NAME	evolith-mcp	追踪中使用的服务名称
EVOLITH_MCP_REQUEST_STATE_SECRET	—	用于签署 MRTR requestState 的密钥（2026-07-28 路径）。依次回退到 EVOLITH_API_KEY、JWT_SECRET，最后使用进程级密钥。只要运行多个副本，就必须显式设置此项；否则，落到其他副本上的审批重试请求会被拒绝
EVOLITH_MCP_RESOURCE_AUTH_SERVERS	—	以逗号分隔的授权服务器签发方，发布在受保护资源元数据文档中。默认为 EVOLITH_MCP_OAUTH_ISSUER
EVOLITH_MCP_RESOURCE_URI	请求主机	此服务的规范 URI（RFC 8707 资源标识符），发布为 resource
EVOLITH_MCP_RESOURCE_SCOPES	read write	发布为 scopes_supported 并在 WWW-Authenticate 中要求的范围

此二进制程序还接受 --transport/-t、--port/-p、--api-key 和 --allow-no-auth（仅限 HTTP）标志，以及 evolith-mcp version 子命令。

---

身份验证

stdio 传输

无需进行请求身份验证：进程在本地运行，供单个用户使用，并由 Agent 直接启动。传输会建立一个明确的本地会话主体（id=local-stdio-session、role=local-session、roles=[local-session, operator]、scopes=[read, write]），并将其记录在每次调用的审计跟踪中（GT-572）。

这不是绕过授权：每次 tools/call 仍会使用该身份进行 ABAC（原生 + OPA）评估；deploy 工具在 production 中仍会被拒绝（它们要求 architect）；每个会修改数据的工具仍要求通过 HITL 门控 { apply, approvalToken }。--allow-no-auth / EVOLITH_MCP_ALLOW_NO_AUTH 不适用于 stdio（没有可跳过的请求身份验证）；如果它们与 --transport stdio 一同传入，服务会在启动时通过 stderr 发出警告。

HTTP 传输

在生产环境（NODE_ENV=production）中，身份验证必不可少：validateAuth() 会忽略 EVOLITH_MCP_ALLOW_NO_AUTH，并拒绝所有缺少有效凭据的请求（401）。EVOLITH_API_KEY 的值是任意密钥（任意字符串；无需特定前缀），通过相等性比较进行校验。它可在以下两种请求头中的任意一种传入：

Authorization: Bearer <EVOLITH_API_KEY>
x-api-key: <EVOLITH_API_KEY>

/health 是公开的（用于存活探测），无需凭据。

配置 OAuth 颁发者后，/.well-known/oauth-protected-resource（以及插入路径的 /.well-known/oauth-protected-resource/<path>）也会公开：这是 RFC 9728 文档，未经身份验证的客户端会读取该文档，以发现应前往哪个授权服务器；如果要求提供客户端正试图获取的凭据才能访问该文档，就会导致无法发现授权服务器。该文档不包含 MCP 数据，只包含颁发者、资源标识符和作用域名称。受保护资源返回 401 时，还会附带 WWW-Authenticate: Bearer resource_metadata="…", scope="…" 挑战；这是 MCP 客户端必须优先使用的发现机制。未配置颁发者时，端点会返回 404，而不会发布 authorization_servers 为空的文档。

客户端注册绝不会经由此服务进行：它是资源服务器；根据 2026-07-28 版修订内容，客户端应在授权服务器处通过 Client ID Metadata Document（或预注册）获取 client_id。动态客户端注册已弃用，此处不予实现；如果有人引入注册端点，protected-resource-metadata.spec.ts 会导致构建失败。

协议修订版本

服务器在同一个 HTTP 端点上响应两个协议修订版本：

修订版本	请求如何选择该版本	形式
2026-07-28（当前）	每个请求中的 _meta["io.modelcontextprotocol/protocolVersion"]，或调用 server/discover	无状态。没有 initialize、没有 notifications/initialized，也没有 Mcp-Session-Id。每个结果都带有 resultType；审批门通过带有密封 requestState（MRTR）的 InputRequiredResult 表示
2025-11-25	initialize 请求	基于握手的路径，由 @modelcontextprotocol/sdk 提供服务，并生成且要求提供 Mcp-Session-Id

两个修订版本都通过同一个分发器运行，因此 ABAC（原生 + OPA）、范围门、审批门和审计跟踪在两条路径上使用相同的代码。保留 2025-11-25 路径，是因为已发布的 SDK 仍将其声明为最新修订版本；它并非另一种设计。

在 2026-07-28 路径上，会更改状态的工具会以 resultType: "input_required" 响应，并附带一个 elicitation/create 请求和一个不透明的 requestState。客户端收集用户的审批，然后重试原始调用——使用新的 JSON-RPC id、相同的参数，并附上 requestState 和 inputResponses。requestState 使用 AES-256-GCM 密封，并绑定到主体、租户、发起的调用和较短的 TTL，因此无法跨用户、调用或时间重放。已持有审批的调用方仍可直接传入 { apply: true, approvalToken }，跳过往返流程，与 2025-11-25 路径完全相同。

下文的 ApiKeyProvisioningService 是一种高级且可选的机制，用于签发带有 evk_ 前缀、SHA-256 哈希和 TTL 的密钥。它独立于此处所述的启动时 EVOLITH_API_KEY。

API 密钥签发

ApiKeyProvisioningService 管理密钥的生命周期：

操作	说明
generateKey(label, options)	生成带有 evk_ 前缀、SHA-256 哈希和可配置 TTL（默认为 90 天）的密钥
validateKey(rawKey)	根据存储的哈希验证密钥并检查是否过期
rotateKey(keyId)	撤销当前密钥，并为同一客户端生成新密钥
revokeKey(keyId)	立即撤销密钥

密钥带有以下范围：read、write、admin。它们绑定到一个 tenant。

ABAC 模型

AbacEvaluator 根据用户的角色控制其可调用的工具：

工具类型	允许的角色	环境
读取（list、get、status）	每个已认证角色	任意
写入（fix、install、set）	operator、sre、architect、admin	任意
写入	developer、qa	仅非生产环境
部署（deploy、publish、merge）	architect、admin、operator、sre	任意
部署	除 architect 之外的任何人	在生产环境中被阻止

ABAC 代码：

代码	原因
ABAC-01	因用户的角色／环境而拒绝工具调用
ABAC-02	用户没有角色——拒绝所有工具调用
ABAC-03	工具未归类到任何已知组

工具分类（子串启发式规则）。 内部角色集合为 DEVELOPER = {developer, qa}、OPERATOR = {operator, sre} 和 ARCHITECT = {architect, admin}。每个工具的读取／写入／部署分类是基于其名称的启发式判断（abac-evaluator.ts）：如果名称包含 read/list/get（或不以 evolith- 开头），则视为读取；如果包含 write/replace/run/fix/advance，则视为写入；如果包含 deploy/publish/merge，则视为部署。因此，evolith-phase-advance 会被分类为写入（因为名称包含子串 advance），尽管它只会提出转换建议。不符合任何分组的工具会以 ABAC-03 被拒绝。

身份验证优先级（HTTP）。 守卫（mcp-server-auth.ts）会先检查 API key：如果 Authorization: Bearer <token> 或 x-api-key 标头与 EVOLITH_API_KEY 匹配，则授予 admin 上下文（角色为 admin，允许调用所有工具）。只有在密钥不匹配且定义了 JWT_SECRET 时，才会尝试将 Bearer 验证为 JWT HS256；在这种情况下，JWT 载荷中的 roles 会用于 ABAC。/health 是公开的。在生产环境中，身份验证是必需的（会忽略 EVOLITH_MCP_ALLOW_NO_AUTH）。

---

可用工具（55）

这些工具在运行时通过 tools/list 获取。它们均会返回原始数据，Gateway 会将其封装在 SuccessEnvelope 或 ErrorEnvelope 中。

数量根据生成的 Product Surface Inventory 中的注册来源（tools/*.ts、resources.service.ts、prompts.service.ts）得出；下表按领域列出每个工具。若两者不一致，以 tools/list 和 inventory 为准。

验证

工具	描述	是否修改数据
evolith-validate	根据 Evolith 治理规则（GOV、INH、ACL、OCB）验证仓库	否
evolith-composable-validate	可组合的多模式验证：SDLC、Architecture、Ruleset、ADR、Ad-hoc	否

evolith-composable-validate 架构：

{
  "path": "string (required) — path to the satellite repository",
  "corePath": "string — path to the Evolith Core",
  "engine": "'native' | 'opa' — evaluation engine (default: native)",
  "topology": "'modular-monolith' | 'microservices' | 'serverless' | ... — enables Architecture mode",
  "phase": "'discovery' | 'design' | 'construction' | 'qa' | 'release' — enables SDLC mode (the schema also accepts the legacy aliases 'f1'..'f5', deprecated)",
  "ruleset": "string — enables Ruleset mode",
  "adr": "'adr-0002' | 'adr-0005' | 'adr-0010' | ... — enables ADR mode",
  "file": "string — enables Ad-hoc mode over a single file"
}

通过组合字段启用不同模式。单次调用可以使用其中多个模式。

---

评估（ADR-0101）

工具	描述	是否修改数据
evolith-evaluate	评估规范的 EvaluationContext（门禁、工件、规则、合规性），并在 ADR-0073 封装中返回 EvaluationResult。无状态：产品、租户和计划仅作为不透明上下文	否
evolith-ruleset-list	列出此 Core 可评估的规则集包——即 evolith-validate 的 select 接受的规范引用，并列出每个包中的规则数量	否

---

架构

工具	描述	是否修改数据
evolith-architecture-validate	根据架构规则验证卫星项目	否
evolith-drift-detect	检测声明的架构与实际架构之间的偏差	否
evolith-topology-recommend	根据技术信号推荐拓扑组合（建议性质，ADR-0104）：Core 提出建议，租户确认	否
evolith-phase-artifacts-evaluate	衡量已确认拓扑组合的下游阶段工件完整性（建议性质，ADR-0104）	否

---

模式

工具	描述	是否修改
evolith-pattern-list	列出规范模式和反模式（PAT-NNNN），可按类别、类型或适用拓扑筛选	否
evolith-pattern-get	按 ID 获取单个模式：问题、影响因素、解决方案、对各拓扑的适用性以及约束性 ADR	否
evolith-pattern-list-by-topology	列出适用于某一拓扑的模式、适用程度（必需 → 推荐 → 可选）以及每个模式施加的规则	否

---

拓扑

工具	描述	是否修改
evolith-topology-list	列出 Evolith Core 中所有可用的架构拓扑	否
evolith-topology-get	按 ID 获取某个拓扑的完整清单	否

evolith-topology-list 架构：

{
  "corePath": "string — path to the Core (optional, default: ../evolith)"
}

evolith-topology-get 架构：

{
  "id": "string (required) — topology ID (e.g. modular-monolith)",
  "corePath": "string — path to the Core (optional)"
}

可用拓扑： modular-monolith、distributed-modules、microservices、serverless、edge-computing、event-driven、data-mesh、agentic-ai

---

SDLC 阶段门

工具	描述	是否修改
evolith-gate-evaluate	评估指定的 SDLC 阶段门	否
evolith-phase-advance	提议阶段转换	否¹

¹ evolith-phase-advance 只会提议转换，不会执行转换。执行转换由操作员或 Tracker 负责。

---

SDLC

工具	描述	是否修改
evolith-sdlc-status	获取存储库当前的 SDLC 阶段状态	否
evolith-sdlc-handoff	执行阶段交接，生成证据清单	是
evolith-dora-metrics	根据 Git 历史估算 DORA 指标：部署频率、前置时间（近似值）、窗口期内的提交总数和合并提交数（days，默认值为 90）	否
evolith-sdlc-generate	根据 Markdown DDD 模型中的 Mermaid classDiagram 生成六边形架构脚手架（与 sdlc generate 功能一致）	是

---

MoSCoW

工具	描述	是否修改
evolith-moscow-create	为项目的某个阶段创建 MoSCoW 矩阵	是
evolith-moscow-load	加载现有的 MoSCoW 矩阵	否
evolith-moscow-update	更新 MoSCoW 矩阵中的条目	是
evolith-moscow-remove	从矩阵中移除条目	是
evolith-moscow-list	列出项目的 MoSCoW 矩阵	否
evolith-moscow-validate	验证矩阵格式是否正确	否
evolith-moscow-report	生成 MoSCoW 优先级报告	否

² 三个会写入 .evolith/moscow/{phase}.json 的 MoSCoW 工具（create、update、remove）自 2026-07-11 起在 moscow.tools.ts 中声明 mutative: true，因此调度器要求提供 apply/approvalToken；load、list、validate 和 report 则用于读取。

---

ADR

工具	描述	是否修改
evolith-adr-list	列出所有架构决策记录（ID、标题、状态、日期）	否
evolith-adr-get	按 ID（ADR-0001）或编号获取单个 ADR 的完整详情	否
evolith-adr-matrix	获取 ADR 矩阵摘要（按状态统计的总数、近期 ADR）	否
evolith-adr-create	创建 ADR：写入 reference/architecture/adrs/<id>.md 并更新矩阵	是
evolith-adr-update	更新 ADR 的状态（Proposed、Accepted、Deprecated、Superseded、Amended）	是

---

Agent

工具	描述	是否修改
evolith-agent-install	在存储库中安装 Evolith Agent	是
evolith-agent-list	列出已安装的 Agent	否
evolith-agent-validate	验证 Agent 的配置	否
evolith-agent-upgrade	将 Agent 升级到最新的模板版本	是
evolith-agent-remove	从存储库中移除 Agent	是
evolith-agent-run	通过 Agent Runtime 管线运行意图	是

---

Satellites

工具	描述	是否会修改
evolith-satellite-list	列出本地 satellite-registry.json 中注册的 Satellites	否
evolith-satellite-status	根据 ID 获取已注册 Satellite 的状态和详细信息	否
evolith-satellite-create	在 GitHub 上创建 Satellite 仓库并注册它（ADR-0073 信封）	是
evolith-satellite-adopt	将现有 GitHub 仓库作为 Satellite 纳入管理（ADR-0073 信封）	是

---

脚手架与初始化

工具	描述	是否会修改
evolith-init-batch	以非交互方式（批处理/CI）初始化 Satellite；与 init --config <json> / init --yes 等效，不显示提示	是
evolith-scaffold	沿渐进式成熟度路径搭建 Satellite 脚手架（阶段 1 模块化单体 → 2 分布式模块 → 3 微服务）	是
evolith-docs-scaffold	搭建 Evolith 要求的基础文档（README.md、AGENTS.md、MASTER_INDEX.md、evolith.yaml）；与 docs 命令一致	是
evolith-fixtures	为演示和测试创建可复现的固定数据与示例数据（evolith.yaml、ADR、规则集）	是

---

升级

工具	描述	是否会修改
evolith-upgrade-plan	根据上游 Core 规划 Satellite 升级（试运行）：变更计划、破坏性变更、预估风险，不写入任何内容	否
evolith-upgrade-apply	应用来自上游 Core 的 Satellite 升级；仅写入上游变更，不写入仅本地的变更	是

---

知识

工具	描述	是否会修改
evolith-knowledge-search	使用 BM25 优先的混合检索搜索架构知识语料库（ADR、规则集、标准）；返回带引用的排序片段	否

---

修复

工具	描述	是否会修改
evolith-auto-fix	自动修复检测到的违规项	是

---

配置

工具	描述	是否会修改
evolith-config-get	从 evolith.yaml 获取配置值	否
evolith-config-set	更新 evolith.yaml 中的值	是

---

可观测性

工具	描述	是否会修改
evolith-metrics	返回内部 MCP Gateway 指标（调用次数、延迟、错误）	否

CLI 对等只读工具（GT-682）

三个原本没有 MCP 对应项的 CLI 命令，已移植为只读工具，通过 core-domain 中 CLI 自有的读取器实现。它们的写入模式（history --clear/--replay、profile create/switch/delete、standards --init/--validate/--export）仍保留在 CLI 中。

工具	描述	是否会修改
evolith-history	读取 CLI 命令历史（$HOME/.evolith/history.jsonl）：list、get、search、stats	否
evolith-profile	读取 CLI 配置档案存储：current（活动配置档案及其值）或 list	否
evolith-standards	读取 <path>/reference/standards 下的标准：list（可选的 category）或 get	否

---

可用资源（12 + 动态）

通过 resources/list 获取资源，并通过 resources/read 读取。

静态资源（resources/list）

URI	名称	描述
evolith://rulesets	规则集	列出 Evolith Core 的所有规则集
evolith://phase-gates	阶段门	阶段门的定义和要求
evolith://agents	Agents	已安装的 Evolith Agent 列表
evolith://core/info	Core 信息	Core 的常规信息（版本、规则集总数、功能）
evolith://governance/version	治理版本	治理架构的版本
evolith://core/version	Core 版本	Core 架构的版本
evolith://repository/config	仓库配置	当前仓库的 evolith.yaml 内容
evolith://moscow/phase-0	MoSCoW 阶段 0	发现阶段的 MoSCoW 矩阵
evolith://architecture/topologies	架构拓扑	所有可用拓扑的列表
evolith://architecture/patterns	架构模式	规范模式和反模式（PAT-NNNN），以及其适用性和强制执行规则
evolith://capabilities	功能清单	评估引擎的版本化功能清单（evaluationKinds、引擎、界面、supportedConsumers）
evolith://contracts	机器契约	Core 为外部使用者发布的机器可读架构／契约集

动态 URI（可通过 resources/read 访问）

URI 模式	描述
evolith://ruleset/{name}	按名称获取规则集内容（例如，evolith://ruleset/governance/base）
evolith://agent/{name}	获取已安装 Agent 的定义（例如，evolith://agent/winston）
evolith://architecture/topology/{id}	拓扑清单（例如，evolith://architecture/topology/modular-monolith）
evolith://open-core/artifacts	Open-Core 边界（OCB）规则
evolith://acl/rules	防腐层规则
evolith://moscow/{phase}	任意阶段的 MoSCoW 分析（例如，evolith://moscow/phase-1）

---

可用提示词（8 个）

通过 prompts/list 获取提示词，并通过 prompts/get 调用。

提示词	描述	参数
evolith/validate-repository	根据治理规则验证仓库	path（必填）、ruleset（可选）
evolith/agent-onboarding	安装并配置新 Agent	name（必填）、template（可选：standard/minimal/enterprise）
evolith/architecture-review	F1/F2/F3 架构审查	path（必填）、level（可选：F1/F2/F3）
evolith/prepare-discovery	准备发现阶段的工件	path（必填）
evolith/phase-gate-check	检查阶段门就绪情况	path（必填）
evolith/sdlc-handoff	执行 SDLC 阶段交接	path（必填）、fromPhase（必填）、toPhase（必填）
evolith/ruleset-analysis	分析对规则集的合规性	ruleset（必填）、path（可选）
evolith/moscow-prioritization	为 SDLC 创建 MoSCoW 矩阵	path（必填）、phase（可选，默认值：phase-0）

---

会修改数据的操作

标记为会修改数据（mutative: true）的工具需要明确批准，以防意外更改。除非请求同时包含以下两个字段，否则分发器（mcp-tool-dispatch.ts:137）会以 FORBIDDEN 拒绝调用：

{
  "name": "winston",
  "dir": "/path/to/repo",
  "apply": true,
  "approvalToken": "<non-empty-token>"
}

• apply 必须严格为 true。
• approvalToken 必须是非空字符串。服务器绝不会以明文记录它：审计前会将其转换为 sha256:… 指纹。

approvalToken 是协议层面的批准契约。一些工具架构仍声明了 confirm 字段，辅助函数 isMutationAllowed() 也仍然存在（它会从 evolith.yaml 读取 mcp.allowMutations），但在 handleCallTool 中实际阻止执行的防护机制是 apply + approvalToken——confirm 和 mcp.allowMutations 都不能替代它。

可变更工具

工具	操作
evolith-agent-install	将 Agent 文件写入仓库
evolith-agent-upgrade	覆盖 Agent 配置
evolith-agent-remove	删除 Agent 目录
evolith-agent-run	通过 Agent Runtime 执行意图（技能可能会写入内容）
evolith-config-set	修改 evolith.yaml
evolith-sdlc-handoff	生成交接清单并写入状态
evolith-sdlc-generate	根据 DDD 模型写入六边形架构脚手架
evolith-auto-fix	对代码应用自动修复
evolith-adr-create / evolith-adr-update	写入 ADR 文件和 ADR 矩阵
evolith-moscow-create / evolith-moscow-update / evolith-moscow-remove	写入 .evolith/moscow/{phase}.json
evolith-satellite-create / evolith-satellite-adopt	创建或关联 GitHub 仓库，并写入本地 satellite 注册表
evolith-init-batch / evolith-scaffold / evolith-docs-scaffold / evolith-fixtures	写入 satellite 的文件、文档基础内容或 fixtures
evolith-upgrade-apply	将上游更改写入 satellite

代码中恰好有 20 个工具声明了 mutative: true（2026-09-20；其余 35 个为读取操作）。调度器在设计上保护的就是这个集合——工具受到保护是因为它具有可变更性，而不是因为它列在这里。evolith-upgrade-plan 和 evolith-phase-advance 特意设为读取操作：它们负责计算并提出方案，不会写入内容。

---

内部架构

Gateway 是一个 NestJS 应用程序（模块 + 依赖注入）。

@beyondnet/evolith-mcp/
├── src/
│   ├── main.ts                         ← Bootstrap, parseArgs, stdio/HTTP startup
│   ├── app.module.ts                   ← Root module
│   ├── common/
│   │   ├── errors.ts                   ← ErrorCodes + DomainException
│   │   ├── envelopes.ts                ← SuccessEnvelope / ErrorEnvelope + correlationId
│   │   └── stderr-logger.ts            ← LoggerService over Pino → stderr
│   ├── mcp/
│   │   ├── mcp.module.ts
│   │   ├── tool.interface.ts           ← McpTool interface + MCP_TOOLS token
│   │   ├── tool-registry.service.ts    ← dynamic tool registry
│   │   ├── mcp-server.service.ts       ← MCP SDK Server + dispatch + transports
│   │   ├── mcp-tool-dispatch.ts        ← dispatch with ABAC + audit + mutative guard
│   │   ├── mcp-server-auth.ts          ← HTTP authentication (EVOLITH_API_KEY)
│   │   ├── abac-evaluator.ts           ← native ABAC evaluator + OPA
│   │   ├── api-key-provisioning.service.ts  ← API key lifecycle
│   │   ├── audit-logger.ts             ← structured log of every tool call
│   │   ├── mcp-cache.service.ts        ← resource cache in Redis
│   │   ├── metrics.service.ts          ← internal Gateway metrics
│   │   ├── prompts.service.ts          ← serves prompts/list and prompts/get
│   │   └── resources.service.ts        ← serves resources/list and resources/read
│   ├── tools/
│   │   ├── tools.module.ts             ← registers every tool
│   │   ├── validate.tool.ts            ← evolith-validate
│   │   ├── composable-validate.tool.ts ← evolith-composable-validate (GT-312)
│   │   ├── architecture.tools.ts       ← evolith-architecture-validate, drift-detect
│   │   ├── topology.tools.ts           ← evolith-topology-list, topology-get
│   │   ├── gate.tools.ts               ← evolith-gate-evaluate
│   │   ├── phase-advance.tools.ts      ← evolith-phase-advance
│   │   ├── sdlc.tools.ts               ← sdlc-status, sdlc-handoff, dora-metrics
│   │   ├── moscow.tools.ts             ← moscow-create/load/update/remove/list/validate/report
│   │   ├── agent.tools.ts              ← agent-install/list/validate/upgrade/remove
│   │   ├── auto-fix.tools.ts           ← evolith-auto-fix
│   │   ├── config.tools.ts             ← config-get, config-set
│   │   └── metrics.tool.ts             ← evolith-metrics
│   ├── resources/
│   │   └── corpus-resource.handler.ts  ← handler for documentary corpus resources
│   ├── watcher/
│   │   └── watcher.service.ts          ← watches workspace files for changes
│   └── domain/
│       └── domain.module.ts            ← wires @beyondnet/evolith-core to @beyondnet/evolith-infra-providers

@beyondnet/evolith-core               ← business logic (use-cases, validators, types)
@beyondnet/evolith-infra-providers    ← adapters (NodeFileSystem, YamlConfigParser, DiskRulesetRepository)

WatcherService

WatcherService 会监视工作区文件（例如 evolith.yaml），以便在 Gateway 运行时用户编辑配置后使缓存失效或触发重新验证。在长期运行的 stdio 传输模式下会自动启用。

CorpusResourceHandler

负责处理对文档语料资源（ADR、操作手册、规范）的访问，让 Agent 无需调用可变更工具即可读取结构化架构上下文。

---

Agent 使用场景

1. 从 Claude Desktop 验证仓库

// prompts/get
{
  "name": "evolith/validate-repository",
  "arguments": { "path": "/Users/me/my-service" }
}

提示词会引导 Agent 使用 evolith-validate 并报告阻断性违规。

2. 从 Cursor 为 Agent 完成入门配置

// prompts/get
{
  "name": "evolith/agent-onboarding",
  "arguments": { "name": "guardian", "template": "enterprise" }
}

Agent 将依次调用 evolith-agent-install 和 evolith-agent-validate。

3. 自动化架构审查

// tools/call
{
  "name": "evolith-composable-validate",
  "arguments": {
    "path": "/repo",
    "topology": "modular-monolith",
    "phase": "design",
    "engine": "native"
  }
}

通过一次调用结合 SDLC 和架构验证。

4. 完整的 SDLC 周期，包含 MoSCoW + 门禁检查

1. tools/call evolith-sdlc-status     → current state of the phase
2. tools/call evolith-moscow-create   → create the prioritization matrix
3. tools/call evolith-gate-evaluate   → evaluate the gate of the current phase
4. tools/call evolith-sdlc-handoff    → generate the handoff manifest
5. tools/call evolith-phase-advance   → propose moving on to the next phase

5. 验证前查询拓扑结构

// tools/call
{ "name": "evolith-topology-list" }
// → list of available topologies

{ "name": "evolith-topology-get", "arguments": { "id": "agentic-ai" } }
// → full manifest with rules and requirements

---

客户端配置

Cursor（~/.cursor/config.json）

{
  "mcpServers": {
    "evolith": {
      "command": "evolith-mcp",
      "args": ["serve"],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

Claude Desktop（claude_desktop_config.json）

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

自定义 Agent（HTTP 传输）

# Start the HTTP server
EVOLITH_API_KEY=evk_abc123 evolith-mcp serve --transport http --port 49100

# Call it from the agent
curl -X POST http://localhost:49100/mcp \
  -H "Authorization: Bearer evk_abc123" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"evolith-validate","arguments":{"path":"/repo"}},"id":1}'

---

SmartCLI 集成

从 evolith-cli mcp 迁移的计划

阶段 1 — 共存（当前）：evolith-cli mcp 仍可正常使用。evolith-mcp serve 是新的入口点。

阶段 2 — 弃用：evolith-cli mcp 将输出 console.warn。请将 Cursor / Claude Desktop 配置迁移到 evolith-mcp。

**阶段 3 — 移除：**在主版本升级中从 @beyondnet/evolith-cli 移除 MCP 代码。CLI 保留其验证命令。

行为差异

方面	evolith-cli mcp（旧版）	evolith-mcp（新版）
传输方式	仅 stdio	stdio + Streamable HTTP
身份验证	无身份验证	HTTP 上的 ABAC + API 密钥
缓存	无缓存	可选 Redis
可观测性	基本日志	Pino + OTEL + 审计日志记录器
工具	部分工具	全部 55 个工具

---

扩展指南

添加新工具：

1. 创建 src/tools/my-tool.tool.ts，实现 McpTool（schema、execute；如果会更改状态，则添加 readonly mutative = true）。
2. 注入所需的领域服务（来自 @beyondnet/evolith-core）。
3. 返回原始数据——McpServerService 会自动将其包装在 SuccessEnvelope 中，并将错误捕获到 ErrorEnvelope 中。
4. 在 tools.module.ts 中注册该工具：添加提供者并将其加入 MCP_TOOLS 工厂。

import { Injectable } from "@nestjs/common";
import { McpTool, McpToolSchema } from "../mcp/tool.interface";

@Injectable()
export class MyTool implements McpTool {
  readonly schema: McpToolSchema = {
    name: "evolith-my-tool",
    description: "Description of what it does",
    inputSchema: {
      type: "object",
      properties: { param1: { type: "string", description: "..." } },
      required: ["param1"],
    },
  };

  async execute(args: Record<string, unknown>): Promise<unknown> {
    if (!args.param1) throw new Error("param1 is required");
    return { ok: true };
  }
}

对于会更改状态的工具，添加 readonly mutative = true。这样，分发器会要求请求中包含 { "apply": true, "approvalToken": "..." }，然后才会运行该工具。

---

可观测性

Pino 日志 → stderr

所有日志都写入 stderr（绝不会写入 stdout）。采用结构化 JSON 格式，包含 correlationId、tool、duration 和 success。

# Follow the logs live (stdio)
evolith-mcp serve 2>&1 | grep '"level"'

evolith-metrics 工具

返回 Gateway 的内部指标：

{
  "uptimeMs": 1820345,
  "totalCalls": 142,
  "totalFailures": 4,
  "tools": {
    "evolith-validate": { "calls": 80, "failures": 1, "totalLatencyMs": 1440, "avgLatencyMs": 18 },
    "evolith-gate-evaluate": { "calls": 32, "failures": 0, "totalLatencyMs": 992, "avgLatencyMs": 31 }
  },
  "recentErrors": ["RULESET_NOT_FOUND: ..."]
}

OpenTelemetry

OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318 \
OTEL_SERVICE_NAME=evolith-mcp \
evolith-mcp serve

审计日志记录器

每次工具调用都会记录：toolName、userId、tenant、environment、allowed（ABAC）、durationMs 和 correlationId。记录以 JSON 格式写入 stderr。

---

最佳实践

• 使用提示词作为 Agent 工作流的入口——这样可以避免 Agent 还要推理工具调用顺序。
• 不要在未先使用相应的只读工具进行验证前，批量确认会更改状态的调用。
• 先运行 evolith-validate，再运行 evolith-auto-fix，以了解变更的实际范围。
• 在生产环境使用 HTTP 时，每 90 天轮换一次 API 密钥，并将作用域限制为所需的最小范围。
• 在长期运行的安装中，Redis 虽然可选，但建议使用，以避免在 resources/read 中反复读取文件系统。
• 需要多种模式时，使用 evolith-composable-validate，而不是分别调用多个工具——这样可以降低延迟并关联结果。

---

故障排除

stdio：日志与 MCP 响应交错显示

日志写入 stderr。如果客户端合并了 stdout 和 stderr，请分开处理这些流：

evolith-mcp serve 2>/tmp/mcp.log

stdio：Refusing to start the MCP stdio transport (GT-572)

在 NODE_ENV=production 下，stdio 传输不会隐式接收 local-session 主体：它要求配置与其他生产环境接口相同的凭据。如果没有该凭据，服务不会启动——它会在启动时向 stderr 明确报错并以代码 78（EX_CONFIG）退出，而不是公布所有工具后再对每次 tools/call 都返回 FORBIDDEN。

修复方法（任选其一）：

export EVOLITH_API_KEY=<key>                                  # container: -e EVOLITH_API_KEY=<key>
evolith-mcp serve --transport stdio --api-key <key>
NODE_ENV=development evolith-mcp serve --transport stdio      # local development session

--allow-no-auth / EVOLITH_MCP_ALLOW_NO_AUTH 是仅适用于 HTTP 的开发开关，特意不作为生产环境凭据的替代品。

HTTP：401 Unauthorized

检查服务器是否配置了 EVOLITH_API_KEY，以及请求是否在 Authorization: Bearer <key> 或 x-api-key: <key> 中发送相同的值。系统会进行精确匹配（无需 evk_ 前缀）。在 NODE_ENV=production 下，即使设置了 EVOLITH_MCP_ALLOW_NO_AUTH=true，仍然必须进行身份验证。

找不到工具（Tool not found in registry）

该工具可能尚未在 tools.module.ts 中注册。检查是否已添加提供者，以及 schema.name 中的名称是否与调用时使用的名称完全一致。

ABAC-02: No roles present

用户上下文（mcp-user-context）中没有角色。在 HTTP 传输中，请检查 JWT 或用户上下文是否正确包含角色声明。

Redis 不可用

缓存会优雅降级。资源会直接从文件系统提供，不使用缓存，并在日志中发出警告。

OPA：未找到 policy.wasm

OPA 评估器需要在 CORE_PATH 下存在 sdk/cli/rulesets/opa/policy.wasm。缺少策略文件时的行为是默认拒绝（GT-348/349），而非默认放行：如果文件不存在且 NODE_ENV === "production"，评估器会返回 allowed: false，并附带 ABAC_POLICY_MISSING 违规项（硬性拒绝）。只有在非生产环境中，OPA 评估器才会弃权，返回 allowed: true，由原生策略作出决定。OPA 引擎内部发生错误时，始终会拒绝。若要强制使用原生评估，请勿指定 engine: "opa"。

---

许可证

ISC — Beyondnet