/mcp-server-firebird

Um servidor MCP (Model Context Protocol) completo para conectar a bancos de dados Firebird externos. Este servidor permite que assistentes de IA executem queries SQL, listem tabelas e gerenciem conexões com bancos Firebird de forma segura e eficiente.

Primary LanguagePython

MCP Server Firebird

Um servidor MCP (Model Context Protocol) completo para conectar a bancos de dados Firebird externos. Este servidor permite que assistentes de IA executem queries SQL, listem tabelas e gerenciem conexões com bancos Firebird de forma segura e eficiente.

📦 Índice

🔥 Características

  • ✅ Protocolo MCP Completo - Implementa todas as especificações do MCP 2024-11-05
  • ✅ Firebird 3.0.10 Oficial - Bibliotecas cliente incluídas no container
  • ✅ Auto-contido - Não precisa de volumes ou instalações no host
  • ✅ Diagnósticos Inteligentes - Detecta e resolve problemas automaticamente
  • ✅ Conexões Externas - Conecta a qualquer servidor Firebird remoto
  • ✅ 4 Ferramentas MCP - test_connection, execute_query, list_tables, server_status
  • ✅ Seguro - Usuário não-root, health check integrado
  • ✅ Internacionalização - Suporte a múltiplos idiomas (pt_BR, en_US)
  • ✅ Testes Abrangentes - Cobertura de testes > 80% com testes unitários e de integração
  • ✅ Qualidade de Código - Linting, formatação automática e verificações de segurança
  • ✅ CI/CD Automatizado - Pipeline completo com GitHub Actions
  • 🎯 Sistema de Prompt Padrão - Aplica automaticamente contexto expert quando as respostas iniciarem o uso do servidor MCP
  • 🧠 3 Prompts Especializados - firebird_expert, firebird_performance, firebird_architecture

🌍 Internacionalização

O servidor suporta múltiplos idiomas através de arquivos JSON centralizados:

  • Idiomas disponíveis: Português (pt_BR), Inglês (en_US)
  • Configuração automática: Via variáveis FIREBIRD_LANGUAGE ou LANG
  • Fallback inteligente: Usa inglês se idioma não encontrado
  • Strings localizadas: Mensagens de erro, logs, diagnósticos e prompts
  • Fácil expansão: Adicione novos idiomas criando arquivos JSON em i18n/

Configuração de Idioma

# Português
docker run -e FIREBIRD_LANGUAGE=pt_BR ...

# Inglês (padrão)
docker run -e FIREBIRD_LANGUAGE=en_US ...

# Automático via LANG
export LANG=pt_BR.UTF-8

🎯 Sistema de Prompt Padrão

O MCP Firebird inclui um sistema inovador que automaticamente aplica contexto expert ao iniciar as respostas caso o servidor MCP seja requisitado, sem necessidade de configuração manual e aprimorando o uso da ferramenta.

🚀 Funcionalidades

  • 🤖 Aplicação Automática: Contexto firebird_expert por padrão no início da interação.
  • 🔧 Configuração Flexível: Via environment variables ou tool parameters
  • 📊 Níveis de Complexidade: basic, intermediate, advanced
  • ⏭️ Override Granular: Desabilitar por tool call ou mudar operação

📝 Configurações Rápidas

# Configuração Expert (padrão)
source .env

# Configurações alternativas:
export FIREBIRD_DEFAULT_PROMPT=firebird_performance  # Foco em performance
export FIREBIRD_DEFAULT_PROMPT=firebird_architecture # Foco em administração
export FIREBIRD_DEFAULT_PROMPT_ENABLED=false         # Desabilitar

🎯 Exemplo de primeira resposta

Com Expert Mode (padrão):

🔥 **FIREBIRD EXPERT MODE ACTIVE**

**Environment:** localhost:3050 | DB: database.fdb | User: SYSDBA
**Expert Guidelines (intermediate level):**
✅ Provide Firebird-specific solutions
✅ Consider performance implications
✅ Include practical examples
✅ Answer language {lang}

---

📊 Query Results: {...}

Desabilitar temporariamente:

{"tool": "execute_query", "arguments": {"sql": "SELECT...", "disable_expert_mode": true}}

🚀 Instalação Rápida

Pré-requisitos

  • Docker instalado
  • Acesso a um servidor Firebird externo
  • Informações de conexão (host, porta, banco, usuário, senha)

Execução Básica

docker run -d \
  --name mcp-firebird \
  -e FIREBIRD_HOST=192.168.1.50 \
  -e FIREBIRD_DATABASE=/dados/sistema.fdb \
  -e FIREBIRD_USER=SYSDBA \
  -e FIREBIRD_PASSWORD=masterkey \
  ghcr.io/marcelofmatos/mcp-server-firebird:latest

Verificar Status

# Ver logs do container
docker logs mcp-firebird

# Verificar se está rodando
docker ps | grep mcp-firebird

⚙️ Configuração

Variáveis de Ambiente

Variável Descrição Padrão Obrigatório
FIREBIRD_HOST Endereço do servidor Firebird localhost ✅
FIREBIRD_PORT Porta do servidor Firebird 3050 ❌
FIREBIRD_DATABASE Caminho completo do banco /path/to/database.fdb ✅
FIREBIRD_USER Usuário do banco SYSDBA ❌
FIREBIRD_PASSWORD Senha do usuário masterkey ✅
FIREBIRD_CHARSET Charset da conexão UTF8 ❌
FIREBIRD_LANGUAGE Idioma das mensagens en_US ❌
MCP_SERVER_NAME Nome do servidor MCP firebird-expert-server ❌
MCP_SERVER_VERSION Versão do servidor 1.0.0 ❌

Exemplos de Configuração

1. Servidor Local

docker run -d \
  --name mcp-firebird-local \
  -e FIREBIRD_HOST=localhost \
  -e FIREBIRD_DATABASE=/var/lib/firebird/employee.fdb \
  -e FIREBIRD_PASSWORD=sua_senha \
  -e FIREBIRD_LANGUAGE=pt_BR \
  ghcr.io/marcelofmatos/mcp-server-firebird:latest

2. Servidor Corporativo

docker run -d \
  --name mcp-firebird-corp \
  -e FIREBIRD_HOST=firebird.empresa.com \
  -e FIREBIRD_PORT=3050 \
  -e FIREBIRD_DATABASE=/aplicacao/sistema.fdb \
  -e FIREBIRD_USER=APP_USER \
  -e FIREBIRD_PASSWORD=senha_segura \
  -e FIREBIRD_CHARSET=ISO8859_1 \
  ghcr.io/marcelofmatos/mcp-server-firebird:latest

3. Servidor em VPS

docker run -d \
  --name mcp-firebird-vps \
  -e FIREBIRD_HOST=10.20.30.40 \
  -e FIREBIRD_DATABASE=/home/dados/banco.fdb \
  -e FIREBIRD_USER=USUARIO_DB \
  -e FIREBIRD_PASSWORD=password123 \
  ghcr.io/marcelofmatos/mcp-server-firebird:latest

🛠️ Ferramentas MCP Disponíveis

1. test_connection

Testa a conexão com o banco Firebird e fornece diagnósticos detalhados.

Uso:

{
  "name": "test_connection"
}

Retorna:

  • Status da conexão
  • Versão do Firebird
  • Diagnósticos de problemas
  • Soluções específicas

2. execute_query

Executa queries SQL no banco Firebird.

Uso:

{
  "name": "execute_query",
  "arguments": {
    "sql": "SELECT * FROM CUSTOMERS WHERE CITY = ?",
    "params": ["São Paulo"]
  }
}

Suporta:

  • SELECT (retorna dados)
  • INSERT, UPDATE, DELETE (retorna linhas afetadas)
  • Queries parametrizadas
  • Transações automáticas

3. list_tables

Lista todas as tabelas de usuário do banco.

Uso:

{
  "name": "list_tables"
}

Retorna:

  • Lista de tabelas
  • Contador de tabelas
  • Nome do banco

4. server_status

Mostra status completo do servidor MCP e bibliotecas.

Uso:

{
  "name": "server_status"
}

Retorna:

  • Status das bibliotecas FDB e Firebird
  • Configuração atual
  • Teste de conexão
  • Recomendações

🎯 Prompts Especialistas Disponíveis

