agent-config-sync v0.2.0A

Immutable. This exact content is served forever at /api/v1/blob/0e05c83b60d42d57.

---
name: agent-config-sync
version: 0.2.0
type: protocol
author: Lukas Geiger + Claude
created: 2026-06-20
updated: 2026-06-20
description: >
  Synchronisiert MCP-Server UND Skills uebergreifend ueber ALLE bekannten Agent-Apps und CLIs
  (Claude Code, Claude Desktop, Codex CLI, Antigravity/Gemini, Kimi Code, Cursor, Cline,
  Windsurf, GitHub Copilot, ...) auf einem oder mehreren Systemen. Aktiviert sich, wenn ein
  MCP-Server oder Skill in mehreren Agent-Tools verfuegbar gemacht werden soll, der User fragt
  "sync mcp/skills ueber alle agents", "warum hat Tool X den Server/Skill nicht", "MCP/Skills
  ueberall verteilen", "config-sync zwischen agents", oder ein neues Agent-Tool an den
  gemeinsamen Stand angeschlossen werden soll. Liest eine Registry (welche Tools syncen wie),
  eine Config (Anbieter-Standardspezifikationen: wo + welches Format) und einen Lauf-Cache
  (aufgeloeste reale Pfade), wendet Sync-Regeln an (pull vs. verteilen) und verifiziert.
  Enthaelt einen Lernmechanismus: unbekannte/veraltete Config-Orte werden per Systemsuche,
  WebSearch und Context7 nachgeschlagen und in der Config aktualisiert. Loest den aelteren,
  auf Claude Code <-> Claude Desktop beschraenkten Skill mcp-config-sync ab (umschliesst ihn
  als Spezialfall). Claude-MCP-Profile werden via ellmos-controlcenter-mcp-Backend verwaltet
  (resolve_profile / switch_profile), nicht durch eigene Logik.

standalone: true
anthropic_compatible: true
bach_compatible: true
bach_origin: false

category: infrastructure
tags: [mcp, skills, sync, multi-agent, claude-code, claude-desktop, codex, gemini, antigravity, kimi, cursor, cline, windsurf, copilot, config, registry, windows, macos, controlcenter]
language: de
status: active

aliases: [mcp-skill-sync, multi-agent-sync, tool-config-sync, agent-sync]

dependencies:
  tools: [python]
  services: [ellmos-controlcenter-mcp]
  protocols: []
  python: []

provenance:
  origin: "custom"
  origin_path: "skills/infrastructure/agent-config-sync/"
  origin_version: "0.2.0"
  last_sync_from_origin: null
  last_sync_to_origin: null
  local_changes_since_sync: false
---

<img src="banner.png" width="100%" alt="agent-config-sync banner">

# Agent Config Sync

Ein **uebergreifendes Sync-Protokoll** fuer MCP-Server **und** Skills ueber alle bekannten
Agent-Apps und CLIs. Statt fuer jedes App-Paar ein eigenes Skript zu pflegen, beschreibt
dieser Skill *deklarativ*, **welche** Tools auf einem System leben, **was** sie teilen sollen
(MCP / Skills / beides) und **wie** (pull, push, bidirektional/verteilen). Ein generischer
Ablauf liest diese Deklaration und fuehrt den Sync aus.

**Claude-MCP-Profile-Backend:** Fuer `claude-code` und `claude-desktop` wird
**`ellmos-controlcenter-mcp`** als Backend genutzt (MCP-Tool `resolve_profile`/`switch_profile`).
`sync.py` enthaelt keine eigene Claude-Profil-Logik; der Agent ruft die ControlCenter-MCP-Tools
zur Laufzeit auf. Direkt lesbare JSON-Profildateien (z.B. `shared.json`) werden weiterhin
direkt gelesen.

**Loest `mcp-config-sync` ab:** Der aeltere Skill `mcp-config-sync` ist als
Registry-Beziehung `claude-pair` (pull, scope mcp) in diesem Skill umschlossen.
Sobald `agent-config-sync` produktiv eingesetzt wird, sollte `mcp-config-sync` auf
`status: deprecated` gesetzt werden.

