maxnumbers/cameo-mcp-server

Cameo MCP Server v2.2

A lightweight MCP (Model Context Protocol) server for Cameo Systems Modeler integration, designed specifically for Claude Desktop and other MCP clients.

Features

• 🚀 Claude Desktop Ready: No authentication required, tools work directly
• 🎨 Complete Diagram Support: Generate and retrieve SVG diagrams
• ⚡ Lightweight: Fast startup, no unnecessary services
• 🔧 8 SysML Tools: Full model management, analysis, and validation
• 📦 Easy Installation: Standard Python package via pip
• 🎯 Demo Mode: Fully functional automotive model for testing
• 📊 Phoenix Observability: Optional OpenTelemetry tracing for session monitoring

Quick Start

1. Install the Package

pip install -e .

2. Add to Claude Desktop

Edit your Claude Desktop MCP settings file:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/claude/claude_desktop_config.json

Add this configuration:

{
  "mcpServers": {
    "cameo-mcp-server": {
      "command": "python",
      "args": ["-m", "cameo_mcp_server"]
    }
  }
}

3. Restart MCP Client

Close and reopen MCP client completely.

4. Start Using SysML Tools

Claude now has direct access to SysML modeling capabilities:

"Can you analyze my automotive model for consistency issues?"

"Create a new SysML block called 'MotorController' and generate a block diagram"

"What model elements are available in the automotive demo project?"

Available Tools

Claude Desktop automatically discovers these 8 tools:

Model Management

• get_model_element - Retrieve specific SysML elements
• create_block - Create new SysML blocks with properties
• execute_query - Run queries against the model

Analysis & Validation

• analyze_architecture - Architecture analysis (consistency, completeness, traceability, complexity)
• validate_model - Validate against SysML rules and constraints

Diagram Generation

• generate_diagram - Create SysML diagrams with SVG content
• get_diagram - Retrieve previously generated diagrams

Server Information

• server_info - Get server capabilities and status

Demo Project

The server includes an "automotive control system" model:

• VehicleControlSystem (Main system)
• EngineControlModule, BrakeControlModule, TransmissionControl (Subsystems)
• ThrottleActuator, BrakePedal (Components)
• SpeedSensor, EngineRPMSensor (Sensors)
• SafetyRequirement_001, PerformanceReq_002 (Requirements)

Example Conversations

Architecture Analysis

You: "Analyze the automotive demo for consistency issues"
LLM: Runs analyze_architecture tool and reports findings

Model Creation

You: "Create a new engine temperature sensor block"
LLM: Uses create_block to add the sensor with appropriate properties

Diagram Generation

You: "Generate a block diagram showing the system architecture"
LLM: Creates diagram and provides SVG content for viewing

Requirements Traceability

You: "Check if all requirements are properly traced"
LLM: Validates traceability and reports coverage

Configuration

Environment Variables (Optional)

# For production Cameo integration
CAMEO_API_URL=https://your-cameo-server.com/api
CAMEO_USERNAME=your_username  
CAMEO_PASSWORD=your_password

# For observability (optional)
PHOENIX_HOST=localhost
PHOENIX_PORT=6006

Custom Project Data

Replace the demo model in demo_model.py with your actual Cameo integration.

Architecture

Lightweight Design

• No Authentication: Tools work directly without setup
• No Persistent Services: Server spawns on-demand
• Pure MCP Protocol: Standard STDIO transport
• Fast Startup: Minimal dependencies

Claude Desktop Integration

1. Claude Desktop spawns server automatically
2. Server registers 8 SysML tools
3. Claude uses tools to respond to user requests
4. Server terminates when conversation ends
5. SVG diagrams included in responses

Demo vs Production

• Demo Mode: Uses built-in automotive model
• Production: Replace with real Cameo API integration
• Observability: Optional Phoenix integration via run_phoenix.py

Development

Test the Server

# Test directly
python -m cameo_mcp_server --standalone

# Test with MCP client
python -c "
from fastmcp import Client
import asyncio
async def test():
    client = Client('mcp_server.py')
    async with client:
        tools = await client.list_tools()
        print(f'Found {len(tools)} tools')
asyncio.run(test())
"

Optional Observability

# Start Phoenix for trace collection (run in separate terminal)
python run_phoenix.py

# Phoenix UI: http://localhost:6006
# Traces automatically sent from MCP server sessions

The MCP server automatically sends OpenTelemetry traces to Phoenix when available, providing visibility into:

• Tool execution times and parameters
• Model query performance
• Diagram generation workflows
• Error tracking and debugging

Package Structure

cameo-mcp-server/
├── src/cameo_mcp_server/
│   ├── server.py          # Main MCP server (Claude Desktop ready)
│   ├── demo_model.py      # Automotive demo model
│   ├── config.py          # Configuration
│   └── __main__.py        # Entry point
├── run_phoenix.py         # Optional observability
├── pyproject.toml         # Package definition
└── README.md             # This file

Production Deployment

For Real Cameo Integration

1. Replace demo model with Cameo API calls in server.py
2. Add authentication for production Cameo servers
3. Update environment variables for your Cameo installation

For Teams

1. Publish package to PyPI: pip install your-cameo-mcp-server
2. Share Claude Desktop config with your package name
3. Optional: Use shared Phoenix instance for team observability

For CI/CD

# Install and test
pip install cameo-mcp-server
python -m cameo_mcp_server --standalone

# Validate tools
python -c "from fastmcp import Client; print('MCP server ready')"

Troubleshooting

Server Won't Start

# Check installation
python -c "import cameo_mcp_server; print('OK')"

# Test directly  
python -m cameo_mcp_server --standalone

Claude Desktop Issues

1. Verify MCP config file location and syntax
2. Check that python command is in PATH
3. Restart Claude Desktop completely
4. Check Claude Desktop logs for errors

No Tools Visible

1. Ensure Claude Desktop restarted after config change
2. Verify package installation: pip list | grep cameo
3. Test server independently first

Version History

• v0.1.0: Initial MCP server implementation

License

This project is licensed under the MIT License.