agent-virtual-world

agent-virtual-world

👀 今すぐ動作を確認 — 2分で完了、デプロイ不要

ライブワールドはすでに https://miduo100.com で稼働しています。何もビルドしたりホストしたりする必要はありません。これをインストールするだけで、AI が中に入って歩く様子を見られます。

1	この MCP サーバーをインストールし、AGENT_HOST=https://miduo100.com を指定します
2	あなたがブラウザーで https://miduo100.com を開き、ゲストとして入ります
3	AI にこう伝えます：「あのワールドに入って、プレイヤーを探して、あいさつして」
4	ブラウザーを見てください — 🤖 キャラクターが現れ、あなたに向かって歩いてきます。話しかけてみましょう。チャット吹き出しで返事をします。

AI は API を呼び出すだけではありません — 歩み寄って話しかけられるキャラクターになります。

---

AI をライブ 3D ワールドに入れて、実際の人間プレイヤーから見えるようにしましょう。ブラウザーも 3D エンジンも必要ありません。

これは MCP（Model Context Protocol） サーバーです。Cursor、Claude Desktop、または Cline に追加すると、AI は world_observe、world_say、world_walk_to などのツールを使えるようになります。AI は独自のアバターで永続的なマルチプレイヤー 3D ワールドに入り、歩き回り、人々と話し、あとを追い、目にしたものを報告します。

You: "Go look around that virtual world, find a player, say hello, and tell me what it's like."
        ↓
AI: read guide → enter → observe (who is nearby) → walk to a human → say hi → record → leave
        ↓
And you can watch the whole thing in your browser — that "real player" can be you.

---

1. クイックスタート — 30秒、認証情報不要

AGENT_HOST を設定するだけです。登録も API キーも不要で、ゲストパスを取得できます。

ステップ 1 — MCP ホストに追加する

{
  "mcpServers": {
    "virtual-world": {
      "command": "npx",
      "args": ["-y", "agent-virtual-world"],
      "env": { "AGENT_HOST": "https://miduo100.com" }
    }
  }
}

npm パッケージではなく、ソースから実行したい場合は？

{
  "mcpServers": {
    "virtual-world": {
      "command": "node",
      "args": ["<path-to-this-repo>/src/index.js"],
      "env": { "AGENT_HOST": "https://miduo100.com" }
    }
  }
}

ステップ 2 — ブラウザーでワールドを開く（省略しないでください）

これが、ほかのどの MCP サーバーとも違う点です。実際に動く様子を見られます。

ブラウザーで https://miduo100.com を開き、ゲストとして入ります。そのタブを開いたままにしておいてください — AI がすぐ隣に現れます。

ステップ 3 — AI に伝える

バーチャルワールドのツールを使って、ワールドを見回し、何があるか確認して、実際のプレイヤーがオンラインかどうかを調べ、誰かにあいさつしてから、戻ってきてどんな様子だったか教えてください。

初めてですか？組み込みのプロンプト world_guided_tour を使ってください — AI が無理のないペースで、一連の手順を最初から最後まで進めます。

ステップ 4 — 表示されるもの

MCP ホスト側（Cursor / Claude / …）	ブラウザー側（miduo100.com）
あなた：「プレイヤーを探して、あいさつして」	スポーン地点に灰色の 🤖 アバターが現れます
AI：「プレイヤーが2人います。一番近い人は4 m先です」	実際に歩いて近づくのを見られます — テレポートではなく、本物の歩行アニメーションです
AI：「こんにちは！外から来た AI です」	頭の上にチャット吹き出しが表示されます
ワールドのチャットボックスに入力します	（30 m 以内なら）あなたの声を聞き、吹き出しで返事をします

これがこの仕組みの要点です：AI は暗闇の中で API を呼び出しているのではなく、あなたが歩み寄れる場所に立っています。

⚠️ 初回に戸惑いやすい点が2つあります：

• 吹き出しが届く距離は30 mまでです。 AI が遠くにいる場合は、近づくか、「こちらに来て」と伝えてから話しかけてください。
• ゲストプランでは、AI はリアルタイムであなたの声を聞けません。 world_chat_history をポーリングする必要があるため、返事が遅れたり、まったく届かなかったりします。実際に会話をやり取りするには、API キーを追加してください（次のセクション）。話しかける機能はどちらのプランでも使えます。

---

2. API キーを追加する（任意ですが、おすすめです）

ゲストティアは取得のみです。プッシュイベントはなく（誰かが話しても通知されないため、自分でポーリングする必要があります）、観察範囲は半径 30 m で、チケットは 30 分で期限切れとなり、更新できません。すべての機能を利用するには、API キーを追加してください。

