mcp-archimate

A REST API and MCP (Model Context Protocol) server for querying and modifying ArchiMate models stored in XML or native Archi Tool files.

The API supports multiple simultaneous data sources, each declared in config.json. All data routes are prefixed with the source identifier (/:source_id/).

Data schemas are aligned with the official ArchiMate 3.1 Open Exchange Format XSDs: archimate3_Model.xsd, archimate3_View.xsd, archimate3_Diagram.xsd.

In-memory mutations: Create / update / delete operations modify the model in memory. Changes are lost on server restart unless you call the save endpoint (POST /:source_id/save) to write them back to disk. The API also supports creating new source files and removing sources from the registry.

Purpose

This project provides services for querying and modifying ArchiMate models via:

1. A REST API (Express / Node.js) for programmatic access and modification of elements, relationships, and views

2. An MCP server (Model Context Protocol) for integrating models into AI workflows (read and write)

Supported data formats

Configuration (config.json)

The config.json file at the project root declares the data sources to load at startup:

{
  "sources": [
    {
      "id": "open-exchange",
      "name": "Open Exchange Demo",
      "path": "data/open-exchange.xml",
      "format": "oef"
    },
    {
      "id": "archisurance",
      "name": "ArchiSurance",
      "path": "data/archisurance.archimate",
      "format": "archi"
    }
  ]
}

All sources are loaded into memory at startup. You can also create and delete sources at runtime via the API — config.json is updated automatically.

Project structure

.
├── config.json                     # Data source declarations
├── data/
│   ├── open-exchange.xml           # ArchiMate model in Open Exchange format
│   └── archisurance.archimate      # ArchiMate model in native Archi Tool format
├── src/
│   ├── schemas.ts                  # TypeScript interfaces: output types + CRUD input types
│   ├── model.ts                    # Open Exchange XML parser (fast-xml-parser)
│   ├── archi-parser.ts             # Native Archi Tool format parser (.archimate)
│   ├── serializer.ts               # XML serializers (ArchiModel → OEF XML / Archi format)
│   ├── registry.ts                 # Data source registry + addSource / removeSource
│   ├── app.ts                      # Express app, REST routes, and MCP server
│   └── main.ts                     # HTTP server entry point
├── tests/
│   └── api.test.ts                 # Unit and integration tests (206 tests)
├── dist/                           # Compiled JavaScript output (generated by tsc)
├── package.json                    # Node.js dependencies
├── tsconfig.json                   # TypeScript configuration
├── Dockerfile                      # Docker image (Node.js 22)
├── docker-compose.yml              # Compose with volumes and watch
└── README.md                       # This file

ArchiMate overview

ArchiMate is an enterprise architecture modelling standard maintained by The Open Group. It provides a common language for describing an architecture from multiple coherent viewpoints.

The model is organised into ArchiMate layers:

• Strategy: capabilities, resources, courses of action, goals

• Business: actors, roles, processes, functions, business services

• Application: application components, interfaces, application services, flows

• Technology: nodes, systems, technical services, networks, infrastructure

• Physical: equipment and materials

• Motivation: goals, principles, constraints, requirements

• Implementation and Migration: deliverables, plateaus, gaps, work packages

Elements are linked by standardised relationships (Serving, Access, Composition, Aggregation, Realization, Assignment, Flow, Influence, Association, etc.).

Data schemas (ArchiMate 3.1 XSD alignment)

All API fields follow the names defined in the official XSDs.

Element (archimate3_Model.xsd — ElementType)

Relationship (archimate3_Model.xsd — RelationshipType)

View (archimate3_View.xsd — ViewType)

Diagram node (archimate3_Diagram.xsd — ViewNodeType)

Diagram connection (archimate3_Diagram.xsd — ConnectionType)

Visual style (archimate3_Diagram.xsd — StyleType / RGBColorType)

Colours are exposed as decomposed RGB values (r, g, b: 0–255) as defined in the XSD.

