KnowledgeGraph MCP Server

警告

私はこのような自動コンテキスト管理ツールに幻滅しています。なぜなら、それを制御するのはほぼ不可能だからです。しばらくすると、いつも手動で散らかったものを整理したり、不適切な LLM のメモを修正したりしなければなりません。 代わりに、私は LLM エージェントに動的に読み込まれるコンテキストへのアクセスを提供するツールを作成しました。ただし、コンテキスト自体はユーザーが作成します: https://github.com/n-r-w/agent-standards-mcp

KnowledgeGraph MCP サーバー

LLM に会話をまたいだ永続的なメモリを与えるシンプルな方法です。このサーバーを使うと、Claude や vscode がナレッジグラフを使ってあなた、あなたのプロジェクト、あなたの好みに関する情報を記憶できます。

主な機能:

• 複数のストレージバックエンド: PostgreSQL（推奨）または SQLite（ローカルファイル）
• プロジェクトの分離: 異なるプロジェクトを分離して保つ（プロンプトを使って自動検出）
• より優れた検索: あいまい検索とページネーションで情報を検索

完全セットアップガイド

Claude でナレッジグラフを動作させるには、次の手順を順番に実行してください:

ステップ 1: インストール方法を選択する

オプション A: NPX（最も簡単 - ダウンロード不要）

# Test that it works
npx knowledgegraph-mcp --help

オプション B: Docker

# Clone and build
git clone https://github.com/n-r-w/knowledgegraph-mcp.git
cd knowledgegraph-mcp
docker build -t knowledgegraph-mcp .

ステップ 2: データベースを選択する

SQLite（デフォルト - セットアップ不要）:

• データベースのインストールは不要
• データベースファイルは [you home folder]/.knowledge-graph/ に自動的に作成されます
• 個人利用やほとんどのシナリオに最適
• これがデフォルトのバックエンドです

PostgreSQL（上級ユーザー向け）:

• システムに PostgreSQL をインストールします
• データベースを作成します: CREATE DATABASE knowledgegraph;
• 複数の同時ユーザーがいる本番利用に適しています

ステップ 3: クライアントを設定する

Claude Desktop

Claude Desktop の設定ファイルを編集します:

設定ファイルを見つける:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

NPX + SQLite（デフォルトで最も簡単）を選んだ場合:

{
  "mcpServers": {
    "Knowledge Graph": {
      "command": "npx",
      "args": ["-y", "knowledgegraph-mcp"]
    }
  }
}

注: SQLite は [you home folder]/.knowledge-graph/knowledgegraph.db にデータベースを自動的に作成します。カスタムの場所を使用するには、次を追加します: "KNOWLEDGEGRAPH_SQLITE_PATH": "/path/to/your/database.db"

Docker + SQLite（デフォルト）を選んだ場合:

{
  "mcpServers": {
    "Knowledge Graph": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "[you home folder]/.knowledge-graph:/app/.knowledge-graph",
        "knowledgegraph-mcp"
      ]
    }
  }
}

注: ボリュームマウントにより、Docker の実行間でデータが永続化されます。カスタムパスを使用するには、次を追加します: -e KNOWLEDGEGRAPH_SQLITE_PATH=/app/.knowledge-graph/custom.db

PostgreSQL を選んだ場合:

{
  "mcpServers": {
    "Knowledge Graph": {
      "command": "npx",
      "args": ["-y", "knowledgegraph-mcp"],
      "env": {
        "KNOWLEDGEGRAPH_STORAGE_TYPE": "postgresql",
        "KNOWLEDGEGRAPH_CONNECTION_STRING": "postgresql://postgres:yourpassword@localhost:5432/knowledgegraph"
      }
    }
  }
}

VS Code

これを VS Code でも使いたい場合は、ユーザー設定（JSON）に次を追加するか、.vscode/mcp.json を作成します:

NPX + SQLite（デフォルト）を使用する場合:

