架构文档服务

MCP架构服务

一种模型上下文协议（MCP）服务器，通过JSON-RPC通信提供对架构指南、模式和架构决策记录（ADR）的结构化访问。

概述

此服务实现了MCP规范，使AI代理和IDE集成能够发现和检索作为上下文资源的架构文档。它监控文档目录以获取实时更新，并提供对架构知识库的快速缓存访问。

可用MCP资源

该服务通过以下URI模式公开文档：

• architecture://guidelines/{path} -建筑指南来自 mcp/resources/guidelines/
• architecture://patterns/{path} -设计模式来自 mcp/resources/patterns/
• architecture://adr/{adr_id} -架构决策记录来自 mcp/resources/adr/

可用MCP提示

该服务提供交互式提示，将说明与架构文档相结合：

• 根据模式审查代码 -根据记录的架构模式审查代码

  • 论据： code （必填，最多10000个字符）， language （可选）
  • 嵌入相关模式文档以供比较

• 建议模式 -建议问题描述的相关模式

  • 论据： problem （必填，最多2000个字符）
  • 嵌入完整的模式目录以供分析

• 创建adr -协助创建新的架构决策记录

  • 论据： topic （必填）
  • 嵌入示例ADR和模板结构

可用的MCP工具

该服务提供可执行工具，使AI代理能够对架构文档执行操作：

• 根据模式进行验证 -根据记录的模式验证代码的合规性
• 搜索架构 -在指南、模式和ADR中按关键字搜索文档
• 检查adr对齐情况 -检查拟议决策是否与现有ADR一致

看 工具开发指南 了解详细的模式、示例以及如何创建自定义工具。

MCP协议支持

资源

• initialize -服务器初始化和能力协商
• notifications/initialized -初始化确认
• resources/list -列出所有可用的文档资源
• resources/read -阅读特定的文档资源内容

提示词

• prompts/list -列出所有可用的交互式提示
• prompts/get -使用参数调用提示符以获取呈现的内容

工具

• tools/list -列出所有可用的可执行工具及其模式
• tools/call -使用经过验证的参数执行工具

补全

• completion/complete -获取提示参数的自动补全建议
  • 支持 pattern_name, guideline_name，以及 adr_id 参数
  • 提供基于前缀的智能过滤

通过JSON-RPC 2.0通过stdio（本地）或TCP（桥接模式）进行通信。

快速开始

先决条件

• 转到1.21或更高版本
• VSCode或fork（或任何支持具有MCP配置的AI代理的IDE）

构建

make build-bridge

配置

增添 .vscode/settings/mcp.json 在您的工作空间中：

{
  "servers": {
    "architecture-service": {
      "command": "nc",
      "args": ["localhost", "8080"],
      "disabled": false,
      "autoApprove": ["resources/list", "resources/read", "prompts/list", "prompts/get", "tools/list"]
    }
  }
}

跑

启动MCP网桥服务器：

make run-bridge

服务器将：

1. 在TCP端口8080上监听
2. 监视器 mcp/resources/ 和 mcp/prompts/ 更改目录
3. 为每个客户端连接创建专用的MCP服务器进程
4. 提供对架构文档的实时访问

测试

在客户端IDE上验证代理是否已连接并显示为正在运行（通过检查服务器日志或客户端本身）。编写提示并尝试获取可用资源之一。

添加文档

将您的markdown文件放在以下目录中：

mcp/
├── resources/
│   ├── guidelines/     # Architectural guidelines
│   ├── patterns/       # Design patterns
│   └── adr/            # Architecture Decision Records
└── prompts/            # Prompt definitions (JSON)

服务器会自动检测新文件并为其建立索引。

用法

AI代理可以通过标准MCP方法与服务交互。请参阅 架构概述 了解详细的协议流和集成模式。

自定义提示和工具

• 在中添加自定义提示作为JSON文件 mcp/prompts/ -看 提示指南
• 通过实现Tool接口创建自定义工具-请参阅 工具开发指南
• 提示可以参考使用的工具 {{tool:tool-name}} 引导式工作流的语法

发展

make build        # Build stdio MCP server
make build-all    # Build all binaries
make test         # Run tests
make help         # Show all available commands

文档

• 架构概述 -系统架构图，包括工具子系统
• 工具开发指南 -创建自定义工具的完整指南
• 提示指南 -提示定义格式和模板语法
• 完工指南 -自动完成提示参数
• ADR模板 -架构决策记录模板