feat(mcp): Ressourcen und Prompts fuer Claude Desktop, zwei Befunde behoben

MCP-ADAPTER 1.1

Werkzeuge ruft ein Modell von sich aus auf - Ressourcen und Prompts waehlt ein
MENSCH. In Claude Desktop sind das Anhang-Menue und Schraegstrich-Befehle, und
genau die fehlten.

  - Vier Ressourcen: dc://roadmap (fertiger Markdown-Block),
    dc://naechste-schritte, dc://projekte, dc://befunde.
  - Vier Prompts: arbeit-aufnehmen, befunde-sichten, fehler-melden,
    roadmap-pflegen. Ihr Wert liegt nicht in der gesparten Tipparbeit, sondern
    darin, dass die Hausregeln mitkommen - erst nachsehen wer dransitzt,
    Fremdmeldung nur mit Begruendung, Verworfenes nicht ohne neues Argument
    wiedervorschlagen. Bisher standen die nur in Werkzeugbeschreibungen, und
    die liest ein Modell erst, wenn es das Werkzeug schon gewaehlt hat.
  - DC_PROJECT: worauf die Ressourcen zeigen. Werkzeuge nehmen project_slug je
    Aufruf, Ressourcen haben keine Argumente.
  - Ressourcen laufen durch dieselbe Fremddaten-Abgrenzung wie
    Werkzeugergebnisse - sie sind eher ein Einfallstor, weil sie ungefragt im
    Kontext landen.
  - Einrichtung fuer claude_desktop_config.json dokumentiert.

  Behoben: "initialize" spiegelte die verlangte Protokollfassung zurueck. Ein
  Client, der 2025-06-18 anfragte, bekam sie bestaetigt, obwohl der Adapter
  fuer 2024-11-05 geschrieben war. Jetzt wird gegen eine Liste tatsaechlich
  bedienter Fassungen ausgehandelt.

  Behoben: process.exit() mitten in schliessenden libuv-Handles. Unter Windows
  eine Assertion und Rueckgabewert != 0 - ein sauber beendeter Server sah aus
  wie ein abgestuerzter.

ZWEI BEFUNDE, DIE ERST DIE RESSOURCEN ZUTAGE FOERDERTEN

  - roadmap.php?action=render lehnte fuer ein Werkbank-Token mit
    "missing_project" ab. projectFilter() laesst es beim Lesen bewusst durch
    (es soll die Landschaft sehen) und liefert null, also wurde der
    Projektbezug "all". Betroffen war ausgerechnet der Tokentyp, den der
    Adapter verlangt. Rueckfall ist jetzt das Heimatprojekt des Tokens.
  - ProjectLinks::between() benutzte :a dreimal, forProject() :slug zweimal.
    Bei ATTR_EMULATE_PREPARES = false unzulaessig -> HY093 und ein 500 auf
    /api/bugtracker/v1/projects. Derselbe Fehler wie einst in der
    Volltextsuche des Bugtrackers; ein Suchlauf ueber alle prepare()-Aufrufe
    der Codebasis fand keine weitere Stelle.

WARUM BEIDE UNBEMERKT BLIEBEN

Beide Wege laufen nur mit einem Werkbank-Token (owner_type = dev_agent). Der
Testlauf hatte keines - es gibt keine API, so eines anzulegen, und in der
Produktion geschieht das von Hand. Ein Tokentyp, den kein Testfall benutzt,
ist ein Tokentyp, dessen Sonderwege niemand prueft.

testctl.php kann jetzt action=workbench_token; vier Testfaelle decken die Wege
ab, samt Gegenprobe, dass der Rueckfall aufs Heimatprojekt das Lesen ueber alle
Projekte nicht einschraenkt. 128 Faelle, alle gruen.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

mcp/deploymentcenter-mcp.mjs

