ResearchTwin MCP Server

ResearchTwin MCP Server ist die persistente Aktionsschicht für ResearchTwin, einen langfristig angelegten Forschungsprojekt-Agenten. Es bietet einem OpenTrek-gehosteten Agenten echte MCP-Werkzeuge zum Aufzeichnen von Forschungsarbeit, zum Beibehalten des Projektstatus und der Anforderungen von Betreuern sowie zum Erstellen evidenzbasierter Fortschrittsberichte.

Das Repository ist als Referenzimplementierung in Wettbewerbsqualität konzipiert: RAG beantwortet Fragen aus Forschungsmaterial, während MCP explizite, nachvollziehbare Änderungen am Projektprotokoll vornimmt.

Alle committeten Beispiele sind fiktiv und anonymisiert. Betriebsdaten gehören in runtime_data/ und sind absichtlich von Git ausgeschlossen.

Überblick

Ein Forschungsassistent sollte mehr tun, als nur eine einzelne Frage zu beantworten. ResearchTwin führt eine dauerhafte Aufzeichnung darüber, was in einem sich entwickelnden Projekt passiert ist:

• konkrete Aktivitäten, Ergebnisse, Hindernisse und nächste Schritte;

• die aktuelle Projektphase, Aufgaben, Risiken und Entscheidungen;

• strukturierte Anforderungen von Betreuern;

• wöchentliche, Besprechungs- oder Phasenberichte, die aus gespeicherten Belegen zusammengestellt werden.

Der Server ist dafür gedacht, vom ResearchTwin-Agenten in OpenTrek aufgerufen zu werden. Er ersetzt weder den Agenten, ein LLM noch die bestehende Wissensbasis ResearchTwin_Docs.

Related MCP server: AgentBase

Warum MCP

RAG und MCP haben unterschiedliche Verantwortlichkeiten:

Diese Trennung hält das Projektprotokoll deterministisch und überprüfbar. Der MCP-Server muss kein weiteres LLM ausführen, nur um eine strukturierte Aktivität zu speichern oder einen Bericht aus gespeicherten Fakten zu erstellen.

Architektur

flowchart LR
    U[Researcher] --> A[OpenTrek ResearchTwin Agent]
    A -->|retrieve and reason| R[ResearchTwin_Docs RAG]
    R --> K[Research papers and technical material]
    A -->|MCP function calls| M[ResearchTwin MCP Server]
    M --> T[Six research-management tools]
    T --> S[JSON persistence layer]
    S --> D[Runtime research records and reports]

Siehe docs/architecture.md für Komponentengrenzen, Persistenzregeln und Erweiterungspunkte.

Funktionen

• Offizielle Python-MCP-SDK-Integration.

• Streamable HTTP als primärer MCP-Transport unter /mcp.

• Optionaler Befehlszeilen-SSE-Kompatibilitätstransport, wenn beim Start ausgewählt.

• Sechs fokussierte Tools statt eines monolithischen Server-Skripts.

• UTF-8-JSON-Persistenz mit atomarem Ersetzen und In-Process-Sperre.

• UUID-Datensatz-IDs und zeitzonenbewusste ISO-8601-Zeitstempel.

• Strukturierte Erfolgs- und Fehlerantworten, die für die Tool-Verarbeitung durch Agenten geeignet sind.

• Windows-PowerShell-Anleitung für Start, Test, Smoke-Test und OpenTrek-Integration.

MCP-Tools

Der vollständige Vertrag für Eingabe, Ausgabe und Fehler finden Sie in docs/mcp_tools.md.

Projektstruktur

ResearchTwin-MCP-Server/
├── server.py                         # Repository-root launch entry point
├── src/researchtwin_mcp/
│   ├── config.py                     # RESEARCHTWIN_* settings validation
│   ├── server.py                     # MCP server and transport startup
│   ├── models/                       # Validation helpers and schemas
│   ├── storage/                      # Shared JSON persistence layer
│   └── tools/                        # Activity, status, advisor, and report tools
├── scripts/
│   ├── start_server.ps1
│   └── smoke_test.py
├── tests/
├── docs/
├── examples/sample_data/             # Fictional, commit-safe demo data
└── runtime_data/                     # Local operational data; ignored by Git

Anforderungen

• Windows PowerShell (der dokumentierte Workflow)

• Python 3.11 oder neuer; Python 3.11.x ist die empfohlene Wettbewerbsumgebung

• Netzwerkzugriff nur, wenn OpenTrek von einem anderen Gerät im LAN ausgeführt wird

Installation

Aus einer neuen Windows-PowerShell-Sitzung:

Set-Location C:\work\OpenTrek\ResearchTwin-MCP-Server
python --version
where.exe python

python -m venv .venv
.\.venv\Scripts\Activate.ps1

python --version
where.exe python
python -m pip install --upgrade pip setuptools wheel
python -m pip install -e ".[dev]"

Das erste Ergebnis von where.exe python sollte nach der Aktivierung der Interpreter der virtuellen Umgebung sein. Wenn PowerShell die Aktivierung für die aktuelle Sitzung blockiert, verwenden Sie das dokumentierte prozessbezogene Ausführungsrichtlinienverfahren und aktivieren Sie die Umgebung erneut. Schwächen Sie die systemweite Richtlinie nicht unnötig.

Konfiguration

Der Server liest diese Umgebungsvariablen aus der Prozessumgebung:

