# MCP ArchiMate Server

A Model Context Protocol (MCP) server for ArchiMate/CoArchi model interaction. Works with VS Code Copilot, Cursor, and other MCP-compatible clients.

## Overview

MCP ArchiMate Server enables AI assistants to read and write ArchiMate models stored in CoArchi XML format. Query elements, create relationships, design diagrams, and sync changes to Git—all through natural language.

**Repository:** https://github.com/dqxorg/mcp-archimate

## Features

- Read and search ArchiMate models (CoArchi XML format)
- Create elements, relationships, and diagrams
- Generate models from architecture documentation
- Auto-add visual connections to diagrams
- Commit and push changes to Git branches
- Full ArchiMate 3.2 schema support

## Installation

### Quick Install (Node.js - Recommended)

**1. Install via npm:**
```bash
npm install -g archimate-chloe-mcp
```

**2. Add to VS Code settings** (`Ctrl+,` → click `{}` icon):
```json
{
  "mcp": {
    "servers": {
      "archimate": {
        "command": "archimate-chloe-mcp",
        "env": {
          "ARCHIMATE_MODEL_PATH": "/path/to/your/archimate/model"
        }
      }
    }
  }
}
```

**3. Restart VS Code**

### Alternative: MCP CLI

```bash
mcp add archimate -- archimate-chloe-mcp
```

### Alternative: Clone from GitHub

```bash
git clone https://github.com/dqxorg/mcp-archimate.git
cd mcp-archimate
npm install
```

Then add to VS Code settings:
```json
{
  "mcp": {
    "servers": {
      "archimate": {
        "command": "node",
        "args": ["/path/to/mcp-archimate/server.js"],
        "env": {
          "ARCHIMATE_MODEL_PATH": "/path/to/your/archimate/model"
        }
      }
    }
  }
}
```

## Configuration

Set the `ARCHIMATE_MODEL_PATH` environment variable to your CoArchi model directory:

```bash
# Linux/Mac
export ARCHIMATE_MODEL_PATH=~/Documents/Archi/models/my-architecture

# Windows
set ARCHIMATE_MODEL_PATH=C:\Users\chloe\Documents\Archi\models\my-architecture
```

## Running the Server

### Python

```bash
python -m archimate_mcp.server
```

### Node.js

```bash
node server.js
```

## VS Code Copilot Setup

After installation, use the `archimate-chloe-mcp` command:

```json
{
  "mcp": {
    "servers": {
      "archimate": {
        "command": "archimate-chloe-mcp",
        "env": {
          "ARCHIMATE_MODEL_PATH": "/path/to/your/archimate/model"
        }
      }
    }
  }
}
```

Set `ARCHIMATE_MODEL_PATH` to your CoArchi model folder (the one with `model/business/`, `model/application/`, etc.).

**Restart VS Code** after adding the configuration.

### Verify Setup

Ask Copilot:
- "What's in my application layer?"
- "Show me all elements"

If you get a response, the MCP server is connected.

## Available Tools

### Model Operations

| Tool | Description |
|------|-------------|
| `get_model_summary` | Get model statistics by layer and type |
| `list_elements_by_layer` | List elements in business/application/technology layer |
| `search_elements` | Search elements by name |
| `get_element` | Get element details by ID |
| `validate_model` | Check model for errors |

### Model Modification

| Tool | Description |
|------|-------------|
| `create_element` | Create a new element |
| `create_relationship` | Create a relationship between elements |
| `create_diagram` | Create a new diagram/view |
| `add_element_to_diagram` | Add element to existing diagram |
| `add_connection_to_diagram` | Add visual connection line |
| `add_connections_from_relationships` | Auto-add all connections |
| `design_from_document` | Generate model from markdown |
| `commit_and_push` | Git commit and push |

### Schema Discovery

| Tool | Description |
|------|-------------|
| `list_available_element_types` | List all ArchiMate element types |
| `list_relationship_types` | List all relationship types |

## Usage Examples

```
User: What's in my application layer?
→ Returns all application components and functions

User: Show me the API component
→ Returns element details with relationships

User: Create a BusinessActor for Product Owner
→ Creates new element in business layer

User: Connect the API to the Database with AccessRelationship
→ Creates relationship between elements

User: Add all connections to the C1 diagram
→ Adds visual connection lines for all relationships

User: Design from C:/docs/architecture.md
→ Generates full model from markdown document
```

## ArchiMate Element Types

### Business Layer
`BusinessActor`, `BusinessRole`, `BusinessCollaboration`, `BusinessProcess`, `BusinessFunction`, `BusinessService`, `BusinessObject`

### Application Layer
`ApplicationComponent`, `ApplicationFunction`, `ApplicationService`, `DataObject`

### Technology Layer
`Node`, `Device`, `SystemSoftware`, `TechnologyService`, `Artifact`

## Relationship Types

| Type | Use Case |
|------|----------|
| `ServingRelationship` | Service provided to actor |
| `FlowRelationship` | Data/control flow |
| `AccessRelationship` | Read/write data |
| `AssignmentRelationship` | Actor assigned to element |
| `RealizationRelationship` | Implementation of specification |
| `CompositionRelationship` | Strong whole-part |
| `AggregationRelationship` | Whole-part |
| `TriggeringRelationship` | Event trigger |

## Model Structure

The server expects a CoArchi model structure:

```
model-repository/
└── your-model/
    └── model/
        ├── business/          # Business layer elements
        ├── application/       # Application layer elements
        ├── technology/        # Technology layer elements
        ├── relations/         # All relationships
        └── diagrams/          # Views and diagrams
```

## Git Integration

The `commit_and_push` tool automatically:
1. Stages all changes
2. Commits with your message
3. Creates a new branch (`archi/{user}-{date}`)
4. Pushes to origin

## Troubleshooting

**Model not loading?**
- Verify `ARCHIMATE_MODEL_PATH` is set correctly
- Check model has proper folder structure (`model/business/`, `model/application/`, etc.)

**Connections not visible in diagram?**
- Use `add_connections_from_relationships` tool
- Press F5 in CoArchi to reload

**Element not found?**
- Use `search_elements` to find the correct ID
- Check if element exists in the model

## License

MIT

Add to your VS Code settings (`settings.json`):

```json
{
  "mcpServers": {
    "archimate": {
      "command": "python",
      "args": ["-m", "archimate_mcp.server"],
      "env": {
        "ARCHIMATE_MODEL_PATH": "C:\\path\\to\\your\\archimate\\model"
      }
    }
  }
}
```

## Claude Desktop Integration

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "archimate": {
      "command": "python",
      "args": ["-m", "archimate_mcp.server"],
      "env": {
        "ARCHIMATE_MODEL_PATH": "/path/to/your/archimate/model"
      }
    }
  }
}
```

## Development

```bash
# Create virtual environment
python -m venv .venv

# Activate
source .venv/Scripts/activate  # Linux/Mac
.venv\Scripts\activate        # Windows

# Install dependencies
pip install fastmcp

# Run tests
python -c "import sys; sys.path.insert(0, '.'); from archimate_mcp.server import get_model; m = get_model(); print(m.get_summary())"
```

## License

MIT License

## Repository

https://github.com/dqxorg/mcp-archimate