## Verhaeltnis zu bestehenden Skills (keine Duplikation)

| Skill | Zustaendigkeit | Verhaeltnis |
|---|---|---|
| **agent-config-sync** (dieser) | Sync von **MCP-Servern + Skills** ueber **alle** Agent-Tools, regelbasiert | Achse 1 (Inter-Agent) + Inter-IDE-Verteilung |
| `mcp-config-sync` | nur MCP, nur Claude Code <-> Claude Desktop, 1 Skript | **Spezialfall**, der hier umschlossen wird (siehe `references/legacy-mcp-config-sync.md`); bleibt vorerst als Legacy bestehen |
| `agents-bridge` | leitet fremde Agents per Redirect-Datei auf die EINE Regel-Quelle `CLAUDE.md` | **Regel**-Sync (Wissen/Workflows), NICHT Tool-Config. Komplementaer. |
| `system-onboarding` | Erstaufsetzen eines neuen Systems (Reihenfolge der Installation) | liefert die Config-Ort-Tabellen, auf denen dieser Skill aufbaut |

**Was dieser Skill NICHT ist:** kein Regel-/CLAUDE.md-Sync (das macht `agents-bridge`), kein
System-Erstsetup (das macht `system-onboarding`), kein Plugin-/Extension-Marktplatz-Abgleich
(die Toolkits sind komplementaer, siehe `mcp-config-sync/references/plugin-extension-parity.md`).

## Die drei Datenebenen

Der Skill trennt bewusst **Was-soll-passieren** von **Wie-sehen-die-Anbieter-aus** von
**Wo-liegt-es-real**:

```
  REGISTRY  (lokal/privat)        was syncen welche Tools wie? (Beziehungen, Modus, Scope)
      |  liest
      v
  CONFIG    (publizierbar)        Anbieter-Standardspezifikationen: pro Tool wo + Format
      |  loest Pfade auf nach
      v
  CACHE     (lokal/privat)        aufgeloeste reale Verzeichnisse/Dateien (Lauf-Cache)
```

| Datei | Inhalt | Privacy |
|---|---|---|
| `REGISTRY.md` + `registry.example.json` | welche Tools vorhanden, Sync-Paare/-Gruppen, Modus, Scope | Template publizierbar; **reale `registry.json` lokal/gitignored** |
| `CONFIG.md` + `config.json` | je Anbieter: Config-Ort (Platzhalter `<HOME>`), Format, Merge-Key, Eigenheiten, Quellen-Stand | publizierbar (neutral) |
| `CACHE.md` + `cache.json` | aufgeloeste reale Pfade auf DIESEM System | **lokal/gitignored** |

## Ablauf (Protokoll)

### 0. Lock + Vorsicht
- Bei aktiver `LOCK*.txt` im Zielbereich: nichts schreiben (LOCK-System beachten).
- Default ist **read-only**: `--status`/`--plan` veraendern nichts. `--apply` nur mit
  `--yes` und nach Anzeige des Plans.

### 1. Registry lesen
- `registry.json` (Fallback: `registry.example.json`) laden.
- Liefert: vorhandene Tools auf diesem `host`, die Sync-Beziehungen (Paare/Gruppen),
  je Beziehung Modus (`pull` | `push` | `bidirectional`) und Scope (`mcp` | `skills` | `both`).

### 2. Config lesen (Anbieter-Specs)
- `config.json` laden: je Anbieter Config-Ort (mit `<HOME>`-Platzhalter), Format
  (`json` | `toml` | `dir`), `mcp_key` (z.B. `mcpServers`), `skills_dir`, Eigenheiten.

### 3. Cache aufloesen
- Platzhalter (`<HOME>`, `<APPDATA>`, ...) gegen das reale System aufloesen → `cache.json`.
- Pruefen, ob die Datei/der Ordner existiert. **Fehlt sie → Lernmechanismus (Schritt 6).**

