MMAR-MCP Server

Un servidor MCP (Model Context Protocol) que conecta Modelos de Lenguaje Grandes a la plataforma de metamodelado MM-AR, permitiendo a los usuarios crear metamodelos completos e instancias de modelos mediante interacción en lenguaje natural.

Descripción general

MMAR-MCP expone las capacidades de la plataforma MM-AR a través del Model Context Protocol:

• 62 herramientas para autenticación, CRUD de metamodelos y CRUD de instancias

• 5 recursos que proporcionan documentación de la arquitectura de la plataforma, plantillas VizRep, el esquema del meta-modelo, tipos de atributos y un metamodelo de referencia

• 3 prompts que codifican flujos de trabajo guiados para creación de metamodelos, creación de instancias y análisis de modelos

El servidor se comunica mediante transporte STDIO y funciona con cualquier host compatible con MCP (Cursor, Claude Desktop, o cualquier cliente que implemente la especificación MCP).

Related MCP server: ParaView-MCP

Requisitos previos

Inicio rápido

Siga estos cinco pasos para pasar de cero a una configuración funcional.

Paso 1: Iniciar la plataforma MM-AR

Opción A: Despliegue completo con Docker (recomendado para la primera configuración)

Clone e inicie el stack completo de MM-AR usando Docker:

git clone https://github.com/MM-AR/mmar-docker-installation.git
cd mmar-docker-installation
docker compose --env-file .env up -d

Espere hasta que todos los contenedores estén en estado saludable. Puede comprobarlo con:

docker compose ps

Opción B: Despliegue híbrido (PostgreSQL en Docker, servicios locales)

Esta es la configuración utilizada durante los experimentos de la tesis. Requiere clonar el repositorio principal de MM-AR:

# 1. Start PostgreSQL in Docker
docker run -d --name mmar_postgres \
  -e POSTGRES_USER=api -e POSTGRES_PASSWORD=root -e POSTGRES_DB=api \
  -p 5432:5432 postgres:16

# 2. Start the API server (requires mmar-server/.env with JWT_SECRET)
cd mmar-server
export $(cat .env | xargs)
cd ..
node dist/mmar-server/index.js

# 3. Start web clients (in separate terminals)
cd mmar-metamodeling-client && npm start   # port 8070
cd mmar-modeling-client && npm start        # port 8080

Una vez en funcionamiento, los siguientes servicios están disponibles:

Verifique que la API esté activa visitando http://localhost:8000/login en su navegador. Debería ver una página de inicio de sesión. Credenciales por defecto: admin / admin.

Paso 2: Clonar y construir el servidor MCP

git clone https://github.com/ProTech001/mmar-mcp-server.git
cd mmar-mcp-server
npm install
npm run build

El paso npm run build compila TypeScript a JavaScript en la carpeta dist/. Este paso es necesario para que el servidor pueda ejecutarse.

Paso 3: Verificar la instalación

Ejecute el conjunto de pruebas de extremo a extremo para confirmar que todo funciona:

npm test

Esto inicia el servidor MCP como un proceso hijo y envía mensajes JSON-RPC a través de STDIO, exactamente como lo haría un host MCP real. Prueba el handshake, la autenticación, el listado de herramientas, la lectura de recursos, la obtención de prompts y un ciclo completo de crear/verificar/eliminar.

Salida esperada (todas las pruebas deberían pasar):

==============================================
  MM-AR MCP Server — End-to-End Test
==============================================

  ✅ PASS  Initialize (handshake)
           → Server: mmar-mcp-server

  ✅ PASS  List Tools
           → 62 tools registered (expected 62)

  ✅ PASS  List Resources
           → 5 resource(s) (expected 5)

  ✅ PASS  Read Platform Info Resource
           → ...

  ...

==============================================
  Results: 16 passed, 0 failed, 16 total
==============================================

Si alguna prueba falla, consulte la sección Solución de problemas a continuación.

Paso 4: Configurar su host MCP

El servidor se ejecuta sobre STDIO. Configure su host MCP para iniciarlo como un subproceso.

Cursor IDE — cree o edite .cursor/mcp.json en la raíz de su proyecto:

{
  "mcpServers": {
    "mmar": {
      "command": "node",
      "args": ["/absolute/path/to/mmar-mcp-server/dist/index.js"],
      "env": {
        "MMAR_API_URL": "http://localhost:8000"
      }
    }
  }
}

Claude Desktop — añada al archivo de configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json en macOS):

{
  "mcpServers": {
    "mmar": {
      "command": "node",
      "args": ["/absolute/path/to/mmar-mcp-server/dist/index.js"],
      "env": {
        "MMAR_API_URL": "http://localhost:8000"
      }
    }
  }
}

Reemplace /absolute/path/to/mmar-mcp-server con la ruta real donde clonó el repositorio.

Paso 5: Empezar a usar

Una vez configurado, el host MCP puede invocar cualquiera de las 62 herramientas. Hay tres prompts guiados disponibles para flujos de trabajo comunes:

1. create-metamodel — Crear un nuevo lenguaje de modelado a partir de una descripción en lenguaje natural

2. create-model — Crear una instancia de modelo usando un metamodelo existente

3. analyze-model — Inspeccionar y analizar modelos existentes

Ejemplo: "Usa el prompt create-metamodel para crear un lenguaje de modelado de Red de Petri con nodos Place, nodos Transition y conexiones Arc."

