Setup

Set up the Unified Product Graph

Install the CLI, create your product graph, wire up the MCP server, and start talking to your AI assistant about your product. Five steps, one binary.

Prerequisites

Before you start

$node -v && npm -v

Node.js 18+ and npm are required. If Node is missing or below 18, install the LTS from nodejs.org and stop here until node -v reports 18 or higher.

Quick start

Five steps to your first graph

1Install the CLI

$npm install -g @unified-product-graph/cli

Verify:

$upg --version

Provides the upg binary. On EACCES / permission errors, do not use sudo: fix your npm prefix (npm config get prefix) or use a Node version manager (nvm, fnm, volta).

A global npm install needs write access to npm’s global prefix (npm config get prefix). If that is a system path you cannot write to, switch to a user-owned Node (nvm/fnm/volta) so -g installs into your home directory, with no sudo required.

2Create your product graph

$upg init --title "My Product" --template blank --yes

Run inside the folder the graph should live in. Writes product.upg to the current directory. --yes is required for non-interactive use; add --force to overwrite. Templates: blank, saas, marketplace, mobile, oss.

3Wire up the MCP server

$upg mcp setup

All projects:

$upg mcp setup --scope user

Writes a standard .mcp.json entry; the server runs on demand via npx, nothing else to install. Default is this project; --scope user makes UPG available in every project.

4Install the /upg-* slash commands

$upg install-skills

All projects:

$upg install-skills --scope user

Brings the full set of /upg-* slash commands (show-tree, check-gaps, show-status, new-discovery, and more) into your AI tool.

5Verify

upg health
upg mcp status

Expected: health reports a valid graph and mcp status shows connected. If it shows disconnected, restart your AI tool so it reloads .mcp.json.

Advanced / self-hostedRun the MCP server yourself with npx, or the Postgres cloud-server with Docker.

What it enables

An agent that can reason over your product

The graph is a file the server reads and writes directly. Watch one conversation move through it:

Read your product's structure: personas, outcomes, opportunities, solutions.

Claude Code · UPG MCP

Start a conversation

Ask anything about your product

“What's in my product graph?”get_product_context

“Add a persona called Solo Product Creator...”create_node

“What opportunities exist for that persona?”search_nodes

The agent picks the right tool and calls it. You just describe what you want.

Not comfortable editing config files? Let your AI assistant set it up for you with a single prompt.

Tools

95 tools across 9 groups

AI agents discover these automatically via the MCP tools/list method. Local and cloud share most signatures; cloud adds collaboration tools.

Context & Session6

Graph overview, session state, product context, and digest tools.

Nodes17

Create, read, update, delete, search, move, batch, and deduplicate nodes.

Edges9

Create, read, delete, export, rename, and resolve edge types.

Areas & Change Log11

Areas, change log, and time-bounded change queries.

Workspace & Portfolios39

Workspace initialisation, product switching, portfolios, and cross-product edges.

Schema1

Entity schemas, valid children, entity metadata, and type labels.

Spec Introspection6

Spec introspection: approaches, playbooks, regions, domains, lenses, frameworks.

Cloud Sync3

Push and pull graph state to/from the UPG cloud.

Validation3

Validate the graph, detect anti-patterns, run structural health checks, and audit skill integrity.

Browse the full tool reference →320 entity types in the spec →

Agent workflows

How agents use the graph

Populate from scratch

Chain persona to job to need to outcome. Every create/update response scores completeness and lists missing fields.

> create persona "Solo Creator"

· create_node → n_a1 · 40%

> add its job, need, outcome

✓ chain created · 4 nodes

Build toward a view

The ontology is the framework. BMC, OKR, OST, GTM each map to a known set of entity types.

> populate a Business Model Canvas

· create_node business_model

· + value_proposition, channel ...

✓ 9 BMC entities

Wire cross-domain

create_edge connects entities across hierarchies; the server infers the edge type from the pair.

> connect value_prop to persona

· create_edge (type inferred)

✓ value_proposition -serves-> persona

Analyse and fill gaps

get_graph_digest finds orphans and counts by type. Fill the gaps through conversation.

> what's floating?

· get_graph_digest

⚠ 3 orphans · 2 outcomes lack metrics

One file, every surface

Your graph, everywhere

The same .upg file powers every surface. Every one speaks UPG.

VS Code ExtensionComing soon

Browse your graph in the sidebar: entity tree, overview, detail panels.

Desktop AppPlanned

The local graph in a native shell, offline-first with a dock icon.

Mobile CompanionPlanned

Capture ideas on the go. Voice-to-graph, quick entity creation.

View source on GitHub →Read the spec →Build an adapter →MIT licensed · free to self-host