O servidor inclui prompts especialistas dinâmicos:

1. firebird_expert

Assistente especialista em Firebird com conhecimento profundo do SGBD.

2. firebird_performance

Especialista em otimização e performance para Firebird.

3. firebird_architecture

Especialista em arquitetura e administração Firebird.

🧪 Desenvolvimento e Testes

Configuração do Ambiente de Desenvolvimento

# Clonar repositório
git clone https://github.com/marcelofmatos/mcp-server-firebird
cd mcp-server-firebird

# Configurar ambiente completo
make setup-dev

# Ou manual:
./scripts/setup-dev.sh

Executando Testes

O projeto possui uma suíte completa de testes:

# Todos os testes
make test-all

# Apenas testes unitários
make test-unit

# Testes de integração
make test-integration

# Testes de performance
make test-performance

# Execução rápida (sem testes lentos)
make test-fast

# Com relatório de cobertura HTML
make test-coverage

Qualidade de Código

# Verificações de qualidade
make lint

# Corrigir problemas automaticamente
make lint-fix

# Formatação de código
make format

# Verificação de tipos
make type-check

# Verificação de segurança
make security-check

# Pre-commit hooks
make pre-commit

Estrutura de Testes

tests/
├── unit/                    # Testes unitários
│   ├── test_firebird_server.py
│   ├── test_mcp_server.py
│   ├── test_i18n.py
│   └── test_performance.py
├── integration/             # Testes de integração
│   ├── test_firebird_integration.py
│   └── docker-compose-test.yml
├── conftest.py             # Configurações compartilhadas
└── __init__.py

Cobertura de Testes

O projeto mantém cobertura de testes superior a 80%:

  • Testes unitários: 150+ testes cobrindo todas as funções principais
  • Testes de integração: Validação com containers Firebird reais
  • Testes de performance: Benchmarks e testes de escalabilidade
  • Testes de segurança: Verificação de vulnerabilidades

Comandos de Desenvolvimento

# Ambiente de desenvolvimento completo
make dev

# Executar servidor local (sem Docker)
make dev-server

# Monitorar mudanças
make watch

# Relatório de cobertura
make coverage-report

# Benchmark de performance
make benchmark

# Limpeza completa
make clean-all

CI/CD Pipeline

O projeto inclui pipeline completo no GitHub Actions:

  • Verificações de código: Ruff, Black, MyPy, Bandit
  • Testes multi-versão: Python 3.8-3.12
  • Testes de integração: Com Firebird real
  • Build Docker: Verificação de container
  • Scan de segurança: Trivy e CodeQL
  • Relatórios: Coverage, benchmarks, artefatos

🔍 Troubleshooting

Problema: Container não inicia

Sintomas:

docker logs mcp-firebird
# Erro: FDB library not available

Solução:

# Rebuildar/baixar imagem mais recente
docker pull ghcr.io/marcelofmatos/mcp-server-firebird:latest
docker run --rm -it ghcr.io/marcelofmatos/mcp-server-firebird:latest python3 -c "import fdb; print('OK')"

Problema: Erro de conexão de rede

Sintomas:

❌ Connection failed: network error
💡 NETWORK ISSUE: Cannot reach 192.168.1.50:3050

Soluções:

  1. Verificar se o servidor Firebird está rodando
  2. Testar conectividade de rede: 
    # Do host Docker
telnet 192.168.1.50 3050
  3. Verificar firewall
  4. Confirmar host e porta

Problema: Erro de autenticação

Sintomas:

❌ Connection failed: login error
💡 AUTHENTICATION ISSUE: Invalid credentials

Soluções:

  1. Verificar usuário e senha: 
    docker run --rm \
  -e FIREBIRD_HOST=seu.servidor \
  -e FIREBIRD_PASSWORD=senha_correta \
  ghcr.io/marcelofmatos/mcp-server-firebird:latest
  2. Confirmar que usuário existe no Firebird
  3. Testar conexão com ferramenta externa (FlameRobin, IBExpert)

Problema: Banco não encontrado

Sintomas:

❌ Connection failed: database not found
💡 DATABASE ISSUE: Database file not found

Soluções:

  1. Verificar caminho do banco: 
    # Caminho deve ser absoluto no servidor Firebird
