@unified-product-graph/mcp-server 0.7.5 → 0.7.6

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 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.7.6] - 2026-05-30
+
+### Added
+
+- **`start` tool (UPG-525):** a zero-state on-ramp. An empty or barely-started graph gives an agent nothing to plan against; `start` reads the live graph and recommends the first canonical playbook (from `UPG_PLAYBOOKS`) plus the exact `create_node` call for its anchor entity. Young graphs (< 8 non-product nodes) get the first canonical playbook whose anchor isn't present yet; established graphs are routed to `plan` / `inspect` / `get_graph_digest`. 94 tools total.
+
+### Changed
+
+- **`create_node` orphan warning (UPG-525):** when a node lands with no parent and its type sits at position > 0 in its domain's creation sequence (the spec expects it under the domain anchor), the response carries a warning naming the typical parent and the canonical edge. Anchors, roots, and guide-less types never warn.
+- **Tool reference return shapes are now authored-source-derived (UPG-556):** the generator parses each tool's `@returns` prose into a structured `return_shape` / `return_notes` at build time, shipped on the manifest. Fixed a `create_node` `@returns` wrap artifact at source.
+- **Dissolved the singleton `Migrations` and `Skills Introspection` tool-reference sections (UPG-557):** `migrate_status` now groups under Nodes and `skill_audit` under Validation, without moving the source. Reference drops from 11 to 9 domains.
+
 ## [0.6.3] - 2026-05-27
 
 ### Changed

package/TOOLS.md

@@ -1,20 +1,18 @@
 # UPG MCP Server: Tool Reference
 
-Reference for the 93 tools exposed by `@unified-product-graph/mcp-server`. Generated from JSDoc on `src/tools/*.ts` (do not edit by hand).
+Reference for the 94 tools exposed by `@unified-product-graph/mcp-server`. Generated from JSDoc on `src/tools/*.ts` (do not edit by hand).
 
 ## Contents
 
