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

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,17 @@ 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",
+        "entityTypeId": "opportunity",
+        "description": "Opportunities scored on the same RICE Scoring inputs as features."
+      },
+      {
+        "label": "Needs to score",
+        "entityTypeId": "need",
+        "description": "Needs scored on the same RICE Scoring inputs as features."
       }
     ],
     "data": {
@@ -12341,6 +12351,14 @@ var UPG_FRAMEWORKS = [
         {
           "type": "feature",
           "role": "scored_item"
+        },
+        {
+          "type": "opportunity",
+          "role": "scored_item"
+        },
+        {
+          "type": "need",
+          "role": "scored_item"
         }
       ],
       "required_properties": {
@@ -12381,6 +12399,82 @@ var UPG_FRAMEWORKS = [
             "label": "Effort",
             "description": "How much work is required to build and ship this, on the effort scale?"
           }
+        ],
+        "opportunity": [
+          {
+            "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?"
+          }
+        ],
+        "need": [
+          {
+            "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_properties": [
@@ -12390,8 +12484,75 @@ var UPG_FRAMEWORKS = [
           "entity_type": "feature",
           "label": "RICE Score",
           "format": "number"
+        },
+        {
+          "property": "rice_score",
+          "expression": "(reach * impact * confidence) / effort",
+          "entity_type": "opportunity",
+          "label": "RICE Score",
+          "format": "number"
+        },
+        {
+          "property": "rice_score",
+          "expression": "(reach * impact * confidence) / effort",
+          "entity_type": "need",
+          "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"
@@ -14516,7 +14677,7 @@ var UPG_FRAMEWORKS = [
       "entity_types": [
         {
           "type": "team",
-          "role": "scored_item"
+          "role": "item"
         },
         {
           "type": "retrospective",
@@ -14773,6 +14934,16 @@ var UPG_FRAMEWORKS = [
         "label": "Ease",
         "entityTypeId": "feature",
         "description": "How easy is this to implement?"
+      },
+      {
+        "label": "Opportunities to score",
+        "entityTypeId": "opportunity",
+        "description": "Opportunities scored on the same ICE Scoring inputs as features."
+      },
+      {
+        "label": "Needs to score",
+        "entityTypeId": "need",
+        "description": "Needs scored on the same ICE Scoring inputs as features."
       }
     ],
     "data": {
@@ -14788,6 +14959,14 @@ var UPG_FRAMEWORKS = [
         {
           "type": "assumption",
           "role": "item"
+        },
+        {
+          "type": "opportunity",
+          "role": "scored_item"
+        },
+        {
+          "type": "need",
+          "role": "scored_item"
         }
       ],
       "required_properties": {
@@ -14816,6 +14995,58 @@ var UPG_FRAMEWORKS = [
             "label": "Ease",
             "description": "Ease of implementation (1-10)"
           }
+        ],
+        "opportunity": [
+          {
+            "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)"
+          }
+        ],
+        "need": [
+          {
+            "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_properties": [
@@ -14825,8 +15056,63 @@ var UPG_FRAMEWORKS = [
           "entity_type": "feature",
           "label": "ICE Score",
           "format": "number"
+        },
+        {
+          "property": "ice_score",
+          "expression": "impact * confidence * ease",
+          "entity_type": "opportunity",
+          "label": "ICE Score",
+          "format": "number"
+        },
+        {
+          "property": "ice_score",
+          "expression": "impact * confidence * ease",
+          "entity_type": "need",
+          "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"
@@ -14928,6 +15214,11 @@ var UPG_FRAMEWORKS = [
         "label": "Job Size",
         "entityTypeId": "metric",
         "description": "Estimated effort (story points, t-shirt size, or person-weeks)"
+      },
+      {
+        "label": "Opportunities to score",
+        "entityTypeId": "opportunity",
+        "description": "Opportunities scored on the same WSJF (Weighted Shortest Job First) inputs as features."
       }
     ],
     "data": {
@@ -14939,6 +15230,10 @@ var UPG_FRAMEWORKS = [
         {
           "type": "metric",
           "role": "item"
+        },
+        {
+          "type": "opportunity",
+          "role": "scored_item"
         }
       ],
       "required_properties": {
@@ -14975,6 +15270,40 @@ var UPG_FRAMEWORKS = [
             "label": "Job Size",
             "description": "Estimated effort (story points, t-shirt size, or person-weeks)"
           }
+        ],
+        "opportunity": [
+          {
+            "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_properties": [
@@ -14984,8 +15313,63 @@ var UPG_FRAMEWORKS = [
           "entity_type": "feature",
           "label": "WSJF Score",
           "format": "number"
+        },
+        {
+          "property": "wsjf_score",
+          "expression": "(user_value + time_criticality + risk_reduction) / job_size",
+          "entity_type": "opportunity",
+          "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"
@@ -15058,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",
@@ -15091,6 +15475,11 @@ var UPG_FRAMEWORKS = [
         "label": "Risk Reduction",
         "entityTypeId": "risk",
         "description": "What risk does this mitigate?"
+      },
+      {
+        "label": "Opportunities to score",
+        "entityTypeId": "opportunity",
+        "description": "Opportunities scored on the same Cost of Delay inputs as features."
       }
     ],
     "data": {
@@ -15110,6 +15499,10 @@ var UPG_FRAMEWORKS = [
         {
           "type": "risk",
           "role": "item"
+        },
+        {
+          "type": "opportunity",
+          "role": "scored_item"
         }
       ],
       "required_properties": {
@@ -15130,6 +15523,24 @@ var UPG_FRAMEWORKS = [
             "label": "Job Size",
             "description": "Weeks of development effort"
           }
+        ],
+        "opportunity": [
+          {
+            "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_properties": [
@@ -15139,8 +15550,47 @@ var UPG_FRAMEWORKS = [
           "entity_type": "feature",
           "label": "WSJF Score",
           "format": "number"
+        },
+        {
+          "property": "wsjf_score",
+          "expression": "cost_of_delay / job_size",
+          "entity_type": "opportunity",
+          "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"
@@ -23728,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.4";
+var UPG_VERSION = "0.8.7";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();
 var UPG_TYPES_SET = new Set(UPG_TYPES);
@@ -26237,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) => {
@@ -26252,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);
   }
@@ -27010,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));
@@ -27022,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) {
@@ -28713,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: {
@@ -29642,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();