Gigapi MCP

🚀 GigAPI MCP Server

GigAPI MCP Server 是一个用于 GigAPI 时序湖的 MCP 服务器，它能与 Claude Desktop 及其他 MCP 兼容客户端实现无缝集成。

✨ 主要特性

GigAPI 工具

• run_select_query
  • 对 GigAPI 集群执行 SQL 查询。
  • 输入：sql（字符串）：要执行的 SQL 查询；database（字符串）：要执行查询的数据库。
  • 所有查询都通过 GigAPI 的 HTTP API 以 NDJSON 格式安全执行。
• list_databases
  • 列出 GigAPI 集群上的所有数据库。
  • 输入：database（字符串）：用于 SHOW DATABASES 查询的数据库（默认为 "mydb"）。
• list_tables
  • 列出数据库中的所有表。
  • 输入：database（字符串）：数据库名称。
• get_table_schema
  • 获取特定表的架构信息。
  • 输入：database（字符串）：数据库名称；table（字符串）：表名称。
• write_data
  • 使用 InfluxDB Line Protocol 格式写入数据。
  • 输入：database（字符串）：要写入的数据库；data（字符串）：InfluxDB Line Protocol 格式的数据。
• health_check
  • 检查 GigAPI 服务器的健康状态。
• ping
  • 对 GigAPI 服务器执行 ping 操作以检查连接性。

🚀 快速开始

1. 安装 MCP 服务器

选项 A：从 PyPI 安装（推荐）

# 首次发布后，该包将在 PyPI 上可用
# 用户可以直接使用 uv 安装
uv run --with mcp-gigapi --python 3.11 mcp-gigapi --help

选项 B：从源代码安装

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

# 安装依赖
uv sync

2. 配置 Claude Desktop

1. 打开 Claude Desktop 配置文件，位置如下：

• 在 macOS 上：~/Library/Application Support/Claude/claude_desktop_config.json
• 在 Windows 上：%APPDATA%/Claude/claude_desktop_config.json

2. 添加以下配置：

公共演示配置（推荐用于测试）

{
  "mcpServers": {
    "mcp-gigapi": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-gigapi",
        "--python",
        "3.13",
        "mcp-gigapi"
      ],
      "env": {
        "GIGAPI_HOST": "gigapi.fly.dev",
        "GIGAPI_PORT": "443",
        "GIGAPI_TIMEOUT": "30",
        "GIGAPI_VERIFY_SSL": "true",
        "GIGAPI_DEFAULT_DATABASE": "mydb"
      }
    }
  }
}

本地开发配置

{
  "mcpServers": {
    "mcp-gigapi": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-gigapi",
        "--python",
        "3.13",
        "mcp-gigapi"
      ],
      "env": {
        "GIGAPI_HOST": "localhost",
        "GIGAPI_PORT": "7971",
        "GIGAPI_TIMEOUT": "30",
        "GIGAPI_VERIFY_SSL": "false",
        "GIGAPI_DEFAULT_DATABASE": "mydb"
      }
    }
  }
}

带认证的配置

{
  "mcpServers": {
    "mcp-gigapi": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-gigapi",
        "--python",
        "3.13",
        "mcp-gigapi"
      ],
      "env": {
        "GIGAPI_HOST": "your-gigapi-server",
        "GIGAPI_PORT": "7971",
        "GIGAPI_USERNAME": "your_username",
        "GIGAPI_PASSWORD": "your_password",
        "GIGAPI_TIMEOUT": "30",
        "GIGAPI_VERIFY_SSL": "true",
        "GIGAPI_DEFAULT_DATABASE": "your_database"
      }
    }
  }
}

3. 重要提示：将 uv 命令替换为 uv 可执行文件的绝对路径：

which uv  # 查找路径

4. 重启 Claude Desktop 以应用更改。

📚 详细文档

API 兼容性

此 MCP 服务器设计用于与 GigAPI 的 HTTP API 端点配合使用：

查询端点

• POST /query?db={database}&format=ndjson - 以 NDJSON 响应格式执行 SQL 查询
• 所有查询均返回 NDJSON（换行分隔的 JSON）格式，以便高效流式传输

写入端点

• POST /write?db={database} - 使用 InfluxDB Line Protocol 写入数据

管理端点

• GET /health - 健康检查
• GET /ping - 简单的 ping 操作

💻 使用示例

写入数据

使用 InfluxDB Line Protocol 格式：

curl -X POST "http://localhost:7971/write?db=mydb" --data-binary @/dev/stdin << EOF
weather,location=us-midwest,season=summer temperature=82
weather,location=us-east,season=summer temperature=80
weather,location=us-west,season=summer temperature=99
EOF

读取数据

通过 JSON POST 以 NDJSON 格式执行 SQL 查询：

curl -X POST "http://localhost:7971/query?db=mydb&format=ndjson" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT time, temperature FROM weather WHERE time >= epoch_ns('\''2025-04-24T00:00:00'\''::TIMESTAMP)"}'

显示数据库/表

# 显示数据库
curl -X POST "http://localhost:7971/query?db=mydb&format=ndjson" \
  -H "Content-Type: application/json" \
  -d '{"query": "SHOW DATABASES"}'

