mcp-neo4j-data-modeling

🔍📊 Neo4j データモデリング MCP サーバー

mcp-name: io.github.neo4j-contrib/mcp-neo4j-data-modeling

🌟 概要

Neo4j のグラフデータモデルの作成、可視化、管理に役立つツールを提供する Model Context Protocol（MCP）サーバーの実装です。このサーバーを使うと、ノード、リレーションシップ、プロパティを定義して、インタラクティブに可視化できるグラフデータベースのスキーマを設計できます。

この MCP サーバーは、以下に示すようなデータモデリングのワークフローを支援します。

• 青色のステップはエージェントが処理します
• 紫色のステップは Data Modeling MCP サーバーが処理します
• 緑色のステップはユーザーが処理します

デモ

Data Modeling と Cypher MCP サーバーを使ってデータモデルを作成し、取り込みスクリプトを生成して、ユースケースを検証する一連のデモについては、こちらの Github リポジトリをご覧ください。

🧩 コンポーネント

📦 リソース

サーバーは以下のリソースを提供します。

スキーマ

• resource://schema/node

  • Node オブジェクトの JSON スキーマを取得します
  • 返される内容：Node の構造を定義する JSON スキーマ

• resource://schema/relationship

  • Relationship オブジェクトの JSON スキーマを取得します
  • 返される内容：Relationship の構造を定義する JSON スキーマ

• resource://schema/property

  • Property オブジェクトの JSON スキーマを取得します
  • 返される内容：Property の構造を定義する JSON スキーマ

• resource://schema/data_model

  • DataModel オブジェクトの JSON スキーマを取得します
  • 返される内容：DataModel の構造を定義する JSON スキーマ

データモデルの例

• resource://examples/patient_journey_model

  • 実際の患者の診療経過を表す医療データモデルを JSON 形式で取得します
  • 返される内容：患者の受診、病状、投薬、ケアプランを追跡する JSON DataModel

• resource://examples/supply_chain_model

  • 実際のサプライチェーンのデータモデルを JSON 形式で取得します
  • 返される内容：製品、注文、在庫、場所を追跡する JSON DataModel

• resource://examples/software_dependency_model

  • 実際のソフトウェア依存関係グラフのデータモデルを JSON 形式で取得します
  • 返される内容：セキュリティ脆弱性、コミット、貢献者の分析を含むソフトウェア依存関係追跡用の JSON DataModel

• resource://examples/oil_gas_monitoring_model

  • 実際の石油・ガス設備監視データモデルを JSON 形式で取得します
  • 返される内容：石油・ガス設備、センサー、アラート、保守を対象とした産業監視用の JSON DataModel

• resource://examples/customer_360_model

  • 実際の Customer 360 データモデルを JSON 形式で取得します
  • 返される内容：アカウント、連絡先、注文、チケット、アンケートを含む顧客関係管理用の JSON DataModel

• resource://examples/fraud_aml_model

  • 実際の不正・AML データモデルを JSON 形式で取得します
  • 返される内容：顧客、取引、アラート、コンプライアンスを含む、金融不正検知およびマネーロンダリング対策用の JSON DataModel

• resource://examples/health_insurance_fraud_model

  • 実際の医療保険不正検知データモデルを JSON 形式で取得します
  • 返される内容：調査、処方、実施、受益者の関係を追跡する医療不正検知用の JSON DataModel

取り込み

• resource://neo4j_data_ingest_process
  • データモデルを使って Neo4j にデータを取り込むための推奨プロセスの詳細な説明を取得します
  • 返される内容：データ取り込みプロセスを説明する Markdown ドキュメント

🛠️ ツール

サーバーは以下の主要なツールを提供します。

✅ 検証ツール

• validate_node

  • 単一のノード構造を検証します
  • 入力：
    • node (Node)：検証するノード
    • return_validated (bool, optional)：True の場合、True の代わりに検証済みのノードオブジェクトを返します
  • 戻り値：有効な場合は True（return_validated=True の場合は検証済みの Node オブジェクト）、無効な場合は ValueError を発生させます

• validate_relationship

  • 単一のリレーションシップ構造を検証します
  • 入力：
    • relationship (Relationship)：検証するリレーションシップ
    • return_validated (bool, optional)：True の場合、True の代わりに検証済みのリレーションシップオブジェクトを返します
  • 戻り値：有効な場合は True（return_validated=True の場合は検証済みの Relationship オブジェクト）、無効な場合は ValueError を発生させます

