Automatically generate spec-compliant SysML v2.0 architecture models and professional diagrams from any software project.
CC_SysML is a Claude Code MCP server that analyzes source code, discovers architectural elements (classes, interfaces, dependencies, workflows), and produces:
- SysML v2
.sysmlmodel files — the canonical textual notation adopted by OMG (July 2025), validated by the same parser Eclipse SysON uses - Professional diagram images — generated via Google Gemini, producing full-resolution PNG diagrams (BDD, IBD, PKG, ACT, SEQ)
┌─────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Source Code │────>│ Parsers │────>│ SysML v2 │────>│ .sysml │
│ (any lang) │ │ AST / regex │ │ Metamodel │ │ model files │
└─────────────┘ └──────────────┘ └──────────────┘ └──────┬───────┘
│
┌──────────────────────┤
│ │
v v
┌────────────────┐ ┌────────────────┐
│ syside-cli.js │ │ Gemini Image │
│ (validation) │ │ Bridge (PNG) │
└────────────────┘ └────────────────┘
| Step | Tool | What Happens |
|---|---|---|
| 1. Parse | tool_parse_project |
Analyze source code — extract classes, functions, imports, inheritance, dependencies. Automatically skips embedded/vendored projects. Results cached for fast queries. |
| 2. Explore | tool_query_elements, tool_get_element, tool_get_relationships |
Browse the parsed model interactively — filter by type, name, package. |
| 3. Generate Model | tool_generate_sysml |
Produce .sysml files for selected diagram types. Auto-validates with syside-cli.js. |
| 4. Generate Diagrams | tool_gemini_generate_image / tool_gemini_generate_diagrams |
Submit architecture-aware prompts to Google Gemini to produce full-resolution professional diagram PNGs. |
| 5. Validate | tool_syside_validate, tool_pysysml2_validate |
Cross-verify .sysml output with independent parsers. |
.sysmlis the standard — OMG SysML v2.0 textual notation: machine-readable, diffable, version-controllable- Gemini produces professional diagrams — proper SysML notation with compartments, relationship arrows, specialization triangles, ports, activation bars — at full resolution (3-5 MB PNGs)
- Tool interoperability —
.sysmlfiles import into SysON, CATIA Magic, Enterprise Architect, and any SysML v2 compliant tool - Validation pipeline — every generated
.sysmlfile is automatically parsed by a spec-compliant parser
The diagrams below were auto-generated by CC_SysML analyzing its own codebase. The .sysml model files are in docs/sysml/ and the diagram images are in docs/sysml/Graphical - Gemini Generated/.
Shows the system's main blocks, their attributes/operations, and relationships (usage, specialization, composition).
Shows the package hierarchy and inter-package dependencies (models, parsers, renderers, diagrams, bridges, utils).
Shows the internal structure of the CC_SysML system — parts, ports, and their connections within the system boundary.
Shows the diagram generation workflow — from receiving a project path through parsing, element selection, parallel rendering, and output.
Shows the runtime interaction flow — User triggers MCPServer, which orchestrates parsing, element selection, text rendering, and Gemini image generation.
- Multi-language parsing — Python (AST-based), TypeScript/JavaScript (tree-sitter + regex fallback)
- Foreign project detection — automatically skips embedded/vendored projects via manifest detection and
.gitignoreparsing - 15 MCP tools — generation, model query API, external parser bridges, and Gemini image generation
- Spec-compliant validation — syside-cli.js (same parser as Eclipse SysON) validates every generated file
- Gemini image pipeline — Playwright-based browser automation with persistent login, hover-button full-size download
- Parse-once, query-many — in-memory model cache for interactive exploration without re-parsing
- Architectural significance scoring — filters noise so diagrams show what matters
- Element deduplication — identity-based tracking prevents double-counting across owned elements and relationships
git clone https://github.com/gitvendis/CC_SysML.git
cd CC_SysML
pip install -e ".[dev,mcp]"
# For Gemini image generation
pip install playwright
playwright install chromiumDiagram image generation uses Google Gemini through browser automation. A one-time interactive login is required to establish a persistent session:
- Start the login flow — call
tool_gemini_login(via MCP) or run:from cc_sysml.bridges.gemini_image_bridge import GeminiImageBridge import asyncio async def login(): bridge = GeminiImageBridge() await bridge.initialize() # launches a Chrome window await bridge.interactive_login() # sign into Google in the browser await bridge.close() asyncio.run(login())
- Sign into Google in the Chrome window that opens (including 2FA if enabled)
- Done — the session is saved to
~/.cc_sysml_gemini_profile/and reused automatically. No credentials are stored in the project repo.
After login, image generation works unattended. The session persists across restarts; re-login is only needed if Google expires the session.
Add to your Claude Code project configuration (.mcp.json):
{
"mcpServers": {
"cc-sysml": {
"command": "python",
"args": ["-m", "cc_sysml.mcp_server"],
"transport": "stdio"
}
}
}Claude Code will then have access to all 15 tools. Example usage:
You: Document this project's architecture in SysML v2
Claude: I'll parse the project, generate SysML v2 model files, and create
professional diagram images.
[calls tool_parse_project, tool_generate_sysml, tool_gemini_generate_diagrams]
Generated 5 diagram files in docs/sysml/:
- project_pkg.sysml (package hierarchy)
- project_bdd.sysml (block definitions)
- project_ibd.sysml (internal structure)
- project_act.sysml (activity flows)
- project_seq.sysml (sequence interactions)
All files validated by syside-cli — 0 errors.
Generated 5 diagram images in docs/sysml/Graphical - Gemini Generated/:
- CC_SysML_bdd_gemini.png (3.2 MB)
- CC_SysML_ibd_gemini.png (323 KB)
- CC_SysML_pkg_gemini.png (3.5 MB)
- CC_SysML_act_gemini.png (4.9 MB)
- CC_SysML_seq_gemini.png (989 KB)
from cc_sysml import generate_sysml, parse_project
# Generate .sysml model files
result = generate_sysml(
project_path="/path/to/project",
diagram_types=["bdd", "ibd"],
output_format="sysml",
output_dir="docs/sysml/",
)
for diagram in result.diagrams:
print(f"{diagram.diagram_type.value}: {diagram.file_path}")
# Parse and explore
analysis = parse_project("/path/to/project")
print(f"Found {len(analysis.all_elements)} architectural elements")import asyncio
from cc_sysml.bridges.gemini_image_bridge import GeminiImageBridge
async def generate_diagrams():
bridge = GeminiImageBridge(headless=False)
await bridge.initialize()
# First time: manual Google login required
await bridge.interactive_login()
# Generate a diagram image
result = await bridge.generate_image(
prompt="Create a SysML v2 BDD for ...",
output_path="docs/sysml/my_bdd.png",
)
print(f"Saved: {result['image_path']} ({result['success']})")
# Batch generation
results = await bridge.generate_diagram_images(
prompts={"bdd": "Create a BDD ...", "seq": "Create a SEQ ..."},
output_dir="docs/sysml/Graphical - Gemini Generated/",
)
await bridge.close()
asyncio.run(generate_diagrams())| Tool | Description |
|---|---|
tool_generate_sysml |
Analyze a project and write .sysml diagram files. Auto-validates with syside-cli. |
tool_parse_project |
Parse a project and cache the model for subsequent queries. |
tool_list_diagram_types |
List supported SysML v2 diagram types. |
tool_validate_sysml |
Validate SysML v2 text using grammar-based structural checks. |
| Tool | Description |
|---|---|
tool_query_elements |
Query elements by type, name pattern, and package. Paginated. |
tool_get_element |
Get full details of a specific element by qualified name. |
tool_get_relationships |
Query relationships filtered by element and kind. Paginated. |
| Tool | Description |
|---|---|
tool_syside_parse |
Parse a .sysml file with syside-cli.js — returns JSON AST + diagnostics. |
tool_syside_validate |
Validate SysML v2 text with syside-cli.js (full spec compliance). |
tool_pysysml2_validate |
Validate with PySysML2 (independent ANTLR4 parser, structural subset). |
tool_bridge_status |
Check availability and versions of external parser bridges. |
| Tool | Description |
|---|---|
tool_gemini_login |
Open browser for manual Google authentication (persistent profile). |
tool_gemini_check_session |
Check if an authenticated Gemini session exists. |
tool_gemini_generate_image |
Generate a single diagram image from a prompt. |
tool_gemini_generate_diagrams |
Batch-generate diagram images from .sysml files. |
src/cc_sysml/
├── skill.py # Main API entry point (with validation loop)
├── mcp_server.py # MCP server (FastMCP/stdio, 15 tools)
├── bridges/ # External integrations
│ ├── syside_bridge.py # SysIDE/syside-cli.js (spec-compliant validation)
│ ├── pysysml2_bridge.py# PySysML2/ANTLR4 (secondary validator)
│ └── gemini_image_bridge.py # Gemini image generation (Playwright)
├── models/ # SysML v2 metamodel data classes
│ ├── base.py # Core: Element, Package, Namespace, Type
│ ├── structural.py # Parts, ports, connections, interfaces
│ ├── behavioral.py # Actions, states, messages, transitions
│ ├── relationships.py # Associations, specializations, allocations
│ └── ... # requirements, views, expressions, metadata
├── parsers/ # Source code analysis
│ ├── python_parser.py # Python AST-based parser
│ ├── project_analyzer.py # Full project orchestrator
│ ├── base.py # Project scanning, foreign project detection
│ ├── significance.py # Architectural significance scoring
│ └── ... # mapper, relationships, typescript parser
├── renderers/ # Output generation
│ ├── textual.py # SysML v2 textual notation (.sysml files)
│ ├── coordinator.py # Multi-diagram orchestration
│ └── ... # svg (legacy), plantuml, mermaid
├── diagrams/ # Diagram type modules and sizing
│ ├── block_definition.py, internal_block.py, package.py
│ ├── activity.py, sequence.py, state_machine.py
│ └── sizing.py # Per-diagram-type element limits
└── utils/ # Shared utilities
The SysIDE Langium-based parser — the same engine that Eclipse SysON uses. Every .sysml file generated by tool_generate_sysml is automatically validated.
- Requires: Node.js (v18+)
- Coverage: full SysML v2 grammar and KerML validation
An independent ANTLR4-based Python parser for cross-verification.
- Coverage: structural subset (packages, parts, ports, attributes, connections)
- Not covered: requirements, actions, states, constraints
git clone https://github.com/gitvendis/CC_SysML.git
cd CC_SysML
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,mcp]"
pytest # Run tests (1000+ unit tests)
ruff check src/ tests/ # Lint
mypy src/ # Type checkMIT