Coordination MCP

Coordination MCP ist ein leichtgewichtiger Dienst für geteilten Arbeitszustand, der sich an mehrere KI-Teilnehmer richtet. Er stellt über MCP persistente Ticket-Objekte, unveränderliche Update-Objekte und textbasierte Artifact-Objekte bereit, sodass ChatGPT, lokale KI und Coding-Agenten in demselben Scope Arbeitskontext teilen, inkrementell synchronisieren und wiederherstellen können.

Was V0.1 kann

• Ticket: speichert den aktuellen Zustand einer laufenden Arbeit; title, status, artifact_ids und meta sind aktualisierbar.

• Update: speichert bereits eingetretene Fakten, Erkenntnisse, Entscheidungen oder Ergebnisse; die seq wird pro Scope monoton steigend zugewiesen.

• Artifact: speichert unveränderliche geteilte Textinhalte, z. B. Markdown, Logs oder lange Dokumente.

• Alle Objekte erhalten vom Server eine global eindeutige ID.

• Referenzen auf Ticket und Artifact müssen zum selben Scope gehören.

V0.1 enthält keine Unterstützung für Authentifizierung, Workflow-Engine, Queue-Acknowledgment, Relationship-Graph, Wake-up-Benachrichtigung und Binary-Artefakte.

Empfohlene Verwendungsmuster

• Ticket repräsentiert den aktuellen, veränderbaren Zustand eines laufenden Arbeitseintrags; es ist kein Ereignisprotokoll.

• Update repräsentiert ein unveränderliches Ereignis, das bereits in der Arbeitszeitleiste stattgefunden hat – etwa Request, Finding, Decision oder Result.

• Artifact repräsentiert unveränderliche, lange Textinhalte; umfangreiche Reviews, Spezifikationen oder Logs sollten in Artifact gelegt werden, nicht in Update, und über artifact_ids verknüpft werden.

• Für created_by sollte ein über Läufe und Agenten hinweg stabiles Participant-Label verwendet werden, z. B. chatgpt, pi-local-agent, nicht jedes Mal zufällig oder wechselnde Namen – so bleibt die Zeitleiste klar zuordenbar. Das Feld dient der Provenienz, nicht der Authentifizierung.

Ein typischer Review-Ablauf ist: lokale KI fordert über ein Update ein Review an → ChatGPT speichert das vollständige Review als Artifact und liefert über ein Update eine Zusammenfassung sowie die artifact_ids zurück → lokale KI behebt den Code und fügt ein Result-Update hinzu → ChatGPT beginnt das Review erneut.

Schnellstart

Anforderungen: Node.js 24+.

cd /path/to/coordination-mcp
npm install
npm run build
node dist/main.js

Der Dienst lauscht standardmäßig auf:

http://127.0.0.1:3000/mcp

Alternativ kann direkt die Entwicklungsumgebung ausgeführt werden:

npm run dev

Der Dienst bindet nur an 127.0.0.1. Falls remote-ChatGPT-Instanzen darauf zugreifen sollen, sollte der ›MCP-Endpoint‹ über einen sicheren Tunnel exponiert werden; den Node.js-Dienst nicht direkt über das Internet auszusetzen. V0.1 hat keine Authentifizierung.

Konfiguration

Die Konfigurationspriorität sieht von niedrigster zu höchster aus:

代码默认值 < config/default.yml < ~/.coordination-mcp/config.yml < --profile < 环境变量

Benutzerkonfiguration

Benutzerkonfiguration anlegen:

mkdir -p ~/.coordination-mcp
$EDITOR ~/.coordination-mcp/config.yml

Beispiel:

port: 43721
allowedHosts:
  - 127.0.0.1
  - localhost
# dataDirectory: /absolute/path/to/coordination-data

~/.coordination-mcp/config.yml ist optional und wird nicht automatisch vom Dienst erzeugt. Ist dataDirectory nicht gesetzt, wird standardmäßig verwendet:

~/.coordination-mcp/data

Es wird empfohlen, ein benutzerdefiniertes dataDirectory als absoluten Pfad anzugeben. Relative Pfade werden relativ zum aktuellen Arbeitsverzeichnis zum Prozessstart aufgelöst.

Profil

Profilpfade werden relativ zum aktuellen Arbeitsverzeichnis aufgelöst; sobald ein Profil angegeben ist, muss die Datei vorhanden sein:

node dist/main.js --profile config/local.yml
node dist/main.js --profile=/absolute/path/to/local.yml

Ein Profil überschreibt nur die Felder, die es deklariert; nicht deklarierte Felder erben weiterhin die vorhergehende Konfiguration.

Umgebungsvariablen

PORT=43721 \
COORDINATION_DATA_DIR=/absolute/path/to/data \
COORDINATION_ALLOWED_HOSTS=127.0.0.1,localhost \
node dist/main.js

Unterstützte Umgebungsvariablen:

Die Konfigurationsdatei wird nur beim Start des Dienstes gelesen; nach Änderungen muss main.js neu gestartet werden.

MCP Tools

Der Dienst stellt über POST /mcp die folgenden 8 Tools bereit:

MCP-Initialisierungsbeispiel

curl -N \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Content-Type: application/json' \
  -H 'mcp-protocol-version: 2025-03-26' \
  -X POST http://127.0.0.1:3000/mcp \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {
        "name": "manual-client",
        "version": "0.1.0"
      }
    }
  }'

Beispiel zum Erstellen eines Tickets

Beispielwerte für tools/call:

{
  "name": "create_ticket",
  "arguments": {
    "scope": "coordination-mcp",
    "title": "Review the MCP integration",
    "created_by": "local-ai",
    "status": "open",
    "meta": {
      "priority": "high"
    }
  }
}

Datenablage

Das Standard-Datenverzeichnis wird erst bei Bedarf erstellt; nur der Dienststart oder reine Leseoperationen legen kein Datenverzeichnis an. Beim ersten Schreiben eines Ticket, Update oder Artifact wird eine Struktur wie folgt erzeugt:

~/.coordination-mcp/
├── config.yml                 # 可选用户配置
└── data/
    └── scopes/
        └── <base64url-scope>/
            ├── tickets/
            │   └── T-*.json
            ├── updates.jsonl
            └── artifacts/
                └── A-*.json

Entwicklung und Validierung

npm test
npm run check
npm run build

Projektdokumentation

• Domain context

• Accepted ADRs

• Archived V0.1 protocol

• Archived implementation architecture

Übersetzung notieren:

• Die Liste im Abschnitt „Empfohlene Verwendungsmuster“ nennt „Request, Review, Decision oder Result“ – ich habe für allgemeinere Begriffe die englischen Fachwörter beibehalten, da sie in der Quelle stehen.

• GXP11 und GXP12 sind als Platzhalter erhalten.

• Die Markdown-Tabellen und Codespans sind unverändert beibehalten.