v0.8.0

Every change here comes from a field report covering two models built end to end
through the tool surface (5 elements / 1 view, and 71 elements / 143
relationships / 5 views).

Breaking, twice: the file tools are now confined to allowed roots, defaulting
to your home directory; and validate_semantics, auto_layout_view and
connect_visible_relationships default to a summary-sized response. See Changed
for what moved and how to restore the previous behaviour.

Changed

• load_model_from_file, export_model_to_file and render_view_to_svg_file
  are confined to allowed filesystem roots. They previously accepted any path
  the launching account could reach, which is ordinary for a local MCP server but
  poor for one whose caller is an LLM agent acting on content it read from a
  model file. Two new environment variables set the boundary —
  MCP_ARCHIMATE_ALLOWED_READ_ROOTS and MCP_ARCHIMATE_ALLOWED_WRITE_ROOTS —
  each taking one or more absolute paths separated by the platform path
  separator, with ~ expanded.

  Unset, both default to your home directory. That keeps every documented
  workflow working (the quickstarts write to ~/Desktop) while putting /etc,
  system locations and other users' files out of reach. If you read or write
  models outside your home directory — a shared drive, /opt, a project under
  /srv — set the variables or those calls will now fail.

  Paths are expanded and fully resolved before the check, so .. segments and
  symlinks cannot escape: a symlink inside an allowed root pointing outside it
  resolves to its real target and is refused. A rejected path returns
  PATH_OUTSIDE_ALLOWED_ROOTS with the resolved path, the configured roots and
  the variable to change in error.details; an unusable configuration returns
  INVALID_ALLOWED_ROOTS rather than silently falling back. For reads the
  boundary is checked before the existence check, so an existing file outside the
  roots is indistinguishable from a missing one.

  This is not a sandbox — enforcement is in-process and the server still runs as
  the launching account — and the home default still exposes things like
  ~/.ssh. Narrow the roots when that matters. (ARC-050)

• Three tools default to detail="summary"; pass detail="full" for the old
  response. Response size was the dominant cost of driving this server: on a
  71-element, 143-relationship model with no views yet, validate_semantics
  returned 214 issues and about 55 KB — large enough that the client spilled it
  to disk rather than keep it in context — of which the repeated code,
  severity and message strings were most of the weight. The completeness
  checks fire once per element and once per relationship, so they are loudest
  exactly when they are least actionable: mid-build, before any view exists.

  • validate_semantics summary: issues_by_code maps each code to
    {count, severity, ids}, and errors carries the error-severity issues in
    full, so is_valid: false always arrives with its reason. There is
    deliberately no issues key in the summary — a caller that still reads
    it fails loudly rather than silently reading a shorter list.
  • auto_layout_view summary: identity, properties, metadata, node_count,
    connection_count, and a bounds box giving the canvas the layout
    consumed, which is what you need to place a note in free space. full adds
    the per-node geometry and connections.
  • connect_visible_relationships summary: counts only. Every relationship not
    drawable in the target view counts as a skip, so on a multi-view model that
    id list is close to the whole relationship set and every entry is expected.
    No severity_filter was added: the summary already separates errors from
    grouped warnings, so a build loop can read data.errors directly. (ARC-058)

• build_quality_report(include_togaf=true) returns the findings and the
  scale, not just tallies. It reported {"status": "limited", "score": 0, "advisory_findings_count": 7} — seven findings, none of them reachable, and a
  score against an unstated maximum. A caller could not tell "this assessment
  does not apply to your model" from "your model has seven real problems". The
  block now carries advisory_findings, max_score, hard_failures_count and
  compliance_claim, all of which were already computed. The scoring scale
  (0–7; ready at zero findings, partial at 3 or more, limited below) is
  now documented on assess_togaf_readiness. Per decision-015 the checklist
  itself is unchanged — no check was added, removed or reweighted. (ARC-059)

• auto_layout_view reports the layer band outcome as data. Requesting
  bands on a single-layer view correctly produces none, but the response said so
  only by omitting a view property, so "not applicable" and "failed" looked
  identical. Both response shapes now carry layer_bands_created and
  layer_bands_reason (single_layer_view, coverage_view, not_requested,
  strategy_does_not_use_bands, or engine_does_not_support_bands). This also
  covers the case the property could never express: a view that previously had
  bands and no longer qualifies keeps mcp:layer_bands as an empty string.
  (ARC-060)

Fixed

• A client-supplied ID could be reused across concept types, producing an
  export with a duplicate identifier. IDs were checked only against their own
  concept namespace, so the same id could be given to an element, a
  relationship, a view, a node and a connection at once — each step accepted.
  Both writers then emitted that identifier twice in a single document: in the
  exchange format identifier is the xs:ID that relationshipRef points at
  as a required xs:IDREF, so the file failed schema validation; in the native
  format two concepts sharing an id let an archimateElement reference resolve
  to the wrong one. Nothing caught it — the round trip through pyArchimate
  succeeds because it keys concepts by the same separate namespaces, and
  quality_gate="strict" checks visual, semantic and coverage issues but not id
  uniqueness. IDs are now unique model-wide. A collision within one concept type
  keeps its existing message; a cross-type collision names the holder in
  error.details.existing_concept_kind. Behaviour change: a model that
  reuses one id across concept types now errors where it previously succeeded —
  but that model was already producing an invalid export. (ARC-061)

• create_view left a view behind when it rejected the viewpoint. The
  viewpoint was validated after model.add(), so a call that returned
  {"status": "error"} still added the view — carrying the rejected value as
  its viewpoint property. The natural recovery, retrying with a corrected
  viewpoint, then failed with View with ID '...' already exists, leaving the
  caller holding a view it did not believe it had created. update_view had
  the same defect and was worse: it applied name and description before
  raising, so a failed call renamed the view. Both now validate before any
  mutation, so a rejected viewpoint changes nothing and the view_id stays
  free for the retry. (ARC-056)

Added

