MMAR-MCP Server

Ein MCP-Server, der große Sprachmodelle mit der MM-AR-Metamodellierungsplattform verbindet und es Benutzern ermöglicht, vollständige Metamodelle und Modellinstanzen durch natürliche Sprachinteraktion zu erstellen.

Übersicht

MMAR-MCP stellt die Fähigkeiten der MM-AR-Plattform über das Model Context Protocol bereit:

• 62 Werkzeuge für Authentifizierung, Metamodell-CRUD und Instanz-CRUD-Operationen

• 5 Ressourcen mit Dokumentation zur Plattformarchitektur, VizRep-Vorlagen, dem Metamodell-Schema, Attributtypen und einem Referenzmetamodell

• 3 Prompts mit geführten Workflows zur Metamodellerstellung, Instanzerstellung und Modellanalyse

Der Server kommuniziert über STDIO-Transport und funktioniert mit jedem MCP-kompatiblen Host (Cursor, Claude Desktop oder jedem Client, der die MCP-Spezifikation implementiert).

Related MCP server: ParaView-MCP

Voraussetzungen

Schnellstart

Befolgen Sie diese fünf Schritte, um von null zu einer funktionierenden Einrichtung zu gelangen.

Schritt 1: Starten Sie die MM-AR-Plattform

Option A: Vollständige Docker-Bereitstellung (empfohlen für die Ersteinrichtung)

Klonen und starten Sie den vollständigen MM-AR-Stack mit Docker:

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

Warten Sie, bis alle Container gesund sind. Sie können dies überprüfen mit:

docker compose ps

Option B: Hybride Bereitstellung (PostgreSQL in Docker, Dienste lokal)

Dies ist das Setup, das während der Experimente der Abschlussarbeit verwendet wurde. Es erfordert das Klonen des Haupt-MM-AR-Repositorys:

# 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

Sobald es läuft, sind die folgenden Dienste verfügbar:

Überprüfen Sie, ob die API läuft, indem Sie http://localhost:8000/login in Ihrem Browser aufrufen. Sie sollten eine Anmeldeseite sehen. Standard-Anmeldedaten: admin / admin.

Schritt 2: Klonen und Erstellen des MCP-Servers

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

Der Schritt npm run build kompiliert TypeScript in JavaScript im Ordner dist/. Dieser Schritt ist erforderlich, bevor der Server ausgeführt werden kann.

Schritt 3: Überprüfen der Installation

Führen Sie die End-to-End-Testsuite aus, um zu bestätigen, dass alles funktioniert:

npm test

Dies startet den MCP-Server als Kindprozess und sendet JSON-RPC-Nachrichten über STDIO, genau wie ein echter MCP-Host. Es testet den Handshake, die Authentifizierung, die Werkzeugliste, das Lesen von Ressourcen, das Abrufen von Prompts und einen vollständigen Erstellen/Überprüfen/Löschen-Zyklus.

Erwartete Ausgabe (alle Tests sollten bestehen):

==============================================
  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
==============================================

Wenn ein Test fehlschlägt, lesen Sie den Abschnitt Fehlerbehebung unten.

Schritt 4: Konfigurieren Sie Ihren MCP-Host

Der Server läuft über STDIO. Konfigurieren Sie Ihren MCP-Host, um ihn als Unterprozess zu starten.

Cursor IDE — erstellen oder bearbeiten Sie .cursor/mcp.json in Ihrem Projektstammverzeichnis:

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

Claude Desktop — fügen Sie Ihrer Claude Desktop-Konfigurationsdatei hinzu (~/Library/Application Support/Claude/claude_desktop_config.json unter macOS):

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

Ersetzen Sie /absolute/path/to/mmar-mcp-server durch den tatsächlichen Pfad, in den Sie das Repository geklont haben.

Schritt 5: Loslegen

Sobald konfiguriert, kann der MCP-Host jedes der 62 Werkzeuge aufrufen. Drei geführte Prompts sind für häufige Arbeitsabläufe verfügbar:

1. create-metamodel — Erstellen Sie eine neue Modellierungssprache aus einer natürlichen Sprachbeschreibung

