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

package/dist/tools-manifest.json

@@ -1,8 +1,8 @@
 {
   "schema_version": "2",
   "package": "@unified-product-graph/mcp-server",
-  "package_version": "0.8.2",
-  "tool_count": 94,
+  "package_version": "0.8.4",
+  "tool_count": 96,
   "domains": [
     "context",
     "nodes",
@@ -1135,7 +1135,7 @@
       "see": [
         "create_edge"
       ],
-      "source": "src/tools/edges.ts:209",
+      "source": "src/tools/edges.ts:210",
       "symbol": "batchCreateEdges",
       "returns": "JSON: `{ created, count }`.",
       "return_shape": "{ created, count }",
@@ -1174,7 +1174,7 @@
       "see": [
         "delete_edge"
       ],
-      "source": "src/tools/edges.ts:297",
+      "source": "src/tools/edges.ts:298",
       "symbol": "batchDeleteEdges",
       "returns": "JSON: `{ deleted, count }`.",
       "return_shape": "{ deleted, count }",
@@ -1225,7 +1225,7 @@
       "see": [
         "move_node"
       ],
-      "source": "src/tools/edges.ts:177",
+      "source": "src/tools/edges.ts:178",
       "symbol": "batchMoveNodes",
       "returns": "JSON: `{ moves, warnings? }` mirroring the per-move result of\n`move_node`.",
       "return_shape": "{ moves, warnings? }",
@@ -1260,6 +1260,10 @@
           "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": [
@@ -1313,7 +1317,7 @@
         "export_edges",
         "repair_dangling_edges"
       ],
-      "source": "src/tools/edges.ts:122",
+      "source": "src/tools/edges.ts:123",
       "symbol": "deleteEdge",
       "returns": "JSON: the removed edge object.",
       "return_notes": [
@@ -1364,7 +1368,7 @@
         "query",
         "list_nodes"
       ],
-      "source": "src/tools/edges.ts:407",
+      "source": "src/tools/edges.ts:408",
       "symbol": "exportEdges",
       "returns": "JSON: `{ edges, total, offset, limit, types?, _hash }`. Each edge\ncarries `{ id, source, target, type, mapping_confidence? }`.",
       "return_shape": "{ edges, total, offset, limit, types?, _hash }",
@@ -1410,7 +1414,7 @@
       "see": [
         "batch_move_nodes"
       ],
-      "source": "src/tools/edges.ts:149",
+      "source": "src/tools/edges.ts:150",
       "symbol": "moveNode",
       "returns": "JSON: `{ moved: true, node_id, new_parent_id, new_edge,\nold_edge_id?, warning? }`. The internal `removed_edge` field is stripped\nfrom the wire payload.",
       "return_shape": "{ moved: true, node_id, new_parent_id, new_edge, old_edge_id?, warning? }",
@@ -1457,7 +1461,7 @@
         "migrate_type",
         "export_edges"
       ],
-      "source": "src/tools/edges.ts:494",
+      "source": "src/tools/edges.ts:495",
       "symbol": "renameEdgeType",
       "returns": "JSON: with `dry_run: true`, `{ dry_run, from, to, flip, would_rename, sample }`.\nWith `dry_run: false`, `{ dry_run, from, to, flip, renamed, ids }`.",
       "return_notes": [
@@ -1505,7 +1509,7 @@
         "Dropping `corrupt` edges is irreversible. The integrity stamp is\nre-computed on next save; a subsequent reload won't bring them back."
       ],
       "see": [],
-      "source": "src/tools/edges.ts:341",
+      "source": "src/tools/edges.ts:342",
       "symbol": "repairDanglingEdges",
       "returns": "JSON: `{ dry_run, report, dropped?, remaining? }`. `report` is\nthe pre-action classification. With `dry_run: false`, `dropped` is the\ncount of edges removed and `remaining` is the post-action report.",
       "return_shape": "{ dry_run, report, dropped?, remaining? }",
@@ -2109,6 +2113,51 @@
       "return_shape": "{ type, alias_of?, domain, expected_properties, edges_out, edges_in, phases?, initial_phase?, terminal_phases?, domain_guide? }",
       "atomicity": "atomic (read-only)"
     },
+    {
+      "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 }.",
+      "domain": "spec",
+      "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": [
+          "framework_id"
+        ]
+      },
+      "throws": [
+        "textError on a missing/unknown framework_id."
+      ],
+      "examples": [],
+      "warnings": [],
+      "see": [
+        "score_entity"
+      ],
+      "source": "src/tools/frameworks.ts:22",
+      "symbol": "applyFramework",
+      "returns": "JSON: `{ exercise_id, exercise, included: [{ edge_id, entity_id }], warnings }`.",
+      "return_shape": "{ exercise_id, exercise, included: [{ edge_id, entity_id }], warnings }",
+      "atomicity": "atomic."
+    },
     {
       "name": "get_anti_pattern",
       "description": "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.",
@@ -2142,7 +2191,7 @@
         "inspect",
         "validate_graph"
       ],
