ArchSmith

@archsmith/mcp-server

ArchSmith 用の archsmith-mcp MCP サーバーです。stdio 経由で、MCP 対応エージェントから 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 の各コマンドに対応しています（validate の後に render する動作や、get_registry の family フィルターも同じです）。通常のエージェントのワークフローを簡潔に保てるよう、render の embedFonts はデフォルトで false です。エクスポートした 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 セッションでは、同じ内容を直接インラインで返した場合に 23,916 トークンを消費したのに対し、resource_link の応答は 3,279 トークンでした。モデルは必要のないバイト列を読み取る必要がありません。archsmith://render/<id> のエントリーは、直近 20 件のレンダリングを保持する小さなインメモリーキャッシュ（MAX_ENTRIES）に保存されます。期限切れまたは不明な ID を読み取ると、ツールエラーではなく、標準の JSON-RPC -32002（「Resource not found」）エラーが返されます。

レスポンスサイズの測定

現在のフィクスチャを基準に、シリアライズされた JSON-RPC { jsonrpc, id, result } レスポンスエンベロープを含む UTF-8 バイト数で測定しています。「SVG」は形状にかかわらず元のレンダリングサイズを示します。「MCP response」は実際に返される内容を示し、SVG をインライン化したもの、または SVG を指す小さな resource_link ディスクリプター（link と表記）のいずれかです。

フィクスチャ	フォント	SVG	MCP レスポンス
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 の固定サイズが必要でした（完全なウェイトのフォント 2 種分）。これは、最大規模の図だけでなく、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 で、embedFonts を省略した状態で stdio MCP サーバー経由の ticket-booking フィクスチャ全体を正常にレンダリングできました。埋め込み @font-face のない SVG が返されました。

get_schema は図の IR JSON Schema を返します。これは下記の archsmith://schema リソースと同じドキュメントですが、ホストクライアントがリソースを提示するかどうかに依存せず、接続されたモデルが IR の作成前に自発的に呼び出せるツールとして提供されます。validate と render は、それぞれの説明文でこのスキーマ（および get_registry）に言及し、さらに IR が無効と判明した場合は、レスポンスの内容でも再度言及します。

リソース

archsmith://schema と、管理対象レジストリごとに 1 つずつ用意される archsmith://registries/<name> により、IR を作成するエージェントは、プロンプトに埋め込まれた古いコピーを使うのではなく、最新のスキーマやレジストリを直接読み取れます。

archsmith://render/<id> は 3 つ目の動的な種類です。レンダリング結果が大きすぎてインライン化できない場合に、render がこれを登録します（上記参照）。これは意図的に resources/list には表示されません。仕様によると、ツールが返すリソースリンクがそこに表示されるとは限らないためです。このリソースには、render 自身が返す resource_link 経由でのみアクセスできます。また、レンダリングがさらに 20 回行われると、上限付きのメモリ内ストアから削除されるため、サーバーの再起動後も残ることはなく、長時間のセッションでメモリが際限なく増えることもありません。

ライセンス

Apache-2.0