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>

Argumento (`args.*`)	Tipo	Requerido	Descripción
`question`	`string`	✅	Pregunta del usuario
`mode`	`'help' \| 'tutor'`	❌	Modo de respuesta. Default: `'help'`
`source_type`	`string`	❌	Filtro por tipo de fuente en vector search
`category`	`string`	❌	Filtro por categoría
`tag`	`string`	❌	Filtro por tag
`limit`	`number`	❌	Número máximo de chunks a recuperar

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

Binding / Secret	Modo help	Modo tutor
`env.GOOGLE_AI_API_KEY`	✅ obligatorio	✅ obligatorio
`env.AI` (Workers AI)	✅ obligatorio	❌ no requerido
D1 (vector search + archivado)	✅ necesario	❌ no accedido

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

Commit	Cambio
`86c9ac4`	Añade modo `tutor` con early return; refactoriza `synthesizeAnswer` en `archivo-core.ts`

Véase también

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