PlantUML MCP Server

Гибкий сервер протокола контекста модели (MCP), который превращает фрагменты PlantUML в диаграммы, которыми можно делиться.
Все возможности доступны через HTTP, Server-Sent Events (SSE) и 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

• 🔒 Опциональная аутентификация Bearer через MCP_API_KEY

• ☁️ Опциональный экспорт ob-file через подписанные URL-адреса для скачивания (OB_FILE_API_BASE_URL)

• 🔐 Опциональный поток OIDC client-credentials для ob-file (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 доступен для проверок готовности.

• Пример настроек клиента: 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) для получения событий и отправляют JSON-сообщения методом POST на /messages.

• Пример конфигурации для 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

• Идеально подходит для локальных экспериментов, CLI mcp или узлов Flowise, которые запускают бинарный файл.

• Примеры настроек находятся в client_config_stdio.json.

Примеры конфигураций клиента

• client_config_http.json – потоковый HTTP (по умолчанию /mcp)

• client_config_sse.json – SSE + выделенный messagesUrl

• client_config_stdio.json – примеры STDIO для npx и процессов, управляемых Flowise

Поместите эти файлы в свой MCP-совместимый клиент или скопируйте фрагменты по мере необходимости. Обновите имена хостов, порты и ключи API в соответствии с вашим развертыванием.

Переменные окружения

Когда настроен OB_FILE_API_BASE_URL, отрендеренные диаграммы загружаются через ob-file, а ответ MCP возвращает подписанный download_url, сгенерированный ob-file. Если настроены OB_FILE_OIDC_DISCOVERY_URL, OB_FILE_OIDC_CLIENT_ID и OB_FILE_OIDC_CLIENT_SECRET, сервер автоматически получает и кэширует токен доступа через учетные данные клиента OAuth 2.0. Путь к общему тому остается в качестве резервного варианта совместимости для локальных/разработческих настроек.

Инструменты, промпты и ресурсы

• Инструменты автоматически регистрируются через tools/list. Они выполняют проверку, опциональные автоисправления и возвращают структурированные метаданные (success, URL-адреса, фрагменты markdown, закодированные данные диаграммы и ошибки проверки).

• Промпты направляют модель через обработку ошибок 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 – snapshot-тест, который преобразует test_files/generate_sequence_diagram/payload.json в PlantUML и сравнивает его с expected.puml

• make test-mcp – дымовое тестирование команд через CLI mcp

Нужна помощь?

• Проверьте подключение с помощью curl http://<host>:<port>/healthz

• Убедитесь, что заголовки аутентификации соответствуют MCP_API_KEY (Bearer-токен), если они включены

• Используйте инспектор MCP или логи узла Flowise для отслеживания полезных нагрузок JSON-RPC

Сервер поставляется со всем необходимым для работы через HTTP, SSE и STDIO. Подключите транспорт, который соответствует вашей среде, и начните создавать диаграммы!