Code Context Storage MCP

code-context-storage-mcp is a local storage and MCP protocol service for a code context knowledge base. It stores code nodes, call edges, semantic information, evidence, business catalogs/mappings, and version snapshots in SQLite, and exposes structured tools externally via FastMCP's stdio transport.

The project sits between "Skill / external AI" and persistent business capabilities: callers read and write the knowledge base through MCP tools and must not access SQLite directly. The MVP targets a single code repository and a fixed source version, focusing on index/artifact import, version-constrained queries, business mapping, evidence validation, incremental sync, snapshot publishing, and evaluation.

Features

• SQLite persistence of code facts: node, edge, evidence, node_semantic.

• Node recall based on semantic and business terms, plus budget-constrained graph context, path, and impact analysis.

• Business catalogs, contexts, mappings, and mapping steps; candidate and confirmed results have explicit statuses.

• staging → published snapshot publishing flow with idempotent operations, CAS concurrency protection, and stale propagation/recovery.

• MCP protocol v2 envelope: request_id, operation_id, schema/tool version, and structured errors.

• Test coverage for unit, contract, black-box, and real stdio MCP adapter scenarios.

Out of scope for this project are code generation/execution, cross-repository unified graphs, automatic business modeling without human confirmation, and mixing runtime observations into static code facts. See the MVP design document for the full boundary.

Related MCP server: local-code-intel-mcp

Requirements

• Python 3.11 or later

• pip

• The working directory in the Windows PowerShell examples is the repository root

Dependencies are declared in pyproject.toml; the core runtime dependency is fastmcp==3.4.7.

Install

A virtual environment is recommended:

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

If PowerShell blocks activation scripts, you can skip activation and run the commands below directly with .\.venv\Scripts\python.exe.

Run the MCP server

After installation, use the project's command-line entry point:

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

Or use the module entry point directly:

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

Both startup methods use the stdio transport. The process reads MCP JSON-RPC messages from stdin and writes responses to stdout, so do not append ordinary logs to stdout; the default database path is .data/context.db, and a different SQLite file can be specified with --database.

View command-line arguments:

code-context-storage-mcp --help

MCP client configuration

A stdio client should launch the following command and write requests to stdin:

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

If the console script is not installed, change command to Python and args to:

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

After connecting, the client should first call MCP's tools/list to see the currently registered tools and their input schemas. Tools are grouped by capability: code fact write/read, graph queries, business catalogs and mappings, sync control, publishing, evidence, knowledge generation, and evaluation; the exact registered set is whatever tools/list returns at service runtime.

Development commands

Run from the repository root:

python -m pytest tests -q

Run black-box tests:

python -m pytest tests\blackbox -q

For scenarios in black-box tests that need a real MCP stdio service, the service command can be configured:

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

Some black-box tests skip when this configuration is missing; in CI it should be explicitly configured so the tests surface configuration or protocol issues.

Phase acceptance and evaluation

Generate the Phase acceptance report and its accompanying evaluation request:

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

Run offline evaluation with the generated request and thresholds:

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 uses an empty response set by default, which is suitable for validating the evaluation pipeline and input contract; to get meaningful evaluation results, provide black-box responses from an MCP client via --responses. The script exits with a non-zero code when the evaluation status is not 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/                设计文档

The main runtime chain is: server.main -> Store -> create_mcp_server -> ToolRouter -> handlers/services -> SQLite. Write operations typically enter staging first, then pass conflict/coverage gates before a snapshot is published; queries are pinned to a single snapshot and source revision and return a traceable execution context.

Data and migrations

The default database file .data/context.db is runtime data and must not be committed to version control. The schema is maintained by SQL files in migrations/; before connecting new code to an existing database, confirm the corresponding migration has been applied. Tests usually use temporary SQLite databases, so they do not depend on the default data file on the development machine.

License

This repository does not currently provide a standalone license file; if you plan to release it publicly, please add a license and contribution guidelines first.