@unified-product-graph/cloud-server 0.6.0

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to `@unified-product-graph/cloud-server` are documented in this file.
+
+This package co-versions with `@unified-product-graph/core` and `@unified-product-graph/mcp-server`. One version line covers the spec and both reference implementations.
+
+## 0.6.0 · 2026-05-22 · Launch train alignment
+
+Aligned with `@unified-product-graph/core@0.6.0`. Bumped `@unified-product-graph/core` dep to `^0.6.0`. No cloud-server surface changes — co-versioned for the launch train.
+
+## 0.5.0 · 2026-05-19 · Inaugural public release
+
+First public npm release on the `@unified-product-graph/` scope. Co-versions with `@unified-product-graph/core@0.5.0` and `@unified-product-graph/mcp-server@0.5.0`.
+
+### Highlights
+
+- **91 tools across 14 domains.** Full tool-surface parity with the local `mcp-server` (79 shared) plus 12 cloud-only: collaboration, comments, webhooks, audit-log, cross-product-edge, and Postgres-side analytics.
+- **Spec introspection.** Playbooks, approaches, domain guides, frameworks, edge catalog, regions, lenses, type labels, entity meta, anti-patterns, benchmarks, lifecycles, scales, and migrations catalogues are all queryable as MCP tools.
+- **Approaches.** `plan`, `inspect`, `prioritise`, `trace`, `reflect` ship as definition-lookup handlers; structured execution lands in a follow-on release.
+- **Cross-product edges.** `create_cross_product_edge`, `list_portfolio_cross_edges`, `migrate_cross_edges` for portfolio-level relationships.
+- **Portfolio hierarchy.** `list_portfolios`, `create_area`, `get_area_context`.
+- **Validation and migration.** `validate_graph`, `migrate_type`, `repair_dangling_edges`, `deduplicate_nodes`, `rename_edge_type`, `export_edges`.
+- **Audit trail.** Every write carries actor and timestamp; replay supported via append-only edge tables.
+- **Self-hostable.** Docker-ready, Postgres-backed; bring your own database.
+- **Shared catalog.** Cloud and local both walk `@unified-product-graph/mcp-tooling` for `ToolDefinition`, `resolveEntityType`, `buildEntitySchema`, and atomicity contracts.
+
+### Install
+
+```bash
+npm install -g @unified-product-graph/cloud-server
+upg-cloud-server --database-url postgres://user:pass@localhost/upg
+```
+
+Wire it into your MCP client by pointing at the running server. Database migrations ship with the package; see [README.md](./README.md#database-setup).
+
+### Pairs with
+
+- `@unified-product-graph/core@0.5.0`
+- `@unified-product-graph/mcp-server@0.5.0` (tool-surface parity)
+- `@unified-product-graph/mcp-tooling@0.5.0` (shared catalog and atomicity contracts)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Product Creator
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,169 @@
+# @unified-product-graph/cloud-server
+
+**91 MCP tools across 14 domains, backed by Postgres.** Self-hostable [Model Context Protocol](https://modelcontextprotocol.io) server for the [Unified Product Graph](https://unifiedproductgraph.org).
+
+<!-- badges -->
+<!-- [![npm](https://img.shields.io/npm/v/@unified-product-graph/cloud-server)](https://www.npmjs.com/package/@unified-product-graph/cloud-server) -->
+<!-- [![license](https://img.shields.io/npm/l/@unified-product-graph/cloud-server)](./LICENSE) -->
+
+## What this is
+
+The UPG Cloud Server stores your product graph in Postgres. It exposes graph operations (products, nodes, edges, search, traversal, collaboration, webhooks) as MCP tools that any compatible client (Claude Code, Cursor, etc.) can call.
+
+**Pick this server when you need:**
+
+- **Multi-tenant storage.** One durable store, many products scoped by `product_id`.
+- **Collaboration.** Comments, role-based access (`owner` / `editor` / `viewer`), audit log.
+- **Outbound webhooks.** Fire on node and edge mutations.
+- **A database service** under your UPG stack.
+
+For a single user on a single graph, prefer `@unified-product-graph/mcp-server` plus a `.upg` file: version-controlled, zero infrastructure. Cloud and local share one spec; graphs round-trip between them.
+
+## Quick Start
+
+### Option 1: Docker (recommended)
+
+```bash
+cd docker
+docker compose up -d
+```
+
+This starts Postgres on port `5433` and applies the migrations automatically. The MCP server then connects to it.
+
+### Option 2: Connect to existing Postgres
+
+```bash
+UPG_DATABASE_URL=postgres://user:pass@localhost:5432/mydb npx @unified-product-graph/cloud-server
+```
+
+Run the [migration](#database-setup) first.
+
+### Option 3: MCP config (Claude Code / Cursor)
+
+Add this to your `.claude/settings.json` or MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "upg-cloud": {
+      "command": "npx",
+      "args": ["@unified-product-graph/cloud-server", "--database-url", "postgres://upg:upg@localhost:5433/upg"]
+    }
+  }
+}
+```
+
+> **Naming.** The config key (`"upg-cloud"`) determines the tool prefix your client sees (`mcp__upg-cloud__*`). The server reports itself to the MCP registry as `unified-product-graph-cloud`. Keep `"upg-cloud"` as the key to stay compatible with existing skill playbooks.
+
+## MCP Tools
+
+**91 tools across 14 domains.** Reference: [`TOOLS.md`](./TOOLS.md) (generated from JSDoc by `npm run generate-tools`). The high-level shape:
+
+| Domain | What it covers |
+| ------ | -------------- |
+| Products & Audit | `list_products`, `create_product`, `get_audit_log` |
+| Context & Traversal | `get_product_context`, `get_graph_digest`, `query`, `get_changes`, `trace` |
+| Nodes | CRUD + `get_nodes`, `search_nodes`, `list_nodes`, `move_node`, batch primitives |
+| Edges | `create_edge`, `delete_edge`, `export_edges`, `rename_edge_type`, batch primitives |
+| Areas | `list_product_areas`, `get_area_graph`, `create_area`, `get_area_context` |
+| Portfolios | `create_cross_product_edge`, `list_portfolios`, `list_portfolio_cross_edges`, `migrate_cross_edges` |
+| Schema | `get_entity_schema` (catalog-driven, shared with local) |
+| Validation & Migration | `validate_graph`, `migrate_type`, `repair_dangling_edges`, `deduplicate_nodes` |
+| Collaboration | `add_comment`, `list_comments`, `grant_access`, `list_collaborators` |
+| Analytics | `get_graph_analytics` (Postgres-side aggregator) |
+| Webhooks | `register_webhook`, `list_webhooks`, `remove_webhook` |
+| Spec introspection | playbooks, approaches, domains, frameworks, edge catalog, regions, lenses, type labels, entity meta, anti-patterns, benchmarks, lifecycles, scales |
+| Approaches | `plan`, `inspect`, `prioritise`, `trace`, `reflect` |
+| Migrations catalogue | `list_type_migrations`, `list_edge_migrations`, `list_split_migrations` |
+
+### Parity with `@unified-product-graph/mcp-server`
+
+Cloud has full tool-surface parity with `@unified-product-graph/mcp-server`. Both walk the same catalog, schema, and atomicity contracts via `@unified-product-graph/mcp-tooling`. Cloud adds collaboration, comments, webhooks, audit-log, cross-product-edge, and Postgres-side analytics on top.
+
+## Database Setup
+
+Docker (`docker compose up -d`) runs migrations automatically. To apply manually:
+
+```bash
+psql $UPG_DATABASE_URL -f migrations/001_initial.sql
+```
+
+This creates a `upg` schema with:
+
+- **`upg.products`**: products with title, description, stage
+- **`upg.nodes`**: typed entities (features, personas, decisions, etc.) with full-text search
+- **`upg.edges`**: typed relationships between nodes
+- **`upg.comments`**: comments on nodes
+- **`upg.audit_log`**: change history per product
+- **`upg.collaborators`**: user roles (`owner` / `editor` / `viewer`) per product
+- **`upg.webhooks`**: registered webhook endpoints
+
+All tables include timestamps, cascading deletes, and performance indexes.
+
+## Configuration
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `UPG_DATABASE_URL` | Yes | (none) | Postgres connection string. Can also be passed as `--database-url`. |
+
+```bash
+# Environment variable
+UPG_DATABASE_URL=postgres://upg:upg@localhost:5433/upg npx @unified-product-graph/cloud-server
+
+# CLI flag
+npx @unified-product-graph/cloud-server --database-url postgres://upg:upg@localhost:5433/upg
+```
+
+## Auth model
+
+The server is an **MCP stdio process**. It speaks MCP over stdin/stdout to a single trusted client (Claude Code, Cursor, etc.).
+
+Multi-tenancy is **graph-shaped**:
+
+- Tools take `product_id` and `user_id` arguments explicitly.
+- `grant_access` / `list_collaborators` write to `upg.collaborators` for host-side role checks.
+- Authorisation enforcement (does this `user_id` have `editor` on this `product_id`?) sits with the wrapping layer: a hosted gateway, an authenticated HTTP transport, or a per-tenant Postgres role.
+
+For public self-hosting, front the server with an authenticating transport. The current contract: trusted client, graph-shaped multi-tenancy.
+
+## Open protocol, optional commercial layer
+
+UPG is an **open protocol** for representing products as structured graphs. This server is the open-source reference implementation. See [unifiedproductgraph.org](https://unifiedproductgraph.org) for the spec and ecosystem.
+
+Commercial products may layer guided creation journeys, AI copilots, and visual canvases on top. Think Git versus hosted Git providers. The server works standalone with any MCP-compatible client.
+
+## Versioning
+
+`@unified-product-graph/cloud-server` co-versions with `@unified-product-graph/core` and `@unified-product-graph/mcp-server`. One version line covers spec and both reference implementations.
+
+See [CHANGELOG.md](./CHANGELOG.md) for release history.
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run in development mode
+npm run dev
+
+# Build (also regenerates TOOLS.md from JSDoc)
+npm run build
+
+# Type-check
+npm run type-check
+
+# Tests
+npm test
+
+# Regenerate TOOLS.md only
+npm run generate-tools
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for local-dev setup, the Docker compose flow, migration conventions, and where to file issues.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/SELF-HOSTING.md

@@ -0,0 +1,185 @@
+# Self-hosting the UPG Cloud Server
+
+The cloud server is a **Postgres-backed MCP server**. Unlike the local server
+(`@unified-product-graph/mcp-server`), which reads and writes a single `.upg`
+file, the cloud server stores the graph in Postgres — so a team can share one
+source of truth with concurrent, transactional writes, multiple products, an
+audit log, comments, and webhooks.
+
+> **Mental model:** the local server is to Git as the cloud server is to a
+> shared database. Same tools, same UPG semantics — different substrate.
+
+This guide covers three deployment tiers, from "ready today" to "real SaaS."
+
+| Tier | What you host | Auth model | Effort | Use when |
+|------|---------------|-----------|--------|----------|
+| **1 — Shared DB** | Just Postgres; each client runs the server locally | Connection string = full access | Minutes | A small, trusting team |
+| **2 — Central endpoint** | The server behind a stdio→HTTP bridge + auth proxy | One shared identity, gated by a proxy | A day of ops | One shared endpoint, still one trust domain |
+| **3 — Multi-tenant SaaS** | The server with auth + per-user identity + RLS | Per-user, per-product RBAC | A real build | External / untrusted users |
+
+---
+
+## What you should know first
+
+- **Transport is stdio.** The server speaks MCP over stdin/stdout to a single
+  trusted client (Claude Code, Cursor, etc.). There is **no built-in network
+  endpoint** — Tiers 2 and 3 add one.
+- **One config knob:** `UPG_DATABASE_URL` (or `--database-url`). The server
+  opens a default `pg.Pool` against it and runs `SELECT 1` at startup — **it
+  exits immediately if the database is unreachable.**
+- **Postgres 13+** is required (the schema uses `gen_random_uuid()`).
+- **RBAC is recorded, not yet enforced.** The schema has an `access` table
+  (`owner` / `editor` / `viewer` roles) and `grant_access` / `list_collaborators`
+  tools, but there are **no RLS policies** and the stdio server threads **no
+  per-user identity**. Today, whoever holds the connection string has full
+  access. Per-user enforcement is Tier 3 (see the roadmap below).
+
+---
+
+## Tier 1 — Shared managed Postgres (recommended starting point)
+
+Host the **database**; every team member runs the server **locally** against it.
+Production-ready today for a team inside one trust boundary.
+
+### 1. Provision Postgres
+
+Any Postgres 13+ works — [Neon](https://neon.tech), [Supabase](https://supabase.com),
+[Railway](https://railway.app), RDS, or a VM. Grab the connection string:
+
+```
+postgres://USER:PASS@HOST:5432/upg?sslmode=require
+```
+
+### 2. Apply the migrations (once, from any machine)
+
+```bash
+export UPG_DATABASE_URL='postgres://…?sslmode=require'
+for f in migrations/*.sql; do
+  psql "$UPG_DATABASE_URL" -f "$f"   # applies 001 → 004 in order
+done
+```
+
+The four migrations create the `upg` schema: `products`, `nodes`, `edges`,
+`cross_product_edges` (001 + 004), `access` / `comments` / `audit_log`
+(002), and `webhooks` (003).
+
+### 3. Point each member's client at the shared DB
+
+Add an MCP server entry to each member's client config. Keep the connection
+string in **personal / local** config — never a committed file.
+
+```jsonc
+// If installed from npm (the package ships a `upg-cloud-server` bin):
+{
+  "mcpServers": {
+    "unified-product-graph-cloud": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@unified-product-graph/cloud-server"],
+      "env": { "UPG_DATABASE_URL": "postgres://…shared…?sslmode=require" }
+    }
+  }
+}
+
+// From a monorepo checkout instead:
+//   "command": "node",
+//   "args": ["./packages/upg-cloud-server/dist/index.js"]
+```
+
+Restart the client. The tools appear namespaced as
+`mcp__unified-product-graph-cloud__*`.
+
+### 4. Work against a shared graph
+
+The cloud server is **multi-product**, so every tool is scoped by `product_id`:
+
+1. `create_product` → returns a product UUID.
+2. Pass that `product_id` to `create_node`, `create_edge`, `query`, etc.
+
+Concurrent writes from different members land as atomic Postgres transactions
+with foreign-key integrity — no `.upg` merge conflicts.
+
+### Local Postgres for development
+
+A `docker-compose.yml` is included for a throwaway local database (Postgres on
+`:5433`, migrations auto-applied on first boot):
+
+```bash
+cd docker
+docker compose up -d postgres
+# UPG_DATABASE_URL=postgres://upg:upg@localhost:5433/upg
+```
+
+---
+
+## Tier 2 — A single shared endpoint (stdio → HTTP bridge)
+
+Centralize the **process** so clients don't run anything locally. Wrap the
+stdio server in an MCP HTTP bridge (e.g. [`supergateway`](https://github.com/supercorp-ai/supergateway)
+or `mcp-proxy`, or swap in the SDK's StreamableHTTP transport) and put an
+**auth proxy in front** — the server itself has no authentication.
+
+```
+[client] --HTTPS--> [auth proxy] --> [bridge + upg-cloud-server (stdio)] --> [managed Postgres]
+```
+
+Clients then use a remote entry instead of spawning a process:
+
+```jsonc
+{
+  "mcpServers": {
+    "unified-product-graph-cloud": {
+      "type": "http",
+      "url": "https://upg.your-company.com/mcp",
+      "headers": { "Authorization": "Bearer <team-token>" }
+    }
+  }
+}
+```
+
+**Caveat:** this centralizes the process, **not the permissions**. Every
+client through the bridge still shares one database identity. Use Tier 2 when
+you want one managed endpoint inside a single trust domain; use Tier 3 when
+clients must be isolated from one another.
+
+---
+
+## Tier 3 — Multi-tenant SaaS (the enforcement tier)
+
+The data model is already built for this — `products`, `access` roles,
+`audit_log`, `webhooks`, `cross_product_edges`. What's missing is the
+**enforcement layer**. Reaching genuine per-user multi-tenancy requires:
+
+1. **An HTTP transport** (replace/augment `StdioServerTransport`) that
+   authenticates each request and resolves it to a `user_id`.
+2. **Identity propagation** into the store, so every query carries the calling
+   user (e.g. `SET LOCAL app.user_id = …` per transaction).
+3. **RLS policies** on `upg.*` keyed off that identity and the `access` table,
+   so reads/writes are gated at the database — not by convention.
+4. **Operational scale** — stateless server replicas behind a load balancer,
+   connection pooling (e.g. PgBouncer; the server currently opens an untuned
+   default `pg.Pool`), and the existing webhook/audit machinery wired to fire
+   on mutations.
+
+Until those land, treat the `access` roles as **advisory metadata**, not a
+security boundary.
+
+> Tracked as a roadmap item — see the UPG issue tracker for "Tier-3 enforcement:
+> HTTP transport + per-user identity + RLS."
+
+---
+
+## Choosing a tier
+
+- **Small trusting team →** Tier 1. Host the DB, done.
+- **Want one shared endpoint →** Tier 2. Bridge + auth proxy.
+- **External / untrusted users →** Tier 3. Auth + identity + RLS + replicas.
+
+## Environment reference
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `UPG_DATABASE_URL` | Yes | Postgres connection string. Also accepted as `--database-url`. |
+
+The server is intentionally minimal in configuration — everything else lives
+in the database.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }