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

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 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.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

@@ -1413,11 +1413,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`
 
@@ -2021,7 +2023,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 +2037,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`
 

package/dist/index.js

@@ -7923,7 +7923,6 @@ function migrateStatusValue(entityType, currentStatus) {
   if (!typeMap) return null;
   return typeMap[currentStatus] ?? null;
 }
-var crossProductEdgeTypeSet = new Set(UPG_CROSS_EDGE_TYPES);
 var UPG_PROPERTY_SCHEMA = {
   // A11yAnnotationProperties: Accessibility annotation.
   a11y_annotation: {
@@ -11080,6 +11079,7 @@ var UPG_PROPERTY_SCHEMA = {
 function getPropertySchema(entityType) {
   return UPG_PROPERTY_SCHEMA[entityType];
 }
+var crossProductEdgeTypeSet = new Set(UPG_CROSS_EDGE_TYPES);
 var UPG_FRAMEWORKS = [
   {
     "id": "opportunity-solution-tree",
@@ -12315,7 +12315,7 @@ var UPG_FRAMEWORKS = [
     ],
     "name": "RICE Scoring",
     "version": "1.0.0",
-    "description": "Score features and opportunities by Reach, Impact, Confidence, and Effort to produce a ranked priority list.",
+    "description": "Score features, opportunities, and needs by Reach, Impact, Confidence, and Effort to produce a ranked priority list.",
     "category": "prioritization",
     "origin": {
       "type": "practitioner",
@@ -12333,7 +12333,7 @@ var UPG_FRAMEWORKS = [
       {
         "label": "Items to score",
         "entityTypeId": "feature",
-        "description": "Features, opportunities, or solutions being evaluated"
+        "description": "Features, opportunities, or needs being evaluated"
       },
       {
         "label": "Opportunities to score",
@@ -12499,7 +12499,60 @@ var UPG_FRAMEWORKS = [
           "label": "RICE Score",
           "format": "number"
         }
-      ]
+      ],
+      "scoring_lens": {
+        "applies_to": [
+          "feature",
+          "opportunity",
+          "need"
+        ],
+        "inputs": [
+          {
+            "property": "reach",
+            "type": "assessment",
+            "scale_id": "reach_5",
+            "required": true,
+            "scope": "framework",
+            "label": "Reach",
+            "description": "How many users will this impact per quarter?"
+          },
+          {
+            "property": "impact",
+            "type": "assessment",
+            "scale_id": "impact_5",
+            "required": true,
+            "scope": "framework",
+            "label": "Impact",
+            "description": "How much will this impact each user, on the impact scale?"
+          },
+          {
+            "property": "confidence",
+            "type": "assessment",
+            "scale_id": "confidence_5",
+            "required": true,
+            "scope": "framework",
+            "label": "Confidence",
+            "description": "How confident are you in the reach, impact, and effort estimates?"
+          },
+          {
+            "property": "effort",
+            "type": "assessment",
+            "scale_id": "effort_5",
+            "required": true,
+            "scope": "framework",
+            "label": "Effort",
+            "description": "How much work is required to build and ship this, on the effort scale?"
+          }
+        ],
+        "computed": [
+          {
+            "property": "rice_score",
+            "expression": "(reach * impact * confidence) / effort",
+            "label": "RICE Score",
+            "format": "number"
+          }
+        ]
+      }
     },
     "structure": {
       "pattern": "table"
@@ -14624,7 +14677,7 @@ var UPG_FRAMEWORKS = [
       "entity_types": [
         {
           "type": "team",
-          "role": "scored_item"
+          "role": "item"
         },
         {
           "type": "retrospective",
@@ -15018,7 +15071,48 @@ var UPG_FRAMEWORKS = [
           "label": "ICE Score",
           "format": "number"
         }
-      ]
+      ],
+      "scoring_lens": {
+        "applies_to": [
+          "feature",
+          "opportunity",
+          "need"
+        ],
+        "inputs": [
+          {
+            "property": "impact",
+            "type": "number",
+            "required": true,
+            "scope": "framework",
+            "label": "Impact",
+            "description": "Expected impact on the target metric (1-10)"
+          },
+          {
+            "property": "confidence",
+            "type": "number",
+            "required": true,
+            "scope": "framework",
+            "label": "Confidence",
+            "description": "Confidence in the impact estimate (1-10)"
+          },
+          {
+            "property": "ease",
+            "type": "number",
+            "required": true,
+            "scope": "framework",
+            "label": "Ease",
+            "description": "Ease of implementation (1-10)"
+          }
+        ],
+        "computed": [
+          {
+            "property": "ice_score",
+            "expression": "impact * confidence * ease",
+            "label": "ICE Score",
+            "format": "number"
+          }
+        ]
+      }
     },
     "structure": {
       "pattern": "table"
@@ -15227,7 +15321,55 @@ var UPG_FRAMEWORKS = [
           "label": "WSJF Score",
           "format": "number"
         }
-      ]
+      ],
+      "scoring_lens": {
+        "applies_to": [
+          "feature",
+          "opportunity"
+        ],
+        "inputs": [
+          {
+            "property": "user_value",
+            "type": "number",
+            "required": true,
+            "scope": "framework",
+            "label": "User/Business Value",
+            "description": "Relative value to users and the business if delivered"
+          },
+          {
+            "property": "time_criticality",
+            "type": "number",
+            "required": true,
+            "scope": "framework",
+            "label": "Time Criticality",
+            "description": "How much value decays if delivery is delayed (deadlines, competition, seasonal windows)"
+          },
+          {
+            "property": "risk_reduction",
+            "type": "number",
+            "required": true,
+            "scope": "framework",
+            "label": "Risk Reduction / Opportunity Enablement",
+            "description": "Value from reducing risk or enabling future opportunities"
+          },
+          {
+            "property": "job_size",
+            "type": "number",
+            "required": true,
+            "scope": "framework",
+            "label": "Job Size",
+            "description": "Estimated effort (story points, t-shirt size, or person-weeks)"
+          }
+        ],
+        "computed": [
+          {
+            "property": "wsjf_score",
+            "expression": "(user_value + time_criticality + risk_reduction) / job_size",
+            "label": "WSJF Score",
+            "format": "number"
+          }
+        ]
+      }
     },
     "structure": {
       "pattern": "table"
@@ -15300,7 +15442,7 @@ var UPG_FRAMEWORKS = [
     ],
     "name": "Cost of Delay",
     "version": "1.0.0",
-    "description": "Quantify the economic cost of not shipping a feature to drive priority decisions. Combines urgency with value.",
+    "description": "Quantify the economic cost of not shipping a feature or opportunity to drive priority decisions. Combines urgency with value.",
     "category": "prioritization",
     "origin": {
       "type": "practitioner",
@@ -15416,7 +15558,39 @@ var UPG_FRAMEWORKS = [
           "label": "WSJF Score",
           "format": "number"
         }
-      ]
+      ],
+      "scoring_lens": {
+        "applies_to": [
+          "feature",
+          "opportunity"
+        ],
+        "inputs": [
+          {
+            "property": "cost_of_delay",
+            "type": "number",
+            "required": true,
+            "scope": "framework",
+            "label": "Cost of Delay",
+            "description": "Weekly revenue impact of not shipping"
+          },
+          {
+            "property": "job_size",
+            "type": "number",
+            "required": true,
+            "scope": "framework",
+            "label": "Job Size",
+            "description": "Weeks of development effort"
+          }
+        ],
+        "computed": [
+          {
+            "property": "wsjf_score",
+            "expression": "cost_of_delay / job_size",
+            "label": "WSJF Score",
+            "format": "number"
+          }
+        ]
+      }
     },
     "structure": {
       "pattern": "table"
@@ -24004,7 +24178,7 @@ function serializePortfolioWithHeader(doc, opts) {
   header.integrity = { algorithm: INTEGRITY_ALGORITHM, body: computeBodyChecksum(doc) };
   return JSON.stringify({ $upg: header, ...body }, null, 2) + "\n";
 }
-var UPG_VERSION = "0.8.6";
+var UPG_VERSION = "0.8.7";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();
 var UPG_TYPES_SET = new Set(UPG_TYPES);
@@ -26513,6 +26687,7 @@ var getEntitySchema = (args, _ctx) => {
 // src/tools/frameworks.ts
 import {
   applyFramework as applyFrameworkLib,
+  applyFrameworkEnvelope,
   scoreEntity as scoreEntityLib
 } from "@unified-product-graph/sdk";
 var applyFramework = (args, ctx) => {
@@ -26528,18 +26703,7 @@ var applyFramework = (args, ctx) => {
       entity_ids: args.entity_ids ?? [],
       status: args.status
     });
-    return text(
-      JSON.stringify(
-        {
-          exercise_id: result.exercise.id,
-          exercise: result.exercise,
-          included: result.edges.map((e) => ({ edge_id: e.id, entity_id: e.target })),
-          warnings: result.warnings
-        },
-        null,
-        2
-      )
-    );
+    return text(JSON.stringify(applyFrameworkEnvelope(result), null, 2));
   } catch (err) {
     return textError(err.message);
   }
@@ -27286,10 +27450,19 @@ var listFrameworks = (args) => {
   const slice = pool.slice(cursorOffset, cursorOffset + limit);
   const nextOffset = cursorOffset + slice.length;
   const nextCursor = nextOffset < total ? encodeCursor(nextOffset) : void 0;
+  const frameworks = slice.map((f) => ({
+    id: f.id,
+    name: f.name,
+    category: f.category,
+    description: f.description,
+    tags: f.tags,
+    approach_ids: f.approach_ids,
+    structure_pattern: f.structure?.pattern
+  }));
   const body = {
     total,
     count: slice.length,
-    frameworks: slice
+    frameworks
   };
   if (nextCursor) body.next_cursor = nextCursor;
   return text(JSON.stringify(body, null, 2));
@@ -27298,7 +27471,10 @@ var getFramework = (args) => {
   const id = args.id;
   if (!id) return textError("Missing required parameter: id");
   const framework = UPG_FRAMEWORKS_BY_ID[id];
-  if (!framework) return textError(`Unknown framework id: ${id}`);
+  if (!framework)
+    return textError(
+      `Unknown framework id: "${id}". Pass a framework id from the catalog (e.g. 'moscow', 'rice-scoring', 'kano-model'). See list_frameworks for the full list.`
+    );
   return text(JSON.stringify(framework, null, 2));
 };
 function buildEdgeEntries(filterSource, filterTarget) {
@@ -28989,7 +29165,7 @@ var TOOL_DEFINITIONS = [
   },
   {
     name: "list_frameworks",
-    description: "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.",
+    description: "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.",
     inputSchema: {
       type: "object",
       properties: {
@@ -29918,6 +30094,7 @@ async function runMcpServer() {
     }
   }
   const store = new UPGFileStore();
+  store.setWriter("upg-mcp-local", SERVER_VERSION);
   await store.load(resolvedPath);
   const deprecated = getDeprecatedTypes();
   const nodes = store.getAllNodes();