All 39 tools, generated from the live registry

This page lists every MCP tool jgs-sysmlv2-api-mcp registers, with its parameters and which ones are required. It is generated directly from build_server().tool_specs() by scripts/gen_tool_reference_html.py, the same registry that produces docs/TOOL-REFERENCE.md, so this page and the server can never drift apart. Full workflow walkthroughs live in docs/usage.md; this page is the parameter-level lookup.

§01 Navigation reads

`get_project`

Project metadata (name, description, default branch). Optional project_id overrides the configured project.

Parameter	Type	Required
`project_id`	string	no

`get_root_elements`

Root (unowned) elements at a commit: the entry point into a model. Filtered client-side (the pilot's /roots does not exclude owned elements). commit_id defaults to the branch head.

Parameter	Type	Required
`commit_id`	string	no

`get_children`

One level of owned children with id/name/type. commit_id defaults to head.

Parameter	Type	Required
`commit_id`	string	no
`element_id`	string	yes

`find_by_name`

Find elements by declaredName, optional type filter. commit_id defaults to head.

Parameter	Type	Required
`commit_id`	string	no
`name`	string	yes
`type`	string	no

`get_relationships`

Typed relationship elements touching an element (matches explicit source/target). direction: in|out|both. commit_id defaults to head.

Parameter	Type	Required
`commit_id`	string	no
`element_id`	string	yes
`direction`	string	no

`get_commit`

Fetch a single commit record (previousCommit, description, created).

Parameter	Type	Required
`commit_id`	string	yes

`get_commit_changes`

Full DataVersion change records of a commit (deletions have payload null).

Parameter	Type	Required
`commit_id`	string	yes

`list_commits`

List commits for the configured project. Order is not guaranteed to be newest-first (use resolve_head/get_commit for the actual head).

No parameters.

`get_element`

Fetch a single element (raw JSON, full fidelity) at a commit. commit_id defaults to the branch head.

Parameter	Type	Required
`commit_id`	string	no
`element_id`	string	yes

`query_elements`

Query elements at a commit with opaque-cursor pagination. commit_id defaults to the branch head.

Parameter	Type	Required
`commit_id`	string	no
`filter`	object	no
`cursor`	string	no
`page_size`	integer	no

`diff_commits`

Diff two commits -> {created, deleted, modified} element-id lists (client-side; pilot lacks native diff).

Parameter	Type	Required
`base_commit`	string	yes
`compare_commit`	string	yes

`nav_traverse`

Traverse owned-member hierarchy from a root element (cycle-safe). commit_id defaults to the branch head.

Parameter	Type	Required
`commit_id`	string	no
`root`	string	yes
`max_depth`	integer	no
`follow_relationships`	boolean	no
`include_names`	boolean	no

`get_licence`

Report the current licence state (valid, reason, tier, customer, expires, days_remaining, expires_soon, seats, features, source) from the in-memory state loaded once at server start. Always available; shows why authoring is locked when unlicensed.

No parameters.

§02 Export and validation

`export_project`

Bulk-export a project as a single JSON bundle (project metadata, commit metadata, all elements at a commit) for offline reasoning or backup. Aggregates data already readable one element at a time via get_project/get_commit/get_elements; it is not a new access boundary. commit_id defaults to the branch head.

Parameter	Type	Required
`commit_id`	string	no
`project_id`	string	no

`validate_model`

Run structural/referential validation over a commit's elements: duplicate @id, dangling source/target references, dangling ownedMemberElement/owningRelatedElement references, and containment cycles. Client-side checks only: no semantic/constraint/multiplicity validation. commit_id defaults to the branch head.

Parameter	Type	Required
`commit_id`	string	no
`project_id`	string	no

`export_plantuml`

Export a commit's elements as PlantUML text using a simplified, self-defined class-diagram convention (elements as classes, containment as composition, Subclassification/Specialization as generalization, other typed relationships as labelled associations). This is a simplified subset for quick visualization, not the full pilot %viz output. commit_id defaults to the branch head.

Parameter	Type	Required
`commit_id`	string	no
`project_id`	string	no
`root`	string	no

§03 Staged authoring writes

`create_element`

Stage creation of a new element under an owner (buffer-only). PRO tier, requires a licence.

Parameter	Type	Required
`type`	string	yes
`name`	string	yes
`owner`	string	yes

`modify_element`

Stage a modification to an existing element (buffer-only). PRO tier, requires a licence.

Parameter	Type	Required
`element_id`	string	yes
`changes`	object	yes

`delete_element`

Stage deletion of a single element (buffer-only; refuses if it owns children). PRO tier, requires a licence.

Parameter	Type	Required
`element_id`	string	yes

`delete_subtree`

Stage deletion of an element and its owned subtree (buffer-only). PRO tier, requires a licence.

Parameter	Type	Required
`element_id`	string	yes

`create_relationship`

Stage a typed relationship (buffer-only). Sets explicit source/target plus the type's concrete end fields (Subclassification, Specialization, Subsetting, Redefinition, FeatureTyping, Dependency); other types take concrete ends via properties. PRO tier, requires a licence.

Parameter	Type	Required
`type`	string	yes
`source`	string	yes
`target`	string	yes
`owner`	string	no
`properties`	object	no

`move_element`

Stage a rehome of an element to a new owner (buffer-only; modifies its OwningMembership at the commit). commit_id defaults to the branch head. PRO tier, requires a licence.

Parameter	Type	Required
`element_id`	string	yes
`new_owner`	string	yes
`commit_id`	string	no

`stage_batch`

Stage many operations atomically (all-or-nothing, buffer-only). Ops: {op: create|relate|modify|delete, ...}; create ops accept a caller-minted element_id so later ops in the batch can reference it. PRO tier, requires a licence.

Parameter	Type	Required
`operations`	array	yes

`review_changes`

Return the staged ops + a confirm token (must be reviewed before commit).

No parameters.

`commit_changes`

Commit the staged buffer; requires a fresh confirm token. PRO tier, requires a licence; applies immediately, no staging. If the POST response is lost after the request is sent, the server reconciles the branch head and returns one of three outcomes: landed (write applied; committed ops removed from the buffer; do not re-commit them), not_landed (nothing applied; re-review and commit again), or indeterminate (resolve the branch head later; expected_version is the head to look past).

Parameter	Type	Required
`message`	string	no
`confirm_token`	string	yes

`discard_changes`

Discard the staged buffer without committing.

No parameters.

§04 Project lifecycle

`create_project`

Create a project (name, optional description). The session stays bound to its configured project. PRO tier, requires a licence; applies immediately, no staging.

Parameter	Type	Required
`name`	string	yes
`description`	string	no

`update_project`

Rename or re-describe a project. project_id defaults to the configured project. Only provided fields change. PRO tier, requires a licence; applies immediately, no staging.

Parameter	Type	Required
`project_id`	string	no
`name`	string	no
`description`	string	no

`delete_project`

Delete a project (destructive; requires confirm: true). The session's configured project is refused; outcome is verified via the project list. PRO tier, requires a licence; applies immediately, no staging.

Parameter	Type	Required
`project_id`	string	yes
`confirm`	boolean	yes

`list_projects`

List projects visible to this API endpoint.

No parameters.

§05 Branch and tag versioning

`list_branches`

List branches (id, name, head commit). Optional project_id overrides the configured project.

Parameter	Type	Required
`project_id`	string	no

`create_branch`

Create a branch. head_commit_id defaults to the session branch head. PRO tier, requires a licence; applies immediately, no staging.

Parameter	Type	Required
`name`	string	yes
`head_commit_id`	string	no

`delete_branch`

Delete a branch (destructive; requires confirm: true). Outcome is verified via the branch list; the default branch is refused. PRO tier, requires a licence; applies immediately, no staging.

Parameter	Type	Required
`branch_id`	string	yes
`confirm`	boolean	yes

`merge_branch`

Squash-merge a source branch onto a target branch as one commit (requires confirm: true). Refuses with conflicting element ids if both branches changed the same element. PRO tier, requires a licence; applies immediately, no staging.

Parameter	Type	Required
`source_branch_id`	string	yes
`target_branch_id`	string	yes
`description`	string	no
`confirm`	boolean	yes

`set_branch`

Retarget this session at a branch: staged commits and default read head follow it. Refused while staged work exists.

Parameter	Type	Required
`branch_id`	string	yes

`list_tags`

List tags (name, tagged commit). Optional project_id overrides the configured project.

Parameter	Type	Required
`project_id`	string	no

`create_tag`

Tag a commit (checkpoint). commit_id defaults to the session branch head. PRO tier, requires a licence; applies immediately, no staging.

Parameter	Type	Required
`name`	string	yes
`commit_id`	string	no

§06 Infrastructure

`ping`

Minimal liveness probe: confirms the endpoint is reachable.

No parameters.

`stats`

Return a snapshot of server metrics counters.

No parameters.