{
  "mcp": {
    "servers": {
      "Knowledge Graph": {
        "command": "npx",
        "args": ["-y", "knowledgegraph-mcp"],
      }
    }
  }
}

Docker（デフォルトの SQLite）を使用する場合:

{
  "mcp": {
    "servers": {
      "Knowledge Graph": {
        "command": "docker",
        "args": [
          "run", "-i", "--rm",
          "-e", "KNOWLEDGEGRAPH_CONNECTION_STRING=sqlite://./knowledgegraph.db",
          "knowledgegraph-mcp"
        ]
      }
    }
  }
}

Docker + PostgreSQL を使用する場合:

まず、PostgreSQL データベースがセットアップされていることを確認します:

# Create the database (run this once)
psql -h 127.0.0.1 -p 5432 -U postgres -c "CREATE DATABASE knowledgegraph;"

次に VS Code を設定します:

{
  "mcp": {
    "servers": {
      "Knowledge Graph": {
        "command": "docker",
        "args": [
          "run", "-i", "--rm",
          "--network", "host",
          "-e", "KNOWLEDGEGRAPH_STORAGE_TYPE=postgresql",
          "-e", "KNOWLEDGEGRAPH_CONNECTION_STRING=postgresql://postgres:[email protected]:5432/knowledgegraph",
          "knowledgegraph-mcp"
        ]
      }
    }
  }
}

代替の Docker + PostgreSQL（--network host が機能しない場合）:

{
  "mcp": {
    "servers": {
      "Knowledge Graph": {
        "command": "docker",
        "args": [
          "run", "-i", "--rm",
          "--add-host", "host.docker.internal:host-gateway",
          "-e", "KNOWLEDGEGRAPH_STORAGE_TYPE=postgresql",
          "-e", "KNOWLEDGEGRAPH_CONNECTION_STRING=postgresql://postgres:[email protected]:5432/knowledgegraph",
          "knowledgegraph-mcp"
        ]
      }
    }
  }
}

重要な注意事項:

• yourpassword を実際の PostgreSQL パスワードに置き換えてください
• 開始する前に knowledgegraph データベースが存在することを確認してください
• 接続エラーが発生する場合は、上記の代替設定を試してください
• Docker + PostgreSQL の問題のトラブルシューティングについては、よくある問題セクションを参照してください

ステップ 4: LLM システムプロンプトを選択する

カスタマイズ:

• ドメインに基づいてエンティティタイプを変更する
• データパターンに合わせて検索戦略を調整する
• ドメイン固有のタグと関係タイプを追加する

LLM の互換性:

• すべての LLM は異なる動作をします。一般的な指示だけで十分なものもあれば、すべてを詳細に記述する必要があるものもあります
• LLM を使って、なぜナレッジグラフを使用しなかったのかを説明させてください。Explain STEP-BY-STEP why you didn't use the knowledge graph? DO NOT DO ANYTHING ELSE と尋ねると、詳細なレポートを取得して指示の問題を特定できます。

利用可能なプロンプト:

• ナレッジグラフ
• タスク管理
• コード品質
• オールインワン
• ナレッジグラフのメンテナンス

ステップ 5: Claude Desktop (または VS Code) を再起動する

Claude Desktop を閉じて、再度開きます。利用可能なツールに「Knowledge Graph」が表示されるはずです。

ステップ 6: 動作をテストする

LLM 向けの簡単なテストコマンド:

1. 「Remember that I prefer morning meetings」→ 選好エンティティを作成します
2. 「John Smith works at Google as a software engineer」→ 人物 + 企業 + 関係を作成します
3. 「Find all people who work at Google」→ 検索と関係をテストします
4. 「Mark the morning meetings preference as urgent」→ タグ付けをテストします

Note: このサービスには、エラーを防ぐための包括的な入力検証が含まれています。問題が発生した場合は、一般的な解決策についてTroubleshooting Guideを確認してください。

