ArchSmith

@archsmith/mcp-server

适用于 ArchSmith 的 archsmith-mcp MCP 服务——通过 stdio 向任何支持 MCP 的 Agent 提供 render/validate/注册表查询功能。

它是 @archsmith/cli 的同级项目，而不是对它的封装：两者都会直接调用 @archsmith/renderer 中的 render()/validate()。完整介绍请参阅根 README。

将其连接到 MCP 主机

将主机指向构建后的入口点，例如在 Claude Desktop 的 claude_desktop_config.json 中：

{
  "mcpServers": {
    "archsmith": {
      "command": "npx",
      "args": ["-y", "@archsmith/mcp-server"]
    }
  }
}

工具

get_schema、render、validate、list_registries、get_registry——与 CLI 自带命令相对应（具有相同的先验证后渲染行为，且 get_registry 使用相同的 family 筛选条件）。render 默认采用 embedFonts: false，让常规 Agent 工作流保持精简；只有在导出的 SVG 必须包含捆绑的 Arimo 字体，并且在未安装字体的情况下也能以相同方式渲染时，才显式传入 embedFonts: true。嵌入的字体会被裁剪为仅包含图表自身文本所需的字形（参见 issue #55），而非整个字体，因此其大小会随图表变化，而不是产生固定开销——仍建议按需显式启用，但不再是不论内容如何都要承担的固定成本。渲染器库和 CLI 仍默认嵌入字体。

SVG 小于 25,000 字节的渲染结果（renderStore.ts 中的 INLINE_THRESHOLD_BYTES）会像上文所示，以单个文本内容块返回。更大的渲染结果——例如大型图表，或 embedFonts: true 使原本已较大的图表超过阈值——则会以 resource_link 返回：一个小型 { type: "resource_link", uri: "archsmith://render/<id>", size, ... } 描述符，可通过对该 uri 调用 resources/read 获取。这意味着工具结果本身不会无限增长——与只能缩减固定成本、但仍随图表内容增大的字体裁剪不同，这种方式对渲染结果的大小没有上限。一个使用大小相当的负载进行测试的真实 Claude Code 会话中，resource_link 响应耗费了 3,279 个 token，而直接内嵌相同内容则耗费了 23,916 个 token——模型无需读取不需要的字节。archsmith://render/<id> 条目保存在小型内存缓存中，缓存仅保留最近 20 次渲染（MAX_ENTRIES）；读取已被驱逐或未知的 id 时，会返回标准 JSON-RPC -32002（“Resource not found”）错误，而不是工具错误。

渲染响应大小

基于当前测试样例，以 UTF-8 字节计量，包括序列化的 JSON-RPC { jsonrpc, id, result } 响应封装。“SVG”是底层渲染结果的大小，与形状无关；“MCP response”是实际返回的内容——要么是内嵌的 SVG，要么是指向该 SVG 的小型 resource_link 描述符（标记为 link）：

测试样例	字体	SVG	MCP response
minimal-valid	省略（默认）	9,014 B	9,989 B
minimal-valid	嵌入（子集）	22,313 B	23,289 B
simple-3-tier-web-app	省略（默认）	12,555 B	13,857 B
simple-3-tier-web-app	嵌入（子集）	26,130 B	27,433 B
ticket-booking	省略（默认）	23,441 B	25,639 B
ticket-booking	嵌入（子集）	38,328 B	355 B（link）

在进行子集化之前，嵌入字体无论测试样例如何，都会固定增加约 40 KB（两种完整字重）——即使是 simple-3-tier-web-app 这样常见的日常图表，也足以超过 MCP 客户端普遍的结果大小限制，而不仅是最大规模的图表（issue #55）。只嵌入各图表自身所需的文本，可将这部分开销减少约 40–55%，使其随内容变化，而不是固定增加；但嵌入字体的 ticket-booking 仍有 38,328 B，超过 25,000 B 的内联阈值，这正是上面的 resource_link 回退机制要处理的情况：无论底层 SVG 多大，工具响应都保持为一个小型、大小固定的描述符。

在 #50 修复响应形状之前，服务还会同时返回 SVG 文本和重复的 base64 图像块，并默认嵌入字体；这使 ticket-booking 的响应达到 149,897 B。现在，服务会避免重复载荷，并将字体嵌入作为显式的、与大小成比例的可移植性权衡，而不是硬编码某个特定客户端的结果大小限制。

真实主机冒烟测试：Claude Code 2.1.153 搭配 Claude Haiku 4.5，通过 stdio MCP 服务成功渲染了完整的 ticket-booking 测试样例，且未设置 embedFonts。收到的 SVG 不含内嵌的 @font-face。

get_schema 返回图表 IR JSON Schema——与下方的 archsmith://schema 资源内容相同，但它是一个工具，已连接的模型可在编写 IR 前主动调用，而不必依赖主机客户端展示资源。validate 和 render 会在各自的描述中提及该工具（以及 get_registry），并会在 IR 无效时再次于响应内容中提及。

资源

archsmith://schema，以及每个受管理注册表对应的一个 archsmith://registries/<name>——让正在编写 IR 的 Agent 可以直接读取最新的实时 schema 和注册表，而不是使用提示词中内置的过时副本。

archsmith://render/<id> 是第三种动态类型：当渲染结果过大而无法内联时，render 会注册一个此类资源（见上文）。此资源刻意不通过 resources/list 列出——根据规范，工具返回的资源链接不保证会出现在该列表中——它只能通过 render 自身返回的 resource_link 访问；在后续 20 次渲染完成后，它会从有界内存存储中淘汰，因此服务重启后不会保留，也不会在长会话中无限累积内存。

许可证

Apache-2.0