Arch MCP Server

Arch MCP服务器

MCP服务器，为代码代理提供体系结构上下文-ERD图、代码策略、API文档、服务关系和最佳实践。

概述

这是一个使用Rust构建的模型上下文协议（MCP）服务器，作为AI编码代理的架构上下文提供者。它提供了工具和资源来帮助代理理解系统架构、关系和编码标准。

支持的文档类型

服务器支持扫描并提供对各种类型的架构和技术文档的访问：

架构图

• C4图表：上下文（C1）、容器（C2）、组件（C3）和服务（C4）图
• ERD图：数据库模式的实体关系图
• ADR文件：架构决策记录
• OpenAPI规范：YAML格式的REST API文档

文档类别

• 协议：API合同、服务协议和技术规范
• 建筑：C4图、ERD图和ADR文件
• 开放应用程序接口：REST API规范和端点文档
• 后端：PHP、Go和其他后端文档
• 前端：JavaScript、TypeScript和前端文档

支持的文件格式

• 标记语言: .md 文件
• MDX: .mdx 文件（带JSX组件的Markdown）
• 文本: .txt 文件
• YAML: .yaml 文件（OpenAPI规范）

可用的MCP工具

该服务器为架构文档分析提供了5个强大的工具：

1. get_resource_content

📄 获取文档资源内容

• 目的：使用从特定文档文件检索内容 docs:// 路径
• 参数:

- path （string）：资源路径格式 docs://path/to/file

• 用例：阅读特定的体系结构文档、API规范、指南和技术文档
• 例子:

- docs://architecture/prj-1/c1.mdx （C4图） - docs://openapi/mpa/activation/v2/public/get-customer-activation-info.yaml （OpenAPI规范）

2. get_docs_list

📋 使用筛选器获取文档列表

• 目的：列出具有高级筛选和分页功能的文档资源
• 参数:

- area （可选）：按区域过滤（例如，“架构”、“后端”、“前端”、“openapi”）-支持OR | 分隔符 - lang （可选）：按语言过滤（例如，“php”、“go”、“js”、“ts”）-支持OR | 分隔符 - category （可选）：按类别筛选（例如，“c1”、“c2”、“c3”、“c4”、“erd”、“协议”、“openapi”）-支持OR | 分隔符 - page （可选）：分页页码（默认值：1） - limit （可选）：每页项目数（默认值：50，最大值：200）

• 用例：文档发现、架构分析、技术文档研究
• 过滤器示例:

- area=architecture&category=c4 -查找所有C4图表 - area=openapi&category=activation -查找激活服务的所有OpenAPI规范 - area=backend&lang=php -查找所有PHP后端文档 - category=agreements -查找所有协议文件

3. get_all_adr_documents

📋 获取所有ADR文件

• 目的：检索按ADR编号排序的所有架构决策记录（ADR）文档
• 参数：无
• 用例：发现和分析整个项目的架构决策
• 退货：包含元数据（包括URI、描述和文件路径）的ADR文档列表

4. get_project_overview

📊 获取项目概述

• 目的：提供项目的全面概述，包括按类别分组的所有文档类型
• 参数:

- project （必填）：项目名称

• 用例：项目分析、文件统计、了解项目结构
• 退货：结构化JSON，包含项目统计信息和按类型、区域和语言组织的所有ResourceInfo对象
• 特性:

- 文档总数和大小 - 按类型分组的文件（C1、C2、C3、C4、ERD、ADR、协议） - 按领域（架构、后端、前端）分组的文档 - 按语言（PHP、Go、JS、TS等）分组的文档 - 包含完整元数据的所有文档的完整列表

5. get_agreements

📋 按语言获取协议

• 目的：检索按编程语言筛选的所有协议文档
• 参数:

- lang （必填）：编程语言（例如，“php”、“go”、“js”、“ts”、“py”、“rust”）

• 用例：了解API合同、服务协议和特定技术堆栈的技术规范
• 退货：包含指定语言元数据的协议文件列表
• 特性:

- 按编程语言筛选 - API合同和服务协议 - 技术规格 - 每份协议的完整元数据

文件扫描

服务器扫描并索引通过以下方式提供的文档存储库根目录中的文档 --docs-root，使用a arch-mcp.toml 映射文件。

/
├── arch-mcp.toml
└── ... (any layout; paths are configured inside arch-mcp.toml)

资源URI模式

文档可以通过结构化URI访问：

• C4图表: docs://architecture/{project}/{diagram}.mdx
• ERD图: docs://architecture/erd/{project}/{diagram}.mdx
• ADR文件: docs://architecture/{project}/adr/{adr-number}-{title}.mdx
• 协议: docs://agreements/{area}/{lang}/{category}/{file}

快速开始

先决条件

• Rust 1.70+（2024年版）
• 货物

有关详细的安装说明，请参阅 install.md.

快速安装：

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

或者遵循官方指南：https://rust-lang.org/tools/install/

安装

1. 构建项目：

cargo build --release

1. 运行服务器：

cargo run --release -- --docs-root ./example_docs/docs/content

服务器将于启动 127.0.0.1:8010 默认情况下。

配置游标以使用MCP服务器

重要：此MCP服务器使用HTTP传输，必须作为单独的进程运行。不支持stdio传输，因为服务器将日志输出到stdout，这会干扰JSON协议。

要将此MCP服务器与Cursor一起使用，请执行以下操作：

1. 启动MCP服务器 （配置Cursor之前必须运行）：

选项A：使用货物:

   cargo run --release -- --docs-root ./example_docs/docs/content

选项B：使用Docker Compose:

   docker compose up

