World Model MCP

@putervision/world-model-mcp

@putervision/world-model-mcp は、AI エージェント向けに永続的な3D／2D空間ワールドモデルを維持する、インフラ不要で決定論的な Model Context Protocol（MCP）サーバーです。永続的なエンティティ追跡、信頼度減衰を伴うオブジェクトの永続性、AABB 衝突回避を伴う移動シミュレーション、予測視錐台投影、Playwright による3Dゲーム自動化により、知覚（@putervision/vision-memory-mcp）と推論／アクション（@putervision/state-memory-mcp）を橋渡しします。

🌐 公式ドキュメントとウェブサイト：putervision.com

---

⚡ クイックスタートとインストール

前提条件：Node.js >= 18.18.0

# 1. Install globally
npm install -g @putervision/world-model-mcp

# 2. Navigate to your project directory
cd your-project

# 3. Initialize world-model-mcp
# Creates .world-model-mcp/, updates .gitignore, registers project,
# and scaffolds IDE instructions and MCP configs for Cursor, Claude, VS Code, Windsurf, etc.
world-model-mcp init

# Done! Restart your IDE or Agent Manager to activate.

代替オプション

# Run directly via binary (after global install)
world-model-mcp run

# Launch interactive 3D WebGL Scene Visualizer
world-model-mcp view

# Display database metrics and permanence confidence stats
world-model-mcp stats

---

🌟 主な特長

• 🌐 決定論的な3D／2D空間メモリとコンパクトスライス：空間インデックスの処理にLLMを介しません。FTS5検索、3Dユークリッド距離による近傍半径検索、システム1の高速評価パス向けに観測者を基準とした1KB未満のコンパクトスライス（$K \le 16$ 個の最寄りエンティティ）を、決定論的なSQLite WALクエリで実現します。
• ⚡ 本番環境対応の統合MCPツール15種類：完全なCRUD、トポロジカルな空間グラフ（on、inside、contains、near）、ray-AABBによる遮蔽の視錐台カリング、ウェイポイントナビゲーション、タイムトラベルによるロールバックに対応します。
• ⏳ オブジェクトの永続性と減衰：エンティティは視界の外に出ても永続メモリに残り、設定可能な指数関数的信頼度減衰（$C = C_0 \cdot e^{-\lambda t}$）とステータスのライフサイクル（active → hidden → lost）に対応します。
• 🚀 衝突と移動のシミュレーション：エンティティの変位軌跡を予測し、AABB障害物との衝突を検出し、アクションの実行前に障害物を回避するナビゲーション用ウェイポイントを算出します。
• 🎮 Playwrightによるゲーム自動化：時間指定のWASD／矢印キー押下シーケンス（KeyW for 450ms、ArrowLeft for 290ms）と、3D↔2D座標の画面投影を生成します。
• 🤝 マルチエージェント空間ブラックボード：TTL、ミューテックスロック、並列サブエージェント間の衝突意図アラートを備えた、トピックベースの連携に対応します。
• 🛡️ 空間仕様駆動開発（Spatial SDD）：物理設計コントラクトのベースライン登録、ライブ検証（クリアランス、境界、包含）、暗号学的SHA-256エビデンスバンドルに対応します。
• 🎨 インタラクティブな3D WebGLビジュアライザー：ブラウザー上のThree.js 3Dビューポートで、アクティブなエンティティ、向きの軸、視錐台コーン、トポロジカルリンクを描画します（world-model-mcp view）。
• 🔒 100％ローカルでプライベート：すべての空間エンティティ、関係、履歴は、ワークスペース内の .world-model-mcp/ に保存されます。

---

🛠️ MCP ツールスイート

@putervision/world-model-mcp は、5 つの主要なワークフロードメインにわたって整理された、本番環境向けの統合 MCP ツール 15 種を提供します。

• 空間メモリと検索：update_entity（エンティティの CRUD、3D 境界、プロパティ、信頼度）、query_entities（FTS5 検索、近接半径、ステータス／タグによるフィルタリング、履歴検索）、set_relation（トポロジカルグラフのリンク：on、inside、near、contains）、get_spatial_map（JSON、GeoJSON、glTF 2.0、OBJ、要約、および format: "compact_slice"）。
• シミュレーションとビジョンの統合：simulate_movement（変位予測、AABB 衝突チェック、ウェイポイント経路探索）、ingest_observation（ビジョン検出結果の取り込み、ユークリッド距離による再識別、視錐台の調整）、get_expected_view（観測者の姿勢、水平 FOV コーン、レイと AABB によるオクルージョン）。
• 目標と状態の統合：link_to_goal（エンティティ／領域を State Memory のタスクに関連付け、空間コンテキストのスライスを抽出）、record_outcome（実行結果、位置の変化、プロパティの変更、破棄を記録）。
• 空間 SDD と証明：manage_spatial_spec（物理的なクリアランス／包含の契約を登録し、実行時に検証スコアを算出）、create_evidence_pack（空間証明をタスクノードに関連付ける、暗号学的な SHA-256 証拠バンドルを作成）。
• マルチエージェント、リプレイ、自動化：use_spatial_blackboard（トピックボード、ミューテックスの取得／解放、インテントの競合）、manage_snapshot（チェックポイント、スナップショット差分、時間を遡るアンドゥ）、wait_for_spatial_state（目標とする空間条件を非同期でポーリング）、generate_game_inputs（Playwright の WASD 押下時間、3D↔2D の画面レイ投影）。

