CorpusGate

Приватный документный шлюз, готовый к работе с LLM, на базе MarkItDown и MCP.

Преобразовывайте, индексируйте и получайте приватные документы для ИИ-инструментов, не отправляя содержимое документов сторонним сервисам.

CorpusGate — это универсальный, самостоятельно размещаемый Document MCP Server для отдельных пользователей и команд, которым нужен контролируемый доступ ИИ-инструментов к документам на собственной инфраструктуре. MarkItDown преобразует поддерживаемые файлы в повторно используемый Markdown. Шлюз разбивает этот Markdown на чанки и индексирует их, а MCP возвращает только релевантные чанки с указанием источника в рамках принудительных лимитов сервера.

Самостоятельное размещение оставляет исходные документы, сгенерированный Markdown, запросы, метаданные и индексы под контролем оператора. Сокращение токенов достигается за счёт ограниченной выдачи и выбора чанков, а не только за счёт MarkItDown. Этот проект — не чат-бот, не генератор ответов LLM, не продукт для анализа контрактов, не SaaS-платформа и не пользовательская панель документов.

Возможности

• Преобразование PDF, DOCX, PPTX, XLSX, TXT, Markdown и HTML через Microsoft MarkItDown.

• Постоянный кэш Markdown, чанки с учётом токенов и сохранением заголовков, дедупликация по SHA-256.

• Лексический поиск SQLite FTS5/BM25 в облегчённой установке по умолчанию.

• Опциональный многоязычный семантический поиск только на CPU и гибридный поиск RRF на основе локальных эмбеддингов.

• Ограниченные ответы MCP с метаданными источника/позиции, курсорами, дедупликацией и лимитами соседних фрагментов.

• Аутентификация REST по API-ключу и MCP по Bearer-токену, безопасное хранение UUID, защита путей/симлинков, ограничение частоты запросов и структурированные логи без содержимого.

• Защищённое развёртывание Docker и Compose для AMD64/ARM64, Oracle Cloud, Tailscale или Caddy HTTPS.

• Помощник настройки, операционные команды doctor/scan/reindex/backup, версионируемая схема SQLite и CI.

Related MCP server: rag-retriever-mcp

Как это работает

REST upload or read-only inbox scan
        │
        ├─ type, signature, size, path, and free-space validation
        ├─ UUID storage + SHA-256 ── unchanged? ── reuse cached/indexed record
        │
        └─ MarkItDown ──> persistent Markdown ──> token-aware chunks
                                                   │
                              ┌────────────────────┴────────────────────┐
                              │                                         │
                    SQLite FTS5 / BM25                      optional local embeddings
                              │                                  + private Qdrant
                              └────────────────────┬────────────────────┘
                                                   │
                               ranking → dedup → token/char budget → MCP

Код держит контракты парсинга, хранения, репозитория, разбиения на чанки, эмбеддинга, векторного хранилища и поиска за интерфейсами, не превращая однострочный продукт в распределённую систему. Документы остаются основным источником данных; индексы Markdown и векторные индексы можно перестроить.

Поддерживаемые форматы

Зашифрованные, повреждённые, содержащие только сканированные изображения или неподдерживаемые конвертером файлы аварийно завершаются безопасно, не останавливая обработку других документов.

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

Требования: Docker Engine с Compose v2 и OpenSSL. Python на хосте не требуется.

git clone https://github.com/mustafa0zdemir/corpusgate.git
cd corpusgate
./corpusgate init
./corpusgate up
curl --fail http://127.0.0.1:8000/health
./corpusgate doctor

./corpusgate init создаёт постоянные каталоги и каталог inbox, копирует .env.example только в том случае, если .env ещё не существует, генерирует отдельные случайные учётные данные REST/MCP без их вывода, проверяет Docker/Compose и выбранный порт, а также проверяет сам Compose-файл. Существующий .env никогда не перезаписывается.

Эквивалентный ручной процесс: скопируйте .env.example в .env, замените оба заполнителя учётных данных разными значениями openssl rand -hex 32, затем создайте каталог documents/ и выполните docker compose up -d. Не помещайте .env в систему контроля версий.

