wakeupneo-mcp 0.1.0

package/README.md

@@ -0,0 +1,151 @@
+# WakeUpNeo MCP Server
+
+Drive your Eisenhower Matrix, Compass documents, and guided rituals from any MCP client (Claude Code, Claude Desktop, Cursor, etc.).
+
+## Quick Start
+
+### 1. Authenticate
+
+```bash
+npx wakeupneo-mcp setup
+```
+
+This opens your browser for Google SSO login (same as the web app). Credentials are saved to `~/.wakeupneo/auth.json` — no manual token management.
+
+```bash
+# Check auth status
+npx wakeupneo-mcp status
+```
+
+### 2. Add to your MCP client
+
+**Claude Code** (`~/.claude/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "wakeupneo": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "wakeupneo-mcp@latest"]
+    }
+  }
+}
+```
+
+**Alternative: environment variables** (for CI or custom setups):
+
+```json
+{
+  "mcpServers": {
+    "wakeupneo": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["/path/to/wakeupneo/wakeupneo-mcp/bin/wakeupneo-mcp.js"],
+      "env": {
+        "WAKEUPNEO_SUPABASE_URL": "https://your-project.supabase.co",
+        "WAKEUPNEO_SUPABASE_ANON_KEY": "your-anon-key",
+        "WAKEUPNEO_REFRESH_TOKEN": "your-refresh-token"
+      }
+    }
+  }
+}
+```
+
+### Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `WAKEUPNEO_APP_URL` | No | Web app URL (default: `https://www.wakeupneo.co`) |
+| `WAKEUPNEO_SERVICE_ROLE_KEY` | No | Required for admin tools only |
+| `WAKEUPNEO_SUPABASE_URL` | No | Fallback if `~/.wakeupneo/auth.json` not present |
+| `WAKEUPNEO_SUPABASE_ANON_KEY` | No | Fallback if `~/.wakeupneo/auth.json` not present |
+| `WAKEUPNEO_REFRESH_TOKEN` | No | Fallback if `~/.wakeupneo/auth.json` not present |
+
+## Available Tools
+
+### Matrix
+- **get_matrix** — Full Eisenhower Matrix view (task counts, per-quadrant lists, flagged items)
+- **move_task** — Move a task between quadrants
+- **approve_schedule** — Batch-approve AI-proposed task placements
+
+### Tasks
+- **create_task** — Create a native task
+- **update_task** — Update task content, quadrant, priority, dates
+- **complete_task** — Mark task as done
+- **delete_task** — Remove a task
+- **list_projects** — List native projects
+- **create_project** — Create a native project
+
+### Documents (Compass)
+- **list_documents** — Browse documents by folder
+- **get_document** — Read a document's full content
+- **create_document** — Create a new document
+- **update_document** — Edit content or title
+- **delete_document** — Remove a document
+- **get_journal** — Recent journal entries
+- **write_journal** — Write/append to today's journal
+- **get_foundation** — Read all foundation docs (Values, Goals, Challenges, People, Soul)
+
+### Rituals
+- **start_ritual** — Begin a guided workflow (morning, daily-brief, weekly-plan, weekly-wrapup)
+- **advance_ritual** — Move to the next step
+- **complete_ritual** — Finish the active ritual
+- **cancel_ritual** — Cancel without completing
+- **get_ritual_status** — Check current progress
+- **list_rituals** — See available ritual types
+- **get_ritual_history** — Past ritual completions
+
+### Browser & Settings
+- **focus_browser** — Open/focus WakeUpNeo in the browser (respects Live Mirror)
+- **get_settings** — View MCP settings (Live Mirror, etc.)
+- **set_live_mirror** — Toggle Live Mirror on/off
+
+### Admin (requires service role key)
+- **admin_get_users** — List active users
+- **admin_feature_flags** — View/toggle feature flags
+- **admin_usage_metrics** — Usage stats (rituals, docs, conversations)
+- **admin_run_as_user** — Inspect a user's matrix state
+- **admin_run_e2e** — Run Playwright e2e tests, returns pass/fail + report path
+
+## Live Mirror
+
+**Live Mirror** controls whether MCP actions navigate the browser in real-time.
+
+- **On** (default): MCP actions open/focus WakeUpNeo and navigate to the relevant view. Changes appear live.
+- **Off**: MCP writes data to Supabase silently. Browser stays where it is.
+
+Toggle via MCP: `set_live_mirror({ enabled: false })`
+
+Per-action override: `focus_browser({ path: '/compass', live_mirror: true })` forces browser focus even when Live Mirror is off.
+
+## How It Works
+
+```
+MCP Client (Claude Code, Cursor, etc.)
+    │ stdio
+    ▼
+WakeUpNeo MCP Server (local)
+    │ authenticated Supabase calls
+    ▼
+Supabase (remote)
+    │ Realtime subscriptions
+    ▼
+WakeUpNeo Web UI (browser)
+    → navigates to the active step
+    → shows content building in real-time
+    → presents approval UI when human input needed
+```
+
+The MCP server authenticates via your Supabase session (RLS enforced). The web app subscribes to Supabase Realtime and updates automatically — tasks appear, documents refresh, rituals progress, views navigate.
+
+## Authentication Flow
+
+The `setup` command uses browser-based OAuth (like `gh auth login`):
+
+1. Starts a temporary local HTTP server
+2. Opens browser to WakeUpNeo's MCP auth page
+3. You log in via Google SSO (one click if already logged in)
+4. Tokens are sent back to the local server
+5. Saved to `~/.wakeupneo/auth.json` (file permissions: 600)
+6. Auto-refreshed on every server start — no manual token management

package/bin/wakeupneo-mcp.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+/**
+ * WakeUpNeo MCP Server — CLI entry point
+ *
+ * Usage:
+ *   npx wakeupneo-mcp           — Start the MCP server (stdio transport)
+ *   npx wakeupneo-mcp setup     — Authenticate via browser (like `gh auth login`)
+ *   npx wakeupneo-mcp status    — Show current auth status
+ *
+ * Auth is loaded from ~/.wakeupneo/auth.json (created by `setup`).
+ * Falls back to env vars: WAKEUPNEO_SUPABASE_URL, WAKEUPNEO_SUPABASE_ANON_KEY, WAKEUPNEO_REFRESH_TOKEN
+ */
+
+import { setup, loadTokens } from '../src/auth.js';
+
+const command = process.argv[2];
+
+if (command === 'setup') {
+  try {
+    await setup();
+    process.exit(0);
+  } catch (err) {
+    console.error(`\n  Setup failed: ${err.message}\n`);
+    process.exit(1);
+  }
+} else if (command === 'status') {
+  const tokens = await loadTokens();
+  if (tokens) {
+    console.log(`\n  Authenticated as: ${tokens.email || 'unknown'}`);
+    console.log(`  Supabase URL: ${tokens.supabaseUrl}`);
+    console.log(`  Saved at: ${tokens.savedAt || 'unknown'}\n`);
+  } else {
+    console.log('\n  Not authenticated. Run `npx wakeupneo-mcp setup` to log in.\n');
+  }
+  process.exit(0);
+} else {
+  // Default: start the MCP server
+  const { createServer } = await import('../src/server.js');
+  const server = await createServer();
+  await server.start();
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "wakeupneo-mcp",
+  "version": "0.1.0",
+  "description": "WakeUpNeo MCP server — drive your Eisenhower Matrix, Compass docs, and rituals from any MCP client",
+  "type": "module",
+  "bin": {
+    "wakeupneo-mcp": "./bin/wakeupneo-mcp.js"
+  },
+  "main": "src/server.js",
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node bin/wakeupneo-mcp.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "@supabase/supabase-js": "^2.89.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "wakeupneo",
+    "eisenhower",
+    "productivity",
+    "task-management"
+  ],
+  "license": "MIT"
+}

