@devrobotlabs/visionapi-mcp

Servidor MCP para la Vision API. Apunta Claude Code, Claude Desktop, Cursor o cualquier otro host MCP a una carpeta de escaneos y pide las facturas: sin integración que escribir, sin clave API en el código generado, sin contrato parafraseado de memoria.

You: pull the totals out of every invoice in ~/inbox and put them in a CSV

Claude: [vision_analyze × 7]
        Done — 7 invoices, 14 credits. Three had no PO number; I left those cells empty.

Instalación

Nada que instalar. Añádelo a la configuración de tu host y se ejecuta mediante npx.

Claude Code — claude mcp add visionapi --env VISION_API_KEY=sk_live_... -- npx -y @devrobotlabs/visionapi-mcp ~/inbox

Claude Desktop — claude_desktop_config.json:

{
  "mcpServers": {
    "visionapi": {
      "command": "npx",
      "args": ["-y", "@devrobotlabs/visionapi-mcp", "/Users/me/inbox"],
      "env": { "VISION_API_KEY": "sk_live_..." }
    }
  }
}

Cursor — .cursor/mcp.json, misma forma:

{
  "mcpServers": {
    "visionapi": {
      "command": "npx",
      "args": ["-y", "@devrobotlabs/visionapi-mcp", "."],
      "env": { "VISION_API_KEY": "sk_live_..." }
    }
  }
}

VS Code — .vscode/mcp.json:

{
  "servers": {
    "visionapi": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@devrobotlabs/visionapi-mcp", "${workspaceFolder}"],
      "env": { "VISION_API_KEY": "sk_live_..." }
    }
  }
}

Obtén una clave en app.visionapi.io/dashboard/keys. Las cuentas nuevas reciben 50 créditos, sin tarjeta.

Los bloques de configuración del host viven en este README en lugar de en un directorio examples/ — una desviación de las nueve bibliotecas cliente, y deliberada. Un fragmento que solo existe en un README no puede desviarse de un script ejecutable que nadie ejecuta.

Related MCP server: receiptconverter-mcp

Qué directorios puede leer

Cada argumento posicional es un directorio del que el servidor puede leer archivos. Si no se da ninguno, el directorio de trabajo del proceso es la única raíz — que es el valor predeterminado seguro, porque los hosts MCP lanzan un servidor stdio con el directorio del proyecto como su cwd.

Esto importa más de lo que parece. El servidor tiene una credencial de gasto en vivo y se ejecuta con tus permisos de sistema de archivos, por lo que puede leer cualquier cosa que tu shell pueda. Pedirle el texto bruto de ~/Documents/passport.jpg es una forma funcional de obtener el contenido de ese documento en el contexto de un modelo y en cualquier transcripción que tu host mantenga. La lista de permitidos es lo que impide que un agente confundido o manipulado haga eso por accidente.

Las rutas se resuelven con realpath en ambos lados antes de compararse, por lo que un enlace simbólico dentro de un directorio permitido no puede apuntar fuera de él.

--allow-any-path desactiva la lista de permitidos por completo. Advierte en stderr al inicio y deberías tener una razón.

Herramientas

Las tres que gastan créditos están anotadas con readOnlyHint: false, por lo que un host que autoaprueba herramientas de solo lectura se detendrá y preguntará antes de que una de ellas se ejecute.

El catálogo también se expone como recursos — visionapi://presets y visionapi://presets/{name} — para hosts que los prefieran. Las herramientas son la superficie principal, porque el soporte de recursos es desigual entre hosts.

Salida

Las respuestas se renderizan para que un modelo las lea, no se vuelcan como JSON. Un preset de factura de 37 campos sobre un documento que llena doce de ellos devuelve una tabla más una línea No encontrado en este documento (25): …, en lugar de veinticinco repeticiones de {"value":null,"confidence":"low"} — de tres a cuatro veces más pequeño, y más fácil de actuar.

Nada se pierde en el proceso. Cada herramienta acepta un format:

• markdown (predeterminado) — la representación anterior.

• compact_json — la misma información como datos, con matrices _not_found y _low_confidence. Para cuando el agente vaya a analizar en lugar de leer.

• json — la respuesta de la API verbatim. Lo que se debe usar al escribir código HTTP real contra el contrato.

La confianza se imprime solo cuando no es alta, por lo que (mid) y (low) resaltan y el caso común no cuesta nada de leer.

Documentos largos

Deja mode en auto. La API mata una solicitud síncrona a los 60 segundos; el servidor entonces la reenvía a la cola y hace polling, informando el progreso a tu host mientras avanza. Se te cobra una vez, porque el intento con tiempo agotado liberó su reserva por completo.

Pasa mode: "async" de antemano para cualquier cosa de más de aproximadamente diez páginas, y pages: "1-5" para muestrear un documento largo de forma económica: se te cobra solo por las páginas seleccionadas.

Costos y fallos

Los fallos no cuestan nada. Cada no-2xx libera la reserva de crédito por completo, por lo que una llamada fallida es segura de corregir y repetir, y no hay limpieza que hacer. Las descripciones de las herramientas lo dicen, por lo que un agente que usa este servidor se comporta de manera sensata después de un error, en lugar de rendirse o reintentar algo que no puede funcionar.

Dos errores llevan consejos que vale la pena conocer:

Entorno

Una clave faltante no impide que el servidor se inicie: advierte en stderr, tools/list sigue funcionando, y la primera llamada facturable devuelve un mensaje que nombra la solución. Un servidor que se niega a iniciar le dice al usuario solo que algo está roto.

Desarrollo

npm install
npm run typecheck
npm test          # 37 offline tests — no key, no network
npx @modelcontextprotocol/inspector node ./dist/cli.js ~/some/dir

npm install --no-save ../node para probar contra una compilación local del cliente. No npm install ../node — eso reescribe package.json a "file:../node", y ese manifiesto es lo que se publica.

Enlaces

• Documentación

• Referencia de integración para agentes de codificación

• Catálogo de presets

• Precios

Licencia MIT.