Surrealdb MCP Server

🚀 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 服務器。如果在使用過程中有任何問題或建議，請隨時聯繫我們的技術支持團隊。