-      "source": "src/tools/spec.ts:1434",
+      "source": "src/tools/spec.ts:1440",
       "symbol": "getAntiPattern",
       "returns": "JSON: `UPGCuratedAntiPattern`",
       "return_notes": [
@@ -2233,7 +2282,7 @@
         "list_anti_patterns",
         "get_playbook"
       ],
-      "source": "src/tools/spec.ts:755",
+      "source": "src/tools/spec.ts:761",
       "symbol": "getDomainGuide",
       "returns": "JSON: the full `UPGDomainUsageGuide` record.",
       "return_notes": [
@@ -2271,7 +2320,7 @@
         "list_domains",
         "get_domain_guide"
       ],
-      "source": "src/tools/spec.ts:1890",
+      "source": "src/tools/spec.ts:1896",
       "symbol": "getDomainRing",
       "returns": "JSON: the full `UPGDomainRing` record.",
       "return_notes": [
@@ -2312,7 +2361,7 @@
         "list_edge_migrations",
         "rename_edge_type"
       ],
-      "source": "src/tools/spec.ts:886",
+      "source": "src/tools/spec.ts:892",
       "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 }",
@@ -2351,7 +2400,7 @@
         "get_entity_schema",
         "list_type_migrations"
       ],
-      "source": "src/tools/spec.ts:1349",
+      "source": "src/tools/spec.ts:1355",
       "symbol": "getEntityMeta",
       "returns": "JSON: `EntityTypeMeta & { domain_id: string | null }`",
       "return_notes": [
@@ -2392,7 +2441,7 @@
         "get_playbook",
         "get_approach"
       ],
-      "source": "src/tools/spec.ts:823",
+      "source": "src/tools/spec.ts:829",
       "symbol": "getFramework",
       "returns": "JSON: the full `UPGFramework` record.",
       "return_notes": [
@@ -2433,7 +2482,7 @@
         "get_framework",
         "list_entity_types"
       ],
-      "source": "src/tools/spec.ts:1143",
+      "source": "src/tools/spec.ts:1149",
       "symbol": "getLensTool",
       "returns": "JSON: `{ ...UPGLens, visible_types: string[] }`",
       "return_shape": "{...UPGLens, visible_types: string[] }",
@@ -2469,7 +2518,7 @@
         "get_entity_meta",
         "get_entity_schema"
       ],
-      "source": "src/tools/spec.ts:1760",
+      "source": "src/tools/spec.ts:1766",
       "symbol": "getLifecycle",
       "returns": "JSON: the full `UPGLifecycle` record, or a descriptive message.",
       "return_notes": [
@@ -2551,7 +2600,7 @@
         "get_playbook",
         "list_lenses"
       ],
-      "source": "src/tools/spec.ts:945",
+      "source": "src/tools/spec.ts:951",
       "symbol": "getRegion",
       "returns": "JSON: the full `UPGRegion` record.",
       "return_notes": [
@@ -2592,7 +2641,7 @@
         "get_entity_meta",
         "list_entity_types"
       ],
-      "source": "src/tools/spec.ts:967",
+      "source": "src/tools/spec.ts:973",
       "symbol": "getRegionForEntity",
       "returns": "JSON: the full `UPGRegion` record.",
       "return_notes": [
@@ -2623,7 +2672,7 @@
         "list_scales",
         "get_entity_schema"
       ],
-      "source": "src/tools/spec.ts:1806",
+      "source": "src/tools/spec.ts:1812",
       "symbol": "getScale",
       "returns": "JSON: the full `UPGScaleDefinition` record including all points.",
       "return_notes": [
@@ -2654,7 +2703,7 @@
         "list_edge_types",
         "list_regions"
       ],
-      "source": "src/tools/spec.ts:995",
+      "source": "src/tools/spec.ts:1001",
       "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 }",
@@ -2700,7 +2749,7 @@
         "get_entity_meta",
         "list_frameworks"
       ],
-      "source": "src/tools/spec.ts:1211",
+      "source": "src/tools/spec.ts:1217",
       "symbol": "getTypeLabel",
       "returns": "JSON: `{ ...UPGTypeLabel, resolved_label: string }`",
       "return_shape": "{...UPGTypeLabel, resolved_label: string }",
@@ -2739,7 +2788,7 @@
         "get_entity_meta",
         "create_node"
       ],
-      "source": "src/tools/spec.ts:1241",
+      "source": "src/tools/spec.ts:1247",
       "symbol": "getValidChildrenTool",
       "returns": "JSON: `{ parent_type, valid_children: string[] }`",
       "return_shape": "{ parent_type, valid_children: string[] }",
