@unified-product-graph/mcp-server 0.8.1 → 0.8.4

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 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.4] - 2026-06-02
+
+Framework exercises, with the 0.8.3 launch fix folded in.
+
+### Added
+- `apply_framework` and `score_entity` tools: create a `framework_exercise` and record per-entity results on the includes edge (94 to 96 tools).
+- `create_edge` accepts gated `properties` (only edge types that opt in). `prioritise` accepts an optional `exercise_id` that sources scoring inputs from the includes edges and scores across any entity type.
+
+### Fixed
+- The server no longer crashes with `ERR_PARSE_ARGS_UNEXPECTED_POSITIONAL` when launched via `upg mcp run` — `parseArgs` now tolerates stray positionals. The standalone `upg-mcp-server` bin is unaffected.
+
+## [0.8.2] - 2026-06-02
+
+Co-version with the @unified-product-graph/* 0.8.2 release train.
+
+### Changed
+- Tool handlers now enforce the shared write-validation policy directly: `batch_create_edges` rejects invalid edge types, `update_node` honours property unset and rejects invalid status, and session-context updates reject invalid lenses.
+- Bundled skills renamed to a consistent verb-based grammar and reworked to be MCP-first: schemas, lifecycles, and edges are fetched from the server before writes rather than hard-coded.
+
+### Added
+- `skill_audit` all-mode for full-surface review.
+
 ## [0.7.6] - 2026-05-30
 
 ### Added

package/README.md

@@ -134,7 +134,7 @@ All spec-introspection handlers are read-only and snapshot from the spec package
 
 ## Installing Skills (Claude Code)
 
-The server provides the raw MCP tools. For a guided experience with slash commands (`/upg`, `/upg-init`, `/upg-journey`), install the skill files:
+The server provides the raw MCP tools. For a guided experience with slash commands (`/upg`, `/upg-new-graph`, `/upg-show-journey`), install the skill files:
 
 ```bash
 bash scripts/install-skills.sh

package/TOOLS.md

@@ -1,6 +1,6 @@
 # UPG MCP Server: Tool Reference
 
-Reference for the 94 tools exposed by `@unified-product-graph/mcp-server`. Generated from JSDoc on `src/tools/*.ts` (do not edit by hand).
+Reference for the 96 tools exposed by `@unified-product-graph/mcp-server`. Generated from JSDoc on `src/tools/*.ts` (do not edit by hand).
 
 ## Contents
 
@@ -10,7 +10,7 @@ Reference for the 94 tools exposed by `@unified-product-graph/mcp-server`. Gener
 - [Areas & Change Log](#areas-change-log): 5 tools
 - [Workspace & Portfolios](#workspace-portfolios): 10 tools
 - [Schema](#schema): 1 tool
-- [Spec Introspection](#spec-introspection): 43 tools
+- [Spec Introspection](#spec-introspection): 45 tools
 - [Cloud Sync](#cloud-sync): 3 tools
 - [Validation](#validation): 3 tools
 
@@ -160,10 +160,10 @@ succeed or fail independently of the session update.`
 | ---- | ---- | -------- | ----------- |
 | `custom` | object |  | Arbitrary key-value pairs for cross-skill state |
 | `focus_area` | string |  | Set the current focus area (e.g. "strategy", "validation", "user_research") |
-| `lens` | `product` \| `engineering` \| `design` \| `growth` |  | Switch the active lens. Changes what context, skills, and gaps are surfaced first. |
+| `lens` | `product` \| `ux_design` \| `engineering` \| `growth` \| `business` \| `research` \| `marketing` \| `full` |  | Switch the active lens. Changes what context, skills, and gaps are surfaced first. Canonical lens ids (derived from core): product, ux_design, engineering, growth, business, research, marketing, full. |
 | `persist_lens` | boolean |  | If true, also save the lens to the .upg file so it persists across sessions |
-| `recommendation` | string |  | Record a recommendation given to the user (e.g. "Run /upg-strategy to fill strategy gap") |
-| `skill_invoked` | string |  | Register that this skill was just invoked (e.g. "upg-status") |
+| `recommendation` | string |  | Record a recommendation given to the user (e.g. "Run /upg-new-strategy to fill strategy gap") |
+| `skill_invoked` | string |  | Register that this skill was just invoked (e.g. "upg-show-status") |
 
 **Returns:**
 
@@ -648,20 +648,22 @@ shallow-merge patches.`
 | `tags` | array |  |  |
 | `title` | string |  |  |
 | `type` | string |  | Change the entity type. Atomic single-node migration: validates against UPG_TYPES, rewrites incident edges to canonical types. |
+| `unset_properties` | array |  | Property keys to DELETE. Applied after the `properties` merge, so one call can set some keys and drop others. Writing `{ key: null }` only stores a literal null; use this to actually remove a key. Unknown keys are ignored. |
 
 **Returns:**
 
-JSON: `{ node, warning?, unknown_properties? }`. `warning`
-aggregates lifecycle-status hints, migration warnings, and any
-unknown-property notice. `unknown_properties` lists property
-keys not in the entity's schema. Pass `strict: true` to reject unknown
-properties instead of warning.
+JSON: `{ node, warning?, unknown_properties?, unset? }`. `warning`
+aggregates migration warnings and any unknown-property notice.
+`unknown_properties` lists property keys not in the entity's schema.
+`unset` lists the keys actually removed. Pass `strict: true` to reject
+unknown properties instead of warning.
 
 **Throws:**
 
 - Returns a textError when `node_id` is missing, the type migration
-fails, when `strict: true` and unknown properties are present, or when
-the underlying store rejects the patch.
+fails, the `status` is not a valid lifecycle phase for the type, when
+`strict: true` and unknown properties are present, or when the underlying
+store rejects the patch.
 
 **See also:** `migrate_type`, `batch_update_nodes`
 
@@ -765,6 +767,7 @@ Create one edge between two nodes. Edge type auto-infers when omitted. Target ac
 
 | Name | Type | Required | Description |
 | ---- | ---- | -------- | ----------- |
+| `properties` | object |  | Edge-scoped properties. Only permitted on edge types that opt in (currently framework_exercise_includes_node); rejected on plain semantic edges. |
 | `source_id` | string | ✓ | Source node ID |
 | `target_id` | string |  | Target node ID |
 | `target_title` | string |  | Target node title (alternative to target_id; requires target_type). |
@@ -1212,6 +1215,9 @@ _No arguments._
 **Returns:**
 
 JSON: `{ products: Array<{ file, title, stage, nodes, edges }> }`.
+`stage` is the CANONICAL UPGProductStage (legacy values like `idea` are
+coerced to `concept`), or `null` when unset — matching what
+`get_product_context` reports for the same product (UPG-611 / DT-MCP-3).
 
 **See also:** `switch_product`, `get_workspace_info`
 
@@ -1344,6 +1350,7 @@ edges_in, phases?, initial_phase?, terminal_phases?, domain_guide? }`.
 
 _Canonical playbooks, approaches, domain guides, frameworks, edge catalogue, regions, lenses, type labels, hierarchy, version, cross-edges, entity meta, anti-patterns, benchmarks, bare-verb approach handlers, migrations, lifecycles, scales, framework categories/patterns, and domain rings. All from `@unified-product-graph/core`._
 
+- [`apply_framework`](#apply-framework)
 - [`get_anti_pattern`](#get-anti-pattern)
 - [`get_approach`](#get-approach)
 - [`get_domain_guide`](#get-domain-guide)
@@ -1386,8 +1393,35 @@ _Canonical playbooks, approaches, domain guides, frameworks, edge catalogue, reg
 - [`prioritise`](#prioritise)
 - [`reflect`](#reflect)
 - [`resolve_edge_for_pair`](#resolve-edge-for-pair)
+- [`score_entity`](#score-entity)
 - [`trace`](#trace)
 
+### `apply_framework`
+
+Apply a framework (MoSCoW, RICE, Kano, ...) to a set of entities: creates a framework_exercise node and an `includes` edge to each entity. The per-entity result is recorded on the edge via score_entity, never on the entity node, so the same entity can sit in many exercises and any entity type can be scored. Returns { exercise_id, exercise, included, warnings }.
+
+**Atomicity:** `atomic.`
+
+**Arguments:**
+
+| Name | Type | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `entity_ids` | array |  | Entities to pull into the exercise (any type). |
+| `framework_id` | string | ✓ | Required. UPGFramework.id (e.g. "moscow", "rice-scoring"). |
+| `status` | string |  | Lifecycle phase: draft \| active \| archived (default draft). |
+| `title` | string |  | Human label for the exercise (default "<Framework> exercise"). |
+
+**Returns:**
+
+JSON: `{ exercise_id, exercise, included: [{ edge_id, entity_id }], warnings }`.
+
+**Throws:**
+
+- textError on a missing/unknown framework_id.
+
+**See also:** `score_entity`
+
+
 ### `get_anti_pattern`
 
 Return one curated anti-pattern by id (kebab-case slug, e.g. "features-without-hypotheses", "personas-without-jobs"). Includes structured condition, why-it-matters, remediation, applicable stages, severity, optional source citation. IDs are stable URL fragments.
@@ -1759,7 +1793,7 @@ JSON: `{ parent_type, valid_children: string[] }`
 
 ### `inspect`
 
-[LLM-mediated] This tool returns a routing envelope, not computed results. For user-facing inspection, invoke the /upg-inspect skill instead of calling this tool directly. Inspect approach: path of arrival to "what's broken?". Returns the Inspect record + invocation params in the family-resemblance envelope. The LLM consumes `signature_hint` and emits `{ violations: [{ severity, kind, entity_id, description, fix_hint }] }` against `UPG_ANTI_PATTERNS` + the live graph. Optional `region` or `entities[]` scope the audit.
+[LLM-mediated] This tool returns a routing envelope, not computed results. For user-facing inspection, invoke the /upg-show-entity skill instead of calling this tool directly. Inspect approach: path of arrival to "what's broken?". Returns the Inspect record + invocation params in the family-resemblance envelope. The LLM consumes `signature_hint` and emits `{ violations: [{ severity, kind, entity_id, description, fix_hint }] }` against `UPG_ANTI_PATTERNS` + the live graph. Optional `region` or `entities[]` scope the audit.
 
 **Atomicity:** `atomic (read-only)`
 
@@ -2184,7 +2218,7 @@ JSON: `{ migrations: [{ from, to, since }], total: number }`
 
 ### `plan`
 
-Plan approach: path of arrival to "what should I build next?". Returns the Plan record + invocation params wrapped in `{ approach_id, scope, generated_at, approach, params }`. The LLM consumes `signature_hint` and synthesises `{ missing_entities, coverage_score }` against the live graph. Optional `region` narrows scope.
+Plan approach: path of arrival to "what should I build next?". Returns the Plan record + invocation params wrapped in `{ approach_id, scope, generated_at, approach, params }`. The LLM consumes `signature_hint` and synthesises `{ missing_entities, coverage_score }` against the live graph. Optional `region` narrows scope; omit `region` to scope to the product's ACTIVE regions; pass `exhaustive:true` to score the full type universe (UPG-601).
 
 **Atomicity:** `atomic (read-only)`
 
@@ -2192,7 +2226,8 @@ Plan approach: path of arrival to "what should I build next?". Returns the Plan
 
 | Name | Type | Required | Description |
 | ---- | ---- | -------- | ----------- |
-| `region` | string |  | Optional UPGRegionId. Narrows planning scope to a single region (e.g. "users_needs", "business_gtm_growth"). Omit for whole-graph planning. |
+| `exhaustive` | boolean |  | If true, score against the entire 312-type universe (every domain creation sequence). Off by default; whole-universe gap scoring is noisy for a focused product. Only applies when `region` is omitted. |
+| `region` | string |  | Optional UPGRegionId or atomic-domain id. Narrows planning scope to a single region (e.g. "users_needs", "business_gtm_growth"). Omit to scope to the product's active regions. |
 
 **Returns:**
 
@@ -2229,7 +2264,8 @@ execution_mode: "execution_v0_4_0" }`.
 
 | Name | Type | Required | Description |
 | ---- | ---- | -------- | ----------- |
-| `candidates` | array | ✓ | Required. entity_id[] to rank. |
+| `candidates` | array |  | entity_id[] to rank. Optional when exercise_id is given (the exercise supplies them). |
+| `exercise_id` | string |  | Optional (0.8.4). A framework_exercise id: reads each candidate's scoring inputs from its includes-edge properties instead of node.properties, and bypasses the target-type guard so any entity type can be scored. |
 | `framework_id` | string | ✓ | Required. UPGFramework.id of the scoring lens (e.g. "rice-scoring", "ice-scoring", "kano-model", "cost-of-delay", "wsjf"). |
 
 **Returns:**
@@ -2304,6 +2340,33 @@ not synthesise a non-canonical key.
 **See also:** `list_edge_types`, `get_edge_type`, `create_edge`, `trace`
 
 
+### `score_entity`
+
+Record a framework's result for one entity on the exercise's includes edge (a MoSCoW bucket, a RICE score, a canvas slot). Auto-includes the entity if not already in scope. Merges into existing edge properties unless replace is set. Returns { edge, warnings }.
+
+**Atomicity:** `atomic.`
+
+**Arguments:**
+
+| Name | Type | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `entity_id` | string | ✓ | Required. The entity being scored. |
+| `exercise_id` | string | ✓ | Required. The framework_exercise id. |
+| `replace` | boolean |  | Replace the edge properties instead of merging (default false). |
+| `values` | object | ✓ | Required. The result as { input: value }, e.g. { "moscow": "must" } or { "reach": 800, "impact": 3 }. |
+
+**Returns:**
+
+JSON: `{ edge, warnings }`.
+
+**Throws:**
+
+- textError when the exercise/entity is missing or the node is not a
+framework_exercise.
+
+**See also:** `apply_framework`
+
+
 ### `trace`
 
 [LLM-mediated] This tool returns a routing envelope, not computed results. For user-facing tracing, invoke the /upg-trace skill instead of calling this tool directly. Trace approach: path of arrival to "walk a meaningful path through existing graph". Returns the Trace record + invocation params in the family-resemblance envelope. The LLM uses `anchor` + `path` to compose `query()` calls and emits `{ trail: [{ depth, entity_id, edge_type_in }], reached: entity_id[] }`. `path` is type-shorthand: `["persona","job","feature"]` walks persona→job→feature using the canonical edge per pair (via `resolve_edge_for_pair`). Optional `edges_override` selects non-canonical edges per hop; `null` per element means "use canonical".