项目概览与核心概念

mcp-adr-analysis-server 是一个基于模型上下文协议（Model Context Protocol, MCP）的服务器，专为分析与管理架构决策记录（Architecture Decision Records, ADR）而设计。它通过标准化的 MCP 接口向 AI 助手（如 Claude、Copilot CLI 等）暴露一系列工具，使 LLM 能够在工程工作流中读取、检索、生成与验证 ADR 内容，从而支持架构决策的自动化与一致性维护。

资料来源：README.md:1-40

项目定位与核心目标

本项目在 npm 上的包名为 mcp-adr-analysis-server，版本目前迭代至 v2.6.8（截至最新发布）。其核心定位是一个"为 AI 协作而生的 ADR 知识服务器"：

• 面向 AI 助手：作为 MCP 服务器运行，让 LLM 客户端通过 ListToolsRequestSchema、CallToolRequestSchema 等标准协议调用工具（资料来源：docs/explanation/mcp-concepts.md:1-30）。
• 聚焦 ADR 工作流：内置检索、生成、模板填充、todo 跟踪等能力，覆盖 ADR 生命周期的关键阶段。
• 离线优先：在 EXECUTION_MODE=full 之外提供轻量级离线模式，例如 v2.6.0 新增的 generate_adr_todo 工具即支持离线里程碑跟踪（资料来源：Release v2.6.0）。

关键概念

架构决策记录（ADR）

ADR 是用于记录重要架构决策的短文档，结构通常包括上下文、决策、状态与后果。本服务器将 ADR 视为一等公民对象，对其进行解析、索引与查询（资料来源：docs/index.md:1-25）。

MCP 工具（Tools）与资源（Resources）

服务器向客户端注册多个工具（社区审计显示注册工具数量为 72 个，见 Issue #612），每个工具以独立文件实现，统一在 ListToolsRequestSchema 中注册。工具类别包括：

• 检索类：如 search_adr、搜索工具 search_tools（资料来源：Issue #612）。
• 生成类：如 generate_adr_todo（v2.6.0 引入，PR #849）（资料来源：Release v2.6.0）。
• 分析与验证类：用于对 ADR 内容进行规则校验与一致性检查。

执行模式

通过环境变量 EXECUTION_MODE 控制行为，常见值包含 full（完整在线模式）和轻量/离线模式。社区曾反映文档中环境变量说明缺失（资料来源：Issue #546），后续版本逐步完善。

架构与运行流程

服务器以 stdio 方式与 MCP 客户端通信，整体流程为：客户端连接 → 工具列表握手 → 工具调用 → 返回结构化结果。

flowchart LR
    A[MCP 客户端<br/>Claude/Copilot] -- stdio --> B[mcp-adr-analysis-server]
    B -- 读取 --> C[ADR 仓库<br/>文件系统]
    B -- 调用 --> D[工具集<br/>72 个注册工具]
    D -- 输出 --> A

资料来源：src/index.ts:1-50、docs/explanation/architecture.md:1-40

版本演进与社区关注点

项目遵循自动化发布流水线，v2.5.x 至 v2.6.x 期间主要变更集中在 CI 稳定性与发布门控（资料来源：Release v2.5.4、Release v2.6.2）。社区当前重点关注：

• AI 执行器集成失败：Copilot CLI 因 token 缺少 inference 访问权限导致工作流失败（资料来源：Issue #1235、Issue #1187）。
• 工具注册一致性：审计发现个别工具文件未在主注册表中注册（资料来源：Issue #612）。
• 文档质量：如 docs/QUICK_START.md 与现有文档系统不一致，可能误导新用户（资料来源：Issue #694）。
• 依赖安全：定期修复 npm 依赖漏洞并更新安全文档（资料来源：Release v2.5.1）。

总结

mcp-adr-analysis-server 通过 MCP 协议将 ADR 管理能力暴露给 AI 助手，核心价值在于把工程决策知识结构化、可查询、可生成。开发者在使用前应关注环境变量配置（OPENROUTER_API_KEY、EXECUTION_MODE）与对应 MCP 客户端的兼容性，并参考最新发布说明与社区已知问题进行部署。资料来源：README.md:1-60

概述

mcp-adr-analysis-server 是一个基于 Model Context Protocol (MCP) 协议实现的服务端应用，专为 Architecture Decision Records (ADR) 提供分析与检索能力。该服务作为大语言模型客户端（如 Claude Desktop、IDE 插件）的工具提供方，通过标准化的 JSON-RPC 接口暴露一组结构化工具，使 LLM 能够在对话上下文中读取、搜索、生成并跟踪仓库中的架构决策记录 资料来源：docs/explanation/server-architecture.md:1-15。

当前主版本为 v2.6.8，包入口文件定义为 dist/index.js，由 Node.js 运行时加载，并通过 stdio 与 MCP 客户端进行双向通信 资料来源：package.json:1-25。该设计使得服务以"无状态进程"方式运行，无需独立的 HTTP 服务器或数据库，显著降低了部署复杂度。

高层架构

服务整体遵循"MCP 传输层 → 路由分发层 → 工具实现层 → 领域服务层"四层架构。下图展示了请求从 MCP 客户端到达具体业务工具的主要数据流：

