# ArchiSymphonyMCP for Navisworks — AI バディ運用ガイド

このファイルは **あなた（社員）の AI バディ**（Claude 等）に渡すための運用ガイドです。
AI バディはこの内容を読むことで、あなたの PC 上の **Autodesk Navisworks Manage を MCP 経由で操作**できます。

> 配布元: https://mcp.archisymphony.com （PLS 社員限定 / ArchiSymphonyMCP for Navisworks）
> 対象: Navisworks Manage 2025 / 2026 / 2027 ＋ PLS Navisworks Bridge 導入済みの Windows PC

---

## 1. これは何か

**PLS NavisworksMCPBridge** は、Navisworks の **全 API（Autodesk.Navisworks.Api.*）** を
**Model Context Protocol (MCP)** 経由で AI から制御できるアドインです。
モデルツリー走査・プロパティ抽出・選択操作・干渉/数量・IFC プロパティ参照などを、AI が自然言語の指示から実行できます。

- **Universal Bridge（リフレクション）** で任意の .NET 型・メソッド・プロパティへ実行時到達 = **API 100% 網羅**（読取＋書込＋introspection）
- **オブジェクトレジストリ(oid)連鎖**で API グラフを辿る（`Application → Document → Models → ModelItem → PropertyCategories → Properties → Value`）
- Navisworks 起動時に **自動でリスナ起動**（手動コマンド不要 / `EventWatcherPlugin`）

## 2. 前提条件（AI バディが最初に確認すること）

1. **Navisworks Manage**（2025/2026/2027）が**起動**しており、モデルが開かれていること
2. 「アドイン」に PLS Bridge が読み込まれている（未導入なら配布ページから MSI を導入）
3. ブリッジが **127.0.0.1:7660**（2025）/ **7661**（2026）/ **7662**（2027）で待受していること:
   ```powershell
   (Test-NetConnection 127.0.0.1 -Port 7660).TcpTestSucceeded   # => True なら接続可
   ```
   ※ `7660 + (year-2025)`。Revit(765x) / Civil 3D(764x) と非衝突（PORTS 設計）。

## 3. 接続方法

### A. MCP サーバー経由（推奨 / Claude Code・Claude Desktop）

MSI 同梱の MCP シム（`%ProgramData%\PLS\NavisworksMCPBridge\mcp\index.mjs`）を MCP クライアントに登録します:

```json
{
  "mcpServers": {
    "archisymphony-navisworks": {
      "command": "node",
      "args": ["C:/ProgramData/PLS/NavisworksMCPBridge/mcp/index.mjs"],
      "env": { "PLS_NAVIS_BRIDGE_PORT": "7660" }
    }
  }
}
```

**公開ツール（これだけで全 API に到達）:**

| tool | 用途 |
|---|---|
| `navisworks_ping` | ブリッジ疎通（bridge_version 取得） |
| `navisworks_invoke` | 任意 API をリフレクションでバルク実行（`requests` 配列） |

### B. 直接 framed TCP（上級 / 自作クライアント）

`127.0.0.1:7660` へ **4 バイト LE 長 + UTF-8 本文** のフレームで、要求配列 JSON を送信します。

## 4. リクエスト形式（`requests` 配列 / バルク 1 トランザクション）

各要素:
```jsonc
{ "op": "...", "target": "Application", "oid": 3, "member": "...", "args": [], "id": "任意" }
```
- `op`: `static_get` / `static_invoke` / `get` / `set` / `invoke` / `list_members`
- `target`: 静的の起点（`"Application"` = `Autodesk.Navisworks.Api.Application`）
- `oid`: 直前までの応答で得たオブジェクト参照（**連鎖の要**）
- 戻り値がオブジェクトなら `{ "oid": N, "type": "...", "name": "..." }` が返り、後続要求で `oid:N` を指定して掘り下げる

## 5. 典型レシピ

### 5.1 開いているモデルの確認
```json
[{"op":"static_get","target":"Application","member":"ActiveDocument","id":"doc"}]
```
→ `{"oid":1,"type":"...Document","toString":"Document (xxx.ifc)"}`

### 5.2 要素ツリーのルート→子
```json
[
 {"op":"static_get","target":"Application","member":"ActiveDocument"},
 {"op":"get","oid":1,"member":"Models"},
 {"op":"get","oid":2,"member":"RootItem","id":"root"},
 {"op":"get","oid":3,"member":"DisplayName"},
 {"op":"get","oid":3,"member":"Children","id":"children"}
]
```

### 5.3 全子孫の列挙（フラット）
```json
[{"op":"static_get","target":"Application","member":"ActiveDocument"},
 {"op":"get","oid":1,"member":"Models"},
 {"op":"get","oid":2,"member":"RootItem"},
 {"op":"get","oid":3,"member":"Descendants","id":"all"}]
```

### 5.4 要素の詳細プロパティ（カテゴリ→プロパティ→値）
```json
[... RootItem を oid3 まで取得 ...,
 {"op":"get","oid":3,"member":"PropertyCategories","id":"cats"},
 {"op":"get","oid":4,"member":"DisplayName"},
 {"op":"get","oid":4,"member":"Properties","id":"props"},
 {"op":"get","oid":9,"member":"Value","id":"val0"}]
```
→ `DataProperty.Value` は `VariantData`。`toString` が `DisplayString:<値>`（例: `IfcClass=IfcBuildingElementProxy`, `D=8000mm` 等）。

## 6. 安全・運用上の注意

- Navisworks API は **メインスレッド専用**。ブリッジが `SynchronizationContext` で UI スレッドへ委譲して実行するため、AI は意識不要。
- 書込（`set`/`invoke`）は実モデルを変更します。**保存前提の操作は社長/担当の確認後**に。
- ブリッジは **127.0.0.1 限定**（外部公開なし）。LAN/テナント越しは上位 sidecar 経由。
- App Control 有効環境では、配布ページの `trust-pls-cert.ps1`（PLS 署名証明書を信頼）を一度実行（Revit/Civil 3D と共通証明書）。

## 7. トラブルシュート

| 症状 | 対処 |
|---|---|
| `navisworks_ping` がタイムアウト | Navisworks 起動 & ポート 7660 待受を確認（§2） |
| Add-Ins に PLS が出ない | MSI 再導入 + `trust-pls-cert.ps1`（証明書信頼）→ Navisworks 再起動 |
| ポートが 7660 でない | 2026=7661 / 2027=7662。`PLS_NAVIS_BRIDGE_PORT` で上書き可 |
| 値が `Unknown` | そのプロパティに値が未設定（モデル側）。異常ではない |

---

配布元: **https://mcp.archisymphony.com**（社員限定）/ メンテナ: コ・クロード（CTO, PLS AI Family）