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

package/dist/tools-manifest.json

@@ -1,7 +1,7 @@
 {
   "schema_version": "2",
   "package": "@unified-product-graph/mcp-server",
-  "package_version": "0.8.6",
+  "package_version": "0.8.7",
   "tool_count": 96,
   "domains": [
     "context",
@@ -2145,17 +2145,20 @@
         ]
       },
       "throws": [
-        "textError on a missing/unknown framework_id."
+        "textError on a missing/unknown framework_id, or when no requested\nentity resolves (no dangling exercise is left behind)."
       ],
       "examples": [],
       "warnings": [],
       "see": [
         "score_entity"
       ],
-      "source": "src/tools/frameworks.ts:22",
+      "source": "src/tools/frameworks.ts:25",
       "symbol": "applyFramework",
-      "returns": "JSON: `{ exercise_id, exercise, included: [{ edge_id, entity_id }], warnings }`.",
-      "return_shape": "{ exercise_id, exercise, included: [{ edge_id, entity_id }], warnings }",
+      "returns": "JSON: `{ exercise_id, exercise, included: [{ edge_id, entity_id, edge_type }], warnings }`\n(the shared cross-surface envelope; identical to CLI `apply --json`).",
+      "return_shape": "{ exercise_id, exercise, included: [{ edge_id, entity_id, edge_type }], warnings }",
+      "return_notes": [
+        "(the shared cross-surface envelope; identical to CLI `apply --json`)."
+      ],
       "atomicity": "atomic."
     },
     {
@@ -2191,7 +2194,7 @@
         "inspect",
         "validate_graph"
       ],
-      "source": "src/tools/spec.ts:1440",
+      "source": "src/tools/spec.ts:1463",
       "symbol": "getAntiPattern",
       "returns": "JSON: `UPGCuratedAntiPattern`",
       "return_notes": [
@@ -2320,7 +2323,7 @@
         "list_domains",
         "get_domain_guide"
       ],
-      "source": "src/tools/spec.ts:1896",
+      "source": "src/tools/spec.ts:1919",
       "symbol": "getDomainRing",
       "returns": "JSON: the full `UPGDomainRing` record.",
       "return_notes": [
@@ -2361,7 +2364,7 @@
         "list_edge_migrations",
         "rename_edge_type"
       ],
-      "source": "src/tools/spec.ts:892",
+      "source": "src/tools/spec.ts:915",
       "symbol": "getEdgeType",
       "returns": "JSON: `{ type, forward_verb, reverse_verb, classification, source_type, target_type }`",
       "return_shape": "{ type, forward_verb, reverse_verb, classification, source_type, target_type }",
@@ -2400,7 +2403,7 @@
         "get_entity_schema",
         "list_type_migrations"
       ],
-      "source": "src/tools/spec.ts:1355",
+      "source": "src/tools/spec.ts:1378",
       "symbol": "getEntityMeta",
       "returns": "JSON: `EntityTypeMeta & { domain_id: string | null }`",
       "return_notes": [
@@ -2441,7 +2444,7 @@
         "get_playbook",
         "get_approach"
       ],
-      "source": "src/tools/spec.ts:829",
+      "source": "src/tools/spec.ts:848",
       "symbol": "getFramework",
       "returns": "JSON: the full `UPGFramework` record.",
       "return_notes": [
@@ -2482,7 +2485,7 @@
         "get_framework",
         "list_entity_types"
       ],
-      "source": "src/tools/spec.ts:1149",
+      "source": "src/tools/spec.ts:1172",
       "symbol": "getLensTool",
       "returns": "JSON: `{ ...UPGLens, visible_types: string[] }`",
       "return_shape": "{...UPGLens, visible_types: string[] }",
@@ -2518,7 +2521,7 @@
         "get_entity_meta",
         "get_entity_schema"
       ],
