nautilus-trader MCP server

Qué es esto

Un servidor MCP (Model Context Protocol) que ofrece a un LLM (Claude Code, Codex CLI, etc.) dos formas de consultar nautilus_trader mientras se escribe código de estrategia contra él:

• Búsqueda de código (index.py) — búsqueda estructural sobre el código fuente real (Python + Rust), por nombre de símbolo. No es una búsqueda difusa por texto/embeddings: encuentra la clase/función/struct real y devuelve su docstring o el código fuente completo.

• Búsqueda en documentación (rags/) — búsqueda semántica (basada en embeddings) sobre los documentos markdown del proyecto (conceptos, guías, tutoriales), para preguntas del tipo «¿cómo hago...?» que no se corresponden con un único nombre de símbolo.

Related MCP server: MCPyDoc

Cómo funciona

• index.py lanza dos servidores de lenguaje reales como subprocesos y se comunica con ellos directamente mediante LSP (JSON-RPC sobre stdio): pylsp para el código fuente de Python en nautilus_trader/python/nautilus_trader, y rust-analyzer para el código fuente de Rust en nautilus_trader/crates. documentSymbol encuentra clases/funciones/structs/impls de nivel superior; hover obtiene el docstring (solo Python — consulte Limitaciones conocidas). Los resultados se guardan en caché en .code_index_cache.json, ya que su creación cuesta ~25 s (sobre todo rust-analyzer sobre ~2600 archivos).

• rags/rag_build.py divide en fragmentos todos los archivos de docs/ y crea un índice dspy.retrievers.Embeddings (embeddings de Gemini), que se guarda en rags/ (config.json + corpus_embeddings.npy) junto con un shape.json que registra la estructura de carpetas original para que rags/search.py pueda filtrar por subcarpeta.

• mcp_server.py integra ambos en 5 herramientas MCP: search_code, get_code_doc, get_code_source, search_docs, show_doc_keys.

Configuración

git clone https://github.com/GwangPyo/NautilusTraderMCP.git
cd NautilusTraderMCP
cp .env.example .env   # fill in GEMINI_API_KEY (and OPENAI/ANTHROPIC if you use load_model)
./install.sh           # conda env "mcp" + deps, nautilus_trader clone, code index, doc index

install.sh es idempotente: si se vuelve a ejecutar, omite el clonado de nautilus_trader, la copia de docs/ y la generación (de pago) de los embeddings de documentación si ya existen. Defina ENV_NAME=<name> para usar un nombre de entorno conda distinto (se usa para pruebas, de modo que no afecte al entorno mcp real).

No se requiere un gestor de entornos: uv venv && uv pip install -e . también funciona; install.sh simplemente estandariza el uso de conda para una configuración reproducible con un solo comando.

Registro con un cliente

./add_claude.sh   # claude mcp add
./add_codex.sh    # codex mcp add

En ambos casos basta con apuntar el cliente a <conda mcp env>/bin/python3 mcp_server.py a través de stdio.

Limitaciones conocidas / TODO

• .code_index_cache.json y rags/{config.json,corpus_embeddings.npy,shape.json} no tienen invalidación: si nautilus_trader/ o docs/ cambian, hay que eliminar los archivos de caché manualmente y volver a ejecutar para que se actualicen.

• No hay pruebas automatizadas: hasta ahora todo se ha verificado manualmente (entorno conda nuevo, entorno uv nuevo, cliente MCP real a través de stdio).

• nautilus_trader/ se clona desde main (sin fijar): puede desviarse con el tiempo; actualmente nada lo verifica contra un commit/tag conocido y válido.