Surreal MCP

🚀 SurrealDB MCP Server

SurrealDB MCP Serverは、AIアシスタントとSurrealDBデータベースをつなぐModel Context Protocol (MCP) サーバーです。これにより、AIアシスタントはSurrealDBデータベースとのやり取りを行い、様々なデータベース操作を実行できます。

🚀 クイックスタート

SurrealDB MCP Serverは、Model Context Protocolを通じてAIアシスタントとSurrealDBの間のギャップを埋め、データベース操作のための標準化されたインターフェースを提供します。これにより、LLMは以下のことが可能になります。

• 複雑なSurrealQLクエリを実行する
• レコードに対するCRUD操作を実行する
• グラフ関係を管理する
• バルク操作を効率的に処理する
• レコードIDやグラフエッジなど、SurrealDBの独自機能を利用する

✨ 主な機能

• 完全なSurrealQLサポート：任意のSurrealQLクエリを直接実行できます。
• 包括的なCRUD操作：簡単に作成、読み取り、更新、削除を行えます。
• グラフデータベース操作：レコード間の関係を作成およびトラバースできます。
• バルク操作：複数のレコードを効率的に挿入できます。
• スマートな更新：完全な更新、マージ、パッチを行えます。
• 型安全：SurrealDBのRecordIDsを適切に処理します。
• コネクションプーリング：効率的なデータベース接続管理を行います。
• 詳細なドキュメント：AIが理解しやすいように、広範なdocstringが用意されています。

📦 インストール

uvxを使用する場合（最も簡単 - インストール不要）

# PyPIから直接実行（公開後）
uvx surreal-mcp

# またはGitHubから実行
uvx --from git+https://github.com/yourusername/surreal-mcp.git surreal-mcp

uvを使用する場合（開発に推奨）

# リポジトリをクローン
git clone https://github.com/yourusername/surreal-mcp.git
cd surreal-mcp

# 依存関係をインストール
uv sync

# サーバーを起動（複数の方法）
uv run surreal-mcp
# または
uv run python -m surreal_mcp
# または
uv run python main.py

pipを使用する場合

# リポジトリをクローン
git clone https://github.com/yourusername/surreal-mcp.git
cd surreal-mcp

# 仮想環境を作成
python -m venv venv
source venv/bin/activate  # Windowsの場合は venv\Scripts\activate

# パッケージをインストール
pip install -e .

# サーバーを起動
surreal-mcp
# または
python -m surreal_mcp

📚 ドキュメント

前提条件

• Python 3.10以上
• SurrealDBインスタンス（ローカルまたはリモート）
• MCP互換クライアント（Claude Desktop、MCP CLIなど）

環境変数の設定

サーバーは以下の環境変数を必要とします。

環境変数の設定方法

.env.example を .env にコピーし、自分の値を更新することができます。

cp .env.example .env
# .envを編集してデータベースの資格情報を入力

または、手動で設定することもできます。

export SURREAL_URL="ws://localhost:8000/rpc"
export SURREAL_USER="root"
export SURREAL_PASSWORD="root"
export SURREAL_NAMESPACE="test"
export SURREAL_DATABASE="test"

MCPクライアントの設定

MCPクライアントの設定に追加します（例：Claude Desktop）。 uvxを使用する場合（推奨）

{
  "mcpServers": {
    "surrealdb": {
      "command": "uvx",
      "args": ["surreal-mcp"],
      "env": {
        "SURREAL_URL": "ws://localhost:8000/rpc",
        "SURREAL_USER": "root",
        "SURREAL_PASSWORD": "root",
        "SURREAL_NAMESPACE": "test",
        "SURREAL_DATABASE": "test"
      }
    }
  }
}

ローカルインストールを使用する場合

{
  "mcpServers": {
    "surrealdb": {
      "command": "uv",
      "args": ["run", "surreal-mcp"],
      "env": {
        "SURREAL_URL": "ws://localhost:8000/rpc",
        "SURREAL_USER": "root",
        "SURREAL_PASSWORD": "root",
        "SURREAL_NAMESPACE": "test",
        "SURREAL_DATABASE": "test"
      }
    }
  }
}

💻 使用例

基本的な使用法

利用可能なツール

1. query

複雑な操作のために生のSurrealQLクエリを実行します。

-- 例: グラフトラバーサルを含む複雑なクエリ
SELECT *, ->purchased->product FROM user WHERE age > 25

2. select

テーブルからすべてのレコードを取得するか、IDで特定のレコードを取得します。

# すべてのユーザーを取得
select("user")

# 特定のユーザーを取得
select("user", "john")

3. create

自動生成されたIDで新しいレコードを作成します。

create("user", {
    "name": "Alice",
    "email": "alice@example.com",
    "age": 30
})

4. update

レコードの内容全体を置き換えます（IDとタイムスタンプは保持されます）。

update("user:john", {
    "name": "John Smith",
    "email": "john.smith@example.com",
    "age": 31
})

5. delete

