MCP服务器Firebird

一个完整的模型上下文协议（MCP）服务器，用于连接到外部 Firebird 数据库。该服务器允许人工智能助手以安全高效的方式执行SQL查询，列出表格并管理与Firebird银行的连接。

📦 索引

🔥 特点
🌍 国际化
🚀 快速安装
⚙️ 配置
🛠️ MCP 工具
🧪 开发与测试
🔍 故障排除
📊 使用范例
🤝 贡献

🔥 特点

✅ 完整的 MCP 协议 - 实现所有MCP规范 2024-11-05
✅ 火鸟3.0.10正式版 - 包含在容器中的客户端库
✅ 自动内容 - 不需要主机上的卷或安装
✅ 智能诊断 自动检测和解决问题
✅ 外部连接 - 连接到任何远程 Firebird 服务器
✅ 4 MCP工具 -test_connection、execute_query、list_tables、server_status
✅ 肯定的 非 root 用户，内置健康检查
✅ 国际化 - 多语言支持（pt_BR， en_US）
✅ 全面测试 单元和集成测试的测试覆盖率 > 80%
✅ 代码质量 - Linting，自动格式化和安全检查
✅ 自动IC/CD -管道完成com GitHub操作
🎯 默认提示系统 - 当响应开始使用 MCP 服务器时自动应用专家上下文
🧠 3个专业提示 -firebird_expert，firebird_performance，firebird-architecture

🌍 国际化

服务器通过集中的JSON文件支持多种语言：

可用语言葡萄牙语（pt_BR），英语（en_US）
自动配置：通过变量 FIREBIRD_LANGUAGE 欧点 LANG
智能回归: 如果找不到语言则使用英语
本地化字符串错误消息，日志，诊断和提示
易于扩展通过在 JSON 文件中创建新语言添加 i18n/

语言设置

# 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

🎯 默认提示系统

MCP Firebird 包含一个创新的系统， 自动应用专家上下文 在需要 MCP 服务器时启动响应，无需手动配置，并改进工具的使用。

🚀 功能

🤖 自动应用交互开始时默认的 firebird_expert 上下文。
🔧 灵活配置：通过环境变量或工具参数
📊 复杂程度：基础、中级、高级
⏭️ 覆盖粒度通过工具调用禁用或更改操作

📝 快速设置

# 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

🎯 第一个答案的例子

专家模式（默认）：

🔥 **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: {...}

暂时禁用：

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

🚀 快速安装

先决条件

码头安装
访问外部 Firebird 服务器
连接信息（主机、端口、银行、用户、密码）

基本执行

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

检查状态

# Ver logs do container
docker logs mcp-firebird

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

⚙️ 配置

环境变量

变量	描述	标准	强制性
`FIREBIRD_HOST` Firebird 服务器地址 `localhost`	✅
`FIREBIRD_PORT` Firebird 服务器端口 `3050`	❌
`FIREBIRD_DATABASE` 完整的银行路线 `/path/to/database.fdb`	✅
`FIREBIRD_USER` 银行用户。 `SYSDBA`	❌
`FIREBIRD_PASSWORD`	用户密码	`masterkey`	✅
`FIREBIRD_CHARSET` 连接的Charset。 `UTF8`	❌
`FIREBIRD_LANGUAGE` 讯息的语言。 `en_US`	❌
`MCP_SERVER_NAME` MCP 服务器名称 `firebird-expert-server`	❌
`MCP_SERVER_VERSION` 服务器版本。 `1.0.0`	❌

配置示例

1. 本地服务器

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. 企业服务器

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. 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

🛠️ 可用的 MCP 工具

1.测试连接

测试与 Firebird 银行的连接并提供详细诊断。

用法：

{
  "name": "test_connection"
}

返回：

连接状态
Firebird版本
问题诊断
具体解决方案

2.execute_query

Executa查询SQL没有banco Firebird。

用法：

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

技术支持：

SELECT （返回数据）
INSERT， UPDATE， DELETE（返回受影响的行）
参数化查询
自动交易

3.列表表

列出所有银行用户表。

用法：

{
  "name": "list_tables"
}

返回：

表格列表
表格计数器
银行名称

4.服务器状态

显示 MCP 服务器和库的完整状态。

用法：

{
  "name": "server_status"
}

返回：

FDB 和 Firebird 库状态
当前设置
连接测试
建议

🎯 专家提示可用

服务器包括动态专家提示符：

1.火鸟_专家

Firebird 专家助理，深入了解 SGBD。

2.火鸟性能

Firebird 的优化和性能专家。

3.火鸟建筑

Firebird架构和管理专家。

🧪 开发与测试

开发环境设置

# 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

运行测试

该项目有一个完整的测试套件：

# 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

代码质量

# 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

测试结构

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

测试覆盖

该项目保持测试覆盖率超过80%：

单元测试150多个测试，涵盖所有主要功能
集成测试使用真正的 Firebird 容器进行验证
性能测试：可扩展性基准和测试
安全测试：漏洞检查

