Code Context Storage MCP

code-context-storage-mcp는 코드 컨텍스트 지식 베이스의 로컬 저장소이자 MCP 프로토콜 서비스입니다. 코드 노드, 호출 엣지, 시맨틱 정보, 증거, 비즈니스 카탈로그/매핑, 버전 스냅샷을 SQLite에 저장하고, FastMCP의 stdio transport를 통해 구조화된 tools를 외부에 제공합니다.

이 프로젝트는 "Skill / 외부 AI"와 영속화된 비즈니스 기능 사이에 위치합니다. 호출자는 MCP tools를 통해 지식 베이스를 읽고 쓰며, 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를 호출하여 현재 등록된 도구와 입력 schema를 확인합니다. 도구는 코드 사실 쓰기/읽기, 그래프 쿼리, 비즈니스 카탈로그 및 매핑, 동기화 제어, 게시, 증거, 지식 생성 및 평가의 기능을 포괄합니다. 구체적인 등록 집합은 서비스 런타임이 반환하는 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 client의 블랙박스 응답을 제공해야 합니다. 스크립트는 평가 상태가 passed가 아닐 때 0이 아닌 종료 코드로 종료됩니다.

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에 들어가고, 충돌/커버리지 등의 게이트를 거친 후 스냅샷을 게시합니다. 쿼리는 하나의 스냅샷과 source revision에 고정되며, 추적 가능한 실행 컨텍스트를 반환합니다.

Data and migrations

기본 데이터베이스 파일 .data/context.db는 런타임 데이터이므로 버전 관리에 커밋해서는 안 됩니다. schema는 migrations/의 SQL 파일로 유지 관리됩니다. 새 코드로 기존 데이터베이스에 연결하기 전에 해당 migration이 적용되었는지 확인해야 합니다. 테스트는 일반적으로 임시 SQLite 데이터베이스를 사용하므로 개발 머신의 기본 데이터 파일에 의존하지 않습니다.

License

현재 저장소에는 별도의 라이선스 파일이 제공되지 않습니다. 외부에 배포하려면 먼저 라이선스와 기여 안내를 추가하십시오.