🚀 SurrealDB MCP 服务器文档

SurrealDB MCP 服务器可帮助开发者更便捷地与 SurrealDB 进行交互，支持多种安装方式和灵活配置，适用于不同的开发和生产环境。

🚀 快速开始

基本配置示例

以下是 mcp.json 文件的一个基本配置示例：

{
  "mcpServers": {
    "surrealdb": {
      "command": "node",
      "args": ["$(npm prefix)/bin/surrealdb-mcp-server"],
      "env": {
        "SURREALDB_URL": "ws://localhost:8000",
        "SURREALDB_NS": "my-namespace",
        "SURREALDB_DB": "my-database",
        "SURREALDB_USER": "root",
        "SURREALDB_PASS": "password"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

配置参数说明

• command：指定运行命令的可执行文件路径。
• args：传递给命令的参数列表。
• env：设置环境变量以连接到 SurrealDB 实例。
• disabled：是否禁用此 MCP 服务器（默认为 false）。
• autoApprove：自动批准的操作列表。

✨ 主要特性

• 支持多种安装方式，如全局安装和使用 npx 直接运行。
• 可灵活配置 MCP 服务器，包括运行命令、参数、环境变量等。
• 支持批量操作请求和详细的日志记录功能。

📦 安装指南

使用 npm 安装

将 surrealdb-mcp-server 全局安装到您的系统中：

npm install -g surrealdb-mcp-server

使用 npx 运行

无需安装，直接使用 npx 运行：

npx surrealdb-mcp-server

💻 使用示例

基础用法

集成到项目中

在您的项目根目录下创建一个 mcp.json 文件，并根据需要添加多个 MCP 服务器配置。例如：

cd your-project
npm init -y # 如果还没有 package.json

然后在您的代码中引入并使用 MCP 服务器：

const { MCP } = require('surrealdb-mcp-server');
// 或者使用 ES6 模块语法：
import { MCP } from 'surrealdb-mcp-server';

创建 MCP 客户端

以下是一个简单的客户端实现示例：

const { createMCPClient } = require('surrealdb-mcp-server');

async function main() {
  const client = await createMCPClient({
    serverName: 'surrealdb',
    command: 'node',
    args: ['$(npm prefix)/bin/surrealdb-mcp-server'],
    env: {
      SURREALDB_URL: 'ws://localhost:8000',
      SURREALDB_NS: 'my-namespace',
      SURREALDB_DB: 'my-database',
      SURREALDB_USER: 'root',
      SURREALDB_PASS: 'password'
    }
  });

  // 执行数据库操作
  await client.execute('SELECT * FROM users');
}

main().catch(console.error);

高级用法

批量操作支持

MCP 服务器支持批量操作请求，您可以根据需要扩展功能：

// 在 mcp.json 中添加多个服务器配置
{
  "mcpServers": {
    "surrealdb1": { ... },
    "surrealdb2": { ... }
  }
}

日志记录

MCP 服务器支持详细的日志记录功能，您可以自定义日志输出格式和级别：

// 在 mcp.json 中添加日志配置
{
  "logging": {
    "level": "debug",
    "outputFile": "./mcp.log"
  }
}

📚 详细文档

环境变量配置

以下是需要设置的环境变量及其含义：

使用场景

本地开发

在本地项目中使用 MCP 服务器时，可以将其作为开发依赖添加到 package.json：

{
  "name": "my-project",
  "version": "1.0.0",
  "scripts": {
    "start": "surrealdb-mcp-server"
  },
  "devDependencies": {
    "surrealdb-mcp-server": "^1.0.0"
  }
}

然后运行：

npm install
npm start

生产环境

在生产环境中使用时，建议将 MCP 服务器作为服务运行。例如，在 Linux 系统上可以将其注册为系统服务。

🔧 技术细节

故障排除

常见问题

"无法找到模块" 错误

如果出现类似 "Cannot find module 'surrealdb-mcp-server'" 的错误，请尝试以下步骤：

1. 验证全局安装：npm list -g surrealdb-mcp-server
2. 检查配置中的路径是否与实际安装路径匹配
3. 重新安装：npm install -g surrealdb-mcp-server

连接问题

如果出现 "Failed to connect to SurrealDB" 错误，请检查以下内容：

1. 确保 SurrealDB 实例正在运行。
2. 检查网络连接是否正常。
3. 验证环境变量是否正确设置。

其他注意事项

权限问题

在某些系统上，您可能需要以管理员权限运行 MCP 服务器。例如，在 Windows 上使用 runas 命令：

runas /user:Administrator npm start

性能优化

为了获得最佳性能，请确保您的 SurrealDB 实例和 MCP 服务器配置在硬件资源上得到充分支持，包括足够的内存和 CPU 资源。

📄 许可证

文档中未提及许可证信息。

结束语

感谢您选择 SurrealDB MCP 服务器。如果在使用过程中有任何问题或建议，请随时联系我们的技术支持团队。