开发命令

# 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管道

该项目在 GitHub Actions 中包含完整的管道：

代码检查：拉夫、黑人、MyPy、土匪
多版本测试：Python 3.8-3.12
集成测试：Com火鸟真实
构建Docker：容器检查
安全扫描：Trivy e CodeQL
报告：覆盖范围、基准、artefatos

🔍 故障排除

问题：容器无法启动

症状：

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

解决方案：

# 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')"

问题：网络连接错误

症状：

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

解决方案：

检查 Firebird 服务器是否正在运行
测试网络连接：

   # Do host Docker
   telnet 192.168.1.50 3050

检查防火墙
确认主机和端口

问题：认证错误

症状：

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

解决方案：

检查用户名和密码：

   docker run --rm \
     -e FIREBIRD_HOST=seu.servidor \
     -e FIREBIRD_PASSWORD=senha_correta \
     ghcr.io/marcelofmatos/mcp-server-firebird:latest

确认用户在 Firebird 中存在
测试与外部工具（ FlameRobin、 IBExpert）的连接

问题：找不到银行

症状：

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

解决方案：

检查银行路径：

   # Caminho deve ser absoluto no servidor Firebird
   -e FIREBIRD_DATABASE=/caminho/completo/banco.fdb

确认文件在服务器上存在
检查文件权限

问题：缺少依赖关系

症状：

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

解决方案：

使用最新的官方图像：

   docker pull ghcr.io/marcelofmatos/mcp-server-firebird:latest

请注意，报告员问题不在GitHub上

📊 使用范例

例1：连接测试

# 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

例2：数据查询

使用工具 execute_query 通过MCP段落：

-- 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')

例三：监测

# 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

示例 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

执行：

# Produção
docker-compose up -d

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

# Logs
docker-compose logs -f mcp-firebird

🔧 高级开发

建立本地

# 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

项目结构

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

Make 可用命令

# 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

📚 额外资源

MCP规格: 模型上下文协议
Firebird 文件: Firebird文档
FDB Python驱动程序: python fdb
Pytest文档: 测试框架
Docker最佳实践: 集装箱指南

🤝 贡献

欢迎捐款！请遵循我们的贡献指南：

开发流程

仓库分叉
配置本地环境:

   git clone https://github.com/seu-usuario/mcp-server-firebird
   cd mcp-server-firebird
   make setup-dev

为 feature 创建分支:

   git checkout -b feature/nova-funcionalidade

用测试开发:

   # 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

提交更改:

   git add .
   git commit -m "feat: adicionar nova funcionalidade"

推e拉请求

质量标准

测试覆盖最低80%
掉毛代码必须通过所有检查（ruff，black，mypy，bandit）
文档新功能需要记录
测试所有功能都必须进行单元测试
承诺使用：常规承诺

本地运行

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

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

🔒 安全

实施的安全实践

非 root 用户 无集装箱
漏洞扫描 com Trivy e Bandit
受审计的依赖关系 定期
未暴露的秘密 em日志
输入验证 在所有查询中
预处理语句 前置SQL注入

📄 许可证

这个项目是根据麻省理工学院许可证授权的 - 查看文件许可证为了细节。

🆘 支持

问题:
讨论:
维基: 维基工程

状态待办事项徽章

______________________________________________________________________

🏷️ 图像标签

latest 最新稳定版本
1.0.0 特定版本
main - 开发版本

# 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

______________________________________________________________________

由❤️ Firebird 和 MCP 社区

⬆ 返回顶部

MCP Server Firebird

快速接入

详细介绍

MCP服务器Firebird

📦 索引

🔥 特点

🌍 国际化

语言设置

🎯 默认提示系统

🚀 功能

📝 快速设置

🎯 第一个答案的例子

🚀 快速安装

先决条件

基本执行

检查状态

⚙️ 配置

环境变量

配置示例

1. 本地服务器

2. 企业服务器

3. VPS服务器

🛠️ 可用的 MCP 工具

1.测试连接

2.execute_query

3.列表表

4.服务器状态

🎯 专家提示可用

1.火鸟_专家

2.火鸟性能

3.火鸟建筑

🧪 开发与测试

开发环境设置

运行测试

代码质量

测试结构

测试覆盖

开发命令

CI/CD管道

🔍 故障排除

问题：容器无法启动

问题： 网络连接错误

问题： 认证错误

问题：找不到银行

问题：缺少依赖关系

📊 使用范例

例1：连接测试

例2：数据查询

例三：监测

🐳 Docker Compose

🔧 高级 开发

建立本地

项目结构

Make 可用命令

📚 额外资源

🤝 贡献

开发流程

质量标准

本地运行

🔒 安全

实施的安全实践

📄 许可证

🆘 支持

状态待办事项徽章

🏷️ 图像标签

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

问题：网络连接错误

问题：认证错误

🔧 高级开发