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
• 🌍 Internacionalização
• 🚀 Instalação Rápida
• ⚙️ Configuração
• 🛠️ Ferramentas MCP
• 🧪 Desenvolvimento e Testes
• 🔍 Troubleshooting
• 📊 Exemplos de Uso
• 🤝 Contribuição

🔥 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

• Especificação MCP: Model Context Protocol
• Documentação Firebird: Firebird Documentation
• FDB Python Driver: python-fdb
• Pytest Documentation: Testing Framework
• Docker Best Practices: Container Guidelines

🤝 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

• Issues: GitHub Issues
• Discussões: GitHub Discussions
• Wiki: Project Wiki

Status dos Badges

---

🏷️ 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