Twining MCP Server

Das Problem

Du verbringst zwei Stunden mit Claude Code, um architektonische Entscheidungen zu treffen. Du entscheidest dich für PostgreSQL statt MongoDB. Du legst dich auf JWT für die Authentifizierung fest. Du markierst eine Race Condition im Zahlungsmodul. Dann endet die Sitzung.

Morgen startest du eine neue Sitzung. Claude hat keine Ahnung, was passiert ist. Die Entscheidungen sind weg. Die Warnungen sind weg. Die Begründung ist weg. Du erklärst alles neu — oder schlimmer noch, Claude widerspricht stillschweigend den Entscheidungen von gestern.

Das wird bei mehreren Agenten noch schlimmer. Agent A entscheidet sich für REST. Agent B wählt gRPC für denselben Dienst. Keiner weiß, dass der andere existiert. Du findest es heraus, wenn der Code nicht kompiliert.

Kontextfenster sind flüchtig. Die Entscheidungen deines Projekts sollten es nicht sein.

Wie Twining das löst

Twining ist ein MCP-Server, der deinen KI-Agenten ein persistentes Projektgedächtnis gibt. Entscheidungen überdauern Kontext-Resets. Neue Sitzungen starten informiert. Die Arbeit mehrerer Agenten bleibt koordiniert.

# Install in 10 seconds
/plugin marketplace add daveangulo/twining-mcp
/plugin install twining@twining-marketplace

Halte fest, was du getan hast — in natürlicher Sprache:

twining_record({
  summary: "Added Redis caching to UserService",
  decisions: ["Chose Redis over Memcached — need persistence across restarts"],
  assumptions: ["Read-heavy workload (10:1 ratio)"],
  scope: "src/services/"
})

Twining analysiert deine Entscheidungen in strukturierte Datensätze — und extrahiert automatisch Begründungen, abgelehnte Alternativen und den Bereich. Ein Tool-Aufruf, keine Formulare.

Starte eine neue Sitzung. Sei sofort auf dem neuesten Stand:

twining_assemble({ task: "optimize the caching layer", scope: "src/services/" })

Twining bewertet jede Entscheidung, Warnung und Erkenntnis nach Relevanz für deine Aufgabe und füllt dann ein Token-Budget in Prioritätsreihenfolge. Du erhältst genau den Kontext, den du benötigst — keine Informationsflut, kein erneutes Erklären.

Frage nach, warum Dinge so sind, wie sie sind:

twining_why({ scope: "src/auth/middleware.ts" })

Gibt die vollständige Entscheidungskette für jede Datei zurück: was wurde entschieden, wann, warum, welche Alternativen wurden abgelehnt und welcher Commit hat es implementiert.

Warum nicht einfach CLAUDE.md verwenden?

CLAUDE.md ist statisch. Du schreibst es einmal und aktualisierst es manuell. Es erfasst Entscheidungen nicht während sie passieren, verfolgt keine Begründungen oder Alternativen, erkennt keine Konflikte zwischen Agenten und kann nicht selektiv Kontext innerhalb eines Token-Budgets zusammenstellen.

Twining ist dynamisch. Jeder twining_decide-Aufruf zeichnet eine strukturierte Entscheidung auf. Jeder twining_post teilt eine Erkenntnis oder Warnung. Jeder twining_assemble bewertet die Relevanz und liefert genau das, was die aktuelle Aufgabe benötigt. Das Verzeichnis .twining/ ist das lebendige institutionelle Gedächtnis deines Projekts.

Warum kein Orchestrator?

Orchestratoren (wie Agenten-Schwärme und hierarchische Koordinatoren) steuern die Arbeit durch Zuweisung von Aufgaben. Twining koordiniert durch Teilen von Status. Der Unterschied ist wichtig:

• Orchestratoren halten den Koordinationskontext in ihrem eigenen Kontextfenster — ein Single Point of Failure, der sich verschlechtert, wenn das Fenster voll wird

• Twinings Blackboard speichert den Koordinationsstatus außerhalb des Fensters eines jeden Agenten und überdauert Kontext-Resets ohne Informationsverlust

Agenten wählen ihre Arbeit selbst aus, indem sie das Blackboard lesen. Kein zentraler Flaschenhals. Kein Relay, das Kontext verliert. Jeder Agent sieht die Entscheidungen und Warnungen jedes anderen Agenten direkt.

Installation

Plugin-Installation (Empfohlen)

# Add the marketplace (one-time)
/plugin marketplace add daveangulo/twining-mcp

# Install the plugin
/plugin install twining@twining-marketplace

