Context Portal MCP (ConPort)

Context Portal MCP サーバー（ConPort）とは？

Context Portal（ConPort）は、プロジェクトのメモリーバンクです。意思決定、タスク、アーキテクチャパターンなどの重要な情報を構造化して保存することで、AI アシスタントが特定のソフトウェアプロジェクトをより深く理解できるよう支援するツールです。AI が簡単にアクセスして活用し、より正確で役立つ回答を提供できる、プロジェクト固有のナレッジベースを構築するものと考えてください。

できること：

• プロジェクトの意思決定、進捗、システム設計を記録します。
• 用語集や仕様書など、プロジェクト固有のデータを保存します。
• スマート検索のように、AI が関連するプロジェクト情報をすばやく見つけられるようにします。
• AI がプロジェクトのコンテキストを活用して、より良い回答を提供できるようにします（RAG）。
• シンプルなテキストファイルベースのメモリーバンクに比べて、コンテキストの管理、検索、更新をより効率的に行えます。

ConPort は、AI アシスタントがさまざまな種類のプロジェクトコンテキストを保存、取得、管理するための、堅牢で構造化された方法を提供します。意思決定、進捗、アーキテクチャなどのエンティティと、それらの関係を記録して、プロジェクト固有のナレッジグラフを効果的に構築します。ベクトル埋め込みによるセマンティック検索機能を強化したこの構造化ナレッジベースは、**検索拡張生成（RAG）**の強力なバックエンドとして機能し、AI アシスタントが正確で最新の情報にアクセスして、コンテキストをより適切に反映した正確な回答を提供できるようにします。

従来のファイルベースのコンテキスト管理システムに代わり、より信頼性が高く、クエリ可能なデータベースバックエンド（ワークスペースごとの SQLite）を提供します。ConPort は汎用コンテキストバックエンドとして設計されており、MCP に対応するさまざまな IDE やクライアントインターフェースと互換性があります。

主な機能：

• SQLite を使用した構造化コンテキストストレージ（ワークスペースごとに 1 つの DB を自動作成）。
• Python/FastAPI で構築された MCP サーバー（context_portal_mcp）。
• 利用可能な MCP ツールの包括的なセット（詳細は以下の「利用可能な ConPort ツール」を参照）。
• workspace_id による複数ワークスペースのサポート。
• 主なデプロイモードは、IDE と緊密に連携する STDIO です。
• コンテキスト項目間の明示的な関係を持つ、動的なプロジェクトナレッジグラフの構築を可能にします。
• 高度な RAG を実現するベクトルデータストレージとセマンティック検索機能を備えています。
• **検索拡張生成（RAG）**の理想的なバックエンドとして、AI に正確でクエリ可能なプロジェクトメモリーを提供します。
• 構造化されたコンテキストを提供し、対応する LLM プロバイダーで AI アシスタントがプロンプトキャッシュを活用できるようにします。
• Alembic マイグレーションを使用してデータベーススキーマの変更を管理し、シームレスな更新とデータの整合性を確保します。

前提条件

作業を始める前に、以下がインストールされていることを確認してください。

• Python： バージョン 3.8 以上を推奨します。
  • Python をダウンロード
  • インストール時に Python がシステムの PATH に追加されるようにしてください（特に Windows の場合）。
• uv：（強く推奨）高速な Python 環境・パッケージマネージャーです。uv を使うと、仮想環境の作成と依存関係のインストールが大幅に簡単になります。
  • uv をインストール

インストールと設定（推奨）

ConPort をインストールして実行する推奨方法は、uvx を使用して PyPI からパッケージを直接実行することです。この方法では、仮想環境を手動で作成、管理する必要がありません。

uvx の設定（ほとんどの IDE で推奨）

MCP クライアントの設定（例：mcp_settings.json）で、次の設定を使用してください。

{
  "mcpServers": {
    "conport": {
      "command": "uvx",
      "args": [
        "--from",
        "context-portal-mcp",
        "conport-mcp",
        "--mode",
        "stdio",
        "--workspace_id",
        "${workspaceFolder}",
        "--log-file",
        "./logs/conport.log",
        "--log-level",
        "INFO"
      ]
    }
  }
}

