3  SysML v2 Upstream Research

3.1 Overview

This chapter documents research into upstream SysML v2 specifications and reference implementations. This research informs architecture decisions (Section 9.4) and identifies integration points for the MCP server. For SysML v2 conceptual background, see Section 2.1.

3.2 Official Repositories

The SysML v2 reference implementations are hosted at github.com/Systems-Modeling:

Repository	Purpose	License
SysML-v2-Release	Latest incremental releases (start here)	LGPL-3.0
SysML-v2-Pilot-Implementation	Parser, Eclipse IDE, Jupyter kernel	LGPL-3.0 / GPL-3.0
SysML-v2-API-Services	REST/HTTP API reference server	LGPL-3.0 / GPL-3.0
SysML-v2-API-Java-Client	Generated Java client (OpenAPI)	LGPL-3.0 / GPL-3.0
SysML-v2-API-Python-Client	Generated Python client	LGPL-3.0
SysML-v2-API-Cookbook	Jupyter notebook examples	N/A

3.3 Pilot Implementation

3.3.1 Repository Structure

SysML-v2-Pilot-Implementation/
├── kerml/                           # KerML examples
├── sysml/                           # SysML examples
├── sysml.library/                   # Standard library models
├── org.omg.sysml/                   # Core EMF metamodel (Ecore)
├── org.omg.kerml.xtext/             # KerML Xtext grammar
├── org.omg.kerml.xtext.ide/         # KerML IDE support
├── org.omg.kerml.xtext.ui/          # KerML Eclipse UI
├── org.omg.sysml.xtext/             # SysML Xtext grammar  
├── org.omg.sysml.xtext.ide/         # SysML IDE support
├── org.omg.sysml.xtext.ui/          # SysML Eclipse UI
├── org.omg.kerml.expressions.xtext/ # Expression language grammar
├── org.omg.sysml.interactive/       # Standalone interactive JAR
├── org.omg.sysml.jupyter.kernel/    # Jupyter kernel
├── org.omg.sysml.plantuml/          # PlantUML visualization
├── org.omg.sysml.execution/         # Execution engine
└── pom.xml                          # Maven build (Tycho)

3.3.2 Parser Technology

Component	Technology
Language	Java 21+ (Eclipse 2025-03)
Framework	Xtext (generates parser from grammar)
Metamodel	Eclipse EMF (Ecore)
Build	Maven with Tycho (for Eclipse plugins)

3.3.3 Standalone Usage

The org.omg.sysml.interactive module provides a standalone JAR:

mvn clean package
# JAR: org.omg.sysml.interactive/target/org.omg.sysml.interactive-*.jar

Key Class: org.omg.sysml.interactive.SysMLInteractive

• Parse SysML/KerML files
• Access the resolved AST/model
• Execute models

3.4 SysML v2 API Specification

3.4.1 REST API Endpoints

3.4.1.1 Projects

Method	Endpoint	Description
GET	/projects	List all projects
POST	/projects	Create project
GET	/projects/{projectId}	Get project by ID
PUT	/projects/{projectId}	Update project
DELETE	/projects/{projectId}	Delete project

3.4.1.2 Branches

Method	Endpoint	Description
GET	/projects/{projectId}/branches	List branches
POST	/projects/{projectId}/branches	Create branch
GET	/projects/{projectId}/branches/{branchId}	Get branch
DELETE	/projects/{projectId}/branches/{branchId}	Delete branch

3.4.1.3 Commits

Method	Endpoint	Description
GET	/projects/{projectId}/commits	List commits
POST	/projects/{projectId}/commits	Create commit
GET	/projects/{projectId}/commits/{commitId}	Get commit
GET	/projects/{projectId}/commits/{commitId}/changes	Get changes

3.4.1.4 Elements

Method	Endpoint	Description
GET	/projects/{projectId}/commits/{commitId}/elements	List elements
GET	/projects/{projectId}/commits/{commitId}/elements/{elementId}	Get element
GET	/projects/{projectId}/commits/{commitId}/roots	Get root elements

3.4.1.5 Queries

Method	Endpoint	Description
GET	/projects/{projectId}/queries	List saved queries
POST	/projects/{projectId}/queries	Create query
GET/POST	/projects/{projectId}/query-results	Execute ad-hoc query

3.4.2 Query Constraints

Queries support:

• PrimitiveConstraint - single property constraints
• CompositeConstraint - AND/OR combinations of constraints

3.5 Reference API Server

3.5.1 Technology Stack

Component	Technology
Framework	Play Framework (Scala/Java)
Build Tool	sbt
Database	PostgreSQL
Java Version	JDK 11

3.5.2 Running Locally

# 1. Start PostgreSQL
docker run --name sysml2-postgres \
  -p 5432:5432 \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -e POSTGRES_DB=sysml2 \
  -d postgres

# 2. Clone and run
git clone https://github.com/Systems-Modeling/SysML-v2-API-Services.git
cd SysML-v2-API-Services
sbt clean
sbt run

# 3. Access Swagger UI
open http://localhost:9000/docs/

3.6 Existing SysML Tools Analysis

Evaluated existing SysML v2 tooling to inform architecture decisions:

Tool	Type	Language	Pros	Cons
Pilot Implementation	Full parser	Java	Complete parsing, official	JVM dependency, complex
API Services	REST server	Java/Scala	Standard API, well-documented	Requires PostgreSQL
Jupyter Kernel	Interactive	Python	Good for exploration	Depends on JVM parser
Python Client	API client	Python	Generated, maintained	Requires running API server

