spm-mcp 0.1.0 → 0.2.0

package/README.md

@@ -1,8 +1,8 @@
 # spm-mcp
 
-**Cursor for product management** — expert document review as MCP tools.
+**Cursor for product management.** Expert document review as MCP tools.
 
-AI made engineering 10x faster. But deciding *what* to build didn't get faster. SPM fixes the input — 30 domain-specific expert reviews that score your product documents against the standards senior PMs actually use.
+AI made engineering 10x faster. But deciding *what* to build didn't get faster. SPM fixes the input with 30 domain-specific expert reviews that score your product documents against the standards senior PMs actually use.
 
 ```bash
 npx spm-mcp
@@ -10,59 +10,74 @@ npx spm-mcp
 
 ## The problem
 
-AI agents build what you specify — including every blind spot. A vague spec used to waste a sprint. Now it ships to production in hours. SPM catches the blind spots before they become shipped code.
+AI agents build what you specify, including every blind spot. A vague spec used to waste a sprint. Now it ships to production in hours. SPM catches the blind spots before they become shipped code.
 
 ## What SPM reviews
 
 Not just PRDs. Every document in the PM lifecycle:
 
-- **Strategy** — Product Roadmap, Growth Strategy, Go-to-Market, OKR Planning, Product Vision
-- **Analysis** — Competitive Analysis, Market Research, Product Metrics, Stakeholder Management
-- **Execution** — User Stories, Feature Spec, Sprint Planning, PRD to Jira, Release Notes, Test Cases
-- **Discovery** — Problem Statement, Persona, Jobs-to-be-Done, Opportunity Assessment
+- **Strategy:** Product Roadmap, Growth Strategy, Go-to-Market, OKR Planning, Product Vision
+- **Analysis:** Competitive Analysis, Market Research, Product Metrics, Stakeholder Management
+- **Execution:** User Stories, Feature Spec, Sprint Planning, PRD to Jira, Release Notes, Test Cases
+- **Discovery:** Problem Statement, Persona, Jobs-to-be-Done, Opportunity Assessment
 
 30 built-in expert reviews. Or create your own with `spm_create_custom_nano_app`.
 
 ## Quick start
 
-### 1. Get your API key
-
-Sign in at [superproductmanager.ai](https://superproductmanager.ai) → Profile → Generate API Key
-
-### 2. Set it
+### Option A: Guided setup (recommended)
 
 ```bash
-export SPM_API_KEY=spm_k_your_key_here
+npx spm-mcp
 ```
 
-### 3. Run
+First run auto-detects no API key and walks you through setup:
+1. Opens your browser to sign in
+2. You generate an API key on your Profile page
+3. Paste it back in the terminal
+4. Key saved to `~/.spm/config.json`. Done.
+
+### Option B: Manual setup
 
 ```bash
+# 1. Get your key at superproductmanager.ai > Profile > Generate API Key
+# 2. Set it
+export SPM_API_KEY=spm_k_your_key_here
+# 3. Run
 npx spm-mcp
 ```
 
+### Option C: claude.ai (remote MCP)
+
+For claude.ai web users, SPM is available as a remote MCP server:
+
+1. Get your API key at [superproductmanager.ai](https://superproductmanager.ai) > Profile
+2. In claude.ai, go to Settings > Integrations > Add MCP Server
+3. URL: `https://spm-mcp.superproductmanager.ai/mcp`
+4. Add header: `X-SPM-API-Key: spm_k_your_key_here`
+
 ## Tools
 
 | Tool | What it does |
 |------|-------------|
 | `spm_list_nano_apps` | Discover available expert reviews (30 built-in + your custom ones) |
-| `spm_analyze` | Score a document against domain-specific expert expectations. Every gap scored 0–1.0 with evidence. |
+| `spm_analyze` | Score a document against domain-specific expert expectations. Every gap scored 0-1.0 with evidence. |
 | `spm_clarify` | Get decision-forcing questions for the weakest gaps. Questions escalate when you give vague answers. |
 | `spm_evaluate` | Re-score gaps after clarification rounds. Tracks progress. Use after every 3 rounds of `spm_clarify`. |
