trinitas-mcp

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

Related MCP server: BuildAutomata Memory MCP Server

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:

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:

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