DeckProbe MCP Server

Позвольте агенту узнать, что внутри PDF, Office или iWork файла — не открывая его.

Установка · Инструменты · Конфигурация · Безопасность · Как это работает · DeckProbe

MCP-сервер, который предоставляет DeckProbe — ffprobe для документов — в виде четырех типизированных инструментов. Запрашивайте количество страниц, слайдов, метаданные, сигналы шифрования и макросов, структуру или целостность и получайте ограниченный, детерминированный 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

Инструменты

Также есть один ресурс, deckprobe://schema, содержащий JSON-схему отчёта, встроенную в работающий движок.

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 намеренно опускает статистику, требующую полного чтения файла. page_count для PDF — яркий пример; запрашивайте его явно.

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) и возвращает для каждой цели её псевдонимы, описание, тип значения, минимальный уровень, класс стоимости и принадлежность к селектору. Передайте detail: "full" для полного отчёта движка, включая фрагменты JSON-схемы для каждой цели и расширенные списки селекторов.

Оба кэшируются на время жизни процесса сервера.

Чтение отчёта

Результат инструмента — это собственная оболочка 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

Сервер запускает нативный CLI DeckProbe, а не вызывает WebAssembly-сборку. CLI читает только те диапазоны байтов, которые нужны плану проб, тогда как WebAssembly-путь держит весь файл в памяти, а отдельный процесс ОС как изолирует ненадёжный разбор, так и может быть полностью завершён. Движок выбирается в следующем порядке:

1. DECKPROBE_MCP_BIN

2. двоичный файл, поставляемый с зависимостью @deckflow/deckprobe этого пакета

3. deckprobe в PATH

4. встроенный WebAssembly-движок

Выбранный движок записывается в stderr при запуске. stdout принадлежит транспорту MCP и больше ничего не несёт.

MCP-сервер или навык агента?

DeckProbe также поставляется с Agent Skill, который обучает агента с доступом к оболочке использовать CLI напрямую. Оба обучают одному и тому же словарю. Используйте навык, когда у агента есть оболочка и вам нужна полная поверхность CLI; используйте этот сервер, когда её нет или когда вы хотите, чтобы типизированные аргументы проверялись до запуска движка.

Разработка

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

Вклад приветствуется — см. CONTRIBUTING.md. Обоснование дизайна, включая отклонённые альтернативы, находится в docs/rfc.md.

Лицензия

MIT. См. LICENSE.