Auto Knowledge Sync MCP

Ein lokaler MCP-Server, der technisches Wissen aus LLM-Entwicklungssitzungen zu vollständigen Dokumenten aufbereitet und es als Wissensquelle für Einzelpersonen oder Teams ansammelt. Der MCP wird als Docker-Container auf dem Computer des Benutzers ausgeführt, und die einzige maßgebliche Quelle (SSOT) des Wissens wird in einem vom Benutzer angegebenen privaten GitHub-Repository aufbewahrt.

Warum wird das benötigt?

Erklärungen, Entscheidungen und Hinweise, die Sie während der Entwicklung mit einem LLM austauschen, sind nützlich, gehen aber nach dem Ende der Sitzung schnell verloren. Dieses Projekt verbindet den folgenden Ablauf mit der üblichen MCP-Nutzung.

1. Der LLM schlägt technisches Wissen vor, das in der Sitzung für die Wiederverwendung wertvoll ist.

2. Der MCP prüft die Vollständigkeit von Dokumenten, persönliche und interne vertrauliche Informationen sowie das Vorhandensein von Originalcode.

3. Nur genehmigte Vorschläge werden in das GitHub-Repository committet.

4. Das Wissen wird anschließend durch Suche, Verifizierung, Challenge und Reorganisation kontinuierlich erneuert.

Die gespeicherten Dokumente sind keine bloßen Stichwortlisten, sondern eigenständige Wissenseinträge, die Konzepte, Funktionsweise, technische Bedeutung, das zu lösende Problem sowie Anwendungsbedingungen und Grenzen beschreiben. Wenn Codebeispiele benötigt werden, sind nur neue Beispiele zulässig – keine Kopien oder Abwandlungen vorhandener Arbeitscode.

Related MCP server: MCP Enhanced Data Retrieval System

Hauptmerkmale

• Remote-SSOT: Wissen und Änderungshistorie werden als GitHub-Commits festgehalten. Lokal werden nur ein regenerierbarer Suchindex und temporäre Daten gespeichert.

• Blockierung sensibler Informationen: Es werden integrierte Prüfungen auf Geheimnisse und personenbezogene Daten (PII) sowie optionale organisationsspezifische Ablehnungsregeln angewendet; es gilt eine Fail-Closed-Richtlinie, die bei fehlgeschlagener Prüfung keine Speicherung vornimmt.

• Explizite Genehmigung: Der Standardgenehmigungsmodus ist always. Er kann nur bei Bedarf auf on_risk oder never gesetzt werden; Sicherheits-Hard-Gates und risikoreiche Änderungen werden stets überprüft.

• Wissenslebenszyklus: Unterstützt neben der Suche auch das Einreichen von Gegenbeispielen, die Prüfung auf veraltete und doppelte Einträge, die Pflege von Beziehungen sowie Vorschläge für Merge, Split, Reclassify und Deprecate.

• Serverloser Betrieb: Es gibt keinen dauerhaft laufenden zentralen Server und keine Betriebsdatenbank. Der MCP wird lokal ausgeführt, wenn MCP-Clients wie Codex oder Claude Code ihn benötigen.

• Minimale Berechtigungen: Das PAT wird nur für ein einziges angegebenes privates Repository vergeben; der MCP fordert keine Berechtigungen für GitHub-Organisationen, Actions oder Pull Requests.

Voraussetzungen

• Docker Desktop oder Docker Engine

• Ein privates GitHub-Repository zur Nutzung als Wissensspeicher

• Ein feingranulares PAT, das ausschließlich dieses Repository umfasst

  • Metadata: Read-only

  • Contents: Read and write

  • Keine Berechtigungen für Pull Requests, Actions oder Administration

• Node.js 24 oder höher sowie Git, falls Sie aus dem Quellcode bauen

