@formtrieb/cdf-mcp - npm Package Compare versions

Comparing version 1.7.3 to 2.0.0

CHANGELOG.md

@@ -5,5 +5,69 @@ # Changelog — `@formtrieb/cdf-mcp`
 format loosely follows [Keep a Changelog](https://keepachangelog.com/);
-the project is pre-1.0 public, so breaking changes still happen but are
-called out explicitly.
+breaking changes are flagged per-release with explicit migration notes.
 
+## [2.0.0] — 2026-07-12
+
+npm's published `latest` for `@formtrieb/cdf-mcp` is `1.7.3` — the
+in-repo 1.8.0 version bump never shipped to npm. Its one addition
+(`cdf_decollapse`) is folded into this release rather than published
+as its own version.
+
+### Added — `cdf_decollapse` tool
+
+De-collapses a crammed property or token-suffix enum (declared values
+taken verbatim, e.g. from a Figma component set's variant list) into
+candidate independent axes and lists the implied-but-undeclared
+combinations as questions for the author to confirm or reject.
+Optional `token_names` cross-checks each observed value against a
+token family to flag enum values with no backing token. Thin wrapper
+on `decollapse()` from `@formtrieb/cdf-core`; response adds a
+`plain_language` field (human sentences, no spec citations, no CDF
+jargon) alongside the full result.
+
+### BREAKING — Five zero-consumer profile-read tools removed
+
+`cdf_get_profile_section`, `cdf_list_profiles`, `cdf_coverage_profile`,
+`cdf_diff_profile`, and `cdf_resolve_extends` (all added in v1.6.0) are
+deleted. They read/derived views over Profile YAML that duplicate
+either a generic file read or an existing component-scope tool; no
+observed caller depended on the profile-specific variant.
+
+**Migration:**
+- `cdf_get_profile_section` / `cdf_list_profiles` → read the Profile
+  YAML directly; no direct MCP replacement (`cdf_get` is component-scope
+  only — its sections don't cover Profile YAML).
+- `cdf_coverage_profile` → read the Profile YAML directly; no direct
+  MCP replacement (`cdf_coverage` works on component specs only — it
+  has no profile-orphan detection). The underlying cdf-core function,
+  `analyzeProfileCoverage`, remains exported for library consumers.
+- `cdf_diff_profile` → read the Profile YAML directly; no direct MCP
+  replacement (`cdf_diff` cannot parse Profile YAML). The underlying
+  cdf-core function, `diffProfiles`, remains exported for library
+  consumers.
+- `cdf_resolve_extends` → no longer needed as a separate call.
+  `parseProfile` in `@formtrieb/cdf-core` is `extends:`-aware (since
+  v1.4.1) and resolves the chain implicitly on load; every tool that
+  loads a Profile already sees the merged shape.
+
+### BREAKING — Lean-by-default tool surface (`CDF_MCP_TOOLSET`)
+
+New installs register only 3 tools by default: `cdf_decollapse`,
+`cdf_vocab_diverge`, `cdf_validate_profile` — the day-to-day
+LLM-authoring loop an evaluator or CDF-authoring workflow reaches for
+most. The remaining 15 tools (component listing/reading/resolving,
+Profile validation extras, Figma access, spec-fragment reading) are
+gated behind `CDF_MCP_TOOLSET=full`, which restores the entire
+previous surface unchanged. Lean is a strict subset of full — nothing
+in the 3-tool default behaves differently in full mode.
+
+**Migration:** clients that relied on any tool outside the lean trio
+(e.g. `cdf_list`, `cdf_get`, `cdf_scaffold`, the Figma-access tools)
+must set `CDF_MCP_TOOLSET=full` in the server's environment. No tool
+names, arguments, or return shapes changed — this is a registration
+gate, not a behavioural change.
+
+### Tool count
+
+Tool count: 18 (full) / 3 (lean default).
+
 ## [1.7.3] — 2026-04-27
@@ -10,0 +74,0 @@

package.json

 {
   "name": "@formtrieb/cdf-mcp",
-  "version": "1.7.3",
-  "description": "MCP server exposing CDF (Component Description Format) tooling to LLM clients — Profile read/diff/coverage, component validation, vocab-divergence, Figma walker + renderers.",
+  "version": "2.0.0",
+  "description": "MCP server for CDF — enum de-collapse, vocabulary-divergence detection, Profile/Component validation, Figma extraction (lean/full toolsets).",
   "license": "Apache-2.0",
@@ -41,3 +41,3 @@ "type": "module",
     "@modelcontextprotocol/sdk": "^1.28.0",
-    "@formtrieb/cdf-core": "^1.0.4",
+    "@formtrieb/cdf-core": "^1.2.0",
     "yaml": "^2.7.0",
@@ -44,0 +44,0 @@ "zod": "^4.0.0"

README.md

 # @formtrieb/cdf-mcp
 
-**MCP adapter for [cdf-core](../cdf-core/). Exposes twenty-two tools that let an
+**MCP adapter for [cdf-core](../cdf-core/). Exposes eighteen tools that let an
 LLM client read, validate, author, and refactor CDF component specs and
-Profiles, plus fetch + extract Figma files for Profile scaffolding.**
+Profiles, plus fetch + extract Figma files for Profile scaffolding.
+Three lean tools (enum de-collapse, vocabulary-divergence, Profile
+validation) are on by default; the other fifteen unlock behind an
+opt-in env var.**
 
@@ -14,17 +17,33 @@ This package is a thin wrapper — all parsing, validation, and analysis
 
-**v1.7.0 — 2026-04-26.** Twenty-two tools. **N1+N5 Figma Access
-Modernization** added five new tools that port the bash walker +
-renderers to TypeScript and add a `figma_execute` runtime adapter,
-unblocking the Snapshot Skill's T0-path (no PAT needed) for evaluators.
-See the v1.7.0 section below + [CHANGELOG](./CHANGELOG.md) for the full
-list.
+**v2.0.0 — 2026-07-12.** Eighteen tools (three in the default lean mode;
+`CDF_MCP_TOOLSET=full` restores the rest). Two breaking changes:
 
-Earlier milestones in this line: v1.6.1 added `cdf_get_spec_fragment`;
-v1.6.0 added Profile read/diff/coverage (5 tools); v1.5.0 was the
-breaking BBQ — drop `cdf_emit_profile`, rename `cdf_validate` → `cdf_validate_component`,
+- **Lean-by-default tool surface.** New installs register only
+  `cdf_decollapse`, `cdf_vocab_diverge`, and `cdf_validate_profile`
+  unless `CDF_MCP_TOOLSET=full` is set in the server's environment.
+  See the [Tools](#tools) section below for the full lean/full split.
+- **Five zero-consumer profile-read tools removed** —
+  `cdf_get_profile_section`, `cdf_list_profiles`, `cdf_coverage_profile`,
+  `cdf_diff_profile`, `cdf_resolve_extends` (all added in v1.6.0) are
+  gone. Migration notes in [CHANGELOG](./CHANGELOG.md).
+
+`cdf_decollapse` (drafted against an unpublished `v1.8.0` line) ships
+for the first time in this release — it de-collapses a crammed enum
+into its independent axes (e.g. a `State` property mixing interaction,
+content, and validation) and lists the combinations those axes imply
+but weren't declared, each as a question for the author to confirm or
+reject.
+
+Earlier milestones in this line: v1.7.0's **N1+N5 Figma Access
+Modernization** added five tools that port the bash walker + renderers
+to TypeScript and add a `figma_execute` runtime adapter, unblocking the
+Snapshot Skill's T0-path (no PAT needed) for evaluators; v1.6.1 added
+`cdf_get_spec_fragment`; v1.6.0 added Profile read/diff/coverage (5
+tools, since removed — see above); v1.5.0 was the breaking BBQ — drop
+`cdf_emit_profile`, rename `cdf_validate` → `cdf_validate_component`,
 add `cdf_validate_profile` (L0–L8). See CHANGELOG for migration notes.
 
-License: Apache-2.0. Public release queued (Akt 3 of the Phase 8
-Public Extract roadmap); until that lands, consumed via `workspace:*`
-inside the Formtrieb monorepo and via local install.
+License: Apache-2.0. Published on npm as `@formtrieb/cdf-mcp`,
+installed automatically by the `cdf` Claude Code plugin or manually
+via `npx @formtrieb/cdf-mcp`.
 
@@ -74,6 +93,37 @@ ## Install & build
 
+CDF-mcp registers a **lean** 3-tool surface by default. Set
+`CDF_MCP_TOOLSET=full` in the server's environment to register the
+full 18-tool surface — lean is always a strict subset of full, so
+nothing in the default 3 tools behaves differently once you opt into
+`full`.
+
+### Which mode do I want?
+
+- **Lean (default)** — you're evaluating CDF against an unfamiliar
+  design system, or your day-to-day loop is enum de-collapse,
+  vocabulary-divergence checking, or Profile validation. Zero
+  configuration; the smallest tool-choice surface for a client to
+  reason about.
+- **Full (`CDF_MCP_TOOLSET=full`)** — you're doing CDF-authoring work
+  end to end: listing/reading/resolving/diffing component specs,
+  scaffolding from Figma analysis data, or fetching + extracting Figma
+  files for Profile scaffolding. The
+  [`cdf` Claude Code plugin](https://github.com/formtrieb/cdf-plugin)
+  sets this for you.
+
+### Lean (default)
+
 | Tool | Purpose |
 |------|---------|
+| `cdf_decollapse` | De-collapse a crammed enum into its independent axes. Takes the declared variant values verbatim — straight from a Figma component set's variant list or a token family's suffixes, no re-interpretation — and infers which of those values are actually bundling several independent concerns into one property or token suffix (e.g. a `State` enum that mixes interaction, content, and validation). Lists the combinations that are implied by those axes but weren't declared, each as a question for the author to confirm or reject. A suggestion, not a judgment — an omission may well be intentional. |
+| `cdf_vocab_diverge` | Detect near-miss typos (Levenshtein ≤2) in property values + interaction-pattern states against the Profile; elicit resolutions; apply renames + persist rationale into the Profile. |
+| `cdf_validate_profile` | Validate a CDF Profile YAML. Runs L0–L7 by default (parse, required fields, types, schema-baking, cross-field, vocabulary isolation, extends-resolution, set_mapping globs); L8 (token-reference resolution against `token_sources`) is opt-in via `resolve_tokens: true`. Accepts either `profile_path` or inline `profile_yaml`. |
+
+### Full (`CDF_MCP_TOOLSET=full`)
+
+Adds these 15 tools on top of the lean trio:
+
+| Tool | Purpose |
+|------|---------|
 | `cdf_validate_component` | Run the validator against one or all component specs. Returns structured issues by severity. (Renamed from `cdf_validate` in v1.5.0.) |
-| `cdf_validate_profile` | **(v1.5.0)** Validate a CDF Profile YAML. Runs L0–L7 by default (parse, required fields, types, schema-baking, cross-field, vocabulary isolation, extends-resolution, set_mapping globs); L8 (token-reference resolution against `token_sources`) is opt-in via `resolve_tokens: true`. Accepts either `profile_path` or inline `profile_yaml`. |
 | `cdf_list` | List all component specs with optional property/state/anatomy counts, filterable by category. |
@@ -87,28 +137,3 @@ | `cdf_get` | Return a single section (e.g. `properties`, `states`, `tokens`) of a component spec, to avoid dumping the whole file. |
 | `cdf_scaffold` | Generate a CDF YAML skeleton from Figma analysis data (uses MCP elicitation to confirm component name, category, description). |
-| `cdf_vocab_diverge` | **(v1.1.0)** Detect near-miss typos (Levenshtein ≤2) in property values + interaction-pattern states against the Profile; elicit resolutions; apply renames + persist rationale into the Profile. |
-
-### v1.6.0 — Profile-Read + Diff + Coverage (new)
-
-| Tool | Purpose |
-|------|---------|
-| `cdf_list_profiles` | List all `*.profile.yaml` files with summary counts |
-| `cdf_get_profile_section` | Read a profile or a single top-level section |
-| `cdf_resolve_extends` | Merge `extends:` chain; returns merged YAML + provenance |
-| `cdf_coverage_profile` | Orphan detection (vocab / grammar / pattern); two-tier auto-detection |
-| `cdf_diff_profile` | Structural diff; default merges extends on both sides |
-
-### v1.6.1 — Profile-Spec fragment reader (new)
-
-| Tool | Purpose |
-|------|---------|
 | `cdf_get_spec_fragment` | Read one fragment of CDF-PROFILE-SPEC (e.g. `Vocabularies`, `TokenGrammar`, `InteractionPatterns`). Fragments live under `cdf/specs/profile/`; the monolith `cdf/specs/CDF-PROFILE-SPEC.md` is a generated publication artefact. Use `format: "sections"` for a parsed heading map. |
-
-### v1.7.0 — Figma Access Modernization (N1+N5 bundle)
-
-Five new tools port the bash walker + renderers to TypeScript and add a
-runtime adapter for `figma_execute` so Snapshot Skill evaluators no
-longer need a Figma PAT (T0 path via `figma-console` MCP).
-
-| Tool | Purpose |
-|------|---------|
 | `cdf_fetch_figma_file` | REST-fetch a Figma file by `file_key`; PAT via `pat:` arg or `FIGMA_PAT` env (arg overrides). Caches to `.cdf-cache/figma/{file_key}.json`. Use `force_refresh: true` to bypass cache. |
@@ -120,9 +145,12 @@ | `cdf_resolve_figma_variables` | Wrap the `figma_execute` Variable-Oracle pattern. Caches resolved Variables to `.cdf-cache/figma/{file_key}.variables.json`. Returns counts + cached path. |
 
-These five tools subsume the previous bash pipeline (`scripts/figma-phase1-extract.sh`,
+The `cdf_fetch_figma_file` / `cdf_resolve_figma_variables` /
+`cdf_extract_figma_file` / `cdf_render_findings` / `cdf_render_snapshot`
+tools subsume the previous bash pipeline (`scripts/figma-phase1-extract.sh`,
 `scripts/extract-to-yaml.sh`, `scripts/render-findings.sh`,
 `scripts/render-snapshot.sh`). Bash scripts remain in the Formtrieb
-monorepo as a regression bridge until v1.8.0 cleanup PR; external
+monorepo as a regression bridge until a future cleanup release; external
 adopters install the cdf-mcp tool surface and skip bash entirely.
 
-Fragment directory resolution (in order — first match wins):
+`cdf_get_spec_fragment` fragment directory resolution (in order — first
+match wins):
 
@@ -129,0 +157,0 @@ 1. `CDF_SPECS_DIR` env var — explicit override. Use when the fragments

New alerts

Environment variable access

Supply chain risk

Package accesses environment variables, which may be a sign of credential stuffing or data theft.

Filesystem access

Supply chain risk

Accesses the file system, and could potentially read sensitive data.

Fixed alerts

Filesystem access

Supply chain risk

Accesses the file system, and could potentially read sensitive data.

Improved metrics

Number of lines in readme file

342

8.92%

Worsened metrics

Total package byte prevSize

386747

-1.71%

Lines of code

2074

-6.7%

Number of low supply chain risk alerts

17

6.25%

Dependency changes

• Updated

  @formtrieb/cdf-core@^1.2.0