DevTwin MCP

Gib KI-Codierungsagenten ein Live-, strukturiertes Verständnis deiner lokalen Entwicklungsumgebung.

DevTwin ist ein Model Context Protocol (MCP)-Server, der eine zentrale Frage für einen KI-Codierungsagenten beantwortet: Warum ist die Umgebung dieses Entwicklers anders, kaputt oder ungesund?

Er erkennt die Projekttechnologie, prüft installierte Laufzeitversionen gegen das, was ein Projekt tatsächlich benötigt, untersucht den Zustand von Abhängigkeiten und Lockfiles, findet benötigte lokale Dienste (Postgres, Redis, ...) und ob diese laufen, prüft Ports und Git-Status und verwandelt all das in strukturierte, evidenzbasierte Diagnosen – ohne deine Umgebung jemals an ein Cloud-Backend zu senden und ohne jemals geheime Werte an das Modell weiterzugeben.

Inhalt

• Warum es DevTwin gibt

• FAQ: Claude CLI hat bereits eine Shell, warum also überhaupt MCP?

• Vorteile

• Tokenkosten

• Ehrliche Kompromisse

• Mit vs. ohne DevTwin: Ein durchgearbeitetes Beispiel

• Beispielfragen, die dadurch möglich werden

• Beispiele pro Sprache

• Architektur

• Unterstützte Ökosysteme

• Installation

• MCP-Client-Konfiguration

• Verwendung in einem anderen Projekt

• Tool-Referenz

• Sicherheitsmodell

• Datenschutzmodell

• Local-First-Architektur

• Entwicklung

• Mitwirken

• Roadmap

• Lizenz

Warum es DevTwin gibt

• KI-Codierungsagenten lesen Code gut, sind aber blind für die Umgebung, in der dieser Code tatsächlich läuft.

• „Warum schlägt npm test auf meinem Rechner fehl?" hat meist nichts mit dem Code zu tun – es ist eine Node-Versionsabweichung, ein Dienst, der nicht läuft, oder Abhängigkeiten, die nie installiert wurden.

• DevTwin gibt einem Agenten dasselbe Signal, das ein leitender Entwickler von Hand sammeln würde – node --version, git status, lsof -i :5432, docker ps – als strukturierte Tool-Aufrufe statt als Ratespiel.

FAQ: Claude CLI hat bereits eine Shell, warum also überhaupt MCP?

Das ist normalerweise die erste Frage, die ein Entwickler stellt, und sie ist berechtigt. In einem Client wie Claude Code, der bereits ein Bash-Tool hat, kann man es einfach bitten, node --version, docker ps, lsof -i :5432 usw. direkt auszuführen – kein MCP-Server nötig. Die Lücke, die DevTwin schließt, ist nicht „Kann das überhaupt gemacht werden" – sondern diese:

Ehrliche Antwort speziell für Claude CLI: Da es bereits Bash hat, ist DevTwins Gewinn dort kleiner als „Fähigkeit, die du nicht hattest" – es sind Sicherheitsgarantien und konsistente, strukturierte Ausgaben, kein brandneuer Zugriff. Deshalb ist es auch nicht kostenlos – siehe Tokenkosten dafür, was die Verbindung tatsächlich kostet und wann es sich lohnt.

Ein paar weitere Fragen, die es sich lohnt zu stellen, bevor man das übernimmt:

„Ist das nicht nur ein doctor-Skript (make doctor, bin/setup) mit zusätzlichen Schritten?" Konzeptionell ja – viele ausgereifte Repos schreiben bereits von Hand eines. DevTwins Unterschied ist, dass die meisten Repos keins haben, das Schreiben eines guten pro Ökosystem echte Arbeit ist, die Ausgabe strukturiertes JSON ist, über das ein Agent nachdenken kann, statt Klartext, den ein Mensch liest, und dieselben 10 Tools funktionieren in jedem Repo identisch, statt eines maßgeschneiderten Skripts pro Projekt mit eigenen Konventionen und blinden Flecken.

