Code Context Storage MCP

code-context-storage-mcp は、コードコンテキスト知識ベースのローカルストレージおよび MCP プロトコルサービスです。コードノード、呼び出しエッジ、セマンティック情報、エビデンス、ビジネスカタログ/マッピング、バージョンスナップショットを SQLite に保存し、FastMCP の stdio transport を通じて構造化ツールを外部に提供します。

このプロジェクトは「Skill / 外部 AI」と永続化されたビジネス機能の間に位置づけられます。呼び出し側は MCP ツールを通じて知識ベースを読み書きし、SQLite に直接アクセスすべきではありません。MVP は単一のコードリポジトリと固定ソースバージョンを対象とし、インデックス/アーティファクトのインポート、バージョン制約付きクエリ、ビジネスマッピング、エビデンス検証、増分同期、スナップショット公開、評価を重点的にサポートします。

Features

• SQLite へのコードファクトの永続化：node、edge、evidence、node_semantic。

• セマンティックおよびビジネス用語に基づくノード検索、および予算制約付きのグラフコンテキスト、パス、影響分析。

• ビジネスカタログ、context、mapping、mapping steps。候補と確定結果には明確なステータスがあります。

• staging → published のスナップショット公開フロー。冪等操作、CAS 並行保護、stale 伝播/復旧を含みます。

• MCP protocol v2 envelope：request_id、operation_id、schema/tool version、構造化エラー。

• テストはユニット、コントラクト、ブラックボックス、実 stdio MCP アダプタシナリオをカバーします。

このプロジェクトの範囲外には、コード生成/実行、リポジトリ横断の統合グラフ、人間による確認なしの自動ビジネスモデリング、およびランタイム観測を静的コードファクトに混ぜることが含まれます。完全な境界は MVP 設計ドキュメント を参照してください。

Related MCP server: local-code-intel-mcp

Requirements

• Python 3.11 以降

• pip

• Windows PowerShell の例では、作業ディレクトリはこのリポジトリのルートです

依存関係は pyproject.toml で宣言され、コアランタイム依存は fastmcp==3.4.7 です。

Install

仮想環境の使用を推奨します：

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e .

PowerShell でアクティベーションスクリプトが禁止されている場合は、環境をアクティベートせずに、以下のコマンドを .\.venv\Scripts\python.exe で直接実行できます。

Run the MCP server

インストール後、プロジェクト提供のコマンドラインエントリを使用します：

code-context-storage-mcp --database .data\context.db

または、モジュールエントリを直接使用します：

python -m code_context_storage_mcp.server --database .data\context.db

どちらの起動方法も stdio transport を使用します。プロセスは stdin から MCP JSON-RPC メッセージを読み取り、応答を stdout に書き込むため、stdout に通常のログを追加しないでください。データベースのデフォルトパスは .data/context.db で、--database で別の SQLite ファイルを指定できます。

コマンドライン引数を確認するには：

code-context-storage-mcp --help

MCP client configuration

stdio クライアントは次のコマンドを起動し、リクエストを stdin に書き込む必要があります：

{
  "mcpServers": {
    "code-context-storage": {
      "command": "code-context-storage-mcp",
      "args": ["--database", ".data/context.db"]
    }
  }
}

console script がインストールされていない場合は、command を Python に変更し、args を次のようにします：

["-m", "code_context_storage_mcp.server", "--database", ".data/context.db"]

クライアントは接続後、まず MCP の tools/list を呼び出して、現在登録されているツールと入力スキーマを確認します。ツールは、コードファクトの書き込み/読み取り、グラフクエリ、ビジネスカタログとマッピング、同期制御、公開、エビデンス、知識生成、評価の能力をカバーします。具体的な登録セットは、サービス実行時に返される tools/list に従います。

Development commands

リポジトリルートで実行します：

python -m pytest tests -q

ブラックボックステストを実行するには：

python -m pytest tests\blackbox -q

ブラックボックステストで実際の MCP stdio サービスが必要なシナリオでは、サービスコマンドを設定できます：

$env:PYTHONPATH = "src"
$env:KNOWLEDGE_GENERATE_MCP_COMMAND = '["python", "-m", "code_context_storage_mcp.server"]'
python -m pytest tests\blackbox -q

一部のブラックボックステストは、この設定がない場合にスキップされます。CI では明示的に設定し、テストが設定またはプロトコルの問題を明らかにするようにしてください。

Phase acceptance and evaluation

Phase acceptance レポートとそれに付随する evaluation request を生成します：

python scripts\run_phase_acceptance.py --output artifacts\phase-acceptance.json

生成されたリクエストとしきい値を使用してオフライン評価を実行します：

python scripts\run_evaluation.py `
  --request artifacts\evaluation-request.json `
  --thresholds artifacts\thresholds.json `
  --output artifacts\evaluation-result.json `
  --database .data\context.db

run_evaluation.py はデフォルトで空の応答セットを使用し、評価パイプラインと入力コントラクトの検証に適しています。意味のある評価結果を得るには、--responses で MCP クライアントのブラックボックス応答を提供する必要があります。スクリプトは、評価ステータスが passed でない場合、非ゼロの終了コードで終了します。

Repository layout

src/code_context_storage_mcp/
  server.py                 CLI 入口，创建 Store 并启动 stdio MCP 服务
  fastmcp_server.py         FastMCP server、tool 注册和 protocol envelope
  tool_definitions.py       tool 输入 schema
  router.py                 tool 到 handler/service 的分发
  handlers/                 代码事实、图查询和业务操作处理器
  services/                 查询、同步、索引、幂等、追踪等业务服务
  publication/              发布适配与发布服务
  store.py                  SQLite 持久化
  entities.py/contracts.py  数据实体与协议契约
migrations/                 SQLite schema migrations
tests/                      单元、契约、集成和黑盒测试
scripts/                    验收与评测脚本
docs/design/                设计文档

実行のメインパスは次のとおりです：server.main -> Store -> create_mcp_server -> ToolRouter -> handlers/services -> SQLite。書き込み系の操作は通常、最初に staging に入り、競合/カバレッジなどのゲートを通過した後にスナップショットを公開します。クエリは単一のスナップショットとソースリビジョンに固定され、トレーサブルな実行コンテキストを返します。

Data and migrations

デフォルトのデータベースファイル .data/context.db はランタイムデータであり、バージョン管理にコミットすべきではありません。スキーマは migrations/ 内の SQL ファイルで管理されます。新しいコードで既存のデータベースに接続する前に、対応するマイグレーションが適用されていることを確認してください。テストは通常、一時的な SQLite データベースを使用するため、開発マシンのデフォルトデータファイルに依存しません。

License

現在のリポジトリには独立したライセンスファイルはありません。外部に公開する場合は、ライセンスと貢献に関する説明を先に追加してください。