Configuración

El servidor lee una variable de entorno:

Establézcala a través de su shell, la configuración del host MCP (ver Paso 4), o en línea:

MMAR_API_URL=http://your-host:8000 node dist/index.js

Catálogo de herramientas

Todas las 62 herramientas tienen el prefijo mmar_ y se agrupan en tres categorías:

Autenticación (3 herramientas)

Operaciones de metamodelo (26 herramientas)

Operaciones de instancia (33 herramientas)

Todos los nombres de herramientas llevan el prefijo mmar_ (por ejemplo, mmar_create_class). El prefijo se omite en la tabla anterior para facilitar la lectura.

Recursos

Estructura del proyecto

mmar-mcp-server/
├── src/
│   ├── index.ts              # Entry point (STDIO transport)
│   ├── server.ts             # MCP server setup and capability registration
│   ├── config.ts             # Configuration (reads MMAR_API_URL)
│   ├── api-client.ts         # MM-AR REST API client with JWT auth and retry logic
│   ├── tools/
│   │   ├── index.ts          # Tool registration hub
│   │   ├── auth.tools.ts     # Authentication tools (3)
│   │   ├── meta.tools.ts     # Metamodel CRUD tools (26)
│   │   └── instance.tools.ts # Instance CRUD tools (33)
│   ├── resources/
│   │   └── index.ts          # Resource definitions (5)
│   └── prompts/
│       └── index.ts          # Prompt definitions (3)
├── test-mcp.mjs              # End-to-end test suite
├── test-data/                 # Example payloads for MCP Inspector testing
│   ├── README.md
│   ├── example-ER-diagram-metamodel.json
│   └── example-petri-net-metamodel.json
├── package.json
├── tsconfig.json
└── .gitignore

Entorno de evaluación reproducible

Ensayos controlados (no chat de Cursor). Empiece aquí:

→ experiments/README.md — configuración, cómo ejecutar, dónde está el JSON
→ experiments/EVALUATION-PROCEDURE.md — protocolo de aislamiento / puntuación
→ experiments/harness-results/PRELIMINARY-RESULTS.md — resultados preliminares de Red de Petri (6 ensayos)

cd experiment-harness
npm install
cp .env.example .env   # add ANTHROPIC_API_KEY; never commit .env

export MMAR_API_URL=http://127.0.0.1:8000
curl -s -o /dev/null -w "API %{http_code}\n" http://127.0.0.1:8000/login   # must be 200

npm run one -- --phase metamodel --language petri-net --trial a
npm run one -- --phase instance --language petri-net --trial a
npm run scoreboard
open ../experiments/harness-results/scoreboard.html

Prefiera 127.0.0.1 sobre localhost si ve rechazo de conexión. Vuelva a ejecutar npm run scoreboard después de nuevos ensayos.

npm run pilot                 # scorer self-test
npm run pilot -- --with-api   # + reset + MCP dry-run + GT seed (API must be up)

Pruebas con MCP Inspector

Para depuración interactiva, puede usar MCP Inspector:

npm run inspect

Esto abre una interfaz web donde puede explorar herramientas, llamarlas manualmente e inspeccionar las cargas útiles de solicitud/respuesta. Consulte test-data/README.md para instrucciones paso a paso y ejemplos de cargas útiles.

Solución de problemas

ECONNREFUSED o "No se puede conectar con la API de MM-AR"

La plataforma MM-AR no está en ejecución o no es accesible en la URL configurada.

1. Compruebe que los contenedores Docker estén en ejecución: docker compose ps

2. Verifique que la API esté activa: curl http://localhost:8000/login

3. Si usa una URL personalizada, asegúrese de que MMAR_API_URL esté configurada correctamente

"El puerto 8000 ya está en uso"

Otro proceso está usando el puerto 8000. Detenga ese proceso o configure la plataforma MM-AR para que use un puerto diferente (consulte la documentación de mmar-docker-installation).

Las pruebas fallan en "Iniciar sesión como admin"

Es posible que la base de datos de MM-AR aún no esté completamente inicializada. Los contenedores Docker necesitan unos segundos después del inicio para completar la inicialización de la base de datos. Espere 10-15 segundos después de docker compose up y vuelva a intentarlo.

"No se encuentra el módulo dist/index.js"

Necesita compilar el código fuente TypeScript primero:

npm run build

El host MCP no detecta el servidor

• Asegúrese de que la ruta en la configuración de su host MCP apunte a la ruta absoluta de dist/index.js

• Reinicie el host MCP después de cambiar la configuración

• Compruebe que Node.js v18+ esté instalado: node --version

Repositorios relacionados

• mmar — Repositorio principal de la plataforma MM-AR

• mmar-docker-installation — Configuración basada en Docker para la plataforma MM-AR completa

• mmar-server — Servidor de API REST de MM-AR

Licencia

ISC

Citación

Si utiliza este software en su investigación, por favor cite:

@inproceedings{chima2026mmar-mcp,
  title={Agentic Creation of Modeling Languages: Extending the MM-AR Metamodeling Platform with MCP},
  author={Chima, Prosper and Fill, Hans-Georg and Curty, Simon},
  booktitle={Proceedings of the International Conference on Conceptual Modeling (ER), Demos and Posters},
  year={2026}
}