• validate_data_model

  • データモデル全体の構造を検証します
  • 入力：
    • data_model (DataModel)：検証するデータモデル
    • return_validated (bool, optional)：True の場合、True の代わりに検証済みのデータモデルオブジェクトを返します
  • 戻り値：有効な場合は True（return_validated=True の場合は検証済みの DataModel オブジェクト）、無効な場合は ValueError を発生させます

👁️ 可視化ツール

• get_mermaid_config_str
  • データモデルを可視化するための Mermaid 図設定文字列を生成します。Mermaid に対応したツールで使用できます
  • 入力：
    • data_model (DataModel)：可視化するデータモデル
  • 戻り値：データモデルを表す Mermaid 設定文字列

🔄 インポート／エクスポートツール

これらのツールは、直感的なビジュアルインターフェースで詳細な Neo4j データモデルを作成できるグラフ描画ウェブアプリケーション、Arrows との連携機能を提供します。

• load_from_arrows_json

  • Arrows アプリの JSON 形式からデータモデルを読み込みます
  • 入力：
    • arrows_data_model_dict (dict)：Arrows アプリからエクスポートした JSON 辞書
  • 戻り値：DataModel オブジェクト

• export_to_arrows_json

  • データモデルを Arrows アプリの JSON 形式にエクスポートします
  • 入力：
    • data_model (DataModel)：エクスポートするデータモデル
  • 戻り値：Arrows アプリと互換性のある JSON 文字列

• load_from_owl_turtle

  • OWL Turtle 形式からデータモデルを読み込みます
  • 入力：
    • owl_turtle_str (str)：オントロジーを表す OWL Turtle 文字列
  • 戻り値：オントロジーから抽出したノードとリレーションシップを含む DataModel オブジェクト
  • 注：この変換では情報が失われます。OWL クラスはノードに、ObjectProperties はリレーションシップに、DatatypeProperties はノードのプロパティに変換されます。

• export_to_owl_turtle

  • データモデルを OWL Turtle 形式にエクスポートします
  • 入力：
    • data_model (DataModel)：エクスポートするデータモデル
  • 戻り値：OWL Turtle 形式でデータモデルを表す文字列
  • 注：この変換では情報が失われます。OWL は ObjectProperties にプロパティを設定できないため、リレーションシップのプロパティは保持されません。

• export_to_pydantic_models

  • データモデルを Pydantic モデルにエクスポートします
  • 入力：
    • data_model (DataModel)：エクスポートするデータモデル
  • 戻り値：ノード、リレーションシップ、データモデル全体のインポート文とモデル定義を含む、Python ファイルとしての Pydantic モデルの文字列表現

• export_to_neo4j_graphrag_pkg_schema

  • データモデルを Neo4j GraphRAG Python Package スキーマ形式にエクスポートします
  • 入力：
    • data_model (DataModel)：エクスポートするデータモデル
  • 戻り値：Neo4j GraphRAG Python Package スキーマを含む辞書

• load_from_neo4j_graphrag_pkg_schema

  • Neo4j GraphRAG Python Package スキーマ形式からデータモデルを読み込みます
  • 入力：
    • neo4j_graphrag_python_package_schema (dict)：Neo4j GraphRAG Python Package スキーマ辞書
  • 戻り値：DataModel オブジェクト

📚 サンプルデータモデルツール

一般的なユースケースやドメイン向けに、あらかじめ構築されたサンプルデータモデルを利用できます。

• list_example_data_models

  • 利用可能なすべてのサンプルデータモデルを説明付きで一覧表示します
  • 入力：なし
  • 戻り値：サンプル名、説明、ノード数／リレーションシップ数、使用手順を含む辞書

• get_example_data_model

  • 利用可能なテンプレートからサンプルのグラフデータモデルを取得します
  • 入力：
    • example_name (str)：読み込むサンプルの名前（'patient_journey'、'supply_chain'、'software_dependency'、'oil_gas_monitoring'、'customer_360'、'fraud_aml'、または 'health_insurance_fraud'）
  • 戻り値：DataModel オブジェクトと Mermaid の可視化設定を含む ExampleDataModelResponse

📝 Cypher 取り込みツール

これらのツールを使用して、データモデルに基づいた Cypher 取り込みクエリを作成できます。作成したクエリは、他の MCP サーバーやアプリケーションで Neo4j にデータを読み込むために使用できます。

• get_constraints_cypher_queries

  • データモデル内のすべてのノードに対する制約（例：一意キー）を作成する Cypher クエリを生成します
  • 入力：
    • data_model (DataModel)：制約の生成対象となるデータモデル
  • 戻り値：制約を設定する Cypher 文のリスト