2. create-model — Erstellen Sie eine Modellinstanz mit einem vorhandenen Metamodell

3. analyze-model — Untersuchen und analysieren Sie vorhandene Modelle

Beispiel: "Verwenden Sie den create-metamodel-Prompt, um eine Petri-Netz-Modellierungssprache mit Place-Knoten, Transition-Knoten und Arc-Verbindungen zu erstellen."

Konfiguration

Der Server liest eine Umgebungsvariable:

Setzen Sie sie über Ihre Shell, die MCP-Host-Konfiguration (siehe Schritt 4) oder inline:

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

Werkzeugkatalog

Alle 62 Werkzeuge haben das Präfix mmar_ und sind in drei Kategorien gruppiert:

Authentifizierung (3 Werkzeuge)

Metamodell-Operationen (26 Werkzeuge)

Instanz-Operationen (33 Werkzeuge)

Alle Werkzeugnamen tragen das Präfix mmar_ (z. B. mmar_create_class). Das Präfix wurde in der obigen Tabelle aus Gründen der Lesbarkeit weggelassen.

Ressourcen

Projektstruktur

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

Reproduzierbare Evaluierungsumgebung

Kontrollierte Versuche (nicht Cursor-Chat). Beginnen Sie hier:

→ experiments/README.md — Einrichtung, Ausführung, wo JSON gespeichert ist → experiments/EVALUATION-PROCEDURE.md — Isolations-/Bewertungsprotokoll → experiments/harness-results/PRELIMINARY-RESULTS.md — Petri-Netz-Vorab (6 Versuche)

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

Bevorzugen Sie 127.0.0.1 gegenüber localhost, wenn Sie eine Verbindungsverweigerung sehen. Führen Sie nach neuen Versuchen erneut npm run scoreboard aus.

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

Testen mit MCP Inspector

Für interaktives Debugging können Sie den MCP Inspector verwenden:

npm run inspect

Dies öffnet eine Weboberfläche, in der Sie Werkzeuge durchsuchen, manuell aufrufen und Anfrage-/Antwort-Payloads überprüfen können. Siehe test-data/README.md für Schritt-für-Schritt-Anleitungen und Beispiel-Payloads.

Fehlerbehebung

ECONNREFUSED oder "Cannot connect to MM-AR API"

Die MM-AR-Plattform läuft nicht oder ist unter der konfigurierten URL nicht erreichbar.

1. Überprüfen Sie, ob Docker-Container laufen: docker compose ps

2. Überprüfen Sie, ob die API läuft: curl http://localhost:8000/login

3. Wenn Sie eine benutzerdefinierte URL verwenden, stellen Sie sicher, dass MMAR_API_URL korrekt gesetzt ist

"Port 8000 already in use"

Ein anderer Prozess verwendet Port 8000. Stoppen Sie entweder diesen Prozess oder konfigurieren Sie die MM-AR-Plattform so, dass sie einen anderen Port verwendet (siehe die mmar-docker-installation-Dokumentation).

Tests schlagen bei "Login as admin" fehl

Die MM-AR-Datenbank ist möglicherweise noch nicht vollständig initialisiert. Die Docker-Container benötigen nach dem Start einige Sekunden, um die Datenbankinitialisierung abzuschließen. Warten Sie 10-15 Sekunden nach docker compose up und wiederholen Sie den Vorgang.

"Cannot find module dist/index.js"

Sie müssen zuerst die TypeScript-Quelle kompilieren:

npm run build

MCP-Host erkennt den Server nicht

• Stellen Sie sicher, dass der Pfad in Ihrer MCP-Host-Konfiguration auf den absoluten Pfad von dist/index.js verweist

• Starten Sie den MCP-Host nach der Änderung der Konfiguration neu

• Überprüfen Sie, ob Node.js v18+ installiert ist: node --version

Verwandte Repositorys

• mmar — Haupt-Repository der MM-AR-Plattform

• mmar-docker-installation — Docker-basierte Einrichtung für die vollständige MM-AR-Plattform

• mmar-server — MM-AR REST-API-Server

Lizenz

ISC

Zitierung

Wenn Sie diese Software in Ihrer Forschung verwenden, zitieren Sie bitte:

@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}
}