mcp-firebird

# MCP Firebird Servidor MCP (Model Context Protocol) para Firebird, com foco em exploracao segura de banco de dados, metadata, relacionamentos e consultas SQL. Esta primeira versao mira Firebird 2.5.2 e sobe em modo somente leitura por padrao. Operacoes de escrita so sao liberadas quando configuradas explicitamente. ## O que ele faz - Conecta em bancos Firebird locais ou remotos - Explora tabelas, views, colunas, indices, procedures, functions e foreign keys - Usa um schema virtual `MAIN`, ja que Firebird 2.5 nao usa schemas como SQL Server - Monta ranking por intencao com `find_entities` - Sugere caminhos de join com `suggest_join_path` - Gera plano de consulta com `plan_query` - Valida SQL antes de executar com `validate_query` - Executa `SELECT` e, opcionalmente, `INSERT`, `UPDATE`, `DELETE` e `MERGE` controlados por permissao - Mantem catalogo em memoria com cache e refresh ## Ferramentas disponiveis | Ferramenta | Descricao | |------------|-----------| | `current_connection` | Mostra status da conexao, permissao e cache sem expor host, usuario ou path do banco | | `list_databases` | Explica a limitacao de descoberta de bancos no Firebird | | `list_schemas` | Lista o schema virtual | | `list_tables` | Lista tabelas e views | | `find_tables` | Busca tabelas e views por nome | | `describe_table` | Mostra colunas, PK, FK, checks e flags | | `list_indexes` | Lista indices e colunas | | `table_stats` | Mostra contagem de linhas via `COUNT(*)` | | `find_columns` | Busca colunas por nome | | `relationship_map` | Mostra o mapa de foreign keys | | `list_procedures` | Lista procedures e functions | | `query` | Executa SQL respeitando as regras de permissao | | `permissions` | Mostra operacoes permitidas e bloqueadas | | `sample_values` | Retorna amostras distintas de valores por coluna | | `query_with_explanation` | Executa query de leitura e adiciona interpretacao curta | | `switch_database` | Troca para outro path/alias permitido | | `refresh_metadata` | Recarrega o catalogo em cache | | `health` | Mostra estado da conexao e metricas do cache | | `find_entities` | Busca entidades por linguagem natural | | `schema_summary` | Resume tabelas mais conectadas | | `explain_table` | Explica o papel provavel de uma tabela | | `suggest_join_path` | Sugere joins a partir do grafo de FKs | | `plan_query` | Gera um plano de consulta a partir de um objetivo | | `validate_query` | Analisa SQL antes da execucao | ## Requisitos - Node.js 18 ou superior - Firebird 2.5.2 acessivel localmente ou por rede - Usuario Firebird com permissao de leitura no banco ## Instalacao ```bash git clone <repo> cd mcp-firebird npm install ``` ## Configuracao MCP Exemplo de `.mcp.json`: ```json { "mcpServers": { "firebird": { "command": "node", "args": ["C:/mcp-firebird/src/index.js"], "env": { "FB_HOST": "<host-firebird>", "FB_PORT": "<porta-firebird>", "FB_DATABASE": "<path-ou-alias-do-banco>", "FB_USER": "<usuario-firebird>", "FB_PASSWORD": "<senha-firebird>", "FB_CHARSET": "UTF8" } } } } ``` `FB_DATABASE` pode ser um caminho de arquivo visto pelo servidor Firebird ou um alias configurado no servidor. ## Variaveis de ambiente | Variavel | Obrigatoria | Padrao | Descricao | |----------|-------------|--------|-----------| | `FB_HOST` | Nao | `localhost` | Host do Firebird | | `FB_PORT` | Nao | `3050` | Porta do Firebird | | `FB_DATABASE` | Sim | - | Caminho ou alias do banco | | `FB_USER` | Nao | `SYSDBA` | Usuario Firebird | | `FB_PASSWORD` | Nao | `masterkey` | Senha Firebird | | `FB_ROLE` | Nao | - | Role opcional | | `FB_CHARSET` | Nao | `UTF8` | Charset da conexao | | `FB_VIRTUAL_SCHEMA` | Nao | `MAIN` | Nome do schema virtual usado nas tools | | `FB_ALLOW_WRITE` | Nao | - | Operacoes de escrita permitidas: `INSERT`, `UPDATE`, `DELETE`, `MERGE` | | `FB_ALLOW_TABLES` | Nao | - | Restringe escrita a tabelas especificas | | `FB_ALLOW_SCHEMAS` | Nao | - | Restringe escrita ao schema virtual | | `FB_ALLOW_DATABASE_SWITCH` | Nao | - | Allowlist opcional de paths/aliases para `switch_database` | | `FB_METADATA_TTL_MS` | Nao | `300000` | TTL do cache de metadata em ms | | `FB_QUERY_TIMEOUT_MS` | Nao | `30000` | Reservado para timeout de query | | `FB_DEFAULT_MAX_ROWS` | Nao | `100` | Limite padrao de linhas para leitura | | `FB_SAMPLE_SIZE` | Nao | `5` | Quantidade padrao do `sample_values` | As variaveis `DB_*` equivalentes tambem sao aceitas como fallback para facilitar migracao. ## Modo de permissao Por padrao o servidor sobe em modo `READ-ONLY`. Sem `FB_ALLOW_WRITE`, apenas consultas de leitura sao permitidas. Exemplo liberando escrita controlada: ```json { "FB_ALLOW_WRITE": "INSERT,UPDATE", "FB_ALLOW_TABLES": "CLIENTE,PEDIDO" } ``` Operacoes permanentemente bloqueadas: `EXEC`, `EXECUTE`, `EXECUTE BLOCK`, `GRANT`, `REVOKE`, `CREATE`, `ALTER`, `DROP`, `RECREATE`, `BACKUP`, `RESTORE` ## Observacoes Firebird - Firebird nao lista todos os bancos do servidor via SQL comum; por isso `list_databases` apenas explica a configuracao atual. - As tools e logs nao exibem host, usuario, path/alias do banco ou allowlist de switch; apenas indicam se a conexao esta configurada e ativa. - `table_stats` usa `COUNT(*)`, que pode ser caro em tabelas grandes. - O schema `MAIN` e virtual; ele existe para manter as tools consistentes com outros bancos. - Metadata de checks em Firebird 2.5 e limitada via SQL de sistema; a tool lista o constraint, mas nao reconstrui todo o predicado. ## Desenvolvimento Executar o servidor: ```bash npm start ``` Rodar testes: ```bash npm test ```