# MCP Server — Delphi 7 (`delphi7`)

Servidor MCP (Model Context Protocol) que expõe o índice completo da RTL + VCL do
**Delphi 7** como ferramentas para agentes de IA. O objetivo é tornar o agente mais
certeiro ao propor código Delphi 7 legado, evitando "modernizar" APIs que não
existem nessa versão (ex.: `TList<T>`, `UnicodeString`) e reduzindo tentativas
erradas (e gasto de tokens).

## O que ele faz

O servidor lê artefatos gerados offline a partir do source `.pas` do IDE (RTL + VCL)
e responde consultas precisas e rápidas:

| Consulta | Ferramenta | Exemplo de uso |
|---|---|---|
| Assinatura exata de um símbolo | `lookup_symbol` | `StrToInt`, `TCustomGrid` |
| Busca por nome incerto (substring) | `search_symbols` | `StrToIntDef`, `Copy` |
| Membros de uma classe, com herança opcional | `get_members` | `TCustomGrid (inherited=True)` |
| Interface pública compacta de uma unit | `unit_interface` | `Grids`, `SysUtils` |
| Trecho do source original ao redor de um símbolo | `source_context` | `StrToInt` |
| Lista de units indexadas, com prefixo | `list_units` | `Sy` → `SysUtils` |

Lookups são **case-insensitive** (como o próprio Delphi). Respostas são truncadas
com aviso para não estourar o contexto do agente.

## Como funciona

```
[Source RTL/VCL .pas]  →  build_index.py (offline, 1×)  →  delphi7_index/
                                                              ├─ symbols.json   (símbolo → unit + assinatura + linha)
                                                              ├─ classes.json   (hierarquia de herança)
                                                              └─ api_index/     (interface pública por unit)

[agente/opencode]  ⇄  server.py (MCP)  ⇄  delphi7_index/
```

- `build_index.py` parseia os `.pas` **uma vez** e gera os JSONs que o servidor
  carrega em memória (lookup O(1) via dict, sem dependências externas).
- `d7_intrinsics.py` traz a tabela curada dos intrínsecos do compilador
  (`Length`, `Copy`, `Inc`, `WriteLn`...) que não têm declaração em `.pas`.
- `server.py` é o processo MCP (FastMCP), expondo as 6 ferramentas.

## Estrutura do projeto

```
mcp_delphi7/
├── server.py            # servidor MCP (FastMCP), ponto de entrada
├── build_index.py       # gera o índice a partir do source .pas
├── d7_intrinsics.py     # tabela de intrínsecos do compilador
├── verifica.py          # suite de verificação (28+ checks)
├── ref/delphi7/         # fonte de referência (RTL: Rtl/, Vcl/)
├── delphi7_source/      # source original do IDE (entrada do build)
├── delphi7_index/       # índice gerado: symbols.json, classes.json, api_index/
├── delphi7_help/        # help do Delphi 7 (texto), consulta manual
└── PLANO_DELPHI7_MCP.md # planejamento/estado do projeto
```

## Requisitos

- Linux (testado) ou Windows com Python 3.x (3.14 usado no desenvolvimento)
- Python 3.10+ e `pip`

## Instalação

```bash
cd /mnt/t/projetos/mcp_servers/mcp_delphi7

# 1. ambiente virtual
python3 -m venv .venv

# 2. dependências (SDK oficial mcp + FastMCP)
.venv/bin/pip install "mcp>=1.0" fastmcp
```

## Construção do índice (offline, re-rodável)

O índice já vem gerado em `delphi7_index/`. Para reconstruí-lo (após alterar o
parser ou atualizar o source):

```bash
# usa SRC_ROOT e OUT_DIR padrão (delphi7_source → delphi7_index)
.venv/bin/python build_index.py

# ou explicitamente:
.venv/bin/python build_index.py delphi7_source delphi7_index
```

Isso produz `symbols.json` (~36k símbolos), `classes.json` (~1k classes) e a pasta
`api_index/` (um arquivo `.txt` por unit).

## Configuração

O servidor é configurado por variáveis de ambiente:

| Variável | Padrão | Descrição |
|---|---|---|
| `DELPHI7_TRANSPORT` | `stdio` | `stdio` ou `http` |
| `DELPHI7_HOST` | `0.0.0.0` | host do transporte HTTP |
| `DELPHI7_PORT` | `8747` | porta do transporte HTTP |
| `DELPHI7_INDEX` | `<projeto>/delphi7_index` | caminho do índice (opcional) |

Os paths no índice são resolvidos **relativos à raiz do projeto**, então o servidor
funciona com qualquer `cwd`.

## Executando

### stdio (padrão — usado por clientes MCP locais)

```bash
.venv/bin/python server.py
```

### HTTP

```bash
DELPHI7_TRANSPORT=http .venv/bin/python server.py
# escuta em http://0.0.0.0:8747/mcp
```

### Como serviço systemd (modo HTTP)

Exemplo de unit em `~/.config/systemd/user/delphi7-mcp.service`:

```ini
[Unit]
Description=Delphi 7 MCP server

[Service]
Environment=DELPHI7_TRANSPORT=http
WorkingDirectory=/mnt/t/projetos/mcp_servers/mcp_delphi7
ExecStart=/mnt/t/projetos/mcp_servers/mcp_delphi7/.venv/bin/python server.py
Restart=on-failure

[Install]
WantedBy=default.target
```

```bash
systemctl --user daemon-reload
systemctl --user enable --now delphi7-mcp
systemctl --user status delphi7-mcp
```

## Verificação

`verifica.py` roda o servidor em stdio e asserta as respostas esperadas para uma
série de símbolos/classes conhecidas (incl. regressões do parser). Sai com código
diferente de zero se algo falhar:

```bash
.venv/bin/python verifica.py
```

## Uso num agente (ex.: opencode)

Registre o servidor como MCP local na configuração do agente apontando para o
executável do projeto, e combine com um `AGENTS.md` que instrua a consultar as
ferramentas do `delphi7` antes de propor qualquer símbolo/API. Convenção sugerida:

> Antes de propor código/API Delphi 7, consulte as tools do servidor `delphi7`
> (`lookup_symbol`, `get_members`, `unit_interface`...). Não invente assinaturas;
> Delphi 7 é antigo e não tem generics, `UnicodeString`, etc.