Опциональный локальный семантический/гибридный поиск после инициализации включается тоже одной операцией:

./corpusgate init --semantic
./corpusgate up --semantic

Первый семантический запуск загружает модель в постоянный кэш, а затем запускает шлюз в автономном режиме с Qdrant во внутренней сети Docker. При последующих запусках тома модели и векторов не пересоздаются. Лексическая установка не устанавливает и не запускает ни один из семантических компонентов.

Добавление документов

Самый простой сценарий работы оператора — использование доступного только для чтения каталога inbox на хосте:

cp examples/documents/* documents/
./corpusgate scan
./corpusgate list-documents

Сканирование пропускает скрытые/системные/временные файлы, неподдерживаемые типы, каталоги и symlink. Входные файлы остаются в documents/; приватные копии с UUID хранятся в постоянном томе исходников. Полный проход «лексический → семантический/гибридный → MCP» описан в синтетическом демо.

Для сценария с одним файлом, который ИИ-инструменты могут запускать без попадания байтов файла в контекст модели, передайте локальный файл напрямую в запущнный REST API (требуется curl):

./corpusgate upload /absolute/path/to/document.pdf

Команда берёт REST-ключ из CORPUSGATE_CLIENT_API_KEY, CORPUSGATE_API_KEY или локального .env, никогда его не печатает, отклоняет редиректы и небезопасный удалённый HTTP и возвращает только метаданные загрузки API. Для удалённого приватного сервера укажите --url https://YOUR-NODE.YOUR-TAILNET.ts.net.

Загрузка также доступна приложениям через REST:

export CORPUSGATE_CLIENT_API_KEY='value-from-your-env'
curl --fail -X POST http://127.0.0.1:8000/api/v1/documents \
  -H "X-API-Key: ${CORPUSGATE_CLIENT_API_KEY}" \
  -F 'file=@examples/documents/private-network-guide.md'

REST также поддерживает постраничные метаданные, Markdown, чанки, лексический поиск и удаление по адресу /api/v1/documents. Интерактивная документация OpenAPI находится на /docs; защищённые операции по-прежнему требуют X-API-Key.

Подключение MCP-клиента

Удалённая конечная точка — https://YOUR_PRIVATE_OR_PUBLIC_HOST/mcp, и каждый MCP-запрос требует:

Authorization: Bearer YOUR_MCP_TOKEN

В качестве рекомендуемого приватного маршрута используйте Tailscale Serve. Caddy HTTPS — публичная альтернатива; в обоих случаях порт шлюза остаётся доступен только на локальном loopback хоста. Проверенное соответствие полей, команда Inspector, примеры Tailscale/HTTPS и устранение неполадок описаны в руководстве по подключению MCP. Не копируйте непроверенную клиентскую JSON-обёртку и не сохраняйте токен в системе контроля версий.

Инструменты MCP

Элементы выдачи последовательно включают document_id, document_name, chunk_id, heading, position, поля релевантности/ранга, ограниченный content, content_length и метаданные режима поиска. Пустая выдача возвращает пустой список items, применённые лимиты, метрики и не содержит курсора. Некорректные режимы, курсоры, фильтры, ID документов или значения сверх лимита приводят к контролируемым ошибкам инструментов. Загрузка и удаление остаются только через REST.

Рекомендуемый порядок действий:

AI tool → search_document(query, top_k=3, max_tokens=600)
        → ranked chunks + source positions + actual retrieval mode
        → optional bounded get_document_section

Лексический, семантический и гибридный поиск

• lexical — режим по умолчанию для эксплуатации: SQLite FTS5 с BM25, взвешенным по заголовкам, сохраняет точные идентификаторы и фразы без отдельных сервисов.

• semantic — вычисляет вложения запросов и чанков локально с помощью настраиваемой многоязычной CPU-модели и хранит векторы в приватном Qdrant.

• hybrid — объединяет независимые лексические и семантические ранги через Reciprocal Rank Fusion; дубликаты чанков выдются один раз, точные лексические совпадения не отбрасываются.

• lexical_fallback — появляется в ответе, когда запрошены semantic/hybrid, но локальная модель, векторный индекс или хранилище недоступны, и включён фолбэк.

Модель по умолчанию — Apache-2.0 sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2, 384-мерная многоязычная модель, работающая через FastEmbed/ONNX только на CPU. Замену модели, офлайн-перенос, правила переиндексации, замеры и рекомендации по памяти для Oracle см. в документации по семантическому поиску.

Оптимизация токенов

MarkItDown позволяет единообразно разбирать файлы разных форматов; сам по себе он не гарантирует уменьшение числа токенов. Шлюз сокращает возвращаемый контекст за счёт однократного кэширования конвертации, ранжирования чанков, исключения дубликатов, применения top_k, max_chars, оценочного max_tokens, лимита на соседние фрагменты и постраничной выдачи длинных результатов. В нём нет инструмента по умолчанию, который возвращает целый документ или исходный файл.

Число токенов — локальная детерминированная оценка, а не специфический для провайдера биллинговый токенизатор. Повторяемое синтетическое измерение и его точные границы описаны в отчёте об оценке поиска; универсальный процент экономии не заявлен.

Безопасность и конфиденциальность

• Нет телеметрии; тексты документов, запросы не покидают систему; нет облачного API для эмбеддингов; нет обязательного LLM-провайдера.

• Исходный файлы хранятся по путям UUID; проверяются path traversal, абсолютные пути, обход через симлинки, скрытые/временные файлы, MIME/сигнатуры, распаковка архивов, размер загрузки и заполнение диска.

• REST работает через API-ключи; удалённый MCP использует Bearer-токены, сравниваемые за константное время, из окружения или Docker secret. Возможна ротация при наличии нескольких актуальных/предыдущих токенов.

• Структурированные логи содержат разрешённые операционные метаданные и никогда не содержат содержимое документов, учётных данных, полных запросы или видимые клиенту обрывки стека выполнения.

• Контейнер шлюза — не-root без capabilities, с no-new-privileges, с корневым диском только для чтения, с явно определёнными writable-томами и tmpfs, с лимитами ресурсов и логов.

• Базовый Compose публикует только 127.0.0.1:8000; Qdrant доступен только внутри Docker-сети. Публичный доступ требует Caddy TLS и сохраняет Bearer-аутентификацию, rate limit и лимиты ответа.

Хранения включает приватные UUID-копии исходников, сгенерированный Markdown, метаданные/чанки/FTS в SQLite, опциональные локальные векторы/модельный кэш, резервное копии и настройки оператора. Чтобы удалить данные, сначала удалите документы через REST; затем удаляйте постоянные тома только после явного резервного копирования и остановки сервиса. Политика приватного параллельного отчёта об уязвимости — в SECURITY.md.

Развёртывание на Oracle Cloud

Рекомендуемое развёртывание на Oracle Ubuntu связывает приложение с loopback и использует Tailscale Serve для HTTPS в пределах tailnet; для случаев с доменом документирован профиль Caddy public. В Oracle Security Lists/NSG никогда не должны открываться порт TCP 8000 или порт Qdrant 6333.

Подготовка VM, примечания по AMD64/Ampere ARM64, установка Docker, владельца файловой системы, секреты, межсетевые экраны, Tailscale/Caddy, логирование, обновление, резервное копирование, восстановление и диагностика описаны в руководстве по развёртыванию на Oracle.

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

Все переменные окружения приложения, значения прописы, требования, диапазоны, примеры и их влияние на безопасность перечислены в контракте конфигурации и в .env.example. При старте отклоняются отсутствующие/недостаточные учётные данные, недопустимые портфолио и пути, незаконные сочетания чанк/бюджета, неподдерживаемые режимы поиска и неверная конфигурация семантического векторного хранилища; секретные значения не выводятся в эхо.

Операционные команды:

./corpusgate version
./corpusgate status
./corpusgate doctor
./corpusgate mcp-smoke
./corpusgate upload /absolute/path/to/document.pdf
./corpusgate scan
./corpusgate reindex
./corpusgate reindex --semantic
./corpusgate list-documents --limit 20 --offset 0

Резервное копирование и восстановление

./corpusgate backup
./corpusgate restore /backups/corpusgate-backup-TIMESTAMP.tar.gz --confirm-restore

Восстановление заменяет текущие постоянные данные и поэтому требует явного флага подтверждения и остановленного процесса записи в продакшене. Резервные копии включают приватное хранилище исходных документов, кэш Markdown, транзакционно скопированную базу данных SQLite, манифест и пример конфигурации без секретов. Храните .env и файлы токенов в отдельной зашифрованной резервной копии секретов. Векторные данные можно пересоздать из чанков.

Обновление и откат

Определите текущую версию, создайте резервную копию, выберите проверенный тег/образ, запустите версионированную идемпотентную миграцию, перезапустите сервис, проверьте готовность/MCP и сохраняйте резервную копию до завершения проверки. База данных, созданная более новым несовместимым приложением, отклоняется, а не молча изменяется.

Точные команды и безопасный путь отката/восстановления описаны в документе «Обновление и откат». Никогда не запускайте docker compose down -v во время обычного обновления.

В репозитории также есть ручной workflow GHCR, требующий одобрения. Поведение стабильного тега, перемещаемого минорного тега и latest описано в политике публикации контейнеров; в рамках этого спринта не было опубликовано ни одного образа.

Устранение неполадок

• ./corpusgate doctor: проверяет конфигурацию, права доступа к хранилищу, SQLite/схему, диск, опциональное состояние модели/векторов, готовность сервиса и версию, не раскрывая секреты.

• 401: используйте REST X-API-Key или MCP Authorization: Bearer, а не другой тип учётных данных.

• Отклонение хоста: добавьте точный хост Tailscale/домена в CORPUSGATE_ALLOWED_HOSTS и пересоздайте шлюз.

• 507: освободите место на диске или пересмотрите порог зарезервированного дискового пространства перед повторной попыткой загрузки.

• lexical_fallback: проверьте кэш модели и состояние Qdrant; лексический поиск остаётся доступен.

• Сбой преобразования: проверьте поддерживаемое расширение, MIME/сигнатуру, целостность UTF-8/Office-архива, размер, шифрование и наличие текстового слоя в PDF.

• Журналы: ./corpusgate logs --tail=100; удаляйте чувствительные данные из вывода перед передачей.

См. SUPPORT.md и руководство по устранению неполадок для конкретного развёртывания, прежде чем открывать issue.

Совместимость

Непроверенные платформы не подаются как поддерживаемые. Перед публикацией артефактов ознакомьтесь с чек-листом выпуска.

Ограничения

• Одноузловой SQLite — не высокодоступная и не многозаписывающая СУБД.

• Загрузка и конвертация синхронны в 0.1.0; для больших документов могут потребоваться более длинные тайм-ауты клиента/прокси.

• Нет OCR, адаптера облачного хранилища, учётных записей пользователей, UI, генерации ответов, реранкейра, тонкой настройки или SaaS-контроллера.

• Приблизительные бюджеты токенов могут отличаться от токенизатора конкретной LLM.

• Загрузка семантической модели требует временного исходящего доступа, если кэш не был перенесён офлайн.

План развития

• Фоновые задачи конвертации без обязательного Redis для одноузловых пользователей.

• Опциональные адаптеры PostgreSQL/pgvector и объектного хранилища за существующими интерфейсами.

• Более активное извлечение метаданных конвертером и управляемый оператором адаптер OCR.

• Подписанные выпуски, SBOM/происхождение артефактов, расширенные кросс-архитектурные и обновляемые настпробы.

Вклад в разработку

Прочтите CONTRIBUTING.md, следуйте CODE_OF_CONDUCT.md, добавляйте тесты и используйте только синтетические нечувствительные фикстуры. Отчёты об уязвимостях должны использовать приватный канал, указанный в SECURITY.md, и никогда не должны попадать в публичную issue.

Лицензия

CorpusGate выпускается под существующей MIT License. Сторонние библиотеки и опциональная модель эмбеддингов сохраняют свои собственные лицензии.