Astah MCP

Servidor MCP local e genérico para transformar pedidos e enunciados de exercícios de modelagem em projetos nativos do Astah (.asta).

O usuário conversa normalmente com o agente do cliente MCP: pode descrever o modelo desejado, colar o enunciado ou anexar um PDF se o cliente conseguir lê-lo. O agente interpreta o conteúdo e chama o servidor com uma especificação estruturada; o usuário não precisa escrever JSON nem informar coordenadas.

O projeto foi construído sobre a API oficial do Astah. Ele implementa todos os tipos de diagrama que a instalação Astah UML permite criar nativamente por API e rejeita explicitamente tipos indisponíveis, evitando apresentar um diagrama aproximado como se fosse o tipo solicitado.

Fluxo de uso

1. O usuário informa o que quer modelar ou fornece o enunciado do exercício.
2. O agente identifica elementos, propriedades, relações, multiplicidades e o tipo de diagrama adequado.
3. O MCP valida a especificação e cria o projeto nativo no Astah.
4. O servidor calcula um layout compacto quando não recebe posições explícitas.
5. O Astah exporta os diagramas para PNGs temporários.
6. O agente inspeciona as imagens e confirma que não há cortes ou sobreposições.
7. A pasta temporária é apagada; somente o .asta final permanece no caminho escolhido.

Por padrão, o MCP cria apenas um diagrama e comprime o conteúdo nele. Mais de um diagrama só é aceito quando o pedido ou o enunciado exige explicitamente várias visões.

Diagramas suportados

Esta versão cria nativamente:

• diagrama de classes, incluindo classes abstratas, interfaces, enumerações e objetos;
• diagrama de casos de uso;
• diagrama de máquina de estados;
• diagrama de atividades;
• diagrama de sequência;
• diagrama de estrutura composta;
• mapa mental.

Também são suportados os principais elementos e relações próprios de cada tipo, como atributos, operações, literais, associações, agregações, composições, generalizações, realizações, dependências, atores, include, extend, transições, fluxos, mensagens, retornos, portas e conectores.

Limites da API

Na edição Astah UML usada pelo servidor, a API não cria nativamente diagramas de comunicação, componentes, implantação, fluxograma, fluxo de dados, entidade-relacionamento, requisitos ou CRUD. Alguns elementos isolados, como Component e Node, existem na API de modelo, mas isso não habilita a criação do respectivo diagrama nativo.

Quando um desses tipos for solicitado, o MCP retorna uma explicação clara da limitação. Ele não troca silenciosamente o tipo pedido por outro. A matriz oficial de suporte pode variar entre produtos e versões do Astah: Astah API Support.

Layout automático

O servidor:

• calcula a menor largura segura considerando nomes, atributos, operações e parâmetros;
• respeita o tamanho mínimo obrigatório de cada apresentação nativa do Astah;
• alinha elementos equivalentes em uma grade compacta e simétrica;
• centraliza superclasses acima das subclasses;
• organiza atividades e estados em fluxo vertical;
• distribui linhas de vida uniformemente;
• prioriza relações retas e usa segmentos ortogonais quando é necessário desviar;
• reserva corredores para rótulos, multiplicidades, portas e conectores;
• não divide um diagrama apenas para obter mais espaço;
• aceita posições explícitas quando o agente identifica que o enunciado exige um arranjo específico.

As regras completas estão em docs/LAYOUT_GUIDE.md.

Requisitos

• Windows;
• Astah UML instalado;
• Node.js 18 ou superior;
• JDK com java e javac no PATH.

Não há dependências npm externas. O servidor usa módulos nativos do Node.js e os arquivos JAR instalados com o Astah.

Por padrão, o Astah é procurado em C:\Program Files\astah-UML. Para usar outra instalação, defina ASTAH_HOME e reabra o cliente MCP:

[Environment]::SetEnvironmentVariable(
  "ASTAH_HOME",
  "D:\Aplicativos\astah-UML",
  "User"
)

Instalação

Clone o repositório:

git clone https://github.com/g0mz/astah-mcp.git
cd astah-mcp

Confira o ambiente:

node --version
java -version
javac -version
node astah-mcp-server.js

O último comando inicia o servidor via stdio e fica aguardando um cliente MCP. Use Ctrl+C para encerrá-lo.