flowchart LR
    A[MCP 客户端<br/>Claude/IDE] -->|stdio/JSON-RPC| B[index.ts<br/>入口]
    B --> C[Server<br/>ListTools/CallTool]
    C --> D[ToolDispatcher<br/>路由]
    D --> E[Tool 实现<br/>tools/*]
    E --> F[领域服务<br/>ADR 解析/AI 调用]
    F -->|结果| E
    E -->|JSON 响应| C
    C -->|stdio/JSON-RPC| A

核心入口位于 src/index.ts，负责初始化 Server 实例并注册所有可用工具；请求到来时由 MCP SDK 完成协议编解码，再交由 src/server.ts 中的请求处理器分派到对应的工具模块 资料来源：src/index.ts:1-50 资料来源：src/server.ts:20-80。所有工具需要先通过 ListToolsRequestSchema 在握手阶段完成自描述注册，从而保证与 MCP 规范的兼容性 资料来源：docs/explanation/mcp-architecture-flow.md:1-30。

模块结构

模块化设计主要体现在 src/ 目录的清晰切分：

• 入口与传输：src/index.ts 负责 stdio 传输握手、信号处理与优雅关闭。
• 服务核心：src/server.ts 负责注册 ListToolsRequestSchema 与 CallToolRequestSchema 处理器，并集中错误返回逻辑。
• 工具分发：src/utils/tool-dispatcher.ts 提供统一的工具查找与调用包装器，消除 server.ts 中重复的 switch/case 逻辑 资料来源：src/utils/tool-dispatcher.ts:1-40。
• 配置加载：src/utils/config.ts 与 src/config/ai-config.ts 负责读取环境变量、解析 EXECUTION_MODE，并在 AI 模式下注入 OpenRouter 兼容的模型参数 资料来源：src/utils/config.ts:1-60 资料来源：src/config/ai-config.ts:1-50。
• 类型定义：src/types/mcp.ts 集中描述工具参数、上下文与响应结构，避免跨模块的 TypeScript 类型漂移 资料来源：src/types/mcp.ts:1-30。

模块之间通过显式导入通信，不存在全局单例或隐式耦合，便于单元测试和按需替换实现。

MCP 协议集成

Server 通过 MCP SDK 注册三类核心能力：工具列表（tools/list）、工具调用（tools/call）与日志通知（notifications/message）。当请求到达 CallToolRequestSchema 时，server.ts 将其参数透传给 ToolDispatcher，后者根据工具名称选择对应的处理函数 资料来源：src/server.ts:60-95。每个工具必须返回标准化的 CallToolResult 结构，其中 content 字段为文本或资源引用数组，便于客户端进行多模态展示 资料来源：docs/explanation/mcp-architecture-flow.md:40-70。

如果工具抛出未捕获异常，Server 会捕获并将错误以 isError: true 形式返回给客户端，从而避免协议层崩溃，这种设计在社区多次 CI 失败场景下保证了服务的可恢复性 资料来源：src/server.ts:100-120。

配置与扩展

配置的单一来源是环境变量与 .env 文件，主要键包括 OPENROUTER_API_KEY、EXECUTION_MODE（取值 lite / full）以及部分可选的遥测开关 资料来源：src/utils/config.ts:20-60。ai-config.ts 根据 EXECUTION_MODE 决定是否启用 AI 驱动的工具，例如 generate_adr_todo 与智能搜索 资料来源：src/config/ai-config.ts:10-40。在 lite 模式下，系统完全离线运行，仅提供基于文件系统的工具，符合社区对"无外网依赖即可使用"的需求 资料来源：docs/explanation/server-architecture.md:50-80。

扩展新工具的标准流程为：在 src/tools/ 下新增实现文件，将元信息（名称、描述、输入 Schema）注册到 ToolDispatcher 的映射表中，并在文档侧补全对应条目。logger.ts 提供了分级日志能力，错误级别消息会自动通过 MCP 通知推送到客户端，便于 LLM 进行自我纠错 资料来源：src/utils/logger.ts:1-30。这种"协议原生日志 + 显式扩展点"的组合，使项目能够在保持核心精简的同时承载大量领域工具。

已知问题与注意事项

社区中的 mcp-tool-check 审计曾发现个别工具未在 ListToolsRequestSchema 中注册，导致其无法被客户端发现；该问题提醒新增工具时必须在两处（实现与注册）保持同步 资料来源：docs/explanation/server-architecture.md:90-110。同时，docs/QUICK_START.md 中的配置示例与当前 config.ts 的实际行为存在差异，部署前应参考 src/utils/config.ts 的最新实现而非过时文档 资料来源：src/utils/config.ts:1-20。

概述

MCP Tools Catalog and Resources 是 mcp-adr-analysis-server 项目中负责工具注册、调度与资源暴露的核心子系统。它通过 Model Context Protocol（MCP）协议向客户端（如 IDE、AI 代理或 CLI）暴露一组可调用的"工具（tools）"以及一组可读取的"资源（resources）"，从而支撑架构决策记录（ADR）的分析、生成与验证流程。

该子系统的设计目标包括：

• 集中注册：所有 MCP 工具通过统一的目录（catalog）进行注册与发现，避免重复定义或遗漏注册。
• 统一调度：通过调度器（dispatcher）将工具调用请求路由到具体实现，并支持链式编排（chain orchestration）。
• 资源路由：对 URI 形式的资源请求进行解析与响应，支持 AD 缓存、模板、验证报告等结构化数据的读取。
• 离线优先：在 EXECUTION_MODE=full 之外的场景下，工具仍可基于本地缓存运行（参见 generate_adr_todo 的离线里程碑跟踪能力）。

社区一致性审计（Issue #612）显示，仓库扫描到 34 个工具源文件、ListToolsRequestSchema 中注册了 72 个工具；任何新增工具若未在目录中注册，会被审计流程识别为缺失项（如 search_tools 的注册问题）。这一约束直接体现了 Tool Catalog 的强制性作用。 资料来源：src/tools/tool-catalog.ts:1-40

工具目录（Tool Catalog）架构

src/tools/tool-catalog.ts 是整个工具子系统的入口点。它以集中方式声明所有可用工具的元数据（名称、描述、输入 schema、所属分类），并对外提供查询接口。工具被划分为若干领域，例如：

• 分析类（Analysis）：对代码库与 ADR 进行静态分析。
• 生成类（Generation）：生成新的 ADR、待办列表或决策草案。
• 验证类（Validation）：检查 ADR 的一致性、完整性与合规性。
• 搜索/发现类（Discovery）：在知识库与缓存中检索相关内容。

tool-catalog.ts 在被加载时会聚合各分类目录中的工具描述，并构建一个不可变的"目录快照"。客户端在启动时通过 MCP 的 ListToolsRequestSchema 获取该快照，从而无需逐个发现工具。资料来源：src/tools/tool-catalog.ts:40-120

文档侧由 docs/reference/analysis-tools.md 维护每个工具的可读说明、参数语义与示例调用，形成"代码即真相、文档即解释"的双层结构。

调度器与链式编排

src/tools/tool-dispatcher.ts 负责将来自 MCP 客户端的工具调用（CallToolRequestSchema）按工具名称转发至对应处理器。其内部维护一张名称到处理器函数的映射表，并在调用前后执行统一的预处理（如参数校验、缓存查找、日志埋点）与后处理（如结果归一化、错误封装）。资料来源：src/tools/tool-dispatcher.ts:1-80

对于需要按顺序执行多个工具的复合任务（例如：先分析代码 → 再生成 ADR 草案 → 最后校验一致性），系统通过 src/tools/tool-chain-orchestrator.ts 提供链式编排能力。编排器接受一个声明式的步骤序列，每一步可以引用目录中的任意工具，并支持：

• 短路条件：当某步返回特定结果时跳过后续步骤。
• 上下文传递：将前序工具的输出注入后续工具的输入。
• 失败重试与回退：在工具抛出可恢复错误时按策略重试。

资料来源：src/tools/tool-chain-orchestrator.ts:30-110

资源路由（Resource Router）

与工具的"调用即执行"不同，MCP 的 resources 是"读取即返回"的只读数据视图。src/resources/resource-router.ts 负责将客户端的 ReadResourceRequestSchema 请求按 URI scheme 分发到对应提供者，例如：

• adr://list：枚举已知 ADR 列表（可能来自缓存或文件系统）。
• adr://{id}：返回指定 ADR 的完整内容。
• template://{name}：返回生成新 ADR 时所使用的模板。
• validation://report：返回最近一次一致性验证的结构化报告。

路由表在 src/resources/index.ts 中集中注册，每个资源提供者在被调用时返回符合 MCP 规范的 contents 数组（含 uri、mimeType 与 text/blob）。资料来源：src/resources/resource-router.ts:1-70 资料来源：src/resources/index.ts:1-50

下表给出 Tools 与 Resources 的核心差异速览：

注册一致性约束

社区中常见的两类问题与本子系统密切相关：

1. 工具遗漏注册：Issue #612 的审计脚本会对比工具源文件数量与 ListToolsRequestSchema 中的注册数量，任何差异常常意味着新增工具未接入目录。开发者新增工具时，应同时更新 tool-catalog.ts 与 docs/reference/analysis-tools.md。
2. 文档与代码不同步：Issue #694、docs/QUICK_START.md 描述了过时工具集，导致新开发者按文档操作时找不到对应工具。文档与 catalog 必须以代码为准，避免"文档孤儿"。

资料来源：docs/reference/analysis-tools.md:1-60

通过以上四层结构——目录（catalog）→ 调度（dispatcher）→ 编排（orchestrator）→ 资源（resources）——MCP Tools Catalog and Resources 为 mcp-adr-analysis-server 提供了一个可发现、可调用、可观测且易于审计的工具与资源能力面，是整个 ADR 分析工作流的协议层入口。

概述

mcp-adr-analysis-server 是一个基于 Model Context Protocol（MCP）的服务器，其核心职责是让 AI Agent 能够对项目中的 架构决策记录（ADR） 进行检索、生成、校验与关联分析。本专题覆盖三大支柱能力：ADR 管理、知识图谱（Knowledge Graph）、智能代码链接（Smart Code Linking）。三者协同，使 ADR 不再是孤立的 markdown 文件，而是可被查询、可被推理、可被反向追溯到具体代码符号的语义网络。资料来源：src/utils/adr-discovery.ts:1-40

ADR 管理

ADR 管理模块负责 ADR 的发现、引导、校验与建议生成，对应一组 MCP 工具与底层工具函数。

• 发现（Discovery）：adr-discovery.ts 提供目录扫描与结构解析能力，用于在仓库的 docs/adrs/ 或自定义目录中定位 ADR 文件并提取元数据（编号、标题、状态、日期）。资料来源：src/utils/adr-discovery.ts:1-80
• 引导校验（Bootstrap Validation）：adr-bootstrap-validation-tool.ts 在项目初始化阶段检查 ADR 目录结构与必备模板字段是否齐全，避免后续分析出现空目录或格式不一致问题。资料来源：src/tools/adr-bootstrap-validation-tool.ts:1-60
• 建议生成（Suggestion）：adr-suggestion-tool.ts 基于当前代码改动与现有 ADR 内容，向 Agent 推荐是否需要新增或更新 ADR。资料来源：src/tools/adr-suggestion-tool.ts:1-90
• 离线 TODO 生成：v2.6.0 引入的 generate_adr_todo 工具（见 Release v2.6.0）将 ADR 拆解为离线可追踪的里程碑任务，便于无 LLM 推理环境下继续推进。资料来源：src/tools/generate-adr-todo-tool.ts:1-120

知识图谱

知识图谱将 ADR、概念标签（topic tags）、相关代码模块、负责人等节点统一建模为有向图，使 Agent 能够回答诸如"哪些 ADR 影响鉴权模块？"或"A 决策与哪些历史决策相矛盾？"之类的关系型问题。

• knowledge-graph-manager.ts 负责节点的增删改查、边的构建以及序列化输出（JSON / GraphML）。资料来源：src/utils/knowledge-graph-manager.ts:1-100
• 图谱的输入来自三处：ADR 文档的元数据、代码分析结果（见下一节）、Agent 在对话中显式声明的关系。资料来源：src/utils/knowledge-graph-manager.ts:60-140
• 节点典型字段包括 adrId、title、status、supersedes、linksToCode；边类型覆盖 supersedes、relates-to、implements、contradicts。资料来源：src/utils/knowledge-graph-manager.ts:40-90

智能代码链接

智能代码链接通过 tree-sitter 解析多语言源代码，抽取函数、类、模块等符号，并与 ADR 中提及的关键词进行匹配，从而在"决策"与"实现"之间建立可验证的桥接。

• tree-sitter-analyzer.ts 封装对 JS/TS、Python、Go 等语言的 AST 遍历，输出 Symbol 列表（名称、位置、签名）。资料来源：src/utils/tree-sitter-analyzer.ts:1-80
• 匹配阶段采用轻量级相似度（命名 + 注释关键词）将符号与 ADR 文本中的"受影响组件"段落对齐，生成 adr → symbol 的有向边并写回知识图谱。资料来源：src/utils/tree-sitter-analyzer.ts:80-150
• 当代码发生迁移时，重新分析可更新链接状态，从而支撑影响面分析（impact analysis）与漂移检测（drift detection）。资料来源：src/utils/tree-sitter-analyzer.ts:150-200

端到端工作流

下图描述一次典型的"代码改动 → ADR 建议 → 知识图谱更新"闭环：

flowchart LR
  A[代码改动] --> B[tree-sitter-analyzer]
  B --> C[提取符号]
  C --> D[knowledge-graph-manager]
  D --> E{匹配既有 ADR?}
  E -- 命中 --> F[更新链接]
  E -- 未命中 --> G[adr-suggestion-tool]
  G --> H[建议新 ADR]
  H --> I[generate_adr_todo]
  I --> J[离线里程碑]
  D --> K[知识图谱查询 API]

已知限制与社区关注

社区多次出现"AI Executor Integration failed"（#1187、#1235）类工作流失败，其根因是 Copilot CLI 在受限组织中无推理权限；该问题会同时阻断依赖 LLM 的 adr-suggestion-tool 调用，但不影响纯本地工具（如 generate_adr_todo 与 adr-bootstrap-validation）。另外，文档审查问题 #546 指出环境变量配置（OPENROUTER_API_KEY 等）说明缺失，使用本模块前应先确认对应密钥已正确注入。资料来源：issues/1187, issues/1235, issues/546

小结

• ADR 管理 提供发现、校验、建议、离线 TODO 完整链路。资料来源：src/tools/adr-bootstrap-validation-tool.ts:1-60
• 知识图谱 是连接 ADR 与外部实体（代码、标签、人员）的语义中枢。资料来源：src/utils/knowledge-graph-manager.ts:40-90
• 智能代码链接 通过 tree-sitter 把决策反向锚定到代码符号，实现可验证的影响面分析。资料来源：src/utils/tree-sitter-analyzer.ts:80-150

系统中的三层记忆模型

服务器的记忆体系分为三个相互协作的层次，每层由独立的工具模块负责：

1. 会话记忆层（Conversation Memory）：由 conversation-memory-manager.ts 管理，负责记录 MCP 工具调用产生的请求与响应序列，使后续调用能够引用先前结果 资料来源：src/utils/conversation-memory-manager.ts:1-120。
2. 实体记忆层（Entity Memory）：由 memory-entity-manager.ts 负责，将 ADR 中的概念（例如"技术选型"、"约束条件"、"决策后果"）抽象为实体对象，并提供增删改查接口 资料来源：src/utils/memory-entity-manager.ts:1-150。
3. 知识图谱层（Knowledge Graph）：由 knowledge-graph-manager.ts 构建实体间的关系边，把孤立的实体连接成可推理的结构 资料来源：src/utils/knowledge-graph-manager.ts:1-200。

三层之间存在单向的数据沉淀关系：会话记忆捕获原始交互 → 实体记忆从中抽取结构化条目 → 知识图谱进一步把条目组织为关系网络 资料来源：src/utils/memory-entity-manager.ts:40-95。

数据流动：从 MCP 请求到响应返回

下表梳理一次典型的工具调用所经过的核心组件：

状态强化阶段是服务器的特色设计：分析过程中会产生大量"弱信号"（例如重复出现的关键词、跨工具引用），state-reinforcement-manager.ts 负责把这些信号累计并放大，使关键的架构决策不易被噪声淹没 资料来源：src/utils/state-reinforcement-manager.ts:30-110。

分层响应与缓存策略

为了适配不同 LLM 客户端的上下文窗口限制，tiered-response-manager.ts 把响应分为多档：完整响应、摘要响应、要点响应。该模块在生成内容前会检查当前上下文的剩余容量，并自动选择合适的输出层级 资料来源：src/utils/tiered-response-manager.ts:1-80。

cache.ts 提供基于键值的内存缓存，用于存储昂贵的计算结果（例如跨多个 ADR 的依赖分析、知识图谱遍历结果等）。缓存键通常由工具名称与参数哈希组合而成，确保相同输入直接命中，避免重复计算 资料来源：src/utils/cache.ts:20-90。当会话记忆被清理时，缓存也会根据配置的失效策略同步淘汰 资料来源：src/utils/cache.ts:95-140。

跨调用的状态维持

服务器的状态在三个时间维度上得到维持：

• 请求内：通过函数参数与局部变量直接传递。
• 会话内：依赖 conversation-memory-manager.ts 与 memory-entity-manager.ts 持久化的会话上下文。
• 会话间：通过 state-reinforcement-manager.ts 的强化状态以及磁盘/缓存层共同承载，使后续会话能够继承前次分析结论。

社区审计记录（issue #612）显示，"mcp-tool-check" 工具一致性报告中曾发现 search_tools 工具注册缺失问题，提示所有涉及记忆与状态的工具必须正确接入 ListToolsRequestSchema，否则状态维持链路会出现断点 资料来源：issue #612 — MCP Tool Consistency Report。同样地，文档审查（issue #546 与 #694）多次指出环境变量与执行模式配置不清晰可能影响 EXECUTION_MODE=full 下的状态保留行为，开发者应在调用前正确设置 OPENROUTER_API_KEY 等关键环境变量 资料来源：issue #546 — Documentation Review。

关键设计要点

• 单一职责：每个管理器只负责一个层级的职责，便于单独替换或测试。
• 可观测性：所有记忆操作都暴露日志与指标接口，便于追踪状态变化。
• 降级能力：当上游 LLM 不可用时，tiered-response-manager.ts 与 cache.ts 协同提供离线响应能力（v2.6.0 引入的 generate_adr_todo 即具备此特性）资料来源：Release v2.6.0。
• 一致性约束：知识图谱层与实体记忆层之间通过实体 ID 关联，任何一方的不一致都会触发同步校验。

AI/LLM 集成与提示工程

概述与职责范围

本项目的 AI/LLM 集成层为 MCP ADR 分析服务器提供"模型无关"的可执行接口,使各类架构决策记录(ADR)分析工具能够通过统一的抽象调用大语言模型。核心目标包括:统一 OpenRouter、本地模型、Copilot CLI 等多种后端;提供自动提示工程(APE)、思维链(CoT)增强、反思(Reflexion)等提示优化手段;以及为上层工具提供一致的超时、重试与脱机降级策略。资料来源：src/utils/ai-executor.ts:1-80

ai-executor.ts 模块定义了 callAIModel、executeWithFallback、getExecutionConfig 等关键入口,集中处理环境变量 EXECUTION_MODE、OPENROUTER_API_KEY 等配置,并在缺失推理凭据时主动抛出可识别的错误,以避免静默失败。资料来源：src/utils/ai-executor.ts:40-120

提示工程组件

自动提示工程 (APE)

automatic-prompt-engineering.ts 实现了一种基于候选生成与评分筛选的提示优化管线:首先生成若干候选指令,再用一个评分函数(通常结合目标任务的样本输出)挑选最优指令,最后将优化后的提示作为系统消息注入到后续调用中。该模块常被用于"生成 ADR 摘要"、"提取决策上下文"等需要稳定输出的工具。资料来源：src/utils/automatic-prompt-engineering.ts:1-60

思维链 (Chain-of-Thought) 增强

chain-of-thought-template.ts 提供标准化的 CoT 模板,包含"角色定义 → 任务说明 → 推理步骤 → 输出格式"四段结构。apply-cot-enhancement.ts 则负责在运行时将 CoT 模板按工具上下文进行参数化注入,确保不同工具(如 analyze_adr、generate_adr_todo)既能共享推理骨架,又能保留各自的领域语义。资料来源：src/utils/chain-of-thought-template.ts:1-50 src/utils/apply-cot-enhancement.ts:1-50

反思机制 (Reflexion)

reflexion.ts 引入了自我评估-重试循环:模型首轮输出后,系统会根据预设的"质量判据"(例如 ADR 必填字段完整性、引用准确性)对结果打分;若未达标,则把评判意见作为附加反馈回传模型,触发二次生成。该机制显著降低了在结构化输出场景下的格式错误率。资料来源：src/utils/reflexion.ts:30-90

执行管线与降级策略

prompt-execution.ts 是上层工具与 AI 执行器之间的桥梁,负责封装"提示组装 → 调用 ai-executor → 结果校验 → 缓存/降级"的完整生命周期。下图展示了典型的执行流:

flowchart LR
  A[Tool 调用] --> B[prompt-execution 组装提示]
  B --> C{是否启用 CoT?}
  C -- 是 --> D[apply-cot-enhancement 注入模板]
  C -- 否 --> E[直接使用 APE 优化后的提示]
  D --> F[ai-executor 调用模型]
  E --> F
  F --> G{是否启用 Reflexion?}
  G -- 是 --> H[反思评分与重试]
  G -- 否 --> I[返回结果]
  H --> I

执行层支持多种 EXECUTION_MODE,例如 full、local-only、offline。在 offline 模式下,系统跳过模型调用,改为返回基于规则的回退结果,以保证 CI 与文档站验证流程不会因凭据缺失而中断。资料来源：src/utils/ai-executor.ts:80-160 src/utils/prompt-execution.ts:40-100

已知限制与社区反馈

社区中已记录的 AI Executor Integration 工作流多次出现"Inference Access Denied"错误,通常发生在 Copilot CLI 使用的令牌不具备推理权限时(#1187、#1235)。这属于上游凭据配置问题,而非本仓库代码缺陷;在自托管场景下,可改用 OPENROUTER_API_KEY 或本地模型后端绕过。此外,文档站审计(#542)与"无经验开发者"测试(#546、#694)曾指出,环境变量说明在多版 README 中不够明确,建议在部署前显式设置 OPENROUTER_API_KEY 与 EXECUTION_MODE 以避免运行时降级。资料来源：issue #1235 issue #1187 issue #546

部署、基础设施与可扩展性

1. 部署范围与设计目标

mcp-adr-analysis-server 是一个基于模型上下文协议（MCP）的 Node.js 服务器，向客户端暴露 ADR（架构决策记录）分析工具。为覆盖本地开发、CI、桌面端与生产云环境，仓库在 docs/ 目录集中提供统一的多形态部署说明：主指南 DEPLOYMENT_GUIDE.md 给出总体策略与运行模式，DOCKER_SETUP.md 描述容器化路径 资料来源：docs/DEPLOYMENT_GUIDE.md:1-40。在 v2.5–v2.6 系列中，发布流水线经历了多次修补：v2.5.4（PR #810）将 publish.yml 改造为“单一事实来源”的发布闸门；v2.6.2（PR #863）修复其 workflow_call 检测；v2.6.6（PR #890）允许发布机器人在 PR 关闭后再次打开时继续轮询 资料来源：docs/DEPLOYMENT_GUIDE.md:60-110。

2. 容器化部署

容器路径由 docs/Dockerfile 与 docs/docker-compose.yml 共同定义。Dockerfile 采用多阶段构建以减小最终镜像体积，并固定与 package.json 中一致的 Node 基础镜像版本 资料来源：docs/Dockerfile:1-30。docker-compose.yml 将服务器、可选推理服务与挂载卷编排为单一栈，使 docker compose up 即可复现接近生产的环境 资料来源：docs/docker-compose.yml:1-45。

部署栈的组件关系如下：

flowchart LR
    A[mcp-adr-analysis-server 容器] --> B[(本地 ADR 目录挂载)]
    A --> C[OpenRouter 推理 API]
    A --> D[(缓存/产物卷)]
    A --> E[GitHub MCP / AI Executor]

容器运行支持通过 EXECUTION_MODE 在 full 与只读分析模式之间切换，相关环境变量约定见 DOCKER_SETUP.md 资料来源：docs/DOCKER_SETUP.md:20-55。

3. 基础设施即代码：AWS 模式

仓库在 patterns/infrastructure/aws.yaml 中提供基础设施即代码模板，使用 AWS 原生格式描述 VPC、子网、IAM 角色、ECR 仓库以及用于运行容器的计算资源 资料来源：patterns/infrastructure/aws.yaml:1-80。与 DEPLOYMENT_GUIDE.md 中云端部署章节配合，可将本地 docker-compose.yml 描述的服务拓扑平滑迁移到 ECS Fargate 或 EKS 资料来源：docs/DEPLOYMENT_GUIDE.md:120-180。

社区报告（#690 “CI Doctor”）指出：aws.yaml 触发的部署曾因 gh-aw 锁文件不一致以及 npm 依赖漏洞而失败，修复后需要重新触发工作流并校验镜像 tag。

4. 主机安装与 CI/CD 流水线

针对无法使用容器的环境，scripts/install-rhel.sh 在 RHEL/CentOS 系列上自动安装 Node、克隆仓库并配置 systemd 单元，使服务以守护进程方式运行 资料来源：scripts/install-rhel.sh:1-60。该脚本与 Docker 路径共享同一份环境变量约定（OPENROUTER_API_KEY、EXECUTION_MODE 等），便于在不同形态间保持行为一致 资料来源：scripts/install-rhel.sh:60-110。

CI/CD 侧，发布由 publish.yml 驱动：v2.5.4 统一发布闸门，v2.5.3 与 v2.6.2 多次修补 tag→npm 同步以及 workflow_call 识别逻辑，v2.6.6 让 bump PR 在关闭后仍能被继续轮询 资料来源：docs/DEPLOYMENT_GUIDE.md:200-280。社区观察的 AI Executor Integration 失败（#1187、#1235）说明：尽管发布闸门已统一，Copilot CLI 推理访问令牌仍是工作流稳定性的外部依赖，仓库通过 Dependabot（如 PR #910 升级 github/gh-aw-actions）持续缓解该风险。

5. 可扩展性实践

扩展此服务的常见路径包括：

• 在 docker-compose.yml 中新增 sidecar 容器（如向量库或缓存代理）；
• 在 aws.yaml 中追加 Fargate Service、目标组与自动伸缩策略；
• 新增 scripts/install-*.sh 覆盖更多 Linux 发行版；
• 在 ListToolsRequestSchema 中注册自定义 MCP 工具（参考 #612 一致性审计所记录的 search_tools 缺失问题）。

所有扩展都应与 DEPLOYMENT_GUIDE.md 中定义的环境变量与运行模式保持一致。社区在 #546 “Documentation Noob Test” 中也指出，环境变量设置与运行模式说明需要在 README 中显式给出，否则新用户将无法正确启动容器或主机部署。

本页面系统化介绍 mcp-adr-analysis-server 项目在运维、测试、故障排查与版本发布四个维度的工程实践。该项目是一个基于模型上下文协议（Model Context Protocol, MCP）的架构决策记录（Architecture Decision Records, ADR）分析服务器，提供了 70+ 个工具来辅助架构分析、知识管理及代码智能处理。由于工具面广、依赖模型推理与 GitHub Actions 自动化，构建一个可重复、可观察、可回滚的工程体系至关重要 资料来源：RELEASES.md:1-40。

1. 运维（Operations）

项目的日常运维主要围绕 GitHub Actions 工作流展开，涵盖持续集成、安全扫描、依赖更新与发布流水线四个核心工作流。

1.1 AI Executor Integration 工作流

AI Executor Integration 工作流是项目最关键的自动化入口之一，用于驱动 Copilot CLI 执行模型推理任务。在最近的多次运行中（例如 #29143226313、#28649312387），该工作流频繁出现 Inference Access Denied 错误，原因是令牌未配置对推理端点的访问权限。资料来源：docs/how-to-guides/troubleshooting.md:1-60。运维人员应确保：

• 组织或仓库已为 Copilot CLI 启用模型推理能力；
• 工作流使用的 GITHUB_TOKEN 拥有足够的 models:read 权限作用域；
• 私有组织需要在设置中显式开启「Allow access to models in this organization」开关。

1.2 依赖与构建更新

@dependabot[bot] 负责周期性地拉起依赖升级 PR，例如 github/gh-aw-actions 从 0.71.1 升级到 0.71.4 的 PR #910、 @rollup/rollup-win32-x64-msvc 从 4.60.2 到 4.60.4 的 PR #929，均通过自动发布流水线直接生成对应版本标签 资料来源：CHANGELOG.md:1-20。

2. 测试（Testing）

测试体系分为单元测试、工具一致性审计与文档无障碍测试三层，确保每次发布前变更既不破坏 API 契约，也保障新开发者上手顺畅。

2.1 工具一致性审计

mcp-tool-check 工作流会扫描 34 个工具源文件并与 ListToolsRequestSchema 中注册的 72 个工具对比。最新一次审计发现 search_tools 工具存在「工具未注册」问题（issue #612），提示开发者在新增工具时必须同步更新中心化的注册表与模式声明 资料来源：docs/how-to-guides/testing-guide.md:1-80。

2.2 文档无障碍测试

docs-noob 自动化测试以新开发者视角审视 docs/ 目录下的 171–172 份 Markdown 文件。在 2026-04-19 与 2026-02-21 的两次扫描中，分别发现了 19 项和 47 项问题，其中关键问题包括 docs/QUICK_START.md 描述了与现状不符的文档系统，以及环境变量配置说明缺失 资料来源：docs/TESTING_GUIDE.md:1-60。

3. 故障排查（Troubleshooting）

常见故障集中在三类：CI 失败、文档与代码不一致、以及 AI Executor 推理拒绝。

CI Doctor 自动诊断工作流（如 #24636103297）将两类故障聚合在同一份报告中，运维者只需按其引用的提交 8f650881f6db2dbe131f4472da3192de4eec7a3f 回溯 bisect 即可定位根因 资料来源：docs/how-to-guides/troubleshooting.md:60-140。

4. 发布（Release）

发布流水线以 publish.yml 为唯一权威闸门（single source of truth），任何到 main 分支的合并都会触发自动版本号提升与 npm 发布。

4.1 版本管理策略

docs/VERSION_MANAGEMENT.md 定义了语义化版本（SemVer）规则：次要版本用于新增功能（如 v2.6.0 引入 generate_adr_todo 工具），补丁版本用于修复 CI/发布管线问题（例如 v2.6.6 的「容忍 bump PR 的 close+reopen」、v2.6.2 的 workflow_call 检测修复） 资料来源：docs/VERSION_MANAGEMENT.md:1-80。

4.2 发布管线演化

项目曾在 v2.5.3 之前遇到 GitHub 标签未正确同步到 npm 的问题（PR #808），后续在 v2.5.4 通过「将 publish gate 作为单一真实来源」彻底重构，确保标签、CHANGELOG 与 npm 包版本三者始终一致 资料来源：RELEASES.md:1-60。

4.3 文档站点验证

docs-site 工作流对部署到 GitHub Pages 的站点执行每周一次的爬取校验。2026-02-20 的运行（issue #542）抓取 7 个页面样本并发现 3 处问题，运维团队据此向文档作者派发修复工单 资料来源：docs/how-to-guides/testing-guide.md:80-140。

Pitfall Log / 踩坑日志

项目：tosin2013/mcp-adr-analysis-server

摘要：发现 19 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安全/权限坑 - 失败模式：security_permissions: [aw] AI Executor Integration failed。

1. 安全/权限坑 · 失败模式：security_permissions: [aw] AI Executor Integration failed

• 严重度：high
• 证据强度：source_linked
• 发现：Developers should check this security_permissions risk before relying on the project: [aw] AI Executor Integration failed
• 对用户的影响：Developers may expose sensitive permissions or credentials: [aw] AI Executor Integration failed
• 证据：failure_mode_cluster:github_issue | https://github.com/tosin2013/mcp-adr-analysis-server/issues/1235 | [aw] AI Executor Integration failed, failure_mode_cluster:github_issue | https://github.com/tosin2013/mcp-adr-analysis-server/issues/1187 | [aw] AI Executor Integration failed

2. 安全/权限坑 · 来源证据：[aw] AI Executor Integration failed

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[aw] AI Executor Integration failed
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/tosin2013/mcp-adr-analysis-server/issues/1235 | 来源类型 github_issue 暴露的待验证使用条件。

3. 安装坑 · 失败模式：installation: Release v2.5.1

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Release v2.5.1
• 对用户的影响：Upgrade or migration may change expected behavior: Release v2.5.1
• 证据：failure_mode_cluster:github_release | https://github.com/tosin2013/mcp-adr-analysis-server/releases/tag/v2.5.1 | Release v2.5.1

4. 安装坑 · 失败模式：installation: Release v2.5.3

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Release v2.5.3
• 对用户的影响：Upgrade or migration may change expected behavior: Release v2.5.3
• 证据：failure_mode_cluster:github_release | https://github.com/tosin2013/mcp-adr-analysis-server/releases/tag/v2.5.3 | Release v2.5.3

5. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/tosin2013/mcp-adr-analysis-server | host_targets=mcp_host, claude, cursor

6. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/tosin2013/mcp-adr-analysis-server | README/documentation is current enough for a first validation pass.

7. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/tosin2013/mcp-adr-analysis-server | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/tosin2013/mcp-adr-analysis-server | no_demo; severity=medium

9. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/tosin2013/mcp-adr-analysis-server | no_demo; severity=medium

10. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/tosin2013/mcp-adr-analysis-server | issue_or_pr_quality=unknown

11. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/tosin2013/mcp-adr-analysis-server | release_recency=unknown

12. 维护坑 · 失败模式：maintenance: Release v2.5.2

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: Release v2.5.2
• 对用户的影响：Upgrade or migration may change expected behavior: Release v2.5.2
• 证据：failure_mode_cluster:github_release | https://github.com/tosin2013/mcp-adr-analysis-server/releases/tag/v2.5.2 | Release v2.5.2

13. 维护坑 · 失败模式：maintenance: Release v2.5.4

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: Release v2.5.4
• 对用户的影响：Upgrade or migration may change expected behavior: Release v2.5.4
• 证据：failure_mode_cluster:github_release | https://github.com/tosin2013/mcp-adr-analysis-server/releases/tag/v2.5.4 | Release v2.5.4

14. 维护坑 · 失败模式：maintenance: Release v2.6.0

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: Release v2.6.0
• 对用户的影响：Upgrade or migration may change expected behavior: Release v2.6.0
• 证据：failure_mode_cluster:github_release | https://github.com/tosin2013/mcp-adr-analysis-server/releases/tag/v2.6.0 | Release v2.6.0

15. 维护坑 · 失败模式：maintenance: Release v2.6.1

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: Release v2.6.1
• 对用户的影响：Upgrade or migration may change expected behavior: Release v2.6.1
• 证据：failure_mode_cluster:github_release | https://github.com/tosin2013/mcp-adr-analysis-server/releases/tag/v2.6.1 | Release v2.6.1

16. 维护坑 · 失败模式：maintenance: Release v2.6.2

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: Release v2.6.2
• 对用户的影响：Upgrade or migration may change expected behavior: Release v2.6.2
• 证据：failure_mode_cluster:github_release | https://github.com/tosin2013/mcp-adr-analysis-server/releases/tag/v2.6.2 | Release v2.6.2

17. 维护坑 · 失败模式：maintenance: Release v2.6.7

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: Release v2.6.7
• 对用户的影响：Upgrade or migration may change expected behavior: Release v2.6.7
• 证据：failure_mode_cluster:github_release | https://github.com/tosin2013/mcp-adr-analysis-server/releases/tag/v2.6.7 | Release v2.6.7

18. 维护坑 · 失败模式：maintenance: Release v2.6.8

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: Release v2.6.8
• 对用户的影响：Upgrade or migration may change expected behavior: Release v2.6.8
• 证据：failure_mode_cluster:github_release | https://github.com/tosin2013/mcp-adr-analysis-server/releases/tag/v2.6.8 | Release v2.6.8

19. 维护坑 · 失败模式：maintenance: v2.6.6

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v2.6.6
• 对用户的影响：Upgrade or migration may change expected behavior: v2.6.6
• 证据：failure_mode_cluster:github_release | https://github.com/tosin2013/mcp-adr-analysis-server/releases/tag/v2.6.6 | v2.6.6