-| `spm_improve` | Generate paste-ready improvements grounded in your answers — not AI hallucination. |
+| `spm_improve` | Generate paste-ready improvements grounded in your answers, not AI hallucination. |
 | `spm_create_custom_nano_app` | Create a custom expert review for any document type not covered by the built-in 30. |
 
 ## How it works
 
 ```
 Your document
-    → spm_analyze     Scores every gap 0–1.0 against expert expectations
-    → spm_clarify     Asks the questions your stakeholder would ask
-    → spm_evaluate    Re-scores — did the gap close?
-    → spm_improve     Generates improvements from YOUR answers
+    > spm_analyze     Scores every gap 0-1.0 against expert expectations
+    > spm_clarify     Asks the questions your stakeholder would ask
+    > spm_evaluate    Re-scores. Did the gap close?
+    > spm_improve     Generates improvements from YOUR answers
 ```
 
-The clarification questions are the product. They surface the assumptions you've been carrying without examining. When you dodge, they escalate — evidence first, then action directives, then assumptions made on your behalf. Like a principal PM review, not a chatbot.
+The clarification questions are the product. They surface the assumptions you've been carrying without examining. When you dodge, they escalate: evidence first, then action directives, then assumptions made on your behalf. Like a principal PM review, not a chatbot.
 
 ## Example workflow
 
@@ -73,8 +88,8 @@ SPM:    4 expectations scored. Problem Definition: 43/100. Success Metrics: 15/1
 You:    Clarify the weakest gap
 SPM:    "Is operator churn or player registration drop-off your primary counter-metric?"
 
-You:    Operator churn — if >20% revert to WhatsApp, we've failed.
-SPM:    [re-evaluates] Counter-metric: 0 → 0.9. Now targeting: Instrumentation plan.
+You:    Operator churn. If >20% revert to WhatsApp, we've failed.
+SPM:    [re-evaluates] Counter-metric: 0 > 0.9. Now targeting: Instrumentation plan.
 
 You:    Improve the success metrics section
 SPM:    [generates paste-ready content grounded in your "operator churn" decision]
@@ -86,17 +101,18 @@ Average documents improve from 35% to 82% in three rounds.
 
 ### Claude Code
 