@@ -2842,7 +2891,7 @@
         "inspect",
         "get_domain_guide"
       ],
-      "source": "src/tools/spec.ts:1392",
+      "source": "src/tools/spec.ts:1398",
       "symbol": "listAntiPatterns",
       "returns": "JSON: `{ total, count, next_cursor?, anti_patterns: UPGCuratedAntiPattern[] }`",
       "return_shape": "{ total, count, next_cursor?, anti_patterns: UPGCuratedAntiPattern[] }",
@@ -2943,7 +2992,7 @@
         "list_domains",
         "list_anti_patterns"
       ],
-      "source": "src/tools/spec.ts:1481",
+      "source": "src/tools/spec.ts:1487",
       "symbol": "listBenchmarks",
       "returns": "JSON: `{ kind, total, count, benchmarks: ... }`",
       "return_shape": "{ kind, total, count, benchmarks:... }",
@@ -2971,7 +3020,7 @@
         "list_portfolio_cross_edges",
         "migrate_cross_edges"
       ],
-      "source": "src/tools/spec.ts:1081",
+      "source": "src/tools/spec.ts:1087",
       "symbol": "listCrossEdgeTypes",
       "returns": "JSON: `{ count, types: readonly UPGCrossEdgeType[] }`",
       "return_shape": "{ count, types: readonly UPGCrossEdgeType[] }",
@@ -2999,7 +3048,7 @@
         "list_domains",
         "get_domain_guide"
       ],
-      "source": "src/tools/spec.ts:1869",
+      "source": "src/tools/spec.ts:1875",
       "symbol": "listDomainRings",
       "returns": "JSON: `{ rings: UPGDomainRing[], total: number }`",
       "return_shape": "{ rings: UPGDomainRing[], total: number }",
@@ -3034,7 +3083,7 @@
         "list_regions",
         "list_entity_types"
       ],
-      "source": "src/tools/spec.ts:720",
+      "source": "src/tools/spec.ts:726",
       "symbol": "listDomains",
       "returns": "JSON: `{ count, domains: Array<{ domain_id, anchor_entity, creation_sequence } | { domain_id, label, description, types, has_guide }> }`",
       "return_shape": "{ count, domains: Array<{ domain_id, anchor_entity, creation_sequence } | { domain_id, label, description, types, has_guide }> }",
@@ -3069,7 +3118,7 @@
         "list_edge_types",
         "validate_graph"
       ],
-      "source": "src/tools/spec.ts:1653",
+      "source": "src/tools/spec.ts:1659",
       "symbol": "listEdgeMigrations",
       "returns": "JSON: `{ migrations: [{ kind, from, to?, since }], total: number }`",
       "return_shape": "{ migrations: [{ kind, from, to?, since }], total: number }",
@@ -3108,7 +3157,7 @@
         "list_edge_migrations",
         "create_edge"
       ],
-      "source": "src/tools/spec.ts:867",
+      "source": "src/tools/spec.ts:873",
       "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 }> }",
@@ -3166,7 +3215,7 @@
         "list_type_migrations",
         "list_domains"
       ],
-      "source": "src/tools/spec.ts:1293",
+      "source": "src/tools/spec.ts:1299",
       "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 }> }",
@@ -3193,7 +3242,7 @@
         "list_frameworks",
         "list_framework_structure_patterns"
       ],
-      "source": "src/tools/spec.ts:1825",
+      "source": "src/tools/spec.ts:1831",
       "symbol": "listFrameworkCategories",
       "returns": "JSON: `{ categories: string[], total: number }`",
       "return_shape": "{ categories: string[], total: number }",
@@ -3221,7 +3270,7 @@
         "list_framework_categories",
         "get_framework"
       ],
-      "source": "src/tools/spec.ts:1846",
+      "source": "src/tools/spec.ts:1852",
       "symbol": "listFrameworkStructurePatterns",
       "returns": "JSON: `{ patterns: string[], total: number }`",
       "return_shape": "{ patterns: string[], total: number }",
@@ -3264,7 +3313,7 @@
         "prioritise",
         "list_approaches"
       ],
-      "source": "src/tools/spec.ts:787",
+      "source": "src/tools/spec.ts:793",
       "symbol": "listFrameworks",
       "returns": "JSON: `{ total, count, next_cursor?, frameworks: UPGFramework[] }`",
       "return_shape": "{ total, count, next_cursor?, frameworks: UPGFramework[] }",
@@ -3293,7 +3342,7 @@
         "list_playbooks",
         "list_frameworks"
       ],
-      "source": "src/tools/spec.ts:1110",
+      "source": "src/tools/spec.ts:1116",
       "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 }> }",
@@ -3330,7 +3379,7 @@
         "list_entity_types",
         "get_entity_meta"
       ],
