Pharos MCP
Локальная база знаний по PDF, сканам и файлам Office: гибридный поиск, права доступа и ответы с ссылкой на страницу
- 241 ★ репозитория
- Последний коммит
- MIT
Расширенный доступ
Почему такой уровень
- Агент читает все документы, видимые выбранной идентичности, и разворачивает их до целых статей
- Через `/v1/ask` найденные фрагменты уходят во внешний API DeepSeek
- Найденные фрагменты помечены как недоверенные данные, но текст документов все равно попадает в контекст агента
Установка
- Работает в
Ручная установка
pip install -e '.[dev]'Выполняется в клонированном репозитории, нужен Python 3.10 или новее. Для GPU-режима добавьте extra `gpu`.
Доступ и проверки
Как мы проверяемРасширенный доступИнструмент запускает код или ходит в сеть, а внешние данные только читает.
- Агент читает все документы, видимые выбранной идентичности, и разворачивает их до целых статей
- Через `/v1/ask` найденные фрагменты уходят во внешний API DeepSeek
- Найденные фрагменты помечены как недоверенные данные, но текст документов все равно попадает в контекст агента
Это чужой код. Посмотрите файлы в репозитории перед установкой.
Что делает
Pharos собирает PDF, сканы, docx, pptx и xlsx в локальную базу знаний и отвечает на вопросы по ней со ссылками на страницу источника. Поиск гибридный, а права доступа проверяются при каждом запросе: документ без разрешений никому не виден. У системы два выхода. Команда `pharos serve` поднимает HTTP API, где `/v1/ask` проходит замкнутую цепочку: поиск, проверка опоры на источник, ответ модели DeepSeek с цитатами. Команда `pharos mcp` открывает агенту, например Claude Code, MCP-инструменты, и агент сам решает, когда искать, как переписать запрос и нужен ли второй проход. Инструментов шесть: `retrieve`, `list_documents`, `get_document`, `get_outline`, `expand` и `retrieve_grouped`. Тяжелые ресурсы держит постоянно работающая служба, потому что встроенный Qdrant принимает одного клиента, а модель на 8 млрд параметров грузится минуту-две. MCP остается тонким HTTP-адаптером и стартует мгновенно. Без службы работает `pharos mcp --direct`: он говорит по stdio и сам загружает GPU-модель.
Для кого. Командам, у которых накопилась библиотека PDF, сканов и офисных файлов, нужны ответы с цитатами и разные права доступа для сотрудников.
Подходит, если
- В отделе сотни PDF и презентаций, и на вопрос «что у нас есть по теме» нужен ответ с цитатой и номером страницы
- Агент в Claude Code должен сам искать по внутренним документам и решать, когда взять соседние фрагменты или всю статью целиком
- У сотрудников разные права, и один человек не должен видеть чужие документы даже через агента
- Индекс хранят на своем сервере с видеокартой, без облачной векторной базы
- Хочется разобрать устройство промышленного RAG: в репозитории 12 разборов от нарезки до оценки качества, на китайском
Не подходит, если
- Нужен облачный сервис без администрирования: индекс строят вручную командой `pharos index`, а службу ведет администратор
- Документов немного, и все они в текстовых файлах: обычного поиска агента по папке хватит
- Нужен доступ из интернета: HTTPS и публикация наружу исключены из целей проекта, а удаленный доступ рекомендуют строить через туннель
Пример запроса к агенту
Найди в нашей библиотеке документов все, что сказано про условия возврата, и приведи страницы источниковMCP
- Транспорт
- stdio
- Авторизация
- API-ключ
Переменные окружения
PHAROS_URLобязательная- Адрес службы `pharos serve`, по умолчанию `http://127.0.0.1:8787`
PHAROS_API_KEYобязательная, секрет- Ключ идентичности, выданный командой `pharos keys new`
PHAROS_TENANT- Арендатор для режима `--direct`: без него поиск возвращает пустой результат
DEEPSEEK_API_KEYсекрет- Нужен службе для `/v1/ask`
Ограничения
Вся документация, кроме README, написана по-китайски, включая серию разборов RAG. Модель эмбеддингов работает на GPU: пример конфигурации рассчитан на WSL, и Claude Code запускает сервер через `wsl`. Корпус для индексации берут из каталога с результатами разбора MinerU, поэтому сканы и файлы Office сначала проходят этот разбор. Службу и `pharos mcp --direct` нельзя открыть на одном индексе одновременно: встроенный Qdrant принимает одного клиента.
Как отключить. Удалите блок `rag` из `.mcp.json` проекта, и агент перестанет видеть инструменты. Службу останавливает `sudo systemctl stop pharos`, если вы поставили ее под systemd. Индекс по умолчанию лежит в `~/rag_real`.
Частые вопросы
Как подключить Pharos к Claude Code?
Скопируйте `.mcp.json.example` в `.mcp.json`, впишите свой `PHAROS_API_KEY` и локальные пути и запустите службу. Агент получит инструмент для поиска по библиотеке.
Как выдать сотруднику доступ?
Администратор создает идентичность командой `python -m pharos keys new alice --tenant demo --admin` или без `--admin`, с группами через `--principals`. Ключ печатается один раз, а список ключей хранит файл из `PHAROS_KEYS_FILE`.
Зачем нужен ключ DeepSeek?
Он нужен только для `/v1/ask`, где ответ формирует модель DeepSeek. MCP-инструменты ключ DeepSeek не используют: ответ строит сам агент по найденным фрагментам.
Может ли агент сам расширить свои права?
Нет, идентичность задается на сервере: ключ определяет арендатора и группы, и параметры инструментов их не меняют. Неизвестный или пустой ключ дает ответ 401.
Как запустить тесты без видеокарты?
`python -m pytest tests -q --ignore=tests/engine` прогоняет только продуктовый слой на фиктивном поисковике и MockLLM, без GPU и сети.
Обсуждение
Вопросов и отзывов пока нет.
Похожие
MCP-серверыЛокальный MCP-сервер, который превращает папку с документами в базу знаний с гибридным поиском для Claude Code и Cursor
Самохостинг RAG-приложение с веб-интерфейсом и встроенным MCP-сервером: документы, Qdrant, ответы с источниками.
CLI и MCP-сервер для извлечения структурированных знаний из документов: графы, гиперграфы и поиск по фактам с источниками
MCP-сервер дает агенту поиск и ответы по локальным документам с гибридным индексом, повторным ранжированием и ссылками на разделы.
MCP-сервер для поиска и загрузки научных статей из arXiv, PubMed, bioRxiv, Semantic Scholar и других открытых источников
MCP-сервер для платформы GraphRAG: загрузка документов из 14 источников, гибридный поиск и ответы ИИ по графу знаний
Сравнение с похожими
Карточки с тем же главным запросом: чем они отличаются.
| Инструмент | Официальный | Авторизация | Звезды репозитория | Главное отличие |
|---|---|---|---|---|
| Pharos (эта карточка) | нет | API-ключ | 241 | |
| knowledge-rag | нет | не нужна | 301 | тоже гибридный поиск по папке документов для Claude Code, а Pharos добавляет права по пользователям и отдельный HTTP-режим с ответами и цитатами |
| MCP Local RAG | нет | не нужна | 429 | локальный поиск без ключей и внешней базы для одного человека, а Pharos рассчитан на команду, службу на GPU и Qdrant |
| haiku.rag | нет | не нужна | 648 | агентный RAG с цитатами на встроенной LanceDB, а Pharos держит индекс в Qdrant под службой с разграничением доступа |
Коротко о README
README на английском служит входом в систему: схема архитектуры, две двери HTTP и MCP, развертывание от одного сервера до трех независимых уровней, модель безопасности и индекс документации. Автор подчеркивает, что решения проекта опираются на измерения на 77 реальных документах.