• command：uvx が環境を処理します。
• args：ConPort サーバーを実行するための引数です。
• ${workspaceFolder}：現在のプロジェクトワークスペースの絶対パスを自動的に指定するために使われる IDE 変数です。
• --log-file：任意：サーバーログを書き込むファイルのパスです。指定しない場合、ログは stderr（コンソール）に出力されます。ログを継続的に記録し、サーバーの動作をデバッグする場合に便利です。
• --log-level：任意：サーバーの最小ログレベルを設定します。有効な選択肢は DEBUG、INFO、WARNING、ERROR、CRITICAL です。デフォルトは INFO です。開発中やトラブルシューティング中に詳細な出力を得るには、DEBUG に設定してください。

重要：多くの IDE は、MCP サーバーの起動時に ${workspaceFolder} を展開しません。次のいずれかの安全な方法を使用してください。

1. --workspace_id に絶対パスを指定します。
2. 起動時に --workspace_id を省略し、呼び出しごとの workspace_id に頼ります（クライアントが毎回指定する場合に推奨）。

代替設定（起動時に --workspace_id を指定しない場合）：

{
  "mcpServers": {
    "conport": {
      "command": "uvx",
      "args": [
        "--from",
        "context-portal-mcp",
        "conport-mcp",
        "--mode",
        "stdio",
        "--log-file",
        "./logs/conport.log",
        "--log-level",
        "INFO"
      ]
    }
  }
}

--workspace_id を省略すると、サーバーは事前初期化をスキップし、最初のツール呼び出し時に、その呼び出しで指定された workspace_id を使ってデータベースを初期化します。

開発者向けインストール（Git リポジトリから）

ConPort の開発とテストには、上記の設定を使って IDE で MCP サーバーとして実行するのが最適です。これにより、STDIO モードと実際のクライアントの動作を確認できます。

ローカルのチェックアウトと仮想環境を使用して実行する必要がある場合は、MCP クライアントを設定し、uv run と .venv/bin/python を使って開発サーバーを起動できます。

{
  "mcpServers": {
    "conport": {
      "command": "uv",
      "args": [
        "run",
        "--python",
        ".venv/bin/python",
        "--directory",
        "<path to context-portal repo> ",
        "conport-mcp",
        "--mode",
        "stdio",
        "--log-file",
        "./logs/conport-dev.log",
        "--log-level",
        "DEBUG"
      ],
      "disabled": false
    }
  }
}

注意：

• --directory にはリポジトリのパスを設定します。これにより、ローカルのチェックアウトと仮想環境のインタープリターが使われます。
• ログは DEBUG の詳細度で ./logs/conport-dev.log に出力されます。

ローカル環境のセットアップ

Git リポジトリを使って開発やコントリビュートを行うためのセットアップです。

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

   git clone https://github.com/GreatScottyMac/context-portal.git
   cd context-portal
   

2. 仮想環境を作成する

   uv venv
   

   シェルの標準的な方法で有効化します（例：macOS/Linux では source .venv/bin/activate）。

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

   uv pip install -r requirements.txt
   

4. IDE で実行する（推奨） 上記の「uvx の設定」または開発用の uv run の設定を使って、IDE の MCP 設定を行います。これは STDIO モードでの ConPort の動作を最も適切にテストする方法です。

5. 任意：CLI のヘルプ

   uv run python src/context_portal_mcp/main.py --help
   

注意：

• --workspace_id の動作と IDE のパス処理については、上記の「uvx の設定」セクションの説明を参照してください。多くの IDE は ${workspaceFolder} を展開しません。

Python のバイトコードキャッシュの消去を含むアップグレード前のクリーンアップについては、v0.2.4_UPDATE_GUIDE.md を参照してください。

LLM エージェントでの使用（カスタム指示）

ConPort の LLM エージェントでの効果は、LLM に具体的なカスタム指示やシステムプロンプトを与えることで大幅に高まります。このリポジトリには、さまざまな環境に合わせた戦略ファイルが含まれています。

