🚀 超现实数据库 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'”的错误，请尝试以下步骤：
- 验证全局安装：
npm list -g surrealdb-mcp-server - 检查配置中的路径是否与实际安装路径匹配
- 重新安装：
npm install -g surrealdb-mcp-server
连接错误
如果出现“无法连接到 SurrealDB”的错误，请检查：
- 确保 SurrealDB 服务器正在运行
- 检查 URL、命名空间、数据库、用户和密码是否正确配置
📚 详细文档
最佳实践
性能优化
- 使用 WebSocket 进行实时通信
- 避免在查询中使用过多的JOIN操作
- 定期执行数据库维护和优化
安全建议
- 使用强密码策略
- 启用 SSL 证书进行加密通信
- 限制客户端连接数
附录
命令行选项
以下是 surrealdb-mcp-server 的常用命令行选项：
--port 指定服务器监听的端口，默认为8000。
--namespace 指定默认的命名空间。
--database 指定默认的数据库。
--user 指定默认的用户名。
--password 指定默认的密码。
环境变量参考
以下是支持的关键环境变量：
SURREALDB_URL 服务器连接地址，默认为ws://localhost:8000。
SURREALDB_NS 默认命名空间。
SURREALDB_DB 默认数据库。
SURREALDB_USER 默认用户名。
SURREALDB_PASS 默认密码。
🤝 贡献指南
欢迎贡献！请参考我们的 GitHub 仓库 进行代码提交和问题报告。