Knowerage — Gestión de cobertura de análisis mediante IA

Servidor MCP local que realiza un seguimiento de la cobertura y la frescura del análisis de código heredado.

Fuente: github.com/MTimma/knowerage

Inicio rápido

Requisitos: Node.js 18 o superior — npx debe estar en tu PATH (viene con npm, que se incluye con Node).

Related MCP server: Atlas

Configuración del servidor MCP

Registra Knowerage donde tu host MCP espere las definiciones del servidor (por ejemplo, algunos clientes usan .cursor/mcp.json o .vscode/mcp.json; otros usan variables de entorno o una interfaz de usuario; sigue la documentación de tu host). Usa la misma estructura de entrada del servidor:

{
  "mcpServers": {
    "knowerage": {
      "command": "npx",
      "args": ["@mtimma/knowerage"],
      "env": {
        "KNOWERAGE_WORKSPACE_ROOT": "${workspaceFolder}",
        "KNOWERAGE_AUTO_FULL_RECONCILE": "true"
      }
    }
  }
}

Reemplaza ${workspaceFolder} con la raíz de tu proyecto si tu host no expande esa variable.

KNOWERAGE_AUTO_FULL_RECONCILE es opcional: cuando no está configurado, está vacío o no tiene un valor verdadero, el observador de archivos está desactivado por defecto. Configúralo en 1, true, yes o on (recortado, sin distinguir entre mayúsculas y minúsculas) para activarlo. Cuando está activado, el servidor observa knowerage/ y, tras un breve periodo de espera, ejecuta knowerage_reconcile_all ante cambios en el sistema de archivos. Eso no es lo mismo que ejecutar una reconciliación completa después de cada llamada a una herramienta MCP; solo reacciona a los cambios de archivo en knowerage/. Las escrituras del registro en registry.json son ignoradas por el observador para que los guardados no entren en bucle.

Cómo usar Knowerage

Una vez configurado el servidor MCP, hablas con tu asistente en frases normales. No necesitas memorizar nombres de herramientas.

Analizar o documentar código

Señala los archivos, clases o comportamientos que te interesen. Por ejemplo:

• Usando Knowerage, analiza el flujo de trabajo del algoritmo lógico en main.java.

• Analiza la lógica de reconciliación y control de versiones de entidades de datos en el servicio ETL.

El asistente crea o actualiza archivos markdown en knowerage/analysis/ y registra la cobertura en knowerage/registry.json (consulta Cómo funciona a continuación).

Cobertura y brechas (mismo proyecto, chat posterior u otro agente)

Cuando ya tienes análisis en el árbol, puedes preguntar:

• En porcentaje, ¿cuánto del código ha cubierto nuestro análisis?

• ¿Qué parte de este repositorio de código aún no se ha analizado?

Knowerage responde a esto a partir del registro y los asistentes de cobertura (por ejemplo, resumen, estado por archivo y listas de elementos obsoletos), no mediante suposiciones sobre el repositorio.

Enfoques alternativos

Instalar mediante npm

npx @mtimma/knowerage

O compilar desde el código fuente

cargo build --release
./target/release/knowerage-mcp

Cómo funciona

1. El agente de IA crea archivos de análisis .md con frontmatter YAML que declara el archivo fuente y los rangos de líneas cubiertos

2. El registro (knowerage/registry.json) realiza un seguimiento de los registros de análisis con hashes SHA-256 para verificar la frescura

3. Las herramientas MCP exponen operaciones de creación, reconciliación, consulta y exportación

4. El agente dice "analiza X" → el flujo de trabajo completo se ejecuta automáticamente (crear → reconciliar → registrar)

Estructura del archivo de registro (knowerage/registry.json)

El formato en disco es un objeto JSON cuyas claves son rutas de análisis (cadenas). Cada valor es un registro (consulta contracts/contracts.md). Un ejemplo completo con dos registros se encuentra en examples/registry.sample.json.

flowchart TB
  subgraph file["knowerage/registry.json"]
    O["Top-level JSON object"]
    O --> K["Each key: analysis markdown path, e.g. knowerage/analysis/.../topic.md"]
    K --> V["Value: one RegistryRecord"]
  end

  subgraph rec["RegistryRecord fields"]
    ap["analysis_path · source_path"]
    cr["covered_ranges: [[start,end], ...]"]
    h["analysis_hash · source_hash (sha256:… )"]
    t["record_created_at · record_updated_at (ISO 8601)"]
    st["status: fresh | stale_doc | stale_src | missing_src | dangling_doc"]
  end

  V --> rec

El frontmatter para los archivos de análisis .md se especifica por separado en el documento de contratos (esquema de metadatos), no dentro de registry.json.

Herramientas MCP

Estructura del proyecto

knowerage/                  # Created per-project
├── analysis/              # Analysis markdown files
│   └── **/*.md
└── registry.json          # Coverage registry

src/                       # Rust MCP server
├── main.rs
├── lib.rs
├── types.rs
├── parser.rs
├── registry.rs
├── mcp.rs
├── security.rs
└── export.rs

Documentación

• Onboarding del usuario — Configuración, ajustes, uso típico

• INSTRUCTIONS.md — Instrucciones para el agente MCP

• Prácticas de Rust

• Prácticas de JS

• Contratos — Esquemas y contratos de API (registro + frontmatter)

• Ejemplo de registro JSON — Contenido de ejemplo de registry.json

Seguridad

• Todas las rutas validadas contra la raíz del espacio de trabajo

• Recorrido de rutas (..) rechazado

• Escrituras atómicas para el registro (a prueba de fallos)

• Sin secretos en archivos de análisis o informes

• Frescura basada en hash SHA-256 (sobrevive a git pull)

Licencia

MIT — copyright Martins Timma.

Partes de este proyecto fueron escritas o refinadas con asistentes de codificación de IA generativa. La revisión humana se aplica al diseño, al comportamiento sensible a la seguridad y a las versiones.