scan-mcp

스캐너 캡처(ADF/양면/용지 크기), 일괄 처리 및 다중 페이지 어셈블리를 위한 최소한의 MCP 서버입니다.

기능

• 장치 검색 및 스캔 작업을 위한 도구를 노출하는 작고 타입이 지정된 MCP 서버

• 결정적이고 유형화된 출력과 함께 JSON Schema로 검증된 입력

• 스마트 장치 선택(ADF/양면 선호, 카메라 백엔드 회피), 강력한 기본값

• 로컬 우선 전송: 모든 것을 기기 내에서 유지하는 기본 stdio, 자체 네트워크 배포를 위한 선택적 HTTP

참고: 이 패키지는 Node 22 및 Linux SANE 백엔드(scanimage)를 대상으로 합니다.

Related MCP server: MCPOSprint

빠른 시작(로컬 stdio, 기본값)

MCP 클라이언트 구성에 서버 항목을 추가하세요:

{
  "mcpServers": {
    "scan": {
      "command": "npx",
      "args": [
        "-y",
        "scan-mcp"
      ],
      "env": {
        "INBOX_DIR": "~/Documents/scanned_documents/inbox"
      }
    }
  }
}

• 이 호출은 개인 정보 보호 우선 단일 시스템 설정을 위해 stdio를 통해 실행됩니다.

• device_id 없이 start_scan_job을 호출하여 스캐너를 자동 선택하고 스캔을 시작하세요.

• 아티팩트는 작업별로 INBOX_DIR 아래에 기록됩니다: job-*/page_*.tiff, doc_*.tiff, manifest.json, events.jsonl. crop_carrier_sheets가 설정되고 캐리어 시트가 감지되면 영향을 받는 각 페이지에 대해 page_*.cropped.tiff 파생 파일도 기록됩니다.

스트리밍 가능한 HTTP 전송

스캐너를 네트워크의 다른 시스템에 연결하는 것을 선호하시나요? scan-mcp는 스트리밍 가능한 HTTP 전송도 지원합니다:

scan-mcp --http

• 기본 포트는 3001입니다. MCP_HTTP_PORT를 설정하여 재정의하세요(예: MCP_HTTP_PORT=3333 scan-mcp --http).

• 기본적으로 모든 인터페이스(::)에 바인딩됩니다. MCP_HTTP_HOST를 설정하여 제한하세요(예: 리버스 프록시가 서버 앞에 있는 경우 MCP_HTTP_HOST=127.0.0.1).

• HTTP 응답은 도구 출력 스트리밍을 위해 서버 전송 이벤트(SSE)를 사용합니다. Claude Desktop 및 Windsurf와 같은 클라이언트는 이 전송을 지원합니다.

• 현재 인증이 없습니다. 내부 LAN 네트워킹을 위한 것입니다.

설치

• npx로 실행: npx scan-mcp (권장)

  • CLI는 Node 22+ 및 필수 스캐너/이미지 도구에 대한 빠른 사전 점검을 실행하고 누락된 항목이 있으면 설치 힌트를 출력합니다.

  • 위의 권장 서버 구성을 참조하세요.

• 다른 시스템에서 실행할 때 npx scan-mcp --http를 사용하여 스트리밍 가능한 HTTP 전송을 시작하세요.

• CLI 도움말: scan-mcp --help

• 소스에서(개발용):

  • npm install

  • npm run build

• Cline 설정 및 기타 자동화된 에이전트 설치에 대해서는 llms-install.md를 참조하세요.

시스템 요구 사항

• SANE 유틸리티가 있는 Linux: scanimage(및 선택적으로 scanadf)

• TIFF 도구: tiffcp(권장) 또는 ImageMagick convert

환경 변수

• SCAN_MOCK(기본값: false): SANE 호출을 모의하고 테스트용 가짜 TIFF를 생성합니다.

• INBOX_DIR(기본값: scanned_documents/inbox): 작업 실행 및 아티팩트의 기본 디렉터리입니다.

• SCANIMAGE_BIN / SCANADF_BIN(기본값: scanimage / scanadf): 바이너리 경로를 재정의합니다.