• Roo Code 用：

  • roo_code_conport_strategy：Roo Code VS Code 拡張機能内で動作する LLM 向けの詳細な指示が含まれており、コンテキスト管理に ConPort ツールを使用する方法を説明しています。
  
  

• CLine 用：

  • cline_conport_strategy：Cline VS Code 拡張機能内で動作する LLM 向けの詳細な指示が含まれており、コンテキスト管理に ConPort ツールを使用する方法を説明しています。
  
  

• Windsurf Cascade 用：

  • cascade_conport_strategy：Windsurf Cascade 環境に統合された LLM 向けの具体的なガイダンスです。重要：Cascade でセッションを開始する際は、LLM に明示的に次のように伝える必要があります。

  Initialize according to custom instructions
  

• 汎用／プラットフォーム非依存での使用：

  • generic_conport_strategy：MCP に対応するあらゆる LLM 向けに、プラットフォームに依存しない一連の指示を提供します。ConPort の get_conport_schema オペレーションを使用して、正確な ConPort ツール名とそのパラメーターを動的に検出することを重視しています。また、ツール呼び出しの詳細をハードコードするのではなく、判断の記録やプロダクトコンテキストの更新など、概念的な操作を「いつ」「なぜ」実行するかを LLM に案内します。
  
  

これらの戦略ファイルの使用方法：

1. LLM エージェントの環境に適した戦略ファイルを選びます。
2. そのファイルの内容全体をコピーします。
3. LLM のカスタム指示またはシステムプロンプトの入力欄に貼り付けます。手順は LLM プラットフォームによって異なります（IDE 拡張機能の設定、ウェブ UI、API の設定など）。

これらの指示により、LLM は次のことができるようになります。

• ConPort からコンテキストを初期化して読み込む。
• 新しい情報（判断、進捗など）を ConPort に追加する。
• カスタムデータとリレーションシップを管理する。
• workspace_id の重要性を理解する。 セッション開始時の重要なヒント： LLM エージェントがコンテキストを正しく初期化して読み込むようにするには、特に最初のメッセージでカスタム指示が常に厳密に守られるとは限らないインターフェースでは、次のような明確な指示からやり取りを始めると効果的です。 Initialize according to custom instructions. これにより、エージェントが戦略ファイルに定義された ConPort の初期化手順を実行するよう促せます。

新しい戦略セット：mem4sprint（新機能）

このリポジトリには、スプリント計画と運用フローに焦点を当てた新しい戦略／ドキュメントセットが含まれています。

• conport-custom-instructions/mem4sprint.md — フラットなカテゴリと有効な FTS プレフィックスを使用するための、簡潔なガイダンスとパターン。
• conport-custom-instructions/mem4sprint.schema_and_templates.md — メタスキーマ、簡潔なスターター、FTS クエリのルール、最小限の運用呼び出しレシピ。

主な内容：

• フラットなカテゴリモデル（例：artifacts、rfc_doc、retrospective、ProjectGlossary、critical_settings）。
• 有効な FTS5 プレフィックスのみを使用：カスタムデータには category:、key:、value_text:、判断には summary:、rationale:、implementation_details:、tags:。
• ハンドラーレイヤーでクエリを正規化し、データベースレイヤーは変更しません。

リリースノートの概要：

• フラット化されたカテゴリと明示的な FTS ルールを含む、mem4sprint の戦略／ドキュメントを追加しました。
• 例を簡潔にし、最小限の運用呼び出しレシピを含めました。
• ドキュメントで、MCP における IDE ワークスペースのパス処理を明確にしました。

ワークスペースでの ConPort の初期使用

新規または既存のプロジェクトワークスペースで ConPort を初めて使用するとき、ConPort データベース（context_portal/context.db）が存在しない場合は、サーバーによって自動的に作成されます。初期のプロジェクトコンテキストのセットアップ、特にプロダクトコンテキストを行うには、次の方法をご検討ください。

projectBrief.md ファイルを使用する（推奨）

