Project Atlantis

Project Atlantis

喵！理想情况下，你可以先在 www.projectatlantis.ai 创建一个账户，然后让机器人引导你完成设置（前提是一切运行正常）。

简单来说，我们有一个分布式的 Linux 风格系统，为机器人提供工具基础设施。工具按文件夹组织，便于跨职能和团队管理。团队可以直接调用彼此的函数，当然，机器人也可以自行完成任务。底层采用符合 MCP 标准的系统，但我们支持热加载等功能，无需不断更新 MCP 工具，也避免了一些繁琐的额外操作。

开始使用时，先克隆仓库，完成 Python 环境配置，将 API 密钥设为环境变量（OPENROUTER_API_KEY、ANTHROPIC_API_KEY 等），然后将这个本地 Python 服务连接到主服务（参见 runServer）。我们提供了构建工具调用聊天机器人的全部源代码，让你可以打造类似 Claude 或其他产品的机器人。查看 Bot/Kitty/，其中有使用 OpenRouter 和 Anthropic API 的可运行示例——机器人通过搜索动态发现工具，而不是预先加载工具。

*注意：每当创建新聊天时，都会运行 @game 回调。

Project Atlantis Network

每个 MCP 服务都是由 AI Agent 和开发者组成的协作网络的一部分。该平台使用 Model Context Protocol，构建了一个生态系统，让 Agent 能够在整个网络中发现并使用彼此的功能。工具和函数可以在 Agent 之间共享、发现和协调，无论是用于机器人驱动的前沿开发、自动化任务，还是其他应用。网络架构让 Agent 能够找到并利用其他用户的工具，从而构建一个共享能力的去中心化生态系统。

该项目的核心是一个 Python MCP 主机（称为“远程服务”），让你可以随时安装函数和第三方 MCP 工具。

Quick Start

1. 前置条件——需要安装 Python 来运行服务，并安装 Node 来运行 Lobster（MCP 客户端）；还应安装 uv/uvx 和 node/npx，因为 MCP 似乎需要两者。

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 脚本，设置电子邮件和服务名称（最佳实践是创建一个副本“runServerFoo”，以便我们更新时可以用它替换 runServer 文件）：

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 and Bot 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, and Home 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 MCP Servers

• 让用户能够安装和管理第三方 MCP 服务工具；JSON 配置文件保存在 dynamic_servers/ 文件夹中。

• 每个 MCP 服务都需要先“启动”，以获取工具列表。

• 每个服务配置都遵循常见的 JSON 结构，包含一个 mcpServers 元素；例如，以下配置会安装一个 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

最佳实践：

• 保持简单——通常一层文件夹就足够了
• 使用描述性文件夹名称（例如，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）
• app 字段支持使用斜杠表示法表示嵌套应用（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

Bot 运行时

Bot/聊天运行时作为动态函数应用位于此仓库中：

python-server/dynamic_functions/Chat/

其中包含游戏/聊天工具、Bot 运行时、Game/ 下的静态内容，以及 Data/ 下的实时玩家状态。Atlantis MCP 服务将其视为其他动态函数应用：扫描文件夹，将装饰过的函数公开为工具，并在文件更改时重新加载。

关键文件

• python-server/dynamic_functions/Home/ — 平台自带的小型 Home 应用，用于 Lobster/Multix README 入口和文件回调。请参阅 Home README。
• python-server/dynamic_functions/Chat/ — Bot/聊天运行时应用。请参阅 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>/ 下的静态 Bot 信息（配置、提示词、图像）。已跟踪。与 Chat 分开存放，以便 Bot 可以运行在与游戏不同的机器上。
• 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-key
• 🏠 Local MCP tool call intercepted — 确认服务正在接收来自 MCP 客户端的工具调用
• MCP 握手错误通常表示客户端指向了错误的端口。默认本地 MCP 端口为 8000；请确保服务和客户端的 --port 设置一致。

与访客相关的日志行包括 "Visitor:"、"New conversation for" 和 "Injected time-gap message"。

我们的 Greenland 地形服务

我们的目标是将此系统用作 Greenland 地形服务的主要机器人基础设施（工具等）。