Engineering Knowledge MCP

Ein sehr leichtgewichtiger lokaler MCP-Server, der Coding-Agenten (Claude Code, GitHub Copilot usw.) eine gemeinsame Engineering-Wissensbasis zum Suchen und Aktualisieren bietet – interne Konventionen, API-Details, Infra-Konfiguration, Auth-Abläufe, lokales Dev-Setup usw.

Das Wissen liegt als einfache Markdown-Dateien in diesem Git-Repository. Der MCP-Server ist eine dünne, zustandslose Lese-/Schreibschicht über das Dateisystem – mehr nicht.

1. Was das tut

• Coding-Agenten können die Wissensbasis durchsuchen, statt über interne Konventionen zu raten oder den Benutzer zu bitten, sich zu wiederholen.

• Agenten können neue Fakten mit fast null Reibung festhalten (ein Tool-Aufruf, ohne wissen zu müssen, wohin der Fakt gehört).

• Agenten können strukturierte Wissensdokumente deterministisch erstellen und aktualisieren.

• Alles ist Markdown in Git, also auch ohne den MCP-Server nützlich – grep, lesen, bearbeiten, Diffs prüfen, committen, PR erstellen, genau wie Code.

Related MCP server: bikky

2. Architektur

engineering-knowledge-mcp/
├── knowledge/           # the knowledge base itself (Markdown, organized by topic area)
│   ├── api/
│   ├── cloud/
│   ├── data/
│   ├── frontend/
│   └── general/
├── inbox/
│   └── knowledge-inbox.md   # low-friction capture target; triage manually into knowledge/
├── src/
│   ├── index.ts         # MCP server entrypoint (stdio transport)
│   ├── paths.ts         # path sanitization / traversal protection
│   ├── knowledge.ts     # search, get, create, update, capture logic
│   └── tools/index.ts   # MCP tool registration + input schemas
├── test/                # node:test unit tests
├── CLAUDE.md            # agent instructions auto-loaded by Claude Code when working in this repo
├── package.json
└── tsconfig.json

Design-Entscheidungen, bewusst:

• MCP nur über stdio. Kein HTTP-Server, kein Express – der Client (Claude Code, Copilot, MCP Inspector) startet diesen Prozess und spricht JSON-RPC über stdin/stdout.

• Keine Datenbank, keine Embeddings, kein Vektor-Store. Die Suche ist case-insensitives Token-Matching über Markdown-Abschnitte, bei Bedarf berechnet. Das ist in der Größenordnung von zehn bis hundert kleinen Dokumenten völlig ausreichend, und es bedeutet, dass es keinen Index gibt, der mit den Dateien auf der Platte synchron gehalten werden muss – die Dateien sind immer die Quelle der Wahrheit.

• Kein In-Memory-Index, kein Dateisystem-Watching. Jeder Tool-Aufruf liest bei Aufrufzeit, was er braucht, von der Platte. Einfacher und bei dieser Größenordnung günstig.

• Keine automatischen Git-Commits. Tool-Aufrufe berühren nur den Arbeitsbaum. Review und Commit/Push liegen bei dir. (Das Design lässt Raum, später Auto-Commit oder PR-Erstellung hinzuzufügen, ohne die Tool-Verträge zu ändern.)

Hinweis zum offiziellen SDK

Die Kurzbeschreibung erwähnte @modelcontextprotocol/server; das tatsächlich veröffentlichte Paket ist @modelcontextprotocol/sdk (v1.30+), das dieses Projekt verwendet (McpServer + StdioServerTransport).

3. Wie Wissen gespeichert wird

Jedes Dokument ist eine Markdown-Datei unter knowledge/<bereich>/<thema>.md, mit optionalem minimalem Frontmatter:

---
title: APIM
tags:
  - api
  - apim
---

# APIM

## Base paths

Internal modelling APIs use ...

## Authentication

...

## Local development

...

Kein erforderliches Schema darüber hinaus – Frontmatter ist optional, Überschriften sind einfach normale Markdown-##-Abschnitte. search_knowledge und update_knowledge verwenden ##-Ebenen (und tiefere) Überschriften als Einheit eines „Abschnitts", sodass das Strukturieren von Dokumenten mit klaren Überschriften sowohl Suchergebnisse als auch Aktualisierungen präziser macht.

Festgehaltenes, aber noch nicht sortiertes Wissen geht als zeitgestempelte Einträge in inbox/knowledge-inbox.md. Regelmäßig (von Hand oder indem man einen Agenten um Hilfe bittet) Einträge aus dem Posteingang in richtige knowledge/-Dokumente verschieben/organisieren.

4. Ausführen

Erfordert Node.js 20+.

npm install
npm run build
npm start

Für lokale Iteration (läuft direkt aus TypeScript über tsx, kein Build-Schritt):

npm run dev

Beide starten den Server auf stdio und warten auf einen Client, der sich verbindet – du wirst keinen Protokollverkehr auf dem Terminal sehen; nur Start-/Diagnoselogs (auf stderr geschrieben, nie auf stdout, da stdout für MCP-Protokollmeldungen reserviert ist).

