@null-pointer/mcp-archimate
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:
npm install -g @null-pointer/mcp-archimate
Or install locally in your project:
npm install @null-pointer/mcp-archimate
Running the MCP Server
Start the server directly:
npx -y @null-pointer/mcp-archimate
Or if installed globally:
mcp-archimate
Prerequisites
- Node.js (v16 or higher)
Claude Desktop Integration
-
Locate your Claude Desktop config file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
- macOS:
-
Add the MCP server configuration:
{ "mcpServers": { "archimate": { "command": "npx", "args": ["-y", "@null-pointer/mcp-archimate"] } } }Or if installed globally:
{ "mcpServers": { "archimate": { "command": "mcp-archimate" } } } -
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
- Start Simple: Begin with core elements and add detail progressively
- Use Proper Layers: Respect ArchiMate's layered architecture
- Validate Early: Check relationships against the specification
- Name Clearly: Use descriptive names for elements
- Focus Purpose: Create diagrams with specific stakeholder viewpoints
Effective Prompting
- Be Specific: Mention the domain (business, application, technology)
- Provide Context: Describe the scenario or use case
- Request Validation: Ask Claude to validate complex models
- 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
npm run dev
Testing the MCP Server
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
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
License
[Add your license information here]
Resources
Support
For issues, questions, or contributions, please visit the project repository or contact the maintainers.