@devrobotlabs/visionapi-mcp

Vision API용 MCP 서버입니다. Claude Code, Claude Desktop, Cursor 또는 다른 MCP 호스트를 스캔 폴더에 연결하고 송장을 요청하세요 — 작성할 통합 코드도, 생성된 코드에 들어갈 API 키도, 기억에서 재구성한 계약서도 없습니다.

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.

설치

설치할 것이 없습니다. 호스트의 설정에 추가하면 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, 동일한 형식:

{
  "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_..." }
    }
  }
}

키는 app.visionapi.io/dashboard/keys에서 발급받으세요. 새 계정에는 카드 없이 50크레딧이 제공됩니다.

호스트 설정 블록은 examples/ 디렉터리가 아니라 이 README에 있습니다 — 아홉 개의 클라이언트 라이브러리와 달라진 점이며, 의도적인 결정입니다. README에만 존재하는 스니펫은 아무도 실행하지 않는 스크립트에서 벗어날 수 없습니다.

Related MCP server: receiptconverter-mcp

읽을 수 있는 디렉터리

모든 위치 인자는 서버가 파일을 읽을 수 있는 디렉터리입니다. 아무것도 지정하지 않으면 프로세스 작업 디렉터리만이 유일한 루트입니다 — MCP 호스트가 프로젝트 디렉터리를 cwd로 하여 stdio 서버를 실행하기 때문에 이것이 안전한 기본값입니다.

이것은 보기보다 중요합니다. 서버는 실시간 지출 자격 증명을 보유하고 파일시스템 권한으로 실행되므로 셸이 읽을 수 있는 모든 것을 읽을 수 있습니다. ~/Documents/passport.jpg의 원본 텍스트를 요청하는 것은 해당 문서의 내용을 모델의 컨텍스트와 호스트가 유지하는 모든 대화 기록에 가져오는 실제 작동 방식입니다. 허용 목록은 혼란에 빠지거나 조작된 에이전트가 실수로 그렇게 하는 것을 막는 장치입니다.

경로는 비교 전 양쪽 모두에서 realpath로 해석되므로 허용된 디렉터리 내부의 심볼릭 링크가 그 밖을 가리킬 수 없습니다.

--allow-any-path는 허용 목록을 완전히 끕니다. 시작 시 stderr에 경고를 출력하며, 사용할 이유가 있어야 합니다.

도구

크레딧을 소비하는 세 도구는 readOnlyHint: false로 주석 처리되어 있어, 읽기 전용 도구를 자동 승인하는 호스트도 이 중 하나가 실행되기 전에 멈추고 물어봅니다.

카탈로그는 리소스로도 노출됩니다 — visionapi://presets 및 visionapi://presets/{name} — 리소스를 선호하는 호스트를 위한 것입니다. 도구가 기본 표면입니다. 리소스 지원이 호스트마다 고르지 않기 때문입니다.

출력

응답은 JSON 덤프가 아니라 모델이 읽을 수 있도록 렌더링됩니다. 37개 필드의 송장 프리셋이 그중 12개만 채우는 문서에 적용되면, 25번의 {"value":null,"confidence":"low"} 반복 대신 테이블과 Not found in this document (25): … 한 줄로 반환됩니다 — 3~4배 더 작고, 조치하기도 쉽습니다.

과정에서 손실되는 것은 없습니다. 모든 도구는 format을 받습니다:

• markdown (기본값) — 위의 렌더링.

• compact_json — _not_found 및 _low_confidence 배열이 포함된 동일한 정보를 데이터로. 에이전트가 읽기보다 파싱할 때 사용.

• json — API 응답을 그대로. 계약에 따라 실제 HTTP 코드를 작성할 때 사용.

신뢰도는 높지 않을 때만 출력되므로 (mid)와 (low)가 눈에 띄고 일반적인 경우에는 읽을 비용이 없습니다.

긴 문서

mode는 auto로 두세요. API는 동기 요청을 60초에 종료합니다. 그러면 서버가 이를 큐에 다시 제출하고 폴링하며 진행 상황을 호스트에 보고합니다. 한 번만 청구됩니다. 시간 초과된 시도가 예약을 전액 해제했기 때문입니다.

대략 10페이지가 넘는 문서에는 처음부터 mode: "async"를 전달하고, 긴 문서를 저렴하게 샘플링하려면 pages: "1-5"를 사용하세요 — 선택한 페이지만 청구됩니다.

비용 및 실패

실패는 비용이 들지 않습니다. 모든 non-2xx는 크레딧 예약을 전액 해제하므로 실패한 호출은 수정하고 반복해도 안전하며 정리할 것도 없습니다. 도구 설명에 이 내용이 명시되어 있어, 이 서버를 사용하는 에이전트는 오류 후 포기하거나 작동할 수 없는 것을 재시도하는 대신 합리적으로 행동합니다.

두 가지 오류에는 직접 알아둘 가치가 있는 조언이 포함되어 있습니다:

환경

키가 없어도 서버 시작은 멈추지 않습니다: stderr에 경고를 출력하고 tools/list는 여전히 작동하며, 첫 청구 가능 호출이 해결 방법을 알려주는 메시지를 반환합니다. 시작을 거부하는 서버는 사용자에게 무언가 고장났다는 것만 알려줍니다.

개발

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를 실행하세요. npm install ../node가 아닙니다 — 이는 package.json을 "file:../node"로 다시 쓰며, 그 매니페스트가 게시되는 것이기 때문입니다.

링크

• 문서

• 코딩 에이전트용 통합 참조

• 프리셋 카탈로그

• 가격

MIT 라이선스.