@markdy/mcp-server 1.0.24 → 1.0.26

package/README.md

@@ -1,35 +1,48 @@
 # @markdy/mcp-server
 
-Official **Model Context Protocol (MCP)** server for Markdy — the animated diagram-as-code DSL.
+> 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.
+Equip **Claude Desktop**, **Cursor**, **Google Antigravity**, **Windsurf**, and autonomous AI agents with tools to parse, validate, transpile, explain, and craft animated Markdy architecture diagrams.
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/HoangYell/markdy-com/main/website/public/images/markdy-ai-agent-workflow.webp" alt="Markdy AI Agent & MCP Integration" width="900" />
+  <a href="https://markdy.com/agent/">
+    <img src="https://raw.githubusercontent.com/HoangYell/markdy-com/main/website/public/images/markdy-ai-agent-workflow.webp" alt="Markdy AI Agent & MCP Integration" width="900" />
+  </a>
+</p>
+<p align="center">
+  <a href="https://markdy.com/playground/">
+    <img src="https://raw.githubusercontent.com/HoangYell/markdy-com/main/website/public/images/scene-oauth-pkce-sequence.webp" alt="Markdy AI-Generated OAuth Sequence Preview" width="900" />
+  </a>
 </p>
 
 ---
 
-## 🛠️ Provided Tools
+## ⚡ Key Capabilities
 
-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.
+| Capability | Description |
+| :--- | :--- |
+| **🛠️ Tools** | Syntax validation with AI self-healing diagnostics, multi-format transpilation (Mermaid, Docker Compose, Kubernetes, Terraform, Draw.io), topology breakdown, and template retrieval. |
+| **📦 Resources** | On-demand access to the canonical specification (`markdy://spec/agent-reference`), Well-Architected governance rules (`markdy://governance/rules`), and curated architecture templates (`markdy://templates/catalog`). |
+| **💬 Prompts** | Pre-engineered prompt workflows (`create_architecture_diagram`, `audit_architecture`, `transpile_architecture`) that guide agents through structured diagram design. |
 
-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.
+## 🚀 Client Configuration
 
-4. `generate_markdy_prompt`
-   - Generates optimal system prompt constraints and instructions for LLMs.
+### 1. Claude Desktop (`claude_desktop_config.json`)
 
----
-
-## 🚀 Configuration
+```json
+{
+  "mcpServers": {
+    "markdy": {
+      "command": "npx",
+      "args": ["-y", "@markdy/mcp-server"]
+    }
+  }
+}
+```
 
-### Claude Desktop (`claude_desktop_config.json`)
+### 2. Cursor (`.cursor/mcp.json`)
 
 ```json
 {
@@ -42,7 +55,7 @@ Equip Claude Desktop, Cursor, Google Antigravity, and autonomous AI agents with
 }
 ```
 
-### Cursor (`.cursor/mcp.json`)
+### 3. Google Antigravity (`~/.gemini/antigravity/mcp_config.json`)
 
 ```json
 {
@@ -55,7 +68,7 @@ Equip Claude Desktop, Cursor, Google Antigravity, and autonomous AI agents with
 }
 ```
 
-### Google Antigravity (`~/.gemini/antigravity/mcp_config.json`)
+### 4. Windsurf (`~/.codeium/windsurf/mcp_config.json`)
 
 ```json
 {
@@ -68,9 +81,123 @@ Equip Claude Desktop, Cursor, Google Antigravity, and autonomous AI agents with
 }
 ```
 
