使用说明

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 映射文件。

<docs-root>/
├── 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/

安装

构建项目：

cargo build --release

运行服务器：

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

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

配置游标以使用MCP服务器

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

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

启动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
```
找到您的Cursor MCP配置文件:
- macOS/Linux： ~/.cursor/mcp.json
- 窗户： %APPDATA%\Cursor\mcp.json
- 或通过光标UI：设置→ 特性→ 模型上下文协议

添加Arch MCP服务器配置:

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

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

用于远程服务器:

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

验证连接:
- MCP服务器应出现在Cursor的可用工具中
- 您可以通过让Cursor在对话中使用架构上下文来测试它
测试MCP服务器: 要验证MCP服务器是否正常工作，您可以在Cursor聊天中输入以下提示进行测试：
```
get overview for proj-a Project.
Use arch-mcp server.
```
如果MCP服务器连接正确，您应该看到：
- 在聊天界面中调用arch-mcp工具
- 显示架构文档的工具执行结果
- 成功检索项目概述数据

自动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
}

资源

待办事项

计划的功能

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

基础设施和建设

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

使用说明

Arch MCP服务器

概述

支持的文档类型

架构图

文档类别

支持的文件格式

可用的MCP工具

1. get_resource_content

2. get_docs_list

3. get_all_adr_documents

4. get_project_overview

5. get_agreements