@conciso/design-system-mcp 0.0.0-bootstrap.0

package/src/instructions.mjs

@@ -0,0 +1,38 @@
+// Server-`instructions` aus ADR-0012: Regeln des Design Systems, die die KI eines Consumers
+// erreichen, bevor sie überhaupt ein Werkzeug aufruft (`initialize`-Antwort, `tmcp`s
+// `ServerOptions.instructions`). Eigene deutsche Regeln zuerst, danach unverändert
+// `STORYBOOK_MCP_INSTRUCTIONS` aus `@storybook/mcp` — die Anleitung zu docs-list/docs-show/
+// docs-show-story bleibt bei der Bibliothek, die die Werkzeuge auch definiert.
+import { STORYBOOK_MCP_INSTRUCTIONS } from '@storybook/mcp';
+
+/**
+ * Storybook-ID der Einrichtungsseite (`storybook-angular/src/docs/grundlagen/einrichtung.mdx`,
+ * `<Meta title="Grundlagen/Einrichtung" name="Übersicht" />`). Als Konstante exportiert, statt
+ * die ID nur im Fließtext unten zu verstecken, damit ein Test sie referenzieren kann, ohne sie
+ * ein zweites Mal abzutippen.
+ */
+export const EINRICHTUNG_DOC_ID = 'grundlagen-einrichtung--übersicht';
+
+const OWN_INSTRUCTIONS = `## Conciso Design System
+
+Feste Regeln für die Angular-Lib „@conciso/design-system-angular“:
+
+1. CSS-Schicht und Fonts global einbinden, nicht pro Komponente. Ohne diesen Schritt bleiben die Wrapper-Komponenten ungestylt.
+2. Kein eigenes CSS für DS-Komponenten schreiben und keine CSS-Klassen erfinden.
+3. Nur Inputs und Outputs verwenden, die docs-show für die jeweilige Komponente liefert. Vorher nachsehen, nie raten.
+4. Bei Fragen zur Einrichtung docs-show mit der ID „${EINRICHTUNG_DOC_ID}“ aufrufen (Storybook-Seite „Einrichtung“).`;
+
+/**
+ * Baut den vollständigen `instructions`-Text: eigene Regeln, optional die Versions-Notiz aus
+ * `checkVersion`, danach die Storybook-eigenen Anweisungen.
+ * @param {string | null} [versionNote] `instructionsNote` aus `checkVersion` (src/version-check.mjs).
+ * @returns {string}
+ */
+export function buildInstructions(versionNote) {
+  const sections = [OWN_INSTRUCTIONS];
+  if (versionNote) {
+    sections.push(versionNote);
+  }
+  sections.push(STORYBOOK_MCP_INSTRUCTIONS);
+  return sections.join('\n\n');
+}

package/src/server.mjs

