火鸟服务器

Name: 火鸟服务器
Author: marcelofmatos

作者：marcelofmatos2 星标更新：2025-07-26

安装使用来源：spider==github.com

项目介绍

MCP Server Firebird

一个完整的MCP（模型上下文协议）服务器，用于连接外部的Firebird数据库。此服务器允许AI助手执行SQL查询、列出表并安全高效地管理与Firebird数据库的连接。

📦 目录

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

🔥 特性

✅ 完整的MCP协议 - 实现了所有MCP 2024-11-05规范
✅ 官方Firebird 3.0.10 - 客户端库包含在容器中
✅ 自包含 - 不需要主机上的卷或安装
✅ 智能诊断 - 自动检测并解决问题
✅ 外部连接 - 连接到任何远程Firebird服务器
✅ 4个MCP工具 - test_connection, execute_query, list_tables, server_status
✅ 安全性 - 非root用户，内置健康检查
✅ 国际化 - 支持多种语言（pt_BR, en_US）
✅ 广泛的测试 - 测试覆盖率>80%，包括单元测试和集成测试
✅ 代码质量 - 代码检查、自动格式化和安全检查
✅ 自动化CI/CD - 使用GitHub Actions的完整流水线
🎯 标准提示系统 - 当AI助手开始使用MCP服务器时，自动应用专家上下文
🧠 3个专业提示 - firebird_expert, firebird_performance, firebird_architecture

🌍 国际化

该服务器支持通过集中化的JSON文件实现多语言：

可用语言：葡萄牙语（pt_BR），英语（en_US）
自动配置：通过环境变量FIREBIRD_LANGUAGE或LANG
智能回退：如果未找到语言，则使用英语
本地化字符串：错误消息、日志、诊断和提示
易于扩展：添加新语言只需在i18n/目录下创建JSON文件

语言配置

# 葡萄牙语
docker run -e FIREBIRD_LANGUAGE=pt_BR ...

# 英语（默认）
docker run -e FIREBIRD_LANGUAGE=en_US ...

# 通过LANG自动设置
export LANG=pt_BR.UTF-8

🎯 标准提示系统

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

🚀 功能

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

📝 快速配置

# 默认专家模式（默认）
source .env

# 其他配置选项：
export FIREBIRD_DEFAULT_PROMPT=firebird_performance  # 侧重性能
export FIREBIRD_DEFAULT_PROMPT=firebird_architecture # 侧重管理
export FIREBIRD_DEFAULT_PROMPT_ENABLED=false         # 禁用

🎯 第一次响应示例

启用专家模式（默认）：

🔥 **FIREBIRD EXPERT MODE ACTIVE**

**环境**：localhost:3050 | 数据库：database.fdb | 用户：SYSDBA
**专家指南（中级水平）**：
✅ 提供特定于Firebird的解决方案
✅ 考虑性能影响
✅ 包含实际示例
✅ 回答语言 {lang}

---

📊 查询结果：{...}

临时禁用：

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

🚀 快速安装

前提条件

已安装Docker
访问外部的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

检查状态

# 查看容器日志
docker logs mcp-firebird

# 检查是否正在运行
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`	连接字符集	`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. test_connection

测试与Firebird数据库的连接并提供详细的诊断信息。

使用：

{
  "name": "test_connection"
}

返回：

连接状态
Firebird版本
问题诊断
特定解决方案

2. execute_query

在Firebird数据库上执行SQL查询。

使用：

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

支持：

SELECT（返回数据）
INSERT, UPDATE, DELETE（返回受影响行数）
参数化查询
自动事务

3. list_tables

列出数据库中的所有用户表。

使用：

{
  "name": "list_tables"
}

返回：

表列表
表计数器
数据库名称

4. server_status

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

使用：

{
  "name": "server_status"
}

返回：

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

🎯 可用的专业提示

服务器包括动态的专业提示：

1. firebird_expert

对Firebird数据库有深入知识的专业助手。

2. firebird_performance

专注于Firebird优化和性能的专业人士。

3. firebird_architecture

专注于Firebird架构和管理的专业人士。

🧪 开发与测试

开发环境配置

