Graphiti MCP But Working

🚀 Graphiti MCP Server - 拡張フォーク

Graphitiは、動的環境で動作するAIエージェント向けに特別に設計された、時間的な情報を考慮した知識グラフを構築およびクエリするためのフレームワークです。従来の検索強化型生成（RAG）手法とは異なり、Graphitiはユーザーの対話、構造化および非構造化の企業データ、外部情報を継続的に統合して、一貫性のあるクエリ可能なグラフに変換します。このフレームワークは、データの増分更新、効率的な検索、正確な履歴クエリをサポートし、グラフ全体の再計算を必要とせず、対話型でコンテキストを考慮したAIアプリケーションの開発に適しています。

これは、Graphiti用の拡張されたモデルコンテキストプロトコル（MCP）サーバーの実装です。MCPサーバーは、MCPプロトコルを介してGraphitiの主要な機能を公開し、AIアシスタントがGraphitiの知識グラフ機能とやり取りできるようにします。

✨ 主な機能

このフォークの主要な拡張点

この拡張バージョンには、元の実装に比べていくつかの重要な改良が含まれています。

1. 🚀 最新のGraphitiコアとの互換性 - 最新の機能と改良を備えたgraphiti-coreの現在のバージョンを使用します。
2. 🤖 GPT - 5、O1、O3モデルのサポート - OpenAIの推論モデルを適切に処理し、自動的にパラメーターを調整します（温度、推論、詳細度のパラメーターを無効にします）。
3. 🔒 トークンベースの認証 - SSEトランスポートを介した安全な公開デプロイを可能にする本番環境対応のナンストークン認証システム。
4. 📊 新しい list_group_ids ツール - 知識グラフ内のすべてのノードと関係にまたがるグループIDを発見および管理します。
5. 🛡️ 強化されたセキュリティ - 定数時間のトークン比較を行う純粋なASGIミドルウェアベースの認証を使用し、タイミング攻撃を防止します。
6. 🔇 テレメトリ制御 - プライバシー重視のデプロイメントでは自動的にテレメトリを無効にします（graphiti_coreのインポート前に設定）。
7. ⚡ 簡素化された依存関係 - セットアップとデプロイを容易にするため、Azure OpenAIの依存関係を削除しました。

Azureサポートについて

Azure OpenAIに関する注意：新しい認証ミドルウェアとの実装の競合のため、リファクタリング中にAzure OpenAIのサポートが削除されました。この拡張MCPサーバーでAzure OpenAIのサポートが必要な場合は、プルリクエストを歓迎します！元の実装は上流のGraphitiリポジトリにあります。

このフォークについて

このフォークは、最新のGraphitiコアとの互換性を維持しながら、安全な公開デプロイ用の本番環境対応機能を追加しています。OpenAI APIとの互換性と強化されたセキュリティ機能に焦点を当てています。

Graphiti MCPサーバーの主な機能

Graphiti MCPサーバーは、Graphitiの以下の主要な高レベル機能を公開します。

• エピソード管理：エピソード（テキスト、メッセージ、またはJSONデータ）の追加、取得、削除
• エンティティ管理：知識グラフ内のエンティティノードと関係の検索と管理
• 検索機能：意味論的およびハイブリッド検索を使用した事実（エッジ）とノードの概要の検索
• グループ管理：グループIDフィルタリングを使用した関連データのグループの整理と管理
• グラフメンテナンス：グラフのクリアとインデックスの再構築

🚀 クイックスタート

この拡張フォークをクローンする

git clone https://github.com/michabbb/graphiti-mcp-but-working.git
cd graphiti-mcp-but-working

または

gh repo clone michabbb/graphiti-mcp-but-working
cd graphiti-mcp-but-working

Claude Desktopやその他の stdio のみのクライアントの場合

1. このディレクトリの完全パスをメモします。

pwd

2. Graphitiの前提条件をインストールします。
3. Claude、Cursor、またはその他のMCPクライアントをします。クライアントのMCP設定ファイルの場所については、クライアントのドキュメントを参照してください。

Cursorやその他の sse 対応クライアントの場合（推奨）

1. 環境変数を設定します（.env.example を .env にコピーし、OPENAI_API_KEY を設定）
2. Docker Composeを使用してサービスを起動します。

docker compose up

3. MCPクライアントを http://localhost:8000/sse に向けます。

安全な公開デプロイの場合、ナンストークン認証を設定するには認証ガイドを参照してください。

📦 インストール

前提条件

1. Python 3.10以上がインストールされていることを確認してください。
2. 実行中のNeo4jデータベース（バージョン5.26以上が必要）
3. LLM操作に必要なOpenAI APIキー

セットアップ

1. リポジトリをクローンし、mcp_serverディレクトリに移動します。
2. uv を使用して仮想環境を作成し、依存関係をインストールします。

# まだuvがない場合はインストールする
curl -LsSf https://astral.sh/uv/install.sh | sh

# 仮想環境の作成と依存関係のインストールを一度に行う
uv sync

設定

サーバーは以下の環境変数を使用します。

