MCP多数据库连接器

┌─────────────────────────────────────────────────────┐
│                    用戶端層                           │
│  ┌──────────────┐  ┌──────────┐  ┌───────────────┐   │
│  │Claude Desktop│  │ Web 瀏覽器│  │ 第三方應用程式  │   │
│  └──────┬───────┘  └────┬─────┘  └───────┬───────┘   │
└─────────┼───────────────┼────────────────┼──────────┘
          │               │                │
┌─────────┼───────────────┼────────────────┼──────────┐
│         ▼               ▼                ▼          │
│  ┌──────────────┐  ┌─────────────────────────┐      │
│  │  MCP Server  │  │     HTTP API Server     │      │
│  │  (stdio)     │  │ (REST /api/v1 + /mcp/)  │      │
│  └──────┬───────┘  └───────────┬─────────────┘      │
│         │       服務層          │                    │
└─────────┼──────────────────────┼────────────────────┘
          │                      │
┌─────────┼──────────────────────┼────────────────────┐
│         ▼                      ▼                    │
│  ┌────────────────────────────────────────────┐     │
│  │            統一工具處理層 (Tools)             │    │
│  │  {prefix}_query / {prefix}_schema ...       │    │
│  └──────────────────────┬──────────────────────┘    │
│                         │  核心層                    │
│  ┌──────────┐  ┌────────┴────────┐  ┌────────────┐  │
│  │ 配置管理  │  │  資料庫管理器     │  │ 錯誤處理     │  │
│  │ (Config) │  │(DatabaseManager)│  │(Exceptions)│  │
│  └──────────┘  └────────┬────────┘  └────────────┘  │
└─────────────────────────┼───────────────────────────┘
                          │
┌─────────────────────────┼────────────────────────────┐
│                         ▼                            │
│  ┌──────────────┐  ┌──────────┐  ┌───────────────┐   │
│  │ Schema 快取   │  │Schema    │  │ 靜態 Schema   │   │
│  │(LFU+LRU+TTL) │  │ 內省器    │  │  載入器(JSON)  │   │
│  └──────────────┘  └────┬─────┘  └───────┬───────┘   │
│                   資料層 │                │           │
│           ┌─────────────┼────────────────┤           │
│           ▼             ▼                ▼           │
│    ┌────────────┐ ┌────────────┐ ┌───────────────┐   │
│    │ SQL Server │ │ PostgreSQL │ │schemas_config/│   │
│    │  (MSSQL)   │ │            │ │  JSON 配置檔   │   │
│    └────────────┘ └────────────┘ └───────────────┘   │
└──────────────────────────────────────────────────────┘

git clone https://github.com/Bright0505/mcp-db.git   # 衍生模組請改用各自的 repo 網址
cd mcp-db
cp .env.example .env
# 編輯 .env 填入資料庫連線資訊

{
  "mcpServers": {
    "mcp-db": {
      "command": "python",
      "args": ["-m", "server"],
      "cwd": "/path/to/mcp-db/src",
      "env": {
        "DB_TYPE": "postgresql",
        "DB_HOST": "localhost",
        "DB_NAME": "your_database",
        "DB_USER": "your_username",
        "DB_PASSWORD": "your_password",
        "DB_PORT": "5432",
        "SCHEMA_ENABLE_CACHE": "true"
      }
    }
  }
}

請測試資料庫連線狀態

# 本機開發（docker-compose.yml 是 development target，掛載 src/）
cp .env.example .env
# 編輯 .env
docker-compose up -d

# 或本地執行（需 Python >= 3.11）
pip install -e .
python -m http_server

# 健康檢查（不需 token）
curl http://localhost:8000/api/v1/health

# 測試資料庫連線（GET）
curl http://localhost:8000/api/v1/connection/test

# 執行查詢（POST；body 為 query ＋ 選填 params）
curl -X POST http://localhost:8000/api/v1/query \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT COUNT(*) AS n FROM ORDERS"}'

# 資料庫 Schema 總覽／單一表格 Schema（GET）
curl http://localhost:8000/api/v1/schema
curl http://localhost:8000/api/v1/schema/ORDERS

# 所有 REST 端點清單
curl http://localhost:8000/api/v1/tools

# 資料庫類型
DB_TYPE=postgresql        # 或 mssql

# 資料庫連線
DB_HOST=localhost
DB_NAME=your_database
DB_USER=your_username
DB_PASSWORD=your_password
DB_PORT=5432              # PostgreSQL: 5432, SQL Server: 1433

# Schema 快取（建議啟用）
SCHEMA_ENABLE_CACHE=true
SCHEMA_CACHE_TTL_MINUTES=60

# HTTP API
HTTP_HOST=0.0.0.0
HTTP_PORT=8000

# 工具前綴（工具名＝{prefix}_query 等；未設為 db）
TOOL_PREFIX=db

# 環境變數命名空間（選用）：設 ENV_PREFIX=FOO_ 後，FOO_DB_HOST 優先於 DB_HOST，
# 供同一份 .env 服務多個模組時各自隔離
# ENV_PREFIX=

# Schema 白名單嚴格模式（預設 false；true 時 schema 探索只認 tables_list.json 的表格，
# 不影響 {prefix}_query 的實際執行，見 schemas_config/README.md）
SCHEMA_STRICT_MODE=false

# 共用 Bearer token（選用、opt-in）：未設或留空＝不驗證；設了之後除 /api/v1/health 外
# 的 REST 與 /mcp/ 都要帶 Authorization: Bearer <token>。可用逗號列多把 token 以便輪替。
# token 預期由前面的閘道（nginx）持有並轉發，不是每個 client 各持一把
MCP_AUTH_TOKEN=

# 速率限制
RATE_LIMIT_DEFAULT=100/minute
RATE_LIMIT_QUERY=30/minute

schemas_config/
├── tables_list.json         # 表格白名單與全域設定
├── global_patterns.json     # 全域欄位命名模式（如 _ID$、_DATE$、_AMT$）
├── ai_enhancement.json      # AI 查詢增強（關鍵字對應、查詢模板）
├── tables/                  # 個別表格詳細配置
│   └── ORDERS.json          # 欄位說明、狀態值定義、JOIN 建議
└── examples/
    └── sample_table.json    # 完整範例參考