# ArchiSymphonyMCP — AI バディ運用ガイド このファイルは **あなた（社員）の AI バディ**（Claude 等）に渡すための運用ガイドです。 AI バディはこの内容を読むことで、あなたの PC 上の **Autodesk Revit を MCP 経由で操作**できるようになります。 > 配布元: https://mcp.archisymphony.com （PLS 社員限定 / ArchiSymphonyMCP） > 対象: Revit 2025 / 2026 / 2027 ＋ ArchiSymphonyMCP アドイン導入済みの Windows PC --- ## 1. これは何か **ArchiSymphonyMCP** は、Revit の全 API を **Model Context Protocol (MCP)** 経由で AI から制御できるアドインです。 建具表生成・モデル検査・要素の一括編集・図面操作などを、AI バディが自然言語の指示から実行できます。 - ローカルの **named pipe** `\\.\pipe\ArchiSymphonyMCP`（例: `ArchiSymphonyMCP2027`）でリッスン - **775+ メソッド**（NonicaTab 互換 51 + vendor 1,303 + PLS native 27 / AI-actionable 1,494 中 89% を named 提供、残りも Universal API Bridge で到達可能） - 通信は **1 行 JSON**: リクエスト `{"method":"...","params":{...}}` → レスポンス 1 行 JSON ## 2. 前提条件（AI バディが最初に確認すること） 1. Revit (2025/2026/2027) が **起動**しており、**モデルが 1 つ開かれている**こと 2. Revit「アドイン」タブに **ArchiSymphonyMCP** が表示されている（未導入なら配布ページから MSI を入れる） 3. named pipe の存在確認（PowerShell）: ```powershell [System.IO.Directory]::GetFiles("\\.\pipe\") | Where-Object { $_ -match "ArchiSymphonyMCP" } # => \\.\pipe\ArchiSymphonyMCP2027 ``` ## 3. 接続方法（2 通り） ### A. MCP サーバー経由（推奨 / Claude Code・Claude Desktop） ArchiSymphonyMCP 同梱の Python MCP サーバー（`mcp-server/server.py`）を MCP クライアントに登録すると、 AI バディが **全 Revit API を read/write** で直接操作できます。 ```json { "mcpServers": { "archisymphony-revit": { "command": "python", "args": ["mcp-server/server.py", "--revit", "2027"] } } } ``` **公開ツール（これだけで全 API に到達。入力・編集も可能）:** | tool | 用途 | |---|---| | `revit_list_methods` | 全 1,330 メソッドを発見（**まず最初に**） | | `revit_call` | 任意の named メソッドを実行（作成/変更/削除/読取・トランザクション） | | `revit_api_invoke` | Universal Bridge: 任意の RevitAPI メソッドを reflection 実行（transacted） | | `revit_api_get_property` / `revit_api_set_property` | 任意プロパティの読取 / 書込 | | `revit_api_list_members` | 任意の Revit API 型を introspection | **全 API 対応の仕組み（重要）:** named メソッド（1,330）に無い API も、Universal API Bridge （`revit_api_invoke` / `revit_api_set_property`）が reflection で RevitAPI/RevitAPIUI の **全 public メソッド・プロパティ**に到達します。作成・変更・削除は Revit トランザクションで安全に実行 されるため、「未対応で詰む」ことはありません。 ### B. named pipe に直接書き込む（任意言語） pipe に 1 行の JSON を書き、1 行の JSON 応答を読むだけです。PowerShell 例: ```powershell $pipe = New-Object System.IO.Pipes.NamedPipeClientStream(".", "ArchiSymphonyMCP2027", "InOut") $pipe.Connect(15000) $w = New-Object System.IO.StreamWriter($pipe); $w.AutoFlush = $true $r = New-Object System.IO.StreamReader($pipe) $w.WriteLine('{"method":"getProjectInfo","params":{}}') $r.ReadLine() # => 1 行 JSON 応答 $pipe.Dispose() ``` ### C. 外部 PC（クライアント PC）から LAN 経由で接続（v1.1.0〜 / 実機検証済み） **Revit を起動している PC 以外の、同じ社内 LAN 上のあなたの PC（Mac など）からも接続できます。** アドインが TCP ブリッジ（既定 `0.0.0.0:5757`）を起動し、ローカル named pipe へ橋渡しします。 **実機 Revit 2027（`192.168.1.40`）で疎通・全 455 メソッド到達まで確認済み。** > **専用キットを配布しています** → `https://mcp.archisymphony.com` の「外部PC接続キット」（`archisymphony-mcp-lan-client.zip`）。 > このキットがクライアント側に必要な MCP サーバー（`lan_server.py`）一式です。 > **クライアント側に Revit／MSI は不要**（Python だけ）。秘密情報はキットに含まれません。 **プロトコル（重要・確定仕様）**: `tcp :5757` は **HTTP ではなく改行区切り JSON**。 1 接続 = 1 認証セッションで、`Authorization: Bearer` ヘッダ方式は**不可**（`token`/`auth` フィールドのみ受理）。 キット同梱の `revit_lan_client.py` がこのハンドシェイク・再接続を担保するので、AI バディはこれを意識せず `revit_*` ツールを使えます。 #### Revit PC 側（管理者・1 回のみ） - **LAN-only**: 接続元はプライベート IP（`10.x` / `172.16–31.x` / `192.168.x`）と loopback のみ許可。社外 IP は拒否。 - **Windows Firewall**: TCP 5757 の受信を「ローカルサブネットのみ」許可: ```powershell New-NetFirewallRule -DisplayName "ArchiSymphonyMCP LAN" -Direction Inbound ` -Action Allow -Protocol TCP -LocalPort 5757 -RemoteAddress LocalSubnet ``` #### トークンの取得方法（必須） トークンは Revit PC で初回起動時に自動生成される 64 桁 hex です。**Revit PC の管理者**が取得し、安全な経路でクライアント PC へ渡します。 ```powershell # Revit PC（Windows）で実行 → 64 桁 hex が表示される Get-Content "$env:ProgramData\ArchiSymphonyMCP\bridge.token" ``` #### クライアント PC 側（Windows・自動 / 推奨） 社内の外部クライアントは Windows が大半です。**Revit / MSI は不要**（Python だけ）。 キットを展開し、通常の PowerShell（管理者不要）で 1 行: ```powershell # Python 3 未導入なら先に https://www.python.org/downloads/ で導入（"Add to PATH" にチェック） powershell -ExecutionPolicy Bypass -File scripts\install-lan-windows.ps1 -RevitHost 192.168.1.40 # → 上で取得した 64 桁トークンの貼り付けを 1 回求められる # → venv 作成 / mcp 導入 / トークンをユーザー専用ファイルに保存 / 疎通確認 / claude mcp 登録 ``` トークンは `%APPDATA%\ArchiSymphonyMCP\bridge.token`（**ユーザー本人のみ ACL**）に保存され、 MCP 設定にはその**パス（`PLS_REVIT_TOKEN_FILE`）だけ**が入ります（**秘密そのものは設定に書きません**）。 完了後、Claude Code / Desktop を**再起動**すると `Revit` ツール（`mcp__Revit__*`）が出現します。 #### クライアント PC 側（macOS・自動） ```bash unzip archisymphony-mcp-lan-client.zip && cd archisymphony-mcp-lan-client scripts/install-lan-mac.sh 192.168.1.40 # 末尾は Revit PC の LAN IP # → 上で取得した 64 桁トークンの貼り付けを 1 回求められる # → venv 作成 / mcp 導入 / トークンをキーチェーン登録 / 疎通確認 / claude mcp 登録 ``` トークンはキーチェーン（service `ArchiSymphonyMCP-bridge-token`）に保存され、**設定ファイルや MCP 設定には書きません**。 #### 手動登録（Claude Desktop など / OS 共通） ```bash python3 -m venv .venv && .venv/bin/python -m pip install "mcp>=1.0.0" # Win: .venv\Scripts\python.exe ``` トークンを与える（いずれか）: 環境変数 `PLS_REVIT_TOKEN=` / `PLS_REVIT_TOKEN_FILE=`、 または macOS キーチェーン `security add-generic-password -s ArchiSymphonyMCP-bridge-token -a "$USER" -w -U`。 MCP クライアントへの登録は同梱 `.mcp.json.example` をコピーして絶対パス・IP を埋める: ```json { "mcpServers": { "Revit": { "command": "/ABS/PATH/archisymphony-mcp-lan-client/.venv/bin/python", "args": ["/ABS/PATH/archisymphony-mcp-lan-client/mcp-server/lan_server.py"], "env": { "PLS_REVIT_HOST": "192.168.1.40", "PLS_REVIT_PORT": "5757" } } } } ``` > 設定はすべて環境変数で解決（会社・テナント固有値のハードコードなし）: > `PLS_REVIT_HOST`（既定 `192.168.1.40`）/ `PLS_REVIT_PORT`（`5757`）/ トークンは > `PLS_REVIT_TOKEN` > `PLS_REVIT_TOKEN_FILE` > キーチェーン service `ArchiSymphonyMCP-bridge-token` の順。 #### 社外（オフサイト）から使う場合 社外ネットワークからは TCP 5757 に直接到達できません（ブリッジは LAN プライベート IP のみ許可）。 社内 VPN（WireGuard）で社内 LAN に参加した上で、上記と同じ手順で接続してください。 ## 4. まず叩くべきメソッド | method | params | 用途 | |---|---|---| | `listMethods` | `{}` | **最初にこれ**。利用可能な全 455 メソッド / 47 カテゴリを列挙 | | `getDocumentInfo` | `{}` | 開いているモデルの概要・リンク・ワークセット | | `getProjectInfo` | `{}` | プロジェクト情報（組織名・番号・住所） | | `getLevels` | `{}` | 全レベルと標高 | | `getElements` | `{"category":"Walls"}` | カテゴリ別の要素一覧（id / 名前 / 型 / レベル） | | `getElementProperties` | `{"elementId":N}` | 要素の全パラメータ + バウンディングボックス | カテゴリ例: `Walls` / `Doors` / `Windows` / `Floors` / `Rooms` / `Sheets` / `Schedules` / `Grids` / `MEP` / `Structural` ほか。 ## 5. AI バディへの運用ルール（重要） - **メソッド名は必ず `listMethods` で確認**してから使う（推測しない。旧 alias は廃止）。 - **破壊的操作**（`deleteElement(s)` / `moveElements` / 大量編集）は、実行前に必ず**対象と件数をユーザーに提示して確認**を取る。 - レスポンスは `{"success":true/false, ...}`。`success:false` の場合は `error` / `errorCode`（例 `METHOD_NOT_FOUND`）を読んで原因を説明する。 - 文字化けする場合は呼び出し側を UTF-8 に: `[Console]::OutputEncoding=[Text.Encoding]::UTF8`。 - モデル未読込時は一部メソッドが応答しない → 先に「モデルを開いてください」と案内する。 ## 6. 典型ワークフロー例（AI バディの思考順序） 1. `listMethods` で能力を把握 2. `getDocumentInfo` / `getLevels` で現況把握 3. 目的のカテゴリを `getElements` で取得 4. 個別に `getElementProperties` で詳細確認 5. 編集系メソッドは **ユーザー確認後**に実行 → 結果を `success` で検証 --- **問い合わせ**: PLS AI Family / クロード（CTO） **最新版・更新**: Revit 起動時に自動でバージョン確認され、新版があれば https://mcp.archisymphony.com へ案内されます。