DeckProbe MCP Server

에이전트가 PDF, Office 또는 iWork 파일을 열지 않고도 그 안에 무엇이 있는지 물어볼 수 있게 해 줍니다.

설치 · 도구 · 구성 · 보안 · 작동 방식 · DeckProbe

DeckProbe — 문서용 ffprobe — 를 네 개의 타입화된 도구로 노출하는 MCP 서버입니다. 페이지 수, 슬라이드 수, 메타데이터, 암호화 및 매크로 신호, 구조 또는 무결성을 요청하면 신뢰도, 근거, 측정된 I/O 비용과 함께 제한된 결정적 JSON을 반환합니다.

렌더링이 없고, 매크로가 실행되지 않으며, 외부 참조를 따르지 않고, 네트워크 연결이 열리지 않습니다. 신뢰할 수 없는 파일을 대상으로 지정해도 안전합니다.

// probe { "path": "deck.pptx", "targets": ["slide_count"], "view": "values" }
{
  "schema_version": 2,
  "status": "ok",
  "driver": { "id": "powerpoint", "profile": "pptx" },
  "values": { "powerpoint.slide_count": 31 },
  "view": "values"
}

설치

사전에 설치할 것이 없습니다. npx가 서버와 엔진을 함께 가져옵니다.

Claude Code

claude mcp add deckprobe -- npx -y @deckflow/deckprobe-mcp

Claude Desktop, Cursor, VS Code, Zed 및 mcpServers를 읽는 기타 모든 클라이언트

{
  "mcpServers": {
    "deckprobe": {
      "command": "npx",
      "args": ["-y", "@deckflow/deckprobe-mcp"]
    }
  }
}

고정 설치를 원하면 npm install -g @deckflow/deckprobe-mcp를 실행하고 deckprobe-mcp를 명령으로 사용하세요.

Node.js 20 이상이 필요합니다. 엔진 바이너리는 macOS, Linux(glibc 및 musl), Windows의 x86-64 및 ARM64용 플랫폼별 선택 종속성으로 제공됩니다. 그 외의 환경에서는 서버가 동일한 엔진을 WebAssembly로 컴파일한 버전으로 대체하므로 npx는 Node가 실행되는 모든 곳에서 작동합니다.

Related MCP server: document-parser

도구

또한 실행 중인 엔진에 번들된 보고서 JSON Schema를 담은 deckprobe://schema 리소스가 하나 있습니다.

probe

{
  "path": "reports/q3.pptx",
  "targets": ["@summary", "@security"],  // presets, short names, or canonical names
  "level": "metadata",                   // header | metadata | deep
  "min_confidence": "high",              // low | medium | high | exact
  "target_confidence": { "slide_count": "exact" },
  "view": "report",                      // report | values
  "budget": { "max_physical_bytes": 8388608, "timeout_ms": 1000 }
}

targets는 짧은 이름(slide_count), 정식 이름(powerpoint.slide_count) 및 프리셋을 허용합니다:

@summary는 전체 파일 읽기가 필요한 통계를 의도적으로 생략합니다. PDF의 page_count가 대표적인 경우입니다 — 명시적으로 요청하세요.

probe_batch

{ "paths": ["a.pdf", "b.pptx", "c.xlsx"], "targets": ["@security"] }

하나의 엔진 프로세스가 전체 배치를 처리합니다. 결과는 입력 순서대로 반환되며, 각각 자체 보고서 또는 자체 오류를 가지므로 잘못된 파일 하나가 실행 전체를 망치지 않습니다. 기본값은 간결한 values 뷰입니다. 리터럴 경로만 허용합니다 — glob은 직접 확장하세요.

list_formats 및 list_targets

list_targets는 format(pdf, docx, xlsx, pptx, doc, xls, ppt, key, numbers, pages)을 받아 각 대상의 별칭, 설명, 값 유형, 최소 레벨, 비용 클래스 및 선택기 멤버십을 반환합니다. 엔진의 전체 보고서(대상별 JSON Schema 조각 및 확장된 선택기 목록 포함)를 보려면 detail: "full"을 전달하세요.

둘 다 서버 프로세스 수명 동안 캐시됩니다.

보고서 읽기

도구 결과는 엔진 자체의 schema-v2 봉투를 수정하지 않은 것입니다. 소비하기 전에 알아야 할 두 가지가 있습니다:

• status: "partial"은 실패가 아닙니다. 요청된 대상 중 하나 이상이 요청된 신뢰도로 해석될 수 없음을 의미합니다. 해당 대상은 execution.unresolved_targets에 명시되며, 다른 모든 결과는 여전히 유효합니다.

