README.md•7.91 kB
# System Designer MCP Server
A Model Context Protocol (MCP) server that provides AI agents with tools to create, validate, and export UML system models. Built with a tool-based approach that empowers LLMs rather than trying to replace their natural language understanding capabilities.
## 📚 Documentation
- [API Reference](./docs/API-REFERENCE.md) - Detailed API documentation for all MCP tools
- [CLI Guide](./docs/CLI-GUIDE.md) - Command-line interface usage and examples
- [Integration Guide](./docs/INTEGRATION-GUIDE.md) - Platform integration instructions
- [Examples](./examples/README.md) - Sample models and use cases
## Features
### Core Tools
- **create_mson_model**: Create and validate MSON models from structured data
- **validate_mson_model**: Validate MSON model consistency and completeness
- **generate_uml_diagram**: Generate UML diagrams in PlantUML and Mermaid formats
- **export_to_system_designer**: Export models to System Designer application format
### Key Capabilities
- ✅ **Tool-Based Architecture**: LLMs handle understanding, server handles validation/formatting
- ✅ **Type Safety**: Comprehensive Zod schema validation for all inputs and outputs
- ✅ **Multiple UML Formats**: Support for both PlantUML and Mermaid diagram generation
- ✅ **System Designer Integration**: Direct export to System Designer macOS application
- ✅ **Comprehensive Testing**: Full test coverage for all tools and functionality
## Installation
### Prerequisites
- [Bun](https://bun.sh/) JavaScript runtime
- Node.js compatibility through Bun
### Setup
```bash
# Clone the repository
git clone <repository-url>
cd system-designer-mcp
# Install dependencies
bun install
# Build the project
bun run build
# Run tests
bun test
```
## Quick Start
### Installation
```bash
# Clone the repository
git clone <repository-url>
cd system-designer-mcp
# Install dependencies
bun install
# Build the project
bun run build
# Run tests
bun test
```
### Using the MCP Server
1. **Start the server**:
```bash
bun run dev
```
2. **Example tool usage**:
```javascript
// Create a MSON model
const model = await mcpClient.callTool('create_mson_model', {
name: 'Student Management System',
type: 'class',
description: 'A system for managing students and courses',
entities: [
{
id: 'student',
name: 'Student',
type: 'class',
attributes: [
{ name: 'id', type: 'string', visibility: 'private' },
{ name: 'name', type: 'string', visibility: 'public' },
],
methods: [{ name: 'enroll', returnType: 'void', visibility: 'public' }],
},
],
relationships: [],
});
// Generate UML diagram
const diagram = await mcpClient.callTool('generate_uml_diagram', {
model: model.content[1].json,
format: 'plantuml',
});
// Export to System Designer
const exported = await mcpClient.callTool('export_to_system_designer', {
model: model.content[1].json,
filePath: './student_system.json',
});
```
### CLI Usage
The server includes a CLI tool for testing and model management:
```bash
# Test System Designer integration
bun run src/cli.ts test-integration
# Export a test model
bun run src/cli.ts export-model MyModel "Test model description"
# Show configuration
bun run src/cli.ts config
```
See the [CLI Guide](./docs/CLI-GUIDE.md) for detailed usage instructions.
### Example MSON Model Structure
```json
{
"id": "student_system",
"name": "Student Management System",
"type": "class",
"description": "A system for managing students and courses",
"entities": [
{
"id": "student",
"name": "Student",
"type": "class",
"attributes": [
{
"name": "id",
"type": "string",
"visibility": "private"
},
{
"name": "name",
"type": "string",
"visibility": "public"
}
],
"methods": [
{
"name": "enroll",
"parameters": [
{
"name": "course",
"type": "Course"
}
],
"returnType": "void",
"visibility": "public"
}
]
}
],
"relationships": [
{
"id": "enrollment",
"from": "student",
"to": "course",
"type": "association",
"multiplicity": {
"from": "1",
"to": "0..*"
},
"name": "enrolls in"
}
]
}
```
## Tool Reference
For detailed API documentation, see the [API Reference](./docs/API-REFERENCE.md).
### Available Tools
- **create_mson_model** - Create and validate MSON models from structured data
- **validate_mson_model** - Validate MSON model consistency and completeness
- **generate_uml_diagram** - Generate UML diagrams in PlantUML and Mermaid formats
- **export_to_system_designer** - Export models to System Designer application format
## Platform Integration
The server can be integrated with various platforms:
- **Claude Desktop** - Native MCP integration
- **VS Code** - Extension development support
- **Web Applications** - React/Node.js integration
- **CLI Tools** - Command-line interface
See the [Integration Guide](./docs/INTEGRATION-GUIDE.md) for detailed setup instructions.
## Architecture
### Tool-Based Approach
This server uses a tool-based architecture that:
1. **Empowers LLMs**: The LLM handles understanding requirements and creating structured data
2. **Validates Input**: Server validates structured input using comprehensive Zod schemas
3. **Processes Efficiently**: Simple, fast processing without complex parsing logic
4. **Exports Flexibly**: Multiple output formats for different use cases
### Benefits Over Parser-Based Approaches
- **Simplicity**: No complex NLP parsing to maintain
- **Flexibility**: Works with any domain the LLM understands
- **Reliability**: Fewer moving parts, less error-prone
- **Performance**: Faster validation and processing
- **Extensibility**: Easy to add new tools and features
## Development
### Running Tests
```bash
# Run all tests
bun test
# Run tests in watch mode
bun test --watch
```
### Building
```bash
# Build for production
bun run build
# Start production server
bun start
```
### Code Structure
```
src/
├── index.ts # Main MCP server with all tools
├── cli.ts # Command-line interface
└── integration/
└── system-designer.ts # System Designer app integration
test/
└── tool-based.test.ts # Comprehensive test suite
docs/
├── API-REFERENCE.md # Detailed API documentation
├── CLI-GUIDE.md # CLI usage guide
└── INTEGRATION-GUIDE.md # Platform integration guide
examples/
├── banking-system.json # Sample banking system model
├── banking-system-plantuml.puml # PlantUML output example
├── banking-system-mermaid.md # Mermaid output example
└── README.md # Example documentation
```
## Integration with System Designer
The server exports models in a format compatible with the System Designer macOS application:
1. **File Export**: Models are saved as JSON files
2. **Automatic Integration**: Files can be imported directly into System Designer
3. **Format Compatibility**: Uses MSON (Metamodel JavaScript Object Notation) format
## Contributing
This project follows a simple contribution model:
1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request
## License
MIT License - see LICENSE file for details.
## Acknowledgments
- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for the tool integration framework
- [System Designer](https://systemdesigner.io/) for the target macOS application
- [Zod](https://zod.dev/) for type-safe validation
- [Bun](https://bun.sh/) for the fast JavaScript runtime