# 克隆仓库
git clone https://github.com/marcelofmatos/mcp-server-firebird
cd mcp-server-firebird

# 设置完整开发环境
make setup-dev

# 或者手动：
./scripts/setup-dev.sh

运行测试

项目具有完整的测试套件：

# 所有测试
make test-all

# 仅单元测试
make test-unit

# 集成测试
make test-integration

# 性能测试
make test-performance

# 快速执行（不包括慢速测试）
make test-fast

# 带HTML报告的测试
make test-coverage

代码质量

# 代码检查
make lint

# 自动修复问题
make lint-fix

# 代码格式化
make format

# 类型检查
make type-check

# 安全检查
make security-check

# 预提交钩子
make pre-commit

测试结构

tests/
├── unit/                    # 单元测试
│   ├── test_firebird_server.py
│   ├── test_mcp_server.py
│   ├── test_i18n.py
│   └── test_performance.py
├── integration/             # 集成测试
│   ├── test_firebird_integration.py
│   └── docker-compose-test.yml
├── conftest.py             # 共享配置
└── __init__.py

测试覆盖率

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

单元测试：150+测试覆盖所有主要功能
集成测试：与真实Firebird容器验证
性能测试：基准测试和可扩展性测试
安全测试：漏洞验证

开发命令

# 完整开发环境
make dev

# 运行本地服务器（无Docker）
make dev-server

# 监控更改
make watch

# 覆盖率报告
make coverage-report

# 性能基准测试
make benchmark

# 完全清理
make clean-all

CI/CD流水线

项目包括GitHub Actions的完整流水线：

代码检查：Ruff, Black, MyPy, Bandit
多版本测试：Python 3.8-3.12
集成测试：与真实Firebird
Docker构建：容器验证
安全扫描：Trivy和CodeQL
报告：覆盖率、基准测试、工件

🔍 故障排除

问题：容器无法启动

症状：

docker logs mcp-firebird
# 错误：FDB库不可用

解决方法：

# 重新拉取最新镜像
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')"

问题：网络连接错误

症状：

❌ 连接失败：网络错误
💡 网络问题：无法访问192.168.1.50:3050

解决方法：

检查Firebird服务器是否运行

测试网络连通性：

# 在Docker主机上
telnet 192.168.1.50 3050

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

问题：身份验证错误

症状：

❌ 连接失败：登录错误
💡 身份验证问题：无效凭据

解决方法：

检查用户名和密码：

docker run --rm \
  -e FIREBIRD_HOST=你的服务器 \
  -e FIREBIRD_PASSWORD=正确的密码 \
  ghcr.io/marcelofmatos/mcp-server-firebird:latest

确认用户存在于Firebird中
使用外部工具（如FlameRobin, IBExpert）测试连接

问题：找不到数据库

症状：

❌ 连接失败：找不到数据库
💡 数据库问题：找不到数据库文件

解决方法：

检查数据库路径：

# 路径必须是Firebird服务器上的绝对路径
-e FIREBIRD_DATABASE=/完整路径/数据库.fdb

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

问题：缺少依赖项

症状：

❌ 连接失败：libtommath.so.0: 无法打开共享对象文件

解决方法：

使用最新的官方镜像：

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

如果问题仍然存在，请在GitHub上报告问题

📊 使用示例

示例1：连接测试

# 启动容器
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

# 查看日志
docker logs firebird-test

# 预期结果：
# [MCP-FIREBIRD] ✅ 数据库连接成功 - Firebird 3.0.x

示例2：数据查询

使用MCP工具execute_query进行：

-- 列出客户
SELECT CUSTOMER_ID, COMPANY_NAME, CITY 
FROM CUSTOMERS 
WHERE COUNTRY = '巴西'
ORDER BY COMPANY_NAME

-- 计算记录数
SELECT COUNT(*) as TOTAL_CUSTOMERS 
FROM CUSTOMERS

-- 插入数据
INSERT INTO CUSTOMERS (CUSTOMER_ID, COMPANY_NAME, CITY) 
VALUES ('NEW01', '新公司', '圣保罗')

示例3：监控

# 自动重启的容器
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

# 监控健康状况
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（可选）
  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