# @null-pointer/mcp-archimate
[](https://badge.fury.io/js/%40null-pointer%2Fmcp-archimate)
[](https://opensource.org/licenses/MIT)
A Model Context Protocol (MCP) server that generates ArchiMate 3.2 enterprise architecture diagrams. This server enables AI assistants like Claude to create, validate, and visualize ArchiMate models through natural language interactions.
## What is ArchiMate?
ArchiMate is an open standard for enterprise architecture modeling that provides a visual language for describing, analyzing, and communicating enterprise architectures. It covers business, application, technology, and implementation domains across multiple architectural layers.
## Features
- **Complete ArchiMate 3.2 Support**: All 55+ element types across 7 architectural layers
- **Intelligent Validation**: Ensures diagram compliance with ArchiMate 3.2 specification
- **Mermaid Diagram Generation**: Creates beautiful, shareable diagrams
- **ArchiMate XML Export**: Generates ArchiMate 3.0 Open Exchange Format XML
- **Case-Insensitive Operations**: Flexible element and relationship naming
- **MCP Integration**: Seamless integration with Claude Desktop and other MCP clients
## Quick Start
### Installation
Install the package globally to use as an MCP server:
```bash
npm install -g @null-pointer/mcp-archimate
```
Or install locally in your project:
```bash
npm install @null-pointer/mcp-archimate
```
### Running the MCP Server
Start the server directly:
```bash
npx -y @null-pointer/mcp-archimate
```
Or if installed globally:
```bash
mcp-archimate
```
### Prerequisites
- Node.js (v16 or higher)
### Claude Desktop Integration
1. **Locate your Claude Desktop config file**:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
2. **Add the MCP server configuration**:
```json
{
"mcpServers": {
"archimate": {
"command": "npx",
"args": ["-y", "@null-pointer/mcp-archimate"]
}
}
}
```
Or if installed globally:
```json
{
"mcpServers": {
"archimate": {
"command": "mcp-archimate"
}
}
}
```
3. **Restart Claude Desktop** to load the new MCP server
## Available Tools
The MCP server provides four main tools:
### 1. `generate_archimate_diagram`
Creates Mermaid diagrams from ArchiMate elements and relationships.
### 2. `validate_archimate_model`
Validates models against ArchiMate 3.2 specification rules.
### 3. `list_archimate_elements`
Lists available element types, optionally filtered by layer.
### 4. `list_archimate_relationships`
Lists all available relationship types.
## Usage Examples
### Basic Business Process Diagram
**Prompt**: "Create an ArchiMate diagram showing a customer ordering process with a customer actor, ordering process, and order management application"
**Expected Output**: A Mermaid diagram showing:
- Business Actor (Customer)
- Business Process (Ordering Process)
- Application Component (Order Management System)
- Appropriate relationships between them
### Application Architecture
**Prompt**: "Design an e-commerce application architecture with a web interface, API service, database, and payment gateway"
**Expected Elements**:
- Application Interface (Web UI)
- Application Service (API Service)
- Data Object (Customer Data, Order Data)
- Technology Service (Payment Gateway)
- Node (Database Server)
### Technology Infrastructure
**Prompt**: "Show me the technology infrastructure for a cloud-based system with load balancer, web servers, application servers, and database cluster"
**Expected Elements**:
- Device (Load Balancer)
- Node (Web Servers, App Servers)
- Technology Service (Database Service)
- Technology Collaboration (Cluster Communication)
## Sample Prompts for Claude
Here are effective prompts to use with Claude when the MCP server is configured:
### Discovery and Learning
```
"What ArchiMate elements are available in the business layer?"
"Show me all the relationship types I can use"
"What's the difference between a business process and business function?"
```
### Simple Diagrams
```
"Create a basic ArchiMate diagram showing how users interact with a mobile app"
"Design a simple business process diagram for customer onboarding"
"Show me the technology stack for a typical web application"
```
### Complex Scenarios
```
"Create an ArchiMate model for a digital banking transformation showing business processes, applications, and technology infrastructure"
"Design an enterprise architecture diagram for a retail company showing customer journey, supporting applications, and underlying technology"
"Model a cloud migration scenario showing current on-premise architecture and target cloud architecture"
```
### Validation and Analysis
```
"Validate this ArchiMate model and tell me if there are any specification violations"
"Check if a business actor can have a realization relationship with an application service"
"What relationships are valid between a business process and application component?"
```
## ArchiMate Layers and Elements
### Motivation Layer
Elements for describing stakeholder concerns, goals, and requirements
- Stakeholder, Driver, Assessment, Goal, Outcome, Principle, Requirement, Constraint
### Strategy Layer
Elements for strategic planning and capability modeling
- Resource, Capability, Value Stream, Course of Action
### Business Layer
Elements for business processes, actors, and services
- Business Actor, Business Role, Business Collaboration, Business Interface, Business Process, Business Function, Business Interaction, Business Event, Business Service, Business Object, Contract, Representation, Product
### Application Layer
Elements for application components and services
- Application Component, Application Collaboration, Application Interface, Application Function, Application Interaction, Application Process, Application Event, Application Service, Data Object
### Technology Layer
Elements for technology infrastructure and platforms
- Node, Device, System Software, Technology Collaboration, Technology Interface, Technology Function, Technology Process, Technology Interaction, Technology Event, Technology Service, Path, Communication Network, Artifact
### Physical Layer
Elements for physical facilities and equipment
- Equipment, Facility, Distribution Network, Material
### Implementation & Migration Layer
Elements for transformation planning
- Work Package, Deliverable, Implementation Event, Plateau, Gap
## Relationship Types
ArchiMate defines several relationship categories:
### Structural Relationships
- **Composition**: Part-of relationships
- **Aggregation**: Groups of elements
- **Assignment**: Allocation of behavior/structure
- **Realization**: Implementation relationships
### Dependency Relationships
- **Serving**: Service provision
- **Access**: Data/object access
- **Influence**: Impact relationships
### Dynamic Relationships
- **Triggering**: Temporal/causal sequences
- **Flow**: Information/material transfer
### Other Relationships
- **Specialization**: Generalization/specialization
- **Association**: Generic connections
## Best Practices
### When Creating Diagrams
1. **Start Simple**: Begin with core elements and add detail progressively
2. **Use Proper Layers**: Respect ArchiMate's layered architecture
3. **Validate Early**: Check relationships against the specification
4. **Name Clearly**: Use descriptive names for elements
5. **Focus Purpose**: Create diagrams with specific stakeholder viewpoints
### Effective Prompting
1. **Be Specific**: Mention the domain (business, application, technology)
2. **Provide Context**: Describe the scenario or use case
3. **Request Validation**: Ask Claude to validate complex models
4. **Iterate**: Build diagrams incrementally with feedback
### Common Patterns
- **Layered View**: Show relationships between business, application, and technology
- **Process Flow**: Model business processes with supporting applications
- **Service Orientation**: Focus on services and their relationships
- **Capability Mapping**: Link business capabilities to supporting elements
## Development
### Running in Development Mode
```bash
npm run dev
```
### Testing the MCP Server
```bash
node test-mcp.js
```
### Project Structure
```
src/
├── core/ # Core ArchiMate element classes
├── generator/ # Diagram generation logic
├── models/ # Type definitions and enums
├── validator/ # ArchiMate specification validation
└── server.ts # MCP server implementation
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request
## License
[Add your license information here]
## Resources
- [ArchiMate 3.2 Specification](https://pubs.opengroup.org/architecture/archimate32-doc/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Mermaid Documentation](https://mermaid.js.org/)
- [Claude Desktop](https://claude.ai/desktop)
## Support
For issues, questions, or contributions, please visit the project repository or contact the maintainers.
