@productbrain/mcp 0.0.1-beta.0

package/.env.mcp.example

@@ -0,0 +1,32 @@
+# ProductBrain MCP — Environment Variables
+# Copy this file to .env.mcp and fill in your values.
+# In Claude Desktop / Cursor, these are typically set via the MCP config's "env" block.
+
+# ── Cloud Mode (recommended) ──────────────────────────────────────────
+#
+# PRODUCTBRAIN_API_KEY — Your API key from SynergyOS Settings → API Keys.
+#                        Starts with pb_sk_. This is the only required variable.
+#
+# PRODUCTBRAIN_URL     — Override the backend URL.
+#                        Defaults to ProductBrain Cloud. Set to http://localhost:3210
+#                        for local development.
+
+# PRODUCTBRAIN_API_KEY=pb_sk_your_key_here
+# PRODUCTBRAIN_URL=https://earnest-sheep-635.convex.site
+
+# ── Self-Hosted Mode ──────────────────────────────────────────────────
+#
+# CONVEX_SITE_URL  — Your Convex deployment SITE URL (*.convex.site, NOT *.convex.cloud).
+# MCP_API_KEY      — Shared secret matching the Convex dashboard env var.
+# WORKSPACE_SLUG   — The workspace slug to operate on.
+
+# CONVEX_SITE_URL=https://your-deployment.convex.site
+# MCP_API_KEY=your-secret-api-key
+# WORKSPACE_SLUG=your-workspace-slug
+
+# ── Debug (optional) ──────────────────────────────────────────────────
+# MCP_DEBUG=1
+
+# ── Analytics (optional) ──────────────────────────────────────────────
+# POSTHOG_MCP_KEY=
+# MCP_USER_ID=

package/README.md