选项C：使用内置二进制文件:

   ./target/release/arch-mcp-server --docs-root ./example_docs/docs/content

1. 找到您的Cursor MCP配置文件:

- macOS/Linux： ~/.cursor/mcp.json - 窗户： %APPDATA%\Cursor\mcp.json - 或通过光标UI：设置→ 特性→ 模型上下文协议

1. 添加Arch MCP服务器配置:

为了地方发展 （在本地主机上运行的服务器）：

   {
     "mcpServers": {
       "arch-mcp": {
         "url": "http://127.0.0.1:8010/mcp",
         "headers": {}
       }
     }
   }

用于远程服务器:

   {
     "mcpServers": {
       "arch-mcp": {
         "url": "https://your-server.com/mcp",
         "headers": {}
       }
     }
   }

1. 验证连接:

- MCP服务器应出现在Cursor的可用工具中 - 您可以通过让Cursor在对话中使用架构上下文来测试它

1. 测试MCP服务器:

要验证MCP服务器是否正常工作，您可以在Cursor聊天中输入以下提示进行测试：

   get overview for proj-a Project.
   Use arch-mcp server.

如果MCP服务器连接正确，您应该看到：

- 在聊天界面中调用arch-mcp工具 - 显示架构文档的工具执行结果 - 成功检索项目概述数据

1. 自动MCP集成（可选）:

对于没有明确“use arch MCP”命令的自动MCP工具使用，您可以将以下部分添加到您的 AGENTS.md 文件：

   ## MCP (Model Context Protocol)

   ### arch-mcp Integration
   Always use arch-mcp when you need to analyze project documentation, understand architectural decisions, or work with ADR (Architecture Decision Records). This tool provides comprehensive project analysis and documentation insights.

   **Key Features:**
   - **Project Overview**: Complete project statistics and documentation coverage
   - **ADR Analysis**: Architecture Decision Records for understanding design choices
   - **API Documentation**: Service agreements and API contracts
   - **C4 Diagrams**: Context, Container, Component, and Code level diagrams
   - **ERD Analysis**: Entity Relationship Diagrams for database design
   - **Technical Specifications**: Detailed specs by programming language and area
   - **Agreements**: Service contracts and technical agreements
   - **Architecture Documentation**: Comprehensive architectural documentation

   **When to Use ArchMCP:**
   - Understanding project architecture and design decisions
   - Analyzing existing documentation and specifications
   - Finding specific technical specifications and agreements
   - Reviewing architectural decisions and ADR history
   - Getting project statistics and documentation coverage
   - Working with database design and ERD diagrams
   - Understanding service agreements and API contracts
   - Analyzing C4 architecture diagrams

这将使AI代理能够在适当的时候自动使用arch-mcp工具，而不需要在提示中明确的“use arch-mcp”命令。

备注：对于远程服务器访问，需要VPN连接。

用法

运行服务器

cargo run --release -- --docs-root ./example_docs/docs/content

MCP检查员

要检查和测试MCP服务器，请使用官方MCP检查员：

npx @modelcontextprotocol/inspector

这将打开一个web界面，您可以在其中：

• 连接到您的MCP服务器
• 测试可用的工具和资源
• 检查服务器功能
• 调试MCP协议交互

示例用法

获取项目概述

{
  "tool": "get_project_overview",
  "parameters": {
    "project": "proj-a"
  }
}

答复：

{
  "project": "proj-a",
  "total_documents": 25,
  "total_size": 1024000,
  "documents_by_type": {
    "c1": [ResourceInfo...],
    "c2": [ResourceInfo...],
    "c4": [ResourceInfo...],
    "erd": [ResourceInfo...],
    "ADR-001": [ResourceInfo...]
  },
  "documents_by_area": {
    "architecture": [ResourceInfo...],
    "backend": [ResourceInfo...]
  },
  "documents_by_language": {
    "php": [ResourceInfo...],
    "none": [ResourceInfo...]
  },
  "all_documents": [ResourceInfo...]
}

按语言获取协议

{
  "tool": "get_agreements",
  "parameters": {
    "lang": "php"
  }
}

答复：

{
  "lang": "php",
  "agreements": [
    {
      "uri": "docs://agreements/backend/php/api/user-service.md",
      "file_path": "content/docs/backend/php/api/user-service.md",
      "area": "backend",
      "lang": "php",
      "category": ["agreements", "api"],
      "project": "",
      "mime_type": "text/markdown",
      "size": 2048,
      "description": "Agreement document: agreements, api - backend (php)"
    }
  ],
  "total_agreements": 1
}

资源

• 模型上下文协议规范
• rmcp文件
• MCP检查员

待办事项

计划的功能

• 标准运输：为MCP协议添加stdio传输支持（目前仅支持HTTP传输）
• 热重新加载：实现热重新加载功能，以便在文件更改时自动重新扫描文档，而无需重新启动服务器
• 扩展文档类型：支持更多文档类型和文件扩展名（例如。， .json, .xml, .csv, .rst, .asciidoc)
• 文档类型检测：基于内容分析自动检测文档类型
• 缓存：为频繁访问的文档实施缓存机制，以提高性能
• 搜索功能：在所有文档中添加全文搜索功能
• 配置验证：增强验证 arch-mcp.toml 配置文件
• 增量扫描：仅重新扫描更改的文件，而不是完整目录扫描
• 文档元数据提取：从文档（frontmatter、标签等）中提取元数据并建立索引

基础设施和建设

• CI/CD管道：为自动化测试和构建建立持续集成管道
• 发布构建：自动创建二进制文件