jgs-magic-sysmlv1-mcp

execute_groovy

Execute Groovy scripts within CATIA Magic's JVM to access and manipulate SysML v1 model elements.

Instructions

Execute Groovy script inside CATIA Magic's JVM with full SysML v1 API access. Requires dev mode active on the plugin side (see enable_dev_mode). Dev mode is a plugin-lifetime capability: it can only be enabled if JGS_V2_DEV_SECRET was set in the CATIA Magic process environment at startup, and the client must supply the matching secret value to enable_dev_mode. Dev mode is independent of licence tier: a FREE-tier client whose plugin was launched with JGS_V2_DEV_SECRET set can still enable dev mode and call execute_groovy. The env var is the security control.

A 'helpers' object is pre-loaded with convenience methods for the v1 (UML/MagicDraw-profile) API. All stereotype names are SysML profile names (e.g. "Block", "Requirement", "Satisfy") — strings, NOT classes:

helpers.findByQN('Model::Pkg::Element') — find by qualified name; returns the Element or null.

helpers.createElement(parent, 'name', factoryFn, stereotypeName=null) — create element under parent. factoryFn is a 0-arg closure returning a fresh element from project.elementsFactory, e.g. { project.elementsFactory.createClassInstance() } (for Block / Requirement) { project.elementsFactory.createPackageInstance() } (for Package) Optionally applies a SysML stereotype by name.

helpers.applyStereotype(element, 'Block') — apply a SysML stereotype by name (uses StereotypesHelper internally).

helpers.setTaggedValue(element, 'Requirement', 'id', 'REQ-001') — set a stereotype-tagged property value.

helpers.getTaggedValue(element, 'Requirement', 'id') — read a stereotype-tagged property value; returns a List (may be empty) or null.

The 'project' binding is pre-loaded with the currently-open Project instance.

Returns a pretty-printed JSON string (str, not dict — intentional: LLM consumers parse the indented JSON for readability, matching v2's macro_tools convention; other v1 tools return dict because FastMCP auto-serialises them, which is fine for non-LLM-facing payloads).

JSON shape (matches v2's executeGroovyStatic exactly): success (bool): true on successful eval, false on exception result (str): script return value via String.valueOf, "null" if script returned null. Only present when success. output (str): captured stdout/stderr from the script error (str): exception message. Only present when not success.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`script`	Yes

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.1Sep 9, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full behavioral burden and handles it thoroughly. It discloses the return type (str, not dict), the exact JSON shape including conditional fields, stdout/stderr capture, exception behavior, pre-loaded bindings, helper semantics, and the dev-mode security control. This is far beyond what an annotation set would typically provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every section earns its place: purpose, security prerequisite, helper API reference, binding explanation, and return format. It is front-loaded with the core purpose and uses code blocks and bullets for scannability. For a tool this general-purpose, the length is justified.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has one parameter, no annotations, and a nontrivial execution environment, the description is remarkably complete. It covers prerequisites, security model, helper methods, available bindings, exception behavior, and output schema. There is no significant missing context that would prevent correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and only names 'script', so the description must compensate. It does so richly by showing what the script should contain, giving usable helper examples, and explaining the available 'project' binding and return contract. The agent gets enough concrete grounding to construct valid Groovy script content despite no schema-level parameter documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear action, resource, and scope: 'Execute Groovy script inside CATIA Magic's JVM with full SysML v1 API access.' This distinguishes it from the many specialized sibling tools by presenting it as a generic script-execution endpoint with broad API access. The level of detail makes the tool's role unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says dev mode must be active and points to enable_dev_mode, explaining the security condition and licence independence. It does not spell out 'prefer a dedicated sibling tool for single-purpose changes,' but the context strongly implies execute_groovy is the advanced escape hatch. This is clear usage guidance with a small gap around alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server