Valid element types (archimate3_Model.xsd — ElementTypeEnum)

62 types in total, organised by layer:

Valid relationship types (archimate3_Model.xsd — RelationshipTypeEnum)

Composition, Aggregation, Assignment, Realization, Serving, Access, Influence, Triggering, Flow, Specialization, Association

REST API

The API is available at http://localhost:8000.

Interactive documentation (Swagger UI)

The spec is generated dynamically from code: ArchiMate 3.1 type enums are always in sync with the constants in src/schemas.ts.

Source management endpoints

SourceCreateInput (all fields required):

{
  "id": "my-model",
  "name": "My Model",
  "path": "data/my-model.xml",
  "format": "oef"
}

format must be "oef" (Open Exchange XML) or "archi" (native Archi Tool format).

POST /:source_id/save response:

{ "saved": true, "path": "data/my-model.xml" }

Per-source endpoints (/:source_id/) — Read

Replace :source_id with the source identifier declared in config.json (e.g. open-exchange, archisurance).

Per-source endpoints (/:source_id/) — Write (in memory)

Request body — Elements

ElementCreateInput (POST — name and type are required):

{
  "name": "My Application",
  "type": "ApplicationComponent",
  "documentation": "Optional description",
  "properties": [
    { "property_definition_ref": "status", "value": "active" }
  ]
}

ElementUpdateInput (PUT — all fields are optional; only provided fields are modified):

{
  "name": "New name",
  "documentation": null
}

Request body — Relationships

RelationshipCreateInput (POST — type, source, and target are required):

{
  "type": "Association",
  "source": "source-element-id",
  "target": "target-element-id",
  "name": "Optional name",
  "is_directed": true
}

RelationshipUpdateInput (PUT — all fields are optional):

{
  "name": "New name",
  "documentation": "New description"
}

HTTP status codes: 201 created, 204 deleted, 404 not found, 422 invalid type or unknown reference.

Type validation: an invalid type (not in the ArchiMate 3.1 set) returns HTTP 422. An unknown source_id returns HTTP 404.

Cascade on delete: deleting an element also removes all relationships that reference it (as source or target).

Example requests

# List configured sources
curl http://localhost:8000/sources

# Model metadata for the open-exchange source
curl http://localhost:8000/open-exchange/

# ApplicationComponent elements from archisurance
curl "http://localhost:8000/archisurance/elements?type=ApplicationComponent"

# Create an element in open-exchange
curl -X POST http://localhost:8000/open-exchange/elements \
  -H "Content-Type: application/json" \
  -d '{"name": "My Service", "type": "ApplicationService"}'

# Update an element's name
curl -X PUT http://localhost:8000/open-exchange/elements/element-id \
  -H "Content-Type: application/json" \
  -d '{"name": "New name"}'

# Create a relationship between two elements
curl -X POST http://localhost:8000/open-exchange/relationships \
  -H "Content-Type: application/json" \
  -d '{"type": "Serving", "source": "source-id", "target": "target-id"}'

# Delete an element (and its relationships)
curl -X DELETE http://localhost:8000/open-exchange/elements/element-id

# Save in-memory model back to disk
curl -X POST http://localhost:8000/open-exchange/save

# Create a new source (blank model written to data/new-model.xml)
curl -X POST http://localhost:8000/sources \
  -H "Content-Type: application/json" \
  -d '{"id": "new-model", "name": "New Model", "path": "data/new-model.xml", "format": "oef"}'

# Remove a source from the registry and delete its file
curl -X DELETE "http://localhost:8000/sources/new-model?delete_file=true"

# View detail in open-exchange
curl http://localhost:8000/open-exchange/views/view-id

Deployment

Running locally

# Install dependencies
npm install

# Start in development mode (with hot reload)
npm run dev

# Start in production mode
npm start

Running via Docker (Docker Hub image)

Published image: lacrif/mcp-archimate:latest

# Run with data and configuration bundled in the image
docker run -p 8000:8000 lacrif/mcp-archimate:latest

