MCP vs SDK vs CLI

You: "Start a new product graph called 'My Product'."

Claude: I'll create that for you.
→ create_product { title: "My Product" }
Created ./product.upg.

// The SDK does not auto-create the file yet.
// Use the CLI for the initial scaffold, then UPGClient takes over.

import { UPGClient } from '@unified-product-graph/sdk'
const upg = new UPGClient({ file: './product.upg' })

$ upg init --title "My Product" --single

✓ Created product.upg
✓ Added workspace.json (run `upg products` to list)

You: "Add a feature called 'Dark mode'."

Claude: Done.
→ create_node { type: "feature", title: "Dark mode" }
Created n_Kg19aubWwbwm7V5t.

const { node } = await upg.nodes.create({
  type: 'feature',
  title: 'Dark mode',
})
console.log(node.id)
// n_Kg19aubWwbwm7V5t

$ upg create feature "Dark mode" --file ./product.upg

✓ Created n_Kg19aubWwbwm7V5t (feature)

You: "List all features."

Claude:
→ list_nodes { type: "feature" }
3 features:
  • Dark mode
  • Keyboard shortcuts
  • Offline mode

const { nodes, total } = await upg.nodes.list({ type: 'feature' })

console.log(`${total} features`)
for (const f of nodes) console.log(f.title)

$ upg list --type feature --file ./product.upg

3 features
  n_Kg19aubWwbwm7V5t  Dark mode
  n_8FzqJpHcXr2BvW1n  Keyboard shortcuts
  n_LbVm3sKdYpQwR4Tt  Offline mode

You: "Connect the persona 'Busy Parent' to the job
'Find ten minutes to work out'."

Claude:
→ create_edge {
    source: "n_2Hf…", target: "n_4Mq…"
  }
Created edge: persona_pursues_job.

const edge = await upg.edges.connect(persona.id, job.id)

console.log(edge.type)
// persona_pursues_job  (inferred)

$ upg connect n_2HfGtKqMpLcVbXwR n_4MqRtYpKvBnZxW8j \
       --file ./product.upg

✓ Connected: persona_pursues_job
  n_2HfGtKqMpLcVbXwR → n_4MqRtYpKvBnZxW8j

You: "Find anything about dark mode."

Claude:
→ search_nodes { query: "dark mode" }
Top hits:
  0.92 · feature       · Dark mode
  0.71 · opportunity   · Dark mode opportunity in mobile
  0.43 · hypothesis    · Users prefer dark UI at night

const hits = await upg.search('dark mode', { limit: 5 })

for (const h of hits) {
  console.log(h.score.toFixed(2), h.node.type, h.node.title)
}

$ upg search "dark mode" --file ./product.upg

0.92  feature       Dark mode
0.71  opportunity   Dark mode opportunity in mobile
0.43  hypothesis    Users prefer dark UI at night

You: "How healthy is the graph?"

Claude:
→ get_graph_digest {}
Health: 8/10
142 nodes · 311 edges · 0 orphans.

const { score, digest } = await upg.health()

console.log(score, digest.orphans)
// 8 0

$ upg health --file ./product.upg --min-score 7

Graph health: 8/10
{ nodes: 142, edges: 311, orphans: 0, ... }

# Exits 1 if score < 7 — wire into CI.