@@ -0,0 +1,238 @@
+# ProductBrain
+
+The single source of truth for product knowledge — glossary, business rules, tensions, decisions, labels, and relations — accessible as an MCP server in [Claude Desktop](https://claude.ai/download), [Cursor](https://cursor.com), and any MCP-compatible AI assistant.
+
+ProductBrain connects your AI assistant to your team's knowledge base. Ask questions, capture decisions, and build a living knowledge graph without leaving your editor.
+
+## Quick Start (Cloud)
+
+### Option A: Guided setup (recommended)
+
+```bash
+npx productbrain setup
+```
+
+This opens SynergyOS → Settings → API Keys, prompts you to paste your key, and writes the config for Cursor or Claude Desktop.
+
+### Option B: Manual config
+
+**1. Get your API key**
+
+Go to **SynergyOS → Settings → API Keys** and click **Generate Key**. Copy the `pb_sk_...` key.
+
+**2. Configure your AI assistant**
+
+**Claude Desktop** — edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "productbrain": {
+      "command": "npx",
+      "args": ["-y", "productbrain"],
+      "env": {
+        "PRODUCTBRAIN_API_KEY": "pb_sk_your_key_here"
+      }
+    }
+  }
+}
+```
+
+**Cursor** — edit `.cursor/mcp.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "productbrain": {
+      "command": "npx",
+      "args": ["-y", "productbrain"],
+      "env": {
+        "PRODUCTBRAIN_API_KEY": "pb_sk_your_key_here"
+      }
+    }
+  }
+}
+```
+
+**3. Restart your assistant and verify**
+
+Ask:
+
+> "Use the health tool to check ProductBrain connectivity"
+
+You should see your workspace ID, collection count, and latency.
+
+## Self-Hosted Setup
+
+If you're running your own Convex deployment, use the three-variable config:
+
+```json
+{
+  "mcpServers": {
+    "productbrain": {
+      "command": "npx",
+      "args": ["-y", "productbrain"],
+      "env": {
+        "CONVEX_SITE_URL": "https://your-deployment.convex.site",
+        "MCP_API_KEY": "your-shared-api-key",
+        "WORKSPACE_SLUG": "your-workspace-slug"
+      }
+    }
+  }
+}
+```
+
+| Variable | Where to find it |
+|----------|-----------------|
+| `CONVEX_SITE_URL` | Convex dashboard → Settings → URL (use `*.convex.site`, not `*.convex.cloud`) |
+| `MCP_API_KEY` | Must match the `MCP_API_KEY` env var in your Convex deployment |
+| `WORKSPACE_SLUG` | Your workspace slug from the SynergyOS URL |
+
+## Dev vs Production
+
+Set `PRODUCTBRAIN_URL` to switch between environments:
+
+```json
+{
+  "env": {
+    "PRODUCTBRAIN_API_KEY": "pb_sk_your_key_here",
+    "PRODUCTBRAIN_URL": "http://localhost:3210"
+  }
+}
+```
+
+Omit `PRODUCTBRAIN_URL` to default to production.
+
+## What You Can Do
+
+### Search and explore
+
+- *"Search the glossary for 'tension'"*
+- *"List all business rules in the Governance domain"*
+- *"What is the canonical definition of 'supplier'?"*
+
+### Capture knowledge
+
+- *"Capture a tension: our MCP entry creation takes too many steps"*
+- *"Draft a decision record for choosing Convex over Supabase"*
+- *"Create a business rule about API key rotation"*
+
+### Navigate the knowledge graph
+
+- *"Gather full context around FEAT-001"*
+- *"What entries are related to GT-019?"*
+- *"Suggest links for this new tension"*
+
+### Check quality
+
+- *"Run a quality check on TEN-graph-db"*
+- *"Review business rules for the AI & MCP Integration domain"*
+- *"Verify the glossary against the codebase"*
+
+## Tools (20+)
+
+| Tool | What it does |
+|------|-------------|
+| `health` | Verify connectivity and get workspace stats |
+| `kb-search` | Full-text search across all knowledge entries |
+| `list-collections` | Browse all collection schemas |
+| `list-entries` | Browse entries with optional filters |
+| `get-entry` | Full record with data, labels, relations, history |
+| `smart-capture` | One-call entry creation with auto-linking and quality scoring |
+| `create-entry` | Create with full field control |
+| `update-entry` | Partial update (merges with existing data) |
+| `gather-context` | Multi-hop graph traversal around an entry |
+| `suggest-links` | Discover potential connections |
+| `relate-entries` | Create typed relations between entries |
+| `find-related` | List direct relations for an entry |
+| `quality-check` | Score an entry against collection-specific criteria |
+| `review-rules` | Surface business rules for a domain |
+| `verify` | Check knowledge entries against the actual codebase |
+| `list-labels` | Browse workspace labels |
+| `manage-labels` | Create, update, or delete labels |
+| `label-entry` | Apply or remove labels from entries |
+| `quick-capture` | Minimal-ceremony entry creation |
+| `mcp-audit` | Session audit log with call statistics |
+
+## Resources
+
+| URI | Content |
+|-----|---------|
+| `productbrain://orientation` | System map: architecture, data model, rules, analytics |
+| `productbrain://terminology` | Glossary + standards summary |
+| `productbrain://collections` | All collection schemas with field definitions |
+| `productbrain://{slug}/entries` | All entries in a given collection |
+| `productbrain://labels` | Workspace labels with hierarchy |
+
+## Prompts
+
+| Prompt | Purpose |
+|--------|---------|
+| `review-against-rules` | Structured compliance review against business rules |
+| `name-check` | Check variable/field names against the glossary |
+| `draft-decision-record` | Draft a decision record from context |
+| `draft-rule-from-context` | Draft a business rule from an observation |
+
+## Security
+
+- **Your data stays yours.** The MCP server connects only to your authenticated Convex deployment. No data is shared with third parties.
+- **API key handling.** Cloud keys (`pb_sk_...`) are SHA-256 hashed before storage. Only the prefix is persisted for display. Keys are sent as Bearer tokens over HTTPS.
+- **Workspace scoping.** Each API key is bound to a single workspace. No cross-workspace access is possible.
+- **Analytics are opt-in.** Set `POSTHOG_MCP_KEY` to enable usage analytics. Omit it entirely to disable all tracking.
+
+## Troubleshooting
+
+### "Missing API key" or "Invalid API key"
+
+Your `PRODUCTBRAIN_API_KEY` is missing or incorrect. Generate a new key from SynergyOS Settings → API Keys.
+
+### "CONVEX_SITE_URL environment variable is required"
+
+You're using self-hosted mode but missing the `env` block. Make sure all three variables are set.
+
+### "Workspace not found"
+
+For self-hosted: check your `WORKSPACE_SLUG`. For cloud: your API key may have been revoked.
+
+### "MCP call network error"
+
+The backend is unreachable. If using `PRODUCTBRAIN_URL`, verify the URL is correct and the server is running.
+
+### Server doesn't appear in Claude Desktop / Cursor
+
+Restart the application after editing the config file. In Cursor, check the MCP panel (Cmd+Shift+P → "MCP: Show Panel") for startup errors.
+
+### Enable debug logging
+
+Set `MCP_DEBUG=1` in your config's `env` block to see audit logs in stderr.
+
+## Development
+
+```bash
+# Clone and install
+git clone https://github.com/synergyai-os/productbrain.git
+cd productbrain
+npm install
+
+# Copy env template and fill in your values
+cp .env.mcp.example .env.mcp
+
+# Run in dev mode (TypeScript, hot reload)
+npm run dev
+
+# Build for production
+npm run build
+
+# Run the built version
+npm start
+
+# Typecheck
+npm run typecheck
+
+# Publish beta
+npm run publish:beta
+```
+
+## License
+
+MIT

package/dist/chunk-DGUM43GV.js

@@ -0,0 +1,11 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+export {
+  __require
+};
+//# sourceMappingURL=chunk-DGUM43GV.js.map

package/dist/chunk-DGUM43GV.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/cli/index.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+// src/cli/index.ts
+var subcommand = process.argv[2];
+if (subcommand === "setup") {
+  const { runSetup } = await import("../setup-K757L5KR.js");
+  await runSetup();
+} else {
+  await import("../index.js");
+}
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/cli/index.ts"],"sourcesContent":["#!/usr/bin/env node\n\n/**\n * ProductBrain CLI entry point.\n *\n * Usage:\n *   npx productbrain           → starts the MCP server (default)\n *   npx productbrain setup     → guided onboarding flow\n */\n\nexport {};\n\nconst subcommand = process.argv[2];\n\nif (subcommand === \"setup\") {\n  const { runSetup } = await import(\"./setup.js\");\n  await runSetup();\n} else {\n  // Default: start the MCP server\n  await import(\"../index.js\");\n}\n"],"mappings":";;;AAYA,IAAM,aAAa,QAAQ,KAAK,CAAC;AAEjC,IAAI,eAAe,SAAS;AAC1B,QAAM,EAAE,SAAS,IAAI,MAAM,OAAO,sBAAY;AAC9C,QAAM,SAAS;AACjB,OAAO;AAEL,QAAM,OAAO,aAAa;AAC5B;","names":[]}