-e FIREBIRD_DATABASE=/caminho/completo/banco.fdb
  2. Confirmar que arquivo existe no servidor
  3. Verificar permissões do arquivo

Problema: Dependências faltando

Sintomas:

❌ Connection failed: libtommath.so.0: cannot open shared object file

Soluções:

  1. Usar a imagem oficial mais recente: 
    docker pull ghcr.io/marcelofmatos/mcp-server-firebird:latest
  2. Se persistir, reportar issue no GitHub

📊 Exemplos de Uso

Exemplo 1: Teste de Conectividade

# Iniciar container
docker run -d \
  --name firebird-test \
  -e FIREBIRD_HOST=192.168.1.100 \
  -e FIREBIRD_DATABASE=/dados/teste.fdb \
  -e FIREBIRD_PASSWORD=123456 \
  ghcr.io/marcelofmatos/mcp-server-firebird:latest

# Verificar logs
docker logs firebird-test

# Resultado esperado:
# [MCP-FIREBIRD] ✅ Database connection OK - Firebird 3.0.x

Exemplo 2: Consulta de Dados

Use a ferramenta execute_query via MCP para:

-- Listar clientes
SELECT CUSTOMER_ID, COMPANY_NAME, CITY 
FROM CUSTOMERS 
WHERE COUNTRY = 'Brasil'
ORDER BY COMPANY_NAME

-- Contar registros
SELECT COUNT(*) as TOTAL_CUSTOMERS 
FROM CUSTOMERS

-- Inserir dados
INSERT INTO CUSTOMERS (CUSTOMER_ID, COMPANY_NAME, CITY) 
VALUES ('NEW01', 'Nova Empresa', 'São Paulo')

Exemplo 3: Monitoramento

# Container com restart automático
docker run -d \
  --name mcp-firebird-prod \
  --restart unless-stopped \
  --health-cmd="python3 -c 'import fdb; print(\"OK\")'" \
  --health-interval=30s \
  --health-timeout=10s \
  --health-retries=3 \
  -e FIREBIRD_HOST=prod.empresa.com \
  -e FIREBIRD_DATABASE=/sistema/producao.fdb \
  -e FIREBIRD_USER=SYS_USER \
  -e FIREBIRD_PASSWORD="$PROD_PASSWORD" \
  ghcr.io/marcelofmatos/mcp-server-firebird:latest

# Monitorar health
docker inspect mcp-firebird-prod | grep -A 5 Health

🐳 Docker Compose

Exemplo de docker-compose.yml:

version: '3.8'