### 4. Plan bilden (pull vs. verteilen)
- Pro Beziehung den **Quellzustand** lesen und mit dem **Zielzustand** vergleichen.
- **pull**: ein designierter Master/Hub wird gelesen, Ziele bekommen dessen Stand.
- **push/verteilen**: ein Quell-Tool verteilt an mehrere Ziele.
- **bidirectional**: Vereinigung; bei Konflikt (gleicher Key, anderer Wert) → eskalieren,
  nicht raten.
- Fuer **mcp**: nur den `mcp_key`-Block ersetzen, restliche Config-Felder erhalten;
  Format-Konvertierung JSON↔TOML, wo noetig (Codex = TOML).
- Fuer **skills**: Verzeichnis-Abgleich (`skills_dir`); App-spezifische Eigenheiten
  beachten (z.B. Claude Desktop liest `~/.claude/skills/` NICHT direkt → Bridge-Skill,
  siehe `mcp-config-sync/references/skills-sync-options.md`).
- Ausgabe: menschenlesbarer **Plan** (welche Datei, welche Keys, add/update/remove).

### 5. Anwenden + Verifizieren (nur `--apply --yes`)
- Vor jedem Schreiben **Backup mit Zeitstempel**.
- Schreiben (Format-erhaltend, nur Ziel-Block).
- **Verifikation:** Ziel erneut lesen, Soll/Ist vergleichen; Diff ausgeben.
- Hinweis: Apps ggf. neu starten (Claude Desktop komplett beenden), damit Aenderungen greifen.

### 6. Lernmechanismus (Selbstheilung der Config)
Wird ausgeloest, wenn ein Config-Ort fehlt, ein Anbieter unbekannt ist oder ein Format
nicht passt:

1. **Config-Ort veraltet/nicht gefunden** → **Systemsuche** nach den bekannten Dateinamen:
   - MCP-Server-Suche: ellmos-FileCommander (`fc_search_files`/`fc_search`) oder `Glob`
     ueber die Home-/AppData-Wurzeln nach `*config*.json`, `config.toml`,
     `claude_desktop_config.json`, `settings.json`, `mcp.json`.
   - Gefundenen realen Pfad in `cache.json` eintragen; wenn er dauerhaft vom Config-Standard
     abweicht, `config.json` (mit Stand-Hinweis) aktualisieren.
2. **Unbekannter Anbieter** (Tool, das in `config.json` fehlt) → **WebSearch** nach
   "<tool> MCP config file location" / "<tool> custom rules file", Ergebnis verifizieren,
   neuen Anbieter-Eintrag in `config.json` anlegen (mit `sources`-Feld + Datum).
3. **Format-/Schema-Unsicherheit** → aktuelle Spezifikation per **WebSearch** UND
   **Context7** (`resolve-library-id` → `query-docs`, z.B. "Model Context Protocol",
   "claude code mcp config", "codex config.toml") nachschlagen; `config.json` korrigieren.

> Jede automatische Config-Aenderung dokumentiert sich selbst: Feld `sources` + `updated`
> im betroffenen Anbieter-Eintrag setzen.

## Aufruf

```bash
# Status: Pfade aufloesen, Existenz pruefen, cache.json aktualisieren (read-only fuer Agent-Configs)
PYTHONIOENCODING=utf-8 python scripts/sync.py --status

# Plan: was wuerde ein Sync tun? (read-only, kein Schreiben)
PYTHONIOENCODING=utf-8 python scripts/sync.py --plan

# Anwenden: block-replace pro Relation, Backup + Verifikation (bestaetigung erforderlich)
PYTHONIOENCODING=utf-8 python scripts/sync.py --apply --yes

# Tests ausfuehren (nutzen nur Fixtures -- keine echten Configs)
PYTHONIOENCODING=utf-8 python -m pytest skills/infrastructure/agent-config-sync/tests/ -v
```

### ControlCenter-Backend (Claude-Provider)