„Funktioniert das nur mit Claude / Claude Code?" Nein. DevTwin spricht das standardmäßige Model Context Protocol – jeder MCP-kompatible Client (Claude Desktop, Cursor, Windsurf usw.) kann sich auf dieselbe Weise damit verbinden. Nichts daran ist Claude-spezifisch.

„Ist es sicher, sich darauf zu verlassen – wird es aktiv gepflegt?" Es ist Alpha-Status und ein junges Projekt – lies den Code (er ist kurz), bevor du ihm in einem Workflow vertraust, von dem du abhängig bist, so wie du es bei jeder neuen Dev-Tooling-Abhängigkeit tun würdest.

„Könnte es etwas Falsches vorschlagen oder automatisch eine schlechte Empfehlung ausführen?" Kein Tool hier führt einen recommendations-String aus – das sind nur Texte, die der Agent (oder du) lesen und darüber entscheiden kann. dev_check ist das einzige Tool, das etwas ausführt, und nur Befehle, die es selbst anhand einer festen Whitelist erkannt hat – siehe Sicherheitsmodell.

„Sendet es Daten nach Hause oder Telemetrie irgendwohin?" Nein. Keine eigenen Netzwerkaufrufe – siehe Local-First-Architektur.

„Ich möchte nicht, dass ein MCP-Server irgendwelche Befehle auf meinem Rechner ausführt." 9 der 10 Tools sind rein lesend (Dateilesen, Versionsprüfungen). Nur dev_check führt etwas aus, und nur Befehle, die DevTwin selbst aus Projektdateien erkannt hat, gegen eine Whitelist geprüft, mit shell=False und einem Timeout – siehe Sicherheitsmodell für genau das, was das erlaubt und was nicht.

Vorteile

• Weniger Fehldiagnosen. Ohne DevTwin kann ein Agent, der einen Fehler debuggt, nur Code lesen und raten – er wird oft einen Code-Fix für das vorschlagen, was eigentlich eine Node-Versionsabweichung oder eine gestoppte Datenbank ist. DevTwin liefert stattdessen die Bodenwahrheit statt einer Vermutung.

• Ein Aufruf statt vieler. Ein einzelner dev_health-Aufruf bündelt ~10 zugrunde liegende Prüfungen (Laufzeitversionen, Abhängigkeitsstatus, Dienste, Ports, Git) in einem strukturierten, bewerteten Ergebnis – statt dass ein Agent ein Dutzend separate Shell-Roundtrips macht und jedes Mal rohe CLI-Ausgaben parst.

• Jedes Mal dieselbe Prüfung. Die genauen Prüfungen pro Ökosystem (Gradle-Wrapper vs. System-Gradle, .nvmrc vs. package.json-Engines, ...) sind einmal kodiert, sodass die Diagnose über Sitzungen hinweg konsistent ist, statt davon abzuhängen, was einem Agenten gerade einfällt.

• Sicherer, als einem Agenten eine Shell zu geben. Keine willkürliche Befehlsausführung, keine zerstörerischen Operationen, jemals – siehe Sicherheitsmodell.

• Geheimnisse werden nie angefasst. Umgebungsvariablen, die geheim aussehen, werden nur auf Vorhandensein geprüft; Werte werden nie gelesen oder zurückgegeben – siehe Datenschutzmodell.

• Funktioniert auch dort, wo der Agent keine Shell hat. MCP-Clients ohne Bash-Tool (einige IDE-Assistenten, eingeschränkte Agenten) erhalten diese Fähigkeit überhaupt, nicht null Fähigkeit.

Tokenkosten

Echte Zahlen, keine Schätzung – direkt aus den MCP-Tool-Schemas dieses Servers gemessen (mcp.list_tools()) und einer echten dev_health()-Antwort, unter Verwendung der üblichen Näherung von ~4 Zeichen pro Token.

Zwei verschiedene Zeitpunkte verbrauchen Token, und sie kosten sehr unterschiedlich:

Aufschlüsselung der Tool-Schemas pro Tool (gemessen):

Das ehrliche Fazit: Für eine einzelne einmalige Diagnose in einer Sitzung, die sonst nie eine Umgebungsfrage berührt, kann rohes Bash in der Gesamttokenzahl günstiger sein – die feste Schemaabgabe von ~1.400 Token überwiegt oft die Einsparungen durch das Ersetzen mehrerer Shell-Befehle durch einen Aufruf. Siehe den durchgerechneten Vergleich unten für echte Zahlen auf beiden Seiten.

DevTwins Fall wird umso stärker, je mehr Umgebungsfragen in einer Sitzung auftauchen (die feste Abgabe wird einmal gezahlt; jede Frage danach kostet ~150 Token bei DevTwin gegenüber Hunderten mehr bei rohem Bash pro Mal) – und sein eigentlicher Vorteil ist überhaupt nicht die reine Tokenanzahl, sondern Konsistenz, Sicherheit und die Funktion in MCP-Clients ohne Bash-Tool. Siehe Vorteile und Ehrliche Kompromisse.

Praktische Konsequenz: Registriere DevTwin pro Projekt, nicht benutzerweit, damit die feste Abgabe nur in Sitzungen anfällt, in denen es tatsächlich nützlich ist – siehe Verwendung in einem anderen Projekt.

Ehrliche Kompromisse

DevTwin ist kein tägliches Werkzeug für eine stabile Umgebung – niemand muss bei jeder Funktion, die er schreibt, erneut prüfen, ob Postgres läuft. Es ist ein Werkzeug für den Notfall: hoher Wert zu bestimmten Zeitpunkten (frischer Klon, ein Build, der auf mysteriöse Weise fehlschlägt, direkt vor einem Commit) und ansonsten im Leerlauf. Das ist das beabsichtigte Nutzungsmuster, kein Mangel.

• Token-Overhead wird bei jeder Runde bezahlt, sobald es verbunden ist, ob genutzt oder nicht – siehe Token-Kosten für real gemessene Zahlen.

• Es gewinnt nicht zuverlässig bei Tokens für eine einzelne einmalige Frage; es gewinnt bei Konsistenz, Sicherheit und Reichweite in Clients ohne Shell – siehe Vorteile.

• Wenn ein Agent bereits vollen Shell-Zugriff auf ein Repo hat, das du vollständig kontrollierst, und selten Umgebungsdrift auftritt, brauchst du DevTwin dort möglicherweise gar nicht.

• DevTwin zahlt sich am meisten aus bei: geteilten/Onboarding-Repos, weniger vertrauenswürdigen oder shell-losen Agent-Setups und Multi-Ökosystem-Monorepos, wo „was prüfe ich überhaupt“ selbst der schwierige Teil ist.

Mit vs. ohne DevTwin: ein durchgerechnetes Beispiel

Angenommen, du fragst einen Agenten „Warum schlägt npm test fehl?“ und die eigentliche Ursache ist eine Node-Versionsabweichung plus ein nicht laufendes Postgres.

Ohne DevTwin (Agent mit roher Bash) – er muss die richtige Sequenz erraten, einen Befehl nach dem anderen:

cat package.json                      # spot "engines": {"node": ">=20"}
node --version                        # v16.20.0 -- mismatch found
grep -i "pg\|postgres" package.json   # spot the Postgres dependency
cat .env                              # risk: may print a real secret into context
lsof -i :5432                         # nothing listening
docker ps                             # check if it's in a container instead

Sechs Round-Trips, ein Untersuchungspfad, den der Agent erfinden musste, eine reale Chance, dass in Schritt 4 ein Geheimnis ins Gespräch leakt, und grob 400–800 Tokens an Befehls- und Ausgabetext (variiert mit Dateigrößen und wie viele Docker-Container laufen).

Mit DevTwin, ein Aufruf:

dev_health()

{
  "status": "error",
  "summary": "2 issues found: runtime drift, service down",
  "issues": [
    "Node 16.20.0 installed, project requires >=20 (from package.json engines)",
    "Postgres required (found in docker-compose.yml) but not running on 5432"
  ],
  "recommendations": [
    "nvm install 20 && nvm use 20",
    "docker compose up -d postgres"
  ]
}

Gleiche Schlussfolgerung, ~150 Tokens für die Antwort – plus die ~1.400-Token-feste Schema-Steuer, die in dieser Runde ohnehin bezahlt wurde (siehe Token-Kosten). Ein Aufruf statt sechs, keine Möglichkeit, ein Geheimnis zu leaken, und jedes Mal dieselbe kuratierte Prüfung statt einer freihändigen Untersuchung, die von Sitzung zu Sitzung variiert.

Beispielhafte Fragen, die das ermöglicht

• „Prüfe meine Entwicklungsumgebung.“

• „Warum schlägt mein Kotlin-Projekt beim Build fehl?“

• „Ist meine Node-Version für dieses Repo korrekt?“

• „Warum kann meine App keine Verbindung zu Postgres herstellen?“

• „Weicht meine Umgebung von dem ab, was dieses Repo erwartet?“

• „Was sollte ich ausführen, bevor ich committe?“

• „Ich habe dieses Repo gerade geklont – was muss ich tun, um es zum Laufen zu bringen?“

Beispiele pro Sprache

Eine Zeile pro unterstütztem Ökosystem: eine Frage, die du tatsächlich stellen würdest, was DevTwin prüft, um sie zu beantworten, und der Test-/Build-Befehl, den es für dev_check erkennt.

Architektur

Ein MCP-Server, viele Ökosystem-Adapter – kein separater Server pro Sprache.

MCP server -> core (workspace/detector/health/drift/diagnostics) ->
adapters (python/node/jvm/go/rust/dotnet/swift/ruby/php/generic) ->
system inspection (os/process/ports/env/fs/docker) ->
service detection (postgres/redis/generic)

Vollständige Details in docs/architecture.md. So fügst du einen neuen Sprachadapter hinzu: docs/adapters.md.

Unterstützte Ökosysteme

Jedes Projekt, das keinem spezifischen Adapter entspricht, erhält trotzdem nützliche Ausgaben vom generischen Adapter – DevTwin gibt für ein nicht erkanntes Projekt nie nichts zurück.

Installation

uv pip install devtwin-mcp
# or
pip install devtwin-mcp

Für lokale Entwicklung gegen einen Klon dieses Repos siehe docs/development.md.

MCP-Client-Konfiguration

Die genaue Konfigurationssyntax unterscheidet sich je nach Client – konsultiere die Doku deines Clients. Generell ist DevTwin ein stdio-MCP-Server, der wie folgt aufgerufen wird:

{
  "mcpServers": {
    "devtwin": {
      "command": "devtwin"
    }
  }
}

Für lokale Entwicklung aus einem Klon (ohne das Paket zu installieren):

{
  "mcpServers": {
    "devtwin": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/devtwin-mcp", "devtwin"]
    }
  }
}

Verifiziere die Tool-Erkennung mit dem MCP Inspector:

npx @modelcontextprotocol/inspector uv run devtwin

Verwendung auf einem anderen Projekt (für andere Entwickler)

DevTwin ist eine Binärdatei – weise beliebig viele Projekte auf dieselbe Installation hin, keine Neuinstallation pro Projekt nötig. Zwei Bereiche:

Projektbereich – lege eine .mcp.json im Projektstamm ab:

{
  "mcpServers": {
    "devtwin": {
      "command": "/absolute/path/to/devtwin-mcp/.venv/bin/devtwin"
    }
  }
}

