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 问题