iflow-mcp_andrewginns-mermaid-mcp-server 11.4.2__py3-none-any.whl

iflow_mcp_andrewginns_mermaid_mcp_server-11.4.2.dist-info/METADATA

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: iflow-mcp_andrewginns-mermaid-mcp-server
+Version: 11.4.2
+Summary: MCP server for validating Mermaid diagrams
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.115.12
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: langchain-mcp>=0.2.1
+Requires-Dist: langchain-openai>=0.3.19
+Requires-Dist: mcp[cli]>=1.9.2
+Requires-Dist: pydantic>=2.11.5
+Requires-Dist: pydantic-ai-slim[mcp]>=0.2.14
+Requires-Dist: python-dotenv>=1.1.0
+Requires-Dist: uvicorn>=0.34.3
+
+# Mermaid MCP Server
+
+A Model Context Protocol (MCP) server for validating Mermaid diagrams.
+
+Implements a minimal Python wrapper over https://github.com/mermaid-js/mermaid-cli for simpler out of the box use.
+
+## Overview
+
+Python MCP server for validating Mermaid diagrams and (optionally) rendering them as PNG images. It uses the Mermaid CLI tool to perform the validation and rendering.
+
+The server provides LLMs with structured validation results including:
+- **Boolean validation status** (`is_valid: true/false`) indicating whether the Mermaid diagram syntax is correct
+- **Detailed error messages** explaining exactly what went wrong if validation fails (e.g., syntax errors, unsupported diagram types, malformed nodes)
+- **Optional base64-encoded PNG images** of successfully rendered diagrams for visual verification
+
+This enables LLMs to programmatically validate Mermaid diagram syntax, understand specific errors to provide helpful corrections, and optionally receive visual confirmation of the rendered output.
+
+Also provides a simple Pydantic-AI MCP Client to invoke the MCP server using a Gemini model for testing.
+
+## Prerequisites
+
+**Important**: This MCP server requires Node.js to be installed on your system, even if you're only using the server component (not the client). The server internally calls `npx @mermaid-js/mermaid-cli` as a subprocess to perform diagram validation and rendering.
+
+### Required Dependencies
+
+- **Node.js** with npm (required for all usage)
+- **Mermaid CLI**: Install with `npm install -g @mermaid-js/mermaid-cli`
+- **Python** with uv (for running the MCP server)
+
+### Quick Dependency Setup
+
+```bash
+# Install Mermaid CLI globally
+npm install -g @mermaid-js/mermaid-cli
+
+# Verify installation
+npx @mermaid-js/mermaid-cli --version
+```
+
+## Quickstart
+
+To use this server with an MCP client (like Claude Desktop), add the following configuration to your MCP settings:
+
+**Note**: Make sure you have Node.js and Mermaid CLI installed (see Prerequisites above) before configuring the MCP server.
+
+### Configuration Format
+
+1. Clone this repository
+
+2. Add this to your MCP client configuration file (e.g., `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "mermaid-validator": {
+      "command": "uv",
+      "args": ["run", "/path/to/mermaid_mcp_server.py"],
+    }
+  }
+}
+```
+
+### Configuration Options
+
+- **command**: Use `uv` to run the server
+- **args**: Run the server script with `uv run`
+- **cwd**: Set to the absolute path of your cloned repository
+- **env**: Environment variables for the server
+  - `MCP_TRANSPORT`: Set to `"stdio"` for standard input/output communication
+
+
+#### Example Extended Configuration
+
+```json
+{
+  "mcpServers": {
+    "mermaid-validator": {
+      "command": "uv", 
+      "args": ["run", "/path/to/mermaid_mcp_server.py"],
+      "env": {
+        "MCP_TRANSPORT": "stdio",
+      }
+    }
+  }
+}
+```
+
+## Abstractions Over Mermaid-CLI
+
+The Python wrapper significantly simplifies the usage of the Mermaid CLI by abstracting away complex file handling and command-line arguments:
+
+### Without the wrapper (raw mermaid-cli):
+```bash
+# Create input file
+echo "graph TD; A-->B" > diagram.mmd
+
+# Create puppeteer config file
+echo '{"args": ["--no-sandbox", "--disable-setuid-sandbox"]}' > puppeteer-config.json
+
+# Run mermaid-cli with multiple arguments
+npx @mermaid-js/mermaid-cli -i diagram.mmd -o output.png --puppeteerConfigFile puppeteer-config.json
+
+# Handle output file and cleanup
+```
+
+### With the Python wrapper:
+```python
+# Simple function call with diagram text
+result = await validate_mermaid_diagram("graph TD; A-->B")
+
+# All file handling, configuration, and cleanup is automatic
+# Returns structured result with validation status and base64-encoded image
+```
+
+### Key Abstractions:
+
+1. **Temporary File Management**: Automatically creates and cleans up temporary `.mmd` input files
+2. **Output File Handling**: Manages temporary `.png` output files and converts them to base64 strings
+3. **Puppeteer Configuration**: Automatically generates the required sandboxing configuration for headless browser rendering
+4. **Error Handling**: Captures and returns structured error messages instead of raw stderr output
+5. **Command Construction**: Builds the complete `npx @mermaid-js/mermaid-cli` command with all necessary flags
+6. **Resource Cleanup**: Ensures all temporary files are properly deleted after processing
+
+This abstraction allows users to focus on diagram validation and rendering without dealing with the underlying file system operations and command-line complexities.
+
+
+# Local Development
+
+This repository can be used standalone to test the functionality of the Mermaid MCP validator programmatically.
+
+## Requirements
+
+See the [Prerequisites](#prerequisites) section above for required dependencies (Node.js, Mermaid CLI, and Python with uv).
+
+## Quick Setup (Recommended)
+
+Use the provided Makefile for streamlined setup:
+
+```bash
+# Install all dependencies (Python + Node.js + Mermaid CLI)
+make install
+
+# Run validation tests
+make test
+```
+
+## Manual Setup
+
+If you prefer manual setup:
+
+1. Clone this repository
+2. Install dependencies: `uv sync`
+3. Install Mermaid CLI: `npm install -g @mermaid-js/mermaid-cli`
+4. Copy `.env.example` to `.env` and fill in your API key
+5. Run the server: `uv run mermaid_mcp_server.py`
+
+## Usage
+
+The server exposes a tool for validating Mermaid diagrams:
+
+- `validate_mermaid_diagram`: Validates a Mermaid diagram and returns validation results
+
+### Tool Parameters
+
+- `diagram_text` (required): The Mermaid diagram text to validate
+- `return_image` (optional, default: `false`): Whether to return the base64-encoded PNG image
+
+### Context Length Optimisation
+
+**Important**: By default, the tool does not return the base64-encoded image (`return_image=false`) to preserve context length in LLM conversations. Base64-encoded images can be very long strings (often 10KB-100KB+) that significantly impact the available context for the conversation.
+
+**When to use each setting**:
+- `return_image=false` (default): Use for diagram validation only. Fast and context-efficient.
+- `return_image=true`: Use only when you specifically need the rendered image data. Warning: This will consume significant context length.
+
+### Example Usage
+
+```python
+# Validation only (recommended for most cases)
+result = await validate_mermaid_diagram("graph TD; A-->B")
+# Returns: MermaidValidationResult(is_valid=True, error_message=None, diagram_image=None)
+
+# Validation with image (use sparingly)
+result = await validate_mermaid_diagram("graph TD; A-->B", return_image=True)
+# Returns: MermaidValidationResult(is_valid=True, error_message=None, diagram_image="iVBORw0KGgoAAAANSUhEUg...")
+```
+
+## Testing
+
+The project includes convenient testing commands:
+
+```bash
+# Run all tests
+make test
+
+# Or run the test script directly
+uv run test_pydantic.py
+```
+
+The test script uses Pydantic AI with Gemini models to validate the MCP server functionality.

iflow_mcp_andrewginns_mermaid_mcp_server-11.4.2.dist-info/RECORD

@@ -0,0 +1,8 @@
+__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mermaid_mcp_server.py,sha256=ZNp8w4tqO_xxU9yXdribs4FdA6U7p6souRqpjieNCg4,4125
+test_pydantic.py,sha256=8CkkwDUiZh1_lmXeJ6Jyp_dUyRZWr_qOse15ACohypw,1243
+iflow_mcp_andrewginns_mermaid_mcp_server-11.4.2.dist-info/METADATA,sha256=2FKzHFfMFDd1WafZkyJ91r2KiQiu55aE8a7SMqp3UP4,7492
+iflow_mcp_andrewginns_mermaid_mcp_server-11.4.2.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+iflow_mcp_andrewginns_mermaid_mcp_server-11.4.2.dist-info/entry_points.txt,sha256=puY__ZIXoXNQYH0HBKeYR4ZtqSr58GnL6lkKsVfMdOM,63
+iflow_mcp_andrewginns_mermaid_mcp_server-11.4.2.dist-info/top_level.txt,sha256=7upMHofPhWv6FPr_Pf4Yj3qFn6utq9ubW-fSBPdpHEA,42
+iflow_mcp_andrewginns_mermaid_mcp_server-11.4.2.dist-info/RECORD,,

iflow_mcp_andrewginns_mermaid_mcp_server-11.4.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

iflow_mcp_andrewginns_mermaid_mcp_server-11.4.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mermaid-mcp-server = mermaid_mcp_server:main

iflow_mcp_andrewginns_mermaid_mcp_server-11.4.2.dist-info/top_level.txt

@@ -0,0 +1,3 @@
+__init__
+mermaid_mcp_server
+test_pydantic

mermaid_mcp_server.py

@@ -0,0 +1,128 @@
+# /// script
+# dependencies = [
+#     "pydantic>=2.11.5",
+#     "mcp[cli]>=1.9.2",
+# ]
+# ///
+
+import os
+import tempfile
+import subprocess
+import base64
+import json
+from typing import Optional
+from pydantic import BaseModel, Field
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP("mermaid-validator")
+
+
+class MermaidValidationResult(BaseModel):
+    """Result of mermaid diagram validation."""
+
+    is_valid: bool = Field(description="Whether the mermaid diagram is valid")
+    error_message: Optional[str] = Field(
+        None, description="Error message if the diagram is invalid"
+    )
+    diagram_image: Optional[str] = Field(
+        None, description="Base64-encoded PNG image of the rendered diagram if valid"
+    )
+
+
+@mcp.tool()
+async def validate_mermaid_diagram(
+    diagram_text: str, return_image: bool = False
+) -> MermaidValidationResult:
+    """
+    Validate a mermaid diagram and optionally render it as a PNG image.
+
+    Uses mermaid-cli to validate and render the diagram. Requires mermaid-cli
+    to be installed globally via npm: npm install -g @mermaid-js/mermaid-cli
+
+    Args:
+        diagram_text: The mermaid diagram text to validate
+        return_image: Whether to return the base64-encoded PNG image (default: False)
+                     Set to True only when you specifically need the image data.
+                     Warning: Images can be very long strings that impact context length.
+
+    Returns:
+        A MermaidValidationResult object containing validation results
+    """
+    temp_file_path = None
+    output_file_name = None
+    puppeteer_config_path = None
+
+    try:
+        with tempfile.NamedTemporaryFile(
+            suffix=".mmd", mode="w", delete=False
+        ) as temp_file:
+            temp_file.write(diagram_text)
+            temp_file_path = temp_file.name
+
+        # Always create output file for validation, but only read it if return_image=True
+        output_file = tempfile.NamedTemporaryFile(suffix=".png", delete=False)
+        output_file.close()
+        output_file_name = output_file.name
+
+        puppeteer_config = {"args": ["--no-sandbox", "--disable-setuid-sandbox"]}
+        with tempfile.NamedTemporaryFile(
+            suffix=".json", mode="w", delete=False
+        ) as config_file:
+            json.dump(puppeteer_config, config_file)
+            puppeteer_config_path = config_file.name
+
+        result = subprocess.run(
+            [
+                "npx",
+                "-y",
+                "@mermaid-js/mermaid-cli@11.4.2",
+                "-i",
+                temp_file_path,
+                "-o",
+                output_file_name,
+                "--puppeteerConfigFile",
+                puppeteer_config_path,
+            ],
+            capture_output=True,
+            text=True,
+        )
+
+        if result.returncode == 0:
+            diagram_image = None
+            if return_image and output_file_name:
+                with open(output_file_name, "rb") as f:
+                    diagram_image = base64.b64encode(f.read()).decode("utf-8")
+
+            return MermaidValidationResult(
+                is_valid=True, error_message=None, diagram_image=diagram_image
+            )
+        else:
+            return MermaidValidationResult(
+                is_valid=False,
+                error_message=f"Mermaid diagram is invalid: {result.stderr}",
+                diagram_image=None,
+            )
+    except Exception as e:
+        return MermaidValidationResult(
+            is_valid=False,
+            error_message=f"Error validating mermaid diagram: {str(e)}",
+            diagram_image=None,
+        )
+    finally:
+        for file_path in [temp_file_path, output_file_name, puppeteer_config_path]:
+            if file_path and os.path.exists(file_path):
+                try:
+                    os.unlink(file_path)
+                except OSError as e:
+                    print(f"Error deleting file {file_path}: {e}")
+                    pass
+
+
+def main():
+    """Main entry point for the MCP server."""
+    transport = os.getenv("MCP_TRANSPORT", "stdio")
+    mcp.run(transport=transport)
+
+
+if __name__ == "__main__":
+    main()

test_pydantic.py

@@ -0,0 +1,47 @@
+import asyncio
+from dotenv import load_dotenv
+from pydantic_ai import Agent
+from pydantic_ai.mcp import MCPServerStdio
+
+load_dotenv()
+
+
+async def main():
+    """Test the mermaid validator MCP server using Pydantic AI."""
+    example_diagram = """
+    graph TD
+        A[Start] --> B{Is it valid?}
+        B -->|Yes| C[Output valid result]
+        B -->|No| D[Output error message]
+        C --> E[End]
+        D --> E
+    """
+
+    mermaid_server = MCPServerStdio(
+        command="uv",
+        args=[
+            "run",
+            "mermaid_mcp_server.py",
+        ],
+    )
+
+    agent = Agent(
+        "gemini-2.5-pro-preview-05-06",
+        system_prompt="""
+        You are a helpful assistant that validates mermaid diagrams.
+        You will be given a mermaid diagram and you need to validate it using the MCP mermaid validator tool.
+        Return whether the diagram is valid, and if not, provide the error message.
+        """,
+        mcp_servers=[mermaid_server],
+    )
+    Agent.instrument_all()
+
+    async with agent.run_mcp_servers():
+        result = await agent.run(
+            "Validate the following mermaid diagram: " + example_diagram
+        )
+    print(result.output)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())