仕組み - LLM の強力な機能

ナレッジグラフは、4 つの相互に接続された概念を通じて強力なクエリを可能にします:

1. エンティティ - ナレッジノード

人物、プロジェクト、企業、テクノロジーを検索可能なエンティティとして保存します。

実例 - プロジェクト管理:

{
  "name": "Sarah_Chen",
  "entityType": "person",
  "observations": ["Senior React developer", "Leads frontend team", "Available for urgent tasks"],
  "tags": ["developer", "team-lead", "available"]
}

LLM のメリット: タグ検索で「利用可能なすべてのチームリード」を即座に見つけられます。

2. 関係 - 発見クエリを可能にする

エンティティを接続して、「誰が何に取り組んでいるか」といった複雑な質問に答えます。

実例 - チーム構成:

{
  "from": "Sarah_Chen",
  "to": "Project_Alpha",
  "relationType": "leads"
}

LLM のメリット: 「Sarah がリードするすべてのプロジェクトを検索」または「誰が Project Alpha をリードしているか?」をクエリできます。

3. 観察 - 原子的な事実

エンティティに関する具体的で検索可能な事実を保存します。

実例 - 実行可能な情報:

• 「Available for urgent tasks」→ 利用可能な人材を見つける
• 「Uses React 18.2」→ 特定の技術を使用しているプロジェクトを見つける
• 「Deadline: March 15, 2024」→ 今後の締め切りを見つける

4. タグ - 即時フィルタリング

ステータスとカテゴリの即時検索を可能にします。

実例 - プロジェクトワークフロー:

• ["urgent", "in-progress", "frontend"] → 緊急のフロントエンドタスクを見つける
• ["completed", "bug-fix"] → 完了したバグ修正を追跡する
• ["available", "senior"] → 利用可能なシニアスタッフを見つける

構成オプション

環境変数

サーバーはカスタマイズ用にいくつかの環境変数をサポートしています:

データベース構成

• KNOWLEDGEGRAPH_STORAGE_TYPE: データベースタイプ (sqlite または postgresql、デフォルト: sqlite)
• KNOWLEDGEGRAPH_CONNECTION_STRING: データベース接続文字列
• KNOWLEDGEGRAPH_SQLITE_PATH: カスタム SQLite データベースパス (オプション)
• KNOWLEDGEGRAPH_PROJECT: データ分離用のプロジェクト識別子 (デフォルト: knowledgegraph_default_project)

検索構成

• KNOWLEDGEGRAPH_SEARCH_MAX_RESULTS: データベース検索から返される結果の最大数 (デフォルト: 100、最大: 1000)
• KNOWLEDGEGRAPH_SEARCH_BATCH_SIZE: 大きなクエリ配列を処理するためのバッチサイズ (デフォルト: 10、最大: 50)
• KNOWLEDGEGRAPH_SEARCH_MAX_CLIENT_ENTITIES: クライアント側検索のためにロードするエンティティの最大数 (デフォルト: 10000、最大: 100000)
• KNOWLEDGEGRAPH_SEARCH_CLIENT_CHUNK_SIZE: クライアント側検索で大きなデータセットを処理するためのチャンクサイズ (デフォルト: 1000、最大: 10000)

Note: 検索制限は自動的に検証され、パフォーマンスの問題を防ぐために安全な範囲にクランプされます。

パフォーマンス最適化

検索システムには、いくつかのパフォーマンス最適化が含まれています：

エンティティ読み込みの制限:

• KNOWLEDGEGRAPH_SEARCH_MAX_CLIENT_ENTITIES は、クライアント側の検索で読み込まれるエンティティの数を制限します
• 大規模なデータセットでのメモリの問題を防ぎます
• 制限に達したときに警告がログに記録されます
• SQLite と PostgreSQL の両方のバックエンドに適用されます

チャンク処理:

• KNOWLEDGEGRAPH_SEARCH_CLIENT_CHUNK_SIZE は、大規模なエンティティセットのチャンクサイズを制御します
• エンティティ数がチャンクサイズを超えたときに自動的に使用されます
• メモリ使用量と検索パフォーマンスを改善します
• 重複排除によって結果の正確性を維持します

データセットサイズ別の推奨値:

• 小規模 (1,000 エンティティ未満): デフォルト値で問題なく動作します
• 中規模 (1,000 ～ 10,000 エンティティ): KNOWLEDGEGRAPH_SEARCH_MAX_CLIENT_ENTITIES=5000、KNOWLEDGEGRAPH_SEARCH_CLIENT_CHUNK_SIZE=500 を検討してください
• 大規模 (10,000 エンティティ超): 可能な場合はデータベースレベルの検索を使用するか、KNOWLEDGEGRAPH_SEARCH_MAX_CLIENT_ENTITIES=2000、KNOWLEDGEGRAPH_SEARCH_CLIENT_CHUNK_SIZE=200 を使用してください

パフォーマンス監視:

• 制限が適用されたときに警告がログに記録されます
• チャンク処理は透過性のために自動的にログに記録されます
• 設定の検証により、最適でない設定を防ぎます

利用可能なツール

サーバーは、ナレッジグラフを管理するための以下のツールを提供します：

データ作成ツール

create_entities

ナレッジグラフに新しいエンティティ（人、概念、オブジェクト）を作成します。

• 使用する場面: まだ存在しないエンティティに使用します
• 制約: 各エンティティには、空でない observation が 1 つ以上必須です
• 動作: 既存の名前を持つエンティティは無視されます（更新には add_observations を使用してください）

入力:

• entities (Entity[]): エンティティオブジェクトの配列。各要素に必須:
  • name (string): 一意の識別子、空でないこと
  • entityType (string): カテゴリ（例：'person'、'project'）、空でないこと
  • observations (string[]): エンティティに関する事実、空でない文字列を 1 つ以上含む必要があります
  • tags (string[]、任意): フィルタリング用の完全一致ラベル
• project_id (string、任意): データを分離するためのプロジェクト名

create_relations

エンティティを接続して、強力なクエリと発見を可能にします。

• 即座のメリット: ある企業のすべての人、ある技術を使用しているすべてのプロジェクト、すべての依存関係を検索できます
• 特に重要: チーム構造、プロジェクトの依存関係、技術スタック
• 例: 'John works_at Google'、'React depends_on JavaScript'、'Project_Alpha managed_by Sarah'

入力:

• relations (Relation[]): 関係オブジェクトの配列。各要素に必須:
  • from (string): ソースエンティティ名（存在する必要があります）
  • to (string): ターゲットエンティティ名（存在する必要があります）
  • relationType (string): 能動態での関係タイプ（works_at、manages、depends_on、uses）
• project_id (string、任意): データを分離するためのプロジェクト名

add_observations

既存のエンティティに事実的な observation を追加します。

• 要件: ターゲットエンティティが存在すること、更新ごとに空でない observation を 1 つ以上
• ベストプラクティス: observation はアトミックで具体的に保ちます

入力:

• observations (ObservationUpdate[]): observation 更新の配列。各要素に必須:
  • entityName (string): ターゲットエンティティ名（存在する必要があります）
  • observations (string[]): 追加する新しい事実、空でない文字列を 1 つ以上含む必要があります
• project_id (string、任意): データを分離するためのプロジェクト名

add_tags

即時フィルタリング用のステータス/カテゴリタグを追加します。

• 即座のメリット: ステータス（urgent、completed、in-progress）またはタイプ（technical、personal）でエンティティを検索できます
• 必須: 効率的なプロジェクト管理と迅速な取得のため
• 例: ['urgent', 'completed', 'bug', 'feature', 'personal']

入力:

• updates (TagUpdate[]): タグ更新の配列。各要素に必須:
  • entityName (string): ターゲットエンティティ名（存在する必要があります）
  • tags (string[]): 追加するステータス/カテゴリタグ（完全一致、大文字と小文字を区別）
• project_id (string、任意): データを分離するためのプロジェクト名

データ取得ツール

read_graph

指定されたプロジェクト内のすべてのエンティティと関係を含む完全なナレッジグラフを取得します。

• 用途: 全体像の把握、現在の状態の理解、すべての接続の確認
• スコープ: 指定されたプロジェクト内のすべてを返します

入力:

• project_id (string, 任意): データを分離するためのプロジェクト名

search_knowledge

テキストまたはタグでエンティティを検索します。バッチ検索のために複数のクエリをサポートします。

• 必須の戦略: 1) まず searchMode='exact' を試す 2) 結果がなければ searchMode='fuzzy' を使用する 3) それでも空なら fuzzyThreshold を 0.1 に下げる
• 完全一致モード: 完全な部分文字列一致（高速で正確）
• あいまいモード: 類似した用語やスペルミスのある用語（低速だが広範囲）
• タグ検索: 正確なカテゴリフィルタリングには exactTags を使用します
• 複数クエリ: 1 回の呼び出しで複数のオブジェクトを検索し、自動的に重複を排除します

入力:

• query (string | string[], 任意): テキスト検索用のクエリ。単一の文字列、または複数のオブジェクト検索用の文字列配列を指定できます。タグのみの検索のために exactTags が指定されている場合は任意です。
• searchMode (string, 任意): "exact" または "fuzzy"（デフォルト: "exact"）。exact が結果を返さない場合にのみ fuzzy を使用してください
• fuzzyThreshold (number, 任意): あいまい一致のしきい値。0.3=デフォルト、0.1=非常に広範囲、0.7=非常に厳格。値が小さいほど多くの結果が見つかります
• exactTags (string[], 任意): 完全一致検索用のタグ（大文字と小文字を区別）。カテゴリフィルタリングに使用します
• tagMatchMode (string, 任意): exactTags 用: "any"=いずれかのタグを持つエンティティ、"all"=すべてのタグを持つエンティティ（デフォルト: "any"）
• page (number, 任意): ページネーションのページ番号（0 始まり、デフォルト: 0）
• pageSize (number, 任意): 1 ページあたりの結果数（1〜1000、デフォルト: 50）
• project_id (string, 任意): データを分離するためのプロジェクト名

例:

• 基本的な検索: search_knowledge(query="JavaScript", searchMode="exact")
• ページネーション付き検索: search_knowledge(query="React", page=0, pageSize=20)
• 大規模データセット: search_knowledge(query="components", page=2, pageSize=100)
• 複数クエリ: search_knowledge(query=["JavaScript", "React"], page=0, pageSize=30)
• タグ + ページネーション: search_knowledge(query="React", exactTags=["frontend"], page=1, pageSize=25)
• タグのみの検索: search_knowledge(exactTags=["urgent", "bug"], tagMatchMode="all") - クエリは不要です

ページネーションの利点:

• パフォーマンス: 大規模データセットを効率的に処理するための OFFSET/LIMIT によるデータベースレベルのページネーション
• メモリ: リクエストごとの結果数を制限することでメモリ使用量を削減
• ナビゲーション: ページネーションのメタデータが totalPages、currentPage、ナビゲーションのヒントを提供
• スケーラビリティ: 数千のエンティティを持つナレッジグラフを効率的に処理

open_nodes

正確な名前で特定のエンティティを、その相互接続とともに取得します。

• 返すもの: 要求されたエンティティとそれらの間の関係
• 用途: 正確なエンティティ名がわかっていて、詳細な情報を取得したい場合

入力:

• names (string[]): 取得するエンティティ名の配列
• project_id (string, 任意): データを分離するためのプロジェクト名

データ管理ツール

delete_entities

エンティティとそのすべての関係を完全に削除します。