-      "source": "src/tools/spec.ts:1766",
+      "source": "src/tools/spec.ts:1789",
       "symbol": "getLifecycle",
       "returns": "JSON: the full `UPGLifecycle` record, or a descriptive message.",
       "return_notes": [
@@ -2600,7 +2603,7 @@
         "get_playbook",
         "list_lenses"
       ],
-      "source": "src/tools/spec.ts:951",
+      "source": "src/tools/spec.ts:974",
       "symbol": "getRegion",
       "returns": "JSON: the full `UPGRegion` record.",
       "return_notes": [
@@ -2641,7 +2644,7 @@
         "get_entity_meta",
         "list_entity_types"
       ],
-      "source": "src/tools/spec.ts:973",
+      "source": "src/tools/spec.ts:996",
       "symbol": "getRegionForEntity",
       "returns": "JSON: the full `UPGRegion` record.",
       "return_notes": [
@@ -2672,7 +2675,7 @@
         "list_scales",
         "get_entity_schema"
       ],
-      "source": "src/tools/spec.ts:1812",
+      "source": "src/tools/spec.ts:1835",
       "symbol": "getScale",
       "returns": "JSON: the full `UPGScaleDefinition` record including all points.",
       "return_notes": [
@@ -2703,7 +2706,7 @@
         "list_edge_types",
         "list_regions"
       ],
-      "source": "src/tools/spec.ts:1001",
+      "source": "src/tools/spec.ts:1024",
       "symbol": "getSpecVersion",
       "returns": "JSON: `{ upg_version, markdown_format_version, entity_count, edge_count, domain_count, region_count }`",
       "return_shape": "{ upg_version, markdown_format_version, entity_count, edge_count, domain_count, region_count }",
@@ -2749,7 +2752,7 @@
         "get_entity_meta",
         "list_frameworks"
       ],
-      "source": "src/tools/spec.ts:1217",
+      "source": "src/tools/spec.ts:1240",
       "symbol": "getTypeLabel",
       "returns": "JSON: `{ ...UPGTypeLabel, resolved_label: string }`",
       "return_shape": "{...UPGTypeLabel, resolved_label: string }",
@@ -2788,7 +2791,7 @@
         "get_entity_meta",
         "create_node"
       ],
-      "source": "src/tools/spec.ts:1247",
+      "source": "src/tools/spec.ts:1270",
       "symbol": "getValidChildrenTool",
       "returns": "JSON: `{ parent_type, valid_children: string[] }`",
       "return_shape": "{ parent_type, valid_children: string[] }",
@@ -2891,7 +2894,7 @@
         "inspect",
         "get_domain_guide"
       ],
-      "source": "src/tools/spec.ts:1398",
+      "source": "src/tools/spec.ts:1421",
       "symbol": "listAntiPatterns",
       "returns": "JSON: `{ total, count, next_cursor?, anti_patterns: UPGCuratedAntiPattern[] }`",
       "return_shape": "{ total, count, next_cursor?, anti_patterns: UPGCuratedAntiPattern[] }",
@@ -2992,7 +2995,7 @@
         "list_domains",
         "list_anti_patterns"
       ],
-      "source": "src/tools/spec.ts:1487",
+      "source": "src/tools/spec.ts:1510",
       "symbol": "listBenchmarks",
       "returns": "JSON: `{ kind, total, count, benchmarks: ... }`",
       "return_shape": "{ kind, total, count, benchmarks:... }",
@@ -3020,7 +3023,7 @@
         "list_portfolio_cross_edges",
         "migrate_cross_edges"
       ],
-      "source": "src/tools/spec.ts:1087",
+      "source": "src/tools/spec.ts:1110",
       "symbol": "listCrossEdgeTypes",
       "returns": "JSON: `{ count, types: readonly UPGCrossEdgeType[] }`",
       "return_shape": "{ count, types: readonly UPGCrossEdgeType[] }",
@@ -3048,7 +3051,7 @@
         "list_domains",
         "get_domain_guide"
       ],
