项目介绍
【技术文档摘要】
Archy - 架构图生成器
Archy 是一个使用 Mermaid 语法生成架构图的 MCP（模型上下文协议）服务器。它可以处理自然语言描述和 GitHub 仓库 URL 来创建各种类型的图表。
特性
- 根据文本描述生成图表
- 根据 GitHub 仓库生成图表
- 支持所有 Mermaid 图表类型：
- 流程图
- 序列图
- 类图
- 状态图
- 实体关系图
- 用户旅程图
- 甘特图
- 饼图
- 四象限图
- 需求图
- Git 图
- C4 图
安装
先决条件
- Node.js (v16 或更高版本)
- npm (v7 或更高版本)
- TypeScript (v5.8 或更高版本，包含在依赖项中)
从源代码安装
-
克隆仓库：
git clone https://github.com/phxdev1/archy.git cd archy -
安装依赖项：
npm install -
构建项目：
npm run build这会将 TypeScript 源文件编译到
build目录中的 JavaScript 文件。
自动化 MCP 安装
Archy 包含一个方便的安装脚本，可以自动配置 VS Code 和 Claude 的 MCP 服务器：
npm run install-mcp
该脚本：
- 自动检测您的操作系统正确的 MCP 设置位置
- 更新 VS Code 和 Claude 的 MCP 配置文件
- 提示输入 GitHub 令牌以分析仓库（可选）
- 使服务器可执行
无需手动编辑 JSON 配置文件，就像某种穴居动物一样！该脚本为您处理所有繁琐的配置工作，让您专注于创建美丽的图表，而不是与文件路径和权限作斗争。
配置
Archy 可以通过环境变量进行配置：
GITHUB_TOKEN：用于身份验证请求的 GitHub API 令牌（可选）OPENROUTER_API_KEY：用于 AI 功能的 OpenRouter API 密钥（可选）
OpenRouter 集成
Archy 通过 LangChain 集成了 OpenRouter，从而增强了 AI 功能的图表生成。当配置了 OpenRouter API 密钥时，以下功能可用：
- AI 增强的文本到图表生成：根据文本描述生成更复杂的图表
- 代码到图表生成：分析代码并生成适当的图表
- 差异可视化：生成显示代码版本之间差异的图表
要使用这些功能：
- 在 OpenRouter 注册账户
- 从 OpenRouter 控制台获取您的 API 密钥
- 在运行 Archy 之前设置
OPENROUTER_API_KEY环境变量
图像导出
Archy 支持将 Mermaid 图表导出为多种图像格式：
- PNG：适合网络和文档的光栅图像格式
- SVG：无损缩放的矢量图像格式
- PDF：适合打印和分享的文档格式
图像可以导出为自定义尺寸和背景颜色。
仓库演变跟踪
Archy 可以分析 Git 仓库以跟踪其随时间的变化：
- 内存中的 Git：克隆和分析仓库而不写入文件系统
- 提交历史：跨多个提交跟踪变化（默认限制为 10 个）
- 文件演变：跟踪特定文件随时间的变化
- 演变可视化：生成显示仓库演变的图表
MCP 集成
要使用 Archy 与 MCP 客户端，如果愿意的话，可以在您的 MCP 设置文件中添加它：
{
"mcpServers": {
"archy": {
"command": "node",
"args": ["/path/to/archy/build/index.js"],
"env": {
"GITHUB_TOKEN": "your-github-token"
}
}
}
}
可用工具
generate_diagram_from_text
根据文本描述生成 Mermaid 图表。
参数：
description：要生成的图表的文本描述diagramType：要生成的图表类型（例如，'flowchart'，'classDiagram'等）
示例：
{
"description": "具有登录、注册和密码重置功能的用户认证系统",
"diagramType": "flowchart"
}
generate_diagram_from_github
根据 GitHub 仓库生成 Mermaid 图表。
参数：
repoUrl：GitHub 仓库的 URLdiagramType：要生成的图表类型（例如，'classDiagram'，'sequenceDiagram'等）
示例：
{
"repoUrl": "https://github.com/username/repository",
"diagramType": "classDiagram"
}
list_supported_diagram_types
列出所有支持的图表类型及其描述。
参数： 无
AI 功能工具
当配置了 OpenRouter API 密钥时，以下工具可用：
generate_diagram_from_text_with_ai
使用 AI（通过 LangChain 和 OpenRouter）根据文本描述生成 Mermaid 图表。
参数：
description：要生成的图表的文本描述diagramType：要生成的图表类型（例如，'flowchart'，'classDiagram'等）useAdvancedModel：（可选）是否使用更高级的 AI 模型来生成复杂图表
示例：
{
"description": "具有用户服务、产品服务和订单服务通过消息队列通信的微服务架构",
"diagramType": "flowchart",
"useAdvancedModel": true
}
generate_diagram_from_code
使用 AI 根据代码生成 Mermaid 图表。
参数：
code：要分析并生成图表的代码diagramType：要生成的图表类型（例如，'classDiagram'，'flowchart'等）
示例：
{
"code": "class User { ... } class AuthService { ... }",
"diagramType": "classDiagram"
}
generate_diff_diagram
生成显示两个代码版本之间差异的 Mermaid 图表。
参数：
beforeCode：更改前的代码afterCode：更改后的代码diagramType：要生成的图表类型（例如，'classDiagram'，'flowchart'等）
示例：
{
"beforeCode": "class User { ... }",
"afterCode": "class User { ... additional methods ... }",
"diagramType": "classDiagram"
}
export_diagram_to_image
将 Mermaid 图表导出为图像格式（PNG、SVG 或 PDF）。
参数：
mermaidCode：要导出的 Mermaid 图表代码format：（可选）导出的图像格式（'png'，'svg'，'pdf'，默认为 'png'）width：（可选）图像宽度（像素，默认为 800）height：（可选）图像高度（像素，默认为 600）backgroundColor：（可选）图像背景颜色（CSS 颜色或 "transparent"，默认为 '#ffffff'）
示例：
{
"mermaidCode": "flowchart TD\n A[Start] --> B[End]",
"format": "svg",
"width": 1200,
"height": 800,
"backgroundColor": "#f0f0f0"
}
generate_repository_evolution_diagram
生成显示仓库随时间演变的图表。
参数：
repoUrl：GitHub 仓库的 URLdiagramType：要生成的图表类型（例如，'gitGraph'，'flowchart'等）filepath：（可选）要跟踪的具体文件路径commitLimit：（可选）要分析的最大提交数（默认为 10）
示例：
{
"repoUrl": "https://github.com/username/repository",
"diagramType": "gitGraph",
"filepath": "src/main.js",
"commitLimit": 5
}
示例
根据文本生成类图
generate_diagram_from_text({
"description": "为图书管理系统生成一个类图，包括 Book、Author 和 Library 类。书籍有标题和 ISBN。作者有姓名，并且可以编写多本书。图书馆包含许多书籍。",
"diagramType": "classDiagram"
})
结果：
classDiagram
class Book {
+String title
+String ISBN
+getDetails()
}
class Author {
+String name
+List books
+addBook(Book)
}
class Library {
+List books
+addBook(Book)
+findBookByISBN(String)
}
Author "1" -- "n" Book: writes
Library "1" -- "n" Book: contains
根据 GitHub 生成流程图
generate_diagram_from_github({
"repoUrl": "https://github.com/username/api-service",
"diagramType": "flowchart"
})
结果：
flowchart TD
A[Client] --> B[API Gateway]
B --> C{Authentication}
C -->|Valid| D[Route Request]
C -->|Invalid| E[Return 401]
D --> F[Service 1]
D --> G[Service 2]
D --> H[Service 3]
F --> I[Database]
G --> I
H --> I
开发
在开发模式下运行
要在开发模式下运行服务器并实现自动重新加载：
npm run dev
这使用 nodemon 和 ts-node 直接运行 TypeScript 代码，而无需单独构建步骤，并在文件更改时自动重启。
运行 TypeScript 编译器
您可以使用以下方法直接运行 TypeScript 编译器：
使用本地安装的 TypeScript
# 使用 npx 运行本地 TypeScript 安装
npx tsc
# 使用特定的 tsconfig 文件编译
npx tsc --project tsconfig.json
# 监控模式 - 当文件更改时自动重新编译
npx tsc --watch
# 编译特定文件
npx tsc src/index.ts src/server.ts
使用全局安装的 TypeScript
如果您已全局安装 TypeScript：
# 全局安装 TypeScript（如果尚未安装）
npm install -g typescript
# 运行 TypeScript 编译器
tsc
# 使用特定的 tsconfig 文件编译
tsc --project tsconfig.json
# 监控模式
tsc --watch
常见 TypeScript 编译器选项
--outDir <directory>：指定编译文件的输出目录--target <ES 版本>：指定 ECMAScript 目标版本（例如，ES2020）--module <模块系统>：指定模块系统（例如，NodeNext）--declaration：生成 .d.ts 声明文件--sourceMap：生成用于调试的源映射文件--strict：启用所有严格的类型检查选项--noEmit：检查错误而不生成输出文件--noImplicitAny：对隐含 'any' 类型的表达式引发错误
完整的编译器选项列表，请运行 npx tsc --help 或参阅 TypeScript 文档。
TypeScript 配置
Archy 使用以下配置构建于 TypeScript：
{
"compilerOptions": {
"target": "ES2020",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"esModuleInterop": true,
"strict": true,
"outDir": "build",
"declaration": true,
"sourceMap": true,
"resolveJsonModule": true
},
"include": ["src/**/*"],
"exclude": ["node_modules", "build"]
}
使用的 TypeScript 主要特性：
- ES2020 目标以支持现代 JavaScript 特性
- NodeNext 模块解析以兼容 Node.js
- 生成声明文件以提供更好的类型支持
- 生成源映射文件以便于调试
项目结构
src/：TypeScript 源文件src/index.ts：主入口点和服务器实现src/server.ts：服务器实现src/generators/：图表生成逻辑src/utils/：实用函数和辅助工具
build/：编译后的 JavaScript 输出examples/：示例使用脚本test/：测试文件