# 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](https://modelcontextprotocol.io) 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)

```bash
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`](examples/claude_desktop_config.json).

## Vollständiger Review-Workflow

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

```bash
python examples/full_review_workflow.py
```

→ [`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):

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

**Client** (auf dem Rechner mit Claude):

```bash
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

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

Client-Config: [`examples/mcp_sse_client.json`](examples/mcp_sse_client.json)

### Health Checks

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

Alternativ: [`examples/run_sse_server.sh`](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`](REPORT.md).

## Entwicklung

Das Projekt verwendet ein commit-basiertes Workflow-Modell. Die verbindlichen Arbeitsregeln stehen in [`AGENT_INSTRUCTIONS.md`](AGENT_INSTRUCTIONS.md).

## Weiterführende Dokumentation

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

## Links

- [Model Context Protocol](https://modelcontextprotocol.io)
- [AI Provider Registry](https://github.com/kbarbel640-del/ai-provider-registry)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)

## Lizenz

MIT License