-      "source": "src/tools/spec.ts:1875",
+      "source": "src/tools/spec.ts:1898",
       "symbol": "listDomainRings",
       "returns": "JSON: `{ rings: UPGDomainRing[], total: number }`",
       "return_shape": "{ rings: UPGDomainRing[], total: number }",
@@ -3118,7 +3121,7 @@
         "list_edge_types",
         "validate_graph"
       ],
-      "source": "src/tools/spec.ts:1659",
+      "source": "src/tools/spec.ts:1682",
       "symbol": "listEdgeMigrations",
       "returns": "JSON: `{ migrations: [{ kind, from, to?, since }], total: number }`",
       "return_shape": "{ migrations: [{ kind, from, to?, since }], total: number }",
@@ -3157,7 +3160,7 @@
         "list_edge_migrations",
         "create_edge"
       ],
-      "source": "src/tools/spec.ts:873",
+      "source": "src/tools/spec.ts:896",
       "symbol": "listEdgeTypes",
       "returns": "JSON: `{ count, edges: Array<{ type, forward_verb, reverse_verb, classification, source_type, target_type }> }`",
       "return_shape": "{ count, edges: Array<{ type, forward_verb, reverse_verb, classification, source_type, target_type }> }",
@@ -3215,7 +3218,7 @@
         "list_type_migrations",
         "list_domains"
       ],
-      "source": "src/tools/spec.ts:1299",
+      "source": "src/tools/spec.ts:1322",
       "symbol": "listEntityTypes",
       "returns": "JSON: `{ total, count, next_cursor?, types: Array<EntityTypeMeta & { domain_id: string | null }> }`",
       "return_shape": "{ total, count, next_cursor?, types: Array<EntityTypeMeta & { domain_id: string | null }> }",
@@ -3242,7 +3245,7 @@
         "list_frameworks",
         "list_framework_structure_patterns"
       ],
-      "source": "src/tools/spec.ts:1831",
+      "source": "src/tools/spec.ts:1854",
       "symbol": "listFrameworkCategories",
       "returns": "JSON: `{ categories: string[], total: number }`",
       "return_shape": "{ categories: string[], total: number }",
@@ -3270,7 +3273,7 @@
         "list_framework_categories",
         "get_framework"
       ],
-      "source": "src/tools/spec.ts:1852",
+      "source": "src/tools/spec.ts:1875",
       "symbol": "listFrameworkStructurePatterns",
       "returns": "JSON: `{ patterns: string[], total: number }`",
       "return_shape": "{ patterns: string[], total: number }",
@@ -3278,7 +3281,7 @@
     },
     {
       "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.",
       "domain": "spec",
       "inputSchema": {
         "type": "object",
@@ -3313,10 +3316,10 @@
         "prioritise",
         "list_approaches"
       ],
-      "source": "src/tools/spec.ts:793",
+      "source": "src/tools/spec.ts:798",
       "symbol": "listFrameworks",
-      "returns": "JSON: `{ total, count, next_cursor?, frameworks: UPGFramework[] }`",
-      "return_shape": "{ total, count, next_cursor?, frameworks: UPGFramework[] }",
+      "returns": "JSON: `{ total, count, next_cursor?, frameworks: Array<{ id, name, category, description, tags, approach_ids, structure_pattern }> }`",
+      "return_shape": "{ total, count, next_cursor?, frameworks: Array<{ id, name, category, description, tags, approach_ids, structure_pattern }> }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -3342,7 +3345,7 @@
         "list_playbooks",
         "list_frameworks"
       ],
-      "source": "src/tools/spec.ts:1116",
+      "source": "src/tools/spec.ts:1139",
       "symbol": "listLenses",
       "returns": "JSON: `{ count, lenses: Array<{ id, name, description, icon, audience, perspective, framework_id?, playbook_id?, visible_domain_count, intelligence_prompt_count }> }`",
       "return_shape": "{ count, lenses: Array<{ id, name, description, icon, audience, perspective, framework_id?, playbook_id?, visible_domain_count, intelligence_prompt_count }> }",
