@unified-product-graph/mcp-server 0.8.6 → 0.8.8

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to `@unified-product-graph/mcp-server` are documented in this file. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.8.8] - 2026-06-03
+
+### Added
+- `validate_graph` now returns `structurally_valid` (spec conformance, independent of product-health linting) alongside the existing `valid` (combined structure + health, unchanged). N4.
+- Non-breaking parameter aliases: `get_node` accepts `node_id`|`id`, `get_framework` `id`|`framework_id`, `switch_product` `file`|`product`; the canonical key wins and errors name both. N2.
+
+### Changed
+- Bundles core 0.8.8 (slot roles, kano/raid-log scoring lenses, framework-score validation).
+
+## [0.8.7] - 2026-06-03
+
+`list_frameworks` now returns a lightweight summary per framework (the full four-layer record was overflowing the tool-result token cap on the default call); `get_framework` returns the full record. `apply_framework` shares one cross-surface envelope with the CLI (`{ exercise_id, exercise, included, warnings }`). `get_framework` gives a helpful error on an unknown id. Last-writer provenance is stamped on writes. The `upg-prioritise` skill teaches the apply/score exercise flow. Co-versions the @unified-product-graph/* 0.8.7 train.
+
 ## [0.8.5] - 2026-06-02
 
 Field-report fast-follow (tester report on 0.8.4).

package/TOOLS.md

@@ -379,7 +379,8 @@ Get a single entity by ID, with full properties and all connected edges.
 | Name | Type | Required | Description |
 | ---- | ---- | -------- | ----------- |
 | `compact_edges` | boolean |  | Omit source_title/target_title from edges (saves ~30% on edge-heavy nodes) |
-| `node_id` | string | ✓ | The node ID |
+| `id` | string |  | Alias for `node_id`. |
+| `node_id` | string | ✓ | The node ID. Alias: `id`. |
 
 **Returns:**
 
@@ -388,8 +389,8 @@ omits `source_title` and `target_title` (saves ~30% on edge-heavy nodes).
 
 **Throws:**
 
-- Returns a textError when `node_id` is missing or the node does not
-exist.
+- Returns a textError when neither `node_id` nor `id` is provided, or
+the node does not exist.
 
 **See also:** `get_nodes`
 
@@ -1296,7 +1297,8 @@ loads the new file as separate filesystem operations.`
 
 | Name | Type | Required | Description |
 | ---- | ---- | -------- | ----------- |
-| `file` | string | ✓ | Path to the .upg file (relative, absolute, or a bare product name in workspace mode). |
+| `file` | string | ✓ | Path to the .upg file (relative, absolute, or a bare product name in workspace mode). Alias: `product`. |
+| `product` | string |  | Alias for `file`. |
 
 **Returns:**
 
@@ -1304,8 +1306,8 @@ JSON: `{ message, file, product: { title, stage }, entities }`.
 
 **Throws:**
 
-- Returns a textError when the file cannot be resolved or the load
-fails (file watcher / parse error).
+- Returns a textError when neither `file` nor `product` is provided, or
+the file cannot be resolved, or the load fails (file watcher / parse error).
 
 **Warnings (non-error surfaces):**
 
@@ -1413,11 +1415,13 @@ Apply a framework (MoSCoW, RICE, Kano, ...) to a set of entities: creates a fram
 
 **Returns:**
 
-JSON: `{ exercise_id, exercise, included: [{ edge_id, entity_id }], warnings }`.
+JSON: `{ exercise_id, exercise, included: [{ edge_id, entity_id, edge_type }], warnings }`
+(the shared cross-surface envelope; identical to CLI `apply --json`).
 
 **Throws:**
 
-- textError on a missing/unknown framework_id.
+- textError on a missing/unknown framework_id, or when no requested
+entity resolves (no dangling exercise is left behind).
 
 **See also:** `score_entity`
 
@@ -1566,7 +1570,8 @@ Return one `UPGFramework` by id (e.g. "rice-scoring", "lean-canvas"). Includes a
 
 | Name | Type | Required | Description |
 | ---- | ---- | -------- | ----------- |
-| `id` | string | ✓ | Framework id (kebab-case). |
+| `framework_id` | string |  | Alias for `id` (matches the key used by apply_framework / prioritise). |
+| `id` | string | ✓ | Framework id (kebab-case). Alias: `framework_id`. |
 
 **Returns:**
 
@@ -1574,7 +1579,8 @@ JSON: the full `UPGFramework` record.
 
 **Throws:**
 
-- textError when `id` is missing or unknown.
+- textError when neither `id` nor `framework_id` is provided, or the
+id is unknown.
 
 **See also:** `list_frameworks`, `prioritise`, `get_playbook`, `get_approach`
 
@@ -2021,7 +2027,7 @@ JSON: `{ patterns: string[], total: number }`
 
 ### `list_frameworks`
 
-List the canonical `UPGFramework` definitions; the 34 curated, famous product frameworks that anchor the public catalog (spanning strategy, discovery, prioritisation, design, growth, engineering, and reflection classics). Paginated (default 50, max 200). Cursor is opaque: pass `next_cursor` from a previous response. Optional `category` is exact-match against `UPGFramework.category` and applies before pagination.
+List the canonical `UPGFramework` definitions: the curated, famous product frameworks that anchor the public catalog (spanning strategy, discovery, prioritisation, design, growth, engineering, and reflection classics). Returns a lightweight summary per framework (id, name, category, description, tags, approach_ids, structure_pattern); call `get_framework(id)` for the full record. Paginated (default 50, max 200). Cursor is opaque: pass `next_cursor` from a previous response. Optional `category` is exact-match against `UPGFramework.category` and applies before pagination.
 
 **Atomicity:** `atomic (read-only)`
 
@@ -2035,7 +2041,7 @@ List the canonical `UPGFramework` definitions; the 34 curated, famous product fr
 
 **Returns:**
 
-JSON: `{ total, count, next_cursor?, frameworks: UPGFramework[] }`
+JSON: `{ total, count, next_cursor?, frameworks: Array<{ id, name, category, description, tags, approach_ids, structure_pattern }> }`
 
 **See also:** `get_framework`, `list_framework_categories`, `list_framework_structure_patterns`, `prioritise`, `list_approaches`
 
@@ -2609,11 +2615,12 @@ Walk the loaded graph and return a per-class, per-node report of schema drift pl
 
 **Returns:**
 
-JSON: `{ valid, summary, entity_drift?, edge_drift?,
-property_drift?, top_level_drift?, lifecycle_drift?, self_referential?,
-anti_pattern_violations?, notes?, _hash }`. Per-class drift arrays appear
-only when the requested `scope` includes that class. Each array is capped
-at `limit` (default 100).
+JSON: `{ valid, structurally_valid?, summary, entity_drift?,
+edge_drift?, property_drift?, top_level_drift?, lifecycle_drift?,
+self_referential?, anti_pattern_violations?, notes?, _hash }`. Per-class
+drift arrays appear only when the requested `scope` includes that class.
+Each array is capped at `limit` (default 100). `structurally_valid` is
+omitted when `skip_drift: true`.
 
 **Throws:**
 
@@ -2622,9 +2629,11 @@ recognised values.
 
 **Warnings (non-error surfaces):**
 
-- Top-level `valid` is true ONLY when both drift is empty AND no
-anti-pattern violations fired. Set `skip_anti_patterns: true` for a
-pure spec-shape check; `skip_drift: true` for catalog-only.
+- `valid` is true ONLY when both drift is empty AND no anti-pattern
+violations fired — it conflates structure and product-health. For a pure
+spec-conformance check read `structurally_valid` (or set
+`skip_anti_patterns: true`, which makes `valid` track structure alone).
+`skip_drift: true` gives a catalog-only run and omits `structurally_valid`.
 
 **Examples:**