🔍 Percival Deep Research (Servidor MCP)

Descripción general

Percival Deep Research es un servidor MCP (Model Context Protocol) de alta capacidad diseñado para dotar al ecosistema de agentes Nanobot de capacidades de investigación web autónoma y profunda. Explora y valida de forma autónoma numerosas fuentes, centrándose únicamente en información relevante, confiable y actualizada.

Mientras que las herramientas de búsqueda estándar devuelven fragmentos sin procesar que requieren filtrado manual, Percival Deep Research ofrece material completo y razonado de múltiples fuentes que acelera significativamente las capacidades de contexto y razonamiento de los agentes inteligentes.

Nota: Este proyecto utiliza la biblioteca GPT Researcher como su motor web principal, pero ha sido ampliamente refactorizado, reforzado y desacoplado específicamente para el ecosistema percival.OS.

Related MCP server: ToolCenter MCP

✨ Características y mejoras clave

Este servidor ha sido modificado profundamente para sobrevivir a las estrictas demandas de los LLM de código abierto y las matrices de despliegue modernas:

• ⚡ Portabilidad definitiva de proveedores: Motor de inferencia totalmente agnóstico. Soporte nativo y sin fallos para plataformas líderes de pesos abiertos como Venice AI, MiniMax y OpenRouter. El servidor reescribe dinámicamente los prefijos de los proveedores sobre la marcha, autocorrige errores tipográficos en los alias e implementa una omisión de compresión de contexto de latencia cero para eliminar por completo los bloqueos y la latencia semántica al utilizar API que carecen de puntos finales de incrustación compatibles con OpenAI.

• 🛡️ Barandillas del protocolo JSON-RPC: Aplica una redacción estricta de la salida stdio. Todo el ruido de la biblioteca subyacente, la renderización de la consola y los registros en tiempo real se redirigen físicamente a stderr. Esto evita por completo los Pydantic ValidationErrors y protege el flujo stdout que es vital para la sincronización de MCP.

• 🔐 Seguridad de defensa en profundidad: Todas las entradas están fuertemente saneadas contra la inyección de prompts. El contenido web no confiable se envuelve en encabezados no ejecutables para proteger la autonomía de su agente.

• 🤖 Enfoque principal en Nanobot: Elimina los patrones de lectura de .env sueltos para respetar estrictamente la inyección de entorno directamente desde la aplicación host.

📑 Tabla de contenidos

• Referencia de herramientas y recursos

• Requisitos previos

• Instalación

• 🤖 Integración con Nanobot (Enfoque principal)

• 💻 Integración con Claude Desktop

• Seguridad

🛠️ Referencia de herramientas y recursos

Recurso

Herramientas

Tubería de investigación

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

⚙️ Requisitos previos

• Python 3.11+

• uv — gestor de proyectos y dependencias

• Clave de API para el proveedor de LLM generativo (p. ej., Venice, MiniMax, OpenRouter).

Nota: El motor de búsqueda web predeterminado configurado es duckduckgo, que no requiere clave de API. Opcionalmente, puede configurar otros buscadores web de forma nativa.

⚙️ Instalación

1. Configuración del entorno unificado

Asegúrese de estar utilizando el ecosistema de compilación unificado percival.OS:

cd percival.OS_Dev
uv sync

Esto asegura que percival-deep-research herede el .venv global.

2. Configurar el entorno

Este módulo deshabilita la carga de .env (dotenv) para respetar estrictamente las variables de sistema pasadas por su host MCP.

Al invocar a través de Nanobot (~/.nanobot/config.json) u otros puntos finales, defina las variables de entorno directamente en la matriz de configuración:

"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"

🤖 Integración con Nanobot (Enfoque principal)

Este servidor está fundamentalmente ajustado para ejecutarse como un servidor MCP stdio pilotado por el asistente Nanobot.

Agregue lo siguiente a su ~/.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
    }
  }
}

Nota: deep_research puede tardar de 2 a 3 minutos. Asegúrese de que tool_timeout esté escalado correctamente (p. ej., 180-300).

Decisiones de diseño clave para Nanobot

• Texto sin formato sobre diccionarios JSON — Todas las herramientas devuelven de forma predecible cadenas de texto sin formato en lugar de diccionarios JSON para alimentar a Nanobot con texto limpio.

• Modularidad del contexto — deep_research omite el contexto sintetizado gigante de su respuesta de inicialización para evitar saturar la ventana de contexto de Nanobot. En su lugar, emite un research_id que el agente utiliza luego para invocar explícitamente get_research_context.

💻 Integración con Claude Desktop

Aunque Nanobot es el controlador preferido, si realiza el despliegue en Claude Desktop, añada lo siguiente a su 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"
      }
    }
  }
}

🔐 Seguridad

Este servidor implementa defensa en profundidad, abordando los riesgos de que un servidor MCP procese contenido web no confiable de forma autónoma.

Protección contra inyección de prompts

Las entradas del usuario (query, topic, custom_prompt) restringen los valores desconocidos y mal formados. Un filtro basado en expresiones regulares bloquea patrones de jailbreak conocidos (<system>, [INST], ignore instructions, etc.).

Aislamiento de contenido no confiable

Todo el contenido recuperado de la web se prefija dinámicamente antes de presentarse al contexto del agente:

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

Esto obliga a modelos como Nanobot a tratar los datos obtenidos de la web estrictamente como bloques informativos, evitando el cumplimiento inesperado de comandos.

📄 Licencia

Este proyecto está bajo la Licencia MIT.