🔍 Percival Deep Research (MCP-Server)

Übersicht

Percival Deep Research ist ein leistungsfähiger MCP-Server (Model Context Protocol), der entwickelt wurde, um das Nanobot-Agenten-Ökosystem mit autonomen, tiefgreifenden Web-Recherchefunktionen auszustatten. Er erkundet und validiert autonom zahlreiche Quellen und konzentriert sich dabei nur auf relevante, vertrauenswürdige und aktuelle Informationen.

Während Standard-Suchwerkzeuge rohe Schnipsel zurückgeben, die manuell gefiltert werden müssen, liefert Percival Deep Research vollständig aufbereitetes, umfassendes Material aus mehreren Quellen, das die Kontext- und Argumentationsfähigkeiten intelligenter Agenten erheblich beschleunigt.

Hinweis: Dieses Projekt verwendet die GPT Researcher-Bibliothek als Kern-Web-Treiber, wurde jedoch umfassend refactored, gehärtet und speziell für das percival.OS-Ökosystem entkoppelt.

✨ Hauptfunktionen & Verbesserungen

Dieser Server wurde stark modifiziert, um den strengen Anforderungen von Open-Source-LLMs und modernen Deployment-Arrays gerecht zu werden:

• ⚡ Ultimative Anbieter-Portabilität: Vollständig agnostische Inferenz-Engine. Native, absturzfreie Unterstützung für führende Open-Weights-Plattformen wie Venice AI, MiniMax und OpenRouter. Wir haben einen benutzerdefinierten Persona-Bypass implementiert, der die berüchtigten Validierungsfehler bei JSON-Dictionaries, die zuvor durch Nicht-OpenAI-Modelle während der Recherche-Orchestrierung verursacht wurden, vollständig eliminiert.

• 🛡️ JSON-RPC-Protokoll-Leitplanken: Erzwingt eine strikte Redaktion der stdio-Ausgabe. Das gesamte Rauschen der zugrunde liegenden Bibliothek, Konsolen-Rendering und Echtzeit-Logs werden physisch auf stderr umgeleitet. Dies verhindert Pydantic ValidationErrors vollständig und schützt den stdout-Stream, der für die MCP-Synchronisation entscheidend ist.

• 🔐 Defense-in-Depth-Sicherheit: Alle Eingaben werden gründlich gegen Prompt-Injection bereinigt. Nicht vertrauenswürdige Webinhalte werden in nicht ausführbare Header verpackt, um die Autonomie Ihres Agenten zu schützen.

• 🤖 Fokus auf Nanobot: Eliminiert lose .env-Lesemuster, um die Umgebungsinjektion direkt von der Host-Anwendung strikt zu berücksichtigen.

📑 Inhaltsverzeichnis

• Referenz für Tools & Ressourcen

• Voraussetzungen

• Installation

• 🤖 Nanobot-Integration (Hauptfokus)

• 💻 Claude Desktop-Integration

• Sicherheit

🛠️ Referenz für Tools & Ressourcen

Ressource

Tools

Recherche-Pipeline

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

⚙️ Voraussetzungen

• Python 3.11+

• uv — Projekt- und Abhängigkeitsmanager

• API-Schlüssel für den Generative LLM-Anbieter (z. B. Venice, MiniMax, OpenRouter).

Hinweis: Die standardmäßig konfigurierte Websuchmaschine ist duckduckgo, die keinen API-Schlüssel erfordert. Sie können optional andere Websuchmaschinen nativ konfigurieren.

⚙️ Installation

1. Einheitliches Umgebungs-Setup

Stellen Sie sicher, dass Sie das einheitliche percival.OS-Build-Ökosystem verwenden:

cd percival.OS_Dev
uv sync

Dies stellt sicher, dass percival-deep-research das globale .venv erbt.

2. Umgebung konfigurieren

Dieses Modul deaktiviert das Laden von .env (dotenv), um die vom MCP-Host übergebenen Systemvariablen strikt zu berücksichtigen.

Wenn Sie über Nanobot (~/.nanobot/config.json) oder andere Endpunkte aufrufen, definieren Sie die Umgebungsvariablen direkt im Konfigurations-Array:

"OPENAI_API_KEY": "your_api_key_from_venice_minimax_openrouter_etc",
"OPENAI_BASE_URL": "https://api.venice.ai/api/v1",
"FAST_LLM": "openai:e2ee-qwen-2-5-7b-p",
"SMART_LLM": "openai:minimax-m27",
"STRATEGIC_LLM": "openai:zai-org-glm-4.7-flash",
"RETRIEVER": "duckduckgo"

🤖 Nanobot-Integration (Hauptfokus)

Dieser Server ist grundlegend darauf abgestimmt, als stdio MCP-Server zu laufen, der vom Nanobot-Assistenten gesteuert wird.

Fügen Sie Folgendes zu Ihrer ~/.nanobot/config.json hinzu:

{
  "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": "openai:e2ee-qwen-2-5-7b-p",
        "RETRIEVER": "duckduckgo"
      },
      "tool_timeout": 300
    }
  }
}

Hinweis: deep_research kann bis zu 2-3 Minuten dauern. Stellen Sie sicher, dass tool_timeout entsprechend skaliert ist (z. B. 180-300).

Wichtige Designentscheidungen für Nanobot

• Klartext statt JSON-Dicts — Alle Tools geben vorhersehbar Klartext-Strings statt JSON-Dicts zurück, um Nanobot mit sauberem Text zu versorgen.

• Kontext-Modularität — deep_research lässt den riesigen synthetisierten Kontext aus seiner Initialisierungsantwort weg, um das Kontextfenster von Nanobot nicht zu sprengen. Stattdessen gibt es eine research_id aus, die der Agent dann verwendet, um explizit get_research_context aufzurufen.

💻 Claude Desktop-Integration

Obwohl Nanobot der bevorzugte Treiber ist, fügen Sie bei einer Bereitstellung für Claude Desktop Folgendes zu Ihrer claude_desktop_config.json hinzu:

{
  "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": "openai:e2ee-qwen-2-5-7b-p",
        "RETRIEVER": "duckduckgo"
      }
    }
  }
}

🔐 Sicherheit

Dieser Server implementiert Defense-in-Depth, um die Risiken eines MCP-Servers anzugehen, der nicht vertrauenswürdige Webinhalte autonom verarbeitet.

Schutz vor Prompt-Injection

Benutzereingaben (query, topic, custom_prompt) schränken unbekannte und falsch formatierte Werte ein. Ein Regex-basierter Filter blockiert bekannte Jailbreak-Muster (<system>, [INST], ignore instructions usw.).

Isolierung nicht vertrauenswürdiger Inhalte

Alle aus dem Web abgerufenen Inhalte werden dynamisch mit einem Präfix versehen, bevor sie dem Agenten-Kontext präsentiert werden:

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

Dies zwingt Modelle wie Nanobot dazu, Web-basierte Daten strikt als Informationsblöcke zu behandeln, um unerwartete Befehlsausführungen zu vermeiden.

📄 Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert.