Knowerage

MCP local que permite a tu agente llevar un seguimiento de la cobertura de análisis de código.

GitHub
3
Prueba este MCPPatrocinado

Documentación

Knowerage project icon

Knowerage — Gestión de Cobertura de Análisis con IA

Enlaces: GitHub · Listado MCP de Glama · npm @mtimma/knowerage

Inicio rápido

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

Configuración del servidor MCP

Registra Knowerage donde tu host MCP espere definiciones de 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 forma de entrada de 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á definido, está vacío o no es un valor verdadero, el observador de archivos se establece en off por defecto. Establécelo en 1, true, yes o on (recortado, sin distinguir mayúsculas/minúsculas) para habilitarlo. Cuando está activado, el servidor observa knowerage/ y, tras un breve debounce, 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 cambios de archivos bajo knowerage/. Las escrituras del registro en registry.json son ignoradas por el observador para que los guardados no se repitan en bucle.

Cómo usar Knowerage

Después de configurar el servidor MCP, hablas con tu asistente en frases normales. No necesitas memorizar nombres de herramientas.

Analizar o documentar código

Señala 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 versionado de entidades de datos en el servicio ETL.

El asistente crea o actualiza markdown bajo knowerage/analysis/ y registra la cobertura en knowerage/registry.json (consulta Cómo funciona más abajo).

Cobertura y vacíos (mismo proyecto, chat posterior u otro agente)

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

  • ¿En porcentaje, cuánto del código ha cubierto nuestro análisis?
  • ¿Qué parte de este código base aún no está analizada?

Knowerage responde a estas preguntas desde el registro y las utilidades de cobertura (por ejemplo, resumen, estado por archivo y listas de desactualizados)—no a partir de suposiciones sobre el repositorio.

Enfoques alternativos

Instalar vía 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) rastrea 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 completo se ejecuta automáticamente (crear → reconciliar → registrar)

Forma 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 archivos de análisis .md se especifica por separado en el documento de contratos (esquema de metadatos), no dentro de registry.json.

Herramientas MCP

HerramientaPropósito
knowerage_create_or_update_docCrear/actualizar documento de análisis
knowerage_parse_doc_metadataAnalizar y validar frontmatter
knowerage_reconcile_recordReconciliar un registro de análisis
knowerage_reconcile_allReescaneo/reconstrucción completa
knowerage_get_file_statusRangos analizados vs. faltantes
knowerage_list_staleListar registros desactualizados/problemáticos
knowerage_list_registryInstantánea completa del registro (misma forma que registry.json, claves ordenadas)
knowerage_get_treeCobertura en árbol/agrupada
registry_export_reportExportar instantánea (JSON/YAML/TXT/HTML)
knowerage_generate_bundleExportación por fragmentos de análisis seleccionados (toc*.md, combined*.md, manifest.json)

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

Seguridad

  • Todas las rutas se validan contra la raíz del espacio de trabajo
  • Se rechaza el path traversal (..)
  • Escrituras atómicas para el registro (a prueba de fallos)
  • Sin secretos en archivos de análisis ni 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 con IA generativa. La revisión humana se aplica al diseño, al comportamiento sensible a la seguridad y a los lanzamientos.