Bevor Sie Unternehmensmaterial speichern, prüfen Sie die Richtlinien Ihrer Organisation zur externen GitHub-Nutzung. Beim ersten Start wird empfohlen, die Verbindung mit synthetischen technischen Inhalten statt mit echten Arbeitsunterlagen zu verifizieren.

Schnellstart

1. Quellcode und lokales Image vorbereiten

git clone https://github.com/One-armed-boy/auto-knowledge-sync-mcp.git
cd auto-knowledge-sync-mcp
npm ci
npm run build
docker build --tag auto-knowledge-sync-mcp:local .

2. PAT-Datei und Konfiguration erstellen

Geben Sie das PAT nicht direkt in der Shell-Befehlszeile oder im YAML an, sondern verwalten Sie es in einer ausschließlich für den Besitzer zugänglichen Datei.

CONFIG_DIR="$HOME/.config/auto-knowledge-sync"
PAT_FILE="$CONFIG_DIR/secrets/github_pat"

mkdir -p "$CONFIG_DIR/secrets"
umask 077
touch "$PAT_FILE"
chmod 600 "$PAT_FILE"
${EDITOR:-nano} "$PAT_FILE"

node dist/cli.js init \
  --repository <GITHUB_OWNER>/<PRIVATE_KNOWLEDGE_REPOSITORY> \
  --token-file "$PAT_FILE"

init erstellt die Standardkonfigurationsdatei und initialisiert das Wissensmanifest im Repository. Wenn Sie die Standardkonfiguration verwenden, müssen Sie das YAML nicht direkt ändern. Die erzeugten Standardpfade sind wie folgt:

$HOME/.config/auto-knowledge-sync/config.yaml
$HOME/.config/auto-knowledge-sync/secrets/github_pat

3. Verbindungsdiagnose und MCP-Client-Registrierung

doctor prüft Repository, PAT-Berechtigungen, Schema-Kompatibilität sowie den Status von Branch und Cache und gibt Registrierungsbefehle für Codex und Claude Code aus.

CONFIG_FILE="$CONFIG_DIR/config.yaml"

node dist/cli.js doctor \
  --config-file "$CONFIG_FILE" \
  --token-file "$PAT_FILE" \
  --client-commands \
  --image-ref auto-knowledge-sync-mcp:local \
  --host-config-file "$CONFIG_FILE" \
  --host-token-file "$PAT_FILE"

Führen Sie den ausgegebenen Befehl client_commands.codex oder client_commands.claude einmal im jeweiligen Client aus. Nach der Registrierung können Sie die Verbindung wie folgt überprüfen:

codex mcp list
codex mcp get auto-knowledge-sync
claude mcp list
claude mcp get auto-knowledge-sync

Wenn Sie einen Client-Befehl benötigen, der direkt die Build-Ergebnisse des Hosts anstelle des Images ausführt, lassen Sie in doctor --client-commands die Option --image-ref sowie die Host-Mount-Optionen weg. Informationen zu stabilen Release-Images und einer per Digest festgelegten Compose-Runtime finden Sie in der Installations- und Betriebsdokumentation.

Grundlegende Verwendung

Verwenden Sie die Werkzeuge nach der Verbindung im LLM in der folgenden Reihenfolge:

1. Prüfen Sie mit repository_status den Status des Remote-Repositorys und des Schemas.

2. Lesen Sie vorhandenes Wissen mit search_knowledge oder get_knowledge.

3. Schlagen Sie neues technisches Wissen mit capture_knowledge vor.

4. Prüfen Sie die Datenschutz- und Vollständigkeitsprüfungen des Ergebnisses und committen Sie es anschließend mit apply_proposal.

5. Wenn veraltetes Wissen oder Gegenbeispiele gefunden werden, verwenden Sie challenge_knowledge oder maintain_knowledge.

Die bereitgestellten MCP-Werkzeuge sind:

Alle Änderungen verwenden einen Idempotenzschlüssel und eine Prüfung des entfernten HEAD. Bei einem Konflikt werden Sie aufgefordert, den aktuellen Status erneut abzurufen und einen neuen Vorschlag zu erstellen.

Konfiguration

Die Standardwerte sind konservativ eingestellt.

schema_version: 1
repository:
  slug: owner/private-knowledge
publishing:
  approval_mode: always
privacy:
  fail_closed: true
search:
  lexical: true
  vector:
    enabled: false
maintenance:
  inline_budget_ms: 200
logging:
  content: never

Die meisten Benutzer benötigen nur die von init erzeugte Konfiguration. Verwenden Sie init --advanced oder --privacy-rules-file nur, wenn ein Genehmigungsmodus oder organisationsspezifische Blockierungsregeln erforderlich sind. Ein Beispiel finden Sie in examples/privacy-rules.yaml.

Details zu Optionen und Kompatibilitätsregeln finden Sie in der Konfigurations- und Betriebsdokumentation; das Schema finden Sie unter spec/schemas.

Daten- und Sicherheitsprinzipien

• Das private GitHub-Repository ist die einzige SSOT des Wissens; der lokale SQLite-Index kann gelöscht und neu erstellt werden.

• Arbeitsoriginale, interne Identifikatoren, Anmeldeinformationen und privater Quellcode werden nicht in Wissenseinträge aufgenommen.

• Wenn eine Codeerklärung erforderlich ist, erstellen Sie neue Beispiele, die unabhängig vom Original sind.

• Das PAT wird nicht in die Konfiguration kopiert, sondern über einen schreibgeschützten Bind-Mount an den Container übergeben.

• Stellen Sie sicher, dass Konfiguration, PAT, private Markdown-Dateien und Arbeitscode nicht in den Git-Arbeitsbaum oder den Docker-Build-Kontext gelangen.

• In Protokollen werden weder Wissensinhalte noch Geheimnisse erfasst.

Das Bedrohungsmodell und die Datenschutz-Pipeline finden Sie in der Sicherheits- und Datenschutzdokumentation, das Verfahren zur Meldung von Schwachstellen in SECURITY.md.

Format des Wissensspeichers

Im GitHub-Repository werden Wissenseinträge, Evidenzkarten, Challenge-Reviews, Regressionsfälle und die generierte INDEX.md gemäß dem kanonischen Schema gespeichert. Verzeichnis-, Frontmatter- und Beziehungsregeln sind in der Wissensspeicher-Spezifikation beschrieben, Such- und Aktualisierungsrichtlinien im Such- und Wissenslebenszyklus.

Upgrade

Release-Images verwenden einen verifizierten Image-Digest anstelle eines veränderlichen Tags. Wenn Sie mit runtime init einen stabilen Compose-Deskriptor erstellen, müssen Sie den MCP-Client nach einem PAT-Wechsel oder einer Image-Aktualisierung nicht erneut registrieren. Prüfen Sie die Kompatibilität zuerst mit upgrade --check und führen Sie dann runtime update-image --verified-release aus. Schema- und Konfigurationsmigrationen werden automatisch zusammen mit versionsspezifischen Migrationsdateien angewendet und überschreiben die ursprüngliche Konfiguration nicht willkürlich.

Ausführliche Anweisungen finden Sie in der Migrationsdokumentation und der Installations- und Betriebsdokumentation.

Entwicklung

Um beizutragen, führen Sie in einer Umgebung mit Node.js 24 oder höher Folgendes aus:

npm ci
npm run check

Test- und Bewertungsbefehle sowie Änderungsregeln finden Sie in der Test- und Bewertungsdokumentation und der Systemarchitektur.

Weiterführende Lektüre

• Produktübersicht und Anforderungen

• Forschungsgrundlage

• Systemarchitektur

• MCP-API-Spezifikation

• GitHub-Speicherung und Parallelität

• Sicherheit und Datenschutz

Die Paketlizenz ist Apache-2.0.