1. **projectBrief.md を作成する：**プロジェクトワークスペースのルートディレクトリに、projectBrief.md という名前のファイルを作成します。
2. **内容を追加する：**プロジェクトの概要を簡潔にまとめて、このファイルに記入します。たとえば、以下の内容を含めることができます。
   • プロジェクトの主な目標や目的。
   • 主な機能やコンポーネント。
   • 想定する対象者やユーザー。
   • 全体的なアーキテクチャスタイルや主要なテクノロジー（わかっている場合）。
   • プロジェクトの基盤となるその他の情報。
3. **インポートの自動プロンプト：**提供された ConPort カスタム指示セット（例：roo_code_conport_strategy）のいずれかを使用する LLM エージェントがワークスペースで初期化されると、次の処理を行うよう設計されています。
   • projectBrief.md が存在するかどうかを確認します。
   • 存在する場合はファイルを読み込み、その内容を ConPort のプロダクトコンテキストにインポートするかどうかを尋ねます。
   • 同意すると、その内容が ConPort に追加され、プロジェクトのプロダクトコンテキストの初期情報としてすぐに利用できます。

手動での初期化

projectBrief.md が見つからない場合、またはインポートしないことを選んだ場合：

• カスタム指示に従った LLM エージェントは通常、ConPort のプロダクトコンテキストがまだ初期化されていないようだと通知します。
• ワークスペース内のほかのファイルを一覧表示して関連情報を収集するなど、プロダクトコンテキストを手動で定義する作業を支援することがあります。

projectBrief.md または手動入力によって初期コンテキストを提供すると、ConPort と接続された LLM エージェントが、開始時点からプロジェクトの基盤をより深く理解できるようになります。

ワークスペースの自動検出

ConPort は適切な workspace_id を自動的に判定できるため、MCP クライアントの設定に絶対パスをハードコードする必要はありません。これは、MCP サーバーの起動時に ${workspaceFolder} を展開できない IDE で特に便利です。

検出はデフォルトで有効になっており、CLI フラグで制御できます。

フラグ：

• --auto-detect-workspace（デフォルト：有効）自動検出を有効にします。
• --no-auto-detect 検出を無効にします（この場合、明示的な --workspace_id またはツールごとの workspace_id を指定する必要があります）。
• --workspace-search-start <path> 上方向の検索を開始するディレクトリを任意で指定します（デフォルトは現在の作業ディレクトリです）。

仕組み（複数の戦略）：

1. 強い指標（高速パス）：package.json、.git、pyproject.toml、Cargo.toml、go.mod、pom.xml のいずれかを含む、信頼度の高いプロジェクトルートを検索します。
2. 複数の一般的な指標：README、ライセンス、ビルドファイルなど、2 つ以上の一般的な指標がディレクトリ内にある場合、そのディレクトリをルートとして扱います。
3. 既存の ConPort ワークスペース：context_portal/ ディレクトリが存在する場合、有効なワークスペースであることを示します。
4. MCP 環境コンテキスト：設定されていて有効な場合、VSCODE_WORKSPACE_FOLDER や CONPORT_WORKSPACE などの環境変数を優先します。
5. フォールバック：指標が見つからない場合、開始ディレクトリを使用し、その内容を詳しくログに記録します（警告あり）。

ツール：

• get_workspace_detection_info（MCP ツール）は、次の情報を示す診断用ディクショナリを提供します。
  • start_path
  • detected_workspace
  • detection_method（strong_indicators | multiple_indicators | existing_context_portal | fallback）
  • indicators_found
  • 関連する環境変数

ベストプラクティス：

• 呼び出しごとに明示的な分離が必要なマルチルートのシナリオでない限り、検出を有効にしておいてください。
• IDE がリテラル文字列 ${workspaceFolder} を渡した場合、ConPort はそれを無視して安全に自動検出します（WARNING にログ記録されます）。
• ネストされたリポジトリなど、ルートが曖昧な場合は、検出情報ツールを実行して、選択されたディレクトリを確認してください。

自動検出のみに依存する MCP の起動例：

