Trinitas

trinitas-mcp ist ein modularer MCP-Server (Model Context Protocol) für Context, Memory und Multi-Model-Orchestrierung. Er wurde als wiederverwendbare Komponente entwickelt und eignet sich besonders für Szenarien, in denen strukturierte Dialog-Memory und Review-Workflows benötigt werden.

Der Server trennt klar zwischen Vorbereitung & Verwaltung (MCP-Server) und tatsächlicher Ausführung von LLM-Calls (Host-Orchestrator). Dadurch bleibt der MCP-Server keyless und fokussiert.

Basiert auf dem offiziellen Model Context Protocol Python SDK (mcp[cli] / FastMCP).

Features

• Erweiterte Memory-Schicht

  • Keyword-Suche, FTS5-Volltextsuche und optionale Embedding-basierte semantische Suche
  • Metadaten werden bei FTS5 und semantischer Suche berücksichtigt

• Review-Workflow

  • propose_review_strategy — erzeugt eine task-spezifische Review-Strategie
  • execute_review — bereitet strukturierte Review-Ausführung vor
  • Robuster Host-Orchestrator mit Retries, Rate Limiting, Cost Tracking und Parallelisierung

• Persistenz & Abfrage

  • Review-Ergebnisse werden in SQLite gespeichert
  • Abfrage über Tools oder als MCP Resource (review://{review_id} / review://{session_id})

• Mehrere Transportwege

  • stdio (Standard für Claude Desktop / Cursor)
  • HTTP + SSE / Streamable HTTP (für remote Nutzung)

• Produktionsfeatures (HTTP-Modus)

  • Health- und Readiness-Checks (/health, /ready)
  • Graceful Shutdown

Voraussetzungen

• Python >= 3.10
• Netzwerkzugriff für Registry-Tools (lokal gecacht)

Quick Start (stdio)

python3 -m venv .venv && source .venv/bin/activate
pip install -e .
trinitas-mcp

Der Server läuft dann per stdio und kann direkt mit Claude Desktop oder Cursor verwendet werden.

Claude Desktop / Cursor: siehe examples/claude_desktop_config.json.

Vollständiger Review-Workflow

Ein lauffähiges End-to-End-Beispiel:

python examples/full_review_workflow.py

→ examples/full_review_workflow.py

Der Workflow umfasst typischerweise folgende Schritte:

1. Dialog-Turns in Memory speichern
2. Review-Strategie generieren (propose_review_strategy)
3. Review vorbereiten und ausführen (execute_review + Host-Orchestrator)
4. Ergebnisse persistieren
5. Reviews über review:// Resource oder Tools abfragen

Für Live-LLM-Calls: python examples/full_review_workflow.py --live (API-Key über TRINITAS_ORCHESTRATOR_API_KEY).

HTTP Modus (remote)

Es gibt zwei HTTP-Transports — wichtig für die richtige Client-URL:

Transport	Server-Start	MCP-Endpunkt	Typische Clients
streamable-http	--transport streamable-http	http://HOST:8000/mcp	Claude Code (--transport http), moderne MCP-Clients
sse (legacy)	--transport sse	http://HOST:8000/sse (GET) + /messages/ (POST)	Ältere SSE-MCP-Clients

Claude Code (empfohlen)

Server (z. B. auf dem Homeserver, alle Interfaces):

trinitas-mcp --transport streamable-http --host 0.0.0.0 --port 8000

Client (auf dem Rechner mit Claude):

claude mcp remove trinitas-mcp   # falls bereits falsch konfiguriert
claude mcp add trinitas-mcp --transport http http://91.192.10.248:8000/mcp
claude mcp list

Häufiger Fehler: http://…:8000/sse mit --transport http → Server loggt POST /sse 405. Claude sendet POST (Streamable HTTP); Legacy-SSE erwartet GET auf /sse.

Troubleshooting nach erfolgreicher Verbindung:

• listMcpResources zeigt oft (No resources found) — normal. trinitas nutzt Resource-Templates, keine statischen Resources:
  • conversation://{session_id} — Dialog-Kontext (z. B. conversation://demo)
  • review://{review_id} oder review://{session_id} — gespeicherte Reviews
• Tool-Test ohne Netzwerk: Bitte Claude, ping_mcp oder get_session_stats mit session_id: "test" aufzurufen.
• Registry-Tools (list_available_providers) brauchen ausgehendes HTTPS vom Server zur GitHub-Pages-Registry.
• Im Server-Log sollte bei Tool-Calls Processing request of type CallToolRequest erscheinen; fehlt das, bricht der Client ab bevor die Anfrage ankommt.

Legacy SSE

trinitas-mcp --transport sse --host 0.0.0.0 --port 8000

Client-Config: examples/mcp_sse_client.json

Health Checks

curl http://127.0.0.1:8000/health
curl http://127.0.0.1:8000/ready

Alternativ: examples/run_sse_server.sh (legacy SSE)

Architektur

┌─────────────────────┐          ┌──────────────────────────────┐
│   MCP Server        │          │     Host-Orchestrator        │
│                     │          │                              │
│ • Memory (FTS5 +    │          │ • LLM Calls (OpenAI-kompatibel)│
│   Semantic Search)  │          │ • Retries + Rate Limiting     │
│ • Review Tools      │◄────────►│ • Cost Tracking               │
│ • Resources         │          │ • Parallel Execution          │
│ • Prompts           │          │ • Observability               │
└─────────────────────┘          └──────────────────────────────┘

Der MCP-Server kümmert sich um Context, Memory und Struktur. Die eigentlichen LLM-Calls werden vom Host-Orchestrator durchgeführt. Diese Trennung macht den Server einfacher, sicherer und besser testbar.

Konfiguration

Wichtige Umgebungsvariablen:

Variable	Beschreibung
TRINITAS_DATA_DIR	Verzeichnis für SQLite-Datenbank
TRINITAS_SEMANTIC_SEARCH	Semantische Suche aktivieren/deaktivieren (1 / 0)
TRINITAS_EMBEDDING_BACKEND	auto, hashing oder sentence-transformers
TRINITAS_RATE_LIMIT_<PROVIDER>	Rate Limit pro Provider (Requests/Minute)
TRINITAS_MCP_TRANSPORT	stdio oder sse
TRINITAS_HEALTH_PATH / TRINITAS_READY_PATH	Health-Check-Pfade (HTTP-Modus)
TRINITAS_SHUTDOWN_TIMEOUT	Graceful-Shutdown-Timeout in Sekunden

Weitere Konfigurationsmöglichkeiten findest du in REPORT.md.

Entwicklung

Das Projekt verwendet ein commit-basiertes Workflow-Modell. Die verbindlichen Arbeitsregeln stehen in AGENT_INSTRUCTIONS.md.

Weiterführende Dokumentation

• REPORT.md — Ausführlicher Projektbericht mit Architektur, Design-Entscheidungen und aktuellem Stand
• examples/full_review_workflow.py — Komplettes End-to-End-Beispiel
• examples/host_orchestrator.py — Beispiel für den Host-Orchestrator

Links

• Model Context Protocol
• AI Provider Registry
• MCP Python SDK

Lizenz

MIT License