Skill dfx-debug wrappt db-debug.sh für Claude Code (statt MCP-Server)

[TaprootFreak]

Skill dfx-debug wrappt db-debug.sh für Claude Code (statt MCP-Server)

Ersetzt den ursprünglichen Vorschlag dieses Issues (Thin-MCP-Server). Eine mehrquellige,
adversarial verifizierte Recherche (Stand Mitte 2026) ergab: für ein täglich genutztes,
read-only DB-Debug-CLI, das auch manuell auf der Shell läuft, ist ein Claude-Code-Skill
die effizientere Bauform — ein eigener MCP-Server ist hier Over-Engineering.

Warum Skill statt MCP

• Konnektivität ist schon gelöst. db-debug.sh authentifiziert sich selbst gegen den
  /gs/debug-Endpoint. MCP rechtfertigt sich über „Zugang schaffen" — der existiert bereits;
  ein MCP-Server würde die Auth-/HTTP-Logik nur duplizieren.
• Dual-Use Shell. Ein Skill ruft dasselbe Script auf, das man manuell tippt. Ein
  MCP-Server bedient die nackte Shell nicht → zwei zu pflegende Interfaces.
• Idle-Kosten. Skill: nur Metadaten (~50–100 Tokens) bis getriggert; der Script-Code
  kommt nie in den Context, nur die Query-Ausgabe zählt. (Hinweis: das populäre
  „MCP frisst ~55k Idle-Tokens" ist seit Tool-Search-Default 01/2026 ohnehin relativiert —
  der Ausschlag gegen MCP steht hier auf den strukturellen Gründen, nicht auf Token-Kosten.)
• „Hard part" ist Wissen, nicht Zugang. Der schwierige Teil ist welche Query/Flag
  (Anomalien, liquidity_balance, Referral-Trees) — Skill-Territorium.

MCP würde sich erst lohnen bei: mehreren Nicht-Claude-Clients am selben Endpoint, 10+ Tools,
echtem stateful/strukturiertem I/O mit Connection-Pooling, oder teamweiter versionierter
Distribution. Keiner dieser Fälle trifft zu.

Design

~/.claude/skills/dfx-debug/
  SKILL.md       # Frontmatter (name/description/allowed-tools) + Modi-Tabelle + Aufruf
  reference.md   # /gs/debug-Semantik, FinancialDataLog/balancesTotal, liquidity_balance-Schema

• SKILL.md referenziert das bestehende scripts/db-debug.sh (Single Source of Truth —
  Verbesserungen aus db-debug.sh: Effizienz-Verbesserungen (Auth-Caching, neue Modi, weniger Round-Trips) #3956 greifen automatisch mit), reicht Mode/SQL durch und dokumentiert die
  Flags (--anomalies / --balance / --stats / --asset-history / --referral-chain /
  --referral-tree / ad-hoc SELECT) sowie die noch fehlende liquidity_balance-Query.
• allowed-tools: Bash(<pfad>/db-debug.sh:*) — kein Permission-Prompt für genau dieses Script.
• Low-freedom-Anweisung: exakt dieses Script ausführen, nur read-only SELECT, nie Writes/DDL.
• reference.md = das /gs/debug-Schema (progressive disclosure → kostet erst beim Lesen Tokens).
• Das Script bleibt unangetastet und 1:1 manuell auf der Shell nutzbar.

Optionale Härtung (separat)

• PreToolUse-Hook, der schreibendes SQL (INSERT/UPDATE/DELETE/DROP) deterministisch blockt —
  Defense-in-Depth; der Server erzwingt read-only ohnehin per AST-Validierung.
• Plugin / privater Marketplace nur, falls das je teamweit an DFX-Devs verteilt werden soll.

Verwandt

• db-debug.sh: Effizienz-Verbesserungen (Auth-Caching, neue Modi, weniger Round-Trips) #3956 — db-debug.sh Effizienz-Verbesserungen (Token-Caching, --liquidity, --raw).
  Das verbesserte Script ist die Ausführungsschicht für beide Pfade (Shell + Skill).

Definition of Done

• ~/.claude/skills/dfx-debug/SKILL.md mit name/description/allowed-tools, ruft das
  bestehende db-debug.sh auf (Script wird nicht angefasst).
• reference.md mit /gs/debug-Semantik + liquidity_balance-Schema (lazy-loaded).
• Skill triggert via natürliche Sprache und /dfx-debug; allowed-tools unterdrückt Prompts.
• Read-only-Disziplin im Body (low freedom); optionaler PreToolUse-Hook dokumentiert.
• Manuelle Shell-Nutzung des Scripts unverändert möglich.

[TaprootFreak]

Verwandt: #3956 (db-debug.sh Effizienz-Verbesserungen) — gleiche Query-Logik, beide profitieren von Token-Caching, --liquidity und rekursiver CTE.

[TaprootFreak]

Aktualisiert: Ursprünglicher Thin-MCP-Vorschlag durch verifizierte Recherche (Stand Mitte 2026) ersetzt — Skill statt MCP. Begründung im aktualisierten Issue-Body; Ausführungsschicht bleibt #3956.