Sysmlv2

A Model Context Protocol (MCP) server that exposes the SysML v2 REST API to AI assistants such as Claude, GPT, and any other MCP-compatible agent.

Supports STDIO (Claude Desktop / Claude Code) and Streamable HTTP (OpenAI Agents SDK / PLMgpt Gateway) transports.

Open source, MIT licensed. No commercial intent.

---

Compatible Backends

This server implements the OMG Systems Modeling API and Services specification and works with any compliant SysML v2 server:

Backend	Vendor	Notes
Teamwork Cloud (TWC)	Dassault Systèmes / 3DS	Full support including TWC-specific tools
SysON	Eclipse / Obeo	Standard OMG API tools; set TWC_SYSMLV2_PATH=/api
SysML v2 Pilot Implementation	OMG reference	Standard OMG API tools; usually no auth token needed
Any OMG-spec compliant server	—	Standard OMG API tools

Tools marked [TWC] in the tool table below are Teamwork Cloud specific and will not work on SysON or the pilot implementation.

---

Quick Start

# 1. Clone and install
git clone https://github.com/your-org/sysmlv2-mcp-server.git
cd sysmlv2-mcp-server
npm install

# 2. Configure
cp .env.example .env
# Edit .env — at minimum set TWC_BASE_URL and TWC_TOKEN

# 3. Build
npm run build

# 4. Run (STDIO mode — default)
npm start

# Run in HTTP mode
MCP_TRANSPORT_MODE=http npm start

---

Configuration

Copy .env.example to .env and set the values for your backend. All options are documented inline in .env.example.

Variable	Default	Description
TWC_BASE_URL	(required)	Your SysML v2 server base URL
TWC_SYSMLV2_PATH	/sysmlv2-api	API path prefix (empty "" for SysON/pilot, /sysmlv2-api for TWC)
TWC_TOKEN	(required for TWC)	API authentication token
MAGICLAB_BASE_URL	(TWC only)	MagicLab web UI URL for deep-link generation
TWC_INSECURE	false	Skip TLS verification (self-signed certs)
MCP_TRANSPORT_MODE	stdio	Transport: stdio or http
MCP_HTTP_PORT	3001	HTTP port (when mode=http)

Backend-specific setup

Teamwork Cloud (TWC)

TWC_BASE_URL=https://your-twc-server:8443
TWC_SYSMLV2_PATH=/sysmlv2-api
TWC_TOKEN=your-api-token
MAGICLAB_BASE_URL=https://your-twc-server:8443/magiclab
TWC_INSECURE=true   # if using self-signed cert

SysON

TWC_BASE_URL=http://localhost:8080
TWC_SYSMLV2_PATH=
TWC_TOKEN=           # leave blank if SysON has no auth
TWC_INSECURE=false

SysML v2 Pilot Implementation (reference server)

TWC_BASE_URL=http://localhost:9000
TWC_SYSMLV2_PATH=
TWC_TOKEN=           # no auth on reference server
TWC_INSECURE=false

---

Claude Desktop Setup (Step-by-Step)

This server has been tested and validated on Claude Desktop.

Step 1 — Clone and install

git clone https://github.com/your-org/sysmlv2-mcp-server.git
cd sysmlv2-mcp-server
npm install

Step 2 — Configure your environment

cp .env.example .env

Open .env and set at minimum:

TWC_BASE_URL=https://your-sysmlv2-server:8443
TWC_TOKEN=your-api-token

See the Configuration section for all options and backend-specific examples.

Step 3 — Build

npm run build

This compiles TypeScript to dist/index.js.

Step 4 — Configure Claude Desktop

Open (or create) your Claude Desktop config file:

Platform	Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json

Add the following (adjust the path to where you cloned the repo):

macOS / Linux

{
  "mcpServers": {
    "sysmlv2": {
      "command": "node",
      "args": ["/absolute/path/to/sysmlv2-mcp-server/dist/index.js"],
      "env": {
        "TWC_BASE_URL": "https://your-sysmlv2-server:8443",
        "TWC_TOKEN": "your-api-token",
        "TWC_SYSMLV2_PATH": "/sysmlv2-api",
        "TWC_INSECURE": "true"
      }
    }
  }
}

Windows

{
  "mcpServers": {
    "sysmlv2": {
      "command": "node",
      "args": ["C:\\path\\to\\sysmlv2-mcp-server\\dist\\index.js"],
      "env": {
        "TWC_BASE_URL": "https://your-sysmlv2-server:8443",
        "TWC_TOKEN": "your-api-token",
        "TWC_SYSMLV2_PATH": "/sysmlv2-api",
        "TWC_INSECURE": "true"
      }
    }
  }
}