{
  "mcpServers": {
    "conport": {
      "command": "uvx",
      "args": [
        "--from", "context-portal-mcp",
        "conport-mcp",
        "--mode", "stdio",
        "--log-level", "INFO"
      ]
    }
  }
}

検出を明示的に無効にする場合（指定された ID のみを使用）：

{
  "mcpServers": {
    "conport": {
      "command": "uvx",
      "args": [
        "--from", "context-portal-mcp",
        "conport-mcp",
        "--mode", "stdio",
        "--no-auto-detect",
        "--workspace_id", "/absolute/path/to/project"
      ]
    }
  }
}

ランチャーが深いサブディレクトリ内で起動する場合は、より上位の開始パスを指定してください。

conport-mcp --mode stdio --workspace-search-start ../../

詳しい背景、エッジケース、トラブルシューティングについては、UNIVERSAL_WORKSPACE_DETECTION.md を参照してください。

利用可能な ConPort ツール

ConPort サーバーは MCP 経由で次のツールを公開し、基盤となるプロジェクトのナレッジグラフとのやり取りを可能にします。これには、ベクトルデータストレージを利用したセマンティック検索のツールが含まれます。これらのツールは、AI エージェントによる拡張生成（RAG）に不可欠な検索の側面を実現します。すべてのツールには、対象のプロジェクトワークスペースを指定するための workspace_id 引数（文字列、必須）が必要です。

注：利便性のため、整数のようなパラメーターはすべて、数値または数字のみの文字列（例：「10」、「 3」）のどちらでも指定できます。サーバーは空白を削除して整数に変換し、その際に検証範囲（例：ge=1）は維持します。謝辞：@cipradu。

• 製品コンテキスト管理：
  • get_product_context：プロジェクト全体の目標、機能、アーキテクチャを取得します。
  • update_product_context：製品コンテキストを更新します。全体を置き換えるcontent（オブジェクト）または部分更新用のpatch_content（オブジェクト）を指定できます（キーを削除するには、パッチの値に__DELETE__を指定します）。
• アクティブコンテキスト管理：
  • get_active_context：現在の作業の重点、最近の変更、未解決の問題を取得します。
  • update_active_context：アクティブコンテキストを更新します。全体を置き換えるcontent（オブジェクト）または部分更新用のpatch_content（オブジェクト）を指定できます（キーを削除するには、パッチの値に__DELETE__を指定します）。
• 決定事項の記録：
  • log_decision：アーキテクチャまたは実装に関する決定事項を記録します。
    • 引数：summary（str、必須）、rationale（str、任意）、implementation_details（str、任意）、tags（list[str]、任意）。
  • get_decisions：記録された決定事項を取得します。
    • 引数：limit（int、任意）、tags_filter_include_all（list[str]、任意）、tags_filter_include_any（list[str]、任意）。
  • search_decisions_fts：決定事項の各フィールド（summary、rationale、details、tags）を全文検索します。
    • 引数：query_term（str、必須）、limit（int、任意）。
  • delete_decision_by_id：IDを指定して決定事項を削除します。
    • 引数：decision_id（int、必須）。
• 進捗管理：
  • log_progress：進捗項目またはタスクのステータスを記録します。
    • 引数：status（str、必須）、description（str、必須）、parent_id（int、任意）、linked_item_type（str、任意）、linked_item_id（str、任意）。
  • get_progress：進捗項目を取得します。
    • 引数：status_filter（str、任意）、parent_id_filter（int、任意）、limit（int、任意）。
  • update_progress：既存の進捗項目を更新します。
    • 引数：progress_id（int、必須）、status（str、任意）、description（str、任意）、parent_id（int、任意）。
  • delete_progress_by_id：IDを指定して進捗項目を削除します。
    • 引数：progress_id（int、必須）。
• システムパターン管理：
  • log_system_pattern：システムパターンまたはコーディングパターンを記録または更新します。
    • 引数：name（str、必須）、description（str、任意）、tags（list[str]、任意）。
  • get_system_patterns：システムパターンを取得します。
    • 引数：tags_filter_include_all（list[str]、任意）、tags_filter_include_any（list[str]、任意）。
  • delete_system_pattern_by_id：IDを指定してシステムパターンを削除します。
    • 引数：pattern_id（int、必須）。
