Vast Db MCP

🚀 VAST 數據庫 MCP 服務器實現說明

VAST 數據庫 MCP 服務器實現了一系列數據庫資源管理和操作功能，可通過 HTTP 請求對數據庫架構、表進行查詢和操作，還提供了交互式 SQL 執行工具。同時，文檔介紹了與 AI 代理框架交互的注意事項、下一步計劃、運行說明以及使用的注意事項。

🚀 快速開始

啟動 MCP 服務

uvicorn fastapi_mcp.main:app --reload

示例請求

獲取所有架構

curl http://localhost:8000/schemas

獲取指定架構下的表

curl http://localhost:8000/schemas/my_schema/tables

獲取表元數據

curl http://localhost:8000/schemas/my_schema/tables/my_table

獲取表數據

curl http://localhost:8000/schemas/my_schema/tables/my_table/data

示例 SQL 查詢

curl -X POST "http://localhost:8000/_api" \
     -H "Content-Type: application/json" \
     -d '{"name": "vast_sql_query", "params": {"sql": "SELECT * FROM my_table LIMIT 5", "format": "json"}}'

✨ 主要特性

1. 資源

a. 列出所有架構（schemas）

• 功能：顯示數據庫中所有的架構名稱。
• 請求方式：GET /schemas
• 響應格式：JSON 數組，包含字符串類型的架構名。

b. 列出指定架構下的表（tables）

• 功能：根據提供的架構名，列出該架構下所有的表信息。
• 請求方式：GET /schemas/{schema_name}/tables
• 響應格式：JSON 數組，每個元素包含以下字段：
  • name：表的名稱
  • type：表的類型（如：BASE TABLE）
  • schema：表所屬的架構名

c. 獲取表元數據

• 功能：根據提供的架構名和表名，返回該表的詳細元數據。
• 請求方式：GET /schemas/{schema_name}/tables/{table_name}
• 響應格式：JSON 對象，包含以下字段：
  • name：表名稱
  • type：表類型
  • schema：架構名
  • columns：列信息數組，每個列對象包含：
    • name：列名
    • type：數據類型
    • nullable：是否允許為空
    • default_value：默認值（如果存在）

d. 獲取表數據

• 功能：根據提供的架構名和表名，返回該表的具體數據。
• 請求方式：GET /schemas/{schema_name}/tables/{table_name}/data
• 響應格式：JSON 數組，每個元素對應一行數據，字段與元數據中的列信息一致。

2. 工具

a. 基於查詢的交互式 SQL 執行工具

• 功能：允許通過提供 SQL 查詢語句來執行任意數據庫操作，並支持指定輸出格式。
• 名稱：vast_sql_query
• 參數：
  • sql：需要執行的 SQL 查詢字符串
  • format：輸出格式，可選值為 json 或 csv

📚 詳細文檔

與 AI 代理框架交互注意事項

提示詞/配置

• 在系統提示或配置中必須包含對可用資源和工具的描述（類似“實現的 MCP 特性”部分）。
• 由於 MCP 缺乏標準發現機制，需要顯式列出所有 URI 和工具名稱及其功能。

身份驗證處理

⚠️ 重要提示

絕對不要在發送給 LLM 的提示中包含 VAST 數據庫憑證。

• 資源請求：

  • 當 LLM 生成目標 URI 後，由 orchestrator（運行代理邏輯的代碼，而非 LLM）負責：
    • 安全加載存儲的憑證
    • 構建 headers 字典：{'X-Vast-Access-Key': '...', 'X-Vast-Secret-Key': '...'}。
    • 將 vast:// URI 映射到實際運行中的 MCP 服務器 HTTP URL（例如 http://localhost:8088/）。
    • 使用 MCP 客戶端或標準 HTTP 客戶端發送 GET 請求，同時傳遞構建的 headers。

• 工具使用：

  • 當 LLM 決定使用 vast_sql_query 工具並提供 sql 和 format 參數時，由 orchestrator 負責：
    • 安全加載存儲的憑證
    • 構建上述 headers 字典，並將其注入到工具執行函數的參數中。LLM 不應自動生成 headers。

請求構造

• LLM 需要生成正確的 URI 路徑參數和查詢參數。
• 由 LLM 生成 sql 和 format 參數用於工具調用。

響應處理

• 客戶端代理代碼需要處理不同的響應 MIME 類型（例如 text/plain, application/json, text/csv）。
• 必須檢查 HTTP 狀態碼（特別是資源請求中），以檢測錯誤（如 401, 404, 500, 503）。
• 需要從響應正文解析錯誤信息（純文本或 JSON），並可能向用戶報告或用於重試/備用操作。

下一步計劃

• 實現健壯的日誌記錄。(完成)
• 添加單元測試。(完成)
• 精細調整輸出格式。(完成 - 提供 JSON 與 CSV 選項)
• 增強錯誤處理機制。(完成)
• 完善文檔編寫與示例。(進行中)

📄 許可證

文檔未提及相關許可證信息。

🔧 注意事項

⚠️ 重要提示

• 所有 API 請求均需包含認證 headers。
• 敏感操作需進行適當的權限控制與日誌記錄。