これらの変数は、プロジェクトディレクトリの .env ファイルに設定できます。

サーバーの実行

uv を使用してGraphiti MCPサーバーを直接実行するには、次のコマンドを実行します。

uv run graphiti_mcp_server.py

オプション付きで実行するには、次のコマンドを使用します。

uv run graphiti_mcp_server.py --model gpt-4.1-mini --transport sse

利用可能な引数：

• --model：MODEL_NAME 環境変数を上書きします。
• --small-model：SMALL_MODEL_NAME 環境変数を上書きします。
• --temperature：LLM_TEMPERATURE 環境変数を上書きします。
• --transport：トランスポート方法を選択します（sseまたはstdio、デフォルト: sse）
• --group-id：グラフの名前空間を設定します（オプション）。指定しない場合は、デフォルトで "default" になります。
• --destroy-graph：設定すると、起動時にすべてのGraphitiグラフを破棄します。
• --use-custom-entities：事前定義された ENTITY_TYPES を使用したエンティティ抽出を有効にします。

同時実行とLLMプロバイダーの429レート制限エラー

Graphitiの取り込みパイプラインは、SEMAPHORE_LIMIT 環境変数によって制御される高い同時実行性を目的として設計されています。デフォルトでは、SEMAPHORE_LIMIT は 10 の同時操作に設定されており、LLMプロバイダーからの 429 レート制限エラーを防ぐのに役立ちます。このようなエラーが発生した場合は、この値を下げてみてください。

LLMプロバイダーがより高いスループットを許可する場合は、SEMAPHORE_LIMIT を増やしてエピソードの取り込みパフォーマンスを向上させることができます。

Dockerによるデプロイ

Graphiti MCPサーバーは、Dockerを使用してデプロイできます。Dockerfileは、パッケージ管理に uv を使用しており、依存関係の一貫したインストールを保証します。

環境設定

Docker Composeセットアップを実行する前に、環境変数を設定する必要があります。2つのオプションがあります。

1. .env ファイルを使用する（推奨）：
   • 提供されている .env.example ファイルをコピーして .env ファイルを作成します。

     cp .env.example .env
     

   • .env ファイルを編集して、OpenAI APIキーやその他の設定オプションを設定します。

     # LLM操作に必要
     OPENAI_API_KEY=your_openai_api_key_here
     MODEL_NAME=gpt-4.1-mini
     # オプション: 非標準のOpenAIエンドポイントの場合のみ必要
     # OPENAI_BASE_URL=https://api.openai.com/v1
     

   • Docker Composeセットアップは、このファイルが存在する場合に使用するように構成されています（オプション）
2. 直接環境変数を使用する：
   • Docker Composeコマンドを実行するときに環境変数を設定することもできます。

     OPENAI_API_KEY=your_key MODEL_NAME=gpt-4.1-mini docker compose up
     

Neo4jの設定

Docker Composeセットアップには、以下のデフォルト設定のNeo4jコンテナが含まれています。

• ユーザー名: neo4j
• パスワード: demodemo
• URI: bolt://neo4j:7687（Dockerネットワーク内から）
• 開発用途に最適化されたメモリ設定

Docker Composeで実行する

Graphiti MCPコンテナは zepai/knowledge-graph-mcp で利用できます。以下のComposeセットアップでは、このコンテナの最新ビルドが使用されます。

docker compose up

または、古いバージョンのDocker Composeを使用している場合は、次のコマンドを使用します。

docker-compose up

これにより、Neo4jデータベースとGraphiti MCPサーバーの両方が起動します。Dockerセットアップは以下のことを行います。

• パッケージ管理とサーバーの実行に uv を使用します。
• pyproject.toml ファイルから依存関係をインストールします。
• 環境変数を使用してNeo4jコンテナに接続します。
• HTTPベースのSSEトランスポート用にポート8000でサーバーを公開します。
• Neo4jのヘルスチェックを含み、MCPサーバーを起動する前にNeo4jが完全に動作可能であることを確認します。

MCPクライアントとの統合

設定

Graphiti MCPサーバーをMCP互換クライアントと共に使用するには、クライアントをサーバーに接続するように設定します。

⚠️ 重要提示

Pythonパッケージマネージャー uv をインストールする必要があります。uv のインストール手順を参照してください。

uv バイナリとGraphitiプロジェクトフォルダの完全パスを設定することを確認してください。

stdio トランスポートの場合の設定例：

{
  "mcpServers": {
    "graphiti-memory": {
      "transport": "stdio",
      "command": "/Users/<user>/.local/bin/uv",
      "args": [
        "run",
        "--isolated",
        "--directory",
        "/Users/<user>>/dev/zep/graphiti/mcp_server",
        "--project",
        ".",
        "graphiti_mcp_server.py",
        "--transport",
        "stdio"
      ],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "password",
        "OPENAI_API_KEY": "sk-XXXXXXXX",
        "MODEL_NAME": "gpt-4.1-mini"
      }
    }
  }
}

SSEトランスポート（HTTPベース）の場合の設定例：