5. Testen mit MCP Inspector

Interaktive UI:

npx @modelcontextprotocol/inspector npm run dev

Das öffnet eine Browser-UI, in der du search_knowledge, list_knowledge_topics, get_knowledge, capture_knowledge, create_knowledge und update_knowledge von Hand aufrufen und ihre JSON-Schemas und Antworten inspizieren kannst.

Nicht-interaktiv / skriptbar:

npx @modelcontextprotocol/inspector --cli node dist/index.js --method tools/list

npx @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/call --tool-name search_knowledge --tool-arg query="apim authentication"

6. Beispiel-MCP-Client-Konfiguration

Claude Code / die meisten MCP-Clients verwenden einen Konfigurationsblock wie:

{
  "mcpServers": {
    "engineering-knowledge": {
      "command": "node",
      "args": ["/absolute/path/to/engineering-knowledge-mcp/dist/index.js"]
    }
  }
}

Für die MCP-Unterstützung von GitHub Copilot verwende den äquivalenten command/args-stdio-Server-Eintrag in seiner MCP-Konfigurationsdatei. Führe npm run build zuerst aus, damit dist/index.js existiert, oder zeige command/args auf npx tsx /absoluter/pfad/zu/src/index.ts, um direkt aus dem Quellcode zu laufen.

7. Wie ein Agent die Tools verwenden sollte

Dieses Repo enthält eine CLAUDE.md mit der folgenden Anweisung, die Claude Code automatisch lädt, wenn es in diesem Repo arbeitet. Für andere Clients (Copilot usw.) füge die äquivalente Anweisung zu ihrem System-Prompt / Anweisungsdatei hinzu:

Bevor du den Benutzer nach internen Engineering-Konventionen, Infrastruktur, APIs, Authentifizierung, Plattformkonfiguration oder etablierten Entwicklungsmustern fragst, durchsuche den Engineering-Wissens-MCP. Erfinde keine internen Konfigurationswerte. Wenn der Benutzer explizit bittet, dauerhaftes Engineering-Wissen zu merken, festzuhalten oder hinzuzufügen, verwende die Schreib-Tools des Wissens-MCP.

Tool-für-Tool-Anleitung:

• search_knowledge(query) – erste Anlaufstelle für „wie machen wir normalerweise…", „was ist unsere Konvention für…", „was ist die Basis-URL / der Auth-Ablauf für…". Gibt bewertete Abschnitte mit Dateipfaden zurück, nicht ganze Dokumente. Durchsucht auch noch nicht triagierte Einträge in inbox/knowledge-inbox.md, sodass ein kürzlich festgehaltenes Wissen auch vor der Ablage unter einem richtigen Thema auffindbar ist. Unter Dokumenten, die bereits auf Text/Überschrift passen, wird eines, dessen Frontmatter-tags auch ein Suchwort treffen, höher bewertet – Tags erhöhen die Bewertung, sie erzeugen allein keinen Treffer.

• list_knowledge_topics() – keine Argumente; listet Pfad, Titel und Tags jedes Dokuments ohne vollständigen Inhalt auf. Verwende das, um zu stöbern, was existiert, wenn du noch keinen guten Suchbegriff hast, oder um zu prüfen, ob ein Thema bereits existiert, bevor du create_knowledge aufrufst.

• get_knowledge(topicOrPath) – sobald du weißt (oder search_knowledge dir gesagt hat), welches Dokument du willst, hole es vollständig. Akzeptiert lockere Referenzen: "apim", "api/apim" oder "knowledge/api/apim.md".

• capture_knowledge(content, suggestedTopic?) – verwende, wenn der Benutzer „merke dir das" / „notiere das" sagt oder eine Tatsache nennt, die es wert ist, behalten zu werden, und du ihn nicht dazu bringen willst, herauszufinden, wo sie hingehört. Es hängt einfach an den Posteingang an.

• create_knowledge(topic, title, content) – verwende, wenn du ein wirklich neues Thema hinzufügst, das noch nicht existiert. Schlägt laut fehl, wenn das Thema bereits existiert (verwende stattdessen update_knowledge).

• update_knowledge(topicOrPath, heading, content, mode) – das bewusst nicht natürlichsprachliche Schreib-Tool. Siehe die Design-Notiz unten.

Warum update_knowledge heading + mode statt einer Freitext-change nimmt

Die Kurzbeschreibung markierte das als etwas, das sorgfältiges Design erfordert: Das Ziel ist, dass der Agent (der ein LLM hat) entscheidet, was eine natürlichsprachliche Änderung bedeutet, nicht dass dieser Server seine eigene KI-Interpretation von Anweisungen ausführt. Also nimmt update_knowledge ein strukturelles, deterministisches Ziel:

• topicOrPath – welches Dokument.

• heading – der exakte ##/###/usw. Überschriftstext, der einen Abschnitt identifiziert. Wenn er nicht existiert, wird ein neuer ##-Abschnitt mit dieser Überschrift am Ende des Dokuments angehängt (damit Aktualisierungen nie still gegen leicht veraltete Dokumente fehlschlagen).

• content – das wörtliche Markdown, das geschrieben werden soll.