• get_node_cypher_ingest_query

  • ノードレコードのリストを Neo4j に取り込む Cypher クエリを生成します
  • 入力：
    • node (Node)：ノードの定義（ラベル、キーとなるプロパティ、プロパティ）
  • 戻り値：ノードの一括取り込み用パラメーター化 Cypher クエリ（$records を使用）

• get_relationship_cypher_ingest_query

  • リレーションシップレコードのリストを Neo4j に取り込む Cypher クエリを生成します
  • 入力：
    • data_model (DataModel)：ノードとリレーションシップを含むデータモデル
    • relationship_type (str)：リレーションシップのタイプ
    • relationship_start_node_label (str)：開始ノードのラベル
    • relationship_end_node_label (str)：終了ノードのラベル
  • 戻り値：リレーションシップの一括取り込み用パラメーター化 Cypher クエリ（$records を使用）

💡 プロンプト

• create_new_data_model
  • 新しいグラフデータモデルを生成するための、構造化されたパラメーター化プロンプトを提供します
  • 入力：
    • data_context (str)：データの説明と、注目すべき具体的な詳細
    • use_cases (str)：データモデルで対応するユースケースのリスト
    • desired_nodes (str, optional)：データモデルに含めるノードラベル
    • desired_relationships (str, optional)：データモデルに含めるリレーションシップタイプ
  • 戻り値：サンプルデータと例の分析、検証を伴うデータモデルの生成、可視化を含む結果の提示という3ステップのプロセスをエージェントに案内する構造化プロンプト

🔧 Claude Desktop での使用方法

💾 リリース済みパッケージ

PyPi https://pypi.org/project/mcp-neo4j-data-modeling/ で入手できます

トランスポート方式を指定して、サーバーを claude_desktop_config.json に追加します。

"mcpServers": {
  "neo4j-data-modeling": {
    "command": "uvx",
    "args": [ "[email protected]", "--transport", "stdio" ]
  }
}

🏷️ ツールの名前空間設定

このサーバーでは、サーバーツールに名前空間を設定できます。

"mcpServers": {
  "neo4j-data-modeling-app1": {
    "command": "uvx",
    "args": [ "[email protected]", "--transport", "stdio", "--namespace", "app1" ]
  },
  "neo4j-data-modeling-app2": {
    "command": "uvx", 
    "args": [ "[email protected]", "--transport", "stdio", "--namespace", "app2" ]
  }
}

名前空間を有効にすると：

• ツール名にプレフィックスが付きます：app1-validate_node、app2-validate_node
• 各名前空間は独立して動作します

🌐 HTTP トランスポートモード

このサーバーは、ウェブベースのデプロイやマイクロサービス向けの HTTP トランスポートに対応しています。

# Basic HTTP mode (defaults: host=127.0.0.1, port=8000, path=/mcp/)
mcp-neo4j-data-modeling --transport http

# Custom HTTP configuration
mcp-neo4j-data-modeling --transport http --host 127.0.0.1 --port 8080 --path /api/mcp/

# With namespace for multi-tenant deployment
mcp-neo4j-data-modeling --transport http --namespace myapp

HTTP の設定に使用する環境変数：

export MCP_TRANSPORT=http
export NEO4J_MCP_SERVER_HOST=127.0.0.1
export NEO4J_MCP_SERVER_PORT=8080
export NEO4J_MCP_SERVER_PATH=/api/mcp/
export NEO4J_NAMESPACE=myapp
mcp-neo4j-data-modeling

🔄 トランスポートモード

このサーバーは、次の3つのトランスポートモードに対応しています。

• STDIO（デフォルト）：ローカルツールおよび Claude Desktop 向けの標準入出力
• SSE：ウェブベースのデプロイ向けの Server-Sent Events
• HTTP：最新のウェブデプロイやマイクロサービス向けの Streamable HTTP

🐳 Docker での使用

ここでは、Claude Desktop で使用するために、Docker Hub でホストされている Data Modeling MCP サーバーのイメージを stdio トランスポートで使用します。

設定の詳細：

• -i：対話モード。stdio トランスポートでの通信のため、STDIN を開いたままにします
• --rm：終了時にコンテナーを自動的に削除します（クリーンアップ）
• -p 8000:8000：ポートマッピング。ホストのポート 8000 をコンテナーのポート 8000 に割り当てます
• NEO4J_TRANSPORT=stdio：Claude Desktop との互換性のため、stdio トランスポートを使用します

{
  "mcpServers": {
    "neo4j-data-modeling": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-p",
        "8000:8000",
        "-e", "NEO4J_TRANSPORT=stdio",
        "-e", "NEO4J_NAMESPACE=myapp",
        "mcp/neo4j-data-modeling:latest"
      ]
    }
  }
}