• カスタムデータ管理：
  • log_custom_data：カテゴリ内にカスタムのキーと値の項目を保存または更新します。値はJSONとしてシリアライズ可能である必要があります。
    • 引数：category（str、必須）、key（str、必須）、value（any、必須）。
  • get_custom_data：カスタムデータを取得します。
    • 引数：category（str、任意）、key（str、任意）。
  • delete_custom_data：特定のカスタムデータ項目を削除します。
    • 引数：category（str、必須）、key（str、必須）。
  • search_project_glossary_fts：カスタムデータカテゴリ「ProjectGlossary」を全文検索します。
    • 引数：query_term（str、必須）、limit（int、任意）。
  • search_custom_data_value_fts：すべてのカスタムデータの値、カテゴリ、キーを全文検索します。
    • 引数：query_term（str、必須）、category_filter（str、任意）、limit（int、任意）。
• コンテキストのリンク：
  • link_conport_items：2つのConPort項目間の関連リンクを作成し、プロジェクトのナレッジグラフを明示的に構築します。
    • 引数：source_item_type（str、必須）、source_item_id（str、必須）、target_item_type（str、必須）、target_item_id（str、必須）、relationship_type（str、必須）、description（str、任意）。
  • get_linked_items：特定の項目にリンクされた項目を取得します。
    • 引数：item_type（str、必須）、item_id（str、必須）、relationship_type_filter（str、任意）、linked_item_type_filter（str、任意）、limit（int、任意）。
• 履歴とメタツール：
  • get_item_history：製品コンテキストまたはアクティブコンテキストのバージョン履歴を取得します。
    • 引数：item_type（"product_context" | "active_context"、必須）、version（int、任意）、before_timestamp（datetime、任意）、after_timestamp（datetime、任意）、limit（int、任意）。
  • get_recent_activity_summary：最近のConPortアクティビティの概要を提供します。
    • 引数：hours_ago（int、任意）、since_timestamp（datetime、任意）、limit_per_type（int、任意、デフォルト：5）。
  • get_conport_schema：利用可能なConPortツールとその引数のスキーマを取得します。
• インポート／エクスポート：
  • export_conport_to_markdown：ConPortデータをMarkdownファイルにエクスポートします。
    • 引数：output_path（str、任意、デフォルト："./conport_export/"）。
  • import_markdown_to_conport：MarkdownファイルからConPortにデータをインポートします。
    • 引数：input_path（str、任意、デフォルト："./conport_export/"）。
• 一括操作：
  • batch_log_items：同じ種類の複数の項目（例：決定事項、進捗項目）を1回の呼び出しで記録します。
    • 引数：item_type（str、必須。例："decision"、"progress_entry"）、items（list[dict]、必須。項目の種類に対応するPydanticモデルの辞書のリスト）。

詳細情報

ConPort の設計、アーキテクチャ、高度な使用パターンについて詳しく知りたい場合は、以下を参照してください。

• conport_mcp_deep_dive.md

コントリビューション

ConPort プロジェクトへの貢献方法については、CONTRIBUTING.md ガイドをご覧ください。

ライセンス

このプロジェクトは Apache-2.0 license の下でライセンスされています。

謝辞

• さまざまなクライアントから MCP サーバーを利用する際のユーザーエクスペリエンスを向上させる、数値引数に対する整数文字列の型強制を実装する貴重な提案をしてくださった @cipradu に心より感謝いたします。

データベースの移行と更新ガイド

context.db ファイルの管理方法、特にデータベーススキーマの変更を含むバージョン間で ConPort を更新する際の詳細な手順については、専用の v0.2.4_UPDATE_GUIDE.md を参照してください。このガイドでは、必要に応じた手動でのデータ移行（エクスポート／インポート）の手順と、トラブルシューティングのヒントを紹介しています。