ADR: bib_list_endpoints lee de bib_nodes en lugar de bib_endpoints

Fecha: 2026-04-25
Estado: Aceptada
Sesión: 27 (plan post-audit I5-4)
Autor: @Esquembri / agent-ingest

Contexto

La MCP tool bib_list_endpoints del handler biblioteca.ts (CF Workers) consultaba la tabla bib_endpoints en D1 para devolver los endpoints del sistema. Tras un cambio del indexer, esta tabla quedó vacía y nunca fue repoblada. Como resultado, la tool siempre devolvía [] con independencia de los filtros aplicados.

El grafo de conocimiento sí contenía los endpoints: 496 nodos con node_type = 'endpoint' en bib_nodes, cada uno con su método, path y metadatos en el campo JSON metadata.

Decisión

Abandonar bib_endpoints como fuente primaria de la tool bib_list_endpoints.
Leer directamente de bib_nodes WHERE node_type = 'endpoint', extrayendo method, path y operationId del campo metadata JSON.

Implementación

-- Antes (tabla vacía)
SELECT ep.*, n.qualified_name, n.app
FROM bib_endpoints ep
JOIN bib_nodes n ON ep.node_id = n.id
WHERE 1=1
[+ filtros por n.app, ep.method, ep.path]
ORDER BY ep.path LIMIT ?

-- Ahora
SELECT id, qualified_name, display_name, app, metadata
FROM bib_nodes
WHERE node_type = 'endpoint'
[+ filtros por app, qualified_name LIKE]
ORDER BY qualified_name LIMIT ?

El mapeo de filtros:

• args.method → qualified_name LIKE '<METHOD>:%' (el qualified_name sigue el patrón METHOD:path).
• args.path_contains → qualified_name LIKE '%<path>%'.

El response object se construye parseando metadata JSON:

{
  id, qualified_name,
  method: meta.method ?? qualified_name.split(':')[0],
  path: meta.path ?? qualified_name.split(':').slice(1).join(':'),
  operation_id: meta.operationId ?? display_name,
  tags: meta.tags ?? [],
  app,
}

Consecuencias

Positivas

• Problema operativo resuelto: 496 endpoints accesibles inmediatamente.
• Sin datos duplicados: una única fuente de verdad para endpoints (el grafo).
• Sin migración: no se requiere repoblar bib_endpoints.

Negativas / Deuda

• La tabla bib_endpoints queda oficialmente obsoleta para este propósito pero sigue existiendo en el schema D1. Candidata a deprecar/eliminar en Fase 8.
• Los filtros sobre method y path son aproximados (via LIKE sobre qualified_name) en lugar de columnas dedicadas — suficiente para el uso actual.

Sub-bloque diferido

• I5-5 (Edges documents para 496 endpoints): generación automática de edges documents para los 496 endpoints requiere parser de menciones path en pages con validación de false positives. Diferido a Fase 8 Enrichment Agent.

Alternativas consideradas

Véase también

• [[feature—supercontext—i5-plataforma-wiki-mcp-fix]]
• [[concept—supercontext—grafo-conocimiento]]
• [[entity—supercontext—handler—biblioteca-mcp]]
• [[concept—supercontext—biblioteca-mcp-tools]]
• [[entity—supercontext—d1—bib-nodes]]