🐳 Docker のデプロイ

Neo4j Data Modeling MCP サーバーは、リモートデプロイ用に Docker を使用してデプロイできます。Docker でデプロイする場合は、Web からアクセスできるように HTTP トランスポートを使用してください。このデプロイを Claude Desktop などのアプリケーションと統合するには、MCP 設定で mcp-remote などのプロキシを使用する必要があります。

📦 ビルド済みイメージの使用

docker build -t mcp-neo4j-data-modeling:latest . でローカルにビルドした後：

# Run with http transport (default for Docker)
docker run --rm -p 8000:8000 \
  -e NEO4J_TRANSPORT="http" \
  -e NEO4J_MCP_SERVER_HOST="0.0.0.0" \
  -e NEO4J_MCP_SERVER_PORT="8000" \
  -e NEO4J_MCP_SERVER_PATH="/mcp/" \
  mcp/neo4j-data-modeling:latest

# Run with security middleware for production
docker run --rm -p 8000:8000 \
  -e NEO4J_TRANSPORT="http" \
  -e NEO4J_MCP_SERVER_HOST="0.0.0.0" \
  -e NEO4J_MCP_SERVER_PORT="8000" \
  -e NEO4J_MCP_SERVER_PATH="/mcp/" \
  -e NEO4J_MCP_SERVER_ALLOWED_HOSTS="example.com,www.example.com" \
  -e NEO4J_MCP_SERVER_ALLOW_ORIGINS="https://example.com" \
  mcp/neo4j-data-modeling:latest

🔧 環境変数

変数	デフォルト	説明
NEO4J_TRANSPORT	stdio（ローカル）、http（リモート）	トランスポートプロトコル（stdio、http、または sse）
NEO4J_MCP_SERVER_HOST	127.0.0.1（ローカル）	バインドするホスト
NEO4J_MCP_SERVER_PORT	8000	HTTP/SSE トランスポート用のポート
NEO4J_MCP_SERVER_PATH	/mcp/	MCP サーバーへのアクセスパス
NEO4J_NAMESPACE	(空 - プレフィックスなし)	ツール名の名前空間プレフィックス（例：myapp-validate_node）
NEO4J_MCP_SERVER_ALLOW_ORIGINS	(空 - デフォルトで安全)	許可する CORS オリジンのカンマ区切りリスト
NEO4J_MCP_SERVER_ALLOWED_HOSTS	localhost,127.0.0.1	許可するホストのカンマ区切りリスト（DNS リバインディング保護）

🌐 レガシー Web アクセス用の SSE トランスポート

SSE トランスポート（レガシー Web クライアント用）を使用する場合、サーバーは次の HTTP エンドポイントを公開します：

# Start the server with SSE transport
docker run -d -p 8000:8000 \
  -e NEO4J_TRANSPORT="sse" \
  -e NEO4J_MCP_SERVER_HOST="0.0.0.0" \
  -e NEO4J_MCP_SERVER_PORT="8000" \
  --name neo4j-data-modeling-mcp-server \
  mcp-neo4j-data-modeling:latest

# Test the SSE endpoint
curl http://localhost:8000/sse

# Use with MCP Inspector
npx @modelcontextprotocol/inspector http://localhost:8000/sse

🚀 開発

📦 前提条件

1. uv（Universal Virtualenv）をインストールします：

# Using pip
pip install uv

# Using Homebrew on macOS
brew install uv

# Using cargo (Rust package manager)
cargo install uv

2. リポジトリをクローンし、開発環境をセットアップします：

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

# Create and activate virtual environment using uv
uv venv
source .venv/bin/activate  # On Unix/macOS
.venv\Scripts\activate     # On Windows

# Install dependencies including dev dependencies
uv pip install -e ".[dev]"

3. テストを実行します

./test.sh

🔧 開発設定

# Add the server to your claude_desktop_config.json
"mcpServers": {
  "neo4j-data-modeling": {
    "command": "uv",
    "args": [
      "--directory", "path_to_repo/src",
      "run", "mcp-neo4j-data-modeling", "--transport", "stdio"]
  }
}

🐳 Docker

Docker コンテナーをビルドして実行します：

# Build the image
docker build -t mcp/neo4j-data-modeling:latest .

# Run the container
docker run mcp/neo4j-data-modeling:latest

📄 ライセンス

この MCP サーバーは MIT License の下でライセンスされています。MIT License の利用規約に従うことを条件に、ソフトウェアを自由に使用、変更、配布できます。詳細については、プロジェクトリポジトリの LICENSE ファイルをご覧ください。