PlantUML MCP 서버

PlantUML 스니펫을 공유 가능한 다이어그램으로 변환하는 유연한 MCP(Model Context Protocol) 서버입니다.
모든 기능은 HTTP, SSE(Server-Sent Events) 및 STDIO를 통해 노출되므로 Claude Desktop, Flowise 또는 기타 MCP 호환 런타임에 서버를 연결할 수 있습니다.

주요 기능

• 🧰 도구: generate_plantuml_diagram, generate_capability_landscape, generate_business_scenario, encode_plantuml, decode_plantuml

• 🧾 프롬프트: plantuml_error_handling, capability_landscape_input_format, archimate_diagram_input_format, business_scenario_input_format

• 📚 정적 리소스: resource://plantuml/server-guide, resource://plantuml/archimate-mapping

• 🔒 MCP_API_KEY를 통한 선택적 Bearer 인증

• ☁️ 서명된 다운로드 URL을 통한 선택적 ob-file 내보내기 (OB_FILE_API_BASE_URL)

• 🔐 ob-file을 위한 선택적 OIDC 클라이언트 자격 증명 흐름 (OB_FILE_OIDC_*)

• 📁 대체 공유 볼륨 내보내기 (GENERATED_FILES_DIR + PUBLIC_FILE_BASE_URL)

Related MCP server: PlantUML MCP Server

요구 사항

• Node.js 18+

• npm 9+

npm install
npm run build     # emits dist/plantuml-mcp-server.js

빌드 후 npx plantuml-mcp-server 또는 node dist/plantuml-mcp-server.js를 사용하세요.

전송 모드

HTTP 전송

MCP_TRANSPORT=http \
MCP_HOST=0.0.0.0 \
MCP_PORT=8765 \
MCP_HTTP_PATH=/mcp \
node dist/plantuml-mcp-server.js

• POST /mcp를 통해 초기화하고 JSON-RPC 페이로드를 전송합니다.

• GET /mcp 및 DELETE /mcp는 스트리밍 가능한 세션을 유지합니다.

• GET /healthz는 준비 상태 확인(readiness probe)을 위해 사용할 수 있습니다.

• 샘플 클라이언트 설정: client_config_http.json.

SSE 전송

MCP_TRANSPORT=sse \
MCP_HOST=0.0.0.0 \
MCP_PORT=8765 \
MCP_SSE_PATH=/sse \
MCP_SSE_MESSAGES_PATH=/messages \
node dist/plantuml-mcp-server.js

• 클라이언트는 이벤트 수신을 위해 /sse (GET)에 연결하고, /messages로 JSON 메시지를 POST합니다.

• Claude Desktop / Flowise용 샘플 구성: client_config_sse.json.

STDIO 전송

MCP_TRANSPORT=stdio npx plantuml-mcp-server
# or run the compiled file directly
MCP_TRANSPORT=stdio node dist/plantuml-mcp-server.js

• 로컬 실험, mcp CLI 또는 바이너리를 생성하는 Flowise 노드에 이상적입니다.

• 예제 설정은 client_config_stdio.json에 있습니다.

샘플 클라이언트 구성

• client_config_http.json – 스트리밍 가능한 HTTP (기본값 /mcp)

• client_config_sse.json – SSE + 전용 messagesUrl

• client_config_stdio.json – npx 및 Flowise 관리 프로세스를 위한 STDIO 예제

이 파일들을 MCP 인식 클라이언트에 넣거나 필요에 따라 스니펫을 복사하세요. 배포 환경에 맞게 호스트 이름, 포트 및 API 키를 업데이트하세요.

환경 변수

OB_FILE_API_BASE_URL이 구성되면 렌더링된 다이어그램은 ob-file을 통해 업로드되며 MCP 응답은 ob-file이 생성한 서명된 download_url을 반환합니다. OB_FILE_OIDC_DISCOVERY_URL, OB_FILE_OIDC_CLIENT_ID 및 OB_FILE_OIDC_CLIENT_SECRET이 구성된 경우, 서버는 OAuth 2.0 클라이언트 자격 증명을 통해 액세스 토큰을 자동으로 획득하고 캐시합니다. 공유 볼륨 경로는 로컬/개발 환경을 위한 호환성 대체 수단으로 유지됩니다.

도구, 프롬프트 및 리소스

• 도구는 tools/list를 통해 자동으로 등록됩니다. 유효성 검사, 선택적 자동 수정 기능을 수행하며 구조화된 메타데이터(success, URL, 마크다운 스니펫, 인코딩된 다이어그램 데이터 및 유효성 검사 오류)를 반환합니다.

• 프롬프트는 PlantUML 오류 처리를 통해 모델을 안내하고 준비된 기능 랜드스케이프 템플릿을 제공합니다.

• 리소스 템플릿은 온보딩 콘텐츠(resource://plantuml/server-guide)를 노출하여 클라이언트가 사용 지침을 스스로 발견할 수 있도록 합니다.

Docker 이미지

제공된 Dockerfile은 TypeScript 소스를 빌드하고 최소한의 런타임 이미지를 생성합니다:

docker build -t plantuml-mcp-server .
docker run --rm -e MCP_TRANSPORT=http -p 8765:8765 plantuml-mcp-server

필요에 따라 환경 변수(PLANTUML_SERVER_URL, MCP_API_KEY 등)를 재정의하세요.

테스트 및 도구

• npm run build – TypeScript 컴파일

• npm start – 기본 HTTP 전송을 사용하여 실행

• npm run start:sse / npm run start:stdio – 편리한 스크립트

• npm run test:business-scenario – test_files/generate_sequence_diagram/payload.json을 PlantUML로 변환하고 expected.puml과 비교하는 스냅샷 테스트

• make test-mcp – mcp CLI를 통한 스모크 테스트 명령

도움이 필요하신가요?

• curl http://<host>:<port>/healthz로 연결 확인

• 활성화된 경우 인증 헤더가 MCP_API_KEY (Bearer 토큰)와 일치하는지 확인

• MCP Inspector 또는 Flowise 노드 로그를 사용하여 JSON-RPC 페이로드 추적

이 서버는 HTTP, SSE 및 STDIO를 통해 작동하는 데 필요한 모든 것을 갖추고 있습니다. 환경에 맞는 전송 방식을 연결하고 다이어그램 생성을 시작하세요!