{
  "mcpServers": {
    "graphiti-memory": {
      "transport": "sse",
      "url": "http://localhost:8000/sse"
    }
  }
}

利用可能なツール

Graphiti MCPサーバーは、以下のツールを公開します。

• add_episode：知識グラフにエピソードを追加します（テキスト、JSON、メッセージ形式をサポート）
• search_nodes：知識グラフ内の関連するノードの概要を検索します。
• search_facts：知識グラフ内の関連する事実（エンティティ間のエッジ）を検索します。
• delete_entity_edge：知識グラフからエンティティエッジを削除します。
• delete_episode：知識グラフからエピソードを削除します。
• get_entity_edge：UUIDでエンティティエッジを取得します。
• get_episodes：特定のグループの最新のエピソードを取得します。
• clear_graph：知識グラフのすべてのデータをクリアし、インデックスを再構築します。
• get_status：Graphiti MCPサーバーとNeo4jの接続状態を取得します。

💻 使用例

基本的な使用法

Graphiti MCPサーバーは、source="json" で add_episode ツールを介して構造化JSONデータを処理できます。これにより、構造化データから自動的にエンティティと関係を抽出できます。

add_episode(
name="Customer Profile",
episode_body="{\"company\": {\"name\": \"Acme Technologies\"}, \"products\": [{\"id\": \"P001\", \"name\": \"CloudSync\"}, {\"id\": \"P002\", \"name\": \"DataMiner\"}]}",
source="json",
source_description="CRM data"
)

Cursor IDEとの統合

Graphiti MCPサーバーをCursor IDEと統合するには、以下の手順を実行します。

1. SSEトランスポートを使用してGraphiti MCPサーバーを実行します。

python graphiti_mcp_server.py --transport sse --use-custom-entities --group-id <your_group_id>

ヒント：group_id を指定してグラフデータの名前空間を設定します。group_id を指定しない場合、サーバーは "default" をグループIDとして使用します。 または

docker compose up

2. CursorをGraphiti MCPサーバーに接続するように設定します。

{
  "mcpServers": {
    "graphiti-memory": {
      "url": "http://localhost:8000/sse"
    }
  }
}

3. CursorのユーザールールにGraphitiルールを追加します。詳細については、cursor_rules.md を参照してください。
4. Cursorでエージェントセッションを開始します。

この統合により、Cursor内のAIアシスタントはGraphitiの知識グラフ機能を通じて永続的なメモリを維持できます。

Claude Desktop（Docker MCPサーバー）との統合

Graphiti MCPサーバーコンテナはSSE MCPトランスポートを使用しています。Claude DesktopはネイティブでSSEをサポートしていないため、mcp-remote のようなゲートウェイを使用する必要があります。

1. SSEトランスポートを使用してGraphiti MCPサーバーを実行する：

docker compose up

2. （オプション）mcp-remote をグローバルにインストールする： mcp-remote をグローバルにインストールすることを好む場合、または npx がパッケージを取得する際に問題が発生した場合は、グローバルにインストールできます。そうでない場合は、次のステップで使用する npx が処理します。

npm install -g mcp-remote

3. Claude Desktopを設定する： Claude Desktopの設定ファイル（通常は claude_desktop_config.json）を開き、mcpServers セクションを次のように追加または変更します。

{
  "mcpServers": {
    "graphiti-memory": {
      // 好みに応じて別の名前を選択できます
      "command": "npx", // またはnpxがPATHにない場合はmcp-remoteの完全パス
      "args": [
        "mcp-remote",
        "http://localhost:8000/sse" // これがGraphitiサーバーのSSEエンドポイントと一致することを確認してください
      ]
    }
  }
}

既に mcpServers エントリがある場合は、その中に graphiti-memory（または選択した名前）を新しいキーとして追加します。 4. Claude Desktopを再起動する： 変更を有効にするには、Claude Desktopを再起動します。

要件

• Python 3.10以上
• Neo4jデータベース（バージョン5.26以上が必要）
• OpenAI APIキー（LLM操作と埋め込みに必要）
• MCP互換クライアント

テレメトリ

Graphiti MCPサーバーはGraphitiコアライブラリを使用しており、これには匿名のテレメトリ収集が含まれています。Graphiti MCPサーバーを初期化すると、フレームワークの改善に役立つために、匿名の使用統計が収集されます。

収集される内容

• 匿名識別子とシステム情報（OS、Pythonバージョン）
• Graphitiのバージョンと設定選択（LLMプロバイダー、データベースバックエンド、埋め込みタイプ）
• 個人情報、APIキー、または実際のグラフコンテンツは決して収集されません

無効化方法

MCPサーバーでテレメトリを無効にするには、環境変数を設定します。

export GRAPHITI_TELEMETRY_ENABLED=false

または、.env ファイルに追加します。

GRAPHITI_TELEMETRY_ENABLED=false

収集される内容と理由の詳細については、GraphitiのメインREADMEのテレメトリセクションを参照してください。

📄 ライセンス

このプロジェクトは、親のGraphitiプロジェクトと同じライセンスでライセンスされています。