Project Atlantis

Project Atlantis

ニャー！ まずは www.projectatlantis.ai でアカウントを作成し、ボットにセットアップを案内してもらうとよいでしょう（すべて問題なく動作する場合）。

基本的には、ボット向けのツール基盤を提供する、分散型の Linux スタイルシステムです。ツールは、機能やチームをまたいで簡単に管理できるよう、フォルダーごとに整理されています。チームは互いの機能を直接呼び出すことができ、もちろん、ボットが自分で処理することもできます。内部では MCP 準拠のシステムが動作していますが、MCP ツールを頻繁に更新する煩雑さなしに、ホットローディングなどをサポートしています。

始めるには、リポジトリをクローンし、Python 環境をセットアップし、API キーを環境変数（OPENROUTER_API_KEY、ANTHROPIC_API_KEY など）として設定してから、このローカルの Python サーバーをメインサーバーに接続します（runServer を参照）。Claude などのようにツールを呼び出すチャットボットを構築するためのソースコードをすべて提供しています。OpenRouter と Anthropic API を使用する動作例については、Bot/Kitty/ を参照してください。ボットはツールを事前に読み込まず、検索を通じて動的に検出します。

*@game コールバックは、新しいチャットが作成されるたびに実行されます。

Project Atlantis Network

各 MCP サーバーは、AI エージェントと開発者の協調ネットワークの一部です。Model Context Protocol を使用することで、このプラットフォームはネットワーク全体でエージェントが互いの機能を発見し、利用できるエコシステムを構築します。ロボット主導のフロンティア開発、自動化タスク、その他あらゆる用途において、ツールや機能をエージェント間で共有、発見、連携できます。ネットワークアーキテクチャにより、エージェントは他のユーザーのツールを見つけて活用でき、共有機能の分散型エコシステムが実現します。

このプロジェクトの中核となるのは Python MCP ホスト（「リモート」と呼ばれます）で、関数やサードパーティ製 MCP ツールをその場でインストールできます。

Quick Start

1. 前提条件 — サーバー用の Python と Lobster（MCP クライアント）用の Node をインストールする必要があります。また、MCP では両方が必要なようなので、uv/uvx と node/npx もインストールしてください。

2. 非同期処理のサポートを考慮すると、現時点では Python 3.13 が最も安定しているようです。

3. Python 仮想環境をセットアップし、依存関係をインストールします。

cd python-server
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

4. python-server フォルダー内の runServer スクリプトを編集し、メールアドレスとサービス名を設定します（更新時に runServer ファイルと置き換えられるコピー「runServerFoo」を作成しておくのが、実際にはベストプラクティスです）。

python server.py  \
  [email protected]  \             # email you use for project atlantis
  --api-key=foobar \                         # should change online
  --host=localhost \                         # npx MCP will be looking here to connect to remote (assumes there is at least one running locally)
  --port=8000  \
  --cloud-host=wss://projectatlantis.ai  \   # points to cloud
  --cloud-port=443  \
  --service-name=home                        # remote name, can be anything but must be unique across all machines

5. MCP クライアントの名称は Lobster になりました。Python サーバーの起動コマンド（たとえば runServer スクリプト）で --port に設定したポートを使用してください。以下の YOUR_SERVER_PORT をその番号に置き換えてください。8000 と決めつけないでください。

Claude Code に接続するには：

claude mcp add atlantis_lobster -- npx atlantis-mcp --port YOUR_SERVER_PORT

Codex に接続するには：

codex mcp add atlantis_lobster -- npx atlantis-mcp --port YOUR_SERVER_PORT

ポートの上書き設定がない場合に限り、デフォルトのポートは 8000 です。サーバーのポートを変更した場合は、MCP エントリの --port 引数も更新してください。JSON 設定テンプレートについては、Lobster クライアントの README を参照してください。

テスト用に Atlantis Open Weather を追加するには：

claude mcp add --transport stdio weather_forecast --env OPENWEATHER_API_KEY=mykey123 -- uvx --from atlantis-open-weather-mcp start-weather-server

6. To connect to Atlantis, sign into https://www.projectatlantis.ai under the same email

7. Your remote(s) should autoconnect using email and default api key = 'foobar' (see 'api' command to generate a new key later). The first server to connect will be assigned your 'default' unless you manually change it later

8. Chat comes pre-installed, along with the Home, Bot and Setup apps, in python-server/dynamic_functions/. On first run, the server also creates a starter Demo app with example functions. No separate installation is needed for these bundled apps. The dynamic_servers/ folder includes an example weather config.

9. You can run this standalone MCP or accessed from the cloud or both

Architecture

Caveat: MCP terminology is already terrible and calling things 'servers' or 'hosts' just makes it more confusing because MCP is inherently p2p

Pieces of the system:

• Cloud: our experimental Atlantis cloud server; mostly a place to share tools and let users bang on them
• Remote: the Python server process found in this repo, officially referred to as an MCP 'host' (you can run >1 either on same box or on different one, just specify different service names)
• Dynamic Function: a simple Python function that you write, acts as a tool
• Dynamic MCP Server: any 3rd party MCP, stored as a JSON config file

Note that MCP auth and security are still being worked out so using the cloud for auth is easier right now

Directories

1. Python Remote (MCP P2P server) (python-server/)

   • Location of our 'remote'. Runs locally but can be controlled remotely

2. Lobster (MCP Client) (client/)

   • lets Claude Code or Codex run Atlantis commands or chat via MCP
   • uses npx (easy to install into Claude Code or Codex)
   • cloud connection not needed - although it may complain
   • only supports a subset of the spec
   • can only see tools on the local box (at least right now) or shared tools set to 'public'

Python Server Layout

Start in python-server/server.py. It is the protocol host: it owns the WebSocket and cloud connections, and MCP tools/call goes through DynamicAdditionServer._handle_tools_call(). From there:

• DynamicFunctionManager.py loads, validates and calls the Python tools in dynamic_functions/, and defines the decorators.
• DynamicServerManager.py runs the third-party MCP servers configured in dynamic_servers/.
• atlantis.py is the runtime API that tool code calls back into.
• lobster.py holds the local Lobster client's readme / command / chat tools.
• state.py and utils.py hold config, logging and shared helpers.

Further docs:

• Dynamic Functions: writing tools.
• atlantis API: the runtime, including browser callbacks.
• Security Model: auth and trust boundaries.

Features

Dynamic Functions

Dynamic functions give users the ability to create and maintain custom functions-as-tools. Functions are loaded on start and automatically reloaded when modified.

The python-server/dynamic_functions/ directory includes the pre-installed Chat, Bot, Home, and Setup apps. These apps are tracked with the server source. Seeing them on a new server is expected.

On first run, the server also creates a starter Demo app with example functions, once per .demo_scaffolded marker. Everything else under dynamic_functions/ is ignored by this repository.

Add your own app in a new subfolder. To keep an app in its own repository, clone that repository directly into dynamic_functions/:

cd python-server/dynamic_functions
git clone [email protected]:you/my-atlantis-app.git MyApp

アプリフォルダーは独立した Git リポジトリであり、サーバーリポジトリでは無視されています。バンドルされたフォルダーはそのまま残してください。dynamic_functions/ ディレクトリ全体を置き換えないでください。

動的関数の作成と使用に関する詳細は、Dynamic Functions Documentation を参照してください。

Dynamic MCP Servers

• サードパーティ製 MCP サーバーツールをインストールして管理する機能をユーザーに提供します。JSON 設定ファイルは dynamic_servers/ フォルダーに保存されます。

• 各 MCP サーバーは、ツールの一覧を取得するために、まず「起動」する必要があります。

• 各サーバーの設定は、'mcpServers' 要素を含む一般的な JSON 構造に従います。たとえば、以下の設定は openweather MCP サーバーをインストールします。

  {
     "mcpServers": {
        "openweather": {
           "command": "uvx",
           "args": [
           "--from",
           "atlantis-open-weather-mcp",
           "start-weather-server",
           "--api-key",
           "<your openweather api key>"
           ]
        }
     }
  }
  

weather MCP サービスは、既存のサービスを uvx に移植したものです。こちら を参照してください。

クラウド

https://www.projectatlantis.ai のクラウドサービスでは、リモートサーバーを一元管理し、マシン間でツールを共有できます。

アプリの構成

動的関数は、フォルダー構造を使用してアプリに整理します。.py ファイルをサブディレクトリに配置するだけです。

dynamic_functions/
├── Home/                    # App: "Home"
│   └── kitty.py
├── Accounting/              # App: "Accounting"
│   ├── accounting.py
│   └── foo.py
└── FilmFromImage/          # App: "FilmFromImage"
    └── qwen_image_edit_local.py

フォルダー名がアプリ名になります。 Home フォルダー内の関数は、それに応じて割り当てられます。

ネストされたアプリ（サブフォルダー）

サブフォルダーを使用して、ネストされたアプリ構造を作成します。

dynamic_functions/
└── MyApp/
    └── SubModule/
        └── Feature/
            └── my_function.py

これにより、アプリ名は MyApp/SubModule/Feature になります。

ベストプラクティス：

• シンプルに保ちます。通常、フォルダーは1階層で十分です
• わかりやすいフォルダー名を使用します（例：Chat、Admin、Tools）
• 関連する関数を同じフォルダーにまとめます
• フォルダー構造を使うと、コードを整理してわかりやすく保てます

検索語を使ったツール呼び出し

ツールを呼び出す際は、複合ツール名を使って関数を区別できます。関数を一意に特定するために必要な分だけパスを含めてください。

形式： remote_owner*remote_name*app*location*function