-Add to `.claude/settings.json`:
+```bash
+claude mcp add spm -- npx spm-mcp
+```
+
+Or add to `.claude/settings.json`. If you ran `npx spm-mcp` setup already, the key is in `~/.spm/config.json` and no env var is needed:
 
 ```json
 {
   "mcpServers": {
     "spm": {
       "command": "npx",
-      "args": ["spm-mcp"],
-      "env": {
-        "SPM_API_KEY": "spm_k_your_key_here"
-      }
+      "args": ["spm-mcp"]
     }
   }
 }
@@ -126,30 +142,31 @@ Add to MCP configuration with the same command and env structure.
 
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
-| `SPM_API_KEY` | Yes | — | Your API key from [superproductmanager.ai](https://superproductmanager.ai) → Profile |
-| `SPM_SUPABASE_URL` | No | Production | Override for self-hosted or development |
-| `SPM_SUPABASE_ANON_KEY` | No | Production | Override for self-hosted or development |
+| `SPM_API_KEY` | Only if no `~/.spm/config.json` | n/a | Your API key. Run `npx spm-mcp` for guided setup. |
+| `SPM_SUPABASE_URL` | No | Production | Override for development |
+| `SPM_SUPABASE_ANON_KEY` | No | Production | Override for development |
 | `SPM_CLOUD_FUNCTIONS_BASE` | No | Production | Override Cloud Functions URL |
 
+API key resolution order: `SPM_API_KEY` env var > `~/.spm/config.json` > setup prompt.
+
 ## Security
 
-- **No filesystem access** — SPM never reads your local files, SSH keys, or credentials
-- **No postinstall scripts** — nothing runs on `npm install`
-- **4 specific env vars only** — reads `SPM_API_KEY`, `SPM_SUPABASE_URL`, `SPM_SUPABASE_ANON_KEY`, `SPM_CLOUD_FUNCTIONS_BASE`. No broad `process.env` access.
-- **Network calls only when tools are invoked** — not on import, not on install
-- **Source included** — TypeScript source ships alongside compiled JS for auditability
-- **Zero known vulnerabilities** — `npm audit` clean
+- **No filesystem access.** SPM never reads your local files, SSH keys, or credentials.
+- **No postinstall scripts.** Nothing runs on `npm install`.
+- **Minimal env access.** Reads 4 optional env vars and `~/.spm/config.json`. No broad `process.env` access.
+- **Network calls only when tools are invoked.** Not on import, not on install.
+- **Source included.** TypeScript source ships alongside compiled JS for auditability.
+- **Zero known vulnerabilities.** `npm audit` clean.
 
 ## Also available as
 
-- **Chrome extension** — reviews documents inside Google Docs, Notion, ClickUp, Linear. [Install from Chrome Web Store](https://chromewebstore.google.com/detail/super-product-manager/ocpjfedoogmpbkhpojdkfdimkbiamihg)
-- **Web app** — paste any document, full analysis in 30 seconds. [superproductmanager.ai](https://superproductmanager.ai)
+- **Chrome extension.** Reviews documents inside Google Docs, Notion, ClickUp, Linear. [Install from Chrome Web Store](https://chromewebstore.google.com/detail/super-product-manager/ocpjfedoogmpbkhpojdkfdimkbiamihg)
+- **Web app.** Paste any document, full analysis in 30 seconds. [superproductmanager.ai](https://superproductmanager.ai)
 
 ## Links
 
 - [Website](https://superproductmanager.ai)
 - [Chrome Extension](https://chromewebstore.google.com/detail/super-product-manager/ocpjfedoogmpbkhpojdkfdimkbiamihg)
-- [Y Combinator RFS: "Cursor for Product Management"](https://www.ycombinator.com/rfs)
 
 ## License
 

package/dist/src/client/cloud-functions.js

@@ -7,6 +7,7 @@ export async function callJsonEndpoint(endpoint, body = {}, apiKey) {
     const url = `${config.cloudFunctionsBase}/${endpoint}`;
     const headers = {
         'Content-Type': 'application/json',
+        'Origin': 'https://mcp.superproductmanager.ai',
     };
     if (apiKey) {
         headers['X-SPM-API-Key'] = apiKey;

package/dist/src/client/spm-api.js

@@ -19,6 +19,7 @@ function getHeaders(apiKey) {
     const headers = {
         'Content-Type': 'application/json',
         'Accept': 'text/event-stream, application/json',
+        'Origin': 'https://mcp.superproductmanager.ai',
     };
     if (key) {
         headers['X-SPM-API-Key'] = key;

package/dist/src/config.d.ts

@@ -1,11 +1,14 @@
 /**
  * SPM MCP Server configuration.
- * All credentials must be provided via environment variables.
+ *
+ * Only SPM_API_KEY is required from the user.
+ * Supabase values are public (protected by RLS) and default to production.
+ * API key is the security boundary: user-specific, hashed, revocable.
  */
 export declare const config: {
-    /** Supabase project URL */
+    /** Supabase project URL (public, RLS-protected) */
     readonly supabaseUrl: string;
-    /** Supabase anon key */
+    /** Supabase anon key (public, RLS-protected) */
     readonly supabaseAnonKey: string;
     /** Base URL for Cloud Functions */
     readonly cloudFunctionsBase: string;

package/dist/src/config.js

@@ -1,22 +1,43 @@
 /**
  * SPM MCP Server configuration.
- * All credentials must be provided via environment variables.
+ *
+ * Only SPM_API_KEY is required from the user.
+ * Supabase values are public (protected by RLS) and default to production.
+ * API key is the security boundary: user-specific, hashed, revocable.
  */
-function requireEnv(name) {
-    const v = process.env[name];
-    if (!v)
-        throw new Error(`${name} environment variable is required`);
-    return v;
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+// ─── Public defaults (same values shipped in client-side bundle) ────
+const DEFAULT_SUPABASE_URL = 'https://zrqngfkafphexqrteukm.supabase.co';
+const DEFAULT_SUPABASE_ANON_KEY = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InpycW5nZmthZnBoZXhxcnRldWttIiwicm9sZSI6ImFub24iLCJpYXQiOjE3MTYyNjc2MTIsImV4cCI6MjAzMTg0MzYxMn0.YNeVJnNwoTRKPRUi3JT0JQXq8XGXZ1GI6q1sqL9l0b4';
+const DEFAULT_CLOUD_FUNCTIONS_BASE = 'https://us-central1-litethink.cloudfunctions.net';
+// ─── Config file persistence (~/.spm/config.json) ───────────────────
+function loadConfigFile() {
+    try {
+        const configPath = join(homedir(), '.spm', 'config.json');
+        const raw = readFileSync(configPath, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+const savedConfig = loadConfigFile();
+// ─── Resolve API key: env var > config file ─────────────────────────
+function resolveApiKey() {
+    const key = process.env.SPM_API_KEY || savedConfig.apiKey || '';
+    return key;
 }
 export const config = {
-    /** Supabase project URL */
-    supabaseUrl: requireEnv('SPM_SUPABASE_URL'),
-    /** Supabase anon key */
-    supabaseAnonKey: requireEnv('SPM_SUPABASE_ANON_KEY'),
+    /** Supabase project URL (public, RLS-protected) */
+    supabaseUrl: process.env.SPM_SUPABASE_URL || DEFAULT_SUPABASE_URL,
+    /** Supabase anon key (public, RLS-protected) */
+    supabaseAnonKey: process.env.SPM_SUPABASE_ANON_KEY || DEFAULT_SUPABASE_ANON_KEY,
     /** Base URL for Cloud Functions */
-    cloudFunctionsBase: process.env.SPM_CLOUD_FUNCTIONS_BASE || 'https://us-central1-litethink.cloudfunctions.net',
+    cloudFunctionsBase: process.env.SPM_CLOUD_FUNCTIONS_BASE || DEFAULT_CLOUD_FUNCTIONS_BASE,
     /** User's SPM API key for authenticating with Cloud Functions */
-    apiKey: process.env.SPM_API_KEY || '',
+    apiKey: resolveApiKey(),
     /** Port for hosted HTTP transport */
     port: parseInt(process.env.PORT || '8080', 10),
 };

package/dist/src/stdio.d.ts

@@ -2,18 +2,11 @@
 /**
  * Stdio transport entry point for the SPM MCP Server.
  *
- * Used by Claude Code and other local MCP clients that spawn the server
- * as a subprocess. API key is read from SPM_API_KEY env var.
+ * Two modes:
+ *   1. Setup (interactive): `npx spm-mcp --setup` or auto-detected on first run
+ *      Opens browser for login, prompts for API key, saves to ~/.spm/config.json
  *
- * Configure in .claude/settings.json:
- * {
- *   "mcpServers": {
- *     "spm": {
- *       "command": "node",
- *       "args": ["/path/to/packages/mcp-server/dist/src/stdio.js"],
- *       "env": { "SPM_API_KEY": "spm_k_..." }
- *     }
- *   }
- * }
+ *   2. Server (non-interactive): started by Claude Code / Cursor as MCP subprocess
+ *      Reads API key from ~/.spm/config.json or SPM_API_KEY env var
  */
 export {};

package/dist/src/stdio.js

@@ -2,23 +2,107 @@
 /**
  * Stdio transport entry point for the SPM MCP Server.
  *
- * Used by Claude Code and other local MCP clients that spawn the server
- * as a subprocess. API key is read from SPM_API_KEY env var.
+ * Two modes:
+ *   1. Setup (interactive): `npx spm-mcp --setup` or auto-detected on first run
+ *      Opens browser for login, prompts for API key, saves to ~/.spm/config.json
  *
- * Configure in .claude/settings.json:
- * {
- *   "mcpServers": {
- *     "spm": {
- *       "command": "node",
- *       "args": ["/path/to/packages/mcp-server/dist/src/stdio.js"],
- *       "env": { "SPM_API_KEY": "spm_k_..." }
- *     }
- *   }
- * }
+ *   2. Server (non-interactive): started by Claude Code / Cursor as MCP subprocess
+ *      Reads API key from ~/.spm/config.json or SPM_API_KEY env var
  */
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { createSpmMcpServer } from './index.js';
-const server = createSpmMcpServer();
-const transport = new StdioServerTransport();
-await server.connect(transport);
+import { config } from './config.js';
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { createInterface } from 'readline';
+const CONFIG_DIR = join(homedir(), '.spm');
+const CONFIG_PATH = join(CONFIG_DIR, 'config.json');
+const SETUP_URL = 'https://superproductmanager.web.app/#/profile';
+function isInteractive() {
+    return process.stdin.isTTY === true;
+}
+function hasApiKey() {
+    return config.apiKey !== '' && config.apiKey.startsWith('spm_k_');
+}
+async function prompt(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+function saveApiKey(key) {
+    let existing = {};
+    try {
+        existing = JSON.parse(readFileSync(CONFIG_PATH, 'utf8'));
+    }
+    catch { /* no existing config */ }
+    if (!existsSync(CONFIG_DIR)) {
+        mkdirSync(CONFIG_DIR, { recursive: true });
+    }
+    writeFileSync(CONFIG_PATH, JSON.stringify({ ...existing, apiKey: key }, null, 2) + '\n');
+}
+async function runSetup() {
+    const log = (msg) => process.stderr.write(msg + '\n');
+    log('');
+    log('  Super Product Manager (SPM) MCP Server');
+    log('  ───────────────────────────────────────');
+    log('');
+    log('  No API key found. Let\'s set you up.');
+    log('');
+    log(`  1. Sign in at: ${SETUP_URL}`);
+    log('  2. Go to Profile > Generate API Key');
+    log('  3. Copy the key (starts with spm_k_)');
+    log('');
+    // Try to open browser
+    try {
+        const { exec } = await import('child_process');
+        const cmd = process.platform === 'darwin' ? 'open' :
+            process.platform === 'win32' ? 'start' : 'xdg-open';
+        exec(`${cmd} "${SETUP_URL}"`);
+        log('  Browser opened. Sign in and generate your key.');
+    }
+    catch {
+        log(`  Open this URL in your browser: ${SETUP_URL}`);
+    }
+    log('');
+    const key = await prompt('  Paste your API key here: ');
+    if (!key.startsWith('spm_k_')) {
+        log('');
+        log('  Invalid key. API keys start with spm_k_');
+        log('  Run `npx spm-mcp --setup` to try again.');
+        return false;
+    }
+    saveApiKey(key);
+    log('');
+    log(`  Key saved to ${CONFIG_PATH}`);
+    log('');
+    log('  You\'re all set! Add SPM to your AI tool:');
+    log('');
+    log('    Claude Code:  claude mcp add spm -- npx spm-mcp');
+    log('    Cursor:       Add to .cursor/mcp.json');
+    log('');
+    return true;
+}
+// ─── Main ───────────────────────────────────────────────────────────
+const wantsSetup = process.argv.includes('--setup');
+if (wantsSetup || (isInteractive() && !hasApiKey())) {
+    // Interactive setup mode
+    const ok = await runSetup();
+    process.exit(ok ? 0 : 1);
+}
+else if (!hasApiKey() && isInteractive()) {
+    // No key and interactive — guide the user
+    process.stderr.write('\n  No SPM_API_KEY found. Run: npx spm-mcp --setup\n\n');
+    process.exit(1);
+}
+else {
+    // MCP server mode (non-interactive, started by AI tool)
+    const server = createSpmMcpServer({ apiKey: config.apiKey });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
 //# sourceMappingURL=stdio.js.map

package/package.json

@@ -1,7 +1,9 @@
 {
   "name": "spm-mcp",
-  "version": "0.1.0",
-  "description": "Super Product Manager MCP Server — AI-powered product document analysis",
+  "version": "0.2.0",
+  "description": "Super Product Manager MCP Server - AI-powered product document analysis for PRDs, roadmaps, and 30 PM document types",
+  "author": "Super Product Manager <chiranjeevi.gunturi@superproductmanager.ai>",
+  "homepage": "https://superproductmanager.ai",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -23,6 +25,14 @@
     "@types/node": "^22.10.0",
     "typescript": "~5.7.0"
   },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "product-management",
+    "document-review"
+  ],
+  "license": "MIT",
   "engines": {
     "node": ">=20"
   }

package/src/client/cloud-functions.ts

@@ -13,6 +13,7 @@ export async function callJsonEndpoint(
   const url = `${config.cloudFunctionsBase}/${endpoint}`;
   const headers: Record<string, string> = {
     'Content-Type': 'application/json',
+    'Origin': 'https://mcp.superproductmanager.ai',
   };
   if (apiKey) {
     headers['X-SPM-API-Key'] = apiKey;

package/src/client/spm-api.ts

@@ -24,6 +24,7 @@ function getHeaders(apiKey?: string): Record<string, string> {
   const headers: Record<string, string> = {
     'Content-Type': 'application/json',
     'Accept': 'text/event-stream, application/json',
+    'Origin': 'https://mcp.superproductmanager.ai',
   };
   if (key) {
     headers['X-SPM-API-Key'] = key;

package/src/config.ts

@@ -1,26 +1,55 @@
 /**
  * SPM MCP Server configuration.
- * All credentials must be provided via environment variables.
+ *
+ * Only SPM_API_KEY is required from the user.
+ * Supabase values are public (protected by RLS) and default to production.
+ * API key is the security boundary: user-specific, hashed, revocable.
  */
 
-function requireEnv(name: string): string {
-  const v = process.env[name];
-  if (!v) throw new Error(`${name} environment variable is required`);
-  return v;
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+// ─── Public defaults (same values shipped in client-side bundle) ────
+
+const DEFAULT_SUPABASE_URL = 'https://zrqngfkafphexqrteukm.supabase.co';
+const DEFAULT_SUPABASE_ANON_KEY =
+  'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InpycW5nZmthZnBoZXhxcnRldWttIiwicm9sZSI6ImFub24iLCJpYXQiOjE3MTYyNjc2MTIsImV4cCI6MjAzMTg0MzYxMn0.YNeVJnNwoTRKPRUi3JT0JQXq8XGXZ1GI6q1sqL9l0b4';
+const DEFAULT_CLOUD_FUNCTIONS_BASE = 'https://us-central1-litethink.cloudfunctions.net';
+
+// ─── Config file persistence (~/.spm/config.json) ───────────────────
+
+function loadConfigFile(): Record<string, string> {
+  try {
+    const configPath = join(homedir(), '.spm', 'config.json');
+    const raw = readFileSync(configPath, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+const savedConfig = loadConfigFile();
+
+// ─── Resolve API key: env var > config file ─────────────────────────
+
+function resolveApiKey(): string {
+  const key = process.env.SPM_API_KEY || savedConfig.apiKey || '';
+  return key;
 }
 
 export const config = {
-  /** Supabase project URL */
-  supabaseUrl: requireEnv('SPM_SUPABASE_URL'),
+  /** Supabase project URL (public, RLS-protected) */
+  supabaseUrl: process.env.SPM_SUPABASE_URL || DEFAULT_SUPABASE_URL,
 
-  /** Supabase anon key */
-  supabaseAnonKey: requireEnv('SPM_SUPABASE_ANON_KEY'),
+  /** Supabase anon key (public, RLS-protected) */
+  supabaseAnonKey: process.env.SPM_SUPABASE_ANON_KEY || DEFAULT_SUPABASE_ANON_KEY,
 
   /** Base URL for Cloud Functions */
-  cloudFunctionsBase: process.env.SPM_CLOUD_FUNCTIONS_BASE || 'https://us-central1-litethink.cloudfunctions.net',
+  cloudFunctionsBase: process.env.SPM_CLOUD_FUNCTIONS_BASE || DEFAULT_CLOUD_FUNCTIONS_BASE,
 
   /** User's SPM API key for authenticating with Cloud Functions */
-  apiKey: process.env.SPM_API_KEY || '',
+  apiKey: resolveApiKey(),
 
   /** Port for hosted HTTP transport */
   port: parseInt(process.env.PORT || '8080', 10),

package/src/stdio.ts

@@ -2,24 +2,118 @@
 /**
  * Stdio transport entry point for the SPM MCP Server.
  *
- * Used by Claude Code and other local MCP clients that spawn the server
- * as a subprocess. API key is read from SPM_API_KEY env var.
+ * Two modes:
+ *   1. Setup (interactive): `npx spm-mcp --setup` or auto-detected on first run
+ *      Opens browser for login, prompts for API key, saves to ~/.spm/config.json
  *
- * Configure in .claude/settings.json:
- * {
- *   "mcpServers": {
- *     "spm": {
- *       "command": "node",
- *       "args": ["/path/to/packages/mcp-server/dist/src/stdio.js"],
- *       "env": { "SPM_API_KEY": "spm_k_..." }
- *     }
- *   }
- * }
+ *   2. Server (non-interactive): started by Claude Code / Cursor as MCP subprocess
+ *      Reads API key from ~/.spm/config.json or SPM_API_KEY env var
  */
 
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { createSpmMcpServer } from './index.js';
+import { config } from './config.js';
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { createInterface } from 'readline';
 
-const server = createSpmMcpServer();
-const transport = new StdioServerTransport();
-await server.connect(transport);
+const CONFIG_DIR = join(homedir(), '.spm');
+const CONFIG_PATH = join(CONFIG_DIR, 'config.json');
+const SETUP_URL = 'https://superproductmanager.web.app/#/profile';
+
+function isInteractive(): boolean {
+  return process.stdin.isTTY === true;
+}
+
+function hasApiKey(): boolean {
+  return config.apiKey !== '' && config.apiKey.startsWith('spm_k_');
+}
+
+async function prompt(question: string): Promise<string> {
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+function saveApiKey(key: string): void {
+  let existing: Record<string, string> = {};
+  try {
+    existing = JSON.parse(readFileSync(CONFIG_PATH, 'utf8'));
+  } catch { /* no existing config */ }
+
+  if (!existsSync(CONFIG_DIR)) {
+    mkdirSync(CONFIG_DIR, { recursive: true });
+  }
+  writeFileSync(CONFIG_PATH, JSON.stringify({ ...existing, apiKey: key }, null, 2) + '\n');
+}
+
+async function runSetup(): Promise<boolean> {
+  const log = (msg: string) => process.stderr.write(msg + '\n');
+
+  log('');
+  log('  Super Product Manager (SPM) MCP Server');
+  log('  ───────────────────────────────────────');
+  log('');
+  log('  No API key found. Let\'s set you up.');
+  log('');
+  log(`  1. Sign in at: ${SETUP_URL}`);
+  log('  2. Go to Profile > Generate API Key');
+  log('  3. Copy the key (starts with spm_k_)');
+  log('');
+
+  // Try to open browser
+  try {
+    const { exec } = await import('child_process');
+    const cmd = process.platform === 'darwin' ? 'open' :
+                process.platform === 'win32' ? 'start' : 'xdg-open';
+    exec(`${cmd} "${SETUP_URL}"`);
+    log('  Browser opened. Sign in and generate your key.');
+  } catch {
+    log(`  Open this URL in your browser: ${SETUP_URL}`);
+  }
+
+  log('');
+  const key = await prompt('  Paste your API key here: ');
+
+  if (!key.startsWith('spm_k_')) {
+    log('');
+    log('  Invalid key. API keys start with spm_k_');
+    log('  Run `npx spm-mcp --setup` to try again.');
+    return false;
+  }
+
+  saveApiKey(key);
+  log('');
+  log(`  Key saved to ${CONFIG_PATH}`);
+  log('');
+  log('  You\'re all set! Add SPM to your AI tool:');
+  log('');
+  log('    Claude Code:  claude mcp add spm -- npx spm-mcp');
+  log('    Cursor:       Add to .cursor/mcp.json');
+  log('');
+  return true;
+}
+
+// ─── Main ───────────────────────────────────────────────────────────
+
+const wantsSetup = process.argv.includes('--setup');
+
+if (wantsSetup || (isInteractive() && !hasApiKey())) {
+  // Interactive setup mode
+  const ok = await runSetup();
+  process.exit(ok ? 0 : 1);
+} else if (!hasApiKey() && isInteractive()) {
+  // No key and interactive — guide the user
+  process.stderr.write('\n  No SPM_API_KEY found. Run: npx spm-mcp --setup\n\n');
+  process.exit(1);
+} else {
+  // MCP server mode (non-interactive, started by AI tool)
+  const server = createSpmMcpServer({ apiKey: config.apiKey });
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}