@annexshow/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,100 @@
+# AnnexShow — MCP-Server
+
+MCP-Server (Model Context Protocol) für die [AnnexShow](https://annexshow.com)
+Agenten-API. Damit kann ein KI-Agent (Claude Desktop, Claude Code u. a.) direkt
+Diagramme, Präsentationen und Brandkits erzeugen — und dem Nutzer sofort einen
+teilbaren Link präsentieren. Leitmotiv: **Idee rein → Link raus.**
+
+Der Server läuft **client-seitig** (lokal beim Agenten) und ruft die AnnexShow
+REST-API auf. Er läuft **nicht** auf dem AnnexShow-Server.
+
+## Voraussetzungen
+
+1. **API-Token erzeugen:** im AnnexShow-Profil unter
+   *Einstellungen → API-Tokens* (Pro-Plan nötig). Der Token beginnt mit `ask_`.
+2. **Projekt anlegen:** Jede Visualisierung gehört zu einem Projekt. Lege es
+   einmalig in der App an und merke dir die `project_id`.
+3. **Node.js >= 18** (für das eingebaute `fetch`).
+
+## Verfügbare Tools
+
+| Tool | Zweck |
+|------|-------|
+| `annexshow_visualize` | Brief oder Knoten/Kanten → auto-layoutetes Canvas (+ optional Share-URL) |
+| `annexshow_create_synergy_diagram` | Radiales Synergie-Diagramm: Zentrum + N Items |
+| `annexshow_create_presentation` | Präsentation aus Stichpunkt-Folien |
+| `annexshow_create_brandkit` | Brandkit anlegen/füllen |
+| `annexshow_apply_brandkit` | Brandkit auf ein Canvas anwenden |
+| `annexshow_share_canvas` | Bestehendes Canvas teilen → Share-URL |
+
+## Setup für Claude Desktop
+
+In `claude_desktop_config.json` (macOS:
+`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "annexshow": {
+      "command": "npx",
+      "args": ["-y", "@annexshow/mcp-server"],
+      "env": {
+        "ANNEXSHOW_API_KEY": "ask_dein_token"
+      }
+    }
+  }
+}
+```
+
+## Setup für Claude Code
+
+```bash
+claude mcp add annexshow \
+  --env ANNEXSHOW_API_KEY=ask_dein_token \
+  -- npx -y @annexshow/mcp-server
+```
+
+Oder als JSON-Snippet in der MCP-Konfiguration:
+
+```json
+{
+  "mcpServers": {
+    "annexshow": {
+      "command": "npx",
+      "args": ["-y", "@annexshow/mcp-server"],
+      "env": {
+        "ANNEXSHOW_API_KEY": "ask_dein_token"
+      }
+    }
+  }
+}
+```
+
+## Umgebungsvariablen
+
+| Variable | Pflicht | Standard |
+|----------|---------|----------|
+| `ANNEXSHOW_API_KEY` | ja | — |
+| `ANNEXSHOW_BASE_URL` | nein | `https://annexshow.com/api/v1` |
+
+## Lokal testen
+
+```bash
+cd mcp
+npm install
+ANNEXSHOW_API_KEY=ask_dein_token node index.js
+```
+
+Der Server kommuniziert über stdio und gibt Statusmeldungen auf stderr aus.
+
+## Beispiel-Dialog
+
+> „Erstelle ein Synergie-Diagramm in Projekt 1 mit dem Zentrum *AnnexShow* und
+> den Punkten Python-SDK, PHP-SDK, MCP-Server. Gib mir den Link."
+
+Der Agent ruft `annexshow_create_synergy_diagram` auf und antwortet mit der
+fertigen Share-URL.
+
+## Lizenz
+
+MIT — ma-kom agentur UG (haftungsbeschränkt).

package/index.js

@@ -0,0 +1,374 @@
+#!/usr/bin/env node
+/**
+ * AnnexShow MCP-Server (stdio).
+ *
+ * Client-seitiger MCP-Server, der die AnnexShow Agenten-REST-API aufruft.
+ * Läuft NICHT auf dem Plesk-Server, sondern lokal beim Agenten/Client.
+ *
+ * Konfiguration über Umgebungsvariablen:
+ *   ANNEXSHOW_API_KEY   (erforderlich)  Agenten-Token (ask_...).
+ *   ANNEXSHOW_BASE_URL  (optional)      Standard: https://annexshow.com/api/v1
+ *
+ * Den Token erzeugst du im AnnexShow-Profil unter Einstellungen -> API-Tokens
+ * (Pro-Plan nötig).
+ */
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+const API_KEY = process.env.ANNEXSHOW_API_KEY;
+const BASE_URL = (
+  process.env.ANNEXSHOW_BASE_URL || "https://annexshow.com/api/v1"
+).replace(/\/+$/, "");
+
+if (!API_KEY) {
+  console.error(
+    "Fehler: ANNEXSHOW_API_KEY ist nicht gesetzt. Token im AnnexShow-Profil unter Einstellungen -> API-Tokens erzeugen (Pro-Plan nötig)."
+  );
+  process.exit(1);
+}
+
+/**
+ * Ruft einen Agenten-Endpunkt per POST auf und liefert den geparsten Body.
+ * Wirft bei einem Status außerhalb 2xx mit Statuscode + Message.
+ */
+async function apiPost(path, payload) {
+  // null/undefined-Felder herausfiltern, damit serverseitige Defaults greifen.
+  const clean = {};
+  for (const [key, value] of Object.entries(payload || {})) {
+    if (value !== null && value !== undefined) {
+      clean[key] = value;
+    }
+  }
+
+  let response;
+  try {
+    response = await fetch(`${BASE_URL}${path}`, {
+      method: "POST",
+      headers: {
+        "X-AnnexShow-Api-Key": API_KEY,
+        Accept: "application/json",
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(clean),
+    });
+  } catch (err) {
+    throw new Error(`Verbindungsfehler: ${err.message}`);
+  }
+
+  const raw = await response.text();
+  let body;
+  try {
+    body = raw ? JSON.parse(raw) : {};
+  } catch {
+    body = raw;
+  }
+
+  if (!response.ok) {
+    const message =
+      (body && typeof body === "object" && (body.message || body.error)) ||
+      (typeof body === "string" ? body : JSON.stringify(body));
+    throw new Error(`AnnexShow-API-Fehler ${response.status}: ${message}`);
+  }
+
+  return body;
+}
+
+/** Textantwort für ein MCP-Tool zusammenbauen. */
+function textResult(lines) {
+  return {
+    content: [{ type: "text", text: lines.filter(Boolean).join("\n") }],
+  };
+}
+
+/** Fehler als MCP-Tool-Fehlerantwort. */
+function errorResult(message) {
+  return {
+    isError: true,
+    content: [{ type: "text", text: message }],
+  };
+}
+
+// --------------------------------------------------------------------------
+// Tool-Definitionen
+// --------------------------------------------------------------------------
+const TOOLS = [
+  {
+    name: "annexshow_visualize",
+    description:
+      "Erzeugt aus einem Brief ODER aus Knoten/Kanten ein fertig auto-layoutetes Canvas und optional eine Share-URL. Entweder 'nodes' ODER 'brief' angeben (brief braucht serverseitig aktivierten KI-Pfad).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        project_id: { type: "integer", description: "ID des Projekts (muss zuerst existieren)." },
+        title: { type: "string", description: "Optionaler Titel des Canvas." },
+        brief: {
+          type: "string",
+          description: "Textuelle Beschreibung (alternativ zu nodes; braucht KI-Pfad).",
+        },
+        nodes: {
+          type: "array",
+          description: "Knoten-Liste.",
+          items: {
+            type: "object",
+            properties: {
+              id: { type: "string" },
+              label: { type: "string" },
+              color: { type: "string" },
+            },
+            required: ["id", "label"],
+          },
+        },
+        edges: {
+          type: "array",
+          description: "Kanten-Liste.",
+          items: {
+            type: "object",
+            properties: {
+              from: { type: "string" },
+              to: { type: "string" },
+              label: { type: "string" },
+            },
+            required: ["from", "to"],
+          },
+        },
+        layout: {
+          type: "string",
+          enum: ["tree", "radial", "grid"],
+          description: "Layout-Algorithmus.",
+        },
+        brandkit_id: { type: "integer", description: "Optionales Brandkit zum Anwenden." },
+        share: { type: "boolean", description: "Wenn true, wird eine Share-URL erzeugt." },
+        width: { type: "integer" },
+        height: { type: "integer" },
+      },
+      required: ["project_id"],
+    },
+    async run(args) {
+      const result = await apiPost("/agent/visualize", args);
+      return textResult([
+        `Canvas erstellt (${result.node_count} Knoten, ${result.edge_count} Kanten, Layout: ${result.layout}).`,
+        result.canvas?.id ? `Canvas-ID: ${result.canvas.id}` : null,
+        result.share_url ? `Share-URL: ${result.share_url}` : null,
+        result.quality?.message ? `Qualität: ${result.quality.message}` : null,
+      ]);
+    },
+  },
+  {
+    name: "annexshow_create_synergy_diagram",
+    description:
+      "Baut ein radiales Synergie-/Netzwerk-Diagramm: ein Zentrum + ein Knoten je Item, jeweils mit dem Zentrum verbunden. Idee rein -> Link raus.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        project_id: { type: "integer", description: "ID des Projekts." },
+        center: { type: "string", description: "Beschriftung des Zentrumsknotens." },
+        items: {
+          type: "array",
+          description: "Beschriftungen der äußeren Knoten.",
+          items: { type: "string" },
+        },
+        share: { type: "boolean", description: "Wenn true (Standard), wird eine Share-URL erzeugt." },
+        title: { type: "string" },
+        brandkit_id: { type: "integer" },
+      },
+      required: ["project_id", "center", "items"],
+    },
+    async run(args) {
+      const { project_id, center, items, share = true, title, brandkit_id } = args;
+      const nodes = [{ id: "center", label: center }];
+      const edges = [];
+      items.forEach((item, i) => {
+        const id = `item${i + 1}`;
+        nodes.push({ id, label: item });
+        edges.push({ from: "center", to: id });
+      });
+      const result = await apiPost("/agent/visualize", {
+        project_id,
+        title: title || center,
+        nodes,
+        edges,
+        layout: "radial",
+        brandkit_id,
+        share,
+      });
+      return textResult([
+        `Synergie-Diagramm erstellt (${result.node_count} Knoten, Layout: ${result.layout}).`,
+        result.canvas?.id ? `Canvas-ID: ${result.canvas.id}` : null,
+        result.share_url
+          ? `Dein Link: ${result.share_url}`
+          : "Hinweis: Kein Share-Link (share=false).",
+      ]);
+    },
+  },
+  {
+    name: "annexshow_create_presentation",
+    description:
+      "Erzeugt aus mehreren Stichpunkt-Folien eine Präsentation (ein Canvas je Folie).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        project_id: { type: "integer", description: "ID des Projekts." },
+        title: { type: "string", description: "Titel der Präsentation." },
+        slides: {
+          type: "array",
+          description: "Folien-Liste.",
+          items: {
+            type: "object",
+            properties: {
+              title: { type: "string" },
+              document: { type: "object", description: "Folien-Inhalt." },
+              width: { type: "integer" },
+              height: { type: "integer" },
+            },
+            required: ["title", "document"],
+          },
+        },
+        template_id: { type: "integer" },
+      },
+      required: ["project_id", "title", "slides"],
+    },
+    async run(args) {
+      const result = await apiPost("/agent/presentations/generate", args);
+      return textResult([
+        `Präsentation "${result.presentation_title}" erstellt (${result.count} Folien).`,
+        Array.isArray(result.canvases) && result.canvases.length
+          ? `Canvas-IDs: ${result.canvases.map((c) => c.id ?? c).join(", ")}`
+          : null,
+      ]);
+    },
+  },
+  {
+    name: "annexshow_create_brandkit",
+    description:
+      "Legt ein Brandkit an oder füllt es (Name, Firma, Slogan, Farben, Fonts, Logos). Liefert Vollständigkeit (0-100) und fehlende Felder zurück.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "Name des Brandkits." },
+        company_name: { type: "string" },
+        slogan: { type: "string" },
+        offer_description: { type: "string" },
+        colors: {
+          type: "object",
+          properties: {
+            primary: { type: "string" },
+            secondary: { type: "string" },
+            signal: { type: "string" },
+          },
+        },
+        fonts: {
+          type: "object",
+          properties: {
+            heading: { type: "string" },
+            body: { type: "string" },
+          },
+        },
+        logos: { type: "array", items: { type: "string" } },
+      },
+      required: ["name"],
+    },
+    async run(args) {
+      const result = await apiPost("/agent/brandkits", args);
+      const missing = Array.isArray(result.missing) ? result.missing : [];
+      return textResult([
+        `Brandkit angelegt (Vollständigkeit: ${result.completion}%).`,
+        result.brandkit?.id ? `Brandkit-ID: ${result.brandkit.id}` : null,
+        missing.length ? `Es fehlt noch: ${missing.join(", ")}` : "Alle Felder vorhanden.",
+        result.message || null,
+      ]);
+    },
+  },
+  {
+    name: "annexshow_apply_brandkit",
+    description: "Wendet ein Brandkit auf ein bestehendes Canvas an.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        canvas_id: { type: "integer", description: "ID des Canvas." },
+        brandkit_id: { type: "integer", description: "ID des Brandkits." },
+      },
+      required: ["canvas_id", "brandkit_id"],
+    },
+    async run(args) {
+      const result = await apiPost("/agent/brandkits/apply", args);
+      return textResult([
+        "Brandkit auf Canvas angewendet.",
+        result.canvas?.id ? `Canvas-ID: ${result.canvas.id}` : null,
+      ]);
+    },
+  },
+  {
+    name: "annexshow_share_canvas",
+    description:
+      "Teilt ein bestehendes Canvas und liefert eine öffentliche Share-URL (Formate: html, svg, pdf, png).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        canvas_id: { type: "integer", description: "ID des zu teilenden Canvas." },
+        title: { type: "string" },
+        description: { type: "string" },
+        allowed_formats: {
+          type: "array",
+          items: { type: "string", enum: ["html", "svg", "pdf", "png"] },
+        },
+        expires_at: { type: "string", description: "Ablaufdatum (ISO-8601), optional." },
+      },
+      required: ["canvas_id"],
+    },
+    async run(args) {
+      const { canvas_id, ...body } = args;
+      const result = await apiPost(`/agent/canvases/${canvas_id}/share`, body);
+      return textResult([
+        "Canvas geteilt.",
+        result.url ? `Dein Link: ${result.url}` : null,
+        Array.isArray(result.formats) ? `Formate: ${result.formats.join(", ")}` : null,
+      ]);
+    },
+  },
+];
+
+const TOOL_MAP = new Map(TOOLS.map((tool) => [tool.name, tool]));
+
+// --------------------------------------------------------------------------
+// Server-Setup
+// --------------------------------------------------------------------------
+const server = new Server(
+  { name: "annexshow-mcp-server", version: "0.1.0" },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: TOOLS.map(({ name, description, inputSchema }) => ({
+    name,
+    description,
+    inputSchema,
+  })),
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const tool = TOOL_MAP.get(request.params.name);
+  if (!tool) {
+    return errorResult(`Unbekanntes Tool: ${request.params.name}`);
+  }
+  try {
+    return await tool.run(request.params.arguments || {});
+  } catch (err) {
+    return errorResult(err.message);
+  }
+});
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("AnnexShow MCP-Server läuft (stdio).");
+}
+
+main().catch((err) => {
+  console.error("AnnexShow MCP-Server konnte nicht starten:", err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@annexshow/mcp-server",
+  "version": "0.1.0",
+  "description": "MCP-Server für die AnnexShow Agenten-API — Idee rein, Link raus.",
+  "type": "module",
+  "license": "MIT",
+  "author": "ma-kom agentur UG <mail@ma-kom.de>",
+  "homepage": "https://annexshow.com",
+  "bin": {
+    "annexshow-mcp": "index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  }
+}