👉 パラメーター仕様、戻り値のスキーマ、ペイロードの例については、API リファレンスガイド と データベーススキーマ をご覧ください。

---

🚀 アーキテクチャと空間メモリのライフサイクル

                     Perception / Vision Detection
                                  │
                                  ▼
                 ┌─────────────────────────────────┐
                 │  Perception Ingestion & Re-ID   │ ──▶ ingest_observation(reconcile: true)
                 └────────────────┬────────────────┘
                                  │
                                  ▼
                 ┌─────────────────────────────────┐
                 │  Durable Entity & Permanence    │ ──▶ update_entity(...)
                 │  (3D Bounding Boxes, Decay)     │ ──▶ set_relation(relation: "on"|"inside")
                 └────────────────┬────────────────┘
                                  │
                                  ▼
                 ┌─────────────────────────────────┐
                 │  Simulation & Waypoint Routing  │ ──▶ simulate_movement(mode: "navigate")
                 │  (AABB Collision Avoidance)     │ ──▶ get_expected_view(fov: 90)
                 └────────────────┬────────────────┘
                                  │
                                  ▼
                 ┌─────────────────────────────────┐
                 │  Playwright & Action Execution  │ ──▶ generate_game_inputs(...)
                 │  (WASD Sequences, Screen Rays)  │ ──▶ record_outcome(action_type: "move")
                 └────────────────┬────────────────┘
                                  │
                                  ▼
                 ┌─────────────────────────────────┐
                 │  Spatial SDD & Cryptographic    │ ──▶ manage_spatial_spec(action: "verify")
                 │  Evidence Bundling to Tasks     │ ──▶ create_evidence_pack(...)
                 └────────────────┬────────────────┘
                                  │
                                  ▼
                 ┌─────────────────────────────────┐
                 │  Persistent SQLite Engine       │ ──▶ .world-model-mcp/world.db (WAL mode)
                 │  Append-Only History Ledger     │ ──▶ SHA-256 Cryptographic Audit Chain
                 └─────────────────────────────────┘

---

📚 ドキュメント一覧

docs/ ディレクトリにある専用ガイドと詳細解説をご覧ください。

ガイド	説明
🏗️ アーキテクチャとコードベースの要約	要点を押さえたアーキテクチャ概要、モジュール一覧、データフロー、設計上の決定事項。
💡 機能とトライアドの概要	PuterVision Autonomous Triad のインタラクション、3D WebGL シーンビジュアライザー、証拠バンドル。
📋 空間ワールドモデルの概念	オブジェクトの永続性（$C = C_0 \cdot e^{-\lambda t}$）、信頼度の減衰、視錐台投影、空間 SDD。
⚙️ 設定と IDE のセットアップ	自動初期化の詳細、環境変数、エディター設定（Cursor、VS Code、Claude、Windsurf）。
🛠️ CLI コマンドリファレンス	CLI フラグ（init、run、view、stats、inspect、map、export、import、doctor、snapshot、spec、blackboard）。
🧰 ツールと API リファレンス	15 種すべての統合 MCP ツール、従来のツールとの対応付け、パラメーター例を網羅したリファレンス。
🗄️ データベーススキーマ	SQLite テーブル（entities、spatial_relations、entity_history、spatial_specs、blackboard_items、evidence_packs）。
🎮 インタラクティブ 3D ゲームアリーナデモ	Three.js ブリッジの診断機能（window.__WORLD_MODEL_BRIDGE）を備えた、自律型の 3D ブラウザーアリーナ。
🧭 例とチュートリアル	詳細な例：空間ナビゲーション、知覚の調整、マルチエージェントのブラックボード。

---

📖 エージェント用プレイブック：標準的な 5 ステップのワークフロー

自律型 AI エージェントが world-model-mcp を含むリポジトリに入った場合：

1. Orient & Explore   ──▶ get_spatial_map(format: "summary") + get_expected_view(fov: 90)
2. Query & Locate     ──▶ query_entities(query: "chest", radius: 15) + query_entities(entity_id: "...")
3. Plan & Simulate    ──▶ simulate_movement(mode: "navigate") + manage_spatial_spec(action: "verify")
4. Execute & Ingest   ──▶ generate_game_inputs(...) + ingest_observation(reconcile: true)
5. Record & Evidence  ──▶ record_outcome(...) + create_evidence_pack(task_id: "...")

---

🧪 テスト

# Run full unit, integration, and geometry stress test suite across 47 test files (206 tests)
npm test

# Run multi-Node matrix test suite across Node.js 18, 20, and 22
npm run test:matrix

# Run 3D geometry, projection, and Playwright game loop tests
npm run test:3d

---

⚖️ ライセンスと免責事項

PuterVision が開発・保守しています。MIT ライセンスの下で公開されています。

• ローカルストレージの保証：空間座標、境界ボリューム、エンティティの履歴はすべて、作業スペース内に100％ローカルで保持されます。テレメトリーやプロジェクトデータが送信されることはありません。
• 商標および非提携について：製品名（Cursor、Claude Code、Gemini、Windsurf、VS Code、GitHub、SQLite、Three.js、Playwright）は、それぞれの所有者に帰属し、互換性の識別のみを目的として使用しています。