-- [Context & Session](#context-session): 4 tools
-- [Nodes](#nodes): 14 tools
+- [Context & Session](#context-session): 5 tools
+- [Nodes](#nodes): 15 tools
 - [Edges](#edges): 9 tools
 - [Areas & Change Log](#areas-change-log): 5 tools
 - [Workspace & Portfolios](#workspace-portfolios): 10 tools
 - [Schema](#schema): 1 tool
 - [Spec Introspection](#spec-introspection): 43 tools
 - [Cloud Sync](#cloud-sync): 3 tools
-- [Validation](#validation): 2 tools
-- [Migrations](#migrations): 1 tool
-- [Skills Introspection](#skills-introspection): 1 tool
+- [Validation](#validation): 3 tools
 
 ## Context & Session
 
@@ -23,6 +21,7 @@ _Product overview, graph digest, lens-aware session state._
 - [`get_graph_digest`](#get-graph-digest)
 - [`get_product_context`](#get-product-context)
 - [`get_session_context`](#get-session-context)
+- [`start`](#start)
 - [`update_session_context`](#update-session-context)
 
 ### `get_graph_digest`
@@ -116,6 +115,37 @@ dedup rule from prose.
 **See also:** `update_session_context`
 
 
+### `start`
+
+Zero-state on-ramp: "there is nothing here yet, where do I begin?". Reads the live graph and, for an empty or barely-started graph, recommends the first canonical playbook (from UPG_PLAYBOOKS) plus the exact create_node call for its anchor entity. Established graphs are routed to plan / inspect / get_graph_digest instead. Takes no arguments.
+
+**Atomicity:** `atomic (read-only)`
+
+_No arguments._
+
+**Returns:**
+
+JSON: `{ graph_state: "empty" | "young" | "established", product,
+node_count, recommended_playbook?, first_action?, recommendation,
+next_tools }`. `recommended_playbook` and `first_action` are present only
+for empty/young graphs.
+
+**Examples:**
+
+// Input (empty graph):
+{}
+// Output (truncated):
+{
+  "graph_state": "empty",
+  "node_count": 0,
+  "recommended_playbook": { "id": "playbook:users-needs", "name": "Users & Needs", "target_anchor_entity": "persona" },
+  "first_action": { "tool": "create_node", "args": { "type": "persona", "title": "<your first persona>" } },
+  "recommendation": "Your graph is empty. Begin with the \"Users & Needs\" playbook: create your first persona."
+}
+
+**See also:** `plan`, `get_playbook`, `list_playbooks`, `get_graph_digest`
+
+
 ### `update_session_context`
 
 Update session context: register a skill invocation, record a recommendation, set focus area, switch lens, or store custom state for cross-skill coordination.
@@ -145,7 +175,7 @@ new state.
 
 ## Nodes
 
-_Read, search, traverse, mutate, batch, migrate, dedupe._
+_Read, search, traverse, mutate, batch, migrate type/properties/status, dedupe._
 
 - [`batch_create_nodes`](#batch-create-nodes)
 - [`batch_delete_nodes`](#batch-delete-nodes)
@@ -157,6 +187,7 @@ _Read, search, traverse, mutate, batch, migrate, dedupe._
 - [`get_nodes`](#get-nodes)
 - [`list_nodes`](#list-nodes)
 - [`migrate_properties`](#migrate-properties)
+- [`migrate_status`](#migrate-status)
 - [`migrate_type`](#migrate-type)
 - [`query`](#query)
 - [`search_nodes`](#search-nodes)
@@ -262,8 +293,8 @@ Create one entity, optionally with a parent edge. For 3+ entities, use `batch_cr
 JSON: `{ node, edge?, unknown_properties?, warning? }`. The `edge`
 field is present only when `parent_id` was supplied and a canonical
 hierarchy edge could be inferred. `unknown_properties` and `warning` are
-present when the caller passed properties not in the entity's schema
-. Pass `strict: true` to reject unknown properties instead of
+present when the caller passed properties not in the entity's schema.
+Pass `strict: true` to reject unknown properties instead of
 warning. For portfolio-scoped types the response shape is
 `{ node, portfolio_file, written_to, warning? }` where `node` is the
 persisted typed record.
@@ -466,6 +497,40 @@ changes (idempotent on the canonical-properties shape).
 **See also:** `migrate_type`, `validate_graph`, `list_type_migrations`
 
 
+### `migrate_status`
+
+Apply `UPG_STATUS_MIGRATIONS` graph-wide: rewrite legacy lifecycle status values to canonical phase ids. Auto-mode (no filters) selects nodes whose current status is invalid against the entity type's lifecycle and has a registered replacement (the same invariant that drives `validate_graph` lifecycle_drift). Surgical mode (`from_status` + `to_status`) overrides the registry and rewrites every (entity_type?, from_status) match. Nodes with invalid statuses but no registered replacement surface under `skipped_no_migration`. Default `dry_run=true`; pass `dry_run=false` to commit.
+
+**Atomicity:** `per-node. Status writes go through `store.updateNode`
+one at a time. Dry-run is read-only.`
+
+**Arguments:**
+
+| Name | Type | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `dry_run` | boolean |  | Preview changes without applying (default true). Pass false to commit. |
+| `entity_type` | string |  | Optional. Restrict the rewrite to nodes of this canonical entity type (e.g. "service", "feature"). |
+| `from_status` | string |  | Optional. Restrict the rewrite to nodes whose current status equals this exact value. When provided, `to_status` is required and the registry is bypassed. |
+| `to_status` | string |  | Required when `from_status` is provided. The canonical phase id to write. |
+
+**Returns:**
+
+JSON: `MigrateStatusResult`.
+
+**Throws:**
+
+- Returns a textError when `from_status` is provided without
+`to_status`, or when `entity_type` is provided but isn't a string.
+
+**Warnings (non-error surfaces):**
+
+- Default is `dry_run: true`. Pass `dry_run: false` to commit.
+Idempotent on retry; re-running after a successful commit reports
+zero changes (canonical statuses pass the validity check).
+
+**See also:** `migrate_type`, `migrate_properties`, `validate_graph`, `list_lifecycles`
+
+
 ### `migrate_type`
 
 Migrate every entity of one type to another, applying defaults from `UPG_MIGRATIONS`. Three passes commit as one write: (1) node rename, (2) edges through `UPG_EDGE_MIGRATIONS` (catalog-aware renames, direction flips, drops; endpoint guards check post-migration types; uncatalogued edges surface as `unmapped_legacy_edges`), (3) every node through `UPG_PROPERTY_MIGRATIONS` (top-level renames, lifts, drops, self-referential cleanup). Type-specific property rules see the post-rename type.
@@ -2388,9 +2453,10 @@ target an existing one.
 
 ## Validation
 
-_Schema-drift detection and full per-node drift reports._
+_Schema-drift detection, full per-node drift reports, and source-vs-deployed integrity audits of UPG `/upg-*` skills._
 
 - [`get_anti_pattern_violations_for`](#get-anti-pattern-violations-for)
+- [`skill_audit`](#skill-audit)
 - [`validate_graph`](#validate-graph)
 
 ### `get_anti_pattern_violations_for`
@@ -2442,6 +2508,23 @@ per-id matching once `target_entities` carries ids.
 **See also:** `validate_graph`, `list_anti_patterns`, `get_anti_pattern`, `inspect`
 
 
+### `skill_audit`
+
+Audit one or every UPG skill for source-vs-deployed integrity. Use before recommending a skill to confirm `.claude/skills/<name>/SKILL.md` is a symlink to canonical source and the bodies match. When `in_sync: false`, what you read from `packages/upg-mcp-server/skills/` is NOT what the user will experience.
+
+**Atomicity:** `atomic (read-only filesystem stat + read)`
+
+**Arguments:**
+
+| Name | Type | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `name` | string |  | Optional skill name (e.g. "upg-trace"). If omitted, audits every canonical skill. |
+
+**Returns:**
+
+`{ skills: SkillAuditRecord[] }`
+
+
 ### `validate_graph`
 
 Walk the loaded graph and return a per-class, per-node report of schema drift plus anti-pattern violations from `UPG_ANTI_PATTERNS`. Schema-drift classes: non-canonical entity types, non-canonical edge types, top-level fields outside `UPGBaseNode`, invalid status values, self-referential `source_id`/`source_type`, properties matching `UPG_PROPERTY_MIGRATIONS` rules. Anti-patterns: catalog entries that fired against the live graph, sorted high → medium → low. Each entry carries `suggested_migration` (drift) or `remediation` (anti-pattern). Top-level `valid` is true iff drift is empty AND no violations fired. Read-only; pairs with `migrate_type`, `rename_edge_type`, `get_anti_pattern_violations_for`.
@@ -2534,66 +2617,3 @@ pure spec-shape check; `skip_drift: true` for catalog-only.
 
 **See also:** `migrate_type`, `migrate_properties`, `rename_edge_type`, `get_anti_pattern_violations_for`, `list_anti_patterns`, `list_type_migrations`, `list_edge_migrations`, `inspect`
 
-
-## Migrations
-
-_Status value migration across the graph._
-
-- [`migrate_status`](#migrate-status)
-
-### `migrate_status`
-
-Apply `UPG_STATUS_MIGRATIONS` graph-wide: rewrite legacy lifecycle status values to canonical phase ids. Auto-mode (no filters) selects nodes whose current status is invalid against the entity type's lifecycle and has a registered replacement (the same invariant that drives `validate_graph` lifecycle_drift). Surgical mode (`from_status` + `to_status`) overrides the registry and rewrites every (entity_type?, from_status) match. Nodes with invalid statuses but no registered replacement surface under `skipped_no_migration`. Default `dry_run=true`; pass `dry_run=false` to commit.
-
-**Atomicity:** `per-node. Status writes go through `store.updateNode`
-one at a time. Dry-run is read-only.`
-
-**Arguments:**
-
-| Name | Type | Required | Description |
-| ---- | ---- | -------- | ----------- |
-| `dry_run` | boolean |  | Preview changes without applying (default true). Pass false to commit. |
-| `entity_type` | string |  | Optional. Restrict the rewrite to nodes of this canonical entity type (e.g. "service", "feature"). |
-| `from_status` | string |  | Optional. Restrict the rewrite to nodes whose current status equals this exact value. When provided, `to_status` is required and the registry is bypassed. |
-| `to_status` | string |  | Required when `from_status` is provided. The canonical phase id to write. |
-
-**Returns:**
-
-JSON: `MigrateStatusResult`.
-
-**Throws:**
-
-- Returns a textError when `from_status` is provided without
-`to_status`, or when `entity_type` is provided but isn't a string.
-
-**Warnings (non-error surfaces):**
-
-- Default is `dry_run: true`. Pass `dry_run: false` to commit.
-Idempotent on retry; re-running after a successful commit reports
-zero changes (canonical statuses pass the validity check).
-
-**See also:** `migrate_type`, `migrate_properties`, `validate_graph`, `list_lifecycles`
-
-
-## Skills Introspection
-
-_Verify source-vs-deployed integrity of UPG `/upg-*` skills before recommending them._
-
-- [`skill_audit`](#skill-audit)
-
-### `skill_audit`
-
-Audit one or every UPG skill for source-vs-deployed integrity. Use before recommending a skill to confirm `.claude/skills/<name>/SKILL.md` is a symlink to canonical source and the bodies match. When `in_sync: false`, what you read from `packages/upg-mcp-server/skills/` is NOT what the user will experience.
-
-**Atomicity:** `atomic (read-only filesystem stat + read)`
-
-**Arguments:**
-
-| Name | Type | Required | Description |
-| ---- | ---- | -------- | ----------- |
-| `name` | string |  | Optional skill name (e.g. "upg-trace"). If omitted, audits every canonical skill. |
-
-**Returns:**
-
-`{ skills: SkillAuditRecord[] }`
-

package/dist/index.js

@@ -23011,6 +23011,62 @@ var getGraphDigest = (args, ctx) => {
   }
   return text(JSON.stringify({ ...digest, lens: sessionContext.lens, lens_digest: lensDigest, _hash: currentHash }, null, 2));
 };
+var YOUNG_GRAPH_THRESHOLD = 8;
+var start = (_args, ctx) => {
+  const { store } = ctx;
+  const allNodes = store.getAllNodes();
+  const realNodes = allNodes.filter((n) => n.type !== "product");
+  const nodeCount = realNodes.length;
+  const product = store.getProduct();
+  const presentTypes = new Set(allNodes.map((n) => n.type));
+  const productInfo = product ? { title: product.title, stage: product.stage ?? null } : null;
+  const state = nodeCount === 0 ? "empty" : nodeCount < YOUNG_GRAPH_THRESHOLD ? "young" : "established";
+  if (state === "established") {
+    return text(
+      JSON.stringify(
+        {
+          graph_state: state,
+          product: productInfo,
+          node_count: nodeCount,
+          recommendation: `Graph is established (${nodeCount} entities). Use plan for the missing-entities backlog, inspect for issues, and get_graph_digest for health.`,
+          next_tools: ["plan", "inspect", "get_graph_digest"]
+        },
+        null,
+        2
+      )
+    );
+  }
+  const canonicalPlaybooks = UPG_PLAYBOOKS.filter((p) => p.is_canonical === true);
+  const recommend = canonicalPlaybooks.find(
+    (p) => p.target_anchor_entity ? !presentTypes.has(p.target_anchor_entity) : true
+  ) ?? canonicalPlaybooks[0];
+  const response = {
+    graph_state: state,
+    product: productInfo,
+    node_count: nodeCount
+  };
+  if (recommend) {
+    const anchor = recommend.target_anchor_entity;
+    response.recommended_playbook = {
+      id: recommend.id,
+      name: recommend.name,
+      region: recommend.region,
+      target_anchor_entity: anchor ?? null,
+      description: recommend.description
+    };
+    if (anchor) {
+      response.first_action = {
+        tool: "create_node",
+        args: { type: anchor, title: `<your first ${anchor}>` }
+      };
+    }
+    response.recommendation = state === "empty" ? `Your graph is empty. Begin with the "${recommend.name}" playbook${anchor ? `: create your first ${anchor}` : ""}. Open the full sequence with get_playbook("${recommend.id}").` : `You have ${nodeCount} ${nodeCount === 1 ? "entity" : "entities"}. Continue with the "${recommend.name}" playbook${anchor ? `: add a ${anchor}` : ""}. Use plan for the full missing-entities backlog.`;
+  } else {
+    response.recommendation = "No canonical playbooks available. Use plan to see the missing-entities backlog.";
+  }
+  response.next_tools = state === "empty" ? ["get_playbook", "create_node", "list_playbooks"] : ["plan", "get_playbook", "get_graph_digest"];
+  return text(JSON.stringify(response, null, 2));
+};
 var getSessionContext = (_args, ctx) => {
   const { sessionContext } = ctx;
   const recommendationsToAvoid = Array.from(
@@ -23738,6 +23794,21 @@ function buildFirstUseHints(canonicalType) {
   if (edgesOut.length > 0) hints.canonical_edges_out = edgesOut;
   return hints;
 }
+function buildOrphanWarning(canonicalType) {
+  let schema;
+  try {
+    schema = buildEntitySchema(canonicalType);
+  } catch {
+    return void 0;
+  }
+  const guide = schema.domain_guide;
+  if (!guide || guide.position_in_sequence <= 0) return void 0;
+  const anchor = guide.anchor_entity;
+  if (!anchor || anchor === canonicalType) return void 0;
+  const edge = resolveContainmentEdge(anchor, canonicalType);
+  const via = edge ? ` (canonical edge: ${edge})` : "";
+  return `Orphan: created ${canonicalType} with no parent. ${canonicalType} typically attaches under ${anchor}${via}. Pass parent_id on create, or wire it later with create_edge.`;
+}
 var createNode = async (args, ctx) => {
   const { store } = ctx;
   if (!args.type) return textError(`Missing required parameter: type`);
@@ -23804,6 +23875,10 @@ var createNode = async (args, ctx) => {
     const aggregatedWarnings = [];
     if (warning) aggregatedWarnings.push(warning);
     if (lengthWarnings.length > 0) aggregatedWarnings.push(...lengthWarnings);
+    if (!args.parent_id && !result.edge) {
+      const orphanWarning = buildOrphanWarning(result.node.type);
+      if (orphanWarning) aggregatedWarnings.push(orphanWarning);
+    }
     const libWarning = result.warning;
     const combinedWarning = libWarning ? aggregatedWarnings.length > 0 ? `${libWarning} | ${aggregatedWarnings.join(" | ")}` : libWarning : aggregatedWarnings.length > 0 ? aggregatedWarnings.join(" | ") : void 0;
     if (unknown_properties.length > 0 || combinedWarning || hints) {
@@ -26753,6 +26828,14 @@ var TOOL_DEFINITIONS = [
       }
     }
   },
+  {
+    name: "start",
+    description: 'Zero-state on-ramp: "there is nothing here yet, where do I begin?". Reads the live graph and, for an empty or barely-started graph, recommends the first canonical playbook (from UPG_PLAYBOOKS) plus the exact create_node call for its anchor entity. Established graphs are routed to plan / inspect / get_graph_digest instead. Takes no arguments.',
+    inputSchema: {
+      type: "object",
+      properties: {}
+    }
+  },
   {
     name: "list_nodes",
     description: "List entities with filtering, edge inclusion, count-only mode, and pagination. For graph-wide edge enumeration, prefer `export_edges` (flat) or `query` (traversal). `list_nodes(include_edges:true)` is for entity-scoped reads.",
@@ -28052,6 +28135,7 @@ var TOOL_DEFINITIONS = [
 var HANDLERS = {
   get_product_context: getProductContext,
   get_graph_digest: getGraphDigest,
+  start,
   list_nodes: listNodes,
   get_node: getNode,
   get_nodes: getNodes,