CC_SysML

Automatically generate spec-compliant SysML v2.0 architecture models, knowledge graphs, and professional diagrams from any software project or Cameo XMI export.

CC_SysML is a Claude Code MCP server that analyzes source code (or imports Cameo/MagicDraw SysML v1.x models), discovers architectural elements, and produces:

SysML v2 .sysml model files — the canonical textual notation adopted by OMG (July 2025), validated by the same parser Eclipse SysON uses
Knowledge graphs — interactive, queryable graph representations with an in-browser exploration dashboard
Professional diagram images — generated via Google Gemini, producing full-resolution PNG diagrams (BDD, IBD, PKG, ACT, SEQ)

How It Works

                                    ┌──────────────┐
                                    │  .sysml      │
                                ┌──>│  model files │──┐
┌─────────────┐  ┌──────────┐  │   └──────────────┘  │   ┌──────────────────┐
│ Source Code  │─>│ Parsers  │──┤                      ├──>│ syside-cli.js    │
│ Python/TS/JS │  │ AST-based│  │   ┌──────────────┐  │   │ (validation)     │
└─────────────┘  └──────────┘  ├──>│  Knowledge   │  │   └──────────────────┘
                               │   │  Graph (NX)  │──┤
┌─────────────┐  ┌──────────┐  │   └──────┬───────┘  │   ┌──────────────────┐
│ Cameo XMI   │─>│ XMI      │──┤          │          ├──>│ Gemini Image     │
│ (SysML v1)  │  │ Parser   │  │          v          │   │ Bridge (PNG)     │
└─────────────┘  └──────────┘  │   ┌──────────────┐  │   └──────────────────┘
                               │   │  Dashboard   │  │
                               │   │  (Cytoscape) │  │   ┌──────────────────┐
                               │   └──────────────┘  └──>│ RDF/OWL (OSLC    │
                               │                         │  SysML v2 vocab) │
                               │   ┌──────────────┐     └──────────────────┘
                               └──>│  Adversarial │
                                   │  Validator   │
                                   └──────────────┘

The Pipeline

Step	Tool	What Happens
1. Parse	`tool_parse_project` or `tool_parse_xmi`	Analyze source code or import a Cameo XMI export. 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. Build KG	`tool_build_kg`	Transform the model into a queryable NetworkX knowledge graph.
5. Explore KG	`tool_kg_dashboard` or `tool_query_kg`	Open an interactive browser dashboard, or query the graph programmatically.
6. Validate KG	`tool_kg_validate`	Run adversarial checks: completeness, structural integrity, ontology conformance, CWA engineering.
7. Generate Diagrams	`tool_gemini_generate_diagrams`	Submit architecture-aware prompts to Google Gemini for professional diagram PNGs.

Knowledge Graph Integration

CC_SysML transforms parsed models into a queryable knowledge graph with two pipeline paths:

Path 1: Source code → Python parsers → AnalysisResult → KGBuilder → KG  (richer data)
Path 2: .sysml text → syside-cli → JSON AST → SysMLASTBuilder → KG     (spec-compliant)

Interactive Dashboard

Launch a browser-based graph explorer:

pip install -e ".[dashboard]"
cc-sysml dashboard /path/to/project --port 8050

The dashboard provides:

Force-directed graph visualization — nodes colored by SysML element kind, edges styled by relationship type
Filter panel — filter by element type, relationship kind, search by name
Click-to-inspect — view full element details, incoming/outgoing relationships
Double-click expand — progressively reveal neighbors
Query console — filter expressions or SPARQL (with rdflib installed)
Live mode — watches .sysml files and auto-reloads on changes
Export PNG — download the current graph view as an image

Technology Stack

Layer	Library	Purpose
Property graph	NetworkX	In-process graph DB, queries, dashboard export
RDF/OWL	rdflib (optional)	SPARQL queries, OSLC SysML v2 vocabulary alignment
Visualization	Dash + Cytoscape.js	Interactive browser dashboard
Validation	5-category adversarial checker	Completeness, structural, ontology, CWA, round-trip
Ontology	OSLC SysML v2 vocab	Authoritative OWL class IRIs from `oslc-op/oslc-specs`