-      "source": "src/tools/spec.ts:1718",
+      "source": "src/tools/spec.ts:1724",
       "symbol": "listLifecycles",
       "returns": "JSON: `{ lifecycles, total, free_types: string[], planned_types: string[] }`",
       "return_shape": "{ lifecycles, total, free_types: string[], planned_types: string[] }",
@@ -3401,7 +3450,7 @@
         "list_domain_rings",
         "create_product"
       ],
-      "source": "src/tools/spec.ts:1589",
+      "source": "src/tools/spec.ts:1595",
       "symbol": "listProductStages",
       "returns": "JSON: `{ count, stages: readonly UPGProductStage[] }`",
       "return_shape": "{ count, stages: readonly UPGProductStage[] }",
@@ -3430,7 +3479,7 @@
         "list_domains",
         "list_playbooks"
       ],
-      "source": "src/tools/spec.ts:913",
+      "source": "src/tools/spec.ts:919",
       "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 }> }",
@@ -3457,7 +3506,7 @@
         "get_scale",
         "get_entity_schema"
       ],
-      "source": "src/tools/spec.ts:1791",
+      "source": "src/tools/spec.ts:1797",
       "symbol": "listScales",
       "returns": "JSON: `{ scales: UPGScaleDefinition[], total: number }`",
       "return_shape": "{ scales: UPGScaleDefinition[], total: number }",
@@ -3486,7 +3535,7 @@
         "migrate_type",
         "validate_graph"
       ],
-      "source": "src/tools/spec.ts:1690",
+      "source": "src/tools/spec.ts:1696",
       "symbol": "listSplitMigrations",
       "returns": "JSON: `{ splits: [...], total: number }`",
       "return_shape": "{ splits: [...], total: number }",
@@ -3523,7 +3572,7 @@
         "list_entity_types",
         "get_entity_meta"
       ],
-      "source": "src/tools/spec.ts:1176",
+      "source": "src/tools/spec.ts:1182",
       "symbol": "listTypeLabels",
       "returns": "JSON: `{ total, count, next_cursor?, labels: UPGTypeLabel[] }`",
       "return_shape": "{ total, count, next_cursor?, labels: UPGTypeLabel[] }",
@@ -3559,7 +3608,7 @@
         "validate_graph",
         "list_entity_types"
       ],
-      "source": "src/tools/spec.ts:1622",
+      "source": "src/tools/spec.ts:1628",
       "symbol": "listTypeMigrations",
       "returns": "JSON: `{ migrations: [{ from, to, since }], total: number }`",
       "return_shape": "{ migrations: [{ from, to, since }], total: number }",
@@ -3618,15 +3667,18 @@
             "items": {
               "type": "string"
             },
-            "description": "Required. entity_id[] to rank."
+            "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": [
-          "candidates",
           "framework_id"
         ]
       },
@@ -3694,7 +3746,7 @@
         "plan",
         "get_anti_pattern"
       ],
-      "source": "src/tools/spec.ts:670",
+      "source": "src/tools/spec.ts:676",
       "symbol": "reflect",
       "returns": "JSON envelope: `{ approach_id, scope, generated_at, approach,\nparams, prompts, execution_mode: \"execution_v0_4_0\" }`",
       "return_notes": [
@@ -3742,12 +3794,56 @@
         "create_edge",
         "trace"
       ],
-      "source": "src/tools/spec.ts:1049",
+      "source": "src/tools/spec.ts:1055",
       "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? }",
       "atomicity": "atomic (read-only)"
     },
+    {
+      "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 }.",
+      "domain": "spec",
+      "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"
+        ]
+      },
+      "throws": [
+        "textError when the exercise/entity is missing or the node is not a\nframework_exercise."
+      ],
+      "examples": [],
+      "warnings": [],
+      "see": [
+        "apply_framework"
+      ],
+      "source": "src/tools/frameworks.ts:63",
+      "symbol": "scoreEntity",
+      "returns": "JSON: `{ edge, warnings }`.",
+      "return_shape": "{ edge, warnings }",
+      "atomicity": "atomic."
+    },
     {
       "name": "trace",
       "description": "[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\".",
@@ -3801,7 +3897,7 @@
         "plan",
         "prioritise"
       ],
-      "source": "src/tools/spec.ts:607",
+      "source": "src/tools/spec.ts:613",
       "symbol": "trace",
       "returns": "JSON envelope: `{ approach_id, scope, generated_at, approach,\nparams, trail, reached, error?, halted_at_depth?,\nexecution_mode: \"execution_v0_4_0\" }`",
       "return_notes": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unified-product-graph/mcp-server",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "description": "Local MCP server for .upg files. Read and write product knowledge graphs offline.",
   "license": "MIT",
   "author": "The Product Creator <hello@theproductcreator.com>",