MCP 서버: 인어 검증기

Mermaid 다이어그램을 검증하고 렌더링하는 모델 컨텍스트 프로토콜 서버입니다. 이 서버를 통해 LLM은 Mermaid 다이어그램을 검증하고 렌더링할 수 있습니다.

용법

빠른 시작

Mermaid Validator를 사용하도록 MCP 클라이언트를 구성하려면 mcp 서버 파일에 다음을 추가합니다.

지엑스피1

Related MCP server: Mermaid MCP Server

건축학

고수준 아키텍처

이 프로젝트는 다음과 같은 간단한 TypeScript Node.js 애플리케이션으로 구성됩니다.

1. 주요 애플리케이션 : 인어 다이어그램을 검증하고 렌더링된 PNG 출력을 반환하는 Node.js 서비스

2. MCP 통합 : MCP 호환 클라이언트에 기능을 노출하기 위해 Model Context Protocol SDK를 사용합니다.

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용 스키마 검증 라이브러리

개발 종속성

• 타입스크립트 : 타입스크립트 컴파일러

• eslint : 린팅 유틸리티

• 더 예쁘게 : 코드 포맷팅

API 사양

validateMermaid 도구

목적 : 인어 다이어그램을 검증하고 유효한 경우 렌더링된 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 출력 형식 : 구현에서는 대부분 MCP 클라이언트, 특히 SVG를 지원하지 않는 Cursor와의 더 나은 호환성을 보장하기 위해 기본 출력 형식으로 PNG를 사용합니다.

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