Adversarial Validation

The KG validator runs five check categories against the source model:

Check	What It Detects
Completeness	Missing nodes/edges — every element in the source model must appear in the KG
Structural integrity	Orphan nodes, dangling edges, ownership cycles, missing required properties
Ontology conformance	Unknown node types/predicates, SHACL shape violations
CWA engineering	Spurious nodes/edges not in the source (closed-world assumption enforcement)
Round-trip	KG re-serialized to `.sysml` must parse back equivalently

Cameo XMI Import

CC_SysML can import UML 2.5 XMI files exported from Cameo Systems Modeler (MagicDraw) and convert SysML v1.x models to SysML v2:

# Parse a Cameo export
cc-sysml parse-xmi exported_model.xmi

# Or via MCP tool
# tool_parse_xmi(xmi_file="/path/to/model.xmi")

SysML v1 → v2 Mapping

Cameo / SysML v1	CC_SysML v2 Output
`<<Block>>` Class	`PartDefinition`
`<<Requirement>>` (id, text)	`RequirementDefinition`
`<<InterfaceBlock>>`	`InterfaceDefinition`
`<<ConstraintBlock>>`	`ConstraintDefinition`
Property (composite)	`PartUsage`
Property (value)	`AttributeFeature`
Port + `<<FlowPort>>`	`PortUsage` (with direction)
Operation + Parameters	`ActionDefinition`
StateMachine / State / Transition	`StateDefinition` / `StateUsage` / `TransitionUsage`
Generalization	`Specialization` relationship
`<<Satisfy>>` Dependency	`Satisfy` relationship
`<<Verify>>` Dependency	`Verify` relationship
`<<Allocate>>` Dependency	`Allocate` relationship
Enumeration + Literals	`EnumerationDefinition`
Connector	`ConnectionUsage`

The parser handles multiple XMI/UML/SysML namespace URI variants and auto-detects the SysML profile prefix. Uses only stdlib xml.etree.ElementTree — no lxml required.

Example Output — CC_SysML Documenting Itself

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/.

Block Definition Diagram (BDD)

Shows the system's main blocks, their attributes/operations, and relationships (usage, specialization, composition).

Package Diagram (PKG)

Shows the package hierarchy and inter-package dependencies (models, parsers, renderers, diagrams, bridges, utils).

Internal Block Diagram (IBD)

Shows the internal structure of the CC_SysML system — parts, ports, and their connections within the system boundary.

Activity Diagram (ACT)

Shows the diagram generation workflow — from receiving a project path through parsing, element selection, parallel rendering, and output.

Sequence Diagram (SEQ)

Shows the runtime interaction flow — User triggers MCPServer, which orchestrates parsing, element selection, text rendering, and Gemini image generation.

Quick Start

Prerequisites

Python 3.11+
Node.js v18+ — required for syside-cli.js validation (the same parser Eclipse SysON uses)

Installation

git clone https://github.com/gitvendis/CC_SysML.git
cd CC_SysML
python -m venv .venv
source .venv/bin/activate

# Core + MCP server
pip install -e ".[mcp]"

# With knowledge graph dashboard
pip install -e ".[mcp,dashboard]"

# With RDF/OWL support (SPARQL queries, OSLC vocabulary)
pip install -e ".[mcp,kg-rdf,dashboard]"

# Everything
pip install -e ".[mcp,kg-all,gemini]"
playwright install chromium

Optional Dependency Groups

Group	What It Adds	Install
`mcp`	MCP server (FastMCP)	`pip install -e ".[mcp]"`
`kg`	NetworkX knowledge graph	`pip install -e ".[kg]"`
`kg-rdf`	RDF/SPARQL via rdflib	`pip install -e ".[kg-rdf]"`
`dashboard`	Dash + Cytoscape.js browser UI	`pip install -e ".[dashboard]"`
`kg-all`	All KG features	`pip install -e ".[kg-all]"`
`gemini`	Gemini image generation (Playwright)	`pip install -e ".[gemini]"`
`pysysml2`	PySysML2 secondary validator	`pip install -e ".[pysysml2]"`