• 警告: 元に戻すことはできません。すべての接続を削除する形で連鎖します
• 用途: 関連性がなくなったエンティティ、または誤って作成されたエンティティ

入力:

• entityNames (string[]): 削除するエンティティ名の配列
• project_id (string, 任意): データを分離するためのプロジェクト名

delete_observations

エンティティをそのまま維持しつつ、特定の観察をエンティティから削除します。

• 用途: 誤った情報の訂正、または古くなった詳細の削除
• 保持: エンティティとその他の観察は変更されずに残ります

入力:

• deletions (ObservationDeletion[]): 削除リクエストの配列。各リクエストには以下が必須です:
  • entityName (string): 対象のエンティティ名
  • observations (string[]): 削除する特定の観察
• project_id (string, 任意): データを分離するためのプロジェクト名

delete_relations

接続が変化したときにリレーションシップ構造を更新します。

• 重要な用途: 職務の変更（古い 'works_at' を削除）、プロジェクトの完了（'assigned_to' を削除）、技術の移行（古い 'uses' を削除）
• 維持するもの: 正確なネットワーク構造を保ち、混乱を防ぎます
• ワークフロー: 新しいリレーションを作成するときは、常に古いリレーションを削除してください

入力:

• relations (Relation[]): 削除するリレーションの配列。各要素に必須:
  • from (string): ソースエンティティ名
  • to (string): ターゲットエンティティ名
  • relationType (string): 削除するリレーションシップの正確な種類
• project_id (string, 任意): データを分離するためのプロジェクト名

remove_tags

古くなったタグを削除してエンティティのステータスを更新します。

• 重要: ステータス追跡用 - 完了したら 'in-progress' を削除し、解決したら 'urgent' を削除します
• 維持するもの: クリーンな検索結果と正確なステータス
• ワークフロー: 新しいステータスタグを追加するときは、常に古いステータスタグを削除してください

入力:

• updates (TagUpdate[]): タグ削除リクエストの配列。各要素に必須:
  • entityName (string): ターゲットエンティティ名
  • tags (string[]): 削除する古くなったタグ（完全一致、大文字と小文字を区別）
• project_id (string, 任意): データを分離するためのプロジェクト名

開発とテスト

マルチバックエンドテスト

このプロジェクトには、SQLite と PostgreSQL の両方で互換性を確保するための包括的なマルチバックエンドテストが含まれています:

両方のバックエンドに対してテストを実行:

npm run test:multi-backend

すべてのテスト（元のテスト + マルチバックエンド）を実行:

npm run test:all-backends

Taskfile を使用する場合（インストールされている場合）:

task test:multi-backend
task test:comprehensive

開発セットアップ

クローンとセットアップ:

git clone https://github.com/n-r-w/knowledgegraph-mcp.git
cd knowledgegraph-mcp
npm install
npm run build

テストを実行:

npm test                    # All tests including multi-backend
npm run test:unit          # Unit tests only
npm run test:performance   # Performance benchmarks

トラブルシューティング

セットアップ中または使用中に問題が発生した場合は、包括的なトラブルシューティングガイドを参照してください。そこでは以下を扱っています:

• 入力検証エラー
• データベース接続の問題
• 設定の問題
• Docker 関連の課題
• テスト実行の失敗
• パフォーマンスの最適化

このガイドには、一般的な問題に対するステップバイステップの解決策と、問題を特定するのに役立つ診断コマンドが含まれています。

MCP Memory Server をベースにしています

これは公式の MCP Memory Server に追加機能を加えた拡張版です:

• 複数のストレージオプション: PostgreSQL（推奨）または SQLite（ローカルファイル）
• プロジェクトの分離: 異なるプロジェクトを分離して保持
• より優れた検索: ファジー検索で情報を検索
• 簡単なセットアップ: Docker サポートとシンプルなインストール

ライセンス

MIT ライセンス - このソフトウェアを自由に使用、変更、配布できます。