🚀 超现实数据库 MCP 服务器指南

本指南将为你详细介绍超现实数据库 MCP 服务器的安装、配置、使用等方面的内容，帮助你快速上手并高效使用该服务器。

🚀 快速开始

📦 安装指南

全局安装方法（推荐）

在终端中运行以下命令全局安装 SurrealDB 的 MCP 服务器：

npm install -g surrealdb-mcp-server

npx 方法（仅用于测试）

你也可以使用 npx 快速运行：

npx surrealdb-mcp-server

⚙️ 配置教程

MCP 服务器可以通过配置文件或命令行参数进行设置。以下是默认配置文件的示例：

{
  "mcpServers": {
    "surrealdb": {
      "command": "node",
      "args": ["$(npm which -g surrealdb-mcp-server)"],
      "env": {
        "SURREALDB_URL": "ws://localhost:8000",
        "SURREALDB_NS": "my_namespace",
        "SURREALDB_DB": "my_database",
        "SURREALDB_USER": "my_user",
        "SURREALDB_PASS": "my_password"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

使用环境变量

你也可以通过环境变量进行配置：

SURREALDB_URL=ws://localhost:8000
SURREALDB_NS=my_namespace
SURREALDB_DB=my_database
SURREALDB_USER=my_user
SURREALDB_PASS=my_password

🛠️ 集成到 CLI 工具

要在自定义 CLI 工具中使用 MCP 服务器，请参考以下配置：

{
  "mcpServers": {
    "surrealdb": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": ["C:\\Users\\YOUR_USERNAME\\AppData\\Roaming\\npm\\surrealdb-mcp-server.cmd"],
      "env": {
        "SURREALDB_URL": "ws://localhost:8000",
        "SURREALDB_NS": "my_namespace",
        "SURREALDB_DB": "my_database",
        "SURREALDB_USER": "my_user",
        "SURREALDB_PASS": "my_password"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

⚠️ 重要提示

在 Windows 系统中，YOUR_USERNAME 需要替换为你的实际用户名。

💻 使用示例

基础用法

情景 1: 作为独立服务器运行

surrealdb-mcp-server --port 8001 --namespace my_ns --database my_db --user my_user --password my_pass

情景 2: 集成到 Node.js 应用程序

在你的应用程序中使用 MCP 客户端：

const { Client } = require('surrealdb-mcp-client');
const client = new Client({
  url: 'ws://localhost:8000',
  ns: 'my_namespace',
  db: 'my_database',
  user: 'my_user',
  pass: 'my_password'
});

client.query('SELECT * FROM my_table').then(console.log);

高级用法

情景 3: 在生产环境中使用

在生产环境中，建议使用 Docker 进行容器化部署：

FROM node:16

WORKDIR /app

COPY package*.json ./

RUN npm install -g surrealdb-mcp-server

CMD ["surrealdb-mcp-server", "--port", "8001", "--namespace", "prod_ns", "--database", "prod_db", "--user", "prod_user", "--password", "prod_pass"]

情景 4: 扩展和负载均衡

为了提高可用性，可以使用反向代理（如 Nginx）对 MCP 服务器进行负载均衡：

upstream surrealdb_mcp {
    server localhost:8001;
    server localhost:8002;
}

server {
    listen 80;

    location / {
        proxy_pass http://surrealdb_mcp;
    }
}

🛠️ 故障排除

常见问题

"找不到模块" 错误

如果出现类似“无法找到模块'surrealdb-mcp-server'”的错误，请尝试以下步骤：

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

连接错误

如果出现“无法连接到 SurrealDB”的错误，请检查：

1. 确保 SurrealDB 服务器正在运行
2. 检查 URL、命名空间、数据库、用户和密码是否正确配置

📚 详细文档

最佳实践

性能优化

1. 使用 WebSocket 进行实时通信
2. 避免在查询中使用过多的JOIN操作
3. 定期执行数据库维护和优化

安全建议

1. 使用强密码策略
2. 启用 SSL 证书进行加密通信
3. 限制客户端连接数

附录

命令行选项

以下是 surrealdb-mcp-server 的常用命令行选项：

--port <number>      指定服务器监听的端口，默认为8000。
--namespace <string>  指定默认的命名空间。
--database <string>   指定默认的数据库。
--user <string>       指定默认的用户名。
--password <string>   指定默认的密码。

环境变量参考

以下是支持的关键环境变量：

SURREALDB_URL        服务器连接地址，默认为ws://localhost:8000。
SURREALDB_NS         默认命名空间。
SURREALDB_DB         默认数据库。
SURREALDB_USER       默认用户名。
SURREALDB_PASS       默认密码。

🤝 贡献指南

欢迎贡献！请参考我们的 GitHub 仓库 进行代码提交和问题报告。