# mcp-archimate

[![CI](https://github.com/lacrif/mcp-archimate/actions/workflows/npm-ci.yml/badge.svg)](https://github.com/lacrif/mcp-archimate/actions/workflows/npm-ci.yml)
[![Codecov](https://codecov.io/github/lacrif/mcp-archimate/graph/badge.svg?token=RZRF5TU53A)](https://codecov.io/github/lacrif/mcp-archimate)
[![Publish](https://github.com/lacrif/mcp-archimate/actions/workflows/npm-publish.yml/badge.svg)](https://github.com/lacrif/mcp-archimate/actions/workflows/npm-publish.yml)
[![npm](https://img.shields.io/npm/v/mcp-archimate)](https://img.shields.io/npm/v/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)

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

```json
{
  "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)

| Path | Description |
| ---- | ----------- |
| [`/docs`](http://localhost:8000/docs) | Swagger UI — interactive exploration of all routes |
| [`/openapi.json`](http://localhost:8000/openapi.json) | OpenAPI 3.0 spec as JSON |

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

| Tool | Description |
| ---- | ----------- |
| `get_model_info` | Global model metadata |
| `list_element_types` | Element types present in the model |
| `list_elements` | Elements with optional filters (`element_type`, `name`) |
| `get_element` | Element detail by `element_id` |
| `list_relationship_types` | Relationship types present in the model |
| `list_relationships` | Relationships with filters (`rel_type`, `source_id_filter`, `target_id`) |
| `get_relationship` | Relationship detail by `relationship_id` |
| `list_views` | Views with `node_count`, `connection_count`, `viewpoint` |
| `get_view` | View detail with nodes, connections, and styles |

#### Write (in-memory changes)

| Tool | Required parameters | Description |
| ---- | ------------------- | ----------- |
| `create_element` | `name`, `type` | Create an ArchiMate element |
| `update_element` | `element_id` | Update an element (partial patch) |
| `delete_element` | `element_id` | Delete an element and its relationships |
| `create_relationship` | `type`, `source`, `target` | Create a relationship between two elements |
| `update_relationship` | `relationship_id` | Update a relationship (partial patch) |
| `delete_relationship` | `relationship_id` | Delete a relationship |

#### Rendering

| Tool | Required parameters | Description |
| ---- | ------------------- | ----------- |
| `render_view` | `view_id` | Generate an SVG or PNG image of a view (`format`: `"svg"` (default) or `"png"`). PNG requires the optional `sharp` package (`npm install sharp`). The MCP response uses the `image` content type so AI clients can display it inline. |

#### File persistence

| Tool | Required parameters | Description |
| ---- | ------------------- | ----------- |
| `save_model` | — | Write the in-memory model back to its source file on disk |
| `create_source` | `id`, `name`, `path`, `format` | Create a new blank model file and register it as a source |
| `delete_source` | `source_id` | Remove a source from the registry (set `delete_file: true` to also delete the file) |

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:

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

Or via the CLI:

```bash
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`

```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:

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

Enable MCP support in VS Code:

```json
// .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`):

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

## Deployment

```bash
# 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

```bash
# 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