@markdy/mcp-server 0.8.25

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hoang Yell (https://hoangyell.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,58 @@
+# @markdy/mcp-server
+
+Official **Model Context Protocol (MCP)** server for Markdy — the animated diagram-as-code DSL.
+
+Equip Claude Desktop, Cursor, Google Antigravity, and autonomous AI agents with tools to parse, validate, transpile, explain, and craft animated Markdy architecture diagrams.
+
+---
+
+## 🛠️ Provided Tools
+
+1. `validate_markdy_code`
+   - Validates syntax and executes Well-Architected governance rules (layer boundaries, cycle detection, gateway checks).
+   - Generates structured diagnostic hints and AI repair prompts.
+
+2. `transpile_to_markdy`
+   - Converts Mermaid, Docker Compose, Kubernetes manifests, or Terraform state into animated MarkdyScript scenes.
+
+3. `explain_architecture`
+   - Parses a MarkdyScript AST to output structural topology summaries, component role counts, and governance health.
+
+4. `generate_markdy_prompt`
+   - Generates optimal system prompt constraints and instructions for LLMs.
+
+---
+
+## 🚀 Configuration
+
+### Claude Desktop (`claude_desktop_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "markdy": {
+      "command": "npx",
+      "args": ["-y", "@markdy/mcp-server"]
+    }
+  }
+}
+```
+
+### Cursor (`.cursor/mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "markdy": {
+      "command": "npx",
+      "args": ["-y", "@markdy/mcp-server"]
+    }
+  }
+}
+```
+
+---
+
+## License
+
+MIT © [Hoang Yell](https://hoangyell.com)

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+
+/**
+ * packages/mcp-server/src/tools.ts
+ * MCP Tool definitions and execution handlers for Markdy.
+ */
+interface ToolResult {
+    [x: string]: unknown;
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}
+declare function handleValidateMarkdy(code: string, checkArchitecture?: boolean): ToolResult;
+declare function handleTranspileToMarkdy(source: string, format: "mermaid" | "docker-compose" | "k8s" | "terraform", title?: string): ToolResult;
+declare function handleExplainArchitecture(code: string): ToolResult;
+declare function handleGenerateMarkdyPrompt(userGoal: string): ToolResult;
+
+/**
+ * packages/mcp-server/src/index.ts
+ * MCP Server for Markdy Diagram Engine.
+ */
+
+declare function createMarkdyMcpServer(): Server;
+declare function startMcpServer(): Promise<void>;
+
+export { createMarkdyMcpServer, handleExplainArchitecture, handleGenerateMarkdyPrompt, handleTranspileToMarkdy, handleValidateMarkdy, startMcpServer };

package/dist/index.js

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+
+// src/tools.ts
+import {
+  parse,
+  validateArchitecture,
+  analyzeAndBuildRepairPrompt
+} from "@markdy/core";
+import {
+  transpileMermaidToMarkdy,
+  transpileDockerComposeToMarkdy,
+  transpileKubernetesManifestsToMarkdy,
+  transpileTerraformStateToMarkdy
+} from "@markdy/compat";
+function handleValidateMarkdy(code, checkArchitecture = true) {
+  try {
+    const ast = parse(code);
+    const diagnostics = ast.diagnostics ?? [];
+    const archViolations = checkArchitecture ? validateArchitecture(ast) : [];
+    const lines = [];
+    lines.push(`\u2705 Markdy Syntax Valid: ${Object.keys(ast.nodes).length} nodes, ${ast.edges.length} static edges, ${ast.beats.length} beats.`);
+    if (diagnostics.length > 0) {
+      lines.push("\n\u26A0\uFE0F Diagnostics & Suggestions:");
+      for (const d of diagnostics) {
+        lines.push(`- line ${d.line}: [${d.severity}] ${d.message}`);
+      }
+    }
+    if (archViolations.length > 0) {
+      lines.push("\n\u{1F6E1}\uFE0F Architecture Rule Violations:");
+      for (const v of archViolations) {
+        lines.push(`- [${v.severity.toUpperCase()}] ${v.ruleName} (line ${v.line ?? 1}): ${v.message}`);
+      }
+    }
+    return {
+      content: [{ type: "text", text: lines.join("\n") }]
+    };
+  } catch (error) {
+    const repairPrompt = analyzeAndBuildRepairPrompt(code);
+    return {
+      isError: true,
+      content: [
+        {
+          type: "text",
+          text: `\u274C Parse Error: ${error.message}
+
+Suggested AI Healing Prompt:
+${repairPrompt}`
+        }
+      ]
+    };
+  }
+}
+function handleTranspileToMarkdy(source, format, title = "Imported Scene") {
+  try {
+    let markdyCode = "";
+    switch (format) {
+      case "mermaid":
+        markdyCode = transpileMermaidToMarkdy(source, title).code;
+        break;
+      case "docker-compose":
+        markdyCode = transpileDockerComposeToMarkdy(source, title);
+        break;
+      case "k8s":
+        markdyCode = transpileKubernetesManifestsToMarkdy(source, title);
+        break;
+      case "terraform":
+        markdyCode = transpileTerraformStateToMarkdy(source, title);
+        break;
+      default:
+        throw new Error(`Unsupported ingestion format: ${format}`);
+    }
+    parse(markdyCode);
+    return {
+      content: [
+        {
+          type: "text",
+          text: markdyCode
+        }
+      ]
+    };
+  } catch (error) {
+    return {
+      isError: true,
+      content: [{ type: "text", text: `Transpilation failed: ${error.message}` }]
+    };
+  }
+}
+function handleExplainArchitecture(code) {
+  try {
+    const ast = parse(code);
+    const nodeCount = Object.keys(ast.nodes).length;
+    const edgeCount = ast.edges.length;
+    const groupCount = Object.keys(ast.groups).length;
+    const beatsCount = ast.beats.length;
+    const rolesSummary = /* @__PURE__ */ new Map();
+    for (const n of Object.values(ast.nodes)) {
+      rolesSummary.set(n.kind, (rolesSummary.get(n.kind) ?? 0) + 1);
+    }
+    const roleBreakdown = Array.from(rolesSummary.entries()).map(([k, count]) => `  - ${k}: ${count}`).join("\n");
+    const violations = validateArchitecture(ast);
+    const explanation = [
+      `### Architecture Overview: ${ast.meta.title || "Untitled Diagram"}`,
+      `- **Layout:** ${ast.meta.direction || "LR"}`,
+      `- **Theme:** ${ast.meta.theme || "paper"}`,
+      `- **Components:** ${nodeCount} nodes across ${groupCount} groups`,
+      `- **Interactions:** ${edgeCount} static connections, ${beatsCount} dynamic beats`,
+      "",
+      `#### Component Kinds:`,
+      roleBreakdown,
+      "",
+      `#### Governance & Well-Architected Health:`,
+      violations.length === 0 ? "\u2705 No architectural violations detected across Well-Architected rule presets." : `\u26A0\uFE0F Detected ${violations.length} governance issue(s):
+` + violations.map((v) => `- [${v.ruleName}] ${v.message}`).join("\n")
+    ].join("\n");
+    return {
+      content: [{ type: "text", text: explanation }]
+    };
+  } catch (error) {
+    return {
+      isError: true,
+      content: [{ type: "text", text: `Explain failed: ${error.message}` }]
+    };
+  }
+}
+function handleGenerateMarkdyPrompt(userGoal) {
+  const prompt = [
+    `You are an expert system architecture designer specializing in MarkdyScript DSL.`,
+    `Goal: ${userGoal}`,
+    ``,
+    `### Instructions:`,
+    `1. Use MarkdyScript 0.8+ syntax. Start with: \`scene "<Title>" theme=paper layout=LR\``,
+    `2. Define nodes using semantic types (e.g. \`browser client\`, \`gateway api_gw\`, \`service auth_svc\`, \`database pg_db\`, \`cache redis\`, \`queue kafka\`).`,
+    `3. Organize components in \`group <id> "<Label>": <members...>\` boundaries.`,
+    `4. Define animated traffic steps in \`beat <id> "<Description>":\``,
+    `5. Animate flows with \`show $nodes\`, \`client -> api_gw "request"\`, and \`api_gw -> auth_svc "verify"\`.`,
+    `6. Keep syntax clean and output ONLY valid MarkdyScript.`
+  ].join("\n");
+  return {
+    content: [{ type: "text", text: prompt }]
+  };
+}
+
+// src/index.ts
+function createMarkdyMcpServer() {
+  const server = new Server(
+    {
+      name: "markdy-mcp-server",
+      version: "0.8.20"
+    },
+    {
+      capabilities: {
+        tools: {}
+      }
+    }
+  );
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+      tools: [
+        {
+          name: "validate_markdy_code",
+          description: "Validates MarkdyScript syntax, detects architectural rule violations, and outputs diagnostics and healing suggestions.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              code: { type: "string", description: "The MarkdyScript diagram code to validate." },
+              checkArchitecture: { type: "boolean", description: "Whether to run Well-Architected governance rule checks." }
+            },
+            required: ["code"]
+          }
+        },
+        {
+          name: "transpile_to_markdy",
+          description: "Converts external infrastructure or diagram code (Mermaid, Docker Compose, Kubernetes manifests, or Terraform state) into animated MarkdyScript scenes.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              source: { type: "string", description: "The source code or content to transpile." },
+              format: {
+                type: "string",
+                enum: ["mermaid", "docker-compose", "k8s", "terraform"],
+                description: "The source format."
+              },
+              title: { type: "string", description: "Optional title for the resulting scene." }
+            },
+            required: ["source", "format"]
+          }
+        },
+        {
+          name: "explain_architecture",
+          description: "Analyzes a MarkdyScript AST and generates a structured summary of components, topology, and governance health.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              code: { type: "string", description: "The MarkdyScript code to analyze." }
+            },
+            required: ["code"]
+          }
+        },
+        {
+          name: "generate_markdy_prompt",
+          description: "Generates optimal LLM system prompts and grammar constraints for building high-quality Markdy architecture animations.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              userGoal: { type: "string", description: "The architecture or flow description the user wants to visualize." }
+            },
+            required: ["userGoal"]
+          }
+        }
+      ]
+    };
+  });
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const safeArgs = args || {};
+    switch (name) {
+      case "validate_markdy_code":
+        return handleValidateMarkdy(
+          String(safeArgs.code ?? ""),
+          safeArgs.checkArchitecture !== false
+        );
+      case "transpile_to_markdy":
+        return handleTranspileToMarkdy(
+          String(safeArgs.source ?? ""),
+          safeArgs.format,
+          safeArgs.title ? String(safeArgs.title) : void 0
+        );
+      case "explain_architecture":
+        return handleExplainArchitecture(String(safeArgs.code ?? ""));
+      case "generate_markdy_prompt":
+        return handleGenerateMarkdyPrompt(String(safeArgs.userGoal ?? ""));
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+  });
+  return server;
+}
+async function startMcpServer() {
+  const server = createMarkdyMcpServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+if (process.argv[1] && process.argv[1].endsWith("index.js")) {
+  startMcpServer().catch((err) => {
+    console.error("Fatal MCP Server Error:", err);
+    process.exit(1);
+  });
+}
+export {
+  createMarkdyMcpServer,
+  handleExplainArchitecture,
+  handleGenerateMarkdyPrompt,
+  handleTranspileToMarkdy,
+  handleValidateMarkdy,
+  startMcpServer
+};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@markdy/mcp-server",
+  "version": "0.8.25",
+  "description": "Model Context Protocol server for Markdy diagram validation, transpilation, and generation.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "markdy-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.6.1",
+    "@markdy/compat": "0.8.25",
+    "@markdy/core": "0.8.25"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.5",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.7"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}