@@ -0,0 +1,111 @@
+// MCP-Server für Consumer (ADR-0012): baut die drei Storybook-Doku-Werkzeuge von
+// @storybook/mcp auf einem tmcp-Server mit stdio-Transport auf. Liest ausschließlich aus dem
+// mitgelieferten Snapshot (`snapshot/manifests`, `snapshot/services`) — kein Netzzugriff, kein
+// Port. Wichtige Invariante: stdout gehört exklusiv dem JSON-RPC-Protokoll, jede Diagnose geht
+// auf stderr.
+import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { dirname, join, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { ValibotJsonSchemaAdapter } from '@tmcp/adapter-valibot';
+import { StdioTransport } from '@tmcp/transport-stdio';
+import {
+  addGetDocumentationTool,
+  addGetStoryDocumentationTool,
+  addListAllDocumentationTool,
+} from '@storybook/mcp';
+import { McpServer } from 'tmcp';
+
+import { buildInstructions } from './instructions.mjs';
+import { checkVersion, resolveInstalledVersion } from './version-check.mjs';
+
+const require = createRequire(import.meta.url);
+// createRequire statt `import … with { type: 'json' }`: Import-Attribute für JSON brauchen
+// neuere Node-Minor-Versionen als unser deklariertes `engines.node: >=20` garantiert; require()
+// löst JSON seit jeher auf und funktioniert auf jeder Node-20-Version.
+const pkg = require('../package.json');
+
+const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+export const SNAPSHOT_ROOT = join(PACKAGE_ROOT, 'snapshot');
+
+/**
+ * @storybook/mcp ruft den manifestProvider mit Pfaden relativ zur Storybook-Wurzel auf, z. B.
+ * „./manifests/components.json“ oder „./services/core/docgen/<id>.json“. `request` bleibt in
+ * stdio immer `undefined` — es gibt kein HTTP-Request-Objekt; wir ignorieren es bewusst.
+ *
+ * ROOT CAUSE: @storybook/mcp löst `$ref`-Pfade aus dem Manifest
+ * URL-artig auf (`new URL(filePath, base).pathname`, siehe `parseManifestRef` in
+ * @storybook/mcp/dist/index.js) und übergibt dem manifestProvider deshalb einen
+ * PROZENTKODIERTEN Pfad, z. B. „./services/addon-docs/mdx/grundlagen-einrichtung--%C3%BCbersicht.json“
+ * für die Datei „…/grundlagen-einrichtung--übersicht.json“ auf der Platte — betrifft jede docs-id
+ * mit Nicht-ASCII-Zeichen (alle „…--übersicht“-MDX-Seiten). Über HTTP dekodiert der Server das
+ * automatisch; unser Dateisystem-Provider muss es hier selbst tun.
+ *
+ * Verteidigung in der Tiefe: `manifestPath` kommt aus `$ref`-Werten im Snapshot, nicht direkt von
+ * Nutzereingaben — trotzdem lehnt der Provider jeden Pfad ab, dessen Auflösung `SNAPSHOT_ROOT`
+ * verlässt (z. B. per `../..`), statt ihn stillschweigend zu folgen. Das Dekodieren läuft VOR
+ * dieser Guard-Prüfung, sonst würde eine kodierte Traversal (`..%2F..%2F…`) die Prüfung als
+ * harmlose Zeichenfolge passieren und erst danach zur echten Traversal werden.
+ * @param {unknown} _request
+ * @param {string} manifestPath
+ * @returns {Promise<string>}
+ */
+export async function manifestProvider(_request, manifestPath) {
+  const relative = manifestPath.replace(/^\.\//, '');
+  let decoded;
+  try {
+    decoded = decodeURIComponent(relative);
+  } catch {
+    throw new Error(`Pfad ungültig kodiert (keine valide Prozentkodierung): „${manifestPath}“.`);
+  }
+  const absolute = join(SNAPSHOT_ROOT, decoded);
+  if (absolute !== SNAPSHOT_ROOT && !absolute.startsWith(SNAPSHOT_ROOT + sep)) {
+    throw new Error(`Pfad außerhalb des Snapshots abgelehnt: „${manifestPath}“.`);
+  }
+  return readFile(absolute, 'utf8');
+}
+
+/**
+ * Baut den tmcp-Server mit den drei registrierten Werkzeugen, aber startet noch keinen Transport.
+ * @param {{ cwd?: string }} [options] `cwd`: Arbeitsverzeichnis, ab dem die Versionsprüfung die
+ *   installierte Angular-Lib auflöst (Default `process.cwd()`) — parametrisiert für Tests, damit
+ *   sie kein reales Consumer-`node_modules` brauchen.
+ */
+export async function createServer({ cwd = process.cwd() } = {}) {
+  const installedVersion = resolveInstalledVersion(cwd);
+  const { instructionsNote, stderrNote } = checkVersion(pkg.version, installedVersion);
+  if (stderrNote) {
+    console.error(stderrNote);
+  }
+
+  const server = new McpServer(
+    {
+      name: pkg.name,
+      version: pkg.version,
+      description:
+        'Dokumentierte Inputs/Outputs der Angular-Lib des Conciso Design System, aus einem ' +
+        'Storybook-Snapshot, kein Netzzugriff.',
+    },
+    {
+      adapter: new ValibotJsonSchemaAdapter(),
+      capabilities: { tools: { listChanged: true } },
+      instructions: buildInstructions(instructionsNote),
+    },
+  ).withContext();
+
+  await addListAllDocumentationTool(server);
+  await addGetDocumentationTool(server);
+  await addGetStoryDocumentationTool(server);
+
+  return server;
+}
+
+/** Baut den Server und hängt ihn an stdio. Gibt den Transport zurück (für Tests/Shutdown). */
+export async function startServer() {
+  const server = await createServer();
+  const transport = new StdioTransport(server);
+  transport.listen({ manifestProvider });
+  console.error(`[cds-mcp] bereit (stdio), Snapshot: ${SNAPSHOT_ROOT}`);
+  return transport;
+}

package/src/version-check.mjs

@@ -0,0 +1,80 @@
+// Versionsprüfung aus ADR-0012 (Lockstep): Der MCP-Server liefert einen Snapshot, der zu genau
+// einer Version der Angular-Lib passt. Weicht die installierte Version ab, warnt der Server
+// (in den `instructions` und auf stderr) statt abzubrechen — ein MCP-Server, der die Verbindung
+// verweigert, ist für die KI unsichtbar, eine falsche Doku-Erwartung dagegen sichtbar und
+// korrigierbar.
+//
+// `checkVersion` ist bewusst eine reine Funktion (zwei Strings/`null` rein, ein Objekt raus):
+// Unit-Tests brauchen dafür keine Fixtures, keinen `node_modules`-Baum und keinen Kindprozess.
+// Das Auflösen der installierten Version (Dateisystemzugriff) steht getrennt in
+// `resolveInstalledVersion`.
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+
+/**
+ * Version, die das Repo laut ADR-0010 („versionsfreies Repo“, siehe
+ * scripts/release/stamp-version.mjs) dauerhaft trägt, bis der Publish-Job die echte Version
+ * einstempelt. Vor dem ersten Release — und bei jedem lokalen `npm test` aus einem Checkout, der
+ * nie gestempelt wurde — steht sie in JEDEM Paket, auch in einer frisch installierten
+ * Angular-Lib aus demselben Checkout. Ein Vergleich dagegen würde in der Entwicklung immer
+ * "unterschiedlich" melden, obwohl beide Seiten aus demselben, noch nicht veröffentlichten Stand
+ * stammen — eine strukturell falsche Warnung, keine echte Abweichung. Deshalb wird der Vergleich
+ * für diesen einen Wert übersprungen, nicht verschärft.
+ */
+export const PLACEHOLDER_VERSION = '0.0.0';
+
+/**
+ * Reine Versionsprüfung ohne Dateisystemzugriff.
+ * @param {string} ownVersion Version aus mcp-server/package.json (`pkg.version`).
+ * @param {string | null} installedVersion Version der installierten Angular-Lib, oder `null`,
+ *   wenn sie nicht auflösbar ist (nicht installiert, kein `package.json`, kaputtes JSON).
+ * @returns {{ instructionsNote: string | null, stderrNote: string | null }}
+ */
+export function checkVersion(ownVersion, installedVersion) {
+  if (ownVersion === PLACEHOLDER_VERSION) {
+    return {
+      instructionsNote: null,
+      stderrNote:
+        '[cds-mcp] Entwicklungsmodus: eigene Version ist der Platzhalter „0.0.0“, Versionsprüfung übersprungen.',
+    };
+  }
+
+  if (installedVersion === null) {
+    return {
+      instructionsNote:
+        `Hinweis: „@conciso/design-system-angular“ ist im Projekt nicht installiert. ` +
+        `Dieser Snapshot gilt für Version ${ownVersion}.`,
+      stderrNote: null,
+    };
+  }
+
+  if (installedVersion === ownVersion) {
+    return { instructionsNote: null, stderrNote: null };
+  }
+
+  const note =
+    `Warnung: Dieser Snapshot gehört zu Version ${ownVersion} von „@conciso/design-system-angular“, ` +
+    `installiert ist Version ${installedVersion}. Dokumentierte Inputs und Outputs können abweichen.`;
+  return { instructionsNote: note, stderrNote: `[cds-mcp] ${note}` };
+}
+
+/**
+ * Löst die Version der installierten Angular-Lib **vom Arbeitsverzeichnis des Consumers aus**
+ * auf, nicht vom Installationsort dieses Pakets (`import.meta.url` wäre hier falsch: `cds-mcp`
+ * liegt in `node_modules/@conciso/design-system-mcp/…`, die zu prüfende Lib aber im
+ * `node_modules` des Consumer-Projekts). `createRequire(join(cwd, 'noop.js'))` erzeugt einen
+ * `require`, dessen Modulauflösung an einem Pfad IM Consumer-Verzeichnis beginnt, ohne dass
+ * dieser Pfad existieren muss — Node löst `require.resolve` immer relativ zum Verzeichnis eines
+ * (auch fiktiven) Moduls auf, nie zur Datei selbst.
+ * @param {string} [cwd] Default: `process.cwd()`, parametrisiert für Tests.
+ * @returns {string | null}
+ */
+export function resolveInstalledVersion(cwd = process.cwd()) {
+  try {
+    const require = createRequire(join(cwd, 'noop.js'));
+    const installedPkg = require('@conciso/design-system-angular/package.json');
+    return installedPkg.version;
+  } catch {
+    return null;
+  }
+}