nautilus-trader MCP 서버

이게 뭔가요?

LLM(Claude Code, Codex CLI 등)이 nautilus_trader에 대해 전략 코드를 작성하는 동안 두 가지 방식으로 항목을 조회할 수 있게 해주는 MCP(Model Context Protocol) 서버입니다.

• 코드 검색(index.py) -- 기호 이름으로 실제 소스(Python + Rust)를 구조적으로 검색합니다. 퍼지 텍스트/임베딩 검색이 아니라 실제 클래스/함수/구조체를 찾아 해당 docstring이나 전체 소스를 반환합니다.

• 문서 검색(rags/) -- 프로젝트의 마크다운 문서(개념, 가이드, 튜토리얼)에 대한 의미론적(임베딩 기반) 검색으로, 단일 기호 이름으로 매핑되지 않는 "어떻게 ... 하나요?" 질문을 위한 것입니다.

Related MCP server: MCPyDoc

작동 방식

• index.py는 두 개의 실제 언어 서버를 하위 프로세스로 생성하고 LSP(stdio를 통한 JSON-RPC)로 직접 통신합니다. nautilus_trader/python/nautilus_trader 아래의 Python 소스에는 pylsp를, nautilus_trader/crates 아래의 Rust 소스에는 rust-analyzer를 사용합니다. documentSymbol은 최상위 클래스/함수/구조체/impl을 찾고, hover는 docstring을 가져옵니다(Python 전용 -- 알려진 제한 사항 참조). 결과는 .code_index_cache.json에 캐시되는데, 빌드에 약 25초가 걸리기 때문입니다(대부분 약 2600개 파일에 대한 rust-analyzer).

• rags/rag_build.py는 docs/ 아래의 모든 파일을 청크로 나누고 rags/(config.json + corpus_embeddings.npy)에 저장된 dspy.retrievers.Embeddings 인덱스(Gemini 임베딩)를 빌드하며, rags/search.py가 하위 폴더로 필터링할 수 있도록 원래 폴더 구조를 기록한 shape.json도 저장합니다.

• mcp_server.py는 이 둘을 search_code, get_code_doc, get_code_source, search_docs, show_doc_keys의 5가지 MCP 도구로 연결합니다.

설정

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는 멱등적입니다. 다시 실행하면 nautilus_trader 클론, docs/ 복사본, (유료) 문서 임베딩 빌드가 이미 있으면 건너뜁니다. 다른 conda env 이름을 사용하려면 ENV_NAME=<name>을 설정하세요(실제 mcp env를 건드리지 않도록 테스트용으로 사용됨).

env 관리자는 필요하지 않습니다. uv venv && uv pip install -e .도 작동합니다. install.sh는 재현 가능한 원커맨드 설정을 위해 conda로 표준화한 것뿐입니다.

클라이언트에 등록

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

둘 다 stdio를 통해 <conda mcp env>/bin/python3 mcp_server.py를 가리키기만 하면 됩니다.

알려진 제한 사항 / TODO

• .code_index_cache.json 및 rags/{config.json,corpus_embeddings.npy,shape.json}에는 무효화가 없습니다. nautilus_trader/ 또는 docs/가 변경되면 캐시 파일을 수동으로 삭제하고 다시 실행해야 변경 사항이 반영됩니다.

• 자동화된 테스트가 없습니다. 지금까지는 모두 수동으로 검증되었습니다(새 conda env, 새 uv env, stdio를 통한 실제 MCP 클라이언트).

• nautilus_trader/가 main(고정되지 않음)에서 클론됩니다. 시간이 지나면서 변경될 수 있으며 현재 알려진 양호한 커밋/태그와 대조하는 항목은 없습니다.