• mode: "append" (Standard) fügt content am Ende des Abschnitts hinzu, "replace" überschreibt den gesamten Abschnittsbody.

Das bedeutet, dass der aufrufende Agent erwartet wird, bereits „aktualisiere den Abschnitt zur lokalen Entwicklung, um den neuen Port zu erwähnen" in konkreten Markdown-Inhalt umgewandelt und append/replace gewählt zu haben – genau die Art von Urteilsentscheidung, die ein LLM-gestützter Client treffen kann, und genau die Art von Urteilsentscheidung, die dieser leichtgewichtige Server nicht aus einem rohen String treffen sollte.

8. Importieren einer bestehenden Wissensbasis

Wenn du bereits Notizen irgendwo hast (ein persönliches Wiki, einen Ordner mit .md-Dateien, einen Notion-Export, ein großes „Stammeswissen"-Dokument, gespeicherte Slack-Threads usw.), gibt es kein Import-Tool und kein spezielles Format, in das konvertiert werden muss – das ist bewusst nur ein Ordner mit Markdown-Dateien. Zwei Möglichkeiten, um zu starten, ungefähr in der Reihenfolge, wie viel deiner bestehenden Struktur es wert ist, erhalten zu werden:

A. Dateien direkt einfügen (am besten, wenn deine Notizen bereits einigermaßen organisiert sind)

1. Kopiere deine bestehenden .md-Dateien in knowledge/, sortiert in diejenigen von api/ cloud/ data/ frontend/ general/, die am besten passt (oder füge neue Themenordner hinzu – nichts erzwingt die anfänglichen fünf).

2. Füge minimales Frontmatter (title, optional tags) zu jeder hinzu, wenn es keins hat – nicht erforderlich, aber es ist günstig und get_knowledge/ Suchergebnisse lesen sich besser mit einem Titel.

3. Zerlege sehr lange Dokumente in mit ## überschriebene Abschnitte, wenn sie es nicht bereits sind – search_knowledge und update_knowledge arbeiten beide auf der Überschriftsebene, also wird ein 10.000-Wörter-Einzelabschnitt-Wand aus Text schlechter suchen/aktualisieren als derselbe Inhalt unter ein paar klaren Überschriften aufgeteilt.

4. Führe npm test aus (Sicherheitscheck, dass nichts kaputt ist) und probiere ein paar search_knowledge / get_knowledge-Aufrufe über den Inspector (§5) gegen deinen echten Inhalt.

5. Prüfe den Diff und committe ihn selbst, wie jede andere Änderung an diesem Repo.

B. Einen Agenten die Migration für dich machen lassen (am besten für chaotisches/ unstrukturiertes Quellmaterial)

Zeige Claude Code (oder einem anderen Coding-Agenten, sobald dieses MCP für ihn konfiguriert ist) auf deine bestehenden Notizen und bitte ihn, sie mit den Schreib-Tools zu migrieren. Zum Beispiel:

Ich habe Engineering-Notizen in ~/notes/engineering/. Lies sie durch und verwende create_knowledge, um sie in richtige Dokumente unter knowledge/ zu verwandeln, nach Thema gruppiert. Wo etwas nicht sauber in ein bestehendes Thema passt, verwende stattdessen capture_knowledge, damit es im Posteingang landet, damit ich es überprüfen kann.

Das funktioniert gut, weil das Umwandeln von chaotischer Prosa in „einen Titel, einige Tags, ein paar klare ##-Abschnitte" genau die Art von Urteilsentscheidung ist, die ein LLM-gestützter Agent gut kann – dieselbe Begründung wie bei update_knowledge, die dieses Urteil an den Aufrufer statt an den Server delegiert (siehe §7). Der Agent kann trotzdem nicht außerhalb von knowledge// inbox/ schreiben, und jede resultierende Datei erscheint als normale unverfolgte/geänderte Datei, die du vor dem Committen überprüfen kannst – nichts wird automatisch committet.

In jedem Fall behandle den ersten Durchgang als groben Entwurf: Es ist in Ordnung (erwartet, sogar), dass capture_knowledge einen langen Posteingang produziert, den du über ein paar Sitzungen triagierst, statt zu versuchen, eine perfekte Taxonomie von Anfang an zu bekommen.

9. Sicherheitshinweise

• Alle Lese-/Schreibvorgänge sind auf knowledge/ und inbox/ unter dem Repo-Root beschränkt. Jeder vom Aufrufer gelieferte Pfad geht durch safeResolve (src/paths.ts), das absolute Pfade, ..-Traversal, Null-Bytes und alles, was außerhalb des erlaubten Verzeichnisses auflöst, ablehnt.

• create_knowledge bereinigt das topic in ein sicheres Dateinamensegment, bevor es verwendet wird.

• Kein Dokumentinhalt wird jemals ausgeführt, ausgewertet oder an ein Shell-Kommando übergeben.

• Kein Tool führt jemals ein Shell-Kommando basierend auf MCP-Eingabe aus.

• Fehler sind explizit (z. B. „kein Wissensdokument gefunden, das X entspricht") statt auf Vermutungen zurückzufallen.