PD2 Lua MCP

Servidor MCP (Model Context Protocol) que dá acesso pesquisável a toda a documentação e código-fonte do Payday 2 em Lua, para uso por LLMs e agentes de IA.

O que é

Em vez de escrever 450 páginas de documentação manual, este projeto baixa as 3 fontes canônicas da comunidade e expõe 7 tools MCP sobre elas. Um agente consulta sob demanda para escrever mods com precisão.

Fontes incluídas

Fonte	URL	Conteúdo
BLT Docs	github.com/JamesWilko/Payday-2-BLT-Docs	API original do BLT (21 páginas)
SuperBLT Docs	gitlab.com/znixian/payday2-superblt-docs	API moderna (XAudio, XML Tweaker, Wren) (27 páginas)
PD2 Lua Source	github.com/steam-test1/Payday-2-LuaJIT-Complete	1770 arquivos .lua descompilados do jogo

Pré-requisitos

• Python 3.10+
• git
• ripgrep (pip install ripgrep)

Instalação

pip install -r requirements.txt

# Clona as 3 fontes para data/
git clone --depth 1 https://github.com/JamesWilko/Payday-2-BLT-Docs.git data/blt-docs
git clone --depth 1 https://gitlab.com/znixian/payday2-superblt-docs.git data/superblt-docs
git clone --depth 1 https://github.com/steam-test1/Payday-2-LuaJIT-Complete.git data/pd2-lua-source

# Constrói índices (5s)
python src/index_builder.py

# (opcional) Atualiza tudo + reconstrói índices
powershell -ExecutionPolicy Bypass -File scripts/update_sources.ps1

Uso via opencode

O opencode.json registra o servidor MCP. Reinicie o opencode na pasta do projeto e as 7 tools ficam disponíveis automaticamente.

Tools disponíveis

Tool	O que faz
pd2_search_docs(query)	Busca nas 48 páginas .md (BLT + SuperBLT)
pd2_read_doc(path)	Lê uma página de doc completa
pd2_find_class(name)	Encontra classe no source + lista métodos
pd2_find_method(class, method)	Lê o corpo de um método específico
pd2_grep_source(pattern)	Busca regex em 1770 arquivos .lua
pd2_list_managers(filter)	Lista os 54 managers do jogo
pd2_get_hierarchy(class)	Cadeia de herança de uma classe

Veja docs/guia/como-usar-este-mcp.md para padrões de uso.

Estrutura

pd2-docs/
├── data/                    # 3 fontes (git clone, versionadas)
├── indexes/                 # JSONs pré-construídos
│   ├── classes-index.json   # 2269 classes
│   ├── methods-index.json   # 35723 métodos
│   ├── docs-index.json      # 48 páginas de doc
│   ├── managers-index.json  # 54 managers
│   └── requires-index.json  # grafo de dependências
├── src/
│   ├── server.py            # servidor MCP (FastMCP)
│   ├── index_builder.py     # constrói os JSONs
│   └── tools/               # (futuro: separar tools)
├── scripts/update_sources.ps1
├── docs/                    # 6 páginas curadas (conhecimento tácito)
├── opencode.json            # registra o MCP server
└── requirements.txt

Status dos índices

Após o build inicial:

• 2269 classes indexadas
• 35723 métodos indexados (com assinatura e localização)
• 48 páginas de documentação oficiais (21 BLT + 27 SuperBLT)
• 54 managers documentados
• 1770 arquivos .lua pesquisáveis via ripgrep

Documentação curada

A pasta docs/ contém páginas que nenhuma das 3 fontes explica sozinha (conhecimento tácito / arquitetura / onboarding):

• Instalação do SuperBLT
• Anatomia do mod.txt
• Como usar este MCP
• Arquitetura do jogo
• Managers
• Convenções