@@ -34,9 +34,33 @@ const BASE_URL = (process.env.DC_BASE_URL || 'https://dc.mhdf.de').replace(/\/+$
 const TOKEN = process.env.DC_TOKEN || '';
 const TIMEOUT_MS = Number(process.env.DC_TIMEOUT_MS || 15000);
 
+// Auf welches Projekt zeigen die Ressourcen?
+//
+// Leer heisst: das Heimatprojekt des Tokens - der Normalfall, wenn der Adapter
+// im Projektverzeichnis laeuft. Zu setzen ist es dort, wo ein Mensch am
+// Ueberblick sitzt statt an einem Projekt: In Claude Desktop haengt man die
+// Roadmap eines anderen Projekts an, ohne dafuer das Token zu tauschen.
+// Werkzeuge nehmen project_slug ohnehin je Aufruf entgegen; Ressourcen haben
+// keine Argumente, deshalb hier.
+const PROJECT = process.env.DC_PROJECT || '';
+
 const SERVER_NAME = 'deploymentcenter';
-const SERVER_VERSION = '1.0.0';
-const DEFAULT_PROTOCOL = '2024-11-05';
+const SERVER_VERSION = '1.1.0';
+
+// Protokollfassungen, die dieser Adapter tatsaechlich bedient - neueste zuerst.
+//
+// Zuvor wurde bei "initialize" schlicht zurueckgegeben, was der Client
+// verlangte. Das ist keine Aushandlung, sondern ein Echo: Ein Client, der
+// 2025-06-18 anfragt, bekam 2025-06-18 bestaetigt und durfte daraufhin
+// annehmen, was diese Fassung mitbringt - obwohl der Adapter fuer 2024-11-05
+// geschrieben war. Fehler dieser Art zeigen sich erst spaeter und an ganz
+// anderer Stelle.
+//
+// Jetzt gilt: Kennt der Adapter die verlangte Fassung, bestaetigt er sie.
+// Kennt er sie nicht, nennt er seine neueste - und der Client entscheidet,
+// ob ihm das genuegt. Genau so ist die Aushandlung gedacht.
+const PROTOCOL_VERSIONS = ['2025-06-18', '2025-03-26', '2024-11-05'];
+const DEFAULT_PROTOCOL = PROTOCOL_VERSIONS[0];
 
 // ---------------------------------------------------------------------------
 // Vertrauensgrenze
@@ -555,6 +579,203 @@ const TOOLS = [
 
 const TOOL_BY_NAME = new Map(TOOLS.map((tool) => [tool.name, tool]));
 
+// ---------------------------------------------------------------------------
+// Ressourcen
+// ---------------------------------------------------------------------------
+// Werkzeuge muss ein Modell von sich aus aufrufen. Ressourcen haengt ein
+// MENSCH an - in Claude Desktop ueber das Anhang-Menue. Das ist der
+// Unterschied, der sie lohnend macht: Wer eine Frage zum Projektstand stellt,
+// legt die Roadmap daneben, statt zu hoffen, dass das Modell dc_roadmap
+// aufruft.
+//
+// Bewusst wenige und nur lesende. Eine Ressource je Endpunkt waere dieselbe
+// Aufblaehung, die bei den Werkzeugen schon abgelehnt wurde.
+const RESOURCES = [
+  {
+    uri: 'dc://roadmap',
+    name: 'Roadmap des Projekts',
+    description:
+      'Der Planungsstand als Markdown, so wie ihn cli/roadmap.php in die '
+      + 'Projektdatei schreibt: Themenbereiche, Reihenfolge, Zielfassung, wer '
+      + 'woran sitzt. Der Live-Stand - nicht die Kopie im Repository.',
+    mimeType: 'text/markdown',
+    read: async () => {
+      const antwort = await call('GET', '/api/bugtracker/v1/roadmap.php', {
+        query: { action: 'render', project_slug: PROJECT },
+      });
+      return { mimeType: 'text/markdown', text: String(antwort.markdown ?? '') };
+    },
+  },
+  {
+    uri: 'dc://naechste-schritte',
+    name: 'Als Naechstes dran',
+    description:
+      'Die vorderen Eintraege der Warteschlange samt Bearbeiter. Beantwortet '
+      + '"woran arbeite ich jetzt" und "sitzt da schon jemand dran".',
+    mimeType: 'application/json',
+    read: async () => {
+      const [naechste, aktiv] = await Promise.all([
+        call('GET', '/api/bugtracker/v1/roadmap.php', { query: { action: 'next', limit: 8, project_slug: PROJECT } }),
+        call('GET', '/api/bugtracker/v1/roadmap.php', { query: { action: 'active', project_slug: PROJECT } }),
+      ]);
+      return {
+        mimeType: 'application/json',
+        text: JSON.stringify({ als_naechstes: naechste.items, in_arbeit: aktiv.items }, null, 2),
+      };
+    },
+  },
+  {
+    uri: 'dc://projekte',
+    name: 'Projektlandschaft',
+    description:
+      'Alle Projekte mit Slug, offenen Items und der Beziehung zum eigenen '
+      + '(uses_sdk, depends_on, shares_code). Noetig, bevor ein Slug geraten wird.',
+    mimeType: 'application/json',
+    read: async () => ({
+      mimeType: 'application/json',
+      text: JSON.stringify(await call('GET', '/api/bugtracker/v1/projects'), null, 2),
+    }),
+  },
+  {
+    uri: 'dc://befunde',
+    name: 'Offene Befunde je Detektor',
+    description:
+      'Die Zaehlung des Supervisors als Einstieg in die Sichtung: was ist '
+      + 'ungewoehnlich, und wie oft.',
+    mimeType: 'application/json',
+    read: async () => ({
+      mimeType: 'application/json',
+      text: JSON.stringify(await call('GET', '/api/supervisor/v1/summary', { query: { project_slug: PROJECT } }), null, 2),
+    }),
+  },
+];
+
+const RESOURCE_BY_URI = new Map(RESOURCES.map((r) => [r.uri, r]));
+
+// ---------------------------------------------------------------------------
+// Prompts
+// ---------------------------------------------------------------------------
+// In Claude Desktop erscheinen sie als Schraegstrich-Befehle im Eingabefeld.
+// Ihr Wert liegt nicht darin, Tipparbeit zu sparen, sondern darin, die
+// Hausregeln mitzuliefern: dass vor dem Anfangen nachgesehen wird, wer schon
+// dransitzt; dass eine Fremdmeldung eine Begruendung braucht; dass ein
+// verworfenes Vorhaben nicht ohne neues Argument wiederkommt.
+//
+// Ohne sie stehen diese Regeln nur in der Werkzeugbeschreibung - und die liest
+// ein Modell erst, wenn es das Werkzeug schon gewaehlt hat.
+const PROMPTS = [
+  {
+    name: 'arbeit-aufnehmen',
+    description: 'Was ist als Naechstes dran? Planungsstand pruefen, Item uebernehmen, anfangen.',
+    arguments: [],
+    build: () => `Nimm Arbeit im Deploymentcenter auf. Halte dabei diese Reihenfolge ein:
+
+1. dc_roadmap aufrufen. Es beantwortet zwei Fragen, die man sich sonst falsch
+   beantwortet: was steht an, und sitzt dort schon jemand dran.
+2. Erst dann dc_next_task, um ein Item exklusiv zu uebernehmen. Ohne diesen
+   Schritt arbeiten zwei Agenten am selben Problem.
+3. Kommt ein Item mit Status "in_verification" oder "awaiting_verification"
+   zurueck, lautet die Aufgabe NICHT "behebe das", sondern "traegt der Fix?".
+   In resolved_in_build steht, gegen welche Fassung zu pruefen ist.
+4. Fortschritt mit dc_comment festhalten, solange du arbeitest.
+5. Kommst du nicht weiter: dc_release. Ein gehaltenes Item sperrt es fuer alle
+   anderen bis zum Lease-Ende.
+
+Sag mir zuerst, was du vorgefunden hast und was du dir vornimmst - bevor du
+etwas aenderst.`,
+  },
+  {
+    name: 'befunde-sichten',
+    description: 'Supervisor-Befunde durchgehen und einstufen: echt, Artefakt oder Rauschen?',
+    arguments: [
+      {
+        name: 'detektor',
+        description: 'Nur eine Detektor-Familie, z. B. "deviation" oder "novel". Optional.',
+        required: false,
+      },
+    ],
+    build: (args) => `Sichte die offenen Supervisor-Befunde${
+      args.detektor ? ` der Familie "${args.detektor}"` : ''
+    }.
+
+Fang mit dc_finding_summary an - die Zaehlung je Detektor zeigt, wo ueberhaupt
+etwas los ist. Dann dc_findings fuer die Einzelbefunde, dc_metrics wenn du den
+Verlauf einer Kennzahl brauchst, um einen Befund zu beurteilen.
+
+Ein Befund behauptet nicht, dass etwas kaputt ist, sondern dass etwas
+ungewoehnlich ist. Die Frage "ist das schlimm?" beantwortest du, nicht der
+Detektor.
+
+Achte besonders auf die Umgebung: Was ausserhalb von "production" auffiel, ist
+eine Stufe niedriger einzuordnen - dort entsteht systematisch mehr Rauschen.
+Aber die Umkehrung gilt auch: Fehlende Zugangsdaten auf dem Pruefstand sind ein
+Artefakt, WIE die Software darauf reagiert dagegen nicht. Endlose
+Wiederholungen, verschluckte Fehler, halb geschriebener Zustand oder ein
+Passwort im Protokoll sind echte Befunde, auch wenn der Ausloeser kuenstlich war.
+
+Schlag mir eine Einstufung je Befund vor. Setzen tue ich sie, nicht du.`,
+  },
+  {
+    name: 'fehler-melden',
+    description: 'Einen Fehler oder eine Idee im richtigen Projekt melden - auch in einem fremden.',
+    arguments: [
+      { name: 'beobachtung', description: 'Was ist passiert?', required: true },
+    ],
+    build: (args) => `Melde das im Deploymentcenter:
+
+${args.beobachtung}
+
+Vorher zu klaeren, in dieser Reihenfolge:
+
+1. In WELCHEM Projekt liegt die Ursache? Nicht dort melden, wo du gerade
+   arbeitest, sondern wo der Fehler herkommt. Ein Fehler im SDK, im
+   update-agent, in der Lizenzpruefung oder im Bugtracker gehoert unter
+   "deploymentcenter". Bei Zweifeln dc_projects aufrufen - den Slug nicht raten.
+2. Ist es ein FREMDES Projekt, ist "evidence" Pflicht: was wurde beobachtet,
+   und warum liegt die Ursache dort und nicht bei uns? Pruefe ehrlich, ob nicht
+   das eigene Projekt die Schnittstelle falsch benutzt - das ist der haeufigere
+   Fall.
+3. Mit dc_search nachsehen, ob es das schon gibt. Ein zweites Item zur selben
+   Sache verteilt die Diskussion auf zwei Straenge.
+4. client_ref setzen, damit ein wiederholter Aufruf kein Duplikat anlegt, und
+   build_version mitschicken - daran entscheidet der Server, ob es eine
+   Regression ist oder nur ein veralteter Pruefstand.
+
+Zeig mir den Entwurf, bevor du dc_report aufrufst.`,
+  },
+  {
+    name: 'roadmap-pflegen',
+    description: 'Ein Vorhaben einplanen, umsortieren oder zuruecksetzen - mit den Regeln dazu.',
+    arguments: [
+      { name: 'vorhaben', description: 'Worum geht es?', required: false },
+    ],
+    build: (args) => `Pflege die Roadmap im Deploymentcenter${
+      args.vorhaben ? `. Es geht um: ${args.vorhaben}` : ''
+    }.
+
+Der aktuelle Stand kommt aus dc_roadmap, geaendert wird mit dc_roadmap_set.
+Vier Regeln, die dabei gelten:
+
+1. Ein Vorhaben steht auf der Roadmap, sobald es einen Themenbereich (epic)
+   hat. Das ist das einzige Kennzeichen. Erst dc_report anlegen, dann
+   einplanen - anlegen und einplanen sind zwei Entscheidungen.
+2. Die Reihenfolge laeuft in Zehnerschritten. Die Luecken sind Absicht: So
+   laesst sich spaeter etwas dazwischenschieben, ohne alles neu zu nummerieren.
+3. Zurueckstellen geht nur mit defer_trigger - woran erkennt man, dass
+   "spaeter" jetzt ist? Ohne benannten Anlass ist ein Vorhaben nicht
+   zurueckgestellt, sondern vergessen. Der Server lehnt es sonst ab.
+4. Steht etwas auf "rejected" oder "deferred", lies erst die Begruendung, auf
+   die doc_anchor zeigt, bevor du es erneut vorschlaegst. Ein neuer Vorschlag
+   braucht ein Argument, das dort noch nicht steht.
+
+Der Zustand gehoert ins Deploymentcenter, die Begruendung in die Projektdatei.
+Trag keine Statuszeilen von Hand in eine Markdown-Datei - der erzeugte Block
+zwischen den dc:roadmap-Markern wird beim naechsten Lauf ueberschrieben.`,
+  },
+];
+
+const PROMPT_BY_NAME = new Map(PROMPTS.map((p) => [p.name, p]));
+
 // ---------------------------------------------------------------------------
 // JSON-RPC ueber stdio
 // ---------------------------------------------------------------------------
@@ -628,19 +849,99 @@ async function handleToolCall(id, params) {
   }
 }
 
+/**
+ * Liefert den Inhalt einer Ressource.
+ *
+ * Anders als bei Werkzeugen gibt es hier kein isError-Feld - ein Fehlschlag
+ * ist ein JSON-RPC-Fehler. Sonst haengte ein Client eine Fehlermeldung als
+ * Kontext an und arbeitete damit weiter, als waere es die Roadmap.
+ */
+async function handleResourceRead(id, params) {
+  const uri = params?.uri;
+  const resource = RESOURCE_BY_URI.get(uri);
+
+  if (!resource) {
+    replyError(id, -32602, `Unbekannte Ressource "${uri}".`);
+    return;
+  }
+
+  try {
+    const { mimeType, text } = await resource.read();
+
+    // Dieselbe Vertrauensgrenze wie bei den Werkzeugen. Eine Ressource wird
+    // sogar eher zum Einfallstor: Sie landet ungefragt im Kontext, weil ein
+    // Mensch sie angehaengt hat - und in Titeln und Fehlertexten steht, was
+    // auf fremden Maschinen entstanden ist.
+    const inhalt = mimeType === 'application/json'
+      ? JSON.stringify(guard(JSON.parse(text)), null, 2)
+      : text;
+
+    const hinweis = inhalt.includes('<<<FREMDDATEN') ? `${TRUST_NOTE}\n\n` : '';
+
+    reply(id, { contents: [{ uri, mimeType, text: hinweis + inhalt }] });
+  } catch (err) {
+    replyError(
+      id,
+      -32603,
+      err instanceof ToolError
+        ? `${err.code}: ${err.message}`
+        : `Ressource "${uri}" nicht lesbar: ${err.message}`
+    );
+  }
+}
+
+/** Baut einen Prompt zusammen. Rein oertlich - kein Aufruf ins Deploymentcenter. */
+function handlePromptGet(id, params) {
+  const prompt = PROMPT_BY_NAME.get(params?.name);
+
+  if (!prompt) {
+    replyError(id, -32602, `Unbekannter Prompt "${params?.name}".`);
+    return;
+  }
+
+  const args = params?.arguments ?? {};
+
+  for (const feld of prompt.arguments) {
+    if (feld.required && !args[feld.name]) {
+      replyError(id, -32602, `Dem Prompt "${prompt.name}" fehlt "${feld.name}".`);
+      return;
+    }
+  }
+
+  // Argumente kommen vom Menschen im Eingabefeld, nicht von einer fremden
+  // Maschine - sie werden deshalb nicht abgegrenzt. Eingesetzt werden sie
+  // trotzdem nur an den vorgesehenen Stellen und nie als Anweisung.
+  reply(id, {
+    description: prompt.description,
+    messages: [{ role: 'user', content: { type: 'text', text: prompt.build(args) } }],
+  });
+}
+
 async function handle(message) {
   const { id, method, params } = message;
 
   switch (method) {
-    case 'initialize':
+    case 'initialize': {
+      // Aushandeln statt spiegeln: Nur eine Fassung bestaetigen, die dieser
+      // Adapter auch bedient. Kennt er die verlangte nicht, nennt er seine
+      // neueste und ueberlaesst dem Client die Entscheidung.
+      const verlangt = params?.protocolVersion;
+      const version = PROTOCOL_VERSIONS.includes(verlangt) ? verlangt : DEFAULT_PROTOCOL;
+
       reply(id, {
-        protocolVersion: typeof params?.protocolVersion === 'string'
-          ? params.protocolVersion
-          : DEFAULT_PROTOCOL,
-        capabilities: { tools: {} },
+        protocolVersion: version,
+        capabilities: {
+          tools: {},
+          // listChanged bleibt aus: Werkzeuge, Ressourcen und Prompts stehen
+          // fest, solange der Prozess laeuft. Die Zusage zu geben und nie
+          // etwas zu senden waere schlechter als sie zu lassen.
+          resources: {},
+          prompts: {},
+        },
         serverInfo: { name: SERVER_NAME, version: SERVER_VERSION },
       });
       return;
+    }
 
     case 'notifications/initialized':
     case 'notifications/cancelled':
@@ -665,6 +966,37 @@ async function handle(message) {
       await handleToolCall(id, params);
       return;
 
+    case 'resources/list':
+      reply(id, {
+        resources: RESOURCES.map(({ uri, name, description, mimeType }) => ({
+          uri, name, description, mimeType,
+        })),
+      });
+      return;
+
+    // Es gibt keine Vorlagen mit Platzhaltern - die Antwort ist leer und nicht
+    // "unbekannte Methode". Ein Client, der beim Aufbau der Anhangsliste einen
+    // -32601 bekommt, meldet das als Fehler, obwohl nichts falsch ist.
+    case 'resources/templates/list':
+      reply(id, { resourceTemplates: [] });
+      return;
+
+    case 'resources/read':
+      await handleResourceRead(id, params);
+      return;
+
+    case 'prompts/list':
+      reply(id, {
+        prompts: PROMPTS.map(({ name, description, arguments: args }) => ({
+          name, description, arguments: args,
+        })),
+      });
+      return;
+
+    case 'prompts/get':
+      handlePromptGet(id, params);
+      return;
+
     default:
       if (id !== undefined) replyError(id, -32601, `Unbekannte Methode "${method}".`);
   }
@@ -679,7 +1011,25 @@ let pending = 0;
 let closed = false;
 
 function drained() {
-  if (closed && pending === 0) process.exit(0);
+  if (!closed || pending > 0) return;
+
+  // NICHT process.exit(). Der reisst den Prozess sofort ab, auch wenn libuv
+  // gerade dabei ist, Handles zu schliessen - unter Windows quittiert das die
+  // Laufzeit mit
+  //
+  //   Assertion failed: !(handle->flags & UV_HANDLE_CLOSING), src\win\async.c
+  //
+  // und einem Rueckgabewert ungleich null. Fuer den Aufrufer sieht ein
+  // ordentlich beendeter Adapter dann aus wie ein abgestuerzter; Claude
+  // Desktop meldet den Server als fehlgeschlagen, obwohl jede Antwort
+  // rausgegangen ist.
+  //
+  // Stattdessen: Rueckgabewert vormerken und die letzte Referenz auf stdin
+  // loesen. Node beendet sich, sobald nichts mehr in der Schleife haengt -
+  // also nachdem geschrieben und geschlossen wurde.
+  process.exitCode = 0;
+  input.close();
+  process.stdin.unref();
 }
 
 input.on('line', (line) => {