• TIFFCP_BIN / IM_CONVERT_BIN(기본값: tiffcp / convert): 다중 페이지 어셈블리 도구입니다.

• SCAN_EXCLUDE_BACKENDS(CSV): 제외할 백엔드(예: v4l).

• SCAN_PREFER_BACKENDS(CSV): 선호하는 백엔드(예: epjitsu,epson2).

• PERSIST_LAST_USED_DEVICE(기본값: true): 마지막으로 사용한 장치를 유지하고 가볍게 선호합니다.

• MCP_HTTP_PORT(기본값: 3001): HTTP 전송을 위한 TCP 포트입니다.

API

도구

• list_devices

  • 백엔드 세부 정보와 함께 연결된 스캐너를 검색합니다.

  • 입력: 없음.

• get_device_options

  • 특정 장치에 대한 SANE 옵션을 가져옵니다.

  • 입력:

    • device_id(문자열): 대상 장치 식별자입니다.

• start_scan_job

  • 스캔 작업을 시작합니다. device_id를 생략하면 자동 선택 및 기본 옵션이 트리거됩니다.

  • 입력(명시되지 않는 한 모두 선택 사항):

    • device_id(문자열)

    • resolution_dpi(정수, 50–1200)

    • color_mode(Color | Gray | Lineart): color_mode는 기본적으로 Lineart(문서 우선)입니다. 600dpi 이상에서는 Color가 기본값입니다. 고해상도 캡처는 일반적으로 1비트가 정보를 파괴하는 아트워크/사진을 의미하기 때문입니다. 기본값을 재정의하려면 color_mode를 명시적으로 전달하세요. 고해상도만 유일한 신호로 사용됩니다.

    • source(Flatbed | ADF | ADF Duplex)

    • duplex(부울)

    • page_size(Letter | A4 | Legal | Custom)

    • custom_size_mm { width, height }

    • doc_break_policy { type, blank_threshold, page_count, timer_ms, barcode_values }

    • output_format(문자열, 기본값 tiff)

    • tmp_dir(문자열)

    • crop_carrier_sheets(부울, 기본값 false): 캐리어 시트 앞 가장자리 밴드를 감지하고 잘린 페이지 파생 파일을 작성합니다. 원시 페이지는 유지됩니다.

• get_job_status

  • 작업 상태 및 아티팩트 수를 검사합니다.

  • 입력:

    • job_id(문자열)

• cancel_job

  • 작업 취소를 요청합니다. 스캔 루프 중 최선의 노력으로 처리됩니다.

  • 입력:

    • job_id(문자열)

• list_jobs

  • 인박스 디렉터리에서 최근 작업을 나열합니다.

  • 입력(선택 사항):

    • limit(정수, 최대 100)

    • state(running | completed | cancelled | error | unknown)

• get_manifest

  • 작업의 manifest.json을 가져옵니다.

  • 입력:

    • job_id(문자열)

• get_events

  • 작업의 events.jsonl 로그를 검색합니다.

  • 입력:

    • job_id(문자열)

입력 형태에 대한 JSON 스키마는 schemas/를 참조하세요. 테스트는 이러한 계약을 기준으로 검증합니다.

선택 및 기본값 작동 방식

기본값은 300dpi, 합리적인 색상 모드, 가능한 경우 ADF/양면을 목표로 합니다. 점수 매기기 및 대체에 대한 자세한 내용은 문서에 있습니다:

• 선택 및 기본값: docs/SELECTION.md

프로젝트 구조

• src/mcp.ts — MCP 서버 진입점 및 도구 등록

• src/services/* — 하드웨어 인터페이스 및 작업 오케스트레이션

• schemas/ — 유효성 검사 및 테스트에 사용되는 JSON 스키마

• docs/ — 아키텍처, 규칙 및 심층 분석

개발

• npm run dev(stdio MCP 서버), npm run dev:http(HTTP 전송)

• make verify는 린트, 타입 검사 및 테스트를 실행합니다.

• 규칙: docs/CONVENTIONS.md 및 아키텍처는 docs/BLUEPRINT.md

로드맵

아이디어 및 향후 개선 사항 추적은 docs/ROADMAP.md에 문서화되어 있습니다.