As an MCP Server (Recommended)

Register the MCP server so Claude Code can use all tools. The command must point to the Python where cc-sysml is installed (typically the venv inside this repo).

Option A — Global (available in all Claude Code sessions):

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "cc-sysml": {
      "command": "/path/to/CC_SysML/.venv/bin/python",
      "args": ["-m", "cc_sysml.mcp_server"],
      "transport": "stdio"
    }
  }
}

Option B — Per-project (scoped to one project):

Add to .mcp.json in the target project's root:

{
  "mcpServers": {
    "cc-sysml": {
      "command": "/path/to/CC_SysML/.venv/bin/python",
      "args": ["-m", "cc_sysml.mcp_server"],
      "transport": "stdio"
    }
  }
}

Note: MCP servers connect at session startup. After adding the configuration, restart Claude Code (/exit then claude) for it to take effect.

Gemini Image Generation Setup

Diagram image generation uses Google Gemini through browser automation. A one-time interactive login is required:

Call tool_gemini_login (via MCP) to open a Chrome window
Sign into Google (including 2FA if enabled)
Done — session saved to ~/.cc_sysml_gemini_profile/ and reused automatically

CLI Usage

# Parse a project and show summary
cc-sysml parse /path/to/project

# Generate SysML v2 model files
cc-sysml generate /path/to/project --format sysml --output docs/sysml/

# Parse a Cameo XMI export
cc-sysml parse-xmi exported_model.xmi

# Launch the knowledge graph dashboard
cc-sysml dashboard /path/to/project --port 8050

# List supported diagram types
cc-sysml diagrams

Python API

from cc_sysml.skill import generate_sysml, parse_project

# Parse and generate
result = generate_sysml("/path/to/project", diagram_types=["bdd", "ibd"])
for diagram in result.diagrams:
    print(f"{diagram.diagram_type.value}: {diagram.file_path}")

# Build a knowledge graph
from cc_sysml.kg.builder import KGBuilder
analysis = parse_project("/path/to/project")
kg = KGBuilder().build(analysis)
print(f"KG: {kg.node_count} nodes, {kg.edge_count} edges")

# Query the graph
from cc_sysml.kg.query import KGQueryEngine
engine = KGQueryEngine(kg)
parts = engine.find_nodes(node_type="PartDefinition")
neighbors = engine.get_neighbors("MyClass", direction="out")

# Parse Cameo XMI
from cc_sysml.parsers.xmi_parser import XMIParser
parser = XMIParser()
result = parser.parse_file("model.xmi")

# Launch dashboard
from cc_sysml.dashboard import launch_dashboard
launch_dashboard("/path/to/project", port=8050)

MCP Tools Reference

Generation & Validation (4 tools)

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.

Model Query API (3 tools)

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.

Knowledge Graph (6 tools)

Tool	Description
`tool_build_kg`	Build a NetworkX knowledge graph from the parsed model.
`tool_query_kg`	Query nodes, edges, neighbors in the knowledge graph.
`tool_kg_validate`	Run 5-category adversarial validation against the source model.
`tool_kg_compare`	Diff the KG against the current model to detect drift.
`tool_kg_dashboard`	Launch the interactive Cytoscape.js browser dashboard.
`tool_kg_canned_query`	Run pre-built SPARQL queries (requires rdflib).

Import (2 tools)

Tool	Description
`tool_parse_xmi`	Parse a Cameo/MagicDraw UML 2.5 XMI export (SysML v1→v2 conversion).
`tool_build_kg_from_sysml`	Build a KG directly from SysML v2 text via syside-cli AST.

External Parser Bridges (4 tools)

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 all bridges (syside, PySysML2, KG, rdflib).

Gemini Image Generation (4 tools)

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.

Architecture