• list_supported_types now returns data.viewpoints. Viewpoints were the
  one string-typed enum in the API missing from the catalog the server's own
  instructions tell callers to consult, so the only way to discover the
  accepted values was to trigger an error. The new key publishes both accepted
  namespaces separately — pyarchimate_slugs (13, from pyArchimate's
  STANDARD_VIEWPOINTS) and archi_viewpoint_ids (25, Archi's canonical ids).
  They overlap in seven values without either containing the other, which is
  why a short-form/long-form rule of thumb does not work: business is a slug
  only, business_process_cooperation an Archi id only, and a plausible
  business_process is neither. Both the catalog and the rejection message now
  read the same source, so what the server advertises cannot drift from what it
  accepts. (ARC-057)

v0.7.4

Documentation only. No code or tool behaviour changed.

Fixed

• The license badge still linked to a 404 on PyPI. 0.7.3 made the README's
  links absolute but missed this one, because it is a nested image-link —
  [![alt](image)](target) — and the rewrite matched the inner image rather
  than the outer target. The verification used the same faulty pattern as the
  fix, so it reported clean. Re-checked with a paren-balancing scan that reads
  every link target directly. (ARC-055)

v0.7.3

Documentation only. No code or tool behaviour changed.

Fixed

• Every link on the PyPI project page was broken. README.md is the PyPI
  long_description, and relative markdown links resolve against the project
  page rather than the repository — so [User Guide](docs/USER_GUIDE.md) became
  https://pypi.org/project/mcp-archimate/docs/USER_GUIDE.md and 404'd. That
  affected all twelve navigational links, including the license badge, the whole
  Documentation table and the SECURITY and CONTRIBUTING pointers. All are now
  absolute github.com URLs, which work identically on GitHub. (ARC-055)

v0.7.2

Documentation only. No code or tool behaviour changed.

Changed

• README and User Guide no longer contradict each other on installation.
  docs/USER_GUIDE.md predated the PyPI release and still opened with
  git clone <repository-url> while the README said "nothing to clone". The
  User Guide now leads with uvx mcp-archimate and treats the source checkout
  as the contributor path. Both documents now describe the same four MCP clients
  (Claude Code, Claude Desktop, Codex, MCP Inspector) with identical
  configuration and the same archimate server key, so prompts stay portable
  between them. (ARC-054)
• The User Guide documents the security model. It was previously silent on
  the filesystem trust boundary and on model content being untrusted input —
  the one thing worth knowing before pointing an agent at your disk. (ARC-054)

Added

• Worked example prompts in the README, covering building a small model,
  exploring an existing one, editing it, improving it, validating and exporting,
  and one full end-to-end build. Editing and improving an existing model — the
  common case once a model exists — had no example at all before. (ARC-054)
• Troubleshooting for two things that look like faults and are not: an MCP
  client showing no tools (now with a way to tell a broken server from a broken
  config), and the server appearing to hang, which is correct stdio behaviour.
  (ARC-054)

Fixed

• Stale references in the User Guide: the server was still described as
  archimate-mcp (renamed in 0.7.1), and the mcp[cli] section described
  Claude Desktop install workflows that no longer exist. (ARC-054)

v0.7.1

Fixed

• The server reported the MCP SDK's version as its own. initialize returned
  serverInfo as archimate-mcp 1.28.1 — the pre-rename name, and the SDK
  version rather than this package's. FastMCP accepts no version argument, so
  the low-level Server kept version=None and fell back to pkg_version("mcp"),
  meaning the reported version tracked whichever SDK release was pinned. Clients
  now show mcp-archimate and the real package version. Display metadata only —
  no protocol behaviour changed — but a version that follows the SDK is
  misleading when diagnosing a problem against a specific release. (ARC-053)

v0.7.0

First public release. The project is now open source on GitHub and published
to PyPI as mcp-archimate, installable with uvx mcp-archimate. No tool, resource
or prompt behaviour changed in this release — the surface is the same 45 tools,
9 resources and 4 prompts as 0.6.0.

Changed

• License is now GPL-3.0-or-later (was a nominal MIT classifier with no
  LICENSE file). This is inherited, not chosen: pyArchimate is GPL-3.0-only
  and is a required runtime dependency, so the combined work users run is
  governed by the GPL. Using the server does not put your models under the
  GPL, and the license does not reach the agent or client calling the server
  across the stdio process boundary. See LICENSE, NOTICE, and
  decision-001. (ARC-041)
• Package metadata is now accurate. Real author and project URLs, keywords,
  corrected classifiers, and the version single-sourced from
  pyarchimate_mcp_server/__init__.py via [tool.hatch.version] — it is no
  longer duplicated in pyproject.toml. (ARC-042)
• Documentation restructured for a public audience. The README is now
  install-first; docs/README.md indexes what remains and names an owner for
  each document. (ARC-043)

Added

• LICENSE (full GPL-3.0 text) and NOTICE, crediting pyArchimate and
  Xavier Mayeur, and recording the licenses of the other runtime dependencies.
  (ARC-041)
• SECURITY.md — vulnerability disclosure, supported versions, and a plain
  statement of the trust model: the server runs with the filesystem rights of
  whoever launches it, and model content is untrusted input that can carry prompt
  injection. A README "Security considerations" section covers the same ground.
  (ARC-045)
• CONTRIBUTING.md — setup, the dev/main branch model, the Backlog
  workflow, and how to write a decision record. (ARC-044)
• Fifteen architecture decision records in .backlog/decisions/, capturing
  the load-bearing choices that were previously only prose warnings in
  CLAUDE.md or buried in task history — including why connection routing is
  implemented here rather than delegated upstream, why an explicit layout call
  never preserves existing positions, and why native Archi export has to repair
  the connection type. (ARC-044, ARC-051)
• tests/test_security.py — nine adversarial tests of the untrusted-input
  boundary covering XXE via inline, external and parameter entities, entity
  expansion, and the same payloads through load_model_from_file. No
  vulnerability was found; the existing defences were verified rather than
  assumed. (ARC-045)
• Continuous integration — lint, format check, and the test suite on Python
  3.10 through 3.13, plus a build and an sdist hygiene gate on every pull
  request. (ARC-046)
• Tag-triggered releases via PyPI Trusted Publishing, with no long-lived
  credential stored anywhere. (ARC-047)

Removed

• Task Master and Windsurf tooling, and the local configuration that came
  with them. Agent support is now scoped to Claude Code and Codex. The server
  itself needs no API keys or environment variables. (ARC-040)
• A 5 MB third-party Archi user guide PDF and a vendored snapshot of the MCP
  SDK documentation, neither of which was ours to redistribute or could stay
  current. (ARC-040)
• Four superseded documents — docs/SDD.md, docs/IMPLEMENTATION_PLAN.md,
  docs/UPGRADE_REPORT_2026-07-24.md and docs/PYPI_PUBLIC_RELEASE_PLAN.md.
  The SDD's glossary survives as an appendix to
  docs/TECHNICAL_ARCHITECTURE.md. (ARC-043)

Fixed

• The source distribution shipped internal files. The 0.6.0 sdist was 4.8 MB
  and contained .taskmaster/, .backlog/, agent configuration and the Archi
  PDF. [tool.hatch.build.targets.sdist] now uses an explicit allow-list, so
  anything added to the repository is excluded by default. The sdist is 199 KB
  and CI fails the build if a forbidden path reappears. (ARC-042, ARC-046)

Known limitations

• No filesystem sandboxing. load_model_from_file, export_model_to_file
  and render_view_to_svg_file accept any path the launching user can reach, and
  exports overwrite without prompting. Configurable allowed roots are planned
  (ARC-050); until then the boundary is whatever you impose from outside, such as
  a container or a dedicated account. Documented in SECURITY.md.

Note on history

The git history was reset to a single root commit for the public release. The
prior commits described an earlier architecture — FastAPI routes, a Graphviz
layout engine, a different task workflow — that no longer matches the code, so
keeping them would have been more misleading than useful. The decision records
in .backlog/decisions/ are the project's memory from here. See decision-010.
(ARC-048)