重要な原則：一意に解決できる最もシンプルな形式を使用します

# If you have these functions:
# - dynamic_functions/Chat/send_message.py
# - dynamic_functions/Email/send_message.py
# - dynamic_functions/SMS/send_message.py

send_message              ❌ Ambiguous! Which one?
**Chat**send_message      ✅ Clear! The one in Chat
**Email**send_message     ✅ Clear! The one in Email

例：

update_image                          → Simple call (only works if unique)
**MyApp**update_image                 → Specify app to disambiguate
**MyApp/SubModule**process_data       → Nested app path
alice*prod*Admin**restart             → Full routing: owner + remote + app + function
***office*print                       → Just location context

仕組み：

• フィールド：remote_owner*remote_name*app*location*function
• フィールドは *（アスタリスク）で区切ります
• 不要なフィールドは省略します（空文字列を使用：**App**func）
• アプリフィールドでは、スラッシュ表記を使ってネストされたアプリを指定できます（MyApp/SubModule）
• 最後のフィールドは常に関数名です
• アスタリスクがない場合は、名前全体を関数名として扱います

複合名を使用する場合：

• 名前の競合： 複数のアプリに同じ名前の関数がある場合
• リモートの指定： クラウドから特定のリモート上の関数を呼び出す場合
• 場所のルーティング： 特定の物理的な場所にある関数を指定する場合
• マルチユーザー環境： 共有環境で所有者とリモートを指定する場合

ベストプラクティス： シンプルな形式（update_image）から始め、曖昧さを解消する必要がある場合にのみ情報を追加します（**ImageTools**update_image）。

例：

# File: dynamic_functions/ImageTools/process.py
@visible
async def update_image(image_path: str):
    """Update an image."""
    return "updated"

# If this is the ONLY update_image:
update_image                          ✅ Works fine!

# If Chat app ALSO has update_image:
**ImageTools**update_image            ✅ Now we need to specify the app

ボットのランタイム

ボット／チャットのランタイムは、動的関数アプリとしてこのリポジトリに含まれています。

python-server/dynamic_functions/Chat/

ゲーム／チャット用ツール、ボットのランタイム、Game/ 以下の静的コンテンツ、Data/ 以下のプレイヤーのライブ状態を保持します。Atlantis MCP サーバーは、ほかの動的関数アプリと同様にこのアプリを扱います。フォルダーをスキャンし、デコレーターが付いた関数をツールとして公開し、ファイルが変更されると再読み込みします。

主なファイル

• python-server/dynamic_functions/Home/ — Lobster／Multix の README エントリーポイントとファイルコールバックに使用する、プラットフォーム管理の小規模な Home アプリです。Home README を参照してください。
• python-server/dynamic_functions/Chat/ — ボット／チャットのランタイムアプリです。Chat README を参照してください。
• python-server/dynamic_functions/Terrain/ — 地形用ツールです。独自のプライベートリポジトリ（[email protected]:project_atlantis/terrain.git）で管理され、このフォルダーにクローンされます。このリポジトリでは追跡されません。
• python-server/dynamic_functions/Chat/Game/ — 静的なゲームコンテンツ（場所、シーン）です。追跡対象です。
• python-server/dynamic_functions/Bot/ — Bot/<sid>/ 以下にある静的なボット情報（設定、プロンプト、画像）です。追跡対象です。ゲームとは別のマシンにボットを配置できるよう、Chat とは分けています。
• python-server/dynamic_functions/Chat/Data/ — game_key をキーとする、ゲームごとのライブ状態です。追跡対象ではありません。

トラブルシューティング

MCP ツールが動作しない場合（例：Unknown tool エラーが返される場合）は、まずサーバーログを確認してください。Python サーバーは詳細なログを python-server/runServer.log に書き込みます。このファイルで、ツール呼び出し、クラウド認証、クライアント接続で何が起きているかを正確に確認できます。ファイルが大きくなることがあるため、末尾の約 1000 行を表示してください。

tail -1000 python-server/runServer.log

ログで確認できる一般的な問題：

• ⚠️ Unexpected tool call from local client — サーバーはツール呼び出しを受信しましたが、認識できませんでした。ツールが登録されていることを確認してください
• ❌ Authentication failed — クラウド認証情報が誤っているか、アカウントが存在しません。メールアドレス／API キーを確認してください
• 🏠 Local MCP tool call intercepted — サーバーが MCP クライアントからツール呼び出しを受信していることを確認できます
• MCP ハンドシェイクエラーは通常、クライアントが誤ったポートを参照していることを意味します。デフォルトのローカル MCP ポートは 8000 です。サーバーの --port とクライアントの --port が一致していることを確認してください。

訪問者に関するログ行には、"Visitor:"、"New conversation for"、"Injected time-gap message" が含まれます。

Greenland Terrain Server

このシステムを、Greenland terrain server の主要なボットインフラ（ツールなど）として使用することを目指しています。