多MCP企业运营副驾驶

面向工厂运营人员的副驾驶。它通过专用MCP服务器调用告警管理API、从运营文档语料库中检索相关段落，并将两者融合为一条带引用和可视化执行轨迹的可靠答案，从而回答自然语言问题。

git clone <repository-url> && cd senior-copilot-mcp-rag-assignment
cp .env.example .env
docker compose up --build

然后打开 http://localhost:5173 并提出验收问题。无需API密钥——堆栈默认使用一个无需LLM即可运行相同工作流的确定性提供程序。如需生成散文，请设置 LLM_PROVIDER=anthropic 和 ANTHROPIC_API_KEY。

1 · 选定用例

多MCP企业运营副驾驶。 该副驾驶可发现并协调跨两个MCP服务器的工具，而非硬编码集成，并在一个工作流中将结构化数据与非结构化文档证据相结合。

强制验收场景：

调查过去90天内锅炉给水泵101反复出现的高严重性告警，识别可能的促成因素，检索相关操作规程，并提供带源证据的建议措施。

该场景作为自动化测试运行（tests/e2e/test_acceptance_scenario.py），它通过真实HTTP接口断言：五个步骤均已执行，步骤2接收了步骤1生成的资产ID，检索范围已按步骤1解析的资产名称缩小，并且答案中包含 [tool: …] 和 [source: …] 标记。

关于源系统的说明

简报中描述的告警管理API并非一个正在运行的服务——所提供的Postman集合就是其规范。因此，它也在此构建为 services/alarm-simulator/：15个端点、Bearer认证、跟踪头、错误信封以及确定性的种子数据，确保所提供的集合中的每个链接断言都返回非空结果。make contract 对该模拟器运行所有三个集合；CI在每次推送时执行相同操作。

2 · 主要功能

• 针对实时告警数据和运营文档的自然语言聊天

• 跨两个MCP服务器的运行时工具发现——无硬编码工具列表

• 多步工具链，其中一个工具的输出成为下一个工具的输入

• 混合文档检索（BM25 + 稠密向量，通过倒数排序融合）并带有内联引用

• 一条结合了结构化工具结果和非结构化文档证据的答案

• 完整执行轨迹：哪个服务器、哪个工具、什么参数、耗时多久、什么结果

• 任何写入操作前需明确人工确认，在工具契约中强制执行

• 在工具故障、超时、无效模式、检索为空、模型拒绝或缺少API密钥等情况下的优雅降级

3 · 技术栈

4 · 架构概要

五个服务。GUI通过REST和SSE与FastAPI编排器通信。编排器针对从两个MCP服务器运行时发现的工具注册表规划一系列步骤，解析每个步骤的参数（包括先前步骤产生的值），将文档检索作为其中一个步骤运行，并组合成一条带引用的答案。

Browser ──HTTP/SSE──▶ backend ──MCP──▶ mcp-alarm-management ──HTTPS+bearer──▶ alarm-simulator
                         │      └────▶ mcp-github-issues    ──────────────▶ GitHub (mocked)
                         └─embedded──▶ Chroma index over rag/documents

只有MCP服务器持有其背后系统的凭证。副驾驶从不直接调用告警管理API，因此语言模型没有通往Bearer令牌的代码路径——它无法读取、请求该令牌，也无法通过提示注入被诱导泄露它。

• 端到端请求流程：docs/architecture.md

• 组件、ADR、NFR、风险、可追溯性：docs/hld.md

• 模式、签名、算法、状态机：docs/lld.md

5 · MCP服务器和工具

两个候选构建的服务器。完整契约——包括输入/输出模式、认证行为、错误行为、超时以及真实示例请求和响应——位于 docs/mcp-tool-catalog.md，该文件由实时的 list_tools() 调用生成并在CI中检查，因此不会与代码脱节。

alarm-management — 14个工具

github-issues — 3个工具

单独运行一个

python -m alarm_mcp                      # stdio, for a local MCP client
python -m alarm_mcp --transport http     # streamable HTTP, as in compose
python scripts/mcp_smoke.py              # chain two tools, no GUI and no LLM

6 · RAG语料库和摄入

10个Markdown文档（操作规程、故障排除指南、标准、安全说明、供应商公告）→ 49个按标题对齐的块 → 嵌入的Chroma索引。

python -m rag.ingestion.cli --docs ./rag/documents --reset

检索融合了BM25和稠密向量，并按早期工具调用解析的资产进行过滤，对于弱匹配报告 low_confidence 而非粉饰。一个语料库文档包含一个实时提示注入载荷，因此信任边界是经过测试而非仅声称的。

完整设计——分块、元数据、融合、引用构建、置信度、注入防御、刷新：docs/rag-design.md。

7 · 配置

每个值都是一个环境变量。.env.example 用安全占位符记录了每个键；未提交任何秘密，运行演示也不需要任何秘密。

完整参考（含类型、默认值和使用服务）：docs/lld.md §9。

8 · 构建和运行

make 是标准方式，也是CI使用的。在没有 make 的Windows上，tasks.ps1 提供相同的目标名称。

端口：GUI 5173，后端 8080，模拟器 8000（已暴露以便Postman集合可对其运行），MCP服务器 9000 / 9001（内部）。

