Surreal MCP

🚀 SurrealDB MCP 服務器

這是一個模型上下文協議（MCP）服務器，它能讓 AI 助手與 SurrealDB 數據庫進行交互。藉助該服務器，AI 助手可以通過標準化接口執行各類數據庫操作，為數據處理帶來便利。

🚀 快速開始

SurrealDB MCP 服務器通過模型上下文協議，為 AI 助手和 SurrealDB 之間搭建了橋樑，提供了標準化的數據庫操作接口。這使得大語言模型（LLMs）能夠：

• 執行復雜的 SurrealQL 查詢
• 對記錄進行 CRUD 操作
• 管理圖關係
• 高效處理批量操作
• 利用 SurrealDB 的獨特功能，如記錄 ID 和圖邊

✨ 主要特性

• 全面支持 SurrealQL：可直接執行任何 SurrealQL 查詢。
• 全面的 CRUD 操作：輕鬆創建、讀取、更新和刪除記錄。
• 圖數據庫操作：創建和遍歷記錄之間的關係。
• 批量操作：高效插入多條記錄。
• 智能更新：支持全量更新、合併和補丁操作。
• 類型安全：正確處理 SurrealDB 的 RecordIDs。
• 連接池：高效管理數據庫連接。
• 詳細文檔：提供豐富的文檔字符串，便於 AI 理解。

📦 安裝指南

使用 uvx（最簡單 - 無需安裝）

# 直接從 PyPI 運行（發佈後）
uvx surreal-mcp

# 或者從 GitHub 運行
uvx --from git+https://github.com/yourusername/surreal-mcp.git surreal-mcp

使用 uv（開發推薦）

# 克隆倉庫
git clone https://github.com/yourusername/surreal-mcp.git
cd surreal-mcp

# 安裝依賴
uv sync

# 運行服務器（多種方式）
uv run surreal-mcp
# 或者
uv run python -m surreal_mcp
# 或者
uv run python main.py

使用 pip

# 克隆倉庫
git clone https://github.com/yourusername/surreal-mcp.git
cd surreal-mcp

# 創建虛擬環境
python -m venv venv
source venv/bin/activate  # 在 Windows 上：venv\Scripts\activate

# 安裝包
pip install -e .

# 運行服務器
surreal-mcp
# 或者
python -m surreal_mcp

📚 詳細文檔

配置

服務器需要以下環境變量：

設置環境變量

你可以將 .env.example 複製到 .env 並更新為你的值：

cp .env.example .env
# 使用你的數據庫憑證編輯 .env

或者手動設置：

export SURREAL_URL="ws://localhost:8000/rpc"
export SURREAL_USER="root"
export SURREAL_PASSWORD="root"
export SURREAL_NAMESPACE="test"
export SURREAL_DATABASE="test"

MCP 客戶端配置

添加到你的 MCP 客戶端設置（例如，Claude Desktop）： 使用 uvx（推薦）：

{
  "mcpServers": {
    "surrealdb": {
      "command": "uvx",
      "args": ["surreal-mcp"],
      "env": {
        "SURREAL_URL": "ws://localhost:8000/rpc",
        "SURREAL_USER": "root",
        "SURREAL_PASSWORD": "root",
        "SURREAL_NAMESPACE": "test",
        "SURREAL_DATABASE": "test"
      }
    }
  }
}

使用本地安裝：

{
  "mcpServers": {
    "surrealdb": {
      "command": "uv",
      "args": ["run", "surreal-mcp"],
      "env": {
        "SURREAL_URL": "ws://localhost:8000/rpc",
        "SURREAL_USER": "root",
        "SURREAL_PASSWORD": "root",
        "SURREAL_NAMESPACE": "test",
        "SURREAL_DATABASE": "test"
      }
    }
  }
}

可用工具

1. query

執行原始 SurrealQL 查詢以進行復雜操作。

-- 示例：帶有圖遍歷的複雜查詢
SELECT *, ->purchased->product FROM user WHERE age > 25

2. select

從表中檢索所有記錄或按 ID 檢索特定記錄。

# 獲取所有用戶
select("user")

# 獲取特定用戶
select("user", "john")

3. create

創建具有自動生成 ID 的新記錄。

create("user", {
    "name": "Alice",
    "email": "alice@example.com",
    "age": 30
})

4. update

替換整個記錄內容（保留 ID 和時間戳）。

update("user:john", {
    "name": "John Smith",
    "email": "john.smith@example.com",
    "age": 31
})

