@unified-product-graph/mcp-server 0.8.13 → 0.8.15

package/TOOLS.md

@@ -1,14 +1,14 @@
 # UPG MCP Server: Tool Reference
 
-Reference for the 96 tools exposed by `@unified-product-graph/mcp-server`. Generated from JSDoc on `src/tools/*.ts` (do not edit by hand).
+Reference for the 99 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): 5 tools
 - [Nodes](#nodes): 15 tools
 - [Edges](#edges): 9 tools
-- [Areas & Change Log](#areas-change-log): 5 tools
-- [Workspace & Portfolios](#workspace-portfolios): 10 tools
+- [Areas & Change Log](#areas-change-log): 6 tools
+- [Workspace & Portfolios](#workspace-portfolios): 12 tools
 - [Schema](#schema): 1 tool
 - [Spec Introspection](#spec-introspection): 45 tools
 - [Cloud Sync](#cloud-sync): 3 tools
@@ -946,12 +946,39 @@ re-computed on next save; a subsequent reload won't bring them back.
 
 _Product areas, the `.upg-area.json` cwd scoper, and the session change log._
 
+- [`assign_product_to_area`](#assign-product-to-area)
 - [`create_area`](#create-area)
 - [`get_area_context`](#get-area-context)
 - [`get_area_graph`](#get-area-graph)
 - [`get_changes`](#get-changes)
 - [`list_product_areas`](#list-product-areas)
 
+### `assign_product_to_area`
+
+Place an existing product under a product area (adds it to the area's `products[]` in `.upg/portfolio.upg`). Resolves the area against the portfolio document and auto-registers the product on the portfolio registry. Use after `create_product`, or pass `area_id` to `create_product` directly.
+
+**Atomicity:** `atomic (single portfolio.upg flush).`
+
+**Arguments:**
+
+| Name | Type | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `area_id` | string | ✓ | Product area id (from list_product_areas) |
+| `product_id` | string | ✓ | Product id (from create_product / list_local_products) |
+
+**Returns:**
+
+JSON: `{ product_id, container_id, container_kind: "product_area",
+container_title?, already_member, registered }`.
+
+**Throws:**
+
+- textError on a missing workspace, an unknown product, or an unknown
+area id (the message points at list_product_areas / list_local_products).
+
+**See also:** `attach_product_to_portfolio`, `create_product`
+
+
 ### `create_area`
 
 Create a product area entity in the portfolio document (`.upg/portfolio.upg`). Product areas represent the organisational axis (who owns what). Supports nesting via `parent_area_id`. The portfolio document is created on demand.
@@ -966,7 +993,7 @@ flushed in one pass.`
 | `description` | string |  | What this area covers |
 | `owner` | string |  | Person or team that owns this area |
 | `parent_area_id` | string |  | Parent area ID for creating a sub-area |
-| `strategic_priority` | `critical` \| `high` \| `medium` \| `low` |  | Strategic priority of this area |
+| `strategic_priority` | `urgent` \| `high` \| `medium` \| `low` \| `none` |  | Strategic priority of this area (canonical Priority scale) |
 | `title` | string | ✓ | Area name (e.g. "Search", "Payments") |
 
 **Returns:**
@@ -1070,6 +1097,7 @@ parent_area_id?, products? }>, total }`.
 
 _Multi-product discovery, switching, init, cross-product edges._
 
+- [`attach_product_to_portfolio`](#attach-product-to-portfolio)
 - [`create_cross_product_edge`](#create-cross-product-edge)
 - [`create_product`](#create-product)
 - [`get_organization`](#get-organization)
@@ -1080,6 +1108,33 @@ _Multi-product discovery, switching, init, cross-product edges._
 - [`list_portfolios`](#list-portfolios)
 - [`migrate_cross_edges`](#migrate-cross-edges)
 - [`switch_product`](#switch-product)
+- [`update_product`](#update-product)
+
+### `attach_product_to_portfolio`
+
+Place an existing product under a portfolio (adds it to the portfolio's `products[]` in `.upg/portfolio.upg`). Resolves the portfolio against the portfolio document and auto-registers the product on the portfolio registry. Use after `create_product`, or pass `portfolio_id` to `create_product` directly.
+
+**Atomicity:** `atomic (single portfolio.upg flush).`
+
+**Arguments:**
+
+| Name | Type | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `portfolio_id` | string | ✓ | Portfolio id (from list_portfolios) |
+| `product_id` | string | ✓ | Product id (from create_product / list_local_products) |
+
+**Returns:**
+
+JSON: `{ product_id, container_id, container_kind: "portfolio",
+container_title?, already_member, registered }`.
+
+**Throws:**
+
+- textError on a missing workspace, an unknown product, or an unknown
+portfolio id (the message points at list_portfolios / list_local_products).
+
+**See also:** `assign_product_to_area`, `create_product`
+
 
 ### `create_cross_product_edge`
 
@@ -1121,9 +1176,10 @@ portfolio edge are separate mutations.`
 
 | Name | Type | Required | Description |
 | ---- | ---- | -------- | ----------- |
+| `area_id` | string |  | Optional product_area id (resolved against portfolio.upg) to place the new product under. |
 | `description` | string |  | Optional product description |
 | `name` | string | ✓ | Product display title (required, non-empty). |
-| `portfolio_id` | string |  | Optional portfolio node id in the current store. When provided, a `portfolio_contains_product` edge is created in the current graph. |
+| `portfolio_id` | string |  | Optional portfolio id (resolved against portfolio.upg) to place the new product under. A portfolio id that resolves only in the active graph still attaches via an in-graph edge (DEPRECATED; prefer attach_product_to_portfolio). |
 | `slug` | string |  | Optional slug for the .upg filename. Defaults to a slug derived from `name`. Collisions append `-2`, `-3`, … |
 | `stage` | string |  | Product lifecycle stage. See UPGProductStage in @unified-product-graph/core. |
 
@@ -1318,6 +1374,34 @@ before any read/mutation to confirm the active product.
 **See also:** `get_workspace_info`, `list_local_products`, `init_workspace`
 
 
+### `update_product`
+
+Update the product header (`$upg.product`): stage, title, description, health_status, url. The supported way to advance a product's lifecycle stage; it writes the value get_graph_digest reads, without hand-editing the .upg file.
+
+**Atomicity:** `atomic (single flush).`
+
+**Arguments:**
+
+| Name | Type | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `description` | string |  | Product description. |
+| `health_status` | string |  | Product health (free-form, e.g. on_track / at_risk). |
+| `stage` | string |  | Product lifecycle stage (canonical UPGProductStage). |
+| `title` | string |  | Product display title. |
+| `url` | string |  | Product URL. |
+
+**Returns:**
+
+JSON: `{ product, updated: string[] }` (the fields changed).
+
+**Throws:**
+
+- textError when no field is supplied, when there is no product header,
+or when `stage` is non-canonical (same strict validation as create_product).
+
+**See also:** `create_product`
+
+
 ## Schema
 
 _Entity schema introspection. Same constraints the LSP enforces._

package/dist/index.js

@@ -10131,7 +10131,8 @@ var UPG_PROPERTY_SCHEMA = {
   // ProductAreaProperties: ProductArea entity.
   product_area: {
     strategic_priority: { type: "string", enum: ["urgent", "high", "medium", "low", "none"], description: "Strategic priority assigned to this area" },
-    description: { type: "string", description: "Narrative description of what this area covers" }
+    description: { type: "string", description: "Narrative description of what this area covers" },
+    owner: { type: "string", description: "Person or team that owns this area" }
   },
   // ProgramProperties: Program.
   program: {
@@ -24371,7 +24372,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.13";
+var UPG_VERSION = "0.8.15";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();
 var UPG_TYPES_SET = new Set(UPG_TYPES);
@@ -26255,6 +26256,7 @@ import * as path2 from "path";
 import {
   writePortfolioScopedNode as writePortfolioScopedNode2,
   openPortfolioStoreIfExists,
+  assignProductToArea,
   PortfolioRoutingError as PortfolioRoutingError2
 } from "@unified-product-graph/sdk";
 var listProductAreas = async (_args, _ctx) => {
@@ -26269,11 +26271,24 @@ var listProductAreas = async (_args, _ctx) => {
     if (area.description) row.description = area.description;
     if (area.parent_area_id !== void 0) row.parent_area_id = area.parent_area_id;
     if (area.strategic_priority) row.strategic_priority = area.strategic_priority;
+    if (area.owner) row.owner = area.owner;
     if (area.products) row.products = area.products;
     return row;
   });
   return text(JSON.stringify({ areas: result, total: result.length }, null, 2));
 };
+var assignProductToAreaTool = async (args, _ctx) => {
+  const productId = args.product_id;
+  const areaId = args.area_id;
+  if (!productId) return textError("Missing required parameter: product_id");
+  if (!areaId) return textError("Missing required parameter: area_id");
+  try {
+    const result = await assignProductToArea(process.cwd(), { product_id: productId, area_id: areaId });
+    return text(JSON.stringify(result, null, 2));
+  } catch (err) {
+    return textError(err.message);
+  }
+};
 var getAreaGraph = (args, ctx) => {
   const { store } = ctx;
   const areaId = args.area_id;
@@ -26428,6 +26443,7 @@ var createArea = async (args, _ctx) => {
   const properties = {};
   if (args.strategic_priority) properties.strategic_priority = args.strategic_priority;
   if (args.parent_area_id) properties.parent_area_id = args.parent_area_id;
+  if (args.owner) properties.owner = args.owner;
   try {
     const result = await writePortfolioScopedNode2(process.cwd(), {
       type: "product_area",
@@ -26474,10 +26490,12 @@ import {
   resolvePortfolioPath,
   openPortfolioStoreIfExists as openPortfolioStoreIfExists2,
   registerProductOnPortfolio,
-  findProductFileById
+  findProductFileById,
+  attachProductToPortfolio
 } from "@unified-product-graph/sdk";
 import {
   createProduct,
+  updateProduct,
   initWorkspace,
   InvalidProductNameError,
   InvalidProductStageError,
@@ -26645,7 +26663,8 @@ var createProductTool = async (args, ctx) => {
       slug: args.slug,
       description: args.description,
       stage: args.stage,
-      portfolio_id: args.portfolio_id
+      portfolio_id: args.portfolio_id,
+      area_id: args.area_id
     });
     return text(
       JSON.stringify({ message: `Created product: ${result.title}`, ...result }, null, 2)
@@ -26658,6 +26677,31 @@ var createProductTool = async (args, ctx) => {
     return textError(`create_product failed: ${err.message}`);
   }
 };
+var updateProductTool = async (args, ctx) => {
+  const { store } = ctx;
+  try {
+    const result = updateProduct({
+      store,
+      stage: args.stage,
+      title: args.title,
+      description: args.description,
+      health_status: args.health_status,
+      url: args.url
+    });
+    if (result.updated.length === 0) {
+      return textError(
+        "Nothing to update: pass at least one of: stage, title, description, health_status, url."
+      );
+    }
+    await store.flush();
+    return text(
+      JSON.stringify({ message: `Updated product (${result.updated.join(", ")})`, ...result }, null, 2)
+    );
+  } catch (err) {
+    if (err instanceof InvalidProductStageError) return textError(err.message);
+    return textError(`update_product failed: ${err.message}`);
+  }
+};
 var listPortfolios = async (_args, _ctx) => {
   const portfolioStore = await openPortfolioStoreIfExists2(process.cwd());
   if (!portfolioStore) {
@@ -26867,6 +26911,21 @@ var migrateCrossEdges = async (args, ctx) => {
     )
   );
 };
+var attachProductToPortfolioTool = async (args, _ctx) => {
+  const productId = args.product_id;
+  const portfolioId = args.portfolio_id;
+  if (!productId) return textError("Missing required parameter: product_id");
+  if (!portfolioId) return textError("Missing required parameter: portfolio_id");
+  try {
+    const result = await attachProductToPortfolio(process.cwd(), {
+      product_id: productId,
+      portfolio_id: portfolioId
+    });
+    return text(JSON.stringify(result, null, 2));
+  } catch (err) {
+    return textError(err.message);
+  }
+};
 
 // src/tools/schema.ts
 var getEntitySchema = (args, _ctx) => {
@@ -29138,12 +29197,30 @@ var TOOL_DEFINITIONS = [
         },
         portfolio_id: {
           type: "string",
-          description: "Optional portfolio node id in the current store. When provided, a `portfolio_contains_product` edge is created in the current graph."
+          description: "Optional portfolio id (resolved against portfolio.upg) to place the new product under. A portfolio id that resolves only in the active graph still attaches via an in-graph edge (DEPRECATED; prefer attach_product_to_portfolio)."
+        },
+        area_id: {
+          type: "string",
+          description: "Optional product_area id (resolved against portfolio.upg) to place the new product under."
         }
       },
       required: ["name"]
     }
   },
+  {
+    name: "update_product",
+    description: "Update the product header (`$upg.product`): stage, title, description, health_status, url. The supported way to advance a product's lifecycle stage; it writes the value get_graph_digest reads, without hand-editing the .upg file.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        stage: { type: "string", description: "Product lifecycle stage (canonical UPGProductStage)." },
+        title: { type: "string", description: "Product display title." },
+        description: { type: "string", description: "Product description." },
+        health_status: { type: "string", description: "Product health (free-form, e.g. on_track / at_risk)." },
+        url: { type: "string", description: "Product URL." }
+      }
+    }
+  },
   {
     name: "migrate_type",
     description: "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.",
@@ -29840,14 +29917,38 @@ var TOOL_DEFINITIONS = [
         },
         strategic_priority: {
           type: "string",
-          enum: ["critical", "high", "medium", "low"],
-          description: "Strategic priority of this area"
+          enum: ["urgent", "high", "medium", "low", "none"],
+          description: "Strategic priority of this area (canonical Priority scale)"
         },
         owner: { type: "string", description: "Person or team that owns this area" }
       },
       required: ["title"]
     }
   },
+  {
+    name: "assign_product_to_area",
+    description: "Place an existing product under a product area (adds it to the area's `products[]` in `.upg/portfolio.upg`). Resolves the area against the portfolio document and auto-registers the product on the portfolio registry. Use after `create_product`, or pass `area_id` to `create_product` directly.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        product_id: { type: "string", description: "Product id (from create_product / list_local_products)" },
+        area_id: { type: "string", description: "Product area id (from list_product_areas)" }
+      },
+      required: ["product_id", "area_id"]
+    }
+  },
+  {
+    name: "attach_product_to_portfolio",
+    description: "Place an existing product under a portfolio (adds it to the portfolio's `products[]` in `.upg/portfolio.upg`). Resolves the portfolio against the portfolio document and auto-registers the product on the portfolio registry. Use after `create_product`, or pass `portfolio_id` to `create_product` directly.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        product_id: { type: "string", description: "Product id (from create_product / list_local_products)" },
+        portfolio_id: { type: "string", description: "Portfolio id (from list_portfolios)" }
+      },
+      required: ["product_id", "portfolio_id"]
+    }
+  },
   {
     name: "list_portfolios",
     description: "List portfolios from the portfolio document (`.upg/portfolio.upg`). Portfolios represent the strategic axis (where we invest). Returns an empty list when no portfolio document exists yet.",
@@ -29999,6 +30100,7 @@ var HANDLERS = {
   get_workspace_info: getWorkspaceInfo,
   init_workspace: initWorkspaceTool,
   create_product: createProductTool,
+  update_product: updateProductTool,
   migrate_type: migrateType,
   migrate_properties: migrateProperties,
   migrate_status: migrateStatus,
@@ -30054,9 +30156,11 @@ var HANDLERS = {
   skill_audit: skillAudit,
   get_area_context: getAreaContext,
   create_area: createArea,
+  assign_product_to_area: assignProductToAreaTool,
   list_portfolios: listPortfolios,
   get_organization: getOrganization,
   create_cross_product_edge: createCrossProductEdge,
+  attach_product_to_portfolio: attachProductToPortfolioTool,
   list_portfolio_cross_edges: listPortfolioCrossEdges,
   migrate_cross_edges: migrateCrossEdges,
   get_sync_state: getSyncState,