Tip: You can pass all environment variables directly in the config env block instead of using a .env file — Claude Desktop will inject them when it starts the server.

Step 5 — Restart Claude Desktop

Fully quit and relaunch Claude Desktop. You should see the SysML v2 tools available in the tools panel (hammer icon).

Step 6 — Verify

Try asking Claude:

"List all my SysML v2 projects"

If the server is connected, Claude will call sysmlv2_get_projects and return your project list.

For more example prompts see EXAMPLES.md.

---

Transport Modes

STDIO (default)

For Claude Desktop, Claude Code, or any MCP client that launches the server as a subprocess.

{
  "mcpServers": {
    "sysmlv2": {
      "command": "node",
      "args": ["/path/to/sysmlv2-mcp-server/dist/index.js"],
      "env": {
        "TWC_BASE_URL": "https://your-sysmlv2-server:8443",
        "TWC_TOKEN": "your-token"
      }
    }
  }
}

Streamable HTTP

For OpenAI Agents SDK, PLMgpt Gateway, or web-based MCP clients.

MCP_TRANSPORT_MODE=http MCP_HTTP_PORT=3001 npm start

Endpoints:

• POST /mcp — Streamable HTTP (primary)
• GET /sse — SSE (legacy)
• GET /health — Health check

---

Tools (38 total)

Project Services (5) — Standard OMG API

Tool	Description
sysmlv2_get_projects	List all projects
sysmlv2_get_project	Get project by ID
sysmlv2_create_project	Create new project
sysmlv2_update_project	Update project name / description
sysmlv2_delete_project	Delete project (irreversible)

Commit Services (6) — Standard OMG API

Tool	Description
sysmlv2_get_commits	List commits for a project
sysmlv2_get_commit	Get commit by ID
sysmlv2_create_commit	Create new commit with optional change set
sysmlv2_diff_commits	Diff two commits (ADDED / UPDATED / DELETED)
sysmlv2_get_commit_changes	Get change set for a commit
sysmlv2_get_commit_change	Get a specific change by ID

Branch Services (5) — Standard OMG API

Tool	Description
sysmlv2_get_branches	List branches
sysmlv2_get_branch	Get branch by ID
sysmlv2_create_branch	Create new branch
sysmlv2_delete_branch	Delete branch (irreversible)
sysmlv2_merge_branch	Merge source commit into target branch

Tag Services (4) — Standard OMG API

Tool	Description
sysmlv2_get_tags	List tags
sysmlv2_get_tag	Get tag by ID
sysmlv2_create_tag	Create tag on a commit
sysmlv2_delete_tag	Delete tag

Element Navigation (4) — Standard OMG API

Tool	Description
sysmlv2_get_elements	Get all elements (paginated)
sysmlv2_get_element	Get element by ID
sysmlv2_get_roots	Get root elements — entry point for model traversal
sysmlv2_get_element_relationships	Get element relationships (IN / OUT / BOTH)

Query Services (7) — Standard OMG API

Tool	Description
sysmlv2_get_queries	List saved queries
sysmlv2_get_query	Get query by ID
sysmlv2_create_query	Create saved query
sysmlv2_update_query	Update saved query
sysmlv2_delete_query	Delete saved query
sysmlv2_execute_query	Execute ad-hoc query
sysmlv2_execute_query_by_id	Execute saved query by ID

Evaluation Services (3) — [TWC only]

These tools use Teamwork Cloud's parametric evaluation extension and are not part of the standard OMG API. They will not work on SysON or the pilot implementation.

Tool	Description
sysmlv2_evaluate	Evaluate parametric model at project level
sysmlv2_evaluate_commit	Evaluate parametric model at a specific commit
sysmlv2_export_evaluation_table	Export evaluation results as a table (project level)
sysmlv2_evaluate_commit_table	Export evaluation results as a table at a specific commit

Convenience Tools (3)

Tool	Backend	Description
sysmlv2_get_requirements	All	Query all RequirementUsage elements via server-side filter
sysmlv2_get_views	[TWC]	Query ViewUsage elements + MagicLab deep links
sysmlv2_open_magiclab	[TWC]	Generate MagicLab URL for a project or element

---

Authentication

The server tries authentication in this order and stops at the first success:

1. Token {TWC_TOKEN} header — TWC default
2. Bearer {TWC_TOKEN} header — OAuth / standard JWT
3. No auth — for open/unauthenticated servers (e.g. local pilot)

---

Architecture

