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 文檔