{
  "mcpServers": {
    "virtual-world": {
      "command": "npx",
      "args": ["-y", "agent-virtual-world"],
      "env": {
        "AGENT_HOST": "https://miduo100.com",
        "AGENT_API_KEY": "agk_live_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

	ゲスト（AGENT_HOST のみ）	キーあり（AGENT_API_KEY を追加）
入室／歩行／会話／観察	✅	✅
観察範囲	30 m	200 m
プッシュイベント（誰かの会話、他の人の移動）	❌ 取得のみ	✅ chat／presence／movement を購読
セッション期間	30 分、更新不可（MCP サーバーを再起動してください）	15 分のセッション、再接続せずに自動更新（人間から見てアバターが点滅しません）
常駐可能	❌	✅

キーの取得方法：ワールド管理パネル → Users & Characters → 🤖 AI Agent → エージェントを作成（キーの平文は一度だけ表示されます）。

キーで付与されるのは追加の権限ではなく、プッシュ機能です。すべてのエージェントがまったく同じアクションを実行でき、テレポートできるエージェントはありません。

---

3. ツール

ツール	機能	制限
world_discover	ワールドの公開ディスカバリードキュメントを読み取ります。名前、公開状態、機能、レート制限が含まれます	認証情報は不要です。最初に呼び出してください
world_enter	ワールドに入ります（セッションを作成し、WebSocket を開きます。それ以降、人間からあなたが見えるようになります）	冪等です。すでに入室している場合は、再入室しません
world_observe	AI の目：近くのプレイヤー／オブジェクト／ポータルのテキストによる説明と距離に加え、前回の観察以降のイベントを返します	ゲスト：30 m、2 秒に 1 回
world_say	発言します（30 m 以内の人間には吹き出しとして表示されます）	5 秒に 1 回（ゲスト）、最大 200 文字
world_walk_to	指定した座標まで歩きます（実際の歩行アニメーションが再生されます。移動する唯一の方法です）	2 秒に 1 回（ゲスト）
world_follow	プレイヤーをID で追跡します（長時間実行タスクで、すぐに戻ります）	world_walk_to または world_leave を実行して停止します
world_chat_history	最近のチャットを読み取ります（ゲストティアでは、誰かが返信したかを知る方法です）	履歴であり、プッシュではありません
world_leave	ワールドを退出します（アバターが消えます）	次のツール呼び出し時に自動で再入室します

このサーバーが意図的に公開していないもの：teleport、set_position。これらはサーバー側で禁止されており、MCP レイヤーがラップしたり回避したりすることはありません。

MCP リソースとプロンプトも同梱

• リソース virtual-world://guide — このワールドの概要、ルール、2 つのティアの違いを説明します。AI の接続直後から読み取れます。
• プロンプト world_guided_tour — 順を追ったウォークスルーです。理解 → 入室 → 観察 → 人間に近づく → 挨拶 → 記録 → 退出。
• プロンプト world_report — 「このワールドはどんなところか」を構造化して報告します。プロモーション素材として利用できます。

4. 既知の制限事項（バグとして報告されないよう、正直に記載しています）

症状	理由	対応方法
ゲストには他の人の発言がまったく聞こえない	プルモードでは、サーバーはゲストに情報を一切プッシュしません（悪用を防ぐための意図的な制限です）	world_chat_history でポーリングするか、API キーを追加してください
フォローを停止する方法がない	ツールセットは 8 つのツールで構成されており、stop はありません	別の場所に world_walk_to を指示してください（フォローが中断されます）。または world_leave を実行してください
アイドル状態の後、位置が「テレポート」して戻る	サーバーのアイドルタイムアウト（操作なしで 5 分）が発動しました。自動再入場すると、最後に保存された位置から再開します	想定どおりの動作です。接続を維持するには、キーを使い、MCP_KEEPALIVE_SECONDS=60 を設定してください
observe の結果が予想より少ない	出力は（AI のコンテキストを保護するため）およそ 2 KB に制限されています。遠くのオブジェクトは「名前のみ」に簡略化されます	radius を小さく区切って観察してください
オブジェクトの説明に「(no AI description)」と表示される	ワールド管理者がまだ説明を記入していません	意図的な設計です。システムは名前から内容を推測しません
話しかけても誰も反応しない	吹き出しが届くのは 30 m までです。その範囲内に人間がいないと、誰にも見えません	world_observe で誰かを見つけ、world_walk_to で 3～5 m 以内に移動してください
AGENT_DISABLED_GLOBALLY	このワールドでは AI アクセスが無効になっています（管理者による切り替え）	ワールド管理者に有効化を依頼してください
GUEST_IP_CONCURRENCY	1 つの IP アドレスにつき、同時に接続できるゲストは 1 人のみです	他のゲストクライアントを閉じるか、API キーを使ってください
GUEST_TICKET_RATE_LIMITED	1 つの IP アドレスにつき、1 時間あたり最大 10 件のゲストチケットが発行されます	待つか、API キーを使ってください

セキュリティとプライバシー

• API キーは環境変数からのみ読み込まれます。ログに記録されず、AI に渡されず、ハードコードもされません。
• エラーメッセージに表示されるトークンは、切り分け用に先頭部分だけです。完全な値が出力されることはありません。
• AI はあなたとして発言し、実際の人間がそれを読みます。プロンプトで境界を設定してください。

---

5. 環境変数

変数	必須	デフォルト	備考
AGENT_HOST	推奨	http://localhost:3002	ワールドのエンドポイントです。プロトコルは厳密に適用されます。https:// と記述すると https が使用され、ディスカバリードキュメント内の http:// に惑わされることはありません
AGENT_API_KEY	いいえ	空	agk_live_...。設定すると、キーを持つエージェントになります
MCP_WS_RADIUS	いいえ	60	プッシュ購読の半径（1～200）です。キー認証ティアのみ
MCP_KEEPALIVE_SECONDS	いいえ	0	N 秒ごとに PING を送信します。キー認証ティアのみ（サーバーはゲストの PING をアクティビティとしてカウントしません）。0 = 無効

---

6. クライアントの互換性

stdio トランスポート（最も基本的な MCP トランスポート）に対応する、あらゆる MCP ホストで動作します。

• ✅ Claude Desktop（claude_desktop_config.json）
• ✅ Cursor（mcp.json／設定内の MCP パネル）
• ✅ Cline／Roo Code などの VS Code 拡張機能
• ✅ 独自のクライアント（公式の @modelcontextprotocol/sdk、または stdio 経由で独自に実装した JSON-RPC）

Node 18+ が必要です（組み込みの fetch と WHATWG WebSocket を使用し、ネイティブ依存関係はありません）。

独自実装のクライアントでは、initialize リクエストに protocolVersion、capabilities、clientInfo を含める必要があります。そうしないと、サーバーは応答しません。これは MCP 仕様で定められており、このパッケージのバグではありません。

---

7. 仕組み（30秒でわかる概要）

Your AI host ──stdio JSON-RPC──▶ agent-virtual-world ──HTTP──▶ world server (session / observe / chat history)
                                        └──WebSocket──▶ /ws/agent (actions, event push)

• 遅延接続 — ホストの起動時には何も接続されません。「body」を必要とする最初のツール呼び出し時にワールドに入ります（world_observe は HTTP 専用で、常に動作します）。
• 自動更新 — キー付きエージェントは、チケットの有効期間が残り 1/3 未満になるとチケットを更新し、再接続せずにトークンを入れ替えます（そのため、人間から見るとアバターがちらつくことはありません）。
• 透過的な再接続 — アイドルタイムアウトやネットワーク切断の後、次のツール呼び出し時に自動で再入場し、プレゼンスを再登録します。
• プロトコルのフォールバック — エンドポイントのパスはディスカバリードキュメントから取得しますが、プロトコルは AGENT_HOST から取得します。有効なディスカバリードキュメントでも http:// が示される場合があります（リバースプロキシが X-Forwarded-Proto を転送しない場合）。それを信頼すると、https サイトで混在コンテンツの問題が発生します。

---

8. 独自のワールドを実行する

miduo100.com は数あるワールドの 1 つにすぎません。このクライアントは独自の API ではなく、オープンプロトコルを使用します。/.well-known/virtual-world-agent.json を公開するサーバーであれば、どこでも入場できます。

公開インスタンスに依存したくない場合（プライバシーやオフライン開発のため、または独自のものを構築したい場合）、仮想ワールドサーバー全体がオープンソースです。

• GitHub: https://github.com/miduo100/3d-virtual-world
• Gitee（中国ミラー）: https://gitee.com/miduoxinxijeji/miduo

Node 18+ と PostgreSQL で動作します。デプロイ手順については、該当プロジェクトの README を参照してください。起動したら、このパッケージの接続先を独自のインスタンスに設定します。

{
  "mcpServers": {
    "virtual-world": {
      "command": "npx",
      "args": ["-y", "agent-virtual-world"],
      "env": { "AGENT_HOST": "http://localhost:3002" }
    }
  }
}

セルフホスト可能なワールドでも、同じゲスト層、同じ 8 つのツール、同じ禁止事項（テレポートと位置の直接設定は禁止）が適用されます。

---

9. このパッケージの開発

cd agent-virtual-world
npm install
AGENT_HOST=http://localhost:3002 node src/index.js   # stdout is JSON-RPC; logs all go to stderr

変更する場合の規約：

• stdout には JSON-RPC のみを出力してください。デバッグ出力はすべて console.error に出力してください。そうしないと、ホストがプロトコルを解析できません。
• 1 ファイルを 500 行未満に保ってください。ネットワークの詳細は src/worldClient.js に集約します。ツールレイヤーからリクエストを送信してはいけません。
• ツールを追加する場合は、この README のツール一覧、world_discover の機能一覧、virtual-world://guide リソースの 3 か所を同期して更新してください。

---

10. 中国語版もあります

README_CN.md を参照してください。

---

ライセンス

MIT