services:
  mcp-firebird:
    image: ghcr.io/marcelofmatos/mcp-server-firebird:latest
    container_name: mcp-firebird-server
    restart: unless-stopped
    environment:
      - FIREBIRD_HOST=firebird.empresa.com
      - FIREBIRD_PORT=3050
      - FIREBIRD_DATABASE=/aplicacao/sistema.fdb
      - FIREBIRD_USER=APP_USER
      - FIREBIRD_PASSWORD=senha_segura
      - FIREBIRD_CHARSET=UTF8
      - FIREBIRD_LANGUAGE=pt_BR
    healthcheck:
      test: ["CMD", "python3", "-c", "import fdb; print('OK')"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

  # Firebird para testes (opcional)
  firebird-test:
    image: jacobalberty/firebird:v4.0
    container_name: firebird-test-db
    environment:
      - FIREBIRD_DATABASE=test.fdb
      - FIREBIRD_USER=SYSDBA
      - FIREBIRD_PASSWORD=test123
      - ISC_PASSWORD=test123
    ports:
      - "3050:3050"
    volumes:
      - firebird_data:/firebird/data
    profiles:
      - testing

volumes:
  firebird_data:
    driver: local

Executar:

# Produção
docker-compose up -d

# Com Firebird de teste
docker-compose --profile testing up -d

# Logs
docker-compose logs -f mcp-firebird

🔧 Desenvolvimento Avançado

Build Local

# Clonar repositório
git clone https://github.com/marcelofmatos/mcp-server-firebird
cd mcp-server-firebird

# Build da imagem
make build

# Testar localmente
make dev

Estrutura do Projeto

mcp-server-firebird/
├── server.py               # Servidor MCP principal
├── requirements.txt        # Dependências de produção
├── requirements-dev.txt    # Dependências de desenvolvimento
├── pyproject.toml         # Configuração do projeto
├── Dockerfile             # Container de produção
├── docker-compose.yml     # Orquestração
├── Makefile              # Comandos de automação
├── .pre-commit-config.yaml # Hooks de qualidade
├── scripts/              # Scripts auxiliares
│   ├── run-tests.sh      # Executor de testes
│   └── setup-dev.sh      # Setup de desenvolvimento
├── tests/                # Testes abrangentes
│   ├── unit/            # Testes unitários
│   ├── integration/     # Testes de integração
│   └── conftest.py      # Configurações de teste
├── i18n/                # Internacionalização
│   ├── en_US.json       # Inglês (padrão)
│   └── pt_BR.json       # Português brasileiro
├── .github/             # CI/CD
│   └── workflows/
│       ├── tests.yml    # Pipeline de testes
│       └── docker-image.yml # Build e deploy
└── README.md           # Esta documentação

Comandos Make Disponíveis

# Ambiente
make setup-dev          # Configuração completa de desenvolvimento
make install-deps       # Instalar dependências

# Testes
make test-all           # Todos os testes
make test-unit          # Testes unitários
make test-integration   # Testes de integração
make test-performance   # Testes de performance
make test-fast          # Execução rápida
make test-coverage      # Com relatório HTML

# Qualidade
make lint               # Verificações de código
make lint-fix           # Corrigir automaticamente
make format            # Formatação
make type-check        # Verificação de tipos
make security-check    # Verificação de segurança
make pre-commit        # Pre-commit hooks

# Docker
make build             # Build da imagem
make run               # Executar container
make dev               # Ambiente de desenvolvimento
make logs              # Ver logs

# Utilitários
make clean-all         # Limpeza completa
make coverage-report   # Relatório de cobertura
make benchmark         # Benchmark de performance
make health-check      # Verificar saúde do sistema

📚 Recursos Adicionais

🤝 Contribuição

Contribuições são bem-vindas! Por favor, siga nosso guia de contribuição:

Fluxo de Desenvolvimento

  1. Fork do repositório
  2. Configurar ambiente local: 
    git clone https://github.com/seu-usuario/mcp-server-firebird
cd mcp-server-firebird
make setup-dev
  3. Criar branch para feature: 
    git checkout -b feature/nova-funcionalidade
  4. Desenvolver com testes: 
    # Desenvolvimento iterativo
make test-fast      # Testes rápidos durante desenvolvimento
make lint-fix       # Correções automáticas
make test-all       # Teste completo antes de commit
  5. Commit das mudanças: 
    git add .
git commit -m "feat: adicionar nova funcionalidade"
  6. Push e Pull Request

Padrões de Qualidade

  • Cobertura de testes: Mínimo 80%
  • Linting: Código deve passar em todas as verificações (ruff, black, mypy, bandit)
  • Documentação: Novas funcionalidades devem ser documentadas
  • Testes: Toda funcionalidade deve ter testes unitários
  • Commits: Usar Conventional Commits

Executando Localmente

# Verificações antes do commit
make pre-commit

# Pipeline completo como no CI
make test-all
make lint
make build

🔒 Segurança

Práticas de Segurança Implementadas

  • Usuário não-root no container
  • Scanning de vulnerabilidades com Trivy e Bandit
  • Dependências auditadas regularmente
  • Secrets não expostos em logs
  • Validação de entrada em todas as queries
  • Prepared statements para prevenir SQL injection

📄 Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.

🆘 Suporte

Status dos Badges

Tests Docker Coverage Security License Python Firebird

🏷️ Tags da Imagem

  • latest - Versão mais recente estável
  • 1.0.0 - Versão específica
  • main - Versão de desenvolvimento
# Usar versão específica
docker pull ghcr.io/marcelofmatos/mcp-server-firebird:1.0.0

# Usar versão de desenvolvimento
docker pull ghcr.io/marcelofmatos/mcp-server-firebird:main

Feito com ❤️ para a comunidade Firebird e MCP

⬆ Voltar ao topo