Mermaid MCP Server

Instructions

Implementation Reference

• mermaid_mcp_server/main.py:22-167 (handler)

  The main handler function for 'convert_mermaid_to_image' tool, decorated with @mcp.tool() for registration. Implements conversion of Mermaid code to image formats (png, jpg, svg, pdf) via mermaid.ink API, including input validation, API request, base64 encoding, and error handling.
  @mcp.tool() def convert_mermaid_to_image( mermaid_code: str, output_format: str = "png", theme: str = "default", background_color: str = "", width: Optional[int] = None, height: Optional[int] = None ) -> Dict[str, Any]: """ 将 Mermaid 图表代码转换为多种格式的图像（PNG、JPG、PDF、SVG）。 参数: mermaid_code: 要转换的 Mermaid 图表语法代码 output_format: 输出格式 - png、jpg、svg 或 pdf（默认：png） theme: 视觉主题 - default、dark、neutral 或 forest（默认：default） background_color: 背景颜色，十六进制代码（如 FF0000）或带 ! 前缀的命名颜色（如 !white） width: 图像宽度（像素，可选） height: 图像高度（像素，可选） 返回: 包含转换后图像数据和元数据的字典 """ try: # 验证输入参数 if not mermaid_code or not mermaid_code.strip(): return { "success": False, "error": "Mermaid 代码是必需的，不能为空" } # 清理 Mermaid 代码（移除 markdown 代码块标记） cleaned_code = mermaid_code.replace("```mermaid", "").replace("```", "").strip() # 验证输出格式 valid_formats = ["png", "jpg", "jpeg", "svg", "pdf"] output_format = output_format.lower() if output_format not in valid_formats: return { "success": False, "error": f"无效的输出格式 '{output_format}'。支持的格式：{', '.join(valid_formats)}" } # 验证主题 valid_themes = ["default", "dark", "neutral", "forest"] if theme not in valid_themes: return { "success": False, "error": f"无效的主题 '{theme}'。支持的主题：{', '.join(valid_themes)}" } logger.info(f"Converting Mermaid diagram to {output_format} format with theme {theme}") # Base64 编码 Mermaid 代码 try: encoded_diagram = base64.urlsafe_b64encode(cleaned_code.encode('utf-8')).decode('ascii') except Exception as e: return { "success": False, "error": f"编码图表失败：{str(e)}" } # 构建 API URL url = _build_api_url(encoded_diagram, output_format, theme, background_color, width, height) logger.info(f"Making request to {url}") # 发送 HTTP 请求 try: response = requests.get(url, timeout=30) if response.status_code != 200: if response.status_code == 400: error_msg = f"无效的 Mermaid 语法：{response.text}" elif response.status_code == 413: error_msg = "图表对于 API 来说太大了" else: error_msg = f"转换失败：HTTP {response.status_code}" logger.error(error_msg) return { "success": False, "error": error_msg } # 确定 MIME 类型 mime_types = { "png": "image/png", "jpg": "image/jpeg", "jpeg": "image/jpeg", "svg": "image/svg+xml", "pdf": "application/pdf" } mime_type = mime_types.get(output_format, "image/png") filename = f"mermaid_diagram.{output_format}" # 将图像数据编码为 base64 以便传输 image_base64 = base64.b64encode(response.content).decode('ascii') logger.info(f"Successfully converted diagram to {output_format} ({len(response.content)} bytes)") return { "success": True, "data": { "image_base64": image_base64, "mime_type": mime_type, "filename": filename, "size_bytes": len(response.content), "format": output_format, "theme": theme }, "message": f"成功将 Mermaid 图表转换为 {output_format.upper()} 格式" } except requests.Timeout: error_msg = "转换超时 - mermaid.ink 响应时间过长" logger.error(error_msg) return { "success": False, "error": error_msg } except requests.ConnectionError: error_msg = "连接错误：无法访问 mermaid.ink 服务" logger.error(error_msg) return { "success": False, "error": error_msg } except Exception as e: error_msg = f"请求错误：{str(e)}" logger.error(error_msg) return { "success": False, "error": error_msg } except Exception as e: error_msg = f"转换过程中发生意外错误：{str(e)}" logger.error(error_msg) return { "success": False, "error": error_msg }
• mermaid_mcp_server/main.py:169-216 (helper)

  Helper function that constructs the mermaid.ink API URL with appropriate endpoint and query parameters for theme, background color, width, and height.
  def _build_api_url( encoded_diagram: str, output_format: str, theme: str, background_color: str, width: Optional[int] = None, height: Optional[int] = None ) -> str: """构建 mermaid.ink API URL""" # 根据格式选择不同的端点 if output_format == "svg": base_url = f"https://mermaid.ink/svg/{encoded_diagram}" elif output_format == "pdf": base_url = f"https://mermaid.ink/pdf/{encoded_diagram}" else: # png, jpg, jpeg base_url = f"https://mermaid.ink/img/{encoded_diagram}" # 构建查询参数 params = {} # 格式特定参数 if output_format in ["png", "jpg", "jpeg"]: params["type"] = output_format # 主题参数（仅适用于图像格式，不适用于 SVG/PDF） if theme and theme != "default" and output_format in ["png", "jpg", "jpeg"]: params["theme"] = theme # 背景颜色参数 if background_color: if background_color.startswith("!"): params["bgColor"] = background_color else: color = background_color.lstrip("#") if len(color) == 6 and all(c in "0123456789ABCDEFabcdef" for c in color): params["bgColor"] = color # 尺寸参数 if width: params["width"] = str(width) if height: params["height"] = str(height) # 组合 URL 和参数 if params: return f"{base_url}?{urlencode(params)}" else: return base_url
• mermaid_mcp_server/main.py:23-44 (schema)

  Input schema defined by function parameters and comprehensive docstring describing types, defaults, and usage for the tool.
  def convert_mermaid_to_image( mermaid_code: str, output_format: str = "png", theme: str = "default", background_color: str = "", width: Optional[int] = None, height: Optional[int] = None ) -> Dict[str, Any]: """ 将 Mermaid 图表代码转换为多种格式的图像（PNG、JPG、PDF、SVG）。 参数: mermaid_code: 要转换的 Mermaid 图表语法代码 output_format: 输出格式 - png、jpg、svg 或 pdf（默认：png） theme: 视觉主题 - default、dark、neutral 或 forest（默认：default） background_color: 背景颜色，十六进制代码（如 FF0000）或带 ! 前缀的命名颜色（如 !white） width: 图像宽度（像素，可选） height: 图像高度（像素，可选） 返回: 包含转换后图像数据和元数据的字典 """