# 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

```powershell
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](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](docs/guia/instalacao-superblt.md)
- [Anatomia do mod.txt](docs/guia/anatomia-mod-txt.md)
- [Como usar este MCP](docs/guia/como-usar-este-mcp.md)
- [Arquitetura do jogo](docs/jogo/arquitetura.md)
- [Managers](docs/jogo/managers.md)
- [Convenções](docs/referencia/convencoes.md)