Skip to main content
Glama

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:

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

Lizenz

MIT License

Available Tools

5 tools
list_available_providersA
Read-onlyIdempotent

List all providers from the AI Provider Registry.

Fetches the live registry document and returns provider summaries including id, api_style, free-tier status, and supported capabilities.

Returns: JSON string with registry metadata and provider list.

Inputs: no named parameters. Returns: result

retrieve_recent_contextA
Read-onlyIdempotent

Retrieve the most recent dialog turns for a session.

Returns turns in chronological order (oldest first) so they can be directly used as LLM context.

Args: session_id: Conversation session to query. limit: Maximum number of recent turns to return (default 10).

Returns: JSON string with session id, turn count, and turn list.

Inputs: session_id (required), limit. Returns: result

route_best_modelA
Read-onlyIdempotent

Recommend the best AI provider for a given task type.

Uses the public kbarbel640-del/ai-provider-registry to score providers by capability match, free-tier preference, and known provider strengths.

Args: task_type: Task category — chat, code, reasoning, vision, search, embeddings, image, or tools. constraints: Optional routing constraints: - prefer_free (bool): Prefer free-tier providers. - exclude_providers (list[str]): Provider ids to skip. - api_style (str): Required API style (e.g. openai).

Returns: JSON string with top recommendation and up to four alternatives.

Inputs: task_type (required), constraints. Returns: result

search_memoryA
Read-onlyIdempotent

Search dialog memory within a session by text substring.

Performs a case-insensitive LIKE search over turn content and roles. Suitable for finding earlier mentions of topics, decisions, or entities.

Args: session_id: Conversation session to search. query: Substring to match in content or role. limit: Maximum results to return (default 20).

Returns: JSON string with matching turns, newest first.

Inputs: query (required), session_id (required), limit. Returns: result

store_dialog_turnA

Store a single dialog turn in persistent session memory.

Persists a message (user, assistant, system, or tool) for later retrieval and context assembly. Metadata can hold arbitrary JSON-serializable context such as model name, tool calls, or review state.

Args: session_id: Unique conversation session identifier. role: Speaker role (e.g. user, assistant, system). content: Message text content. metadata: Optional key-value context attached to this turn.

Returns: JSON string with the stored turn record including assigned id.

Inputs: role (required), content (required), session_id (required), metadata. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: list providers, retrieve recent dialog, route best model, search memory, and store dialog turn. No overlapping functionality.

    Naming Consistency5/5

    All tool names follow the verb_noun pattern in snake_case (e.g., list_available_providers, store_dialog_turn), providing a predictable and consistent naming scheme.

    Tool Count4/5

    5 tools is on the lower side but acceptable for a server combining provider routing and dialog memory. Each tool serves a clear role without redundancy.

    Completeness4/5

    Dialog memory covers store, retrieve, and search adequately. Provider coverage has list and route but lacks a single-provider detail lookup, a minor gap.

    Related MCP Connectors

    Related MCP Servers