• confidence_score는 라벨당 고정 상수(0.4, 0.7, 0.95, 1.0)이며, 보정된 확률이 아닙니다. 0.95가 값이 95%의 확률로 맞다는 의미는 아닙니다.

resolved 또는 estimated 상태의 결과만 value를 갖습니다. unknown은 흔하며, 일반적으로 문서가 해당 사실을 단순히 기록하지 않음을 의미합니다.

실패한 호출은 엔진의 오류 봉투와 함께 무엇을 해야 하는지에 대한 한 줄을 포함한 isError를 반환합니다. 서버가 엔진 실행 전에 발생시키는 실패(경로 누락, 디렉터리, 허용 목록 밖의 경로, 마감 시간 초과)는 MCP_ 접두사 코드와 origin: "mcp-server"를 사용하여 동일한 봉투 형태를 사용합니다.

구성

모든 설정은 환경 변수이며, 클라이언트의 MCP 구성에 설정합니다. 모두 선택 사항입니다.

{
  "deckprobe": {
    "command": "npx",
    "args": ["-y", "@deckflow/deckprobe-mcp"],
    "env": { "DECKPROBE_MCP_ROOTS": "/Users/me/Documents:/Users/me/Downloads" }
  }
}

보안

DeckProbe는 신뢰할 수 없는 입력을 위해 설계되었습니다: 제한된 파싱, 렌더러 없음, 매크로 인터프리터 없음, 외부 참조 해석 없음, 네트워크 액세스 없음. 이 서버는 그 위에 두 가지를 추가합니다.

• 프로세스 격리 및 하드 마감 시간. 각 프로브는 자체 수명이 짧은 프로세스에서 실행되며, DECKPROBE_MCP_TIMEOUT_MS를 초과하면 종료됩니다.

• 선택적 읽기 허용 목록. DECKPROBE_MCP_ROOTS는 접근 가능한 트리를 고정합니다. 경로는 검사 전에 심볼릭 링크가 해석되므로 링크가 이를 우회할 수 없습니다. 기본값은 제한 없음으로, 사용자가 직접 실행할 수 있는 CLI와 일치합니다 — 공유 또는 자동화된 배포에는 설정하세요.

보고서는 문서의 내용을 재현하는 대신 문서를 설명합니다(메타데이터, 개수, 신호). 문서 제목과 같은 보고서 값은 여전히 공격자가 제어하는 문자열입니다: 서버는 이를 JSON 데이터로 전달하고 지침에 삽입하지 않으므로, 소비자는 동일한 방식으로 취급해야 합니다.

취약점은 SECURITY.md에 설명된 대로 비공개로 신고하세요.

작동 방식

MCP client
    │  JSON-RPC over stdio
    ▼
deckprobe-mcp ── validates arguments, resolves the path, maps the result
    │  argv + stdout (one process per probe, or one --jsonl process per batch)
    ▼
DeckProbe engine ── plans the cheapest paths that answer the request

서버는 WebAssembly 빌드를 호출하는 대신 네이티브 DeckProbe CLI를 생성합니다. CLI는 프로브 계획에 필요한 바이트 범위만 읽는 반면, WebAssembly 경로는 전체 파일을 메모리에 보관하며, 별도의 OS 프로세스는 신뢰할 수 없는 파싱을 격리하고 완전히 종료할 수 있습니다. 엔진은 다음 순서로 선택됩니다:

1. DECKPROBE_MCP_BIN

2. 이 패키지의 @deckflow/deckprobe 종속성과 함께 제공되는 바이너리

3. PATH의 deckprobe

4. 번들된 WebAssembly 엔진

해석된 엔진은 시작 시 stderr에 기록됩니다. stdout은 MCP 전송에 속하며 다른 것은 전달하지 않습니다.

MCP 서버 또는 에이전트 스킬?

DeckProbe는 셸을 사용할 수 있는 에이전트에게 CLI를 직접 사용하도록 가르치는 Agent Skill도 제공합니다. 둘 다 동일한 어휘를 가르칩니다. 에이전트에 셸이 있고 CLI의 전체 표면을 원하면 스킬을 사용하고, 셸이 없거나 엔진이 실행되기 전에 타입화된 인수의 유효성 검사를 원하면 이 서버를 사용하세요.

개발

npm install
npm test          # typecheck, lint, build, and the full suite
npm run test:watch

기여를 환영합니다 — CONTRIBUTING.md를 참조하세요. 거부된 대안을 포함한 설계 근거는 docs/rfc.md에 있습니다.

라이선스

MIT. LICENSE를 참조하세요.