Almacenamiento de Contexto de Código MCP

code-context-storage-mcp es el servicio de almacenamiento local y protocolo MCP para la base de conocimiento de contexto de código. Guarda nodos de código, aristas de llamadas, información semántica, evidencia, directorio/mapeo de negocio y snapshots de versiones en SQLite, y expone herramientas estructuradas a través del transporte stdio de FastMCP.

El proyecto se posiciona entre "Skill / IA externa" y las capacidades de negocio persistentes: los llamadores leen y escriben la base de conocimiento a través de las herramientas MCP y no deben acceder directamente a SQLite. El MVP está orientado a un único repositorio de código y una versión fija del código fuente, con enfoque en la importación de índices/artefactos, consultas restringidas por versión, mapeo de negocio, validación de evidencia, sincronización incremental, publicación de snapshots y evaluación.

Características

• Persistencia de hechos de código en SQLite: node, edge, evidence, node_semantic.

• Recuperación de nodos basada en semántica y términos de negocio, así como contexto de grafo, rutas y análisis de impacto con restricción de presupuesto.

• Directorio de negocio, contexto, mapeo y pasos de mapeo; los resultados candidatos y confirmados tienen estados explícitos.

• Flujo de publicación de snapshots de staging → published, con operaciones idempotentes, protección de concurrencia CAS y propagación/recuperación de stale.

• Envelope de protocolo MCP v2: request_id, operation_id, versión de schema/tool y errores estructurados.

• Cobertura de pruebas para escenarios de unidad, contrato, caja negra y adaptador MCP stdio real.

Lo que está fuera del alcance de este proyecto incluye la generación/ejecución de código, el grafo unificado entre repositorios, el modelado automático de negocio sin confirmación humana y la mezcla de observaciones de runtime con hechos de código estáticos. Los límites completos se encuentran en el documento de diseño del MVP.

Related MCP server: local-code-intel-mcp

Requisitos

• Python 3.11 o superior

• pip

• El directorio de trabajo en los ejemplos de Windows PowerShell es la raíz de este repositorio

Las dependencias se declaran en pyproject.toml; la dependencia principal de runtime es fastmcp==3.4.7.

Instalación

Se recomienda usar un entorno virtual:

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

Si PowerShell bloquea el script de activación, puede omitir la activación del entorno y ejecutar directamente los siguientes comandos con .\.venv\Scripts\python.exe.

Ejecutar el servidor MCP

Después de la instalación, use el punto de entrada de línea de comandos proporcionado por el proyecto:

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

O use directamente el punto de entrada del módulo:

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

Ambos métodos de inicio utilizan el transporte stdio. El proceso lee mensajes MCP JSON-RPC desde stdin y escribe las respuestas en stdout, por lo tanto no agregue registros normales a stdout; la ruta predeterminada de la base de datos es .data/context.db, y se puede especificar otro archivo SQLite con --database.

Ver los argumentos de línea de comandos:

code-context-storage-mcp --help

Configuración del cliente MCP

El cliente stdio debe iniciar el siguiente comando y escribir las solicitudes en stdin:

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

Si el script de consola no está instalado, puede cambiar command a Python y args a:

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

Después de conectarse, el cliente debe llamar a tools/list de MCP para ver las herramientas registradas actualmente y sus schemas de entrada. Las herramientas cubren escritura/lectura de hechos de código, consultas de grafo, directorio y mapeo de negocio, control de sincronización, publicación, evidencia, generación de conocimiento y evaluación; el conjunto específico de registros se rige por el tools/list devuelto por el servicio en tiempo de ejecución.

Comandos de desarrollo

Ejecute en la raíz del repositorio:

python -m pytest tests -q

Ejecutar pruebas de caja negra:

python -m pytest tests\blackbox -q

Los escenarios en las pruebas de caja negra que requieren un servicio MCP stdio real pueden configurar el comando del servicio:

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

Algunas pruebas de caja negra se omitirán si falta esta configuración; en CI, debe configurarse explícitamente para que las pruebas expongan problemas de configuración o protocolo.

Aceptación y evaluación de fases

Generar el informe de aceptación de fase y su solicitud de evaluación asociada:

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

Ejecutar la evaluación fuera de línea con la solicitud generada y los umbrales:

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 usa un conjunto de respuestas vacío por defecto, adecuado para validar el pipeline de evaluación y los contratos de entrada; para obtener resultados de evaluación significativos, debe proporcionar respuestas de caja negra del cliente MCP con --responses. El script termina con un código de salida distinto de cero cuando el estado de evaluación no es passed.

Estructura del repositorio

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/                设计文档

La cadena principal de ejecución es: server.main -> Store -> create_mcp_server -> ToolRouter -> handlers/services -> SQLite. Las operaciones de escritura generalmente entran primero en staging, y después de pasar por puertas como conflictos/cobertura, se publica el snapshot; las consultas se fijan en un snapshot y una revisión de fuente, y devuelven un contexto de ejecución trazable.

Datos y migraciones

El archivo de base de datos predeterminado .data/context.db son datos de runtime y no deben enviarse al repositorio. El schema se mantiene mediante los archivos SQL en migrations/; antes de conectar una base de datos existente con código nuevo, debe confirmarse que la migración correspondiente se haya aplicado. Las pruebas generalmente usan bases de datos SQLite temporales, por lo que no dependen del archivo de datos predeterminado en la máquina de desarrollo.

Licencia

El repositorio actual no proporciona un archivo de licencia independiente; si se va a publicar externamente, primero debe agregarse la licencia y las instrucciones de contribución.