oder mit der Claude Code CLI:

claude mcp add devtwin /absolute/path/to/devtwin-mcp/.venv/bin/devtwin --scope project

Benutzerbereich:

claude mcp add devtwin /absolute/path/to/devtwin-mcp/.venv/bin/devtwin --scope user

Nach dem Hinzufügen starte den Client neu (oder verbinde den MCP-Server neu) und stelle dann einfach normale Fragen – siehe Beispielhafte Fragen, die das ermöglicht.

Monorepo-Tipp: In einem Repo mit gemischten Plattformen (z. B. Android + iOS + Backend) richte Fragen an den spezifischen Unterordner statt an den Repo-Stamm – z. B. „prüfe die Gesundheit der android/-App“. dev_detect im Stamm eines gemischten Repos meldet jedes gefundene Ökosystem, was einmal nützlich ist, aber für eine gezielte Prüfung laut ist.

Tool-Referenz

Alle Tools geben {status, summary, data, issues, recommendations} zurück. status ist einer von ok, warning, error, unknown.

Sicherheitsmodell

• Keine beliebige Befehlsausführung. Es gibt kein execute_shell-Werkzeug. dev_check führt nur Befehle aus, die DevTwin selbst aus Projektdateien erkannt hat, geprüft gegen eine Zulassungsliste, ausgeführt mit shell=False und einem Timeout.

• Keine destruktiven Aktionen, niemals. DevTwin führt nie git reset --hard, rm -rf, kill -9, docker compose down, Lockfile-Löschung oder .env-Mutation aus.

• dev_prepare plant nur. Es klassifiziert jeden vorgeschlagenen Schritt (read_only/safe/requires_approval/dangerous) und führt selbst nie etwas aus.

Vollständige Details: docs/security.md.

Datenschutzmodell

• Umgebungsvariablen werden nur auf Vorhandensein geprüft, wenn ihr Name geheim aussieht (PASSWORD, TOKEN, SECRET, API_KEY, PRIVATE_KEY, ACCESS_KEY, AUTH, CREDENTIAL, ...) – Werte werden nie zurückgegeben.

• .env-Dateien werden nur auf Variablen-Namen gescannt.

• dev_precommit kennzeichnet geheim-aussehende gestufte Dateinamen, ohne deren Inhalte zu lesen oder zu melden.

Lokal-first-Architektur

• Keine Serverkomponente, kein Konto, keine eigenen Netzwerkaufrufe über die lokalen Befehle hinaus, die es inspiziert (git, docker, Sprach-Toolchains).

• Alles, was es meldet, stammt aus Dateien und Prozessen, die bereits auf der Maschine vorhanden sind, auf der es läuft.

Entwicklung

uv sync --all-extras
uv run pytest
uv run ruff check .
uv run mypy src
uv run devtwin

Siehe docs/development.md für den vollständigen Arbeitsablauf.

Beitragen

Siehe CONTRIBUTING.md. Das Hinzufügen eines neuen Sprach-Ökosystems ist der häufigste Beitrag – siehe docs/adapters.md für eine Vorlage, oder src/devtwin/adapters/swift.py, ruby.py und php.py für echte, zusammengeführte Beispiele, an denen Sie sich orientieren können.

Roadmap

• Zusätzliche Ökosystem-Adapter: Elixir, Dart, Scala, C/C++ (CMake/Bazel/Buck), Nix (siehe docs/adapters.md für Hinweise zum Hinzufügen)

• Zusätzliche Dienst-Erkennungen (MySQL/MariaDB, MongoDB, Kafka, RabbitMQ)

• Umfangreichere Drift-Vergleiche mit CI-Konfiguration (z. B. GitHub Actions Laufzeit-Matrizen)

• Optionale lokale Zwischenspeicherung teurer Prüfungen über Tool-Aufrufe innerhalb einer Sitzung

Lizenz

Apache-2.0 – siehe LICENSE.