Configuração do cliente MCP

Adicione o servidor à configuração do cliente, substituindo o caminho pelo local do clone:

{
  "mcpServers": {
    "astah": {
      "command": "node",
      "args": [
        "C:\\caminho\\para\\astah-mcp\\astah-mcp-server.js"
      ]
    }
  }
}

Antigravity IDE

Abra o painel do agente e selecione ... → MCP Servers → Manage MCP Servers → View raw config. Adicione o objeto acima ao arquivo global ~/.gemini/config/mcp_config.json ou ao arquivo local .agents/mcp_config.json do projeto. Reinicie ou recarregue os servidores MCP.

Outros clientes

Claude Desktop, VS Code com GitHub Copilot, Cline, Goose e outros clientes compatíveis com MCP podem usar a mesma configuração stdio: comando node e caminho absoluto de astah-mcp-server.js.

O cliente precisa ter um agente/modelo capaz de interpretar o enunciado e usar ferramentas MCP. Para enunciados em PDF, ele também precisa conseguir ler o anexo.

Como pedir um modelo

Depois de configurar o servidor, escreva ao agente em linguagem natural. Exemplos:

Crie no Astah um diagrama de classes para este enunciado e salve em
C:\Projetos\biblioteca.asta. Inclua atributos, operações, relações e multiplicidades.

Leia o PDF anexado, resolva o exercício no Astah e crie somente o diagrama pedido.
Mantenha tudo compacto, reto e sem cortar textos.

Modele o ciclo de vida de um pedido com uma máquina de estados e salve em
C:\Projetos\estados-pedido.asta.

Se o arquivo de saída já existir, o MCP não o substitui por padrão. O agente só deve enviar overwrite: true quando o usuário autorizar a substituição explicitamente.

Ferramentas MCP

create_astah_model

Ferramenta principal. Recebe do agente a interpretação estruturada do enunciado, cria um ou mais diagramas nativos e retorna as imagens temporárias para revisão visual.

Ela aceita:

• caminho absoluto do .asta;
• contexto original do exercício;
• tipo, nome, elementos, membros e relações de cada diagrama;
• coordenadas opcionais — quando omitidas, o layout é automático;
• autorização explícita para múltiplos diagramas e para sobrescrita.

O esquema completo é fornecido ao cliente automaticamente por tools/list; normalmente ninguém precisa montá-lo manualmente.

get_astah_capabilities

Lista os tipos, elementos e relações criáveis na instalação atual e explica os tipos indisponíveis.

verify_astah_visual_layout

Exporta e revisa um projeto .asta existente sem modificá-lo. Os PNGs e o relatório são temporários e apagados após serem carregados na resposta MCP.

get_astah_layout_guidelines

Retorna as regras visuais usadas pelo gerador e pela inspeção final.

validate_astah_environment

Confirma a presença do Astah, da API, do Java, do exportador e dos geradores, sem alterar projetos.

Compatibilidade

create_meteorological_station_model continua disponível somente para clientes antigos que já dependiam dessa ferramenta. Novos exercícios devem usar create_astah_model.

Testes

Teste genérico mínimo:

node tests\smoke-client.mjs "C:\Temp\astah-mcp-smoke.asta"

Teste explícito de todos os sete tipos criáveis:

node tests\all-diagrams-client.mjs "C:\Temp\astah-mcp-all.asta"

Use caminhos novos ou remova os projetos de teste antes de repetir, pois a proteção contra sobrescrita também vale nos testes.

Estrutura

astah-mcp/
├── astah-mcp-server.js
├── java/
│   ├── UniversalAstahModel.java
│   └── MeteorologicalStationModel.java
├── tests/
│   ├── smoke-client.mjs
│   └── all-diagrams-client.mjs
├── docs/
│   └── LAYOUT_GUIDE.md
├── package.json
└── README.md

Segurança e arquivos temporários

O servidor inicia processos locais do Node.js, Java e Astah. Instale somente uma cópia confiável. Projetos existentes são protegidos contra substituição acidental. Especificações intermediárias, PNGs e relatórios de revisão são criados na pasta temporária do sistema e removidos automaticamente; o .asta solicitado é o único artefato permanente.