src/index.ts            Single-file MCP server
  ├── Config            Environment-based configuration
  ├── HTTP helpers      apiRequest() with multi-auth fallback
  ├── Pagination        Link-header based paginatedGet()
  ├── SysMLv2MCPServer  Main class
  │   ├── registerProjectTools()
  │   ├── registerCommitTools()
  │   ├── registerBranchTools()
  │   ├── registerTagTools()
  │   ├── registerElementTools()
  │   ├── registerQueryTools()
  │   ├── registerEvaluationTools()   ← TWC specific
  │   ├── registerConvenienceTools()
  │   ├── runStdio()
  │   └── runHTTP()
  └── Auto-run          STDIO when executed directly

To add new tools, create a registerXxxTools() method in the class and call it from registerAllTools().

---

Importing for HTTP Mode

import { mcpServer, SysMLv2MCPServer } from "./dist/index.js";

// Run in HTTP mode
mcpServer.run("http");

---

Contributing

Contributions welcome. To add support for a new tool or backend-specific extension:

1. Add a registerXxxTools() method in SysMLv2MCPServer
2. Call it from registerAllTools()
3. If the tool is backend-specific, add a [TWC] / [SysON] marker in the README tool table
4. Submit a PR with a brief description of what API endpoint you're wrapping

---

License

MIT — free to use, modify, and distribute with attribution.

---

Publishing to GitHub

Prerequisites

• A GitHub account
• Git installed on your machine
• GitHub CLI (optional but makes it easier)

---

Option A — Using GitHub CLI (recommended, easiest)

Step 1 — Install GitHub CLI (if not already installed)

# macOS
brew install gh

# Windows (via winget)
winget install GitHub.cli

Step 2 — Log in

gh auth login

Follow the prompts — choose GitHub.com → HTTPS → authenticate via browser.

Step 3 — Navigate to the release folder

# macOS / Linux
cd /path/to/mcp-sysmlv2-server-release

# Windows
cd C:\path\to\mcp-sysmlv2-server-release

Step 4 — Initialise git and create the repo in one command

git init
git add .
git commit -m "Initial release"
gh repo create sysmlv2-mcp-server \
  --public \
  --description "MCP server exposing the SysML v2 REST API to AI assistants (Claude, OpenAI Agents). MIT licensed." \
  --push \
  --source .

Done — your repo is live at https://github.com/<your-username>/sysmlv2-mcp-server.

---

Option B — Using Git + GitHub website (manual)

Step 1 — Create a new repo on GitHub

1. Go to https://github.com/new
2. Set repository name: sysmlv2-mcp-server
3. Set description: MCP server exposing the SysML v2 REST API to AI assistants. MIT licensed.
4. Set visibility: Public
5. Do NOT check "Add a README", "Add .gitignore", or "Choose a license" — the repo must be empty
6. Click Create repository
7. Copy the repo URL shown (e.g. https://github.com/<your-username>/sysmlv2-mcp-server.git)

Step 2 — Initialise git in the release folder

cd /path/to/mcp-sysmlv2-server-release
git init

Step 3 — Stage all files

git add .

Step 4 — Verify nothing sensitive is included

git status

You should see only: src/index.ts, package.json, tsconfig.json, .env.example, README.md, EXAMPLES.md, .gitignore. No .env, no node_modules/, no dist/.

Step 5 — Create the first commit

git commit -m "Initial release — SysML v2 MCP Server v1.0.0"

Step 6 — Add the remote and push

git remote add origin https://github.com/<your-username>/sysmlv2-mcp-server.git
git branch -M main
git push -u origin main

Step 7 — Add a license on GitHub

1. Go to your new repo on GitHub
2. Click Add file → Create new file
3. Name it LICENSE
4. Click Choose a license template → select MIT
5. Fill in your name → Review and submit

---

After publishing — recommended GitHub settings

Add topics (improves discoverability): Go to your repo → click the ⚙️ gear icon next to "About" → add topics: sysml sysmlv2 mcp mbse model-context-protocol teamwork-cloud claude ai systems-engineering

Update the README repo URL: In README.md, replace:

git clone https://github.com/your-org/sysmlv2-mcp-server.git

with your actual URL:

git clone https://github.com/<your-username>/sysmlv2-mcp-server.git

Then commit and push:

git add README.md
git commit -m "Fix clone URL to actual repo"
git push

Add a release tag:

git tag -a v1.0.0 -m "v1.0.0 — Initial public release"
git push origin v1.0.0

Then on GitHub go to Releases → Draft a new release → select v1.0.0 → write release notes → publish.