Skip to main content
Glama
enesjakozh
rtuin

mcp-mermaid-validator

by rtuin
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

MCP 服务器：美人鱼验证器

一个用于验证和渲染Mermaid图的模型上下文协议服务器。该服务器使 LLM 能够验证和渲染 Mermaid 图。

用法

快速入门

您可以通过将 Mermaid Validator 添加到您的 mcp 服务器文件中来配置您的 MCP 客户端以使用 Mermaid Validator：

{
  "mcpServers": {
    "mermaid-validator": {
      "command": "npx",
      "args": [
        "-y",
        "@rtuin/mcp-mermaid-validator@latest"
      ]
    }
  }
}

Related MCP server: Mermaid MCP Server

建筑学

高级架构

该项目的结构是一个简单的 TypeScript Node.js 应用程序，它：

  1. 主要应用：一个 Node.js 服务，用于验证美人鱼图表并返回渲染的 PNG 输出

  2. MCP 集成：使用模型上下文协议 SDK 向 MCP 兼容客户端公开功能

  3. Mermaid CLI 集成：利用 Mermaid CLI 工具执行图表验证和渲染

代码结构

mcp-mermaid-validator/
├── dist/                   # Compiled JavaScript output
│   └── main.js             # Compiled main application
├── src/                    # TypeScript source code
│   └── main.ts             # Main application entry point
├── node_modules/           # Dependencies
├── package.json            # Project dependencies and scripts
├── package-lock.json       # Dependency lock file
├── tsconfig.json           # TypeScript configuration
├── eslint.config.js        # ESLint configuration
├── .prettierrc             # Prettier configuration
└── README.md               # Project documentation

组件功能

MCP 服务器（主要组件）

核心功能在src/main.ts中实现。该组件：

  1. 创建 MCP 服务器实例

  2. 注册一个接受 Mermaid 图表语法的validateMermaid工具

  3. 使用 Mermaid CLI 验证和渲染图表

  4. 返回验证结果并渲染 PNG（如果有效）

  5. 使用适当的错误消息处理错误情况

数据流

  1. 输入：美人鱼图语法作为字符串

  2. 加工：

    • 该图通过 stdin 传递给 Mermaid CLI

    • CLI 验证语法，如果有效则渲染 PNG

    • 从 stdout/stderr 捕获输出和错误

  3. 输出：

    • 成功：文本确认+渲染 PNG 作为 base64 编码图像

    • 失败：包含验证失败详细信息的错误消息

依赖项

外部库

  • @modelcontextprotocol/sdk ：用于实现模型上下文协议的 SDK

  • @mermaid-js/mermaid-cli ：用于验证和渲染 Mermaid 图表的 CLI 工具

  • zod ：TypeScript 的模式验证库

开发依赖项

  • typescript ：TypeScript 编译器

  • eslint ：Lint 实用程序

  • Prettier ：代码格式化

API 规范

验证美人鱼工具

目的：验证美人鱼图，如果有效则返回渲染的 PNG

参数：

  • diagram （字符串）：要验证的美人鱼图语法

返回值：

  • 成功：

    {
  content: [
    { 
      type: "text", 
      text: "Mermaid diagram is valid" 
    },
    {
      type: "image", 
      data: string, // Base64-encoded PNG
      mimeType: "image/png"
    }
  ]
}

  • 失败：

    {
  content: [
    { 
      type: "text", 
      text: "Mermaid diagram is invalid" 
    },
    {
      type: "text",
      text: string // Error message
    },
    {
      type: "text",
      text: string // Detailed error output (if available)
    }
  ]
}

技术决策

  1. MCP 集成：该项目使用模型上下文协议来标准化 AI 工具的接口，从而实现与兼容客户端的无缝集成。

  2. PNG 输出格式：该实现使用 PNG 作为默认输出格式，以确保与大多数 MCP 客户端（尤其是不支持 SVG 的 Cursor）更好地兼容。

  3. 子进程方法：该实现使用 Node.js 子进程与 Mermaid CLI 交互，它提供：

    • 主应用程序与渲染进程之间的隔离

    • 能够捕获详细的错误信息

    • 正确处理渲染管道

  4. 错误处理策略：实现使用嵌套的try-catch结构来：

    • 区分验证错误（无效图表语法）和系统错误

    • 提供详细的错误信息以帮助用户修复他们的图表

    • 确保即使在处理无效输入时服务仍然保持稳定

  5. 简单的项目结构：该项目使用简单的 TypeScript 项目结构来：

    • 易于维护和理解

    • 直接依赖管理

    • 简化的构建过程

构建和执行

可以使用 npm 脚本构建和运行该应用程序：

# Install dependencies
npm install

# Build the application
npm run build

# Run locally (for development)
npx @modelcontextprotocol/inspector node dist/main.js

# Format code
npm run format

# Lint code
npm run lint

# Watch for changes (development)
npm run watch

该应用程序作为 MCP 服务器运行，通过标准输入/输出进行通信，使其适合与 MCP 兼容客户端集成。

发布

要发布新版本，请按以下步骤操作：

  • npm run build

  • npm run bump

  • npm run changelog

  • npm publish --access public

Available Tools

1 tool
validateMermaidC

Validates a Mermaid diagram and returns the rendered image (PNG or SVG) if valid

ParametersJSON Schema
NameRequiredDescriptionDefault
diagramYes
formatNopng

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations; description fails to disclose what happens on invalid input (e.g., error messages), side effects, or rate limits. Minimal behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no fluff. Efficient for its brevity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema; description mentions 'rendered image' but not format details (binary vs base64) or validation success/failure behavior. Lacks completeness for a validation tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%; tool description does not explain parameters beyond schema fields. 'diagram' and 'format' remain underdocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clear verb-resource: 'Validates a Mermaid diagram' and specifies output ('rendered image'). Lacks sibling differentiation but no siblings exist.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use or when not to, no alternatives mentioned. Implied usage only.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev0.7.0
    • ChangedvalidateMermaid1 field changed
      • addedInput schema / properties / format
        Added value: +{
+  "default": "png",
+  "enum": [
+    "svg",
+    "png"
+  ],
+  "type": "string"
+}
  2. 1 tool updatev1.0.0
    • First observedvalidateMermaid
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored across 1 tool

Disambiguation5/5

With only one tool, there is no possibility for confusion. The tool's purpose is clear and distinct.

Naming Consistency5/5

A single tool cannot be inconsistent. The name 'validateMermaid' follows a clear verb_noun pattern.

Tool Count5/5

A single validation tool perfectly matches the server's focused purpose. Adding more tools would be unnecessary.

Completeness5/5

The tool fully covers the domain: it validates Mermaid diagrams and returns the rendered image. No obvious gaps exist.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

Appeared in Searches