@@ -3379,7 +3382,7 @@
         "list_entity_types",
         "get_entity_meta"
       ],
-      "source": "src/tools/spec.ts:1724",
+      "source": "src/tools/spec.ts:1747",
       "symbol": "listLifecycles",
       "returns": "JSON: `{ lifecycles, total, free_types: string[], planned_types: string[] }`",
       "return_shape": "{ lifecycles, total, free_types: string[], planned_types: string[] }",
@@ -3450,7 +3453,7 @@
         "list_domain_rings",
         "create_product"
       ],
-      "source": "src/tools/spec.ts:1595",
+      "source": "src/tools/spec.ts:1618",
       "symbol": "listProductStages",
       "returns": "JSON: `{ count, stages: readonly UPGProductStage[] }`",
       "return_shape": "{ count, stages: readonly UPGProductStage[] }",
@@ -3479,7 +3482,7 @@
         "list_domains",
         "list_playbooks"
       ],
-      "source": "src/tools/spec.ts:919",
+      "source": "src/tools/spec.ts:942",
       "symbol": "listRegions",
       "returns": "JSON: `{ count, regions: Array<{ id, label, order, shape, mental_model, anchor_type, composes_atomic_domains, entity_count, intra_edge_count, boundary_edge_count }> }`",
       "return_shape": "{ count, regions: Array<{ id, label, order, shape, mental_model, anchor_type, composes_atomic_domains, entity_count, intra_edge_count, boundary_edge_count }> }",
@@ -3506,7 +3509,7 @@
         "get_scale",
         "get_entity_schema"
       ],
-      "source": "src/tools/spec.ts:1797",
+      "source": "src/tools/spec.ts:1820",
       "symbol": "listScales",
       "returns": "JSON: `{ scales: UPGScaleDefinition[], total: number }`",
       "return_shape": "{ scales: UPGScaleDefinition[], total: number }",
@@ -3535,7 +3538,7 @@
         "migrate_type",
         "validate_graph"
       ],
-      "source": "src/tools/spec.ts:1696",
+      "source": "src/tools/spec.ts:1719",
       "symbol": "listSplitMigrations",
       "returns": "JSON: `{ splits: [...], total: number }`",
       "return_shape": "{ splits: [...], total: number }",
@@ -3572,7 +3575,7 @@
         "list_entity_types",
         "get_entity_meta"
       ],
-      "source": "src/tools/spec.ts:1182",
+      "source": "src/tools/spec.ts:1205",
       "symbol": "listTypeLabels",
       "returns": "JSON: `{ total, count, next_cursor?, labels: UPGTypeLabel[] }`",
       "return_shape": "{ total, count, next_cursor?, labels: UPGTypeLabel[] }",
@@ -3608,7 +3611,7 @@
         "validate_graph",
         "list_entity_types"
       ],
-      "source": "src/tools/spec.ts:1628",
+      "source": "src/tools/spec.ts:1651",
       "symbol": "listTypeMigrations",
       "returns": "JSON: `{ migrations: [{ from, to, since }], total: number }`",
       "return_shape": "{ migrations: [{ from, to, since }], total: number }",
@@ -3794,7 +3797,7 @@
         "create_edge",
         "trace"
       ],
-      "source": "src/tools/spec.ts:1055",
+      "source": "src/tools/spec.ts:1078",
       "symbol": "resolveEdgeForPair",
       "returns": "JSON: `{ source_type, target_type, edge_type: string | null,\nanchor_hint?, alternate_anchors?, adjacent_edges? }`",
       "return_shape": "{ source_type, target_type, edge_type: string | null, anchor_hint?, alternate_anchors?, adjacent_edges? }",
@@ -3838,7 +3841,7 @@
       "see": [
         "apply_framework"
       ],
-      "source": "src/tools/frameworks.ts:63",
+      "source": "src/tools/frameworks.ts:55",
       "symbol": "scoreEntity",
       "returns": "JSON: `{ edge, warnings }`.",
       "return_shape": "{ edge, warnings }",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unified-product-graph/mcp-server",