package/src/auth.js

@@ -0,0 +1,226 @@
+/**
+ * Authentication for the WakeUpNeo MCP server.
+ *
+ * Supports two auth methods:
+ * 1. Token file at ~/.wakeupneo/auth.json (created via `npx wakeupneo-mcp setup`)
+ * 2. Environment variables (WAKEUPNEO_SUPABASE_URL, WAKEUPNEO_SUPABASE_ANON_KEY, WAKEUPNEO_REFRESH_TOKEN)
+ *
+ * The `setup` command runs a browser-based OAuth flow (like `gh auth login`):
+ * - Starts a local HTTP server on a random port
+ * - Opens browser to WakeUpNeo's MCP auth page
+ * - User logs in via Google SSO (one click if already logged in)
+ * - Tokens are sent back to the local server via redirect
+ * - Saved to ~/.wakeupneo/auth.json for future use
+ */
+
+import { createServer } from 'http';
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import { readFile, writeFile, mkdir, open, unlink } from 'fs/promises';
+import { homedir } from 'os';
+import { join } from 'path';
+
+const execAsync = promisify(exec);
+
+const AUTH_DIR = join(homedir(), '.wakeupneo');
+const AUTH_FILE = join(AUTH_DIR, 'auth.json');
+const LOCK_FILE = join(AUTH_DIR, 'auth.lock');
+
+const LOCK_TIMEOUT_MS = 10_000; // treat lock as stale after 10s
+const LOCK_RETRY_MS = 150;
+
+/**
+ * Acquire an exclusive file lock before refreshing tokens.
+ * Uses atomic O_EXCL creation — safe on all POSIX systems.
+ * Stale locks (from crashed processes) are removed after LOCK_TIMEOUT_MS.
+ */
+export async function acquireLock() {
+  const deadline = Date.now() + LOCK_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    try {
+      const fh = await open(LOCK_FILE, 'wx'); // O_CREAT | O_EXCL — atomic
+      await fh.close();
+      return;
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+      await new Promise(r => setTimeout(r, LOCK_RETRY_MS));
+    }
+  }
+  // Stale lock — clear it and proceed
+  try { await unlink(LOCK_FILE); } catch {}
+}
+
+/**
+ * Release the file lock.
+ */
+export async function releaseLock() {
+  try { await unlink(LOCK_FILE); } catch {}
+}
+
+const DEFAULT_APP_URL = 'https://www.wakeupneo.co';
+
+function getAppUrl() {
+  return process.env.WAKEUPNEO_APP_URL || DEFAULT_APP_URL;
+}
+
+/**
+ * Load saved credentials from ~/.wakeupneo/auth.json
+ * @returns {object|null} — { supabaseUrl, supabaseAnonKey, refreshToken } or null
+ */
+export async function loadTokens() {
+  try {
+    const raw = await readFile(AUTH_FILE, 'utf-8');
+    const data = JSON.parse(raw);
+    if (data.supabaseUrl && data.supabaseAnonKey && data.refreshToken) {
+      return data;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Save credentials to ~/.wakeupneo/auth.json
+ */
+export async function saveTokens({ supabaseUrl, supabaseAnonKey, refreshToken, email }) {
+  await mkdir(AUTH_DIR, { recursive: true });
+  const data = {
+    supabaseUrl,
+    supabaseAnonKey,
+    refreshToken,
+    email,
+    savedAt: new Date().toISOString(),
+  };
+  await writeFile(AUTH_FILE, JSON.stringify(data, null, 2) + '\n', { mode: 0o600 });
+}
+
+/**
+ * Get credentials from auth.json or environment variables.
+ * Auth file takes precedence; env vars are the fallback.
+ * @returns {{ supabaseUrl: string, supabaseAnonKey: string, refreshToken: string }}
+ */
+export async function getCredentials() {
+  // Try auth file first
+  const saved = await loadTokens();
+  if (saved) {
+    return saved;
+  }
+
+  // Fall back to environment variables
+  const supabaseUrl = process.env.WAKEUPNEO_SUPABASE_URL;
+  const supabaseAnonKey = process.env.WAKEUPNEO_SUPABASE_ANON_KEY;
+  const refreshToken = process.env.WAKEUPNEO_REFRESH_TOKEN;
+
+  if (supabaseUrl && supabaseAnonKey && refreshToken) {
+    return { supabaseUrl, supabaseAnonKey, refreshToken };
+  }
+
+  throw new Error(
+    'Not authenticated. Run `npx wakeupneo-mcp setup` to log in, ' +
+    'or set WAKEUPNEO_SUPABASE_URL, WAKEUPNEO_SUPABASE_ANON_KEY, and WAKEUPNEO_REFRESH_TOKEN.'
+  );
+}
+
+/**
+ * Run the interactive setup flow.
+ * Opens the browser to WakeUpNeo's MCP auth page, waits for the OAuth callback.
+ */
+export async function setup() {
+  console.log('\n  WakeUpNeo MCP — Setup\n');
+  console.log('  Opening browser for authentication...\n');
+
+  const appUrl = getAppUrl();
+
+  return new Promise((resolve, reject) => {
+    const server = createServer((req, res) => {
+      const url = new URL(req.url, `http://localhost`);
+
+      if (url.pathname === '/callback') {
+        const supabaseUrl = url.searchParams.get('supabase_url');
+        const supabaseAnonKey = url.searchParams.get('supabase_anon_key');
+        const refreshToken = url.searchParams.get('refresh_token');
+        const email = url.searchParams.get('email');
+
+        if (!supabaseUrl || !supabaseAnonKey || !refreshToken) {
+          res.writeHead(400, { 'Content-Type': 'text/html' });
+          res.end('<html><body><h2>Authentication failed</h2><p>Missing tokens. Please try again.</p></body></html>');
+          server.close();
+          reject(new Error('Missing tokens in callback'));
+          return;
+        }
+
+        // Save credentials
+        saveTokens({ supabaseUrl, supabaseAnonKey, refreshToken, email })
+          .then(() => {
+            res.writeHead(200, { 'Content-Type': 'text/html' });
+            res.end(`
+              <html>
+                <body style="font-family: system-ui; display: flex; align-items: center; justify-content: center; height: 100vh; margin: 0; background: #0a0a0a; color: #e5e5e5;">
+                  <div style="text-align: center;">
+                    <h2 style="color: #22c55e;">&#10003; Authenticated</h2>
+                    <p>Logged in as <strong>${email || 'unknown'}</strong></p>
+                    <p style="color: #737373;">You can close this tab and return to your terminal.</p>
+                  </div>
+                </body>
+              </html>
+            `);
+
+            console.log(`  Authenticated as ${email || 'unknown'}`);
+            console.log(`  Credentials saved to ${AUTH_FILE}\n`);
+
+            server.close();
+            resolve();
+          })
+          .catch((err) => {
+            res.writeHead(500, { 'Content-Type': 'text/html' });
+            res.end('<html><body><h2>Error saving credentials</h2></body></html>');
+            server.close();
+            reject(err);
+          });
+        return;
+      }
+
+      // Health check / catch-all
+      res.writeHead(200, { 'Content-Type': 'text/plain' });
+      res.end('WakeUpNeo MCP auth server');
+    });
+
+    // Listen on random port
+    server.listen(0, '127.0.0.1', async () => {
+      const port = server.address().port;
+      const authUrl = `${appUrl}/auth/mcp?callback_port=${port}`;
+
+      console.log(`  Auth server listening on port ${port}`);
+      console.log(`  Opening: ${authUrl}\n`);
+
+      // Open browser
+      try {
+        const platform = process.platform;
+        if (platform === 'darwin') {
+          await execAsync(`open "${authUrl}"`);
+        } else if (platform === 'linux') {
+          await execAsync(`xdg-open "${authUrl}"`);
+        } else if (platform === 'win32') {
+          await execAsync(`start "" "${authUrl}"`);
+        }
+      } catch {
+        console.log(`  Could not open browser automatically.`);
+        console.log(`  Please open this URL manually: ${authUrl}\n`);
+      }
+
+      console.log('  Waiting for authentication...\n');
+
+      // Timeout after 5 minutes
+      setTimeout(() => {
+        console.log('  Authentication timed out. Please try again.\n');
+        server.close();
+        reject(new Error('Authentication timed out'));
+      }, 5 * 60 * 1000);
+    });
+
+    server.on('error', (err) => {
+      reject(new Error(`Failed to start auth server: ${err.message}`));
+    });
+  });
+}

package/src/browser.js

@@ -0,0 +1,183 @@
+/**
+ * Browser automation — open or focus WakeUpNeo in the default browser.
+ * macOS-specific: uses `open` command and AppleScript for tab focusing.
+ *
+ * Supports Live Mirror setting — when disabled, browser focus is skipped.
+ */
+
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import { readFile } from 'fs/promises';
+import { homedir } from 'os';
+import { join } from 'path';
+import { getSupabase, getUserId } from './supabase.js';
+
+const execAsync = promisify(exec);
+
+const DEFAULT_APP_URL = 'https://www.wakeupneo.co';
+const AUTH_FILE = join(homedir(), '.wakeupneo', 'auth.json');
+
+// Debounce: suppress duplicate focus calls fired within 500ms of each other
+let focusDebounceTimer = null;
+let focusDebounceResolvers = [];
+
+function debouncedFocus(fn) {
+  return new Promise((resolve) => {
+    focusDebounceResolvers.push(resolve);
+    if (focusDebounceTimer) clearTimeout(focusDebounceTimer);
+    focusDebounceTimer = setTimeout(async () => {
+      focusDebounceTimer = null;
+      const resolvers = focusDebounceResolvers.splice(0);
+      try {
+        const result = await fn();
+        resolvers.forEach(r => r(result));
+      } catch {
+        resolvers.forEach(r => r({ action: 'failed' }));
+      }
+    }, 300);
+  });
+}
+
+async function getAppUrl(path = '') {
+  let base = process.env.WAKEUPNEO_APP_URL;
+  if (!base) {
+    try {
+      const raw = await readFile(AUTH_FILE, 'utf-8');
+      const data = JSON.parse(raw);
+      if (data.appUrl) base = data.appUrl;
+    } catch {
+      // ignore — fall through to default
+    }
+  }
+  base = base || DEFAULT_APP_URL;
+  return path ? `${base}${path}` : base;
+}
+
+/**
+ * Check if Live Mirror is enabled for the current user.
+ * Reads from user_profiles.settings.MCP_SETTINGS.live_mirror (default: true).
+ */
+async function isLiveMirrorEnabled() {
+  try {
+    const supabase = getSupabase();
+    const userId = getUserId();
+    const { data } = await supabase
+      .from('user_profiles')
+      .select('settings')
+      .eq('user_id', userId)
+      .maybeSingle();
+    return data?.settings?.MCP_SETTINGS?.live_mirror !== false;
+  } catch {
+    // If we can't read the setting (e.g., not initialized yet), default to enabled
+    return true;
+  }
+}
+
+/**
+ * Open WakeUpNeo in the default browser, or focus an existing tab.
+ * Respects the Live Mirror setting — when disabled, returns a skipped result.
+ *
+ * @param {string} [path] — Optional path to navigate to (e.g., '/compass', '/settings')
+ * @param {object} [options] — Options
+ * @param {boolean} [options.live_mirror] — Per-action override (true/false). Omit to use user setting.
+ * @returns {Promise<{ action: string, url: string }>}
+ */
+export async function focusBrowser(path = '', { live_mirror } = {}) {
+  const url = await getAppUrl(path);
+
+  // Check Live Mirror setting (per-action override takes precedence)
+  const mirrorEnabled = live_mirror !== undefined ? live_mirror : await isLiveMirrorEnabled();
+  if (!mirrorEnabled) {
+    return { action: 'skipped', url, reason: 'Live Mirror is off' };
+  }
+
+  return debouncedFocus(() => {
+    const platform = process.platform;
+    if (platform === 'darwin') return focusMacOS(url);
+    if (platform === 'linux') return focusLinux(url);
+    if (platform === 'win32') return focusWindows(url);
+    return execAsync(`open "${url}"`).then(() => ({ action: 'opened', url }));
+  });
+}
+
+async function focusMacOS(url) {
+  // Try to focus an existing Chrome tab first
+  try {
+    const script = `
+      tell application "Google Chrome"
+        set found to false
+        repeat with w in windows
+          set tabIndex to 0
+          repeat with t in tabs of w
+            set tabIndex to tabIndex + 1
+            if URL of t contains "wakeupneo" or URL of t contains "localhost:5173" then
+              set active tab index of w to tabIndex
+              set index of w to 1
+              activate
+              set found to true
+              exit repeat
+            end if
+          end repeat
+          if found then exit repeat
+        end repeat
+        if not found then
+          open location "${url}"
+          activate
+        end if
+      end tell
+    `;
+    await execAsync(`osascript -e '${script.replace(/'/g, "'\\''")}'`);
+    return { action: 'focused', url };
+  } catch {
+    // Chrome not running or AppleScript failed — try Safari
+    try {
+      const safariScript = `
+        tell application "Safari"
+          set found to false
+          repeat with w in windows
+            set tabIndex to 0
+            repeat with t in tabs of w
+              set tabIndex to tabIndex + 1
+              if URL of t contains "wakeupneo" or URL of t contains "localhost:5173" then
+                set current tab of w to t
+                set index of w to 1
+                activate
+                set found to true
+                exit repeat
+              end if
+            end repeat
+            if found then exit repeat
+          end repeat
+          if not found then
+            open location "${url}"
+            activate
+          end if
+        end tell
+      `;
+      await execAsync(`osascript -e '${safariScript.replace(/'/g, "'\\''")}'`);
+      return { action: 'focused', url };
+    } catch {
+      // Fallback: just open the URL in default browser
+      await execAsync(`open "${url}"`);
+      return { action: 'opened', url };
+    }
+  }
+}
+
+async function focusLinux(url) {
+  try {
+    await execAsync(`xdg-open "${url}"`);
+    return { action: 'opened', url };
+  } catch {
+    return { action: 'failed', url, error: 'xdg-open not available' };
+  }
+}
+
+async function focusWindows(url) {
+  try {
+    await execAsync(`start "" "${url}"`);
+    return { action: 'opened', url };
+  } catch {
+    return { action: 'failed', url, error: 'Failed to open browser' };
+  }
+}

package/src/navigation.js

@@ -0,0 +1,41 @@
+/**
+ * MCP Navigation — broadcasts navigation hints to the frontend via Supabase Realtime.
+ *
+ * Uses broadcast (not DB writes) so there's no race condition with the settings blob
+ * and no migration required. If the frontend isn't subscribed the event is silently dropped —
+ * navigation hints are best-effort and never block tool calls.
+ */
+
+import { getSupabase, getUserId } from './supabase.js';
+
+/**
+ * Broadcast a navigation signal so the frontend can switch to the relevant project/view.
+ * @param {object} opts
+ * @param {string|null} opts.project_id  — Native project UUID (null = All Tasks)
+ * @param {string}      opts.source      — 'native' | 'todoist' | 'jira' | 'asana' | 'github'
+ * @param {string|null} opts.quadrant    — Target quadrant hint ('do','decide','delegate','delete','inbox')
+ */
+export async function broadcastNavigation({ project_id = null, source = 'native', quadrant = null } = {}) {
+  try {
+    const supabase = getSupabase();
+    const userId = getUserId();
+
+    const channel = supabase.channel(`mcp:navigation:${userId}`);
+
+    await new Promise((resolve) => {
+      channel.subscribe((status) => {
+        if (status === 'SUBSCRIBED') resolve();
+      });
+    });
+
+    await channel.send({
+      type: 'broadcast',
+      event: 'navigate',
+      payload: { project_id, source, quadrant, timestamp: Date.now() },
+    });
+
+    await supabase.removeChannel(channel);
+  } catch {
+    // Navigation is best-effort — never fail a tool call over this
+  }
+}