Nsxdavid Surrealdb MCP Server

🚀 超現實數據庫 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 倉庫 進行代碼提交和問題報告。