| add_elementA | Add a new ArchiMate element to the active model. Call `list_supported_types` to discover valid `element_type` values
if you are not certain. The response `data.id` is the canonical
element ID; use it as `source_id`/`target_id` when adding
relationships and as `element_id` when adding view nodes.
Args:
element_type: A supported ArchiMate element type, e.g.
`BusinessActor`, `BusinessProcess`, `ApplicationComponent`,
`ApplicationService`, `DataObject`, `Node`, `Artifact`,
`Goal`, `Stakeholder`, `Grouping`, `AndJunction`,
`OrJunction`. Use `list_supported_types` for the full list.
name: Element name. Must be a non-empty string.
description: Optional element documentation text.
folder_path: Optional conceptual folder path. Roots are
normalized: `Business`, `/Business`, and `business` resolve
to `/Business`. Sub-folders such as `/Business/Actors` are
preserved.
properties: Optional custom property key-value pairs. Values are
stored as strings.
element_id: Optional stable element ID. When omitted a UUID is
generated.
Returns:
Success envelope with `data` shaped like an `ElementDetail`:
`{id, name, type, description, properties, folder,
incoming_relationship_ids, outgoing_relationship_ids}`.
Errors:
`INVALID_ELEMENT_NAME` when `name` is missing or blank.
`InvalidElementTypeError` for an unknown `element_type`.
`ModelNotFoundError` if no model is active.
`ModelOperationError` for a duplicate `element_id` or invalid
folder path.
|
| add_elementsA | Add multiple elements to the active model in one call. Each element item supports the same fields as `add_element`. Both
short and long field names are accepted (`type` or `element_type`,
`id` or `element_id`).
Element item shape:
```
{
"id": "id-customer", # optional stable ref
"name": "Customer", # required
"type": "BusinessActor", # required (alias: element_type)
"description": "...", # optional
"folder_path": "/Business", # optional
"properties": {"k": "v"} # optional
}
```
Args:
elements: List of element item objects.
rollback_on_error: When true (default), restore the previous
model state if any item fails. Set to false to keep partial
results.
Returns:
Success envelope with `data.elements` (list of `ElementDetail`),
`data.count`, and `data.rollback_on_error`.
Errors:
`ModelNotFoundError`, `InvalidElementTypeError`,
`ModelOperationError` for the first failing item.
|
| update_elementA | Update an existing ArchiMate element. Updates is a dict containing only the fields to change. Other fields
are left untouched. Properties are merged into existing properties
(use an empty value to clear a key on subsequent updates).
Args:
element_id: ID of the element to update.
updates: Mapping of fields to update. Supported keys:
- `name` (str): New element name.
- `description` (str): New documentation text.
- `folder_path` (str): New folder path; folder root must
match the element's ArchiMate category.
- `properties` (dict[str, str]): Property updates merged
into existing properties.
Element type cannot be changed; recreate the element to
change its type.
Returns:
Success envelope with the updated `ElementDetail` in `data`.
Errors:
`ElementNotFoundError` when `element_id` is unknown.
`ModelOperationError` for invalid folder paths.
|
| delete_elementA | Delete an ArchiMate element from the active model. pyArchimate also removes dependent concepts such as relationships
and visual nodes/connections referencing the deleted element.
Args:
element_id: ID of the element to delete.
Returns:
Success envelope with `data.deleted=true`.
Errors:
`ElementNotFoundError` when `element_id` is unknown.
|
| create_empty_modelA | Create a new empty ArchiMate model and make it the active model. Replaces any currently active model. Call this (or one of the
`load_model_*` tools) before any element/relationship/view tool.
Use `update_model` to change this metadata later, including on a
model that was loaded rather than created.
Args:
name: Human-readable model name. Must be a non-empty string.
description: Optional model-level documentation. Comes back as
`data.model_info.documentation` and survives both export
formats.
properties: Optional model-level properties. Keys and values are
coerced to strings.
Returns:
Success envelope with `data.model_id` (the new model UUID) and
`data.model_info` (same shape as `pyarchimate://activemodel/info`:
name, id, documentation, properties, elements_count,
relationships_count, views_count, is_loaded).
Errors:
`INVALID_MODEL_NAME` when `name` is missing or blank.
|
| update_modelA | Update the active model's name, documentation, and properties. Updates is a dict containing only the fields to change; other fields
are left untouched and properties are merged into the existing ones.
There is no `model_id` parameter because exactly one model is active.
Works on a loaded model, not only on one created by this server.
Unlike `update_element`, unknown keys are rejected rather than
ignored: a mis-keyed update would silently leave model metadata
unwritten while still reporting success.
Args:
updates: Mapping of fields to update. Supported keys:
- `name` (str): New model name. Must be non-blank; it is
stripped, exactly as in `create_empty_model`.
- `description` (str): New model documentation. Reported
back as `documentation`.
- `documentation` (str): Accepted alias for `description`.
- `properties` (dict[str, str]): Property updates merged
into the existing model properties.
Returns:
Success envelope with `data.model_info` (same shape as
`pyarchimate://activemodel/info`).
Errors:
`INVALID_MODEL_UPDATE` when `updates` is not an object or
contains unsupported keys (`error.details.unsupported_keys`
and `error.details.supported_keys` list which).
`INVALID_MODEL_NAME` when `name` is present but not a non-blank
string.
`ModelNotFoundError` if no model is active.
|
| load_model_from_contentA | Load an ArchiMate model from XML string content (replaces active model). For loading large files or paths use `load_model_from_file` instead;
this tool expects the actual XML payload, not a path.
Args:
model_content: XML content. Must start with `<` and be 10 MiB or
smaller. DTD and entity declarations are rejected for safety.
content_format: One of `archimate` (Open Group exchange XML,
default), `archi` (Archi native `.archimate` XML), or `xml`.
Returns:
Success envelope with `data.model_info` describing the loaded
model (see `pyarchimate://activemodel/info`).
Errors:
`INVALID_MODEL_CONTENT` when `model_content` is not XML.
`UnsupportedFormatError` when `content_format` is not recognized.
`ModelOperationError` when pyArchimate fails to parse the XML.
|
| export_model_contentA | Serialize the active model as XML string content. Use this when the caller wants the XML in the response payload. Use
`export_model_to_file` to write directly to disk.
Args:
output_format: One of `archimate` (default, Open Group exchange
XML), `archi` (Archi native `.archimate` XML, opens directly
in Archi), or `xml`.
auto_layout: When true, run layout on every view before
serialization. Defaults to false.
layout_strategy: Layout strategy used when `auto_layout=true`.
One of `layered_by_type` (default, ArchiMate semantic
lanes), `layered` (relationship-direction layered), or
`grid`.
layout_engine: Layout engine applied to every view when
`auto_layout=true`. One of `internal` (default) or
`pyarchimate` (see `auto_layout_view` for what the latter
gives up). Per-call only: nothing about the engine is
written into the exported file. Validated even when
`auto_layout=false`, so a typo is never swallowed.
Returns:
Success envelope with `data.content` (XML string),
`data.auto_layout`, and (when `auto_layout=true`)
`data.layout_strategy` and `data.layout_engine`.
Errors:
`ModelNotFoundError` if no model is active.
`UnsupportedFormatError` for an unknown `output_format`.
`ModelOperationError` for layout or serialization failures,
including an unknown strategy/engine (with
`error.details.suggestions`) and a view the `pyarchimate`
engine cannot lay out safely — one such view fails the
whole export.
|
| export_model_to_fileA | Serialize the active model and write it to a local file. Preferred when the user wants a `.archimate` file Archi can open
directly. Parent directories are created if missing.
Args:
path: Output path on the MCP server's filesystem. `~` is
expanded; relative paths resolve against the server's CWD.
output_format: One of `archi` (default, Archi native), `archimate`
(Open Group exchange), or `xml`.
auto_layout: When true, lay out every view before serialization.
layout_strategy: One of `layered_by_type` (default), `layered`,
or `grid`. Only applied when `auto_layout=true`.
layout_engine: One of `internal` (default) or `pyarchimate`
(see `auto_layout_view` for what the latter gives up).
Only applied when `auto_layout=true`, but always
validated. Per-call only: the engine is never recorded in
the written file.
Returns:
Success envelope with `data.path`, `data.output_format`,
`data.bytes_written`, `data.auto_layout`, and (when
`auto_layout=true`) `data.layout_strategy` and
`data.layout_engine`.
Errors:
`ModelNotFoundError` if no model is active.
`UnsupportedFormatError`, `ModelOperationError` for invalid
path/format, an unknown strategy/engine (with
`error.details.suggestions`), a view the `pyarchimate` engine
cannot lay out safely, or serialization failure.
|
| create_model_from_specA | Create a complete ArchiMate model from a structured JSON spec. The spec is applied transactionally by default. Element, relationship,
and view objects accept either short field names (`type`, `source`,
`target`, `id`, `element`, `relationship`) or the long forms used by
individual tools (`element_type`, `relationship_type`, `source_id`,
`target_id`, `element_id`, `relationship_id`, `view_id`).
Spec shape:
```
{
"name": "Model Name", # required
"elements": [ # optional list
{
"id": "id-customer", # optional stable ref
"name": "Customer", # required
"type": "BusinessActor", # required
"description": "...", # optional
"folder_path": "/Business", # optional
"properties": {"owner": "EA"} # optional
}
],
"relationships": [
{
"id": "id-uses", # optional stable ref
"type": "Serving", # required
"source": "id-customer", # required ref or UUID
"target": "id-portal", # required ref or UUID
"name": "uses", # optional
"description": "...", # optional
"properties": {...}, # optional
"access_type": "Read", # for Access only
"influence_strength": "+" # for Influence only
}
],
"views": [
{
"id": "id-context", # optional stable ref
"name": "Context", # required
"folder_path": "/Views", # optional
"nodes": [ # optional
{"element": "id-customer",
"x": 40, "y": 40, # x/y optional
"width": 160, "height": 80} # width/height optional
],
"connections": [ # optional
{"relationship": "id-uses"}
],
"connect_visible_relationships": true, # optional
"auto_layout": true, # optional
"layout_strategy": "layered_by_type", # optional
"layout_engine": "internal" # optional; or
# "pyarchimate"
}
]
}
```
Args:
spec: Specification object as described above.
rollback_on_error: When true (default), restore the previous
active model on any failure. Set to false to keep partial
results.
Returns:
Success envelope with `data` containing summary IDs of created
model, elements, relationships, and views.
Errors:
`INVALID_SPEC` for missing required keys.
`InvalidElementTypeError`, `InvalidRelationshipTypeError`,
`ElementNotFoundError`, `ModelOperationError` for validation or
creation failures.
|
| build_quality_reportB | Build a structured visual, semantic, coverage, and optional TOGAF report. |
| assess_togaf_readinessC | Return advisory TOGAF-oriented readiness findings. |
| export_elements_to_csvA | Export all active model elements as a CSV string. The CSV includes base columns `id`, `name`, `type`, `description`.
Custom properties are emitted as `Property:<name>` columns.
Returns:
Success envelope with `data.csv_data` containing the CSV string.
Errors:
`ModelNotFoundError` if no model is active.
|
| export_relationships_to_csvA | Export all active model relationships as a CSV string. The CSV includes base columns `id`, `name`, `type`, `source_id`,
`target_id`. Custom properties are emitted as `Property:<name>`
columns.
Returns:
Success envelope with `data.csv_data` containing the CSV string.
Errors:
`ModelNotFoundError` if no model is active.
|
| validate_modelA | Validate visual references in the active model. Delegates to pyArchimate's `check_invalid_conn` and
`check_invalid_nodes` helpers. Diagram-only annotation connectors
(a note line joining an Archi Note to an element) are excluded: they
have no backing relationship by design, so they are not defects. A
connector between two element-backed nodes whose relationship is
genuinely missing is still reported. Use `validate_semantics` for
ArchiMate semantic checks beyond visual references.
Returns:
Success envelope with `data.is_valid` (bool),
`data.invalid_connection_ids`, `data.invalid_node_ids`,
`data.invalid_connections_count`, and
`data.invalid_nodes_count`.
Errors:
`ModelNotFoundError` if no model is active.
|
| validate_semanticsA | Run ArchiMate semantic checks beyond visual reference validation. Checks include invalid relationship combinations, missing node
references, duplicate element names within the same folder/type,
elements not placed in any view, and orphan service/data elements.
Returns:
Success envelope with `data.is_valid` (bool), `data.issues`
(list of issue dicts), and `data.issues_count`.
Errors:
`ModelNotFoundError` if no model is active.
|
| list_supported_typesA | List supported ArchiMate types and configuration values. Always call this before generating model content if you are not
certain which names the running pyArchimate build accepts. The
catalog is version-specific.
Returns:
Success envelope with `data` containing element types grouped by
category, relationship types, folder roots, valid `access_type`
values, valid `influence_strength` values, supported layout
strategies, supported layout engines, and summary counts.
Does not require an active model.
|
| summarize_modelA | Summarize the active model: counts, view summaries, totals. Useful for verifying generation results without dumping full XML.
Returns:
Success envelope with `data` containing model name, total
element/relationship/view counts, and per-view node and
connection counts.
Errors:
`ModelNotFoundError` if no model is active.
|
| summarize_viewA | Summarize a single view: node count, connection count, gaps. Args:
view_id: ID of the view to summarize.
Returns:
Success envelope with `data` containing the view name, node
count, connection count, and relationships that could still be
connected (both endpoints visible) but are not yet drawn.
Errors:
`ModelNotFoundError` if no model is active.
`ViewNotFoundError` when `view_id` is unknown.
|
| count_by_typeA | Count active model content grouped by ArchiMate type. Returns:
Success envelope with `data.elements_by_type` and
`data.relationships_by_type`, each a dict of type name to count.
Errors:
`ModelNotFoundError` if no model is active.
|
| list_orphan_elementsA | List elements with no relationships and/or no view placement. Useful for finding gaps before completing a model.
Returns:
Success envelope with `data.elements_without_relationships`,
`data.elements_not_in_any_view`, and `data.fully_orphan_elements`
(each a list of element IDs), plus matching count fields.
Errors:
`ModelNotFoundError` if no model is active.
|
| query_elementsA | Query elements in the active model with optional filters. All filters are AND-combined. Pass an empty `{}` to list every
element (equivalent to the `pyarchimate://activemodel/elements`
resource).
Supported filter keys:
- `type` (str): Match elements with this exact ArchiMate type,
e.g. `BusinessActor`, `ApplicationComponent`.
- `name_contains` (str): Case-insensitive substring match
against element name.
- `properties_contain` (dict[str, str]): Match elements whose
custom properties contain every provided key/value pair.
Args:
filter_criteria: Dict containing zero or more of the keys
above. Unknown keys are ignored.
Returns:
Success envelope with `data.elements`, a list of
`ElementDetail` objects (`id`, `name`, `type`, `description`,
`properties`, `folder`, `incoming_relationship_ids`,
`outgoing_relationship_ids`).
Errors:
`ModelNotFoundError` if no model is active.
|
| query_relationshipsA | Query relationships in the active model with optional filters. All filters are AND-combined. Pass an empty `{}` to list every
relationship (equivalent to the
`pyarchimate://activemodel/relationships` resource).
Supported filter keys:
- `type` (str): Match relationships with this exact pyArchimate
relationship type, e.g. `Serving`, `Composition`,
`Assignment`. The `Relationship` suffix is not used.
- `source_id` (str): Match relationships whose source element
UUID equals this value.
- `target_id` (str): Match relationships whose target element
UUID equals this value.
Args:
filter_criteria: Dict containing zero or more of the keys
above. Unknown keys are ignored.
Returns:
Success envelope with `data.relationships`, a list of
`RelationshipDetail` objects (`id`, `name`, `type`,
`description`, `properties`, `access_type`,
`influence_strength`, `source_element_id`,
`target_element_id`).
Errors:
`InvalidRelationshipTypeError` for an unknown `type`.
`ModelNotFoundError` if no model is active.
|
| add_relationshipA | Add a new ArchiMate relationship between two elements. Both endpoints must already exist as elements in the active model.
Use `list_supported_types` to discover valid `relationship_type`,
`access_type`, and `influence_strength` values.
Args:
relationship_type: A supported pyArchimate relationship type,
without the `Relationship` suffix. Examples: `Assignment`,
`Serving`, `Composition`, `Aggregation`, `Realization`,
`Triggering`, `Flow`, `Access`, `Influence`,
`Specialization`, `Association`. Note: Archi's "Used By"
concept maps to `Serving`.
source_id: ID of the source element.
target_id: ID of the target element.
name: Optional relationship name.
description: Optional documentation text.
properties: Optional custom property key-value pairs (string
values).
access_type: Required only for `Access` relationships. One of
`Access`, `Read`, `Write`, `ReadWrite`.
influence_strength: Required only for `Influence` relationships.
One of `+`, `++`, `-`, `--`, or `0`-`10`.
relationship_id: Optional stable relationship ID. When omitted a
UUID is generated.
Returns:
Success envelope with `data` shaped like a `RelationshipDetail`:
`{id, name, type, description, properties, access_type,
influence_strength, source_element_id, target_element_id}`.
Errors:
`InvalidRelationshipTypeError` for an unknown
`relationship_type`.
`ElementNotFoundError` when `source_id` or `target_id` is
unknown.
`ModelNotFoundError` if no model is active.
`ModelOperationError` for invalid relationship combinations,
duplicate `relationship_id`, or unsupported access/influence
values.
|
| add_relationshipsA | Add multiple relationships to the active model in one call. Each relationship item supports the same fields as `add_relationship`.
Short and long field names are both accepted (`type` or
`relationship_type`, `source` or `source_id`, `target` or
`target_id`, `id` or `relationship_id`).
Relationship item shape:
```
{
"id": "id-uses", # optional stable ref
"type": "Serving", # required (alias: relationship_type)
"source": "id-customer", # required (alias: source_id)
"target": "id-portal", # required (alias: target_id)
"name": "uses", # optional
"description": "...", # optional
"properties": {"k": "v"}, # optional
"access_type": "Read", # for Access only
"influence_strength": "+" # for Influence only
}
```
Args:
relationships: List of relationship item objects.
rollback_on_error: When true (default), restore the previous
model state if any item fails.
Returns:
Success envelope with `data.relationships` (list of
`RelationshipDetail`), `data.count`, and
`data.rollback_on_error`.
Errors:
`InvalidRelationshipTypeError`, `ElementNotFoundError`,
`ModelNotFoundError`, `ModelOperationError` for the first
failing item.
|
| update_relationshipA | Update an existing ArchiMate relationship. Endpoints (source/target) and relationship type cannot be changed.
Recreate the relationship to change those.
Args:
relationship_id: ID of the relationship to update.
updates: Mapping of fields to update. Supported keys:
- `name` (str)
- `description` (str)
- `properties` (dict[str, str]): merged into existing
properties.
- `access_type` (str): only meaningful for `Access`. One of
`Access`, `Read`, `Write`, `ReadWrite`.
- `influence_strength` (str): only meaningful for
`Influence`. One of `+`, `++`, `-`, `--`, or `0`-`10`.
Returns:
Success envelope with the updated `RelationshipDetail` in
`data`.
Errors:
`RelationshipNotFoundError` when `relationship_id` is unknown.
`ModelOperationError` for unsupported access/influence values.
|
| delete_relationshipA | Delete an ArchiMate relationship from the active model. pyArchimate also removes any visual connections that referenced the
deleted relationship.
Args:
relationship_id: ID of the relationship to delete.
Returns:
Success envelope with `data.deleted=true`.
Errors:
`RelationshipNotFoundError` when `relationship_id` is unknown.
|
| get_relationship_compatibilityB | Return valid ArchiMate relationship options for source and target types. |
| recommend_relationshipC | Recommend valid relationship types for source/target ids or types. |
| repair_semantic_issuesC | Apply selected deterministic semantic relationship repairs. |
| create_viewA | Create a new ArchiMate view (diagram) in the active model. Views are containers for visual nodes and connections. Add nodes
with `add_node_to_view` and connections with
`add_connection_to_view` once both endpoint elements are visible.
Set a `viewpoint` so the view opens with the right Archi viewpoint
(e.g. `layered` for mixed-layer overviews, `capability` for
capability maps, `service_realization` for service views).
Args:
name: View name. Must be a non-empty string.
view_id: Optional stable view ID. When omitted a UUID is
generated.
folder_path: Optional folder path. The `Views` root is
normalized: `Views`, `/Views`, and `views` resolve to
`/Views`.
viewpoint: Optional viewpoint: any canonical Archi viewpoint id
(e.g. `layered`, `application_cooperation`) or pyArchimate
slug. Invalid values fail with the accepted catalogs in
`error.details`.
Returns:
Success envelope with `data` shaped like a `ViewDetail`:
`{id, name, nodes: [], connections: []}`.
Errors:
`INVALID_VIEW_NAME` when `name` is missing or blank.
`ModelNotFoundError` if no model is active.
`ModelOperationError` for a duplicate `view_id` or invalid
folder path.
|
| update_viewA | Update an existing ArchiMate view. Only metadata fields can be updated; nodes and connections are
managed by `add_node_to_view`, `add_connection_to_view`, and the
layout tools.
Args:
view_id: ID of the view to update.
updates: Mapping of fields to update. Supported keys:
- `name` (str): New view name.
- `description` (str): New documentation text.
- `properties` (dict[str, str]): Property updates merged
into existing properties.
Returns:
Success envelope with the updated `ViewDetail` in `data`.
Errors:
`ViewNotFoundError` when `view_id` is unknown.
|
| delete_viewA | Delete an ArchiMate view from the active model. Removes the view and its visual nodes/connections. Underlying
elements and relationships are NOT removed.
Args:
view_id: ID of the view to delete.
Returns:
Success envelope with `data.deleted=true`.
Errors:
`ViewNotFoundError` when `view_id` is unknown.
|
| add_node_to_viewA | Add an ArchiMate element as a visual node in a view. If `x`/`y` are omitted, or the requested rectangle would overlap an
existing node, the server places the node in the next free slot.
Default node size is 160x80 (junctions are normalized to 32x32 by
`auto_layout_view`).
Args:
view_id: ID of the target view.
element_id: ID of the element to render in the view.
x: Optional preferred X coordinate (top-left, integer pixels).
y: Optional preferred Y coordinate (top-left, integer pixels).
width: Node width in pixels. Defaults to 160.
height: Node height in pixels. Defaults to 80.
node_id: Optional stable visual node ID. When omitted a UUID is
generated.
Returns:
Success envelope with `data.node_id` containing the visual
node's UUID.
Errors:
`ViewNotFoundError` (returned as `ModelOperationError` from the
manager) when `view_id` is unknown.
`ElementNotFoundError` when `element_id` is unknown.
`ModelOperationError` for a duplicate `node_id`.
|
| add_note_to_viewA | Add a diagram-only note (sticky annotation) to a view. Use this to comment on a diagram — a caveat, an owner, a "retire in
FY27". Do NOT create a `Grouping` element just to write a comment:
that pollutes the model tree and participates in validation, while a
note does not.
Notes are visual only. A note has no ArchiMate element, no folder
and no model-tree entry, so it never shows up in `query_elements`,
`count_by_type`, `list_orphan_elements` or the coverage section of
`build_quality_report`. `connect_to_node_ids` draws annotation-only
connector lines that create NO ArchiMate relationship.
`x`/`y` are kept exactly as given, including across
`auto_layout_view` (both layout engines), because a note annotates
one specific spot. Layout will not move element nodes out from under
a note, so place notes in free space — off to the side of the
diagram, or below it. Routed connections are drawn around notes.
Args:
view_id: ID of the target view.
text: Note text. Must be non-empty; kept verbatim, so multi-line
text keeps its line breaks and indentation. Verbatim also
means escape sequences are NOT interpreted: pass real line
breaks for a multi-line note, because a literal backslash-n
is stored and rendered as those two characters.
x: X coordinate (top-left, integer pixels). Used exactly.
y: Y coordinate (top-left, integer pixels). Used exactly.
width: Note width in pixels. Defaults to 185 (Archi's default).
height: Note height in pixels. Defaults to 80.
connect_to_node_ids: Optional list of things to point at. Each
entry may be a visual node ID or an element ID that is
already visible in this view.
note_id: Optional stable visual node ID. When omitted a UUID is
generated.
Returns:
Success envelope with `data.node_id`, `data.connection_ids`,
`data.connected_node_ids` (resolved visual node IDs),
`data.text`, and the geometry `data.x`, `data.y`,
`data.width`, `data.height`.
Errors:
`INVALID_NOTE_TEXT` when `text` is missing or blank.
`ViewNotFoundError` when `view_id` is unknown.
`ModelOperationError` for a duplicate `note_id`, or for connect
targets that are not visible in the view — the unresolved
IDs are listed in `error.details.unknown_ids` and nothing is
created.
Notes are not updatable or deletable yet: recreate the view (or the
note) if the text or placement needs to change.
|
| add_nodes_to_viewA | Add multiple visual nodes to a view in one call. Each node item supports the same fields as `add_node_to_view`. Both
short and long field names are accepted (`element` or `element_id`,
`id` or `node_id`).
Node item shape:
```
{
"id": "id-customer-node", # optional stable ref
"element": "id-customer", # required (alias: element_id)
"x": 40, "y": 40, # optional, auto-placed if absent
"width": 160, "height": 80 # optional, defaults shown
}
```
Args:
view_id: ID of the target view.
nodes: List of node item objects.
rollback_on_error: When true (default), restore the previous
view state if any item fails.
Returns:
Success envelope with `data.node_ids`, `data.count`, and
`data.rollback_on_error`.
Errors:
`ModelOperationError` (view not found / duplicate node_id) and
`ElementNotFoundError` for the first failing item.
|
| auto_layout_viewA | Automatically reposition all nodes in a view to avoid overlap. The default `internal` layout nests Aggregation/Composition members
inside visible Grouping nodes, wraps wide lanes into multiple rows,
aligns connected nodes vertically across lanes, and routes
connections orthogonally around nodes. With `layer_bands` (default
true) and the `layered_by_type` strategy, views spanning two or
more ArchiMate layers get labeled visual bands (diagram-only Archi
Groups — the semantic model is never modified; set
`layer_bands=false` to disable).
The engine choice applies to this call only. It is never stored on
the model or the view, so it cannot appear in an export or in
Archi's Properties tab.
Note: parameter is `strategy` (matches `auto_layout_view`) but the
equivalent parameter on `export_model_content` and
`export_model_to_file` is named `layout_strategy`.
Args:
view_id: ID of the view to lay out.
strategy: One of:
- `layered_by_type` (default): ArchiMate semantic lanes
(Motivation/Strategy on top, then Business, Application,
Application Data, Technology/Physical/Implementation).
- `layered`: relationship-direction layered, source nodes
before target nodes.
- `grid`: compact non-overlapping grid, no semantic
ordering.
Ignored (but still validated) by the `pyarchimate` engine,
which has a single fixed algorithm.
layout_engine: One of:
- `internal` (default): everything described above.
- `pyarchimate`: pyArchimate's own coarse-grid placement.
Much faster on large views, but it applies no `strategy`,
no layer bands, no lane wrapping, no barycenter
alignment, and no ArchiMate lane ordering (its own layer
classification misplaces SystemSoftware, Artifact, Path,
Equipment, Facility, Material, Contract, Representation
and ImplementationEvent). Best for flat views of
default-sized nodes. It has no collision detection, so a
view whose nodes do not fit its grid cell is refused
rather than silently overlapped — see Errors.
Returns:
Success envelope with the resulting `ViewDetail` in `data`
(nodes with updated x/y/width/height and connections). Under
`pyarchimate` the message says which options were not applied.
Errors:
`ViewNotFoundError` (returned as `ModelOperationError`) when
`view_id` is unknown.
`ModelOperationError` for an unknown strategy or engine, with
close matches in `error.details.suggestions`.
`ModelOperationError` when `layout_engine="pyarchimate"` cannot
lay the view out safely, with `error.details.grid_size` and
`error.details.oversized_nodes`. No placement is written, so
the view is never left half laid out, but the shared
prologue (Grouping nesting, group sizing) may already have
repaired it. Retry with `layout_engine="internal"`.
|
| render_view_to_svg_fileA | Render one view to an SVG file so a human can look at the diagram. Use this when someone wants to *see* a view without opening Archi —
to check that a layout reads well, or to drop a picture into a
document or chat. Lay the view out first with `auto_layout_view` if
the geometry needs work: rendering never moves anything.
SVG is a rendering, NOT a third model format. It cannot be imported
back into Archi and it is not a substitute for
`export_model_to_file` (`archi` = Archi native `.archimate`,
`archimate` = Open Group exchange XML). Use those to persist a
model; use this to look at one view.
The markup is written to disk and never returned: an 11-element view
is already ~3.2k tokens of SVG text, and reading it back would not
tell you anything you cannot get from `summarize_view` or
`build_quality_report`. Hand the returned path to the user.
Args:
view_id: ID of the view to render.
path: Output path on the MCP server's filesystem (`.svg`
conventionally). `~` is expanded, relative paths resolve
against the server's CWD, and parent directories are
created if missing.
Returns:
Success envelope with `data.path`, `data.view_id`,
`data.view_name`, `data.model_name`, `data.bytes_written`,
`data.node_count`, `data.connection_count`, and the rendered
canvas size in `data.width` / `data.height`. Never the markup.
Errors:
`ModelNotFoundError` if no model is active.
`ViewNotFoundError` when `view_id` is unknown.
`ModelOperationError` for a blank path or a write failure.
|
| add_connection_to_viewA | Add a visual connection for a relationship in a view. Both endpoint elements of the relationship must already be visible
as nodes in the view. Use `add_node_to_view` to add missing
endpoints first, or call `connect_visible_relationships` to draw
every relationship whose endpoints are already visible.
Args:
view_id: ID of the target view.
relationship_id: ID of the relationship to render.
connection_id: Optional stable visual connection ID. When
omitted a UUID is generated.
Returns:
Success envelope with `data.connection_id` containing the
visual connection UUID.
Errors:
`ModelOperationError` when `view_id` is unknown, when either
endpoint node is not present in the view, or when
`connection_id` is duplicated.
`RelationshipNotFoundError` when `relationship_id` is unknown.
|
| add_connections_to_viewA | Add multiple visual connections to a view in one call. Each connection item supports the same fields as
`add_connection_to_view`. Both short and long field names are
accepted (`relationship` or `relationship_id`, `id` or
`connection_id`).
Connection item shape:
```
{
"id": "id-uses-conn", # optional stable ref
"relationship": "id-uses" # required (alias: relationship_id)
}
```
Args:
view_id: ID of the target view.
connections: List of connection item objects.
rollback_on_error: When true (default), restore the previous
view state if any item fails.
Returns:
Success envelope with `data.connection_ids`, `data.count`, and
`data.rollback_on_error`.
Errors:
`ModelOperationError` and `RelationshipNotFoundError` for the
first failing item.
|
| connect_visible_relationshipsA | Add visual connections for every relationship whose endpoints are visible. Iterates over every relationship in the active model and, when both
its source and target elements are already visible nodes in the
view, adds the missing visual connection. Existing connections are
skipped.
Args:
view_id: ID of the target view.
rollback_on_error: When true (default), restore the previous
view state if any connection fails.
Returns:
Success envelope with `data.connection_ids` (newly added),
`data.added_count`, `data.skipped_relationship_ids`, and
`data.skipped_count`.
Errors:
`ModelOperationError` when `view_id` is unknown.
|
| ensure_all_relationships_in_viewsA | Ensure every model relationship is rendered in at least one view. Useful when Archi Validator reports `Unused Relation` or
`'Serving relation' is not used in a View`. The tool creates or
reuses a coverage view, adds the missing endpoint nodes, and adds
the missing connections. It also relocates redundant
Grouping-to-contained-child Aggregation/Composition connections out
of readable views into the coverage view (containment communicates
the meaning visually instead).
Coverage views are marked with the `mcp:relationship_coverage_view`
property, so future invocations recognize them regardless of the
display name.
Args:
coverage_view_name: Name of the coverage view. If a view with
this name exists, it is reused; otherwise it is created.
auto_layout: When true (default), lay out the affected views
after adding nodes and connections.
layout_strategy: Validated for consistency with other layout
tools but not applied — the coverage view layout is a fixed
source/target pair grid.
layout_engine: Must be `internal` (the default). The coverage
layout is a fixed pair grid, so no other engine can be
honoured here and passing one is an error rather than a
silently ignored hint.
rollback_on_error: When true (default), restore the previous
model state if coverage creation fails.
Returns:
Success envelope with `data` containing the coverage view ID,
added node and connection counts, relocated containment
connection counts, skipped relationship IDs, and remaining
unused relationship IDs.
Errors:
`ModelNotFoundError` if no model is active.
`ModelOperationError` for an unknown layout strategy/engine
(with `error.details.suggestions`), or for any engine other
than `internal`. Both are validated whether or not
`auto_layout` is true.
|
| get_usage_guideA | Return the client-facing usage guide for this ArchiMate MCP server. Call this tool when you are unsure how to operate the server. It is
intended to prevent source-code inspection: do not inspect the MCP
server source code to learn normal usage. Use this guide, prompts,
tools/list, and resources/list instead.
Returns:
Success envelope with recommended workflows, anti-patterns,
response conventions, and important tools.
|
| load_model_from_fileA | Load an ArchiMate model from a local file (replaces active model). The preferred entry point when the user gives a local `.archimate`
or XML file path. Expects a filesystem path readable by the MCP
server process; for raw XML text use `load_model_from_content`.
By default the response includes a compact inspection (summary,
type counts, validation status, recommended next calls) so a
separate `inspect_active_model` round trip is unnecessary.
Args:
path: Local filesystem path readable by the MCP server process.
`~` is expanded; relative paths resolve against the server CWD.
content_format: One of `archi` (default, Archi native
`.archimate`), `archimate` (Open Group exchange XML), or
`xml`.
inspect_after_load: When true (default), include a compact model
summary, type counts, validation status, and recommended next
calls in the response.
include_semantic_validation: When true (default), include a
compact semantic validation summary when inspecting.
sample_limit: Maximum number of issue/orphan examples to include
in compact summaries. Clamped to 0-50.
Returns:
Success envelope with `data.model_info`, `data.loaded_from`, and
optionally `data.inspection`.
Errors:
`INVALID_PATH`, `FILE_NOT_FOUND`, `FILE_READ_ERROR`,
`UnsupportedFormatError`, or `ModelOperationError`.
|
| inspect_active_modelA | Inspect the active model without dumping full XML or source code. Use this immediately after loading an existing model and before
editing. It combines model info, summaries, type counts, visual
validation, compact semantic validation, compact orphan summaries,
and recommended next calls.
Args:
include_semantic_validation: Include compact semantic validation
summary. Defaults to true.
include_orphans: Include compact orphan element summary.
Defaults to true.
sample_limit: Maximum number of issue/orphan examples to include.
Clamped to 0-50.
Returns:
Success envelope with compact inspection data.
Errors:
`ModelNotFoundError` if no model is active.
|