-  "version": "0.8.6",
+  "version": "0.8.7",
   "description": "Local MCP server for .upg files. Read and write product knowledge graphs offline.",
   "license": "MIT",
   "author": "The Product Creator <hello@theproductcreator.com>",
@@ -45,6 +45,7 @@
     "generate-tools:check": "tsx scripts/generate-tool-reference.ts --check",
     "test": "vitest run",
     "test:watch": "vitest",
+    "smoke": "node scripts/upg-smoke.mjs --file test-fixtures/sample.upg",
     "lint": "eslint src/",
     "type-check": "tsc --noEmit",
     "prepublishOnly": "npm run build"

package/skills/upg-prioritise/SKILL.md

@@ -20,7 +20,8 @@ This is the home of the **Prioritise** approach. Where Inspect tells you *what's
 Use the `mcp__unified-product-graph__*` MCP tools:
 - **Read candidates:** `list_nodes`, `search_nodes`, `get_node`, `get_product_context`
 - **Approach + frameworks:** `get_approach({ approach_id: "prioritise" })`, `get_framework({ framework_id: "..." })`
-- **Capture decisions (optional):** `create_node`, `update_node`, `create_edge`
+- **Run + record a framework (the result lives on the graph):** `apply_framework` (creates the exercise and pulls candidates in), `score_entity` (records each candidate's result on its edge). On the CLI: `upg apply <framework> [ids...]`, `upg score <exercise> <entity> --data '{...}'`, and `upg show <exercise>` to read the scores back.
+- **Capture a decision (optional):** `create_node`, `update_node`, `create_edge`
 
 ## The Prioritisation Frameworks
 
@@ -152,18 +153,32 @@ Always add a one-sentence interpretation below the output: what does the ranking
 
 ### Step 5: Capture the Results
 
-Prioritisation that stays in a conversation dies. After presenting the results, ask:
+Prioritisation that stays in a conversation dies. The scoring run you just
+facilitated is itself a first-class object: a **framework exercise**. Running a
+framework over a set of candidates creates a `framework_exercise` node, and each
+candidate's result is recorded on an `includes` edge from the exercise to that
+entity. The score lives on the **edge**, not the candidate node, so the same
+feature can be a "must" in one exercise and a "could" in another, and the entity
+stays clean and queryable.
 
-> **What do you want to capture from this?**
+Record the run (confirm before writing):
 
-Common patterns and where they go:
+- **MCP:** `apply_framework({ framework_id, entity_ids, title })` to create the
+  exercise and pull the candidates in, then `score_entity({ exercise_id,
+  entity_id, values })` per candidate. `values` is the result you computed, e.g.
+  `{ "moscow": "must" }` or `{ "reach": 4, "impact": 5, "confidence": 3, "effort": 2 }`.
+- **CLI:** `upg apply <framework> <id...> --title "..."`, then
+  `upg score <exercise> <entity> --data '{...}'`; read it back with
+  `upg show <exercise>`.
+
+You can also capture the *decision* the ranking led to, which is distinct from the
+scores themselves:
 
 | What to capture | How |
 |-----------------|-----|
-| A prioritisation decision (chosen framework + top-ranked candidate) | `create_node` with type `decision`, link to candidates |
-| An updated `priority` field on existing nodes | `update_node` on each candidate |
-| A now-explicit "Won't do" item | `create_node` with type `decision`, note the rationale for deferral |
-| The full scoring run, for reference | Add as a `note` field on a `decision` node |
+| The scoring run (every candidate's result) | `apply_framework` + `score_entity` (above) |
+| A prioritisation decision (chosen framework + what you will do) | `create_node` type `decision`, linked to the exercise and the top candidates |
+| A now-explicit "Won't do" item | `create_node` type `decision`, note the rationale for deferral |
 
 Always confirm before writing. Never silently mutate graph nodes.