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

package/CHANGELOG.md

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

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
 
@@ -767,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). |
@@ -1349,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)
@@ -1391,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.
@@ -2235,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:**
@@ -2310,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".

package/dist/index.js

@@ -511,8 +511,8 @@ var UPG_DOMAINS = [
   {
     id: "workspace",
     label: "Workspace",
-    description: "Spatial thinking spaces for arranging entities, debating decisions, and committing to the graph. Workspaces are transient canvases that sit alongside all other domains, letting you compose and explore relationships before they become permanent graph structure.",
-    types: ["workspace"]
+    description: "Spatial thinking spaces for arranging entities, debating decisions, and committing to the graph. Workspaces are transient canvases that sit alongside all other domains, letting you compose and explore relationships before they become permanent graph structure. A framework exercise is a structured workspace: one run of a framework (MoSCoW, RICE, Kano, \u2026) applied to a chosen set of entities, with each entity's result recorded on the exercise-to-entity edge rather than the entity itself.",
+    types: ["workspace", "framework_exercise"]
   }
 ];
 var UPG_ENTITY_TO_DOMAIN = Object.freeze(
@@ -933,7 +933,8 @@ var UPG_ENTITY_META = [
   { name: "integration_partner", type_id: "ent_311", maturity: "stable", since: "0.1.0" },
   { name: "partner_revenue_share", type_id: "ent_312", maturity: "stable", since: "0.1.0" },
   // ── Workspace ──
-  { name: "workspace", type_id: "ent_328", maturity: "proposed", since: "0.2.0" }
+  { name: "workspace", type_id: "ent_328", maturity: "proposed", since: "0.2.0" },
+  { name: "framework_exercise", type_id: "ent_350", maturity: "proposed", since: "0.8.4" }
 ];
 var UPG_ENTITY_META_BY_NAME = new Map(
   UPG_ENTITY_META.map((m) => [m.name, m])
@@ -2073,6 +2074,18 @@ var UPG_EDGE_CATALOG = {
   // universal across the DDD type family. Verbs follow DDD literature:
   // aggregate belongs_to context, context contains aggregates.
   node_belongs_to_bounded_context: { forward_verb: "belongs_to", reverse_verb: "contains", classification: "cross-domain", source_type: "node", target_type: "bounded_context" },
+  // ── Cross-domain: Framework exercises ────────────────────────────────────────
+  // A framework_exercise is one run of a framework (MoSCoW, RICE, Kano, …) over a
+  // set of entities. It `includes` each entity it touches; the framework's
+  // per-entity result — a MoSCoW bucket, a RICE score, a canvas slot, a funnel
+  // stage — rides on this edge's `properties`, NOT on the entity node. A value
+  // that exists only within a specific exercise is a fact about the relationship,
+  // not the entity, so it lives on the edge (same principle as owner-as-edge).
+  // Polymorphic (`target_type: 'node'`): an exercise can include any entity type,
+  // which closes the feature-only limitation structurally. `carries_properties`
+  // opts this edge into the gated edge-property model. See ADR
+  // 2026-06-02-framework-exercises.
+  framework_exercise_includes_node: { forward_verb: "includes", reverse_verb: "included_in", classification: "cross-domain", source_type: "framework_exercise", target_type: "node", carries_properties: true },
   // ── New edges replacing deleted string properties ────────────────────
   // Marketing
   marketing_strategy_pursues_outcome: { forward_verb: "pursues", reverse_verb: "pursued_by", classification: "cross-domain", source_type: "marketing_strategy", target_type: "outcome" },
@@ -2702,7 +2715,9 @@ var UPG_POLYMORPHIC_EDGE_KEYS = [
   "node_owned_by_department",
   "node_owned_by_person",
   // Universal architecture references
-  "node_belongs_to_bounded_context"
+  "node_belongs_to_bounded_context",
+  // Framework exercises (an exercise can include any entity type)
+  "framework_exercise_includes_node"
 ];
 var _POLY_KEY_SET = new Set(UPG_POLYMORPHIC_EDGE_KEYS);
 var LEGACY_PRODUCT_STAGES = Object.freeze({
@@ -5625,6 +5640,31 @@ var TEMPLATE_LIFECYCLES = [
   // ── Phase B: SALES_DEAL (qualified → proposal → negotiation → won/lost) ─────
   fromTemplate("deal", SALES_DEAL_TEMPLATE)
 ];
+var FRAMEWORK_EXERCISE_LIFECYCLE = {
+  entity_type: "framework_exercise",
+  initial_phase: "draft",
+  terminal_phases: ["archived"],
+  phases: [
+    {
+      id: "draft",
+      label: "Draft",
+      description: "The exercise has been created and entities pulled into scope, but the framework's inputs have not all been filled in yet.",
+      transitions_to: ["active", "archived"]
+    },
+    {
+      id: "active",
+      label: "Active",
+      description: "The current, authoritative run of its framework. Its include edges carry the live results consumers read, rank, and render by.",
+      transitions_to: ["archived"]
+    },
+    {
+      id: "archived",
+      label: "Archived",
+      description: "A past run, retained for provenance. Still queryable but superseded by a newer exercise and hidden from default views. Can be revived to active.",
+      transitions_to: ["active"]
+    }
+  ]
+};
 var UPG_LIFECYCLES = [
   // Product (root)
   PRODUCT_LIFECYCLE,
@@ -5726,6 +5766,8 @@ var UPG_LIFECYCLES = [
   // Product & Growth
   VARIANT_LIFECYCLE,
   GROWTH_CAMPAIGN_LIFECYCLE,
+  // Workspace
+  FRAMEWORK_EXERCISE_LIFECYCLE,
   // ── Template-generated lifecycles ─────────────────────────────────
   ...TEMPLATE_LIFECYCLES
 ];
@@ -9203,6 +9245,11 @@ var UPG_PROPERTY_SCHEMA = {
     },
     methodology: { type: "string", description: "Forecasting methodology used" }
   },
+  // FrameworkExerciseProperties: Framework exercise: one run of a framework over a set of entities.
+  framework_exercise: {
+    framework_id: { type: "string", description: "Which framework this exercise runs: a framework id (e.g. 'moscow', 'rice-scoring', 'kano-model'). Resolves against the framework catalog." },
+    inputs_snapshot: { type: "object", description: "Optional frozen copy of the framework's input spec at apply time, so a historical exercise still renders correctly if the framework definition later evolves (inputs added, removed, or rescaled)." }
+  },
   // FunnelProperties: Funnel entity.
   funnel: {
     funnel_type: { type: "string", enum: ["acquisition", "activation", "retention", "revenue", "referral", "custom"], description: "Which stage of the customer lifecycle this funnel measures" },
@@ -18764,7 +18811,7 @@ var PORTFOLIO_GUIDE = {
 var WORKSPACE_GUIDE = {
   domain_id: "workspace",
   anchor_entity: "workspace",
-  creation_sequence: ["workspace"],
+  creation_sequence: ["workspace", "framework_exercise"],
   patterns: [],
   required_bridges: [],
   anti_patterns: [
@@ -23564,7 +23611,7 @@ var NODE_KEY_ORDER = [
   "sort_order",
   "properties"
 ];
-var EDGE_KEY_ORDER = ["id", "source", "target", "type", "mapping_confidence"];
+var EDGE_KEY_ORDER = ["id", "source", "target", "type", "mapping_confidence", "properties"];
 var CROSS_EDGE_KEY_ORDER = ["id", "source", "target", "type", "source_product_id", "target_product_id", "mapping_confidence"];
 var PRODUCT_KEY_ORDER = ["id", "title", "description", "stage", "properties"];
 function canonicalNode(node) {
@@ -23576,7 +23623,8 @@ function canonicalNode(node) {
 }
 function canonicalEdge(edge) {
   return orderedObject(edge, EDGE_KEY_ORDER, {
-    forceKeys: ["id", "source", "target", "type"]
+    forceKeys: ["id", "source", "target", "type"],
+    openKeys: ["properties"]
   });
 }
 function canonicalCrossEdge(edge) {
@@ -23680,7 +23728,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.2";
+var UPG_VERSION = "0.8.4";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();
 var UPG_TYPES_SET = new Set(UPG_TYPES);
@@ -25286,7 +25334,8 @@ var createEdge = (args, ctx) => {
     target_id: args.target_id,
     target_title: args.target_title,
     target_type: args.target_type,
-    type: args.type
+    type: args.type,
+    properties: args.properties
   });
   if ("error" in result) {
     if (result.no_canonical_edge_for) {
@@ -26185,6 +26234,62 @@ var getEntitySchema = (args, _ctx) => {
   }
 };
 
+// src/tools/frameworks.ts
+import {
+  applyFramework as applyFrameworkLib,
+  scoreEntity as scoreEntityLib
+} from "@unified-product-graph/sdk";
+var applyFramework = (args, ctx) => {
+  const { store } = ctx;
+  const frameworkId = args.framework_id;
+  if (!frameworkId) {
+    return textError('Missing required parameter: framework_id (e.g. "moscow", "rice-scoring")');
+  }
+  try {
+    const result = applyFrameworkLib(store, {
+      framework_id: frameworkId,
+      title: args.title,
+      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
+      )
+    );
+  } catch (err) {
+    return textError(err.message);
+  }
+};
+var scoreEntity = (args, ctx) => {
+  const { store } = ctx;
+  const exerciseId = args.exercise_id;
+  const entityId = args.entity_id;
+  const values = args.values;
+  if (!exerciseId) return textError("Missing required parameter: exercise_id");
+  if (!entityId) return textError("Missing required parameter: entity_id");
+  if (!values || typeof values !== "object" || Array.isArray(values)) {
+    return textError(
+      'Missing required parameter: values (object of input \u2192 value, e.g. { "moscow": "must" })'
+    );
+  }
+  const result = scoreEntityLib(store, {
+    exercise_id: exerciseId,
+    entity_id: entityId,
+    values,
+    replace: args.replace
+  });
+  if ("error" in result) return textError(result.error);
+  return text(JSON.stringify({ edge: result.edge, warnings: result.warnings }, null, 2));
+};
+
 // src/tools/spec.ts
 import { buildResolverHints as buildResolverHints2 } from "@unified-product-graph/sdk";
 import {
@@ -26779,34 +26884,38 @@ var inspect = async (args, ctx) => {
   });
 };
 var prioritise = (args, ctx) => {
-  const candidates = args.candidates;
+  const candidates = args.candidates ?? [];
   const frameworkId = args.framework_id;
-  if (!candidates || !Array.isArray(candidates) || candidates.length === 0) {
-    return textError("Missing required parameter: candidates (entity_id[])");
-  }
+  const exerciseId = args.exercise_id;
   if (!frameworkId) {
     return textError(
       'Missing required parameter: framework_id (e.g. "rice-scoring", "ice-scoring", "wsjf")'
     );
   }
+  if (!exerciseId && (!Array.isArray(candidates) || candidates.length === 0)) {
+    return textError(
+      "Provide candidates (entity_id[]), or an exercise_id whose includes edges supply the candidates and their scoring inputs."
+    );
+  }
   const framework = UPG_FRAMEWORKS_BY_ID[frameworkId];
   if (!framework) {
     return textError(
       `Unknown framework_id: "${frameworkId}". See list_frameworks for valid ids.`
     );
   }
-  const execResult = executePrioritise(framework, candidates, ctx.store);
+  const execResult = executePrioritise(framework, candidates, ctx.store, { exerciseId });
+  const params = { candidates, framework_id: frameworkId, ...exerciseId ? { exercise_id: exerciseId } : {} };
   if (execResult.kind === "execution") {
     return approachEnvelope("prioritise", candidates, {
-      params: { candidates, framework_id: frameworkId },
+      params,
       framework_resolved: execResult.framework_used,
       ranked: execResult.ranked,
       required_properties: execResult.required_properties,
-      execution_mode: "execution_v0_4_0"
+      execution_mode: exerciseId ? "exercise_v0_8_4" : "execution_v0_4_0"
     });
   }
   return approachEnvelope("prioritise", candidates, {
-    params: { candidates, framework_id: frameworkId },
+    params,
     framework_resolved: execResult.framework_used,
     hint: execResult.hint,
     execution_mode: "definition_lookup_v0_4_0"
@@ -28181,6 +28290,10 @@ var TOOL_DEFINITIONS = [
         type: {
           type: "string",
           description: "Edge type. Auto-inferred if omitted."
+        },
+        properties: {
+          type: "object",
+          description: "Edge-scoped properties. Only permitted on edge types that opt in (currently framework_exercise_includes_node); rejected on plain semantic edges."
         }
       },
       required: ["source_id"]
@@ -28482,10 +28595,39 @@ var TOOL_DEFINITIONS = [
     inputSchema: {
       type: "object",
       properties: {
-        candidates: { type: "array", items: { type: "string" }, description: "Required. entity_id[] to rank." },
-        framework_id: { type: "string", description: 'Required. UPGFramework.id of the scoring lens (e.g. "rice-scoring", "ice-scoring", "kano-model", "cost-of-delay", "wsjf").' }
+        candidates: { type: "array", items: { type: "string" }, description: "entity_id[] to rank. Optional when exercise_id is given (the exercise supplies them)." },
+        framework_id: { type: "string", description: 'Required. UPGFramework.id of the scoring lens (e.g. "rice-scoring", "ice-scoring", "kano-model", "cost-of-delay", "wsjf").' },
+        exercise_id: { type: "string", description: "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." }
+      },
+      required: ["framework_id"]
+    }
+  },
+  {
+    name: "apply_framework",
+    description: "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 }.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        framework_id: { type: "string", description: 'Required. UPGFramework.id (e.g. "moscow", "rice-scoring").' },
+        title: { type: "string", description: 'Human label for the exercise (default "<Framework> exercise").' },
+        entity_ids: { type: "array", items: { type: "string" }, description: "Entities to pull into the exercise (any type)." },
+        status: { type: "string", description: "Lifecycle phase: draft | active | archived (default draft)." }
       },
-      required: ["candidates", "framework_id"]
+      required: ["framework_id"]
+    }
+  },
+  {
+    name: "score_entity",
+    description: "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 }.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        exercise_id: { type: "string", description: "Required. The framework_exercise id." },
+        entity_id: { type: "string", description: "Required. The entity being scored." },
+        values: { type: "object", description: 'Required. The result as { input: value }, e.g. { "moscow": "must" } or { "reach": 800, "impact": 3 }.' },
+        replace: { type: "boolean", description: "Replace the edge properties instead of merging (default false)." }
+      },
+      required: ["exercise_id", "entity_id", "values"]
     }
   },
   {
@@ -29141,6 +29283,8 @@ var HANDLERS = {
   batch_delete_nodes: batchDeleteNodes,
   batch_create_edges: batchCreateEdges,
   batch_delete_edges: batchDeleteEdges,
+  apply_framework: applyFramework,
+  score_entity: scoreEntity,
   repair_dangling_edges: repairDanglingEdges,
   export_edges: exportEdges,
   rename_edge_type: renameEdgeType,
@@ -29409,7 +29553,12 @@ async function runMcpServer() {
     options: {
       file: { type: "string", short: "f" },
       title: { type: "string", short: "t" }
-    }
+    },
+    // Tolerate stray positionals. When launched via `upg mcp run`, argv carries
+    // the `mcp run` subcommand tokens; without this, parseArgs throws
+    // ERR_PARSE_ARGS_UNEXPECTED_POSITIONAL and the server never starts. The
+    // standalone bin (`upg-mcp-server`) passes none, so this is harmless there.
+    allowPositionals: true
   });
   let resolvedPath = await discoverUPGFile(values.file);
   if (!resolvedPath) {