# 显示表
curl -X POST "http://localhost:7971/query?db=mydb&format=ndjson" \
  -H "Content-Type: application/json" \
  -d '{"query": "SHOW TABLES"}'

# 统计记录数
curl -X POST "http://localhost:7971/query?db=mydb&format=ndjson" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT count(*), avg(temperature) FROM weather"}'

🔧 技术细节

环境变量

必需变量

• GIGAPI_HOST：GigAPI 服务器的主机名
• GIGAPI_PORT：GigAPI 服务器的端口号（默认：7971）

可选变量

• GIGAPI_USERNAME 或 GIGAPI_USER：认证所需的用户名（如果需要）
• GIGAPI_PASSWORD 或 GIGAPI_PASS：认证所需的密码（如果需要）
• GIGAPI_TIMEOUT：请求超时时间（秒）（默认：30）
• GIGAPI_VERIFY_SSL：启用/禁用 SSL 证书验证（默认：true）
• GIGAPI_DEFAULT_DATABASE：查询使用的默认数据库（默认：mydb）
• GIGAPI_MCP_SERVER_TRANSPORT：设置 MCP 服务器的传输方法（默认：stdio）
• GIGAPI_ENABLED：启用/禁用 GigAPI 功能（默认：true）

示例配置

本地开发配置

# 必需变量
GIGAPI_HOST=localhost
GIGAPI_PORT=7971

# 可选：覆盖本地开发的默认值
GIGAPI_VERIFY_SSL=false
GIGAPI_TIMEOUT=60
GIGAPI_DEFAULT_DATABASE=mydb

带认证的生产配置

# 必需变量
GIGAPI_HOST=your-gigapi-server
GIGAPI_PORT=7971
GIGAPI_USERNAME=your_username
GIGAPI_PASSWORD=your_password

# 可选：生产环境设置
GIGAPI_VERIFY_SSL=true
GIGAPI_TIMEOUT=30
GIGAPI_DEFAULT_DATABASE=your_database

公共演示配置

GIGAPI_HOST=gigapi.fly.dev
GIGAPI_PORT=443
GIGAPI_VERIFY_SSL=true
GIGAPI_DEFAULT_DATABASE=mydb

数据格式

GigAPI 使用 Hive 分区，结构如下：

/data
  /mydb
    /weather
      /date=2025-04-10
        /hour=14
          *.parquet
          metadata.json

开发

设置开发环境

1. 安装依赖：

uv sync --all-extras --dev
source .venv/bin/activate

2. 在仓库根目录创建 .env 文件：

GIGAPI_HOST=localhost
GIGAPI_PORT=7971
GIGAPI_USERNAME=your_username
GIGAPI_PASSWORD=your_password
GIGAPI_TIMEOUT=30
GIGAPI_VERIFY_SSL=false
GIGAPI_DEFAULT_DATABASE=mydb

3. 使用 MCP Inspector 进行测试：

fastmcp dev mcp_gigapi/mcp_server.py

运行测试

# 运行所有测试
uv run pytest -v

# 仅运行单元测试
uv run pytest -v -m "not integration"

# 仅运行集成测试
uv run pytest -v -m "integration"

# 运行代码检查
uv run ruff check .

# 使用公共演示进行测试
python test_demo.py

使用公共演示进行测试

仓库中包含一个测试脚本，用于针对公共 GigAPI 演示验证 MCP 服务器：

python test_demo.py

这将测试：

• ✅ 健康检查和连接性
• ✅ 数据库列表（SHOW DATABASES）
• ✅ 表列表（SHOW TABLES）
• ✅ 数据查询（SELECT count(*) FROM table）
• ✅ 示例数据检索

PyPI 发布

此包在每次 GitHub 发布时自动发布到 PyPI。发布过程由 GitHub Actions 工作流处理：

• CI 工作流 (.github/workflows/ci.yml)：在拉取请求和推送到主分支时运行测试
• 发布工作流 (.github/workflows/publish.yml)：在创建发布时发布到 PyPI

对于用户

发布后，用户可以直接从 PyPI 安装该包：

# 安装并运行 MCP 服务器
uv run --with mcp-gigapi --python 3.11 mcp-gigapi

对于维护者

要发布新版本：

1. 在 pyproject.toml 中更新版本号
2. 创建 GitHub 发布
3. 工作流将自动发布到 PyPI

详细的发布说明请参阅 RELEASING.md。

🔧 故障排除

常见问题

1. 连接被拒绝：检查 GigAPI 是否正在运行，以及主机/端口是否正确
2. 认证失败：验证用户名/密码是否正确
3. SSL 证书错误：对于自签名证书，设置 GIGAPI_VERIFY_SSL=false
4. 未找到数据库：确保使用的是正确的默认数据库（通常为 "mydb"）

调试模式

通过设置日志级别启用调试日志：

import logging
logging.basicConfig(level=logging.DEBUG)

📄 许可证

本项目采用 Apache-2.0 许可证。

🤝 贡献

1. 分叉仓库
2. 创建功能分支
3. 进行更改
4. 添加测试
5. 提交拉取请求

🛠️ 支持

• 问题反馈：GitHub Issues
• 文档：GigAPI 文档