SurrealDB MCP Server

<div align="center"> <img src="assets/images/surreal-logo.jpg" alt="SurrealDB Logo" width="200">

一个模型上下文协议（MCP）服务器，使AI助手能够与SurrealDB数据库进行交互

</div>

概述

SurrealDB MCP服务器填补了AI助手与SurrealDB之间的空白，通过模型上下文协议提供了一个标准化的数据库操作接口。这使得大型语言模型（LLMs）能够：

• 执行复杂的SurrealQL查询
• 对记录执行CRUD操作
• 管理图关系
• 高效处理批量操作
• 使用SurrealDB的独特功能，如记录ID和图边

特性

• 完整的SurrealQL支持：直接执行任何SurrealQL查询
• 全面的CRUD操作：轻松创建、读取、更新和删除
• 图数据库操作：创建并遍历记录之间的关系
• 批量操作：高效的多记录插入
• 智能更新：全量更新、合并和补丁
• 类型安全：正确处理SurrealDB的RecordIDs
• 连接池：高效的数据库连接管理
• 详细的文档：为AI理解提供的详尽文档字符串

先决条件

• Python 3.10或更高版本
• SurrealDB实例（本地或远程）
• 兼容MCP的客户端（如Claude Desktop、MCP CLI等）

安装

使用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

配置

服务器需要以下环境变量：

变量	描述	示例
SURREAL_URL	SurrealDB连接URL	ws://localhost:8000/rpc
SURREAL_USER	数据库用户名	root
SURREAL_PASSWORD	数据库密码	root
SURREAL_NAMESPACE	SurrealDB命名空间	test
SURREAL_DATABASE	SurrealDB数据库	test

设置环境变量

你可以复制.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. 查询

执行原始的SurrealQL查询以进行复杂操作。

-- 示例：带有图遍历的复杂查询
SELECT *, ->purchased->product FROM user WHERE age > 25

2. 选择

检索表中的所有记录或通过ID获取特定记录。

# 获取所有用户
select("user")

# 获取特定用户
select("user", "john")

3. 创建

创建具有自动生成ID的新记录。

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

4. 更新

替换整个记录内容（保留ID和时间戳）。

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

5. 删除

永久从数据库中移除记录。

delete("user:john")

6. 合并

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

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

7. 补丁

对记录应用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("product", [
    {"name": "Laptop", "price": 999.99},
    {"name": "Mouse", "price": 29.99},
    {"name": "Keyboard", "price": 79.99}
])

10. 关联

在记录之间创建图关系。

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"]

贡献

欢迎贡献！请随意提交Pull Request。

1. 分叉仓库
2. 创建你的特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打开Pull Request

许可证

本项目采用MIT许可证 - 详情见LICENSE文件。

致谢

• SurrealDB 提供了出色的图数据库
• FastMCP 简化了MCP服务器开发
• 模型上下文协议 提供了标准化的AI工具接口

支持

• 邮箱：your.email@example.com
• Discord：加入我们的服务器
• 问题：GitHub问题

---

<div align="center"> 为SurrealDB和MCP社区制作 </div>