# Mount your own configuration and data
docker run -p 8000:8000 \
    -v /path/to/config.json:/app/config.json:ro \
    -v /path/to/data:/app/data:ro \
    lacrif/mcp-archimate:latest

Running via local Docker build

# Build the image locally
docker build -t mcp-archimate:local .

# Run with local volumes (config + data)
docker run -p 8000:8000 \
    -v ./config.json:/app/config.json:ro \
    -v ./data:/app/data:ro \
    mcp-archimate:local

Docker Compose (volumes + watch)

The docker-compose.yml file automatically mounts config.json and the data/ directory as volumes, and enables automatic reloading via docker compose watch.

# Build and start the service with mounted volumes
docker compose up --build

# Watch mode: automatic rebuild or sync on file changes
docker compose watch

Watch behaviour:

Using your own models

To point the API at your own ArchiMate files:

1. Place your files in data/ (.xml OEF or .archimate Archi Tool)

2. Edit config.json to declare your sources

3. Restart the server (or let docker compose watch do it)

{
  "sources": [
    {
      "id": "my-model",
      "name": "My Enterprise Architecture",
      "path": "data/my-model.xml",
      "format": "oef"
    }
  ]
}

MCP server

The project exposes an MCP server (read and write), mounted inside the same Express application.

MCP endpoint

• Base URL: http://localhost:8000/mcp

• Transport: streamable-http

Exposed MCP tools

Every tool accepts an optional source_id parameter (default: first configured source).

Read

Write (in-memory changes)

Rendering

File persistence

Tool descriptions include the valid ArchiMate 3.1 types to guide LLMs.

MCP client configuration

The MCP server uses the streamable-http transport at http://localhost:8000/mcp. The server must be running before any MCP client connects.

Claude Code (CLI)

The .mcp.json file at the project root is automatically detected by Claude Code:

{
    "mcpServers": {
        "mcp-archimate": {
            "type": "http",
            "url": "http://localhost:8000/mcp"
        }
    }
}

Or via the CLI:

claude mcp add mcp-archimate http://localhost:8000/mcp --transport http

Claude Desktop

Edit the Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

{
    "mcpServers": {
        "mcp-archimate": {
            "type": "http",
            "url": "http://localhost:8000/mcp"
        }
    }
}

Restart Claude Desktop after editing.

VS Code / GitHub Copilot

The .vscode/mcp.json file is already included in the project:

{
    "servers": {
        "mcp-archimate": {
            "url": "http://localhost:8000/mcp",
            "type": "http"
        }
    },
    "inputs": []
}

Enable MCP support in VS Code:

// .vscode/settings.json
{
    "github.copilot.chat.mcp.enabled": true
}

The MCP tools then appear in the Copilot Chat panel (tool icon).

OpenAI Codex CLI

In the Codex configuration file (~/.codex/config.toml):

[mcp_servers.mcp-archimate]
type = "http"
url = "http://localhost:8000/mcp"

Tests

Tests are located in tests/api.test.ts (181 tests) and cover:

• Unit tests: conversion helpers, colour conversion, XSD constants, CRUD functions (createElement, updateElement, deleteElement, createRelationship, updateRelationship, deleteRelationship), serializers (serializeToOEF, serializeToArchi with round-trip tests), saveModel, listSources

• Integration tests: all REST endpoints (/sources, CRUD cycles for elements and relationships, POST /sources, DELETE /sources/:id, POST /:source_id/save), MCP service (initialize + tools/list with all 18 tools)

Running tests locally

# Install dependencies
npm install

# Run tests
npm test

Quick reference

• Data format: ArchiMate 3.1 Open Exchange XML and native Archi Tool format

• API: Express (REST)

• MCP server: @modelcontextprotocol/sdk (streamable-http)

• Runtime: Node.js 22 / TypeScript

• Default port: 8000

• MCP endpoint: http://localhost:8000/mcp (streamable-http)