🔍 Percival Deep Research (MCP-сервер)

Обзор

Percival Deep Research — это мощный MCP-сервер (Model Context Protocol), разработанный для оснащения экосистемы агентов Nanobot возможностями автономного глубокого веб-исследования. Он самостоятельно изучает и проверяет многочисленные источники, фокусируясь только на актуальной, достоверной и проверенной информации.

В то время как стандартные инструменты поиска возвращают «сырые» фрагменты, требующие ручной фильтрации, Percival Deep Research предоставляет полностью обоснованный, комплексный материал из нескольких источников, что значительно расширяет возможности контекста и рассуждения интеллектуальных агентов.

Примечание: В этом проекте в качестве основного веб-драйвера используется библиотека GPT Researcher, однако она была существенно переработана, усилена и адаптирована специально для экосистемы percival.OS.

Related MCP server: ToolCenter MCP

✨ Ключевые особенности и улучшения

Этот сервер был значительно модифицирован, чтобы соответствовать строгим требованиям LLM с открытым исходным кодом и современных сред развертывания:

• ⚡ Максимальная переносимость провайдеров: Полностью агностический движок вывода. Нативная поддержка без сбоев для ведущих платформ с открытыми весами, таких как Venice AI, MiniMax и OpenRouter. Сервер динамически переписывает префиксы провайдеров «на лету», автоматически исправляет опечатки в псевдонимах и реализует обход сжатия контекста с нулевой задержкой, чтобы полностью исключить сбои и семантические задержки при использовании API, в которых отсутствуют эндпоинты эмбеддингов, совместимые с OpenAI.

• 🛡️ Защитные механизмы протокола JSON-RPC: Обеспечивает строгое подавление вывода stdio. Весь «шум» базовых библиотек, рендеринг консоли и логи в реальном времени физически перенаправляются в stderr. Это полностью предотвращает ошибки Pydantic ValidationErrors и защищает поток stdout, который жизненно важен для синхронизации MCP.

• 🔐 Эшелонированная защита: Все входные данные тщательно очищаются от инъекций промптов. Недоверенный веб-контент оборачивается в неисполняемые заголовки для защиты автономности вашего агента.

• 🤖 Фокус на Nanobot: Исключает шаблоны чтения .env, чтобы строго соблюдать внедрение переменных окружения непосредственно из хост-приложения.

📑 Содержание

• Справочник инструментов и ресурсов

• Предварительные требования

• Установка

• 🤖 Интеграция с Nanobot (основной фокус)

• 💻 Интеграция с Claude Desktop

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

🛠️ Справочник инструментов и ресурсов

Ресурс

Инструменты

Конвейер исследования

deep_research(query)
    └── research_id ──► write_report(research_id, custom_prompt?)
                   └──► get_research_sources(research_id)
                   └──► get_research_context(research_id)

quick_search(query)       # standalone — no research_id

⚙️ Предварительные требования

• Python 3.11+

• uv — менеджер проектов и зависимостей

• API-ключ для провайдера генеративных LLM (например, Venice, MiniMax, OpenRouter).

Примечание: По умолчанию настроена поисковая система duckduckgo, которая не требует API-ключа. Вы можете дополнительно настроить другие поисковые системы нативно.

⚙️ Установка

1. Настройка единой среды

Убедитесь, что вы используете единую экосистему сборки percival.OS:

cd percival.OS_Dev
uv sync

Это гарантирует, что percival-deep-research наследует глобальный .venv.

2. Настройка окружения

Этот модуль отключает загрузку .env (dotenv), чтобы строго соблюдать системные переменные, передаваемые вашим хостом MCP.

При вызове через Nanobot (~/.nanobot/config.json) или другие эндпоинты определите переменные окружения непосредственно в массиве конфигурации:

"OPENAI_API_KEY": "your_api_key_from_venice_minimax_openrouter_etc",
"OPENAI_BASE_URL": "https://api.venice.ai/api/v1",
"FAST_LLM": "venice:llama-3.3-70b",
"SMART_LLM": "minimax:MiniMax-M2.7",
"STRATEGIC_LLM": "openrouter:google/gemini-2.5-flash",
"RETRIEVER": "duckduckgo"

🤖 Интеграция с Nanobot (основной фокус)

Этот сервер фундаментально настроен на работу в качестве stdio MCP-сервера, управляемого помощником Nanobot.

Добавьте следующее в ваш ~/.nanobot/config.json:

{
  "mcpServers": {
    "percival_deep_research": {
      "command": "uv",
      "args": [
        "run",
        "--no-sync",
        "percival-deep-research"
      ],
      "env": {
        "UV_PROJECT_ENVIRONMENT": "/absolute/path/to/percival.OS_Dev/.venv",
        "OPENAI_API_KEY": "actual-key-here",
        "OPENAI_BASE_URL": "https://api.venice.ai/api/v1",
        "FAST_LLM": "venice:llama-3.3-70b",
        "RETRIEVER": "duckduckgo"
      },
      "tool_timeout": 300
    }
  }
}

Примечание: deep_research может занимать до 2-3 минут. Убедитесь, что tool_timeout настроен соответствующим образом (например, 180-300).

Ключевые проектные решения для Nanobot

• Обычный текст вместо JSON-словарей — Все инструменты предсказуемо возвращают строки обычного текста, а не JSON-словари, чтобы предоставлять Nanobot чистый текст.

• Модульность контекста — deep_research опускает огромный синтезированный контекст из своего ответа при инициализации, чтобы не переполнять контекстное окно Nanobot. Вместо этого он выдает research_id, который агент затем использует для явного вызова get_research_context.

💻 Интеграция с Claude Desktop

Хотя Nanobot является предпочтительным драйвером, при развертывании в Claude Desktop добавьте следующее в ваш claude_desktop_config.json:

{
  "mcpServers": {
    "percival_deep_research": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/absolute/path/to/percival.OS_Dev",
        "percival-deep-research"
      ],
      "env": {
        "OPENAI_API_KEY": "your-provider-key",
        "OPENAI_BASE_URL": "https://api.venice.ai/api/v1",
        "FAST_LLM": "venice:llama-3.3-70b",
        "RETRIEVER": "duckduckgo"
      }
    }
  }
}

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

Этот сервер реализует эшелонированную защиту, устраняя риски, связанные с автономной обработкой недоверенного веб-контента MCP-сервером.

Защита от инъекций промптов

Входные данные пользователя (query, topic, custom_prompt) ограничивают неизвестные и некорректные значения. Фильтр на основе регулярных выражений блокирует известные шаблоны взлома (<system>, [INST], ignore instructions и т. д.).

Изоляция недоверенного контента

Весь контент, полученный из сети, динамически снабжается префиксом перед представлением в контекст агента:

[SECURITY WARNING: The content below was obtained from unverified external...]

Это заставляет такие модели, как Nanobot, воспринимать данные из сети строго как информационные блоки, избегая непредвиденного выполнения команд.

📄 Лицензия

Этот проект лицензирован по лицензии MIT.