Surreal Mcp

SurrealDB MCP サーバー

=� 概要

SurrealDB MCP サーバーは、Model Context Protocol を通じてデータベース操作の標準化されたインターフェースを提供し、AI アシスタントと SurrealDB の間をつなぎます。これにより、LLM は次の操作を実行できます。

• 複雑な SurrealQL クエリを実行する
• レコードに対する CRUD 操作を行う
• グラフのリレーションシップを管理する
• 一括操作を効率的に処理する
• レコード ID やグラフエッジなど、SurrealDB 独自の機能を活用する

機能

• SurrealQL の完全サポート：あらゆる SurrealQL クエリを直接実行
• 包括的な CRUD 操作：作成、読み取り、更新、削除を簡単に実行
• グラフデータベース操作：レコード間のリレーションシップを作成してたどる
• 一括操作：複数レコードを効率的に挿入
• スマートな更新：完全更新、マージ、パッチ
• 型安全：SurrealDB の RecordID を適切に処理
• コネクションプーリング：データベース接続を効率的に管理
• 複数データベースのサポート：ツール呼び出しごとにネームスペース／データベースを上書き
• 詳細なドキュメント：AI が理解しやすい詳細な docstring

=� 前提条件

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

=� インストール

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

# Run directly from PyPI (once published)
uvx surreal-mcp

# Or run from GitHub
uvx --from git+https://github.com/yourusername/surreal-mcp.git surreal-mcp

uv を使用する場合（開発におすすめ）

# Clone the repository
git clone https://github.com/yourusername/surreal-mcp.git
cd surreal-mcp

# Install dependencies
uv sync

# Run the server (multiple ways)
uv run surreal-mcp
# or
uv run python -m surreal_mcp
# or
uv run python main.py

pip を使用する場合

# Clone the repository
git clone https://github.com/yourusername/surreal-mcp.git
cd surreal-mcp

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install package
pip install -e .

# Run the server
surreal-mcp
# or
python -m surreal_mcp

� 設定

このサーバーの設定には環境変数を使用します。

必須の変数（起動時）

変数	説明	例
SURREAL_URL	SurrealDB 接続 URL	ws://localhost:8000/rpc
SURREAL_USER	データベースのユーザー名	root
SURREAL_PASSWORD	データベースのパスワード	root

任意の変数（ツール呼び出しごとに上書き可能）

変数	説明	例
SURREAL_NAMESPACE	デフォルトの SurrealDB ネームスペース	test
SURREAL_DATABASE	デフォルトの SurrealDB データベース	test

注：環境変数に SURREAL_NAMESPACE と SURREAL_DATABASE を設定していない場合は、ツール呼び出しごとに namespace と database パラメーターを指定する必要があります。

環境変数の設定

.env.example を .env にコピーし、値を更新できます。

cp .env.example .env
# Edit .env with your database credentials

または、手動で設定します。

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"
      }
    }
  }
}

=' 利用可能なツール

すべてのツールで、環境変数のデフォルト値を上書きするための namespace および database パラメーターを任意で指定できます。

1. query

複雑な操作向けに、生の SurrealQL クエリを実行します。

-- Example: Complex query with graph traversal
SELECT *, ->purchased->product FROM user WHERE age > 25

# Query with namespace/database override
query("SELECT * FROM user", namespace="production", database="main")

2. select

テーブルのすべてのレコード、または ID を指定した特定のレコードを取得します。

# Get all users
select("user")

# Get specific user
select("user", "john")

# Select from a different database
select("user", namespace="other_ns", database="other_db")

3. create

ID を自動生成して新しいレコードを作成します。

create("user", {
    "name": "Alice",
    "email": "[email protected]",
    "age": 30
})

4. update

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

update("user:john", {
    "name": "John Smith",
    "email": "[email protected]",
    "age": 31
})

5. delete

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

delete("user:john")

6. merge

ほかのフィールドに影響を与えず、特定のフィールドを部分的に更新します。

merge("user:john", {
    "email": "[email protected]",
    "verified": True
})

7. patch

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

patch("user:john", [
    {"op": "replace", "path": "/email", "value": "[email protected]"},
    {"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",           # relation name
    "product:laptop-123",  # to
    {"quantity": 1, "date": "2024-01-15"}  # relation data
)

=� 例

基本的な CRUD 操作

# Create a user
user = create("user", {"name": "Alice", "email": "[email protected]"})

# Update specific fields
merge(user["id"], {"verified": True, "last_login": "2024-01-01"})

# Query with conditions
results = query("SELECT * FROM user WHERE verified = true ORDER BY created DESC")

# Delete when done
delete(user["id"])

リレーションシップの操作

# Create entities
user = create("user", {"name": "John"})
product = create("product", {"name": "Laptop", "price": 999})

# Create relationship
relate(user["id"], "purchased", product["id"], {
    "quantity": 1,
    "total": 999,
    "date": "2024-01-15"
})

# Query relationships
purchases = query(f"SELECT * FROM {user['id']}->purchased->product")

一括操作

# Insert multiple records
products = insert("product", [
    {"name": "Laptop", "category": "Electronics", "price": 999},
    {"name": "Mouse", "category": "Electronics", "price": 29},
    {"name": "Desk", "category": "Furniture", "price": 299}
])

# Bulk update with query
query("UPDATE product SET on_sale = true WHERE category = 'Electronics'")

<<<<<<< HEAD

<� アーキテクチャ

=======

複数データベースの操作

namespace と database パラメーターを使用すると、1 つのセッションで複数のデータベースを操作できます。

# Create a record in the production database
create("user", {"name": "Alice"}, namespace="prod", database="main")

# Query from staging database
select("user", namespace="staging", database="main")

# Copy data between databases
users = select("user", namespace="staging", database="main")
for user in users["data"]:
    create("user", user, namespace="prod", database="main")

動作の概要：

シナリオ	結果
環境変数が設定されていて、パラメーターがない	プール接続を使用します（最高のパフォーマンス）
環境変数が設定されていて、パラメーターが指定されている	指定された namespace／database を使用するオーバーライド接続を使用します
環境変数が設定されておらず、パラメーターが指定されている	指定された namespace／database を使用するオーバーライド接続を使用します
環境変数が設定されておらず、パラメーターもない	明確なエラーメッセージを表示して失敗します

<� アーキテクチャ

main

サーバーは以下で構成されています：

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

>� テスト

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

前提条件

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

テストの実行

# Make sure SurrealDB is running
surreal start --user root --pass root

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=surreal_mcp

# Run specific test file
uv run pytest tests/test_tools.py

# Run specific test class or method
uv run pytest tests/test_tools.py::TestQueryTool
uv run pytest tests/test_tools.py::TestQueryTool::test_query_simple

# Run with verbose output
uv run pytest -v

# Run only tests matching a pattern
uv run pytest -k "test_create"

テスト構成

tests/
├── __init__.py
├── conftest.py              # Fixtures and test configuration
├── test_tools.py            # Tests for all MCP tools
├── test_server.py           # Tests for server configuration
└── test_namespace_override.py  # Tests for namespace/database override

テストの作成

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

• 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 ファイルをご覧ください。

=O 謝辞

• 素晴らしいグラフデータベースを提供する SurrealDB に感謝します
• MCP サーバー開発を簡素化する FastMCP に感謝します
• 標準化された AI ツールインターフェースを提供する Model Context Protocol に感謝します

=� サポート

• =� メール：[email protected]
• =� Discord：サーバーに参加
• = 問題：GitHub Issues

---