データベースからレコードを永久に削除します。

delete("user:john")

6. merge

特定のフィールドを部分的に更新し、他のフィールドに影響を与えません。

merge("user:john", {
    "email": "newemail@example.com",
    "verified": True
})

7. patch

JSON Patch操作（RFC 6902）をレコードに適用します。

patch("user:john", [
    {"op": "replace", "path": "/email", "value": "new@example.com"},
    {"op": "add", "path": "/verified", "value": True}
])

8. upsert

特定のIDでレコードを作成または更新します。

upsert("settings:global", {
    "theme": "dark",
    "language": "en"
})

9. insert

複数のレコードを効率的に一括挿入します。

insert("product", [
    {"name": "Laptop", "price": 999.99},
    {"name": "Mouse", "price": 29.99},
    {"name": "Keyboard", "price": 79.99}
])

10. relate

レコード間にグラフ関係を作成します。

relate(
    "user:john",           # from
    "purchased",           # 関係名
    "product:laptop-123",  # to
    {"quantity": 1, "date": "2024-01-15"}  # 関係データ
)

高度な使用法

基本的なCRUD操作

# ユーザーを作成
user = create("user", {"name": "Alice", "email": "alice@example.com"})

# 特定のフィールドを更新
merge(user["id"], {"verified": True, "last_login": "2024-01-01"})

# 条件付きでクエリを実行
results = query("SELECT * FROM user WHERE verified = true ORDER BY created DESC")

# 終了後に削除
delete(user["id"])

関係の操作

# エンティティを作成
user = create("user", {"name": "John"})
product = create("product", {"name": "Laptop", "price": 999})

# 関係を作成
relate(user["id"], "purchased", product["id"], {
    "quantity": 1,
    "total": 999,
    "date": "2024-01-15"
})

# 関係をクエリ
purchases = query(f"SELECT * FROM {user['id']}->purchased->product")

バルク操作

# 複数のレコードを挿入
products = insert("product", [
    {"name": "Laptop", "category": "Electronics", "price": 999},
    {"name": "Mouse", "category": "Electronics", "price": 29},
    {"name": "Desk", "category": "Furniture", "price": 299}
])

# クエリで一括更新
query("UPDATE product SET on_sale = true WHERE category = 'Electronics'")

🔧 技術詳細

サーバーは以下のもので構築されています。

• FastMCP：簡素化されたMCPサーバー実装
• SurrealDB Python SDK：公式のデータベースクライアント
• コネクションプーリング：効率的な接続管理
• Async/Await：非ブロッキングのデータベース操作

🧪 テスト

このプロジェクトには、pytestを使用した包括的なテストスイートが含まれています。

前提条件

• ローカルで実行されているSurrealDBインスタンス
• テストデータベースへのアクセス（一時的なテストデータベースを使用）

テストの実行

# SurrealDBが実行されていることを確認
surreal start --user root --pass root

# すべてのテストを実行
uv run pytest

# カバレッジを含めて実行
uv run pytest --cov=surreal_mcp

# 特定のテストファイルを実行
uv run pytest tests/test_tools.py

# 特定のテストクラスまたはメソッドを実行
uv run pytest tests/test_tools.py::TestQueryTool
uv run pytest tests/test_tools.py::TestQueryTool::test_query_simple

# 詳細な出力で実行
uv run pytest -v

# パターンに一致するテストのみを実行
uv run pytest -k "test_create"

テスト構造

tests/
├── __init__.py
├── conftest.py         # フィクスチャとテスト設定
├── test_tools.py       # すべてのMCPツールのテスト
└── test_server.py      # サーバー設定のテスト

テストの書き方

テストスイートには、一般的なテストデータのフィクスチャが含まれています。

• clean_db - クリーンなデータベース状態を保証する
• sample_user_data - サンプルのユーザーデータ
• created_user - 事前に作成されたユーザーレコード
• created_product - 事前に作成された製品レコード

テストの例：

@pytest.mark.asyncio
async def test_create_user(clean_db, sample_user_data):
    result = await mcp._tools["create"].func(
        table="user",
        data=sample_user_data
    )
    assert result["success"] is True
    assert result["data"]["email"] == sample_user_data["email"]

🤝 コントリビューション

コントリビューションは大歓迎です！プルリクエストを送信してください。

1. リポジトリをフォークする
2. 機能ブランチを作成する (git checkout -b feature/AmazingFeature)
3. 変更をコミットする (git commit -m 'Add some AmazingFeature')
4. ブランチにプッシュする (git push origin feature/AmazingFeature)
5. プルリクエストを開く

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細については LICENSE ファイルを参照してください。

🙏 謝辞

• SurrealDB - 素晴らしいグラフデータベース
• FastMCP - MCPサーバー開発の簡素化
• Model Context Protocol - 標準化されたAIツールインターフェース

🆘 サポート

• 📧 メール: your.email@example.com
• 💬 Discord: サーバーに参加
• 🐛 問題報告: GitHub Issues