# tool-transcribai-mcp

Servidor **MCP (Model Context Protocol)** para transcribir texto de imágenes con **OCR local** (tesseract.js, WASM, sin internet y sin gastar tokens) y generar descripciones breves con bajo consumo de tokens.

Compatible con ChatGPT, Claude, opencode, Cursor y cualquier cliente MCP.

## Herramientas

| Herramienta | Descripción |
|---|---|
| `transcribir_imagen` | OCR local de una imagen → texto plano + bloques con su confianza |
| `listar_imagenes` | Lista las imágenes soportadas de un directorio (ruta y tamaño) |
| `analizar_imagen` | OCR + descripción breve opcional → Markdown, texto plano o JSON (puede guardar archivo) |
| `procesar_carpeta` | Procesa todas las imágenes de una carpeta en lote, un archivo de salida por imagen |

## Cómo funciona

- **OCR 100% local**: tesseract.js corre dentro del servidor (WASM). La imagen nunca sale de tu máquina y no se consumen tokens.
- **Descripción IA opcional**: si configuras una API key (`OPENAI_API_KEY` o `TOOL_TRANSCRIBAI_API_KEY`), `describe` envía **solo el texto OCR** (no la imagen) al modelo con un prompt corto (máx. 3 frases), minimizando tokens.
- **Seguridad por defecto**: toda ruta se resuelve contra `allowedRoot` (path traversal bloqueado), con límites de tamaño (20 MB) y de lote (100 imágenes).

## Uso con un cliente MCP

Configúralo con `uvx`, `npx` o la ruta directa al binario. Ejemplo con npx:

```json
{
  "mcpServers": {
    "transcribai": {
      "command": "npx",
      "args": ["tool-transcribai-mcp"]
    }
  }
}
```

O en modo local (tras `npm install && npm run build`):

```json
{
  "mcpServers": {
    "transcribai": {
      "command": "node",
      "args": ["<ruta>/tool-transcribai-mcp/dist/index.js"]
    }
  }
}
```

### Modo Streamable HTTP (opcional)

```bash
TOOL_TRANSCRIBAI_HTTP=1 TOOL_TRANSCRIBAI_HTTP_PORT=3397 npm run start
```

## Instalación / desarrollo

```bash
npm install
npm run dev        # servidor stdio con tsx
npm run build      # compila a dist/
npm test           # tests (Vitest)
npm run typecheck
```

Requisitos: Node.js 18+.

## Configuración

| Variable | Defecto | Descripción |
|---|---|---|
| `TOOL_TRANSCRIBAI_ROOT` | `cwd` | Directorio raíz permitido |
| `TOOL_TRANSCRIBAI_MAX_IMAGE_BYTES` | 20 MB | Tamaño máximo por imagen |
| `TOOL_TRANSCRIBAI_MAX_BATCH` | 100 | Máx. imágenes por carpeta |
| `TOOL_TRANSCRIBAI_LANG_PATH` | — | Datos de idioma Tesseract locales (offline) |
| `TOOL_TRANSCRIBAI_HTTP` | — | `1` para activar modo HTTP |
| `TOOL_TRANSCRIBAI_HTTP_PORT` | `3397` | Puerto del modo HTTP |
| `TOOL_TRANSCRIBAI_API_KEY` / `OPENAI_API_KEY` | — | API key para la descripción IA |
| `TOOL_TRANSCRIBAI_DESCRIBE_MODEL` | `gpt-4o-mini` | Modelo de descripción |

## Idiomas OCR

`eng` (defecto), `spa`, `fra`, `deu`, `ita`, `por`, `nld`, `cat`, `eus`, `glg`, `ron`, `ces`, `pol`, `rus`, `ukr`, `tur`, `ara`, `hin`, `jpn`, `kor`, `chi_sim`, `chi_tra`.

## Licencia

MIT. Ver [LICENSE](LICENSE).