trinitas-mcp
trinitas-mcp is a modular MCP server for dialog memory management, context retrieval, AI model routing, and orchestration.
Store Dialog Turns (
store_dialog_turn): Persist individual conversation messages (user, assistant, system, or tool roles) into a session-based memory store, with optional metadata such as model name, tool calls, or review state.Retrieve Recent Context (
retrieve_recent_context): Fetch the most recent dialog turns for a given session in chronological order, ready for use as LLM context (configurable limit, default 10 turns).Search Session Memory (
search_memory): Perform case-insensitive substring searches across stored dialog turns within a session to find earlier mentions of topics, decisions, or entities (returns newest-first, default limit 20).Route Best AI Model (
route_best_model): Recommend the best AI provider for a specific task type (e.g.chat,code,reasoning,vision,search,embeddings,image,tools), with optional constraints like preferring free-tier providers, excluding certain providers, or requiring a specific API style. Returns a top recommendation plus up to four alternatives.List Available Providers (
list_available_providers): Retrieve all AI providers from the live AI Provider Registry, including their IDs, API styles, free-tier status, and supported capabilities.Review Workflows: Propose and execute structured review strategies, persist review outcomes in SQLite, and retrieve them via dedicated tools or
review://resources.Flexible Deployment: Supports stdio for local integration (e.g., Claude Desktop/Cursor) or HTTP/SSE for remote access, with health/readiness checks and graceful shutdown in HTTP mode.
Retrieves the AI Provider Registry hosted on GitHub Pages to recommend and route AI providers based on task types.
Uses SQLite for local memory storage, allowing persistent dialog turn recording and retrieval per session.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@trinitas-mcp Search memory for 'project plan'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-Strategieexecute_review— bereitet strukturierte Review-Ausführung vorRobuster 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-mcpDer 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:
Dialog-Turns in Memory speichern
Review-Strategie generieren (
propose_review_strategy)Review vorbereiten und ausführen (
execute_review+ Host-Orchestrator)Ergebnisse persistieren
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 |
|
| Claude Code ( |
sse (legacy) |
|
| Ä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 8000Client (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 listHä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:
listMcpResourceszeigt oft (No resources found) — normal. trinitas nutzt Resource-Templates, keine statischen Resources:conversation://{session_id}— Dialog-Kontext (z. B.conversation://demo)review://{review_id}oderreview://{session_id}— gespeicherte Reviews
Tool-Test ohne Netzwerk: Bitte Claude,
ping_mcpoderget_session_statsmitsession_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 CallToolRequesterscheinen; fehlt das, bricht der Client ab bevor die Anfrage ankommt.
Legacy SSE
trinitas-mcp --transport sse --host 0.0.0.0 --port 8000Client-Config: examples/mcp_sse_client.json
Health Checks
curl http://127.0.0.1:8000/health
curl http://127.0.0.1:8000/readyAlternativ: 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 |
| Verzeichnis für SQLite-Datenbank |
| Semantische Suche aktivieren/deaktivieren ( |
|
|
| Rate Limit pro Provider (Requests/Minute) |
|
|
| Health-Check-Pfade (HTTP-Modus) |
| 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 Standexamples/full_review_workflow.py— Komplettes End-to-End-Beispielexamples/host_orchestrator.py— Beispiel für den Host-Orchestrator
Links
Lizenz
MIT License
Available Tools
5 toolslist_available_providersARead-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_contextARead-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_modelARead-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_memoryARead-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
Scored across 5 tools
Each tool has a clearly distinct purpose: list providers, retrieve recent dialog, route best model, search memory, and store dialog turn. No overlapping functionality.
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.
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.
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
Persistent memory for AI agents: save, search and connect context across tools and sessions.
Universal memory for AI agents and tools. Save, organize and search context anywhere.
Persistent memory layer for AI clients: store, recall, and correct context across tools.
Cross-tool persistent memory and context for AI assistants over MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceFacilitates enhanced interaction with large language models (LLMs) by providing intelligent context management, tool integration, and multi-provider AI model coordination for efficient AI-driven workflows.MIT
- FlicenseNot gradedqualityDmaintenanceProvides AI agents with persistent, searchable memory that survives across conversations using semantic search, temporal versioning, and smart organization. Enables long-term context retention and cross-session continuity for AI assistants.14-
- FlicenseNot gradedqualityDmaintenanceEnables AI systems to remember interactions, understand document context through semantic search, and intelligently route requests with persistent memory and quality-scored content synthesis.-
- FlicenseBqualityDmaintenanceEnables persistent memory for AI systems by providing tools for episodic, semantic, and procedural data storage through a vector-and-graph-enhanced database. It allows models to maintain long-term continuity using similarity search, thematic clustering, and identity tracking.241-