NeoCoder: Neo4j-Guided AI Coding Workflow

NeoCoder：Neo4j によるガイド付き AI コーディングワークフロー

Claude などの AI アシスタントが、Neo4j のナレッジグラフを標準化されたコーディングワークフローの主要かつ動的な「取扱説明書」とプロジェクトメモリーとして使用できるようにする MCP サーバーの実装です。

NeoCoder：ハイブリッド AI 推論・ワークフローシステム

Neo4j ナレッジグラフ、Qdrant ベクトルデータベース、高度な AI オーケストレーションを組み合わせ、ナレッジ管理、調査分析、標準化されたワークフローのためのハイブリッド推論システムを実現する、高度な MCP サーバー実装です。

概要

NeoCoder は、次の要素を組み合わせることで、従来の RAG（検索拡張生成）をはるかに超える革新的な コンテキスト拡張推論 システムを実装します。

コアアーキテクチャ：

1. Neo4j ナレッジグラフ - 信頼できる構造化された事実、関係、ワークフロー
2. Qdrant ベクトルデータベース - セマンティック検索、類似性の検出、コンテキストの理解
3. MCP オーケストレーション - 統合と引用を伴う、データソース間のインテリジェントなルーティング
4. F 縮約による統合 - 情報源の帰属を保持しながら、知識を動的に統合

主な機能：

• ハイブリッドな知識推論：構造化された事実とセマンティックなコンテキストをシームレスに組み合わせます
• 動的な知識抽出：ドキュメント、コード、会話を相互接続された知識構造に変換します
• 引用ベースの分析：複数のデータベースにわたって、すべての主張を情報源まで追跡できます
• マルチインカーネーションシステム：コーディング、調査、意思決定支援、ナレッジ管理に特化したモードを備えています
• インテリジェントなワークフローテンプレート：必須の検証手順を備えた、Neo4j によるガイド付き手順です

革新的な機能：

🧠 スマートクエリルーティング：AI がグラフ、ベクトル、ハイブリッドから最適なデータソースを自動的に判断します
🔬 調査分析エンジン：引用グラフとセマンティックコンテンツを含む学術論文を処理します
⚡ F 縮約処理：出所情報を保持しながら、類似した概念を動的に統合します
🎯 コンテキスト拡張推論：単一のデータソースでは得られない洞察を生成します
📊 完全な監査証跡：知識の統合とワークフローの実行をすべて追跡します
🛡️ 本番環境対応のプロセス管理：自動クリーンアップ、シグナル処理、リソース追跡により、プロセスのリークを防止します
🔧 強化されたツール処理：バックグラウンドタスクを適切に管理しながら、堅牢な非同期初期化を行います

私のアイデアから新たに追加した機能です- ロトカ・ヴォルテラ生態学的フレームワークをナレッジグラフインカーネーションに統合

プロセス管理と信頼性

NeoCoder は、MCP のベストプラクティスに従い、包括的なプロセス管理を実装しています。

• シグナルハンドラー：正常なシャットダウンのために SIGTERM/SIGINT を適切に処理します
• リソース追跡：プロセス、Neo4j 接続、バックグラウンドタスクを自動的に追跡します
• ゾンビプロセスのクリーンアップ：孤立したサーバーインスタンスを積極的に検出してクリーンアップします
• メモリー管理：適切なクリーンアップパターンによってリソースリークを防止します
• バックグラウンドタスク管理：非同期初期化と並行処理を安全に扱います
• コネクションプーリング：自動クリーンアップを備えた効率的な Neo4j ドライバー管理を行います

監視コマンド

次のツールを使ってサーバーの状態を監視できます。

• get_cleanup_status() - リソース使用状況とクリーンアップの状態を表示します
• check_connection() - Neo4j への接続と権限を確認します

クイックスタート

前提条件

• Neo4j：ローカルまたはリモートのインスタンスが稼働していること（構造化ナレッジグラフ用）

• Qdrant：セマンティック検索と埋め込みのためのベクトルデータベース（ハイブリッド推論用）

• Python 3.10+：MCP サーバーの実行用

• uv：MCP サーバー用の Python パッケージマネージャー

• Claude Desktop：Claude AI で使用する場合

• MCP-Desktop-Commander：コマンドラインやファイルシステムの操作に非常に便利です

• Lotka-Volterra Ecosystem および全般的な機能強化には、以下を使用します。

• wolframalpha-llm-mcp：とても便利です！

• mcp-server-qdrant-enhanced：私の Qdrant 強化版 MCP サーバーです

• さらに便利な機能を利用する場合（任意）

• arxiv-mcp-server

このバージョンは現在も開発中です

• コード解析版：AST/ASG：現在、開発とバージョンの書き直しが必要です

• WolframAlpha の無料 API キーを取得します。

Wolfram|Alpha の無料 API キー（AppID）を取得するには、Wolfram ID を登録してから Wolfram|Alpha Developer Portal でアプリケーションを登録する必要があります。

Wolfram ID を作成します。まだお持ちでない場合は、https://account.wolfram.com/login/create で Wolfram ID を作成してください。

Developer Portal に移動します。Wolfram ID を取得したら、Wolfram|Alpha Developer Portal https://developer.wolframalpha.com/portal/myapps にサインインしてください。

最初の AppID に登録します。「Sign up to get your first AppID」ボタンをクリックしてください。

AppID 作成ダイアログに入力します。アプリケーションの名前と簡単な説明を入力してください。

AppID を受け取ります。必要な情報を入力すると、AppID とも呼ばれる API キーが表示されます。

Wolfram|Alpha API は非商用利用であれば無料で、月に最大 2,000 件のリクエストを利用できます。

アプリケーションごとに固有の AppID が必要です。

MCP サーバーは Python コードを実行し、Neo4j グラフと AI アシスタント（例：Claude）の間をつなぎます

インストール

1. リポジトリをクローンする