+### 5. Zed (`settings.json`)
+
+```json
+{
+  "context_servers": {
+    "markdy": {
+      "command": {
+        "path": "npx",
+        "args": ["-y", "@markdy/mcp-server"]
+      }
+    }
+  }
+}
+```
+
+---
+
+## 🛠️ Provided Tools
+
+### 1. `validate_markdy_code`
+Validates MarkdyScript syntax and verifies Well-Architected governance rules (layer boundaries, cycle detection, ingress gateway enforcement). Returns structured diagnostic suggestions and an AI healing prompt if parse errors occur.
+
+#### Parameters
+| Parameter | Type | Presence | Default | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `code` | `string` | **Required** | *None* | The complete MarkdyScript diagram code starting with `scene`. |
+| `checkArchitecture` | `boolean` | Optional | `true` | When `true`, runs Well-Architected governance lint rules. |
+
+#### Example Request
+```json
+{
+  "name": "validate_markdy_code",
+  "arguments": {
+    "code": "scene theme=paper layout=LR\nservice API\ndatabase DB\nbeat main:\n  API -> DB \"query\"\n  API <- DB \"200 OK\""
+  }
+}
+```
+
+---
+
+### 2. `transpile_to_markdy`
+Converts existing infrastructure definitions or diagrams into animated MarkdyScript scenes.
+
+#### Parameters
+| Parameter | Type | Presence | Allowed Values | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `source` | `string` | **Required** | *Raw code / markup* | Source code to transpile. |
+| `format` | `string` | **Required** | `mermaid`, `docker-compose`, `k8s`, `terraform`, `drawio` | Format of the input source. |
+| `title` | `string` | Optional | `"Imported Scene"` | Scene title rendered in the output diagram header. |
+
+#### Example Request
+```json
+{
+  "name": "transpile_to_markdy",
+  "arguments": {
+    "format": "docker-compose",
+    "source": "version: '3'\nservices:\n  web:\n    image: nginx\n  api:\n    image: node-app",
+    "title": "Container Stack"
+  }
+}
+```
+
+---
+
+### 3. `explain_architecture`
+Parses a MarkdyScript AST to output structural topology summaries, component role counts, and governance health metrics.
+
+#### Parameters
+| Parameter | Type | Presence | Description |
+| :--- | :--- | :--- | :--- |
+| `code` | `string` | **Required** | The MarkdyScript diagram code to inspect. |
+
+---
+
+### 4. `generate_markdy_prompt`
+Generates optimal, hallucination-resistant LLM system prompts and grammar constraints tailored to a specific user goal.
+
+#### Parameters
+| Parameter | Type | Presence | Description |
+| :--- | :--- | :--- | :--- |
+| `userGoal` | `string` | **Required** | Description of the system or workflow to visualize. |
+
+---
+
+### 5. `get_architecture_catalog`
+Returns production-grade golden architecture templates (Microservices, RAG, Kafka Event-Driven, K8s Ingress, GitOps CI/CD, OAuth2, HA Multi-Region, Flowcharts) with full runnable MarkdyScript source code.
+
+#### Parameters
+| Parameter | Type | Presence | Description |
+| :--- | :--- | :--- | :--- |
+| `filterCategory` | `string` | Optional | Filter string by category name (e.g. `'AI'`, `'Cloud'`, `'Security'`). |
+
+---
+
+## 📦 Provided Resources
+
+AI agents can directly read these canonical context URIs via MCP:
+
+| URI | MIME Type | Description |
+| :--- | :--- | :--- |
+| `markdy://spec/agent-reference` | `text/markdown` | Canonical MarkdyScript specification, node kinds, and cycle-prevention rules. |
+| `markdy://templates/catalog` | `application/json` | Curated JSON catalog of all 8 golden architecture templates. |
+| `markdy://governance/rules` | `application/json` | Well-Architected governance rules and lint presets. |
+
+---
+
+## 💬 Provided Prompts
+
+| Prompt | Arguments | Purpose |
+| :--- | :--- | :--- |
+| `create_architecture_diagram` | `userGoal` (req), `theme` (opt), `layout` (opt) | Guided workflow to design an animated Markdy architecture diagram from scratch. |
+| `audit_architecture` | `code` (req) | Audits a MarkdyScript diagram against Well-Architected governance and cycle-safety rules. |
+| `transpile_architecture` | `source` (req), `format` (req) | Guides migration of legacy diagrams or infra into animated MarkdyScript. |
+
 ---
 
-## 📖 Documentation & References
+## 📖 Canonical References
 
 - **Authoritative AI Agent Guide**: <https://markdy.com/AGENT.md>
 - **Human Documentation**: <https://markdy.com/docs/>

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 
 /**
  * packages/mcp-server/src/tools.ts
- * MCP Tool definitions and execution handlers for Markdy.
+ * MCP Tool definitions, Resource handlers, and Prompt workflows for Markdy.
  */
 interface ToolResult {
     [x: string]: unknown;
@@ -12,17 +12,29 @@ interface ToolResult {
     }>;
     isError?: boolean;
 }
+interface ResourceResult {
+    [x: string]: unknown;
+    contents: Array<{
+        uri: string;
+        mimeType?: string;
+        text: string;
+    }>;
+}
 declare function handleValidateMarkdy(code: string, checkArchitecture?: boolean): ToolResult;
 declare function handleTranspileToMarkdy(source: string, format: "mermaid" | "docker-compose" | "k8s" | "terraform" | "drawio", title?: string): Promise<ToolResult>;
 declare function handleExplainArchitecture(code: string): ToolResult;
 declare function handleGenerateMarkdyPrompt(userGoal: string): ToolResult;
+declare function handleGetArchitectureCatalog(filterCategory?: string): ToolResult;
+declare function handleReadResource(uri: string): ResourceResult;
 
 /**
  * packages/mcp-server/src/index.ts
  * MCP Server for Markdy Diagram Engine.
+ * Supports Tools, Resources, and Prompts for Claude Desktop, Cursor, Antigravity, and autonomous agents.
  */
 
+declare const MCP_SERVER_VERSION = "1.0.25";
 declare function createMarkdyMcpServer(): Server;
 declare function startMcpServer(): Promise<void>;
 
-export { createMarkdyMcpServer, handleExplainArchitecture, handleGenerateMarkdyPrompt, handleTranspileToMarkdy, handleValidateMarkdy, startMcpServer };
+export { MCP_SERVER_VERSION, createMarkdyMcpServer, handleExplainArchitecture, handleGenerateMarkdyPrompt, handleGetArchitectureCatalog, handleReadResource, handleTranspileToMarkdy, handleValidateMarkdy, startMcpServer };