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

package/dist/index.js

@@ -11079,7 +11079,6 @@ 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",
@@ -11297,31 +11296,37 @@ var UPG_FRAMEWORKS = [
     "slots": [
       {
         "label": "Customer Jobs",
+        "role": "customer_job",
         "entityTypeId": "job",
         "description": "Place job entities in the Customer Jobs position of the matrix"
       },
       {
         "label": "Pains",
+        "role": "pain",
         "entityTypeId": "need",
         "description": "Place need entities in the Pains position of the matrix"
       },
       {
         "label": "Gains",
+        "role": "gain",
         "entityTypeId": "desired_outcome",
         "description": "Place desired outcome entities in the Gains position of the matrix"
       },
       {
         "label": "Products & Services",
+        "role": "product_or_service",
         "entityTypeId": "feature",
         "description": "Place feature entities in the Products & Services position of the matrix"
       },
       {
         "label": "Pain Relievers",
+        "role": "pain_reliever",
         "entityTypeId": "feature",
         "description": "Place feature entities in the Pain Relievers position of the matrix"
       },
       {
         "label": "Gain Creators",
+        "role": "gain_creator",
         "entityTypeId": "feature",
         "description": "Place feature entities in the Gain Creators position of the matrix"
       }
@@ -11950,26 +11955,31 @@ var UPG_FRAMEWORKS = [
     "slots": [
       {
         "label": "Competitive Rivalry",
+        "role": "competitive_rivalry",
         "entityTypeId": "competitor",
         "description": "Intensity of competition among existing players"
       },
       {
         "label": "Threat of New Entrants",
+        "role": "new_entrants",
         "entityTypeId": "competitor",
         "description": "How easy is it for new competitors to enter?"
       },
       {
         "label": "Threat of Substitutes",
+        "role": "substitutes",
         "entityTypeId": "competitor",
         "description": "Can customers switch to alternatives?"
       },
       {
         "label": "Buyer Power",
+        "role": "buyer_power",
         "entityTypeId": "persona",
         "description": "How much leverage do buyers have?"
       },
       {
         "label": "Supplier Power",
+        "role": "supplier_power",
         "entityTypeId": "persona",
         "description": "How much leverage do suppliers have?"
       }
@@ -12137,31 +12147,37 @@ var UPG_FRAMEWORKS = [
     "slots": [
       {
         "label": "Inbound Logistics",
+        "role": "inbound_logistics",
         "entityTypeId": "key_activity",
         "description": "Inbound Logistics phase: key activity entities move through this stage"
       },
       {
         "label": "Operations",
+        "role": "operations",
         "entityTypeId": "key_activity",
         "description": "Operations phase: key activity entities move through this stage"
       },
       {
         "label": "Outbound Logistics",
+        "role": "outbound_logistics",
         "entityTypeId": "key_activity",
         "description": "Outbound Logistics phase: key activity entities move through this stage"
       },
       {
         "label": "Marketing & Sales",
+        "role": "marketing_and_sales",
         "entityTypeId": "key_activity",
         "description": "Marketing & Sales phase: key activity entities move through this stage"
       },
       {
         "label": "Service",
+        "role": "service",
         "entityTypeId": "key_activity",
         "description": "Service phase: key activity entities move through this stage"
       },
       {
         "label": "Support Activities",
+        "role": "support_activity",
         "entityTypeId": "capability",
         "description": "Support Activities phase: capability entities move through this stage"
       }
@@ -12232,26 +12248,31 @@ var UPG_FRAMEWORKS = [
     "slots": [
       {
         "label": "Portfolio",
+        "role": "portfolio",
         "entityTypeId": "portfolio",
         "description": "Innovation portfolio balanced across three horizons: core performance, emerging growth, and future creation"
       },
       {
         "label": "Product",
+        "role": "product",
         "entityTypeId": "product",
         "description": "Product or business unit assigned to a horizon: H1 (defend and extend), H2 (build), or H3 (seed and explore)"
       },
       {
         "label": "Initiative",
+        "role": "initiative",
         "entityTypeId": "portfolio",
         "description": "Growth initiative positioned in a horizon, with appropriate funding model, governance, and success metrics"
       },
       {
         "label": "Product Area",
+        "role": "product_area",
         "entityTypeId": "product_area",
         "description": "Product area representing a horizon: core products (H1), adjacent expansions (H2), or experimental ventures (H3)"
       },
       {
         "label": "Capability",
+        "role": "capability",
         "entityTypeId": "capability",
         "description": "Capability needed to execute across horizons: H1 needs efficiency, H2 needs scaling, H3 needs discovery"
       }
@@ -12731,21 +12752,25 @@ var UPG_FRAMEWORKS = [
     "slots": [
       {
         "label": "Must-haves",
+        "role": "must_have",
         "entityTypeId": "feature",
         "description": "Expected features: absence causes dissatisfaction"
       },
       {
         "label": "Performance",
+        "role": "performance",
         "entityTypeId": "feature",
         "description": "More is better: linear satisfaction increase"
       },
       {
         "label": "Delighters",
+        "role": "delighter",
         "entityTypeId": "feature",
         "description": "Unexpected features: presence creates delight"
       },
       {
         "label": "Indifferent",
+        "role": "indifferent",
         "entityTypeId": "feature",
         "description": "Features users don't care about either way"
       }
@@ -12754,7 +12779,7 @@ var UPG_FRAMEWORKS = [
       "entity_types": [
         {
           "type": "feature",
-          "role": "item"
+          "role": "scored_item"
         }
       ],
       "required_properties": {
@@ -12838,7 +12863,90 @@ var UPG_FRAMEWORKS = [
           "label": "Dissatisfaction Coefficient",
           "format": "number"
         }
-      ]
+      ],
+      "scoring_lens": {
+        "applies_to": [
+          "feature"
+        ],
+        "inputs": [
+          {
+            "property": "functional_response",
+            "type": "enum",
+            "required": true,
+            "scope": "framework",
+            "label": "Functional Response",
+            "description": "How users feel when the feature IS present",
+            "enum_values": [
+              "i_like_it",
+              "i_expect_it",
+              "i_am_neutral",
+              "i_can_tolerate_it",
+              "i_dislike_it"
+            ]
+          },
+          {
+            "property": "dysfunctional_response",
+            "type": "enum",
+            "required": true,
+            "scope": "framework",
+            "label": "Dysfunctional Response",
+            "description": "How users feel when the feature IS NOT present",
+            "enum_values": [
+              "i_like_it",
+              "i_expect_it",
+              "i_am_neutral",
+              "i_can_tolerate_it",
+              "i_dislike_it"
+            ]
+          },
+          {
+            "property": "delighter_count",
+            "type": "number",
+            "required": false,
+            "scope": "framework",
+            "label": "Delighter classifications",
+            "description": "Count of survey responses classifying this feature as a delighter (attractive)"
+          },
+          {
+            "property": "performance_count",
+            "type": "number",
+            "required": false,
+            "scope": "framework",
+            "label": "Performance classifications",
+            "description": "Count of survey responses classifying this feature as performance (one-dimensional)"
+          },
+          {
+            "property": "must_be_count",
+            "type": "number",
+            "required": false,
+            "scope": "framework",
+            "label": "Must-be classifications",
+            "description": "Count of survey responses classifying this feature as must-be (basic)"
+          },
+          {
+            "property": "indifferent_count",
+            "type": "number",
+            "required": false,
+            "scope": "framework",
+            "label": "Indifferent classifications",
+            "description": "Count of survey responses classifying this feature as indifferent"
+          }
+        ],
+        "computed": [
+          {
+            "property": "satisfaction_coefficient",
+            "expression": "(delighter_count + performance_count) / (delighter_count + performance_count + must_be_count + indifferent_count)",
+            "label": "Satisfaction Coefficient",
+            "format": "number"
+          },
+          {
+            "property": "dissatisfaction_coefficient",
+            "expression": "(must_be_count + performance_count) / (delighter_count + performance_count + must_be_count + indifferent_count) * -1",
+            "label": "Dissatisfaction Coefficient",
+            "format": "number"
+          }
+        ]
+      }
     },
     "structure": {
       "pattern": "matrix"
@@ -12893,16 +13001,19 @@ var UPG_FRAMEWORKS = [
     "slots": [
       {
         "label": "Now",
+        "role": "now",
         "entityTypeId": "feature",
         "description": "Committed work in progress"
       },
       {
         "label": "Next",
+        "role": "next",
         "entityTypeId": "feature",
         "description": "High-confidence upcoming work"
       },
       {
         "label": "Later",
+        "role": "later",
         "entityTypeId": "initiative",
         "description": "Exploratory, needs more discovery"
       }
@@ -13418,26 +13529,31 @@ var UPG_FRAMEWORKS = [
     "slots": [
       {
         "label": "Atoms",
+        "role": "atom",
         "entityTypeId": "design_component",
         "description": "Atoms: design component entities for this dimension of the framework"
       },
       {
         "label": "Molecules",
+        "role": "molecule",
         "entityTypeId": "design_component",
         "description": "Molecules: design token entities for this dimension of the framework"
       },
       {
         "label": "Organisms",
+        "role": "organism",
         "entityTypeId": "design_pattern",
         "description": "Organisms: design pattern entities for this dimension of the framework"
       },
       {
         "label": "Templates",
+        "role": "template",
         "entityTypeId": "wireframe",
         "description": "Templates: design system entities for this dimension of the framework"
       },
       {
         "label": "Pages",
+        "role": "page",
         "entityTypeId": "screen",
         "description": "Pages: screen entities for this dimension of the framework"
       }
@@ -14102,26 +14218,31 @@ var UPG_FRAMEWORKS = [
     "slots": [
       {
         "label": "Outer Ring",
+        "role": "outer_ring",
         "entityTypeId": "acquisition_channel",
         "description": "All 19 traction channels brainstormed"
       },
       {
         "label": "Middle Ring",
+        "role": "middle_ring",
         "entityTypeId": "acquisition_channel",
         "description": "Top 6 channels worth testing"
       },
       {
         "label": "Inner Ring",
+        "role": "inner_ring",
         "entityTypeId": "acquisition_channel",
         "description": "Top 3 channels to focus on"
       },
       {
         "label": "Traction Test",
+        "role": "traction_test",
         "entityTypeId": "growth_campaign",
         "description": "Cheap test for each channel"
       },
       {
         "label": "Bullseye Channel",
+        "role": "bullseye_channel",
         "entityTypeId": "acquisition_channel",
         "description": "The single best-performing channel"
       }
@@ -14191,26 +14312,31 @@ var UPG_FRAMEWORKS = [
     "slots": [
       {
         "label": "Free Entry",
+        "role": "free_entry",
         "entityTypeId": "gtm_strategy",
         "description": "How users access the product for free"
       },
       {
         "label": "Aha Moment",
+        "role": "aha_moment",
         "entityTypeId": "gtm_strategy",
         "description": "First experience of core value"
       },
       {
         "label": "Expansion Motion",
+        "role": "expansion_motion",
         "entityTypeId": "sales_motion",
         "description": "How usage spreads within accounts"
       },
       {
         "label": "Monetisation Trigger",
+        "role": "monetisation_trigger",
         "entityTypeId": "gtm_strategy",
         "description": "When and how to convert to paid"
       },
       {
         "label": "Metric",
+        "role": "metric",
         "entityTypeId": "metric",
         "description": "Key metric driving the PLG motion"
       }
@@ -14285,21 +14411,25 @@ var UPG_FRAMEWORKS = [
     "slots": [
       {
         "label": "Objective",
+        "role": "objective",
         "entityTypeId": "objective",
         "description": "Qualitative, inspiring goal"
       },
       {
         "label": "Key Result 1",
+        "role": "key_result",
         "entityTypeId": "key_result",
         "description": "Measurable outcome proving progress"
       },
       {
         "label": "Key Result 2",
+        "role": "key_result",
         "entityTypeId": "key_result",
         "description": "Measurable outcome proving progress"
       },
       {
         "label": "Initiatives",
+        "role": "initiative",
         "entityTypeId": "initiative",
         "description": "Work streams that drive key results"
       }
@@ -14373,26 +14503,31 @@ var UPG_FRAMEWORKS = [
     "slots": [
       {
         "label": "Activity",
+        "role": "activity",
         "entityTypeId": "key_activity",
         "description": "Place persona entities in the Activity position of the matrix"
       },
       {
         "label": "Responsible",
+        "role": "responsible",
         "entityTypeId": "role",
         "description": "Does the work"
       },
       {
         "label": "Accountable",
+        "role": "accountable",
         "entityTypeId": "role",
         "description": "Makes the final call"
       },
       {
         "label": "Consulted",
+        "role": "consulted",
         "entityTypeId": "role",
         "description": "Gives input"
       },
       {
         "label": "Informed",
+        "role": "informed",
         "entityTypeId": "role",
         "description": "Kept in the loop"
       }
@@ -14466,21 +14601,25 @@ var UPG_FRAMEWORKS = [
     "slots": [
       {
         "label": "What Went Well",
+        "role": "went_well",
         "entityTypeId": "outcome",
         "description": "Practices to continue"
       },
       {
         "label": "What Didn't Go Well",
+        "role": "went_poorly",
         "entityTypeId": "need",
         "description": "Issues to address"
       },
       {
         "label": "Action Items",
+        "role": "action_item",
         "entityTypeId": "learning",
         "description": "Changes for next iteration"
       },
       {
         "label": "Learnings",
+        "role": "learning",
         "entityTypeId": "learning",
         "description": "Insights to carry forward"
       }
@@ -14841,7 +14980,36 @@ var UPG_FRAMEWORKS = [
           "label": "Severity",
           "format": "number"
         }
-      ]
+      ],
+      "scoring_lens": {
+        "applies_to": [
+          "risk"
+        ],
+        "inputs": [
+          {
+            "property": "probability",
+            "type": "number",
+            "required": true,
+            "label": "Probability",
+            "description": "Likelihood the risk materialises (risk.probability assessment)"
+          },
+          {
+            "property": "impact",
+            "type": "number",
+            "required": true,
+            "label": "Impact",
+            "description": "Consequence severity if the risk materialises (risk.impact assessment)"
+          }
+        ],
+        "computed": [
+          {
+            "property": "severity",
+            "expression": "probability * impact",
+            "label": "Severity",
+            "format": "number"
+          }
+        ]
+      }
     },
     "structure": {
       "pattern": "table"
@@ -14917,31 +15085,37 @@ var UPG_FRAMEWORKS = [
     "slots": [
       {
         "label": "Items to score",
+        "role": "candidate",
         "entityTypeId": "feature",
         "description": "Features or experiments being evaluated"
       },
       {
         "label": "Impact",
+        "role": "impact",
         "entityTypeId": "outcome",
         "description": "How much will this move the needle?"
       },
       {
         "label": "Confidence",
+        "role": "confidence",
         "entityTypeId": "assumption",
         "description": "How sure are we about the impact?"
       },
       {
         "label": "Ease",
+        "role": "ease",
         "entityTypeId": "feature",
         "description": "How easy is this to implement?"
       },
       {
         "label": "Opportunities to score",
+        "role": "candidate",
         "entityTypeId": "opportunity",
         "description": "Opportunities scored on the same ICE Scoring inputs as features."
       },
       {
         "label": "Needs to score",
+        "role": "candidate",
         "entityTypeId": "need",
         "description": "Needs scored on the same ICE Scoring inputs as features."
       }
@@ -15192,31 +15366,37 @@ var UPG_FRAMEWORKS = [
     "slots": [
       {
         "label": "Backlog Items",
+        "role": "candidate",
         "entityTypeId": "feature",
         "description": "Backlog Items: feature entries to evaluate"
       },
       {
         "label": "User/Business Value",
+        "role": "user_business_value",
         "entityTypeId": "metric",
         "description": "User/Business Value: metric entries to evaluate"
       },
       {
         "label": "Time Criticality",
+        "role": "time_criticality",
         "entityTypeId": "metric",
         "description": "How much value decays if delivery is delayed (deadlines, competition, seasonal windows)"
       },
       {
         "label": "Risk Reduction / Opportunity Enablement",
+        "role": "risk_reduction",
         "entityTypeId": "metric",
         "description": "Risk Reduction / Opportunity Enablement: metric entries to evaluate"
       },
       {
         "label": "Job Size",
+        "role": "job_size",
         "entityTypeId": "metric",
         "description": "Estimated effort (story points, t-shirt size, or person-weeks)"
       },
       {
         "label": "Opportunities to score",
+        "role": "candidate",
         "entityTypeId": "opportunity",
         "description": "Opportunities scored on the same WSJF (Weighted Shortest Job First) inputs as features."
       }
@@ -15672,16 +15852,19 @@ var UPG_FRAMEWORKS = [
     "slots": [
       {
         "label": "Symptom",
+        "role": "symptom",
         "entityTypeId": "need",
         "description": "The observed problem the analysis starts from."
       },
       {
         "label": "Why chain",
+        "role": "why",
         "entityTypeId": "insight",
         "description": 'Each "why?" answer along the chain, typically five iterations deep.'
       },
       {
         "label": "Root cause",
+        "role": "root_cause",
         "entityTypeId": "insight",
         "description": "The terminal answer at the bottom of the chain: the underlying cause to address."
       }
@@ -16026,16 +16209,19 @@ var UPG_FRAMEWORKS = [
     "slots": [
       {
         "label": "First-order move",
+        "role": "first_order",
         "entityTypeId": "decision",
         "description": "The decision or move under consideration."
       },
       {
         "label": "Second-order consequences",
+        "role": "second_order",
         "entityTypeId": "insight",
         "description": "Downstream effects that follow from the first-order move."
       },
       {
         "label": "Higher-order consequences",
+        "role": "higher_order",
         "entityTypeId": "insight",
         "description": "Third-, fourth-, fifth-order ripples: second-order consequences of the second-order consequences."
       }
@@ -16094,6 +16280,7 @@ for (const fw of UPG_FRAMEWORKS) {
   if (!UPG_FRAMEWORKS_BY_CATEGORY[fw.category]) UPG_FRAMEWORKS_BY_CATEGORY[fw.category] = [];
   UPG_FRAMEWORKS_BY_CATEGORY[fw.category].push(fw);
 }
+var crossProductEdgeTypeSet = new Set(UPG_CROSS_EDGE_TYPES);
 var PRIORITY_LABELS = [
   // ── need (CONSOLIDATED: replaces pain_point + user_need) ─────────────────────
   {
@@ -24888,12 +25075,13 @@ var listNodes = (args, ctx) => {
 };
 var getNode = (args, ctx) => {
   const { store } = ctx;
-  if (!args.node_id) return textError(`Missing required parameter: node_id`);
+  const nodeId2 = args.node_id ?? args.id;
+  if (!nodeId2) return textError(`Missing required parameter: node_id (alias: id)`);
   const result = getNodeLib(store, {
-    node_id: args.node_id,
+    node_id: nodeId2,
     compact_edges: args.compact_edges ?? false
   });
-  if (!result) return textError(`Node not found: ${args.node_id}`);
+  if (!result) return textError(`Node not found: ${nodeId2}`);
   const typed = result;
   if (typed.node.properties) {
     const { unknown_properties, warning } = checkUnknownProperties(typed.node.type, typed.node.properties);
@@ -26332,7 +26520,10 @@ var listLocalProducts = (_args, _ctx) => {
 };
 var switchProduct = async (args, ctx) => {
   const { store } = ctx;
-  const fileArg = args.file;
+  const fileArg = args.file ?? args.product;
+  if (typeof fileArg !== "string" || fileArg.length === 0) {
+    return textError("Missing required parameter: file (alias: product). Pass a .upg path or a bare product name.");
+  }
   let resolved = path3.resolve(fileArg);
   if (!fs.existsSync(resolved)) {
     const cwd = process.cwd();
@@ -27130,9 +27321,11 @@ var validateGraph = (args, ctx) => {
     argsHint: `scope=${scope}, limit=${limit}`
   });
   if (guardOutcome.kind === "refuse") return guardOutcome.result;
-  const driftClean = skipDrift || summary.entity_drift === 0 && summary.edge_drift === 0 && summary.top_level_drift === 0 && summary.lifecycle_drift === 0 && summary.self_referential === 0 && summary.property_drift === 0 && edgeTypePairDrift.length === 0 && graphTopologySelfLoops.length === 0 && propertyTypeDrift.length === 0;
+  const structurallyClean = summary.entity_drift === 0 && summary.edge_drift === 0 && summary.top_level_drift === 0 && summary.lifecycle_drift === 0 && summary.self_referential === 0 && summary.property_drift === 0 && edgeTypePairDrift.length === 0 && graphTopologySelfLoops.length === 0 && propertyTypeDrift.length === 0;
+  const driftClean = skipDrift || structurallyClean;
   const antiPatternClean = skipAntiPatterns || (antiPatternViolations?.length ?? 0) === 0;
   const valid = driftClean && antiPatternClean;
+  const structurallyValid = skipDrift ? void 0 : structurallyClean;
   let highCount = 0;
   let mediumCount = 0;
   let lowCount = 0;
@@ -27145,6 +27338,11 @@ var validateGraph = (args, ctx) => {
   }
   const response = {
     valid,
+    // N4 (UPG QA 0.8.7): additive structural-conformance signal. true ⟺ every
+    // drift class is 0, independent of anti-pattern health. Omitted when
+    // `skip_drift` is true (structure was not assessed). A CI gate that wants
+    // "is this graph spec-shaped?" should read this, not `valid`.
+    ...structurallyValid !== void 0 ? { structurally_valid: structurallyValid } : {},
     summary: {
       ...summary,
       spec_version: UPG_VERSION,
@@ -27468,8 +27666,8 @@ var listFrameworks = (args) => {
   return text(JSON.stringify(body, null, 2));
 };
 var getFramework = (args) => {
-  const id = args.id;
-  if (!id) return textError("Missing required parameter: id");
+  const id = args.id ?? args.framework_id;
+  if (!id) return textError("Missing required parameter: id (alias: framework_id)");
   const framework = UPG_FRAMEWORKS_BY_ID[id];
   if (!framework)
     return textError(
@@ -28440,7 +28638,8 @@ var TOOL_DEFINITIONS = [
     inputSchema: {
       type: "object",
       properties: {
-        node_id: { type: "string", description: "The node ID" },
+        node_id: { type: "string", description: "The node ID. Alias: `id`." },
+        id: { type: "string", description: "Alias for `node_id`." },
         compact_edges: { type: "boolean", description: "Omit source_title/target_title from edges (saves ~30% on edge-heavy nodes)" }
       },
       required: ["node_id"]
@@ -28882,7 +29081,11 @@ var TOOL_DEFINITIONS = [
       properties: {
         file: {
           type: "string",
-          description: "Path to the .upg file (relative, absolute, or a bare product name in workspace mode)."
+          description: "Path to the .upg file (relative, absolute, or a bare product name in workspace mode). Alias: `product`."
+        },
+        product: {
+          type: "string",
+          description: "Alias for `file`."
         }
       },
       required: ["file"]
@@ -29181,7 +29384,8 @@ var TOOL_DEFINITIONS = [
     inputSchema: {
       type: "object",
       properties: {
-        id: { type: "string", description: "Framework id (kebab-case)." }
+        id: { type: "string", description: "Framework id (kebab-case). Alias: `framework_id`." },
+        framework_id: { type: "string", description: "Alias for `id` (matches the key used by apply_framework / prioritise)." }
       },
       required: ["id"]
     }