git clone https://github.com/angrysky56/NeoCoder-neo4j-ai-workflow.git
cd NeoCoder-neo4j-ai-workflow

2. Python と仮想環境をセットアップする

pyenv と uv がインストールされていることを確認してください。

pyenv install 3.11.12  # if not already installed
pyenv local 3.11.12
uv venv
source .venv/bin/activate

3. 依存関係をインストールする

uv pip install -e '.[dev,docs,gpu]'

4. Neo4j と Qdrant を起動する

• Neo4j： Neo4j サーバーを起動します（ローカルまたはリモート）。 デフォルトの接続先：bolt://localhost:7687

Neo4j の接続パラメーター：

• URL：bolt://localhost:7687（デフォルト）

• ユーザー名：neo4j（デフォルト）

• パスワード：Neo4j データベースのパスワード

• データベース：neo4j（デフォルト）

  必要に応じて、環境変数で認証情報を設定します。

  • NEO4J_URL
  • NEO4J_USERNAME
  • NEO4J_PASSWORD
  • NEO4J_DATABASE

• Qdrant： Qdrant のデータを永続化するには、次の Docker コマンドを使用します（推奨）。

  docker run -p 6333:6333 -p 6334:6334 \
    -v "$(pwd)/qdrant_storage:/qdrant/storage:z" \
    qdrant/qdrant
  

  これにより、プロジェクトディレクトリ内の qdrant_storage フォルダーに Qdrant のデータが保存されます。

5.（任意）VS Code ユーザー向け

• コマンドパレット（Ctrl+Shift+P）を開き、Python: Select Interpreter を選択して、.venv/bin/python を選びます。

1. 設定を使用すると自動でインストールされるはずです。もう試していないので確かではありません。また、一部の依存関係はかなり大きいです。

クイックスタート案——あはは、すみません

推奨：Claude Desktop との統合：

次の内容を追加して Claude Desktop を設定します。 claude-app-config.json：

