Pyrus AI 生态系统 — MCP 基础设施

本仓库是 Pyrus MCP 基础设施服务及其支持的人工智能工程团队的实现与治理中心。它还包含未来 Knowledge MCP 的架构规范与路线图，该服务拥有独立的数据存储与生命周期。

产品边界

AI clients / employees
        |
        +---------------------+
        |                     |
        v                     v
   Pyrus MCP             Knowledge MCP
   Pyrus actions         canonical knowledge
        |                     |
        v                     v
     Pyrus API          PostgreSQL/pgvector
        ^                     ^
        |                     |
        +------- PyrusBot ----+
             orchestration

Pyrus MCP

一个生产级外部服务，允许授权员工/AI 主机通过 MCP 执行 Pyrus 操作。它可独立部署，且不得依赖开发者工作站。

Knowledge MCP

一个独立的 MCP 服务，用于规范化的版本化文档、证据/谱系、语义嵌入、混合检索，以及通过 Pyrus MCP 向 Pyrus 知识库进行受控发布。

PyrusBot

一个未来的编排/应用层，将消费这两个 MCP。它后续可演变为聊天机器人、CLI、Web 工具或 IDE 适配器，而无需更改基础设施契约。

Related MCP server: MCP Gateway

当前优先级

Pyrus MCP 的生产就绪优先级最高。 Knowledge MCP 并行进行规范，但在其契约获得批准后才实施。PyrusBot 的集成在基础设施契约稳定后进行。

规范性文档

• IMPLEMENTATION_PLAN.md — 规范性实施入口点。

• docs/architecture/system-architecture-v2.md — 完整系统架构。

• docs/architecture/contracts-v2.md — MCP、Pyrus API、安全、Webhook 和 Knowledge 契约。

• docs/planning/production-roadmap-v2.md — 阶段路线图与并行化规则。

• tasks/registry.yaml — 可执行任务图，包含所有者、审查者、关卡和依赖关系。

• contracts/pyrus-tool-catalog.yaml — 可恢复的遗留兼容性目录；当前因遗留证据未恢复而阻塞。

• docs/qa/gates.md — 合并/发布/生产验收关卡。

• docs/ai-team/agent-registry.yaml — 工程角色与权限。

当前关键阻塞项

1. 先前计划引用了 pyrus_mcp_tools_spec.json 和 inventory.json，但这些工件在当前仓库中不存在。在声明 1:1 对等性之前，必须恢复确切的遗留契约。

2. 可见计划显示“61 个工具”，但当前可见的分组列表无法独立验证该数字。因此，确切的遗留工具数量和名称是一个 P0 契约恢复任务。

3. 单一的 SERVER_AUTH_TOKEN 不足以作为多用户生产授权模型。目标是兼容 MCP/OAuth 的承载授权、受众验证、作用域、租户绑定、撤销和审计。

4. SQLite 是本地开发选项，而非持久化的生产系统记录。

工程栈

Pyrus MCP

Python 3.11+ 策略；uv；FastMCP；Streamable HTTP；用于本地测试的 stdio；Pydantic；httpx；pytest；Ruff；静态类型检查；PostgreSQL；可选 Redis；Docker；GitHub Actions；外部密钥管理。

Knowledge MCP

Python + FastMCP；PostgreSQL + pgvector；用于大型/原始工件的对象存储；嵌入提供者适配器（含模型/版本记录）；后台索引/嵌入作业；可选 Redis；相同的生产安全与可观测性规范。

开发模型

每个实施项有一个主执行者、一个独立审查者，以及明确的关卡所有者。当一个任务包含多个可独立测试的结果时，应将其拆分。新发现会创建关联任务，而非静默扩展范围。

生产发布需通过架构、契约、安全、QA、持久化、可观测性、预发布和发布检查。

有用命令

node scripts/dashboard-server.mjs
# Open http://localhost:4748/

仪表盘是任务注册表的接口；注册表及上述文档仍为真理之源。