Archy MCP 服务说明文档
1. 服务概述
一句话简介：基于Mermaid语法的架构图生成MCP服务器，支持自然语言描述和GitHub仓库分析生成多种类型图表。
- 服务名称：Archy - Architectural Diagram Builder
- 版本号：Latest
- 开发者/提供方：phxdev1
- 协议类型：MCP (Model Context Protocol)
- 官方链接：https://glama.ai/mcp/servers/phxdev1/archy-mcp
2. 核心功能
Archy MCP 提供以下主要功能：
- 文本描述生成图表：从自然语言描述生成Mermaid架构图
- GitHub仓库分析：分析GitHub仓库并生成架构图
- 多种图表类型支持：
- 流程图
- 时序图
- 类图
- 状态图
- 实体关系图
- 用户旅程图
- 甘特图
- 饼图
- 象限图
- 需求图
- Git图
- C4图
- AI增强生成：通过OpenRouter集成实现AI驱动的图表生成
- 图片导出：支持导出为PNG、SVG、PDF格式
- 仓库演进追踪：分析Git仓库的演进历史并可视化
3. 使用场景
Archy MCP 适用于以下场景：
- 系统架构设计：快速生成系统架构图和组件关系图
- 代码文档：从代码仓库自动生成类图和时序图
- 流程可视化：将业务流程转换为可视化流程图
- 项目管理：生成甘特图进行项目进度管理
- 数据库设计：生成实体关系图展示数据库结构
- API文档：生成时序图展示API调用流程
- 代码演进分析：追踪和可视化代码仓库的演进历史
4. 接入方式
4.1 服务端点
Archy 作为MCP服务器运行，通过stdio方式提供服务：
- 传输方式：stdio
- 协议版本：MCP 1.0+
- 服务类型：本地MCP服务器
4.2 认证与权限
Archy 支持以下认证配置：
- GITHUB_TOKEN：GitHub API令牌，用于仓库分析（可选）
- OPENROUTER_API_KEY：OpenRouter API密钥，用于AI增强功能（可选）
4.3 数据格式
- 输入格式：自然语言描述或GitHub URL
- 输出格式：Mermaid语法代码或图片文件
- 支持格式：PNG、SVG、PDF
4.4 服务器配置
在MCP客户端配置中添加服务：
{ "mcpServers": { "archy": { "command": "node", "args": ["/path/to/archy/build/index.js"], "env": { "GITHUB_TOKEN": "your-github-token", "OPENROUTER_API_KEY": "your-openrouter-api-key" } } } }5. 接口定义
Archy MCP 提供以下核心工具：
5.1 基础工具
| 工具名称 | 描述 | 参数 |
|---|---|---|
generate_diagram_from_text | 从文本描述生成Mermaid图表 | description: 文本描述 diagramType: 图表类型 |
generate_diagram_from_github | 从GitHub仓库生成Mermaid图表 | repoUrl: 仓库URL diagramType: 图表类型 |
list_supported_diagram_types | 列出所有支持的图表类型 | 无 |
5.2 AI增强工具（需要OpenRouter API密钥）
| 工具名称 | 描述 | 参数 |
|---|---|---|
generate_diagram_from_text_with_ai | 使用AI从文本生成图表 | description: 文本描述 diagramType: 图表类型 useAdvancedModel: 是否使用高级模型 |
generate_diagram_from_code | 从代码生成图表 | code: 代码内容 diagramType: 图表类型 |
generate_diff_diagram | 生成代码差异可视化图表 | oldCode: 旧代码 newCode: 新代码 |
6. 快速开始
6.1 环境要求
- Node.js：v16或更高版本
- npm：v7或更高版本
- TypeScript：v5.8或更高版本（包含在依赖中）
- 操作系统：Windows、macOS、Linux
6.2 安装步骤
步骤1：克隆仓库
git clone https://github.com/phxdev1/archy.git cd archy步骤2：安装依赖
npm install步骤3：构建项目
npm run build步骤4：自动配置MCP（推荐）
npm run install-mcp该脚本会自动：
- 检测操作系统的MCP配置位置
- 更新VS Code和Claude的MCP配置文件
- 提示输入GitHub令牌（可选）
- 设置服务器可执行权限
6.3 使用示例
示例1：从文本描述生成流程图
{ "description": "用户认证系统，包含登录、注册和密码重置功能", "diagramType": "flowchart" }示例2：从GitHub仓库生成类图
{ "repoUrl": "https://github.com/username/repository", "diagramType": "classDiagram" }7. 注意事项
使用注意事项
- GitHub令牌：分析私有仓库或提高API限制时需要配置GITHUB_TOKEN
- OpenRouter集成：AI增强功能需要配置OPENROUTER_API_KEY
- 图片导出：支持自定义尺寸和背景颜色
- 仓库演进追踪：默认限制为10个提交记录
- 内存Git：仓库克隆和分析在内存中进行，不写入文件系统
OpenRouter集成说明
- 在OpenRouter官网注册账号并获取API密钥
- 配置环境变量
OPENROUTER_API_KEY - AI增强功能包括：
- 更复杂的文本到图表生成
- 代码到图表生成
- 差异可视化
最佳实践
- 使用自动安装脚本
npm run install-mcp简化配置 - 为复杂图表使用AI增强功能
- 选择合适的图表类型以获得最佳效果
- 使用SVG格式获得可缩放的矢量图