# PLS Civil3DMCPBridge — AI バディ運用ガイド

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

> 配布元: https://mcp.archisymphony.com （PLS 社員限定 / PlsCivil3DBridge）
> 対象: Civil 3D 2025 / 2026 / 2027 ＋ PlsCivil3DBridge アドイン導入済みの Windows PC

---

## 1. これは何か

**PlsCivil3DBridge** は、Civil 3D / AutoCAD の全 .NET API を **Model Context Protocol (MCP)** 経由で AI から制御できるアドインです。
Alignment / Surface / 縦断 / パイプネットワーク等の読取・編集・introspection を、AI バディが自然言語の指示から実行できます。

- アドインが起動時に **ローカル TCP** `127.0.0.1:7640`（= `7640 + (年度-2025)`、2025/2026/2027 が同時起動可）でリッスン
- **Universal Bridge（reflection）**: `Autodesk.AutoCAD.*` / `Autodesk.Civil.*` の **全 public メソッド・プロパティ**へ到達（API 100% 網羅）
- 通信は **4 バイト長(LE) + UTF-8 JSON** フレーム。MCP shim が stdio ⇄ TCP を仲介

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

1. Civil 3D (2025/2026/2027) が **起動**しており、**図面が 1 つ開かれている**こと
2. MSI 導入済み（`%APPDATA%\Autodesk\ApplicationPlugins\PlsCivil3DBridge.bundle`）。**起動時に自動ロード＋ブリッジ自動起動**（手動 NETLOAD 不要）
3. ターゲット PC に **Node.js**（MCP shim 実行のため）
4. ブリッジ稼働確認（PowerShell）:
   ```powershell
   Test-NetConnection 127.0.0.1 -Port 7640 -InformationLevel Quiet   # => True
   ```
   閉じている場合は Civil 3D コマンドラインで `PLSCIVILBRIDGE`（手動起動）。停止は `PLSCIVILBRIDGESTOP`。

## 3. 接続方法（MCP サーバー経由 / 推奨）

MSI 同梱の MCP shim（`<bundle>\Contents\mcp\index.mjs`）を MCP クライアントに登録します。

```json
{
  "mcpServers": {
    "civil3d": {
      "command": "node",
      "args": ["%APPDATA%\\Autodesk\\ApplicationPlugins\\PlsCivil3DBridge.bundle\\Contents\\mcp\\index.mjs"],
      "env": { "CIVIL3D_BRIDGE_HOST": "127.0.0.1", "PLS_CIVIL3D_BRIDGE_PORT": "7640" }
    }
  }
}
```

> Civil 3D 2026 は `7641`、2027 は `7642`（`PLS_CIVIL3D_BRIDGE_PORT` で明示指定）。

**公開ツール（これだけで全 API に到達。読取・編集も可能）:**

| tool | 用途 |
|---|---|
| `civil3d_ping` | ブリッジ疎通確認（`bridge_version` / ActiveDocument / 図面名を返す）。**まず最初に** |
| `civil3d_invoke` | reflection バッチを **1 トランザクション**実行。任意の .NET API に到達 |

`civil3d_invoke` の `requests` 配列（各要素）:

| フィールド | 説明 |
|---|---|
| `op` | `static_get` / `get` / `set` / `invoke` / `list_members` |
| `target` | 型名（例 `Autodesk.Civil.ApplicationServices.CivilApplication`）または別名 `CivilDocument` / `Database` |
| `handle` | 既知オブジェクトの handle（`target` の代わりに指定可） |
| `member` | メソッド / プロパティ名 |
| `args` | 引数配列（`set` / 引数付き `invoke` 用） |
| `id` | 結果の識別子（任意） |

## 4. まず叩くべき呼び出し

```jsonc
// civil3d_invoke の requests 例（1 トランザクションでまとめて）
[
  { "op":"static_get", "target":"Autodesk.Civil.ApplicationServices.CivilApplication", "member":"ActiveDocument", "id":"doc" },
  { "op":"invoke", "target":"CivilDocument", "member":"GetAlignmentIds", "id":"aligns" },
  { "op":"invoke", "target":"CivilDocument", "member":"GetSurfaceIds",   "id":"surfaces" },
  { "op":"get",    "target":"Database", "member":"Filename", "id":"fn" }
]
```

Civil ドメインの collection accessor 例: `GetAlignmentIds` / `GetSurfaceIds` / `GetSiteIds` / `GetPipeNetworkIds` / `GetPressurePipeNetworkIds` / `GetIntersectionIds` / `GetViewFrameGroupIds`。
各要素は `{handle, type, name}` で返るので、続く呼び出しで `handle` を指定して instance の `get`/`invoke`/`set` を行う。

```jsonc
// 取得した Alignment handle に対する instance 操作
[
  { "op":"get",    "handle":"13E2E", "member":"Name",   "id":"name" },
  { "op":"get",    "handle":"13E2E", "member":"Length", "id":"len" },
  { "op":"invoke", "handle":"13E2E", "member":"GetProfileIds", "id":"profiles" },
  { "op":"list_members", "handle":"13E2E", "id":"members" },           // introspection
  { "op":"set",    "handle":"13E2E", "member":"Description", "args":["AI 編集テスト"], "id":"setdesc" }
]
```

## 5. AI バディへの運用ルール（重要）

- **メンバー名は `list_members` で確認**してから使う（推測しない）。型が不明なら `list_members` で introspection。
- **破壊的操作**（`set` による上書き、削除系メソッド、大量編集）は、実行前に必ず**対象と件数をユーザーに提示して確認**を取る。
- レスポンスはエンベロープ `{"bridge_version","ok","count","results":[{id,ok,result,resultType}]}`。各 `result.ok=false` の場合は `error` を読んで原因を説明する。
- 書込・作成・削除は **DocumentLock + Transaction** 内で安全に実行される（「未対応で詰む」ことはない = Universal Bridge）。
- 図面未読込時は一部呼び出しが失敗 → 先に「図面を開いてください」と案内する。
- 大量要求は 1 バッチ（1 トランザクション）にまとめると高速。巨大すぎる場合はクライアント側で分割。

## 6. 典型ワークフロー（AI バディの思考順序）

1. `civil3d_ping` で疎通＋現況図面を把握
2. `civil3d_invoke` で `Get*Ids` 系を叩きドメイン要素を列挙
3. 得た `handle` で個別に `get` / `list_members` 詳細確認
4. 編集系（`set` / 編集メソッド）は **ユーザー確認後**に実行 → `results[].ok` で検証

## 7. ヘッドレス実行（任意 / accoreconsole）

対話 Civil 3D を使わず、`accoreconsole.exe` + `.scr` から `PLSCIVILINVOKE` を呼ぶと、
env `PLS_CIVIL_INVOKE_IN`（要求 JSON 配列）→ `PLS_CIVIL_INVOKE_OUT`（結果）でバッチ実行できる（CI / 検証向け）。

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

| 症状 | 対処 |
|---|---|
| 7640 が閉じている | Civil 3D 起動済か確認 → コマンドラインで `PLSCIVILBRIDGE` |
| `mcp__civil3d__*` が出ない | MCP クライアント（Claude）を**再起動**（MCP は起動時ロード） |
| `node` が無い | ターゲット PC に Node.js を導入（shim 実行に必須） |
| 起動時に証明書警告 | 同梱 `Contents\codesign\trust-pls-cert.ps1` を管理者で 1 回実行 |

---

**問い合わせ**: PLS AI Family / クロード（CTO）
**最新版・更新**: Civil 3D 起動時に自動でバージョン確認され、新版があれば https://mcp.archisymphony.com へ案内されます。