Fuer `claude-code`- und `claude-desktop`-Targets wird kein direkter Config-Write gemacht.
Stattdessen den **`ellmos-controlcenter-mcp`**-Server nutzen:

```
resolve_profile()   -- aktives Profil und Serverinhalt lesen
switch_profile()    -- Profil wechseln / MCP-Config-Datei neu erzeugen
```

Der `--plan`-Output zeigt explizit, welche ControlCenter-Aktion noetig ist.

## Privacy / Konventionen

- **Publizierbar (neutral):** `SKILL.md`, `CONFIG.md`, `config.json`, `REGISTRY.md`,
  `registry.example.json`, `CACHE.md`, `cache.example.json`, `scripts/`. Nur Platzhalter
  (`<HOME>`, `~`, `<HOST>`, `<USER>`), KEINE echten Personen-Pfade/Hostnames.
- **Lokal/privat (gitignored):** `registry.json`, `cache.json` (die mit echten Pfaden
  gefuellten Instanzen fuer DIESES System). Muster in der `.SKILLS/.gitignore` ergaenzt.
- **Quelle = `skills/...`.** NICHT nach `~/.claude/skills/` deployen — das entscheidet der
  User spaeter via `skill_sync.py`. Nicht committen/pushen ohne Freigabe.

## Aufbau dieses Skills

```
agent-config-sync/
├── SKILL.md                  (diese Datei — das Protokoll, DE)
├── SKILL.en.md               (englische Version)
├── REGISTRY.md               Doku: was syncen welche Tools wie
├── registry.example.json     Template (publizierbar)
├── registry.json             reale Instanz fuer dieses System (LOKAL, gitignored)
├── CONFIG.md                 Doku: Anbieter-Standardspezifikationen
├── config.json               je Anbieter: Ort + Format + Eigenheiten (publizierbar)
├── CACHE.md                  Doku: Lauf-Cache aufgeloester Pfade
├── cache.example.json        Template (publizierbar)
├── cache.json                aufgeloeste reale Pfade (LOKAL, gitignored)
├── scripts/
│   └── sync.py               Funktionale Implementierung (--status/--plan/--apply)
├── tests/
│   └── test_sync.py          Pytest-Tests (nur Fixtures, keine echten Config-Writes)
└── references/
    └── legacy-mcp-config-sync.md   wie der alte MCP-Skill hier aufgeht
```

## Changelog

### 0.2.0 (2026-06-20)
- `--apply` implementiert: format-erhaltendes JSON-block-replace, TOML-Abschnitt-replace
  (Codex), Backup + Verifikation je Schritt, Skills-Verzeichnis-Abgleich.
- Test-Suite (`tests/test_sync.py`, 15 Tests, nur Fixtures -- keine echten Config-Writes).
- ControlCenter-Backend-Anbindung: Claude-Provider-Writes delegieren an
  `ellmos-controlcenter-mcp` (resolve_profile/switch_profile); keine eigene Profil-Logik.
- Test-Isolation via `--root`-Flag und `AGENT_CONFIG_SYNC_TEST_ROOT`-Env-Guard.
- Nutzerneutral: Platzhalter in SKILL.md/CONFIG/Templates; `registry.json`/`cache.json` gitignored.
- Versionierungs-Konformitaet: `last_sync_from_origin: null` (originaerer custom-Skill),
  `status: active`, in `registry/components.json` aufgenommen.
- Supersede-Relation zu `mcp-config-sync` in `references/legacy-mcp-config-sync.md` und
  SKILL.md-Kopftext modelliert.
- i18n: SKILL.md (DE, primaer) + SKILL.en.md (EN, vollstaendig).

### 0.1.0 (2026-06-20)
- Initiales Scaffold: Protokoll-SKILL.md, Registry/Config/Cache-Modell (Template + Doku),
  Lernmechanismus (Systemsuche/WebSearch/Context7), `scripts/sync.py`-Stub
  (`--status`/`--plan`). Umschliesst `mcp-config-sync` als Spezialfall.