src/cc_sysml/
├── skill.py              # Main API entry point
├── mcp_server.py         # MCP server (FastMCP/stdio, 23 tools)
├── cli.py                # CLI (generate, parse, parse-xmi, dashboard, validate, diagrams)
├── config.py             # Output formats, scope, rendering config
│
├── parsers/              # Source code & model import
│   ├── python_parser.py  #   Python AST-based parser
│   ├── typescript_parser.py  # TypeScript/JS parser
│   ├── xmi_parser.py     #   Cameo UML 2.5 XMI import (SysML v1→v2)
│   ├── project_analyzer.py   # Full project orchestrator
│   └── significance.py   #   Architectural significance scoring
│
├── 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.py   #   Requirements, use cases, verification
│
├── renderers/            # Output generation
│   ├── textual.py        #   SysML v2 textual notation (.sysml files)
│   ├── svg.py            #   Custom SVG renderer
│   └── coordinator.py    #   Multi-diagram orchestration
│
├── kg/                   # Knowledge graph integration
│   ├── builder.py        #   AnalysisResult → NetworkX KG (4-pass algorithm)
│   ├── sysml_ast_builder.py  # .sysml → syside AST → KG (spec-compliant path)
│   ├── graph.py          #   KnowledgeGraph dataclass (NX + optional RDF)
│   ├── query.py          #   KGQueryEngine (find, filter, SPARQL, canned queries)
│   ├── validator.py      #   5-category adversarial validation
│   ├── rdf_serializer.py #   NetworkX → rdflib.Graph (OSLC IRIs)
│   ├── rdf_loader.py     #   Load OSLC SysML v2 OWL vocabulary
│   ├── checks/           #   Validation check implementations
│   ├── ontology/         #   SysML class/predicate vocabulary, SHACL runner
│   ├── shacl/            #   SHACL constraint shapes (structural, behavioral, req, alloc)
│   └── vendor/opencaesar/#   Vendored OSLC SysML-vocab.ttl + KerML-vocab.ttl
│
├── dashboard/            # Interactive browser UI
│   ├── app.py            #   Dash application factory
│   ├── callbacks.py      #   All interactive callbacks
│   ├── graph_builder.py  #   KG → Cytoscape.js element conversion
│   ├── style_map.py      #   Node colors/shapes, edge styles by SysML type
│   ├── layout.py         #   Four-panel CSS grid layout
│   ├── query_engine.py   #   Filter expression engine
│   ├── file_watcher.py   #   Watchdog-based live reload
│   └── server.py         #   Dashboard launcher (daemon thread for MCP)
│
├── bridges/              # External tool integrations
│   ├── syside_bridge.py  #   SysIDE/syside-cli.js (spec-compliant parser)
│   ├── pysysml2_bridge.py#   PySysML2/ANTLR4 (secondary validator)
│   └── gemini_image_bridge.py  # Gemini image generation (Playwright)
│
├── diagrams/             # Diagram type modules and sizing
└── utils/                # Shared utilities

Development

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,dashboard,gemini]"
playwright install chromium

pytest                    # Run tests (1,380 tests)
ruff check src/ tests/    # Lint
mypy src/                 # Type check

See CONTRIBUTING.md for pull request guidelines.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 16 Commits
.github/workflows		.github/workflows
docs		docs
prompts		prompts
resources		resources
scripts		scripts
src/cc_sysml		src/cc_sysml
tests		tests
.gitignore		.gitignore
.mcp.json		.mcp.json
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SKILL.md		SKILL.md
pyproject.toml		pyproject.toml
ralph_sysml.sh		ralph_sysml.sh

Folders and files

Latest commit

History

Repository files navigation

CC_SysML

How It Works

The Pipeline

Knowledge Graph Integration

Interactive Dashboard

Technology Stack

Adversarial Validation

Cameo XMI Import

SysML v1 → v2 Mapping

Example Output — CC_SysML Documenting Itself

Block Definition Diagram (BDD)

Package Diagram (PKG)

Internal Block Diagram (IBD)

Activity Diagram (ACT)

Sequence Diagram (SEQ)

Quick Start

Prerequisites

Installation

Optional Dependency Groups

As an MCP Server (Recommended)

Gemini Image Generation Setup

CLI Usage

Python API

MCP Tools Reference

Generation & Validation (4 tools)

Model Query API (3 tools)

Knowledge Graph (6 tools)

Import (2 tools)

External Parser Bridges (4 tools)

Gemini Image Generation (4 tools)

Architecture

Development

License

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages