MCP Tool: bib_ask — Búsqueda semántica en corpus de wiki

Entidadactivecreado Tue Jun 02#functions #mcp-tool #search #vectorial #ux #biblioteca #multi-tenancy #anthropic

Descripción

bib_ask es un MCP Tool que ejecuta búsqueda semántica sobre el corpus de wiki (páginas bib_wiki_pages) usando embeddings vectoriales. Responde preguntas naturales consultando la base de conocimiento de CreaRack Pro.

Firma

async function handleAsk(
  args: {
    question: string;
    source_type?: 'doc' | 'endpoint' | 'model' | 'schema';
    app?: string;
    user_facing?: boolean;
  },
  env: Env,
): Promise<string>

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
`question`	`string`	✓	Pregunta en lenguaje natural sobre CreaRack Pro
`source_type`	`'doc' \| 'endpoint' \| 'model' \| 'schema'`	-	Filtrar resultados por tipo de fuente
`app`	`string`	-	Filtrar resultados por app Django (ej: `racks`, `monitoring`)
`user_facing`	`boolean`	-	[v2.1+] Si `true`, restringe búsqueda a páginas de ayuda de usuario (product=‘crearack’ o sin marcar). Excluye documentación técnica/interna. Default: `false` (acceso total). Solo usado por Help Widget; staff y Oráculo siempre ven todo el corpus.

Flujo interno

Embedding: Transforma question a vector denso usando embeddings de Anthropic (Claude Haiku).
Búsqueda vectorial: Consulta tabla bib_wiki_chunks (Valkey cache) para encontrar chunks similares.
Filtros: Aplica filtros opcionales por source_type y app.
Corpus Help Widget: Si user_facing=true, realiza over-fetch (20 chunks) y luego filtra contra tabla bib_wiki_pages (product = ‘crearack’ o NULL), retornando solo 5 matches de ayuda real.
Construcción de respuesta: Sintetiza chunks relevantes con Claude Sonnet en un párrafo coherente.

Fuentes de datos

Tabla primaria: bib_wiki_pages (metadatos: slug, título, product, status, etc.)
Chunks vectoriales: bib_wiki_chunks (contenido fragmentado + embeddings)
Modelo LLM: Anthropic Claude Sonnet (síntesis) + Haiku (embeddings)
Cache: Valkey (búsqueda vectorial rápida)

Casos de uso

Caso	user_facing	Resultado esperado
Usuario pulsando Help Widget en interfaz	`true`	5 páginas de ayuda/tutoriales (product=‘crearack’). Sin docs internas
Staff técnico / Oráculo consultando corpus	omitir / `false`	5 mejores matches de TODO el corpus (incluyendo docs técnicas, internas)

Cambios recientes (v2.1, commit@44fec40)

Nuevo parámetro user_facing: Separación de corpus Help Widget vs. staff/técnico.
Función filterUserFacing(): Valida matches contra whitelist de páginas públicas.
Over-fetch + filter: Para Help Widget, fetch 20 chunks y filtra a 5 user-facing.

Implementación

Handler: functions/api/mcp/handlers/archivo.ts (función handleAsk)
Tool definition: functions/api/mcp/tools.ts (schema en array TOOLS)
Entorno: Cloudflare Workers (edge runtime, acceso a D1/Valkey)

Véase también

[[concept—biblioteca—wiki]]
[[concept—saas—multi-tenancy]]
[[entity—functions—tool—bib-search-nodes]]
[[entity—functions—handler—archivo]]
[[entity—functions—schema—env]]