Beinhaltet den MCP-Server, Skills, Lifecycle-Hooks und Pre-Commit-Durchsetzung. Zwei Gates: twining_assemble vor der Arbeit, twining_record vor dem Commit — Hooks erzwingen beides automatisch.

Team-Auto-Installation

Commite dies in die .claude/settings.json deines Repos, damit jedes Teammitglied Twining beim Klonen erhält:

{
  "extraKnownMarketplaces": {
    "twining-marketplace": {
      "source": {
        "source": "github",
        "repo": "daveangulo/twining-mcp"
      }
    }
  },
  "enabledPlugins": {
    "twining@twining-marketplace": true
  }
}

Wenn Teammitglieder dem Repository-Ordner vertrauen, installiert Claude Code automatisch den Marketplace und das Plugin.

Nur-MCP-Installation

Für Nicht-Claude-Code-Clients (Cursor, Windsurf, etc.):

claude mcp add twining -- npx -y twining-mcp --project .

Oder füge es zu .mcp.json hinzu:

{
  "mcpServers": {
    "twining": {
      "command": "npx",
      "args": ["-y", "twining-mcp", "--project", "."]
    }
  }
}

MCP-Server-Anweisungen sind automatisch in der Initialisierungsantwort enthalten.

Upgrade von manueller Installation

Wenn du Twining zuvor manuell konfiguriert hast, wechsle zum Plugin:

1. Entferne den manuellen MCP-Server: claude mcp remove twining

2. Installiere das Plugin: /plugin marketplace add daveangulo/twining-mcp dann /plugin install twining@twining-marketplace

3. Aufräumen: Entferne Twining-Hooks aus .claude/settings.json, entferne .claude/agents/twining-aware.md falls vorhanden, entferne Twining-Abschnitte aus CLAUDE.md (Skills erledigen das jetzt)

4. Behalten: .twining/-Verzeichnis (alle Statusdaten bleiben erhalten)

5. Überprüfen: /twining:status

Das Beste herausholen

Das Plugin handhabt Agentenanweisungen automatisch über Skills. Für den Nur-MCP-Installationspfad füge Twining-Anweisungen zur CLAUDE.md deines Projekts hinzu, damit Agenten sie automatisch verwenden — siehe docs/CLAUDE_TEMPLATE.md für eine Vorlage zum Kopieren.

Dashboard

Ein Web-Dashboard startet automatisch unter http://localhost:24282 — durchsuche Entscheidungen, Blackboard-Einträge, Wissensgraphen und Agentenstatus. Konfigurierbar über TWINING_DASHBOARD_PORT.

Was ist enthalten

Kern-Tools (immer verfügbar)

Dies sind die Tools, die Agenten in jeder Sitzung verwenden:

twining_record akzeptiert Entscheidungen in natürlicher Sprache wie "Redis statt Memcached gewählt — benötige Persistenz" und analysiert sie automatisch in strukturierte Datensätze mit Begründung, abgelehnten Alternativen und abgeleitetem Bereich. Es akzeptiert auch Annahmen, Einschränkungen, betroffene Dateien und Abhängigkeitsketten — alles, was der Entscheidungsspeicher für eine hochpräzise Kontextzusammenstellung benötigt.

Erweiterte Tools (verfügbar mit full_surface: true)

Für fortgeschrittene Workflows — tiefgreifendes Entscheidungsmanagement, Graphen-Exploration, Multi-Agenten-Koordination:

Aktivieren mit .twining/config.yml:

tools:
  full_surface: true

Wie es funktioniert

Der gesamte Status lebt in .twining/ als einfache Dateien — JSONL für das Blackboard, JSON für Entscheidungen, Graphen, Agenten und Übergaben. Alles ist jq-abfragbar, grep-bar und git-diffbar. Keine Datenbank. Keine Cloud. Keine Konten.

Architekturschichten:

• Speicher — Dateibasierte Speicher mit Sperrung für gleichzeitigen Zugriff

• Engine — Entscheidungsverfolgung, Blackboard, Graphentraversierung, Kontextzusammenstellung mit Token-Budgetierung, Agentenkoordination

• Embeddings — Lokales all-MiniLM-L6-v2 via @huggingface/transformers, lazy-geladen, mit Keyword-Fallback. Der Server startet nie aufgrund von Embedding-Problemen nicht.

• Dashboard — Schreibgeschützte Web-UI mit cytoscape.js Graphenvisualisierung und vis-timeline

• Tools — MCP-Tool-Definitionen, validiert mit Zod, 1:1-Mapping zur Tool-Oberfläche

Siehe TWINING-DESIGN-SPEC.md für die vollständige Spezifikation.

