1. 为什么要在 Node.js 里把 Archy MCP 接进工作流
Archy 是一个基于 MCP（Model Context Protocol）协议的本地服务，核心能力是把自然语言描述或 GitHub 仓库地址转成 Mermaid 语法的架构图。它支持流程图、时序图、类图、状态图、ER 图、甘特图、C4 架构图等十几种图表类型，还能分析仓库演进历史生成 gitGraph。适合谁用？如果你平时写技术文档、做代码评审、维护项目架构说明，又不想手动画图，这个服务能省掉大量重复劳动。
但实际落地时，很多人卡在同一个地方：Archy 本身需要 GitHub Token 和 OpenRouter API Key 两个凭证，而你的 AI 编码工具（比如 Claude Code、Cursor、VS Code 里的 MCP 客户端）可能已经配了别的 Key。每接一个新 MCP 服务就要重新管理一套密钥，时间一长就乱了。我试过把 Archy 的 Key 和 TaoToken 的统一 Key 混在一起配，结果环境变量冲突，服务起不来。
这篇要解决的问题就是：用 TaoToken 的统一 Key 作为 Archy MCP 的模型调用入口，把 Mermaid 图表生成和 GitHub 仓库分析串成一条可复制的配置链路。你会看到完整的 config.toml 和 settings.json 骨架、Key 的填写位置、启动后的连通性验证命令，以及几个我踩过的坑。
2. TaoToken 前置准备：统一 Key 与 Archy 的关系
TaoToken 在这里扮演的角色是模型调用的统一入口。Archy 的 AI 增强功能（比如generate_diagram_from_text_with_ai、generate_diagram_from_code、generate_diff_diagram）需要调用大模型来理解复杂描述并生成更准确的 Mermaid 代码。默认它走 OpenRouter，但你可以把请求指向 TaoToken 的 API 端点，用同一个 Key 管理所有模型的调用。
先拿到你的 TaoToken Key。打开 TaoToken 控制台，在 API Keys 页面创建一个新 Key，复制出来备用。这个 Key 后面会填到 Archy 的环境变量里。
关于模型选择，Archy 的 AI 增强功能对模型能力有一定要求，建议用支持长上下文和结构化输出的模型。你可以在 模型对话 页面先测试一下模型对 Mermaid 语法的理解程度，确认能稳定输出合法图表代码后再接入 Archy。
GitHub Token 是另一个独立凭证，和 TaoToken 无关。它的作用是提高 GitHub API 的请求限额：不配 Token 时每小时只有 60 次请求，配了之后能到 5000 次。如果你只是偶尔分析一两个仓库，可以先不配；如果要批量分析或频繁调用generate_diagram_from_github，建议在 GitHub 的 token 设置页面创建一个只读权限的 personal access token。
注意：TaoToken 的 Key 和 GitHub Token 是两个独立的环境变量，不要混用。Archy 的
env字段里要分别填写。
3. 可复制配置：config.toml 与 settings.json 骨架
Archy 的安装分两步：先把源码拉下来构建，再配置 MCP 客户端。环境要求是 Node.js v16 以上、npm v7 以上。TypeScript 已经包含在依赖里，不用单独装。
先克隆仓库并构建：
git clone https://github.com/phxdev1/archy.git cd archy npm install npm run build构建完成后，入口文件在build/index.js。记住这个绝对路径，配置里要用。
接下来是 MCP 客户端的配置。不同客户端用的配置文件格式不一样，Claude Code 用settings.json，有些工具用config.toml。下面分别给出骨架。
3.1 settings.json 配置（Claude Code / VS Code 系）
{ "mcpServers": { "archy": { "command": "node", "args": ["/absolute/path/to/archy/build/index.js"], "env": { "GITHUB_TOKEN": "ghp_你的GitHubToken", "OPENROUTER_API_KEY": "你的TaoTokenKey", "OPENROUTER_BASE_URL": "https://taotoken.net/api" } } } }关键点：OPENROUTER_API_KEY填 TaoToken 的 Key，OPENROUTER_BASE_URL指向 TaoToken 的 API 地址。这样 Archy 的 AI 增强请求就会走 TaoToken，而不是默认的 OpenRouter 端点。args里的路径必须是绝对路径，相对路径在某些客户端里会解析失败。
3.2 config.toml 配置（Codex / 部分 CLI 工具）
[mcp_servers.archy] command = "node" args = ["/absolute/path/to/archy/build/index.js"] [mcp_servers.archy.env] GITHUB_TOKEN = "ghp_你的GitHubToken" OPENROUTER_API_KEY = "你的TaoTokenKey" OPENROUTER_BASE_URL = "https://taotoken.net/api"TOML 格式里字符串用双引号，数组用方括号。如果你用的是 Windows，路径要写成C:\\path\\to\\archy\\build\\index.js这种双反斜杠形式，或者用正斜杠。
3.3 环境变量对照表
| 变量名 | 是否必填 | 作用 | 填写内容 |
|---|---|---|---|
| GITHUB_TOKEN | 可选 | 提高 GitHub API 限额 | GitHub personal access token |
| OPENROUTER_API_KEY | AI 功能必填 | 模型调用凭证 | TaoToken 控制台创建的 Key |
| OPENROUTER_BASE_URL | AI 功能必填 | 模型 API 端点 | https://taotoken.net/api |
如果你只用基础功能（generate_diagram_from_text、generate_diagram_from_github、list_supported_diagram_types），可以只填 GITHUB_TOKEN，不填 TaoToken 的 Key。但一旦用到_with_ai、_from_code、_diff这几个接口，就必须配齐。
4. 验证请求：启动后检查 MCP 服务连通性
配置写完后，不要急着在 AI 工具里调用。先手动启动一次，确认服务能正常跑起来。
node /absolute/path/to/archy/build/index.js如果没有任何报错、进程保持运行，说明入口文件没问题。按 Ctrl+C 退出。
接下来验证 MCP 协议层的连通性。最直接的方式是用 MCP 客户端发一个list_supported_diagram_types请求，这个接口不需要任何外部凭证，能返回就说明服务注册成功。
如果你用 Claude Code，可以在对话里直接问：
列出 Archy 支持的所有图表类型正常情况下会返回一个包含 flowchart、sequenceDiagram、classDiagram、stateDiagram、erDiagram、journey、gantt、pie、quadrantChart、requirementDiagram、gitGraph、C4Context 等类型的列表。
再测一个需要 TaoToken 的接口，验证 Key 和 Base URL 是否生效：
用 Archy 生成一个用户登录流程的流程图，描述是：输入用户名密码 -> 验证 -> 成功进入首页，失败显示错误如果返回了合法的 Mermaid 代码块，比如：
flowchart TD A[输入用户名密码] --> B{验证} B -->|成功| C[进入首页] B -->|失败| D[显示错误]说明 TaoToken 的 Key 已经正确注入，模型调用链路通了。
再测 GitHub 仓库分析：
用 Archy 分析 https://github.com/phxdev1/archy 这个仓库，生成类图这个请求会走 GitHub API，如果没配 GITHUB_TOKEN 可能会遇到速率限制报错。配了 Token 的话，返回的类图会包含仓库里的主要类和它们的关系。
5. 本篇常见错排查
5.1 服务启动报 "Cannot find module"
九成是args里的路径写错了。检查三点：路径是不是绝对路径、build/index.js是否真的存在、有没有拼写错误。在终端里先ls /your/path/build/index.js确认文件存在，再填进配置。
5.2 AI 接口返回 401 或 "invalid api key"
TaoToken 的 Key 填到了OPENROUTER_API_KEY里，但OPENROUTER_BASE_URL没改，请求还是发到了默认端点。检查配置里有没有这一行：
"OPENROUTER_BASE_URL": "https://taotoken.net/api"另外确认 Key 没有多余空格，复制的时候容易带上换行符。
5.3 GitHub 接口报 "API rate limit exceeded"
没配 GITHUB_TOKEN，或者 Token 权限不够。GitHub 的 personal access token 需要至少repo读取权限（公开仓库用public_repo也行）。配好后重启 MCP 服务生效。
5.4 Mermaid 代码渲染失败
Archy 返回的是 Mermaid 语法文本，不是图片。你需要在支持 Mermaid 的环境里渲染，比如 VS Code 装 Mermaid 插件、Typora、或者 Mermaid Live Editor。如果代码里有中文标签，确保渲染环境支持 UTF-8。
5.5 导出图片时报 "puppeteer not found"
export_diagram_to_image依赖 Puppeteer 做渲染。如果npm install时跳过了可选依赖，需要单独装：
npm install puppeteer装完后重新npm run build。
5.6 配置改了但客户端没生效
MCP 客户端通常在启动时读取配置，改完settings.json或config.toml后要重启客户端。有些工具支持热重载，但保险起见还是重启一次。
6. 把 Archy 接进长期编码工作流
单次生成图表只是起点。如果你打算把 Archy 作为日常编码和文档维护的固定工具，建议把 TaoToken 的 Key 统一管理起来，避免每个 MCP 服务都配一套凭证。TaoToken 的 Coding Plan 适合这种长期、多服务共用的场景，一个 Key 覆盖模型调用，Archy 只是其中一个消费方。
接入文档在 TaoToken 文档 里有更详细的端点说明和参数示例。如果你在配置过程中遇到 Key 相关的问题，先去 API Keys 页面 确认 Key 状态和额度。
最后说一个实际经验：Archy 的generate_repository_evolution_diagram接口默认只分析 10 个提交，分析大仓库时记得把commitLimit调大，但别一次拉太多，GitHub API 的响应时间会明显变长。我一般设成 20 到 30 之间，够看演进趋势又不至于等太久。
