tool-transcribai-mcp: Instructions file for Codex

tool-transcribai-mcp

Servidor MCP (Model Context Protocol) para transcribir texto de imágenes con OCR local (tesseract.js) y generar descripciones breves con bajo consumo de tokens. Compatible con ChatGPT, Claude, opencode, Cursor y cualquier cliente MCP.

Herramientas MCP

Registradas en src/server.ts (cada una en src/tools/):

Herramienta	Archivo	Qué hace
transcribir_imagen	tools/transcribir.ts	OCR local de una imagen → texto plano + bloques con confianza
listar_imagenes	tools/listar.ts	Lista las imágenes soportadas de un directorio
analizar_imagen	tools/analizar.ts	OCR + descripción breve (opcional) → .md/.txt/.json, puede guardar archivo
procesar_carpeta	tools/carpeta.ts	Procesa TODAS las imágenes de una carpeta en lote, un archivo por imagen

Comandos

• npm run dev — ejecuta el servidor en modo stdio con tsx
• npm run build — compila TypeScript a dist/
• npm run start — arranca dist/index.js (uso en producción)
• npm test — tests con Vitest (test/)
• npm run typecheck — tsc --noEmit
• npm run lint — ESLint

Siempre ejecuta npm run typecheck y npm test antes de terminar cualquier cambio.

Convenciones de código

• TypeScript ESM: "type": "module", e imports con extensión .js explícita (p. ej. from './config.js'). No uses .ts en los imports.
• Todo está en español: mensajes de error, descripciones de schemas y salida de herramientas.
• Schemas de entrada con zod (z.object(...)) y type Args = z.infer<...>.
• Archivo de servicio por herramienta en src/tools/, lógica compartida en src/services/.
• Nunca hagas console.log para responder: las herramientas devuelven textResult(texto) (de src/tools/helpers.ts).
• Mensajes de error: ante SecurityError usa ⛔ {message}; para otros errores ❌ Error....

Configuración (variables de entorno)

Prefijo TOOL_TRANSCRIBAI_ (ver src/config.ts):

• TOOL_TRANSCRIBAI_ROOT — directorio raíz permitido (por defecto cwd). Cualquier ruta fuera de aquí se rechaza.
• TOOL_TRANSCRIBAI_MAX_IMAGE_BYTES — tamaño máximo por imagen (por defecto 20 MB).
• TOOL_TRANSCRIBAI_MAX_BATCH — máx. imágenes por carpeta (por defecto 100).
• TOOL_TRANSCRIBAI_LANG_PATH — datos de idioma local de Tesseract (para uso offline, sin CDN).
• TOOL_TRANSCRIBAI_HTTP=1 + TOOL_TRANSCRIBAI_HTTP_PORT — modo Streamable HTTP (por defecto stdio).
• TOOL_TRANSCRIBAI_API_KEY / OPENAI_API_KEY — API key de la IA descriptiva (solo env, nunca argumentos).
• TOOL_TRANSCRIBAI_DESCRIBE_ENDPOINT / TOOL_TRANSCRIBAI_DESCRIBE_MODEL — endpoint y modelo (por defecto gpt-4o-mini).