FAQ

Verlangsamt Twining Claude Code? Nein. Es ist ein lokaler MCP-Server — Tool-Aufrufe sind lokale Dateilese- und Schreibvorgänge. Die semantische Suche wird bei der ersten Verwendung lazy geladen.

Kann ich es mit Cursor, Windsurf oder anderen MCP-Clients verwenden? Ja. Twining ist ein Standard-MCP-Server. Jeder MCP-Host kann sich damit verbinden.

Wo gehen meine Daten hin? Der gesamte Koordinationsstatus ist lokal in .twining/. Tool-Aufruf-Metriken werden lokal in .twining/metrics.jsonl gespeichert (gitignored). Optionale anonyme Telemetrie kann aktiviert werden — siehe Analytics unten.

Ist Twining ein Agenten-Orchestrator? Nein. Es ist eine Koordinations-Statusschicht. Es erfasst, was Agenten entschieden haben und warum, und stellt dieses Wissen zukünftigen Agenten zur Verfügung. Verwende es zusammen mit Orchestratoren, Agententeams oder eigenständigen Sitzungen.

Analytics

Twining enthält ein dreischichtiges Analysesystem, das dir hilft, den Wert zu verstehen, den es bietet.

Insights-Dashboard-Tab

Das Web-Dashboard enthält einen Insights-Tab, der Folgendes zeigt:

• Wert-Metriken — Rate der verhinderten blinden Entscheidungen, Warnungsbestätigung, Testabdeckung über tested_by-Graphenbeziehungen, Commit-Rückverfolgbarkeit, Entscheidungslebenszyklus, Wissensgraphen-Statistiken und Agentenkoordinationsmetriken

• Tool-Nutzung — Aufrufzahlen, Fehlerraten, durchschnittliche/P95-Latenz pro Tool

• Fehleraufschlüsselung — Fehler gruppiert nach Tool und Fehlercode

Alle Wert-Metriken werden aus vorhandenen .twining/-Daten berechnet — keine neue Datenerfassung erforderlich.

Tool-Aufruf-Metriken

Jeder MCP-Tool-Aufruf wird automatisch mit Timing- und Erfolgs-/Fehlerverfolgung instrumentiert. Metriken werden lokal in .twining/metrics.jsonl gespeichert (gitignored — operative Daten, keine architektonischen).

Um die lokale Metrikerfassung zu deaktivieren, setze in .twining/config.yml:

analytics:
  metrics:
    enabled: false

Opt-in-Telemetrie

Anonyme aggregierte Nutzungsdaten können optional an PostHog gesendet werden, um Twining zu verbessern. Standardmäßig deaktiviert. Um sie zu aktivieren, füge zu .twining/config.yml hinzu:

analytics:
  telemetry:
    enabled: true

Das war's — der PostHog-Projektschlüssel ist in den Quellcode eingebaut. Wenn du deine eigene PostHog-Instanz betreibst, kannst du sie mit posthog_api_key und posthog_host überschreiben.

Was wird gesendet: Tool-Namen, Aufrufdauer, Erfolgs-/Fehler-Booleans, Serverversion, Betriebssystem, Architektur.

Was wird niemals gesendet: Dateipfade, Entscheidungsinhalte, Agentennamen, Fehlermeldungen, Tool-Argumente, Umgebungsvariablen.

Datenschutzvorkehrungen:

• DO_NOT_TRACK=1 Umgebungsvariable überschreibt immer die Konfiguration

• CI=true deaktiviert automatisch die Telemetrie

• Identität ist ein SHA-256-Hash aus Hostname + Projekt-Root (niemals Rohpfade)

• Netzwerkfehler sind lautlos — keine Wiederholungsversuche

• posthog-node ist eine optionale Abhängigkeit — sanfter No-Op, falls nicht installiert

Entwicklung

npm install       # Install dependencies
npm run build     # Build
npm test          # Run tests (800+ tests)
npm run test:watch

Erfordert Node.js >= 18.

CI/CD

Zwei GitHub Actions-Workflows automatisieren die Build-Verifizierung und Veröffentlichung:

CI (.github/workflows/ci.yml) — läuft bei jedem PR und Push auf main:

• Baut und testet über Node 18, 20 und 22

• Bricht laufende Durchläufe ab, wenn ein neuer Push auf demselben Branch eintrifft

Publish (.github/workflows/publish.yml) — läuft bei v*-Tag-Push:

• Baut mit eingebettetem POSTHOG_API_KEY für veröffentlichte Pakete

• Führt die vollständige Testsuite als Defense-in-Depth aus

• Veröffentlicht auf npm mit