Conclusion: No existing lightweight Go-based tooling. MCP server fills this gap with basic parsing and API proxy capabilities. See Section 9.5 for technology choices.

3.7 Integration Options

3.7.1 Option A: Pure API Proxy

┌─────────────┐     ┌─────────────┐     ┌──────────────────┐
│ LLM Client  │────▶│ MCP Server  │────▶│ SysML v2 API     │
│             │     │ (Go)        │     │ (REST/HTTP)      │
└─────────────┘     └─────────────┘     └──────────────────┘

Pros: Simple, no JVM dependency, aligns with upstream API spec
Cons: Requires running API server, no offline parsing

3.7.2 Option B: Embedded Parser (JVM)

┌─────────────┐     ┌─────────────────────────────────────┐
│ LLM Client  │────▶│ MCP Server (JVM)                    │
│             │     │  ├── org.omg.sysml.interactive      │
└─────────────┘     │  └── SysML v2 API Client            │
                    └─────────────────────────────────────┘

Pros: Offline parsing, full AST access
Cons: Larger footprint, JVM dependency

3.7.3 Option C: Hybrid (Selected Approach)

┌─────────────┐     ┌─────────────┐     ┌──────────────────┐
│ LLM Client  │────▶│ MCP Server  │────▶│ SysML v2 API     │
│             │     │ (Go)        │     │ (for validation) │
└─────────────┘     │      │      │     └──────────────────┘
                    │      ▼      │
                    │ Basic Parser│
                    └─────────────┘

Go server with basic parsing, delegating full validation to API server.

Rationale: Balances deployment simplicity (single Go binary) with validation capability (API server for full SysML v2 compliance). Basic parsing handles common operations offline; API server handles complex validation when available.

3.8 Data Models

3.8.1 Element (JSON-LD)

{
  "@id": "uuid",
  "@type": "PartDefinition",
  "name": "Vehicle",
  "qualifiedName": "Package1::Vehicle",
  "ownedElement": [{"@id": "..."}],
  "owner": {"@id": "..."}
}

3.8.2 Query

{
  "@type": "Query",
  "select": ["@id", "name", "@type"],
  "where": {
    "@type": "CompositeConstraint",
    "operator": "and",
    "constraint": [
      {"@type": "PrimitiveConstraint", "property": "@type", "value": "PartDefinition"},
      {"@type": "PrimitiveConstraint", "property": "name", "value": "Vehicle"}
    ]
  }
}

3.9 MCP Tool Design

Based on upstream API capabilities, the MCP server implements tools in phases (see Section 8.3.1 for full requirements):

Phase	Tool	Description
0	sysml_parse	Parse SysML v2 text, extract elements (complete)
1	gitlab_read_file	Read .sysml file from GitLab repository
1	gitlab_list_models	List .sysml files in repo/directory
2	sysml_validate	Full validation via SysML v2 API server
2	sysml_query	Query elements by type/properties
2	gitlab_commit	Commit changes to GitLab
2	gitlab_create_mr	Create merge request

Resources follow MCP’s URI-based access pattern:

Resource URI	Phase	Description
sysml://examples/{name}	0	Bundled example models
gitlab://{project}/file/{path}	1	GitLab file access
sysml://projects	2	SysML v2 API project list

3.10 Licensing Considerations

All repositories use LGPL-3.0 (with GPL-3.0 for some components):

• Can link to LGPL libraries without making your code LGPL
• Modifications to LGPL code must be released under LGPL
• Compatible with building MIT-licensed MCP implementations

3.11 Industry Context: Agile Hardware Engineering

[1] argues that agile hardware engineering requires Git-based revision control for system models—not just agile tactics layered on legacy PLM tools. SysML v2’s textual notation enables branching/merging workflows approximating software engineering agility, with AI agents serving as “scribes” keeping models synchronized with engineering artifacts.

Aspect	INCOSE Formal	Agile Hardware
Reviews	Gated (SRR, PDR, CDR)	Continuous via PRs
Artifacts	Comprehensive docs	Lightweight models
Iteration	Spiral/Vee	Branch/merge cycles
AI Role	Analysis support	Model sync agent

Our position: This capstone follows INCOSE processes for academic rigor (see Section 5.1), while the MCP server aligns with the agile vision—enabling AI tools to interact with SysML models in Git via GitLab. The formal documentation proves we can do rigorous SE; the tooling enables teams to move faster when appropriate.

3.12 Key Findings

1. Parser complexity: Full SysML v2 parsing requires JVM (Xtext/EMF). A basic regex-based parser suffices for element extraction.

2. API maturity: The REST API spec is stable and well-documented. OpenAPI clients available for Java and Python.

3. Deployment burden: Running the reference API server requires PostgreSQL and JVM. Consider mock/stub for development.

4. JSON-LD format: All API responses use JSON-LD with @id, @type conventions. Must handle linked data patterns.

5. Query capability: The query language supports sophisticated filtering. Useful for AI-driven model exploration.

6. Git-native workflows: Industry momentum toward storing SysML v2 models in Git repositories, enabling software-style collaboration patterns [1].

[1]

S. Massey, “A discussion on accelerating hardware engineering through agile practices.” 2025. Available: https://resources.sysgit.io/a-discussion-on-accelerating-hardware-engineering-through-agile-practices/