Project Atlantis

Un servidor host MCP en Python que permite la instalación dinámica de funciones y herramientas MCP de terceros.

GitHub
10
Prueba este MCPPatrocinado

Documentación

terminal

Project Atlantis

¡Miau! Idealmente, quizás quieras crear una cuenta primero en www.projectatlantis.ai y luego hacer que el bot te guíe a través de la configuración (asumiendo que todo funcione correctamente)

Básicamente tenemos un sistema distribuido estilo Linux que proporciona infraestructura de herramientas para bots. Las herramientas están organizadas en carpetas para una gestión fácil entre funciones y equipos. Los equipos pueden llamar a las funciones de otros directamente o, por supuesto, los bots pueden hacer las cosas por sí mismos. Internamente es un sistema compatible con MCP, pero soportamos hotloading, etc., sin parte de la sobrecarga torpe de actualizar constantemente las herramientas MCP.

Para comenzar, clona el repositorio, haz lo del entorno de Python, configura tus claves API como variables de entorno (OPENROUTER_API_KEY, ANTHROPIC_API_KEY, etc.) y conecta este servidor Python local al servidor principal (consulta runServer). Te damos todo el código fuente para construir tu propio chatbot de llamada a herramientas como Claude o similar. Consulta Bot/Kitty/ para ejemplos funcionales usando las APIs de OpenRouter y Anthropic: el bot descubre herramientas dinámicamente mediante búsqueda en lugar de precargarlas.

*nota: la devolución de llamada @game se ejecuta cada vez que se crea un nuevo chat

Red de Project Atlantis

Cada servidor MCP forma parte de una red colaborativa de agentes de IA y desarrolladores. Usando el Protocolo de Contexto de Modelos, la plataforma crea un ecosistema donde los agentes pueden descubrir y usar las capacidades de los demás a través de la red. Las herramientas y funciones pueden compartirse, descubrirse y coordinarse entre agentes, ya sea para desarrollo fronterizo impulsado por robots, tareas de automatización o cualquier otra aplicación. La arquitectura de red permite a los agentes encontrar y aprovechar herramientas de otros usuarios, creando un ecosistema descentralizado de capacidades compartidas.

La pieza central de este proyecto es un host MCP en Python (denominado "remoto") que te permite instalar funciones y herramientas MCP de terceros sobre la marcha.

Inicio Rápido

  1. Requisitos previos: necesitas instalar Python para el servidor y Node para Lobster (el cliente MCP); también deberías instalar uv/uvx y node/npx, ya que parece que MCP necesita ambos.

  2. Python 3.13 parece ser el más estable en este momento debido al soporte de async.

  3. Configura tu entorno virtual de Python e instala las dependencias:

cd python-server
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
  1. Edita el script runServer en la carpeta python-server y establece el correo electrónico y el nombre del servicio (en realidad es una buena práctica crear una copia "runServerFoo" que puedas reemplazar con el archivo runServer cuando hagamos actualizaciones):
python server.py  \
  --email=youremail@gmail.com  \             # 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
  1. El cliente MCP ahora se llama Lobster. Usa el puerto configurado por --port en el comando de lanzamiento del servidor Python (por ejemplo, tu script runServer). Reemplaza YOUR_SERVER_PORT a continuación con ese número; no asumas que es 8000.

Para conectarlo a Claude Code:

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

Para conectarlo a Codex:

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

El puerto predeterminado es 8000 solo cuando no se configura una anulación de puerto. Si cambias el puerto del servidor, actualiza también el argumento --port de la entrada MCP. Consulta el README del cliente Lobster para ver una plantilla de configuración JSON.

Para agregar Atlantis Open Weather para pruebas:

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

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

  2. 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

  3. Terrain and Chat come pre-installed, along with the Home app, 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.

  4. 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

design

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:

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 Terrain, 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. Your own apps and generated runtime data are separate from the bundled code and are ignored by Git by default.

Add your own app in a new subfolder. If you keep its source in a separate repository, symlink just that app into dynamic_functions/:

# After creating your app repository at ~/my-atlantis-app:
cd python-server
ln -s ~/my-atlantis-app dynamic_functions/MyApp

Mantén las carpetas incluidas en su lugar. Reemplazar o mover todo el directorio dynamic_functions/ también eliminaría las aplicaciones preinstaladas de esta copia.

Para obtener información detallada sobre cómo crear y usar funciones dinámicas, consulta la Documentación de Funciones Dinámicas.

Servidores MCP Dinámicos

  • Brinda a los usuarios la capacidad de instalar y gestionar herramientas de servidores MCP de terceros; los archivos de configuración JSON se guardan en la carpeta dynamic_servers/

  • Cada servidor MCP deberá "iniciarse" primero para obtener la lista de herramientas

  • Cada configuración de servidor sigue la estructura JSON habitual que contiene un elemento 'mcpServers'; por ejemplo, esto instala un servidor MCP de openweather:

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

El servicio MCP de clima es solo uno existente que porté a uvx. Consulta aquí

Nube

El servicio en la nube en https://www.projectatlantis.ai proporciona un centro centralizado para gestionar tus servidores remotos y compartir herramientas entre máquinas.

Organización de Aplicaciones

Las funciones dinámicas se organizan en aplicaciones usando la estructura de carpetas. Simplemente coloca tus archivos .py en subdirectorios:

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

El nombre de la carpeta ES el nombre de la aplicación. Las funciones en la carpeta Home se asignan en consecuencia.

Aplicaciones Anidadas (Subcarpetas)

Crea estructuras de aplicaciones anidadas usando subcarpetas:

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

Esto crea el nombre de la aplicación: MyApp/SubModule/Feature

Mejores Prácticas:

  • Mantenlo simple: un nivel de carpetas suele ser suficiente
  • Usa nombres de carpeta descriptivos (por ejemplo, Chat, Admin, Tools)
  • Agrupa funciones relacionadas en la misma carpeta
  • La estructura de carpetas mantiene tu código organizado y claro

Llamada a Herramientas con Términos de Búsqueda

Al llamar a herramientas, puedes usar nombres de herramientas compuestos para desambiguar funciones. Incluye solo la parte de la ruta necesaria para identificar de manera única la función.

Formato: remote_owner*remote_name*app*location*function

Principio Clave: Usa la forma más simple que se resuelva de manera única

# 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

Ejemplos:

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

Cómo funciona:

  • Campos: remote_owner*remote_name*app*location*function
  • Separa los campos con * (asterisco)
  • Omite los campos que no necesites (usa cadenas vacías: **App**func)
  • El campo de aplicación admite notación de barra para aplicaciones anidadas (MyApp/SubModule)
  • El último campo es siempre el nombre de la función
  • Sin asteriscos = trata el nombre completo como nombre de la función

Cuándo usar nombres compuestos:

  • Conflictos de nombres: Varias aplicaciones tienen funciones con el mismo nombre
  • Segmentación remota: Llama a funciones en remotos específicos desde la nube
  • Enrutamiento de ubicación: Apunta a funciones en ubicaciones físicas específicas
  • Configuraciones multiusuario: Especifica propietario y remoto en entornos compartidos

Mejor práctica: Comienza simple (update_image) y agrega contexto solo cuando sea necesario para resolver ambigüedades (**ImageTools**update_image).

Ejemplo:

# 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

Tiempo de Ejecución del Bot

El tiempo de ejecución del bot/chat vive en este repositorio como una aplicación de funciones dinámicas:

python-server/dynamic_functions/Chat/

Contiene las herramientas de juego/chat, el tiempo de ejecución del bot, el contenido estático en Game/ y el estado de jugadores en vivo en Data/. El servidor MCP de Atlantis lo trata como cualquier otra aplicación de funciones dinámicas: escanea la carpeta, expone las funciones decoradas como herramientas y las recarga cuando los archivos cambian.

Archivos Clave

  • python-server/dynamic_functions/Home/ — pequeña aplicación Home propiedad de la plataforma, utilizada para los puntos de entrada del README de Lobster/Multix y la devolución de llamada de archivos. Consulta el README de Home.
  • python-server/dynamic_functions/Chat/ — la aplicación de tiempo de ejecución del bot/chat. Consulta el README de Chat.
  • python-server/dynamic_functions/Terrain/ — herramientas de terreno rastreadas, incluido el ciclo de vida de la base de datos y el esquema; la base de datos SQLite en vivo permanece sin rastrear. Consulta el README de Terrain.
  • python-server/dynamic_functions/Chat/Game/ — contenido de juego estático: ubicaciones, escenas. Rastreado.
  • python-server/dynamic_functions/Bot/ — información estática del bot en Bot/<sid>/ (configuración, prompt, imagen). Rastreado. Se mantiene separado de Chat para que los bots puedan vivir en una máquina diferente al juego.
  • python-server/dynamic_functions/Chat/Data/ — estado en vivo por juego, claveado por game_key. No rastreado.

Solución de Problemas

Si las herramientas MCP no funcionan (por ejemplo, devolviendo errores Unknown tool), revisa primero el registro del servidor. El servidor Python escribe registros detallados en python-server/runServer.log — este archivo muestra exactamente qué está sucediendo con las llamadas a herramientas, la autenticación en la nube y las conexiones de clientes. Puede volverse grande, así que revisa las últimas ~1000 líneas:

tail -1000 python-server/runServer.log

Problemas comunes visibles en el registro:

  • ⚠️ Unexpected tool call from local client — el servidor recibió una llamada a herramienta pero no la reconoció; verifica que tus herramientas estén registradas
  • ❌ Authentication failed — las credenciales de la nube son incorrectas o la cuenta no existe; verifica tu correo electrónico/clave API
  • 🏠 Local MCP tool call intercepted — confirma que el servidor está recibiendo llamadas a herramientas del cliente MCP
  • Los errores de handshake de MCP generalmente significan que el cliente apunta al puerto incorrecto. El puerto MCP local predeterminado es 8000; asegúrate de que el --port del servidor y el --port del cliente coincidan.

Las líneas de registro relacionadas con visitantes incluyen "Visitor:", "New conversation for" y "Injected time-gap message".

Nuestro Servidor de Terreno de Groenlandia

lobby

El objetivo es usar este sistema como la infraestructura principal de bots (herramientas, etc.) para nuestro servidor de terreno de Groenlandia