5. delete

從數據庫中永久刪除記錄。

delete("user:john")

6. merge

部分更新特定字段，而不影響其他字段。

merge("user:john", {
    "email": "newemail@example.com",
    "verified": True
})

7. patch

對記錄應用 JSON Patch 操作（RFC 6902）。

patch("user:john", [
    {"op": "replace", "path": "/email", "value": "new@example.com"},
    {"op": "add", "path": "/verified", "value": True}
])

8. upsert

使用特定 ID 創建或更新記錄。

upsert("settings:global", {
    "theme": "dark",
    "language": "en"
})

9. insert

高效批量插入多條記錄。

insert("product", [
    {"name": "Laptop", "price": 999.99},
    {"name": "Mouse", "price": 29.99},
    {"name": "Keyboard", "price": 79.99}
])

10. relate

在記錄之間創建圖關係。

relate(
    "user:john",           # from
    "purchased",           # 關係名稱
    "product:laptop-123",  # to
    {"quantity": 1, "date": "2024-01-15"}  # 關係數據
)

💻 使用示例

基本 CRUD 操作

# 創建用戶
user = create("user", {"name": "Alice", "email": "alice@example.com"})

# 更新特定字段
merge(user["id"], {"verified": True, "last_login": "2024-01-01"})

# 帶條件查詢
results = query("SELECT * FROM user WHERE verified = true ORDER BY created DESC")

# 完成後刪除
delete(user["id"])

處理關係

# 創建實體
user = create("user", {"name": "John"})
product = create("product", {"name": "Laptop", "price": 999})

# 創建關係
relate(user["id"], "purchased", product["id"], {
    "quantity": 1,
    "total": 999,
    "date": "2024-01-15"
})

# 查詢關係
purchases = query(f"SELECT * FROM {user['id']}->purchased->product")

批量操作

# 插入多條記錄
products = insert("product", [
    {"name": "Laptop", "category": "Electronics", "price": 999},
    {"name": "Mouse", "category": "Electronics", "price": 29},
    {"name": "Desk", "category": "Furniture", "price": 299}
])

# 批量更新查詢
query("UPDATE product SET on_sale = true WHERE category = 'Electronics'")

🔧 技術細節

服務器採用以下技術構建：

• FastMCP：簡化的 MCP 服務器實現
• SurrealDB Python SDK：官方數據庫客戶端
• 連接池：高效管理連接
• 異步/等待：非阻塞數據庫操作

測試

項目包含使用 pytest 的全面測試套件。

前提條件

• 本地運行的 SurrealDB 實例
• 測試數據庫訪問權限（使用臨時測試數據庫）

運行測試

# 確保 SurrealDB 正在運行
surreal start --user root --pass root

# 運行所有測試
uv run pytest

# 運行並查看覆蓋率
uv run pytest --cov=surreal_mcp

# 運行特定測試文件
uv run pytest tests/test_tools.py

# 運行特定測試類或方法
uv run pytest tests/test_tools.py::TestQueryTool
uv run pytest tests/test_tools.py::TestQueryTool::test_query_simple

# 運行並輸出詳細信息
uv run pytest -v

# 僅運行匹配模式的測試
uv run pytest -k "test_create"

測試結構

tests/
├── __init__.py
├── conftest.py         # 測試夾具和配置
├── test_tools.py       # 所有 MCP 工具的測試
└── test_server.py      # 服務器配置的測試

編寫測試

測試套件包含常見測試數據的夾具：

• clean_db - 確保數據庫狀態乾淨
• sample_user_data - 示例用戶數據
• created_user - 預創建的用戶記錄
• created_product - 預創建的產品記錄

示例測試：

@pytest.mark.asyncio
async def test_create_user(clean_db, sample_user_data):
    result = await mcp._tools["create"].func(
        table="user",
        data=sample_user_data
    )
    assert result["success"] is True
    assert result["data"]["email"] == sample_user_data["email"]

貢獻

歡迎貢獻代碼！請隨時提交拉取請求。

1. 分叉倉庫
2. 創建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打開拉取請求

📄 許可證

本項目採用 MIT 許可證 - 詳情請參閱 LICENSE 文件。

致謝

• SurrealDB 提供了出色的圖數據庫
• FastMCP 簡化了 MCP 服務器開發
• Model Context Protocol 提供了標準化的 AI 工具接口

支持

• 📧 郵箱：your.email@example.com
• 💬 Discord：加入我們的服務器
• 🐛 問題：GitHub 問題