如果其中某个端口已被占用，请在 .env 中覆盖主机端——容器端口从不改变。将 VITE_API_BASE_URL 设置为匹配后端端口，因为Vite在构建时将其内联到GUI中：

BACKEND_HOST_PORT=8090 VITE_API_BASE_URL=http://localhost:8090 docker compose up --build

不使用Docker：make install，然后在四个独立终端中运行四个Python服务——uvicorn alarm_simulator.main:app --port 8000，python -m alarm_mcp --transport http，python -m github_mcp --transport http，make ingest，uvicorn copilot_backend.api.app:app --port 8080——并在 apps/frontend 中运行 npm run dev。

9 · 测试

make contract 需要newman (npm install -g newman) 和一个正在运行的模拟器。

269 个测试，全部通过，89% 的行覆盖率 — 详细说明见 docs/coverage.md。覆盖范围：

LLM 在所有地方都被模拟，包括端到端，因此测试套件快速、免费且可重复。有关含义，请参见 docs/known-limitations.md。

10 · 示例交互

重复报警（验收场景）。 五个步骤：解析资产 → 汇总其高严重性报警 → 关联共现对 → 查找合理化候选 → 检索规程，按刚解析的资产过滤。答案报告 Discharge Pressure Low 后跟 Suction Strainer DP High 共 31 次（提升度 2.29，平均滞后 393 秒） [tool: alarm-management/get_alarm_correlation]，并将其与来自 [source: OP-BFP-101#…] 的隔离和检查步骤配对。

操作员响应效率。 generate_calculation → execute_calculation（在 calculation_id 上链式调用）→ 确认延迟趋势 → 来自 STD-OPRESP 的适用标准。

升级。 活动报警 → 最高报警的优先级评分 → 带有相关报警上下文的推荐操作 → 匹配的报警哲学部分。

提交问题。 报警摘要 → 重复检查 → draft_issue。create_issue 以 confirmation.required 停止运行；GUI 显示确切参数，仅在批准后继续。无论 UI 做什么，MCP 服务器都会拒绝。

一个没有支持文档的问题。 检索报告 low_confidence；答案明确说明未找到相关规程，而不是用一般知识替代。

11 · 仓库布局

apps/backend/          FastAPI orchestrator, MCP client, LLM providers
apps/frontend/         React + TypeScript GUI
mcp-servers/           alarm-management (14 tools), github-issues (3 tools)
services/              alarm-simulator — the candidate-built source system
connectors/alarm_api/  Reusable HTTP client, deliberately separate from the MCP server
packages/schemas/      Shared Pydantic tool contracts
rag/                   documents, ingestion, retrieval, tests
tests/                 unit, integration, e2e
docs/                  architecture, HLD, LLD, tool catalog, RAG design, decisions, limits
postman/               The supplied collections — the Alarm API specification

与提交指南 §3 中结构有两个记录的偏差：

• services/alarm-simulator/ — 简要说明单独要求一个由候选人构建的后端，这不是预命名文件夹之一。将模拟器（被集成的系统）与 connectors/（访问它的客户端）分开，比将两者合并在一起更清晰。

• docs/hld.md 和 docs/lld.md — 与必需的 docs/architecture.md 一起添加，后者仍然是入口点。

指南允许在明确记录的情况下使用等效结构。由于强制目录名称是连字符分隔的，因此不是有效的 Python 包名称，每个目录都包含一个正确命名的包（mcp-servers/alarm-management/alarm_mcp/），映射到 pyproject.toml 中的顶级导入。

12 · 假设

1. 报警管理 API 不存在，因此 Postman 集合被视为其规范，模拟器被构建为完全满足它们。在集合未说明的地方（例如，仅出现在链式集合中的过滤器），集合的断言是权威。

2. 报警 ID、资产 ID 和时间戳是可重现的。 种子是固定的，因此演示、测试和 Postman 运行都看到相同的数据。

3. 关联意味着在同一资产上的滞后窗口内共现。 统计显著性测试超出了合成数据的范围。

4. 一个租户，一个站点资产。 没有租户标识符贯穿检索或工具授权。

5. GUI 到后端的跳转是未认证的，这对于本地演示是可接受的，并在限制中明确指出。

6. docker compose up 是受支持的路径。 手动路径在 §8 中有记录，但 CI 执行的是 compose 文件。

13 · 已知限制和未来改进

诚实的范围边界，每个都说明了如果有更多时间会如何不同处理： docs/known-limitations.md。接下来要做的事情，按我执行的顺序： docs/future-improvements.md。

14 · 演示

截图

通过 make screenshots 从运行堆栈捕获，因此可以重新生成而不会过时： docs/screenshots/。

还捕获了：空状态 和 带引用芯片的答案。

视频

链接： 待添加 — 参见 docs/demo.md 了解录制的演练脚本。

它涵盖了端到端的验收场景、带模式检查的工具发现、执行时间线、解析为证据的引用芯片、写入确认门控，然后是失败路径 — 模拟器在会话中途停止以显示重试、降级答案和诚实的空白。

许可证

MIT — 参见 LICENSE。