mcp-archimate

A REST API and MCP (Model Context Protocol) server for querying and modifying ArchiMate 3.1 models stored in the Open Exchange File format (.xml).

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)

Related MCP server: ArchiScribe MCP Server

Configuration (config.json)

To point the API at your own ArchiMate files:

1. Place your file in data/ in the ArchiMate 3.1 Open Exchange XML format (.xml)

2. Edit config.json to declare it

3. Restart the server

{
  "path": "data/archisurance.xml",
  "name": "ArchiSurance"
}

The format is the one defined by The Open Group XSDs archimate3_Model.xsd, archimate3_View.xsd and archimate3_Diagram.xsd (provided under models/). Archi can produce this file via File → Export → Open Exchange XML or via the CLI archi --xmlexchange.export <path>.

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.

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

MCP Tools

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"

Deployment

# Install dependencies
npm install

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

# Start in production mode
npm start

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), parser/serializer (parseOpenExchange, serializeToOpenExchange with round-trip tests), saveModel

• Integration tests: all REST endpoints (CRUD cycles for elements/relationships/views, /save, /views/:id/image), MCP service (initialize + tools/list with all registered tools)

Running tests locally

# Install dependencies
npm install

# Run tests
npm test

# Run tests coverage
npm test -- --coverage

Quick reference

• Data format: ArchiMate 3.1 Open Exchange XML (.xml)

• API: Express (REST)

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

• Runtime: Node.js 24 / TypeScript