.env.example ist nur eine Referenz/Vorlage; der Server lädt keine .env-Datei automatisch. Legen Sie Werte in der PowerShell-Sitzung fest oder verwenden Sie einen externen Umgebungs-Loader, falls Ihre Bereitstellung bereits einen hat:

$env:RESEARCHTWIN_HOST = "0.0.0.0"
$env:RESEARCHTWIN_PORT = "8000"
$env:RESEARCHTWIN_DATA_DIR = "runtime_data"
$env:RESEARCHTWIN_LOG_LEVEL = "INFO"

Legen Sie keine Schlüssel, persönliche Kennungen oder eine benutzerspezifische IP-Adresse in Quellcode oder committete Konfiguration.

Ausführen

Bei aktiver virtueller Umgebung:

python server.py

Der standardmäßige primäre Endpunkt ist:

http://<LAN_IPV4>:8000/mcp

Nur für den lokalen Rechner ersetzen Sie <LAN_IPV4> durch 127.0.0.1. Für OpenTrek auf einem anderen vertrauenswürdigen LAN-Gerät verwenden Sie die zutreffende IPv4-Adresse des Windows-Hosts. Das Hilfsskript ist ebenfalls verfügbar:

.\scripts\start_server.ps1

Streamable HTTP ist der normale Modus. Für explizite SSE-Kompatibilität führen Sie python server.py --transport sse aus und registrieren den resultierenden /sse-Endpunkt wie in der OpenTrek-Integrationsanleitung dokumentiert. SSE ist ein separat ausgewählter Transportmodus, keine alternative URL, die neben /mcp registriert wird.

Test

Führen Sie Unit-Tests aus dem Repository-Stammverzeichnis aus:

pytest -v

Führen Sie den lokalen MCP-Streamable-HTTP-Smoke-Test aus, nachdem die Abhängigkeiten installiert wurden:

python scripts\smoke_test.py

Der Smoke-Test überprüft die tatsächliche Protokollkonnektivität, die Tool-Erkennung und einen Aktivitätsaufzeichnungs-/Listungs-Roundtrip. Er verwendet isolierte temporäre Daten anstelle Ihres runtime_data/-Verzeichnisses.

OpenTrek-Integration

Die OpenTrek-Registrierung sollte die STREAMABLE-Auswahl der Benutzeroberfläche und diese URL-Form verwenden:

http://<LAN_IPV4>:8000/mcp

Erfinden Sie keinen transportType-JSON-Wert von Hand. Wählen Sie auf der OpenTrek-MCP-Registrierungsseite STREAMABLE aus, geben Sie die URL ein, speichern Sie und überprüfen Sie, ob alle sechs Tools erkannt werden. Siehe docs/open_trek_integration.md für LAN-IPv4-Erkennung, SSE-Kompatibilität, VPN-Prüfungen und einen sicheren Firewall-Fehlerbehebungsprozess.

Demo-Szenario

Eine End-to-End-Demonstration kann den Unterschied zwischen Wissensabruf und persistentem Handeln zeigen:

1. Der Agent verwendet RAG, um ein fiktives RNN-PPO-Papier oder eine Methodennotiz zu erklären.

2. Der Forscher sagt, dass ein RNN-PPO-Experiment abgeschlossen wurde, das Training aber noch instabil ist.

3. Der Agent ruft record_research_activity mit dem Ergebnis, dem Problem und dem nächsten Schritt auf.

4. Eine fiktive Anforderung des Betreuers, sich auf Generalisierung zu konzentrieren, wird mit record_advisor_instruction aufgezeichnet.

5. Der Agent prüft den Projektstatus und ruft dann generate_research_report für eine Gruppensitzung auf.

Der resultierende Markdown-Bericht basiert auf gespeicherten Aufzeichnungen, nicht auf einer Einzelantwort. Ein kommentiertes Runbook finden Sie in docs/demo_flow.md.

Datenschutz und Git-Sicherheit

Die .gitignore des Repositorys schließt .venv/, pycache/, Python-Bytecode, .env, pytest- und Ruff-Caches, runtime_data/ und Protokolldateien aus. Diese Pfade können lokale Forschungsaktivitäten, Betreuerkontext, Berichte, Anmeldeinformationen oder maschinenspezifische Daten enthalten.

Nur die fiktiven, anonymen Fixtures in examples/sample_data/ sind sicher zu committen. Überprüfen Sie vor jedem Commit oder Push:

git status
git diff --check

Committen Sie niemals echte Betreuernachrichten, echte Papierinhalte, Chat-Transkripte, Schlüssel, VPN-Details oder personenbezogene Informationen.

Roadmap

• Bei Bedarf von JSON-Dateien zu einem dauerhaften Mehrbenutzer-Speicher-Backend wechseln.

• Integrationspunkte für ResearchTwin Memory und ResearchTwin_Core hinzufügen.

• Papier-Intelligenz- und Zitier-Workflows um die bestehende RAG-Schicht hinzufügen.

• Ein geschütztes Dashboard zur Überprüfung des Projektverlaufs und der Berichte hinzufügen.

• Die Wettbewerbs-Demo-Geschichte verbessern, ohne echte Forschungsdaten preiszugeben.

Dokumentation

• Architektur

• MCP-Toolreferenz

• OpenTrek-Integration

• Demo-Ablauf

• Fiktive Beispieldaten