mcp-paperless-ngx

Создан на основе REST API версии 10 и отличается тремя вещами:

• Учтённое покрытие. Каждая из 92 документированных конечных точек либо доступна как инструмент, либо перечислена в src/tools/coverage.ts с письменным обоснованием, почему её исключили. Тест это проверяет, так что релиз Paperless, добавляющий эндпоинт, приводит к падению CI, а не к тихой потере поддержки.

• Дисциплина токенов. Документ Paperless несёт в себе полный текст OCR. Наивные обёртки возвращают его по умолчанию, и один поиск может исчерпать контекст модели. Здесь результаты списков обрезаются на стороне сервера через ?fields=, текст живёт за отдельным постраничным инструментом, и ни один эндпоинт списка не передаёт сырой ответ API — тест это проверяет. См. Стоимость контекста.

• Ограниченная поверхность. 99 инструментов утопили бы список инструментов модели. Наборы инструментов позволяют открыть только то, что нужно конкретному клиенту, а --read-only полностью убирает все пути записи.

Paperless-ngx 2.x не поддерживается: API версии 10 ввёл эндпоинты (вложенные теги, версии документов, share_link_bundles, операции разделения PDF), которые этот сервер считает существующими.

Быстрый старт

npx -y mcp-paperless-ngx --check   # verify connectivity, then exit

Claude Code

claude mcp add paperless --scope user \
  --env PAPERLESS_URL=https://paperless.example.com \
  --env PAPERLESS_TOKEN=your-api-token \
  -- npx -y mcp-paperless-ngx

Claude Desktop, Cursor, Cline и другие MCP-клиенты

{
  "mcpServers": {
    "paperless": {
      "command": "npx",
      "args": ["-y", "mcp-paperless-ngx"],
      "env": {
        "PAPERLESS_URL": "https://paperless.example.com",
        "PAPERLESS_TOKEN": "your-api-token"
      }
    }
  }
}

Получение API-токена

Веб-интерфейс Paperless → ваше имя пользователя (справа сверху) → My Profile → кнопка с круговой стрелкой рядом с полем API-токена.

Related MCP server: paperlessngx-mcp

Конфигурация

Флаги CLI --url, --token, --public-url, --toolsets и --read-only переопределяют окружение. --check проверяет связь, --list-tools печатает включённые инструменты.

Наборы инструментов

mail и admin по умолчанию выключены, потому что большинству сессий они не нужны, а каждый дополнительный инструмент стоит контекста на каждом запросе. Включите их явно:

PAPERLESS_TOOLSETS=documents,metadata,system,mail
PAPERLESS_TOOLSETS=all

Стоимость контекста

Обёртка API для языковой модели имеет стоимость, которой нет у самого API: всё, что видит модель, оплачивается на каждом запросе. Два места, где это бьёт, и что этот сервер с ними делает.

Ответы. Три формы дороги в Paperless и легко возвращаются случайно:

Определения инструментов. Это более крупная и менее очевидная стоимость: имена, описания и JSON-схемы отправляются с каждым запросом, независимо от того, вызывается ли какой-либо инструмент.

Сделать это бесплатным невозможно — это цена инструмента, которым модель может пользоваться без угадывания. Но стоит подходить осознанно: если ваши сессии только ищут и подшивают документы, запуск PAPERLESS_TOOLSETS=documents,metadata экономит больше контекста, чем любое урезание ответов.

Безопасность

Сервер открывает деструктивные операции, потому что менеджер документов без них — не совсем менеджер. Он не пытается угадывать, когда они уместны — это суждение принадлежит клиенту и пользователю. Вместо этого он делает следующее:

• Деструктивные инструменты помечены destructiveHint: true, чтобы MCP-клиенты могли требовать подтверждения.

• Описания инструментов прямо говорят, что нельзя отменить (empty_trash, delete_custom_field, delete_originals), и просят подтверждения перед вызовом.

• --read-only удаляет все инструменты записи из списка, а не отказывает им во время вызова.

• Массовые эндпоинты поддерживают режим «применить ко всему, что соответствует этому фильтру». Этот сервер не открывает его: массовые инструменты принимают явные списки ID, так что неправильный фильтр не может молча затронуть весь архив.

• create_share_link создаёт публично доступный URL. Его описание говорит об этом, а подсказка audit_sharing существует, чтобы просмотреть, что уже открыто.

Эндпоинты, связанные с учётными данными (генерация токенов, включение TOTP, отключение второго фактора у кого-то), намеренно не открыты. См. EXCLUDED_ENDPOINTS для полного списка и обоснования.

Подсказки

Зарегистрированы как слэш-команды в клиентах, поддерживающих MCP-подсказки:

Тестирование

Три уровня, потому что они ловят разные вещи:

npm test                                        # logic — no network
PAPERLESS_URL=… PAPERLESS_TOKEN=… \
  node scripts/smoke-test.mjs                   # all 55 read-only tools, live
PAPERLESS_URL=… PAPERLESS_TOKEN=… \
  node scripts/write-test.mjs                   # writes, live — see the warning

npm test проверяет собственные рассуждения сервера: покрытие эндпоинтов, значения enum против схемы, что ни один инструмент списка не утекает сырые объекты API, что режим только для чтения действительно убирает записи.

smoke-test.mjs проверяет предположения, которые он делает о Paperless. Он вызывает каждый инструмент только для чтения против реального экземпляра, разрешая ID из вызовов списков вместо жёсткого кодирования, и печатает размеры ответов, чтобы дорогие инструменты оставались видимыми. Он ничего не записывает.

write-test.mjs покрывает остальное: загрузку и потребление, обновление каждого типа поля, заметки, массовые правки тегов, ссылки для публикации, ротацию и цикл корзины.

Он трогает только объекты, которые создаёт сам. Всё, что он создаёт, называется с префиксом zz-mcp-test и удаляется в конце, и он никогда не изменяет документ, который не загрузил. Если запуск прерван, остатки с этим префиксом безопасно удалить. Если есть тестовый экземпляр, предпочтите его.

Следим за Paperless

PAPERLESS_URL=… PAPERLESS_TOKEN=… node scripts/sync-schema.mjs
npm test

sync-schema.mjs перегенерирует schema/endpoints.json из OpenAPI-документа вашего собственного экземпляра. Тестовый набор затем сообщает о любом эндпоинте, который не открыт и не исключён явно. Это весь цикл обслуживания: укажите на более новый Paperless, и тест скажет, что изменилось.

Разработка

npm install
npm start          # run from source
npm run build      # compile to build/
npm test           # unit tests + coverage checks
npm run inspect    # build, then open the MCP inspector

Предшествующее искусство

Несколько MCP-серверов для Paperless уже существуют, наиболее известный — cubinet-code/paperless-ngx-mcp, а также nloui/paperless-mcp и barryw/PaperlessMCP. Они нацелены на API 2.x. Если вы используете Paperless-ngx 2.x, воспользуйтесь одним из них; этот предполагает 3.x.

Лицензия

MIT. См. LICENSE.