{
  "mcpServers": {
    "neocoder": {
      "command": "uv",
      "args": [
        "--directory",
        "/your-path-to/NeoCoder-neo4j-ai-workflow",
        "run",
        "mcp_neocoder"
      ],
      "env": {
        "NEO4J_URL": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "your-neo4j-password-here",
        "NEO4J_DATABASE": "neo4j",
        "LOG_LEVEL": "INFO",
        "MCP_TRANSPORT": "stdio",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

重要：この設定のパスワードは、Neo4j データベースのパスワードと一致している必要があります。

それ以外の場合は、依存関係をインストールします： 簡単なトラブルシューティング：

• パッケージが見つからないというエラーが表示された場合は、.venv が有効になっていることと、正しい Python バージョンを使用していることを再確認してください。
• 環境をリセットする必要がある場合は、.venv を削除して上記の手順を繰り返してください。
• DB に接続できませんか？ neo4j Desktop と QDRANT をインストールしてください。これらが実行中であることを確認してください。NEO4J ではパスワードの設定が必要です。

docker pull qdrant/qdrant

docker run -p 6333:6333 -p 6334:6334 \
    -v "$(pwd)/qdrant_storage:/qdrant/storage:z" \
    qdrant/qdrant

---

これで、Neo4j と Qdrant を組み合わせた完全なハイブリッド Lotka-Volterra エコシステム推論で NeoCoder を使用する準備が整いました！

推奨システムプロンプト

> **System Instruction:** You are an AI assistant integrated with a Neo4j knowledge graph that defines our standard procedures and tracks project changes.
>
> **Your Core Interaction Loop:**
> 1.  **Identify Task & Keyword:** Determine the action required (e.g., fix a bug -> `FIX`).
> 2.  **Consult the Hub:** If unsure about keywords or process, start by querying `:AiGuidanceHub {id: 'main_hub'}` for guidance and links to best practices or other guides.
> 3.  **Retrieve Instructions:** Formulate a Cypher query to fetch the `steps` from the current `:ActionTemplate` matching the keyword (e.g., `MATCH (t:ActionTemplate {keyword: 'FIX', isCurrent: true}) RETURN t.steps`). Execute this query.
> 4.  **Execute Guided Workflow:** Follow the retrieved `steps` meticulously. This includes reviewing project READMEs, implementing changes, and critically:
> 5.  **Perform Verification:** Execute the testing steps defined in the template. **ALL required tests MUST pass before you consider the task complete.**
> 6.  **Record Completion (Post-Testing):** Only if tests pass, formulate and execute the Cypher query specified in the template to create a `:WorkflowExecution` node, linking it appropriately. Do NOT record if tests failed.
> 7.  **Finalize Updates:** Update the project's README content (in Neo4j or the file) as per the template's instructions.
>
> **Strict Rule:** Always prioritize instructions retrieved from the Neo4j graph over your general knowledge for workflow procedures. Use the graph as your single source of truth for *how* tasks are done here.

---

> **knowledge_graph_incarnation with integrated Lotka Volterra Special System Instruction:** You are an AI assistant integrated with a sophisticated hybrid reasoning system that combines Neo4j knowledge graphs, Qdrant vector databases, and MCP orchestration for advanced knowledge management and workflow execution.
>
> **Your Core Capabilities:**
> 1. **Standard Coding Workflows:** Use Neo4j-guided templates for structured development tasks
> 2. **Hybrid Knowledge Reasoning:** Combine structured facts (Neo4j) with semantic search (Qdrant) for comprehensive analysis
> 3. **Dynamic Knowledge Synthesis:** Apply F-Contraction principles to merge and consolidate knowledge from multiple sources
> 4. **Multi-Modal Analysis:** Process research papers, code, documentation, and conversations into interconnected knowledge structures
> 5. **Citation-Based Reasoning:** Provide fully attributed answers with source tracking across databases
>
> **Your Core Interaction Loop:**
> 1.  **Identify Task & Context:** Determine the required action and select appropriate incarnation/workflow
> 2.  **Consult Guidance Hubs:** Query incarnation-specific guidance hubs for specialized capabilities and procedures
> 3.  **Execute Hybrid Workflows:** For knowledge tasks, use KNOWLEDGE_QUERY template for intelligent routing between graph and vector search
> 4.  **Apply Dynamic Synthesis:** Use KNOWLEDGE_EXTRACT template to process documents into both structured (Neo4j) and semantic (Qdrant) representations
> 5.  **Ensure Quality & Citations:** All knowledge claims must be properly cited with source attribution
> 6.  **Record & Learn:** Log successful executions for system optimization and learning
>
> **Hybrid Reasoning Protocol:**
> - **Graph-First**: Use Neo4j for authoritative facts, relationships, and structured data
> - **Vector-Enhanced**: Use Qdrant for semantic context, opinions, and nuanced information
> - **Intelligent Synthesis**: Combine both sources with conflict detection and full citation tracking
> - **F-Contraction Merging**: Dynamically merge similar concepts while preserving source attribution
>
> **Strict Rules:**
> - Always prioritize structured facts from Neo4j over semantic information
> - Every claim must include proper source citations
> - Use incarnation-specific tools and templates as single source of truth for procedures
> - Apply F-Contraction principles when processing multi-source information

---

Instructions for WolframAlpha use
- WolframAlpha understands natural language queries about entities in chemistry, physics, geography, history, art, astronomy, and more.
- WolframAlpha performs mathematical calculations, date and unit conversions, formula solving, etc.
- Convert inputs to simplified keyword queries whenever possible (e.g. convert "how many people live in France" to "France population").
- Send queries in English only; translate non-English queries before sending, then respond in the original language.
- Display image URLs with Markdown syntax: ![URL]
- ALWAYS use this exponent notation: `6*10^14`, NEVER `6e14`.
- ALWAYS use {"input": query} structure for queries to Wolfram endpoints; `query` must ONLY be a single-line string.
- ALWAYS use proper Markdown formatting for all math, scientific, and chemical formulas, symbols, etc.:  '$$\n[expression]\n$$' for standalone cases and '\( [expression] \)' when inline.
- Never mention your knowledge cutoff date; Wolfram may return more recent data.
- Use ONLY single-letter variable names, with or without integer subscript (e.g., n, n1, n_1).
- Use named physical constants (e.g., 'speed of light') without numerical substitution.
- Include a space between compound units (e.g., "Ω m" for "ohm*meter").
- To solve for a variable in an equation with units, consider solving a corresponding equation without units; exclude counting units (e.g., books), include genuine units (e.g., kg).
- If data for multiple properties is needed, make separate calls for each property.
- If a WolframAlpha result is not relevant to the query:
 -- If Wolfram provides multiple 'Assumptions' for a query, choose the more relevant one(s) without explaining the initial result. If you are unsure, ask the user to choose.
 -- Re-send the exact same 'input' with NO modifications, and add the 'assumption' parameter, formatted as a list, with the relevant values.
 -- ONLY simplify or rephrase the initial query if a more relevant 'Assumption' or other input suggestions are not provided.
 -- Do not explain each step unless user input is needed. Proceed directly to making a better API call based on the available assumptions.

複数の形態

NeoCoder は複数の「形態」をサポートしています。これは、コアとなる Neo4j グラフ構造を維持しながら、特定のユースケースに合わせてシステムを調整する、さまざまな運用モードです。グラフネイティブなスタックでは、テンプレートと実行ポリシーを入れ替えるだけで、同じ Neo4j コアがまったく異なる「頭脳」として機能します。

主なアーキテクチャ原則

NeoCoder の分割構造は、次の理由により高い適応性を備えています。

• Neo4j は事実を第一級のグラフオブジェクトとして保存します
• ワークフローはテンプレートノードに格納されます
• 実行エンジンはグラフをたどるだけです

これら3つの層は互いに独立しているため、1つの層を固定したまま、ほかの層を変化させることができます。たとえば、今日のコードデバッガーを、明日には実験ノートや学習管理システムに変えることができます。この設計は、スキーマ、セマンティクス、運用を意図的に切り離す、Neo4j 独自の「グラフからナレッジグラフへ」という成熟の道筋にも通じています。

一般的なグラフスキーマのパターン

すべての形態で、次のコア要素を共有します。

要素	常に存在するもの	一般的なラベル／リレーションシップ
アクター	人間／エージェント／ツール	(:Agent)-[:PLAYS_ROLE]->(:Role)
意図	仮説、決定、教訓、シナリオ	(:Intent {type})
証拠	文書、指標、観察	(:Evidence)-[:SUPPORTS]->(:Intent)
結果	合格／不合格、報酬、評価、状態ベクトル	(:Outcome)-[:RESULT_OF]->(:Intent)

利用可能なインカーネーション：

• base_incarnation（デフォルト） - オリジナルの NeoCoder、ツール、テンプレート、インカーネーションのワークフロー管理
• research_incarnation - 仮説の追跡と実験のための科学研究プラットフォーム
  • 仮説を登録し、実験を設計し、実験の実行を記録して、結果を公開します
  • Neo4j により、系譜クエリを用いたラボのワークフロー向け来歴パイロットを支えます
• decision_incarnation - 意思決定分析およびエビデンス追跡システム
  • 期待値指標を用いて、意思決定の選択肢を作成します
  • 新しいエビデンスが届くと、ベイズ更新エージェントが指標の事後分布を再計算します
  • 透明性が高く、説明可能な推論パイプライン
• data_analysis_incarnation - 複雑系のモデリングとシミュレーション
  • 状態ベクトルと物理的結合を用いてコンポーネントをモデル化します
  • パスクエリを使用して、障害の伝播をシミュレートします
  • パラメーター検証用の量子着想型スケジューラー（オプション）
• knowledge_graph_incarnation - 高度なハイブリッド推論システム
  • ハイブリッドナレッジクエリ：Neo4j の構造化データと Qdrant のセマンティック検索を組み合わせます
  • 動的ナレッジ抽出：ドキュメントを処理し、グラフ表現とベクトル表現の両方に変換します
  • F-縮約による統合：出典の帰属を保ちながら、類似する概念をインテリジェントに統合します
  • 引用ベースの推論：複数のデータベースにわたる完全な出典追跡
  • 研究分析エンジン：学術論文処理に特化したワークフロー
  • スマートクエリルーティング：AI が最適なデータソース戦略を自動的に判断します
  • データベース間ナビゲーション：構造化された事実とセマンティックなコンテンツをシームレスにリンクします
  • 矛盾の検出：出典間の不整合を特定して警告します
  • リアルタイムのナレッジ統合：会話やドキュメントから動的にグラフを構築します
• code_analysis_incarnation - 抽象構文木を使用したコード分析
  • AST および ASG ツールを使用して、コード構造を解析および分析します
  • コードの複雑さと品質指標を追跡します
  • 異なるバージョンのコードを比較します
  • コード分析からドキュメントを生成します
  • コードスメルや潜在的な問題を特定します

各インカーネーションには、それぞれ専用のツールセットがあり、サーバーの起動時に自動的に登録されます。これらのツールは、MCP サーバーに接続する Claude やその他の AI アシスタントで使用できます。

実装ロードマップ

NeoCoder には、次の項目を含む実装ロードマップがあります。

1. LevelEnv ↔ Neo4j アダプター：イベントをグラフ構造にマッピングし、バッチ処理を行います
2. Amplitude レジスター（量子レイヤー）：重ね合わせ状態を扱う量子着想型レイヤー（オプション）
3. スケジューラー：エントロピーと影響度スコアに基づいてタスクに優先順位を付けます
4. TAG アセットの再利用：垂直方向の情報隠蔽に既存の抽象化を活用します

特定のインカーネーションでの起動

# List all available incarnations
python -m mcp_neocoder.server --list-incarnations

# Start with a specific incarnation
python -m mcp_neocoder.server --incarnation continuous_learning

インカーネーションは、switch_incarnation() ツールを使用して実行時に切り替えることもできます。

switch_incarnation(incarnation_type="complex_system")

インカーネーションの動的読み込み

NeoCoder には、incarnations ディレクトリ内のインカーネーションを自動的に検出して読み込む、完全に動的なインカーネーション読み込みシステムがあります。つまり、次のことが可能です。

1. ハードコードされたインポートは不要：server.py を変更せずに、新しいインカーネーションを追加できます
2. 自動検出：*_incarnation.py 形式の新しいファイルを incarnations ディレクトリに追加するだけです
3. すべてのツールが利用可能：そのインカーネーションがアクティブでなくても、すべてのインカーネーションのツールが登録され、利用できます
4. 簡単な拡張：提供されたテンプレートを使って、新しいインカーネーションを作成できます

新しいインカーネーションの作成

新しいインカーネーションを作成するには：

1. src/mcp_neocoder/incarnations/ ディレクトリに、your_incarnation_name_incarnation.py という命名パターンで新しいファイルを作成します
2. 次のテンプレート構造を使用します：

"""
Your incarnation name and description
"""

import json
import logging
import uuid
from typing import Dict, Any, List, Optional, Union

import mcp.types as types
from pydantic import Field
from neo4j import AsyncTransaction

from .polymorphic_adapter import BaseIncarnation, IncarnationType

logger = logging.getLogger("mcp_neocoder.incarnations.your_incarnation_name")


class YourIncarnationNameIncarnation(BaseIncarnation):
    """
    Your detailed incarnation description here
    """

    # Define the incarnation type - must match an entry in IncarnationType enum
    incarnation_type = IncarnationType.YOUR_INCARNATION_TYPE

    # Metadata for display in the UI
    description = "Your incarnation short description"
    version = "0.1.0"

    # Initialize schema and add tools here
    async def initialize_schema(self):
        """Initialize the schema for your incarnation."""
        # Implementation...

    # Add more tool methods below
    async def your_tool_name(self, param1: str, param2: Optional[int] = None) -> List[types.TextContent]:
        """Tool description."""
        # Implementation...

3. polymorphic_adapter.py の IncarnationType enum に、インカーネーションの種類を追加します
4. サーバーを再起動すると、新しいインカーネーションが自動的に検出されます

インカーネーションの使用方法と作成方法の詳細については、incarnations.md を参照してください。

利用可能なテンプレート

NeoCoder には、次の標準テンプレートが付属しています：

1. FIX - 報告されたバグを修正するためのガイダンス。必須のテストとログ記録が含まれます
2. REFACTOR - 機能を維持しながらコードをリファクタリングするための構造化されたアプローチ
3. DEPLOY - 安全性チェックを行いながら、本番環境にコードをデプロイするためのガイダンス
4. FEATURE - 適切なテストとドキュメントを備えた新機能を実装するための構造化されたアプローチ
5. TOOL_ADD - NeoCoder MCP サーバーに新しいツール機能を追加するためのプロセス
6. CYPHER_SNIPPETS - Neo4j クエリ向けの Cypher スニペットの管理と使用
7. CODE_ANALYZE - AST および ASG ツールを使用してコードを分析するための構造化されたワークフロー
8. KNOWLEDGE_QUERY - 複数のソースを用いたインテリジェントな推論を実現するハイブリッドナレッジクエリシステム
9. KNOWLEDGE_EXTRACT - F-Contraction マージによる動的なナレッジ抽出と統合

高度なハイブリッド推論システム

NeoCoder は、複数のデータソースを組み合わせ、これまでにないナレッジ統合機能を実現する、革新的なコンテキスト拡張型推論アーキテクチャを備えています。

ハイブリッドクエリアーキテクチャ

KNOWLEDGE_QUERY テンプレートは、高度な 3 ステップの推論プロセスを実装しています。

ステップ 1：スマートクエリルーター

• 意図の分類：AI がクエリを分析し、最適なデータソース戦略を判断します
• クエリの種類：
  • グラフ中心：「誰が誰と仕事をしていますか？」「依存関係の連鎖を表示」
  • ベクトル中心：「X に対する意見は？」「Y に関する議論を検索」
  • ハイブリッド：「[グラフ内の人物] は [意味的なトピック] について何と言いましたか？」
• 実行計画：複雑なハイブリッドクエリに対する複数ステップの計画を設計します

ステップ 2：並列データ取得

• Neo4j クエリ：構造化された事実と関係性を取得するために、Cypher クエリを実行します
• Qdrant 検索：ドキュメントコレクション全体を対象に、意味検索を実行します
• 逐次最適化：ハイブリッドクエリでは、グラフの結果を使ってベクトル検索を絞り込みます

ステップ 3：クロスデータベース統合

• インテリジェントな統合：構造化された事実と意味的なコンテキストを組み合わせます
• ソースの優先順位付け：Neo4j の事実を信頼できる情報として扱い、ニュアンスや意見には Qdrant を使用します
• 必須の引用：すべての主張を特定のソースに帰属させます
• 矛盾の検出：データソース間の不整合を特定し、明示します

動的ナレッジ抽出（F-Contraction）

KNOWLEDGE_EXTRACT テンプレートは、グラフ縮約の原理に着想を得た、動的なナレッジ統合を実装しています。

F-Contraction の基本概念：

• 概念を頂点として扱う：個々の概念をそれぞれグラフエンティティにします
• 関係性をエッジとして扱う：共起と明示的な接続を追跡します
• 動的マージ：LLM を活用して重複または類似する概念を検出します
• ソースの保持：マージ後も、すべての元のソースへのポインターを維持します

ナレッジ処理パイプライン：

1. ドキュメントの取り込み：PDF、テキスト、コード、会話を解析します
2. デュアルストレージ：Qdrant 向けにテキストをチャンク化し、Neo4j 向けにエンティティを抽出します
3. エンティティ抽出：論文、著者、概念、手法などを特定します
4. 関係性の検出：引用、依存関係、意味的なつながりを特定します
5. F-Contraction マージ：類似するエンティティをインテリジェントに統合します
6. 相互参照マッピング：グラフエンティティをベクトルドキュメントのチャンクにリンクします
7. 品質検証：一貫性と完全性を確認します

研究分析エンジン

学術文書や技術文書の処理に特化した機能：

• 引用グラフの構築：論文間の関係ネットワークを構築します
• マルチホップ推論：「引用リンクをたどって、トランスフォーマーアーキテクチャの進化を追跡する」
• 矛盾の分析：「論文 A と論文 B では、X の定義がどのように異なりますか？」
• 時間軸に沿った統合：複数の情報源をもとに、概念の変遷を追跡します
• 分野横断的な統合：複数の研究分野の知見を組み合わせます

ハイブリッド推論のメリット

1. これまでにない統合：単一のデータソースでは得られない回答を生成します
2. 情報源の透明性：生データから結論までの完全な監査証跡を保持します
3. 矛盾の認識：矛盾する情報を明示的に扱います
4. セマンティックな拡充：構造化された事実を、文脈の理解によって補強します
5. 動的な学習：F-Contraction によるマージを通じてナレッジベースを改善します
6. 研究の加速：複雑な学術文献を迅速に分析します

アーキテクチャ

ナレッジグラフの構造

• :AiGuidanceHub：AI の中心的なナビゲーションハブ
• :ActionTemplate：標準的なワークフロー（FIX、REFACTOR など）のテンプレート
• :Project：README や構造を含むプロジェクトデータ
• :File/Directory：プロジェクトのファイル構造を表現します
• :WorkflowExecution：完了したワークフローの監査証跡
• :BestPracticesGuide：コーディング標準とガイドライン
• :TemplatingGuide：テンプレートの作成・変更方法
• :SystemUsageGuide：グラフシステムの使用方法

MCP サーバーのツール

MCP サーバーは、AI アシスタント向けに次のツールを提供します：

コアツール

• check_connection：Neo4j の接続状況を確認します
• get_guidance_hub：AI ナビゲーションのエントリーポイント
• get_action_template：特定のワークフローテンプレートを取得します
• list_action_templates：利用可能なすべてのテンプレートを表示します
• get_best_practices：コーディング標準を確認します
• get_project：README を含むプロジェクトの詳細を表示します
• list_projects：システム内のすべてのプロジェクトを一覧表示します
• log_workflow_execution：ワークフローの正常な完了を記録します
• get_workflow_history：実施した作業の監査証跡を表示します
• add_template_feedback：テンプレートへのフィードバックを提供します
• run_custom_query：Cypher クエリを直接実行します
• write_neo4j_cypher：グラフに対する書き込み操作を実行します

インカネーション管理ツール

• get_current_incarnation：現在アクティブなインカネーションを取得します
• list_incarnations：利用可能なすべてのインカネーションを一覧表示します
• switch_incarnation：別のインカネーションに切り替えます
• suggest_tool：タスクの説明に基づいてツールを提案します

各インカネーションを有効にすると、そのインカネーションに特化した追加のツールが自動的に登録されます。

ナレッジグラフとハイブリッド推論ツール

ナレッジグラフの機能では、構造化グラフデータとセマンティックベクトル検索を組み合わせた、高度なハイブリッド推論機能を利用できます。

コアとなるナレッジ管理：

• create_entities：観察内容と適切な Neo4j ラベルを付けて、複数のエンティティを作成します
• create_relations：型付きの関係とタイムスタンプを使って、エンティティを接続します
• add_observations：既存のエンティティにタイムスタンプ付きの観察内容を追加します
• delete_entities：関係を連鎖的に削除して、エンティティを削除します
• delete_observations：特定の観察内容を対象に削除します
• delete_relations：エンティティを保持したまま、特定の関係を削除します
• read_graph：エンティティ、観察内容、関係を含むナレッジグラフ全体を表示します
• search_nodes：エンティティ名、種類、観察内容を対象に全文検索します
• open_nodes：入出力の関係を含む、エンティティの詳細情報を取得します

高度なハイブリッド推論ツール：

• KNOWLEDGE_QUERY ワークフロー：インテリジェントなハイブリッドクエリシステム

  • クエリをグラフ中心、ベクトル中心、ハイブリッドのいずれかにスマートに振り分けます
  • Neo4j と Qdrant からデータを並列取得します
  • 引用の追跡を必須とする、データベース横断の統合を行います
  • 矛盾を検出し、情報源に優先順位を付けます

• KNOWLEDGE_EXTRACT ワークフロー：F-Contraction による動的なナレッジ抽出

  • メタデータを抽出しながらドキュメントを取り込みます
  • 二重ストレージ：テキストチャンクを Qdrant に、エンティティを Neo4j に保存します
  • LLM を活用してエンティティを抽出し、関係を発見します
  • 情報源を保持しながら、F-Contraction により類似する概念を統合します
  • グラフデータとベクトルデータ間の相互参照をマッピングします
  • 品質を検証し、抽出結果をレポートします

調査分析機能：

• 引用グラフの構築：論文、著者、機関のネットワークを構築します
• マルチホップ統合：関連する情報源をたどり、概念の変遷を追跡します
• 時間的分析：経時的な変化や進展を追跡します
• 矛盾の解決：複数の情報源から得られた矛盾する情報を処理します
• 情報源の帰属：生データから結論まで、完全な来歴を追跡します

統合機能：

• Qdrant コレクション：セマンティック検索のためにベクトルデータベースとシームレスに統合します
• データベース横断ナビゲーション：構造化データとセマンティックデータを双方向にリンクします
• メモリ統合：長期メモリシステムと接続し、継続性を保ちます
• MCP オーケストレーション：高度なツール連携とワークフロー管理を行います

Cypher スニペットツールキット

MCP サーバーには、Cypher クエリスニペットを管理および検索するためのツールキットが含まれています。

• list_cypher_snippets：任意の条件で絞り込んで、利用可能な Cypher スニペットをすべて一覧表示します
• get_cypher_snippet：ID を指定して、特定の Cypher スニペットを取得します
• search_cypher_snippets：キーワード、タグ、パターンで Cypher スニペットを検索します
• create_cypher_snippet：新しい Cypher スニペットをデータベースに追加します
• update_cypher_snippet：既存の Cypher スニペットを更新します
• delete_cypher_snippet：Cypher スニペットをデータベースから削除します
• get_cypher_tags：Cypher スニペットで使用されているタグをすべて取得します

このツールキットは、参照や学習に利用できる Cypher クエリパターンと例の検索可能なリポジトリを提供します。

ツール提案システム

MCP サーバーには、新しいツールを提案およびリクエストするためのシステムが含まれています。

• propose_tool：NeoCoder システム用の新しいツールを提案します
• request_tool：ユーザーとして、新しいツール機能をリクエストします
• get_tool_proposal：特定のツール提案の詳細を取得します
• get_tool_request：特定のツールリクエストの詳細を取得します
• list_tool_proposals：任意の条件で絞り込んで、ツールの提案をすべて一覧表示します
• list_tool_requests：任意の条件で絞り込んで、ツールのリクエストをすべて一覧表示します

このシステムを利用すると、AI アシスタントが新しいツールを提案し、ユーザーが新機能をリクエストできます。また、機能リクエストを構造化された方法で管理し、追跡できます。

テンプレートのカスタマイズ

テンプレートは、templates ディレクトリに .cypher ファイルとして保存されています。既存のテンプレートを編集することも、新しいテンプレートを作成することもできます。

新しいテンプレートを追加するには：

1. templates ディレクトリに新しいファイルを作成します（例：custom_template.cypher）
2. 既存のテンプレートの形式に従います
3. データベースを初期化し、テンプレートを Neo4j に読み込みます

「Cypher Snippet Toolkit」ツールは、以下に定義されたグラフ構造を使用します

以下は、Neo4j Browser、Cypher shell、または任意のドライバーにそのまま貼り付けられる、Neo4j 5 シリーズ対応のツールキットをまとめたものです。 これにより、すべての (:CypherSnippet) ノードが Cypher 構文、例、メタデータを格納する ミニドキュメント用グラフ が作成されます。テキストインデックスと（任意の）ベクトルインデックスを使うことで、通常のキーワード または 埋め込みベクトルからスニペットをすぐに検索できます。

---

1 · スキーマと安全性に関する制約

// 1-A Uniqueness for internal IDs
CREATE CONSTRAINT cypher_snippet_id IF NOT EXISTS
FOR   (c:CypherSnippet)
REQUIRE c.id IS UNIQUE;            // Neo4j 5 syntax

// 1-B Optional tag helper (one Tag node per word/phrase)
CREATE CONSTRAINT tag_name_unique IF NOT EXISTS
FOR   (t:Tag)
REQUIRE t.name IS UNIQUE;

2 · 検索を支えるインデックス

// 2-A Quick label/property look-ups
CREATE LOOKUP INDEX snippetLabelLookup IF NOT EXISTS
FOR (n) ON EACH labels(n);

// 2-B Plain-text index (fast prefix / CONTAINS / = queries)
CREATE TEXT INDEX snippet_text_syntax IF NOT EXISTS
FOR (c:CypherSnippet) ON (c.syntax);

CREATE TEXT INDEX snippet_text_description IF NOT EXISTS
FOR (c:CypherSnippet) ON (c.description);

// 2-C Full-text scoring index (tokenised, ranked search)
CREATE FULLTEXT INDEX snippet_fulltext IF NOT EXISTS
FOR (c:CypherSnippet) ON EACH [c.syntax, c.example];

// 2-D (OPTIONAL) Vector index for embeddings ≥Neo4j 5.15
CREATE VECTOR INDEX snippet_vec IF NOT EXISTS
FOR (c:CypherSnippet) ON (c.embedding)
OPTIONS {indexConfig: {
  `vector.dimensions`: 384,
  `vector.similarity_function`: 'cosine'
}};

ビルドが 5.14 以下の場合は、代わりに db.index.vector.createNodeIndex を呼び出してください。

3 · スニペットを保存するテンプレート

:params {
  snippet: {
    id:         'create-node-basic',
    name:       'CREATE node (basic)',
    syntax:     'CREATE (n:Label {prop: $value})',
    description:'Creates a single node with one label and properties.',
    example:    'CREATE (p:Person {name:$name, age:$age})',
    since:      5.0,
    tags:       ['create','insert','node']
  }
}

// 3-A MERGE guarantees idempotence
MERGE (c:CypherSnippet {id:$snippet.id})
SET   c += $snippet
WITH  c, $snippet.tags AS tags
UNWIND tags AS tag
  MERGE (t:Tag {name:tag})
  MERGE (c)-[:TAGGED_AS]->(t);

パラメータマップを使うと、コードを再利用でき、クエリプランの再コンパイルを防げます。

4 · 検索方法

4-A TEXT インデックスによる完全一致／前方一致

MATCH (c:CypherSnippet)
WHERE c.name STARTS WITH $term      // fast TEXT index hit
RETURN c.name, c.syntax, c.example
ORDER BY c.name;

4-B ランク付けされた全文検索

CALL db.index.fulltext.queryNodes(
  'snippet_fulltext',               // index name
  $q                                // raw search string
) YIELD node, score
RETURN node.name, node.syntax, score
ORDER BY score DESC
LIMIT 10;

4-C 埋め込みの類似性（ベクトル検索）

WITH $queryEmbedding AS vec
CALL db.index.vector.queryNodes(
  'snippet_vec', 5, vec            // top-5 cosine hits
) YIELD node, similarity
RETURN node.name, node.syntax, similarity
ORDER BY similarity DESC;

5 · スニペットの更新または削除

// 5-A Edit description
MATCH (c:CypherSnippet {id:$id})
SET   c.description = $newText,
      c.lastUpdated = date()
RETURN c;

// 5-B Remove a snippet cleanly
MATCH (c:CypherSnippet {id:$id})
DETACH DELETE c;

どちらの操作でもインデックスの整合性は自動的に保たれるため、追加の作業は不要です。

6 · 一括エクスポート／インポート（APOC）

CALL apoc.export.cypher.all(
  'cypher_snippets.cypher',
  {useOptimizations:true, format:'cypher-shell'}
);

これにより、共有可能な Cypher が出力され、cypher-shell < cypher_snippets.cypher で再実行できます。

---

クイックスタートのまとめ

1. 制約とインデックスを設定するため、データベースごとに一度、セクション 1 と 2 を実行します。
2. 新しいドキュメント項目を追加するには、セクション 3（パラメータ駆動）を使用します。
3. セクション 4 でクエリを実行します。埋め込みを保存する場合は、ベクトル検索を追加することもできます。
4. セクション 6 を使ってバックアップまたは公開します。

これらの構成要素を使うと、常にローカルに保存され、バージョン管理や拡張が可能な、検索できる 「Cypher の中の Cypher チートシート」 が実現します。クエリのレパートリーが増えても、必要な情報を手軽に呼び出せます！

注：元の書式をすべて保持した、このドキュメントの完全なリファレンス版は /docs/cypher_snippets_reference.md ファイルにあります。

作成者：angrysky56 Claude 3.7 Sonnet Gemini 2.5 Pro Preview 3-25 ChatGPT o3

コード分析

NeoCoder のコードベースに関する包括的な分析は、/analysis ディレクトリにあります。以下が含まれます：

• アーキテクチャの概要
• インカーネーションシステムの分析
• コードメトリクスと構造
• ワークフローテンプレートの分析
• 統合ポイント
• 今後の開発に関する推奨事項

最近の更新

2025-06-24：革新的なハイブリッド推論システム（v2.0.0）

• 画期的な進歩：Neo4j + Qdrant + LLM による統合を実現する、コンテキスト拡張型推論アーキテクチャを実装
• 新機能：KNOWLEDGE_QUERY アクションテンプレート — 3 ステップのハイブリッド推論システム：
  • スマートクエリルーター：AI が意図を分類し、実行戦略を計画します
  • 並列データ取得：Neo4j と Qdrant の両方にシームレスにクエリを実行します
  • データベース横断シンセサイザー：引用の追跡を必須とするインテリジェントな統合を行います
• 新機能：KNOWLEDGE_EXTRACT アクションテンプレート — F-Contraction によるナレッジ統合：
  • ドキュメントをグラフ表現とベクトル表現の両方に動的に処理します
  • LLM を活用したエンティティ抽出と関係性の発見
  • ソース情報を保持しながら、概念をインテリジェントに統合します
  • 構造化データと意味データの間の相互参照マッピング
• 強化：高度なハイブリッド機能を備えたナレッジグラフのインカーネーション：
  • ガイダンスハブのトランザクションエラーを修正し、シームレスなユーザー体験を実現
  • 高度な調査分析ワークフローを実装
  • 競合検出とソースの優先順位付けを追加
  • 意味検索のための Qdrant ベクトルデータベースとの完全な統合
• アーキテクチャ：従来の RAG をはるかに超える、コンテキスト拡張型推論の基盤を確立
• 検証：実際の研究論文コーパスを使用したテストに成功し、引用グラフと意味分析を実証
• 効果：単一のデータソースでは実現できない、かつてないナレッジ統合を可能にします

2025-06-14：非同期処理／イベントループ管理の重大な問題を修正（v1.4.1）

• 重大な修正：safe_neo4j_session 関数における非同期コンテキストマネージャープロトコルのエラーを解決
• 根本原因：テスト内の AsyncMock と一部のドライバー構成が、非同期コンテキストマネージャーではなくコルーチンを返していました
• 解決策：コルーチンとコンテキストマネージャーの両方を検出し、適切に処理する _handle_session_creation ヘルパー関数を追加
• 効果：「TypeError: 'coroutine' object does not support the asynchronous context manager protocol」エラーを解消
• テスト：再発防止のため、包括的なテストスイート（test_event_loop_fix.py）を追加
• 互換性：既存の Neo4j ドライバーの使用方法との完全な後方互換性を維持
• 変更ファイル：src/mcp_neocoder/event_loop_manager.py、tests/test_event_loop_fix.py

2025-04-27：AST/ASG 対応のコード分析インカーネーションを追加（v1.4.0）

• AST と ASG のツールを使用した詳細なコード分析を行う code_analysis_incarnation.py を新たに追加
• コード構造と分析結果を保存する Neo4j スキーマを実装
• ステップごとのワークフローを備えた CODE_ANALYZE アクションテンプレートを追加
• コード分析専用ツールを作成：
  • analyze_codebase：ディレクトリ構造全体を分析
  • analyze_file：個々のファイルを詳細に分析
  • compare_versions：コードの異なるバージョンを比較
  • find_code_smells：潜在的なコード上の問題を特定
  • generate_documentation：コードドキュメントを自動生成
  • explore_code_structure：コード構造をナビゲート
  • search_code_constructs：コード内の特定のパターンを検索
• 外部 AST/ASG ツールと統合
• ガイダンスハブに適切なドキュメントを追加
• IncarnationType enum を更新し、CODE_ANALYSIS タイプを追加

2025-04-27：ナレッジグラフのトランザクションエラーメッセージを解消（v1.3.2）

• ナレッジグラフ機能でトランザクションスコープの問題に関連するエラーメッセージを完全に解消
• よりスムーズなユーザー体験を実現するため、サーバー側でエラーメッセージを捕捉して置き換える処理を実装
• すべてのデータベース操作に、より安全な新しい実行パターンを追加：
  • 書き込み操作でトランザクションスコープエラーを解消する _safe_execute_write メソッドを作成
  • 読み取り操作で適切なトランザクション処理を確保する _safe_read_query メソッドを作成
  • 正確な操作結果のフィードバックを実現するため、エンティティ数の追跡を改善
• JSON の解析に失敗した場合でも操作を継続できるよう、エラー復旧機能を強化
• すべてのナレッジグラフツールの実装を簡素化し、改善
• 既存のナレッジグラフデータとの完全な後方互換性を維持
• より明確な使用例を追加してガイダンスハブを強化

2025-04-27：ナレッジグラフのトランザクションスコープの問題を修正（v1.3.1）

• ナレッジグラフ機能で「transaction out of scope」エラーが返される重大な問題を修正
• すべてのナレッジグラフ操作に、トランザクションセーフな方法を実装
• すべてのナレッジグラフツールを更新し、トランザクションコンテキストを適切に処理するよう修正：
  • create_entities が適切に結果を返すよう修正
  • 簡素化した方法で create_relations を修正
  • データが確実にコミットされるよう add_observations を修正
  • delete_entities、delete_observations、delete_relations 関数を修正
  • 複数の安全なトランザクションでデータを取得するよう read_graph を修正
  • より堅牢なクエリ方法で search_nodes を修正
  • エンティティの詳細を安全にクエリするよう open_nodes を修正
• ナレッジグラフツールの使用例を明確にして、ガイダンスハブを強化
• ナレッジグラフ操作全体のエラー処理を改善
• 既存のナレッジグラフデータとの後方互換性を維持

2025-04-26：ナレッジグラフ API 関数を修正（v1.3.0）

• ナレッジグラフ API 関数が Neo4j のノードラベル付けシステムと適切に連携しない問題を修正
• 汎用の :KnowledgeNode ではなく、:Entity ラベルを適切に付与したエンティティを実装
• ナレッジグラフ管理機能一式を追加：
  • create_entities：適切なラベルと観察情報を付与してエンティティを作成
  • create_relations：型付きのリレーションシップでエンティティを接続
  • add_observations：既存のエンティティに観察情報を追加
  • delete_entities：エンティティとその接続を削除
  • delete_observations：エンティティから特定の観察情報を削除
  • delete_relations：エンティティ間のリレーションシップを削除
  • read_graph：ナレッジグラフの全体構造を表示
  • search_nodes：名前、種類、観察内容からエンティティを検索
  • open_nodes：特定のエンティティの詳細情報を取得
• フォールバック機能付きの全文検索サポートを追加し、全文検索に対応していない環境にも対応
• ナレッジグラフ用の制約とインデックスを含む適切なスキーマ初期化機能を追加
• 新しい API 関数の使用方法を説明する内容でガイダンスハブを更新

2025-04-25：インカーネーションのドキュメントを拡充（v1.2.0）

• 複数のインカーネーションを支えるアーキテクチャ原則に関する詳細なドキュメントを追加
• 各インカーネーションの種類について、運用パターンとユースケースの説明を強化
• インカーネーション間で共通するグラフスキーマのモチーフに関する情報を追加
• 量子に着想を得たアプローチを統合するための実装ロードマップを掲載

2025-04-24：インカネーションツールの登録を修正（v1.1.0）

• サーバーの起動時にインカネーションツールが正しく登録されない問題を修正しました
• クラス定義の重複による循環依存の問題を修正しました
• _tool_methods クラス属性によるツールメソッドの明示的な宣言をサポートしました
• 各インカネーションのすべてのツールが正しく検出されるよう、ツール検出メカニズムを改善しました
• サーバーの初期化中に問題が発生しないよう、イベントループの処理を強化しました
• トラブルシューティングに役立つ包括的なログ機能を追加しました
• 必要になるまで適切に遅延されるよう、スキーマの初期化を修正しました

実装に関する詳細なメモは、CHANGELOG.md ファイルを参照してください。

ライセンス

MIT License