Handler MCP bib_ask — Biblioteca (archivo.ts)

Descripción

handleAsk es la función principal del tool MCP bib_ask, definida en functions/api/mcp/handlers/archivo.ts. Orquesta el flujo completo de pregunta-respuesta de la Biblioteca: desde la recepción de la query hasta la síntesis con Gemini y el archivado del resultado.

Es el handler que activa el Help Widget de CreaRack Pro cuando un usuario hace una pregunta.

Firma y parámetros de entrada

async function handleAsk(
  args: Record<string, unknown>,
  env: Env
): Promise<string>

Flujo de ejecución

Modo help (default)

handleAsk(args)
  │
  ├─ [guard] question requerida
  ├─ [guard] GOOGLE_AI_API_KEY
  ├─ [guard] env.AI (Workers AI binding)
  │
  ├─ embedTexts([question])          → vector embedding de la query
  ├─ searchChunks(embedding, filters) → chunks relevantes de la wiki (D1)
  │
  ├─ synthesizeAnswer(apiKey, question, chunks, 'help')
  │     ├─ buildHelpPrompts(question, chunks, lang)
  │     └─ Gemini REST API call
  │
  ├─ utility hit → registro en D1
  └─ return JSON { answer, sources, model, chunks_used, duration_ms, archive, mode }

Modo tutor (early return)

handleAsk(args)
  │
  ├─ [guard] question requerida
  ├─ [guard] GOOGLE_AI_API_KEY
  │
  ├─ [EARLY RETURN si mode === 'tutor']
  │     ├─ synthesizeAnswer(apiKey, question, [], 'tutor')
  │     │     ├─ buildTutorPrompts(question, lang)
  │     │     └─ Gemini REST API call
  │     └─ return JSON { answer, sources: [], mode: 'tutor', archive: { attempted: false, reason: 'tutor-mode' } }
  │
  └─ [flujo help no se ejecuta]

Diferencias clave del modo tutor:

• Se omiten embedTexts, searchChunks, utility hit y archivado.
• El binding env.AI no es necesario (el check se ubica post-early-return).
• sources siempre [].
• Más rápido al no hacer operaciones de embedding.

Respuesta JSON

{
  answer: string,          // markdown — respuesta al usuario
  sources: ChunkMatch[],   // chunks usados como grounding ([] en tutor)
  model: string,           // modelo Gemini utilizado
  chunks_used: number,     // 0 en tutor
  duration_ms: number,     // latencia de síntesis
  archive: {
    attempted: boolean,
    reason?: string,       // 'tutor-mode' | otros
  },
  mode: 'help' | 'tutor',
}

Dependencias de entorno

Notas de implementación

• El parámetro mode se recibe como args.mode (string desconocido) y se castea con guardia: (args.mode as string) === 'tutor' ? 'tutor' : 'help'. Cualquier valor no reconocido cae a 'help', preservando la retrocompatibilidad.
• El handler sigue el patrón Cloudflare Workers: no usa el SDK google-genai (no soportado en Workerd). Llama directamente a la REST API de Google AI Studio via fetch.
• Los filtros source_type, category, tag y limit se pasan a searchChunks para restringir el espacio de búsqueda vectorial (solo aplican en modo help).

Historial relevante

Véase también

• [[entity—biblioteca—handler—archivo-core]]
• [[feature—biblioteca—it-tutor-mode]]
• [[concept—biblioteca—synthesize-answer]]