slashvibe-mcp 0.3.20 → 0.3.21

package/README.md

@@ -1,288 +1,83 @@
-# /vibe MCP Server
+# vibe-mcp
 
-The social layer for AI coding. DMs, presence, discovery, and games between developers — without leaving your editor.
+Social layer for AI-assisted coding. DMs, presence, and connection between developers.
 
-Works with Claude Code, Cursor, VS Code, Windsurf, Cline, Continue.dev, JetBrains, and any MCP-compatible client.
+**Works in:** Claude Code • Cursor • Any MCP-compatible IDE
 
-## Install
+## Quick Start
 
-Add to your MCP config and restart your editor:
-
-<details open>
-<summary><strong>Claude Code</strong></summary>
-
-Add to `~/.claude.json`:
-```json
-{
-  "mcpServers": {
-    "vibe": {
-      "command": "npx",
-      "args": ["-y", "slashvibe-mcp"]
-    }
-  }
-}
-```
-
-Or via CLI:
+**Claude Code:**
 ```bash
-claude mcp add vibe -- npx -y slashvibe-mcp
+npx slashvibe-mcp setup
 ```
-</details>
 
-<details>
-<summary><strong>Cursor</strong></summary>
+**Cursor:** See [Cursor Setup Guide](docs/CURSOR_SETUP.md)
 
-Add to `~/.cursor/mcp.json`:
-```json
-{
-  "mcpServers": {
-    "vibe": {
-      "command": "npx",
-      "args": ["-y", "slashvibe-mcp"]
-    }
-  }
-}
-```
-</details>
+**Other IDEs:** Any editor supporting MCP protocol can use the manual config below.
 
-<details>
-<summary><strong>VS Code (GitHub Copilot)</strong></summary>
+## Installation
 
-Add to `.vscode/mcp.json` in your workspace:
-```json
-{
-  "servers": {
-    "vibe": {
-      "command": "npx",
-      "args": ["-y", "slashvibe-mcp"]
-    }
-  }
-}
-```
+```bash
+# Install globally
+npm install -g vibe-mcp
 
-Or add to your `settings.json`:
-```json
-{
-  "mcp": {
-    "servers": {
-      "vibe": {
-        "command": "npx",
-        "args": ["-y", "slashvibe-mcp"]
-      }
-    }
-  }
-}
+# Or add to Claude Code MCP config
+claude mcp add vibe-mcp
 ```
-</details>
-
-<details>
-<summary><strong>Windsurf</strong></summary>
 
-Add to `~/.codeium/windsurf/mcp_config.json`:
-```json
-{
-  "mcpServers": {
-    "vibe": {
-      "command": "npx",
-      "args": ["-y", "slashvibe-mcp"]
-    }
-  }
-}
-```
-</details>
+## Manual Setup
 
-<details>
-<summary><strong>Cline (VS Code)</strong></summary>
+Add to `~/.claude.json`:
 
-Open Cline > MCP Servers icon > Configure > Edit JSON, then add:
 ```json
 {
   "mcpServers": {
     "vibe": {
       "command": "npx",
-      "args": ["-y", "slashvibe-mcp"]
+      "args": ["vibe-mcp"],
+      "env": {
+        "VIBE_API_URL": "https://www.slashvibe.dev"
+      }
     }
   }
 }
 ```
-</details>
-
-<details>
-<summary><strong>Continue.dev</strong></summary>
-
-Create `.continue/mcpServers/vibe.json`:
-```json
-{
-  "command": "npx",
-  "args": ["-y", "slashvibe-mcp"]
-}
-```
-</details>
-
-<details>
-<summary><strong>JetBrains (IntelliJ, WebStorm, etc.)</strong></summary>
-
-Go to **Settings > Tools > AI Assistant > Model Context Protocol (MCP)** and add a new server:
-- **Command:** `npx`
-- **Arguments:** `-y slashvibe-mcp`
-
-Or import from your Claude Code config if you already have one.
-</details>
-
-## Getting Started
-
-Once installed, tell Claude:
-
-```
-"let's vibe"
-```
-
-That's it. Claude will authenticate you via GitHub, show who's online, and check your inbox.
-
-If you prefer step-by-step:
-
-1. **Authenticate** — `vibe init` opens GitHub OAuth in your browser. Takes 30 seconds.
-2. **See who's around** — `vibe who` shows online builders and what they're working on.
-3. **Check messages** — `vibe inbox` shows unread DMs.
-4. **Send your first message** — `vibe dm @seth hey, just set up /vibe!`
-
-## Tools
-
-### Core — Messaging & Presence
-
-| Tool | What it does |
-|------|-------------|
-| `vibe_start` | Entry point — authenticates, shows who's online, checks inbox |
-| `vibe_init` | Set up your identity via GitHub OAuth |
-| `vibe_who` | See who's online and what they're building |
-| `vibe_dm` | Send a direct message |
-| `vibe_inbox` | Check your unread messages |
-| `vibe_open` | Open a conversation thread with someone |
-| `vibe_ping` | Send a quick wave to someone |
-| `vibe_react` | React to a message |
-| `vibe_status` | Set your mood or what you're working on |
-| `vibe_away` / `vibe_back` | Set yourself away or return |
-| `vibe_bye` | End your session |
-
-### Discovery — Find Your People
-
-| Tool | What it does |
-|------|-------------|
-| `vibe_discover` | Find builders by interests, projects, or activity |
-| `vibe_suggest_tags` | Get tag suggestions for your profile |
-| `vibe_skills_exchange` | Browse and offer skills |
-| `vibe_workshop_buddy` | Find a learning partner |
-| `vibe_invite` | Generate an invite link |
-
-### Creative — Ship & Share
-
-| Tool | What it does |
-|------|-------------|
-| `vibe_ship` | Announce what you shipped |
-| `vibe_idea` | Share an idea with the community |
-| `vibe_request` | Ask the community for help |
-| `vibe_feed` | See what people are shipping and sharing |
-| `vibe_create_artifact` | Create a shareable guide, workspace, or learning |
-| `vibe_view_artifact` | View shared artifacts |
-
-### Memory — Context That Persists
-
-| Tool | What it does |
-|------|-------------|
-| `vibe_remember` | Save a note about someone for next time |
-| `vibe_recall` | Pull up everything you know about someone |
-| `vibe_forget` | Delete a memory |
-| `vibe_handoff` | Create an AIRC context handoff for another tool |
-
-### Games — 27 Multiplayer & Solo Games
-
-| Tool | What it does |
-|------|-------------|
-| `vibe_game` | Start a multiplayer game with someone |
-| `vibe_solo_game` | Play a solo game (riddles, hangman, number guess) |
-| `vibe_tictactoe` | Challenge someone to tic-tac-toe |
-| `vibe_crossword` | Collaborative crossword puzzle |
-| `vibe_drawing` | Collaborative ASCII drawing |
-| `vibe_party_game` | Start a party game for 3+ players |
-
-### Bridges — Cross-Platform Social
-
-| Tool | What it does |
-|------|-------------|
-| `vibe_x_mentions` | Check your X/Twitter mentions |
-| `vibe_x_reply` | Reply on X from the terminal |
-| `vibe_social_inbox` | Unified inbox across platforms |
-| `vibe_social_post` | Post to multiple networks at once |
-
-### Diagnostics
-
-| Tool | What it does |
-|------|-------------|
-| `vibe_doctor` | Full health check — API, auth, storage, presence |
-| `vibe_test` | Quick connection and identity test |
-| `vibe_help` | Show available commands |
-| `vibe_update` | Check for and apply updates |
-| `vibe_settings` | Configure preferences |
-
-## How It Works
-
-/vibe is an MCP server that connects your editor to [slashvibe.dev](https://slashvibe.dev). Messages sync via a Postgres backend with local SQLite persistence for offline-first speed. Everyone using /vibe is on the same network — regardless of which editor they use.
-
-```
-Your Editor ←→ /vibe MCP (stdio) ←→ slashvibe.dev API ←→ Other users
-                     ↕
-               Local SQLite DB
-               (~/.vibecodings/sessions.db)
-```
-
-- **Identity** persists via GitHub OAuth — your handle follows you across sessions
-- **Messages** are stored locally first, then synced to the server (optimistic send)
-- **Presence** broadcasts via heartbeat — others see you in real time
-- **Memory** is local — notes you save about people stay on your machine
-
-## Troubleshooting
 
-**"I installed but don't see /vibe tools in Claude Code"**
-- Make sure you restarted Claude Code after adding the MCP config
-- Check your config file: `~/.claude.json` or `~/.config/claude-code/mcp.json`
-- Run `vibe doctor` to diagnose issues
+## Features
 
-**"Authentication failed or timed out"**
-- The OAuth flow opens a browser window — if it didn't open, go to [slashvibe.dev/login](https://slashvibe.dev/login) manually
-- The auth callback runs on `localhost:9876` — make sure that port is free
-- You have 2 minutes to complete the GitHub login
+- **Presence** - See who's online building with Claude Code
+- **DMs** - Direct messages between developers
+- **Memory** - Remember context about connections
+- **Status** - Share what you're working on
+- **Games** - Play tic-tac-toe while coding
 
-**"Messages aren't sending"**
-- Run `vibe doctor` to check API connectivity
-- Check your internet connection
-- Messages are saved locally even if the API is down — they'll sync when you reconnect
+## Commands
 
-**"I see 'Unknown tool' errors"**
-- You may be running an older version. Run `vibe update` or reinstall: `npm install -g slashvibe-mcp`
+Once installed, use these in Claude Code:
 
-## Configuration
+| Command | Description |
+|---------|-------------|
+| `vibe` | Check inbox and see who's online |
+| `vibe who` | List online users |
+| `vibe dm @handle "message"` | Send a DM |
+| `vibe status shipping` | Set your status |
+| `vibe remember @handle "note"` | Save a memory |
+| `vibe recall @handle` | Recall memories |
 
-Config lives at `~/.vibecodings/config.json` (primary) or `~/.vibe/config.json` (legacy fallback).
+## API
 
-Local message database: `~/.vibecodings/sessions.db` (SQLite, shared with Vibe Terminal desktop app).
+The MCP server connects to `slashvibe.dev` for:
+- User presence and discovery
+- Message routing
+- Identity verification
 
-## Contributing
+## Related
 
-We welcome contributions. Please read our [Contributor License Agreement](./CLA.md) before submitting pull requests.
-
-- Report bugs via [GitHub Issues](https://github.com/VibeCodingInc/vibe-mcp/issues)
-- Propose features via [Discussions](https://github.com/VibeCodingInc/vibe-mcp/discussions)
+- [GitHub](https://github.com/VibeCodingInc/vibe-mcp) - Source code
+- [slashvibe.dev](https://slashvibe.dev) - Web presence
+- [Spirit Protocol](https://spiritprotocol.io) - Parent ecosystem
+- [AIRC](https://airc.chat) - Agent identity protocol
 
 ## License
 
-MIT — see [LICENSE](./LICENSE)
-
-## Links
-
-- [slashvibe.dev](https://slashvibe.dev) — The platform
-- [Vibe Terminal](https://github.com/VibeCodingInc/vibe-terminal) — Desktop app
-- [@slashvibe on X](https://twitter.com/slashvibe) — Updates
-
----
-
-Built by [Slash Vibe, Inc.](https://slashvibe.dev)
+MIT

package/analytics.js

@@ -0,0 +1,107 @@
+/**
+ * Analytics — Retention event tracking from MCP server
+ *
+ * Logs events to the /api/analytics/event endpoint for measuring
+ * user engagement and retention funnel performance.
+ *
+ * Usage:
+ *   const analytics = require('./analytics');
+ *   analytics.track('empty_inbox_action', { action: 'discover', source: 'inbox' });
+ */
+
+const config = require('./config');
+
+const API_URL = process.env.VIBE_API_URL || 'https://www.slashvibe.dev';
+
+/**
+ * Track an analytics event (fire and forget)
+ * @param {string} eventType - Event type (from valid types in api/lib/events.js)
+ * @param {object} data - Additional event data
+ */
+async function track(eventType, data = {}) {
+  const handle = config.getHandle();
+  if (!handle) return; // Skip if not initialized
+
+  try {
+    // Fire and forget - don't await or block
+    fetch(`${API_URL}/api/analytics/events`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        type: eventType,
+        handle,
+        data: {
+          ...data,
+          client: 'mcp-server',
+          timestamp: Date.now()
+        }
+      })
+    }).catch(() => {}); // Silently ignore errors
+  } catch (e) {
+    // Analytics should never block or fail user flows
+  }
+}
+
+/**
+ * Track empty inbox interaction
+ * @param {string} action - Which action was taken (or 'none' if user closed)
+ * @param {object} context - Context about the state (hadOnboardingTask, hadRecentShips, etc.)
+ */
+function trackEmptyInbox(action, context = {}) {
+  // Track that user reached empty inbox state
+  track('empty_inbox_reached', {
+    hadRecentThreads: context.recentThreads?.length > 0,
+    hadOnboardingTask: !!context.onboardingTask,
+    hadRecentShips: context.recentShips?.length > 0
+  });
+
+  // If an action was taken, track it
+  if (action && action !== 'none') {
+    track('empty_inbox_action', {
+      action,
+      ...context
+    });
+  }
+}
+
+/**
+ * Track lurk mode state change
+ * @param {boolean} enabled - Whether lurk mode was enabled or disabled
+ */
+function trackLurkMode(enabled) {
+  track(enabled ? 'lurk_mode_enabled' : 'lurk_mode_disabled', {});
+}
+
+/**
+ * Track onboarding task completion
+ * @param {string} taskId - The task that was completed
+ */
+function trackOnboardingTask(taskId) {
+  track('onboarding_task_completed', { taskId });
+}
+
+/**
+ * Track discovery initiation
+ * @param {string} source - Where discovery was initiated from (inbox, start, etc.)
+ */
+function trackDiscovery(source) {
+  track('discovery_initiated', { source });
+}
+
+/**
+ * Track session lifecycle
+ * @param {string} event - 'started' or 'ended'
+ * @param {object} sessionData - Session metrics (duration, actions, etc.)
+ */
+function trackSession(event, sessionData = {}) {
+  track(event === 'started' ? 'session_started' : 'session_ended', sessionData);
+}
+
+module.exports = {
+  track,
+  trackEmptyInbox,
+  trackLurkMode,
+  trackOnboardingTask,
+  trackDiscovery,
+  trackSession
+};

package/auth-store.js

@@ -0,0 +1,148 @@
+/**
+ * Auth Store - In-memory singleton for authentication state
+ *
+ * This is the SOURCE OF TRUTH for auth during MCP runtime.
+ * File persistence (config.json) is only for durability across restarts.
+ *
+ * Why this exists:
+ * - OAuth callback and API calls happen in the same MCP process
+ * - File-based auth was unreliable due to per-PID session files and caching
+ * - In-memory state is immediate and deterministic
+ *
+ * Usage:
+ * - Startup: authStore.hydrate() loads from disk once
+ * - OAuth: authStore.setToken(token) updates immediately
+ * - API calls: authStore.getToken() returns current token (no file I/O)
+ */
+
+// In-memory state - the single source of truth during runtime
+let _token = null;
+let _handle = null;
+let _oneLiner = null;
+let _hydrated = false;
+
+/**
+ * Hydrate auth state from disk (call once at MCP startup)
+ * This loads persisted state from config.json
+ */
+function hydrate() {
+  if (_hydrated) return; // Only hydrate once
+
+  try {
+    const config = require('./config');
+    const cfg = config.load();
+
+    _token = cfg.authToken || cfg.privyToken || null;
+    _handle = cfg.handle || cfg.username || null;
+    _oneLiner = cfg.one_liner || cfg.workingOn || null;
+    _hydrated = true;
+
+    if (_token) {
+      console.error('[auth-store] Hydrated from disk: @' + _handle);
+    } else {
+      console.error('[auth-store] Hydrated from disk: no token');
+    }
+  } catch (e) {
+    console.error('[auth-store] Hydration failed:', e.message);
+  }
+}
+
+/**
+ * Set auth token (call after OAuth completes)
+ * @param {string} token - JWT token
+ */
+function setToken(token) {
+  const hadToken = !!_token;
+  _token = token;
+
+  if (!hadToken && token) {
+    console.error('[auth-store] Token set (was empty)');
+  } else if (hadToken && token && token !== _token) {
+    console.error('[auth-store] Token updated');
+  }
+}
+
+/**
+ * Get current auth token
+ * @returns {string|null} Current token or null
+ */
+function getToken() {
+  return _token;
+}
+
+/**
+ * Set user handle
+ * @param {string} handle - User handle (without @)
+ */
+function setHandle(handle) {
+  _handle = handle;
+}
+
+/**
+ * Get current handle
+ * @returns {string|null} Current handle or null
+ */
+function getHandle() {
+  return _handle;
+}
+
+/**
+ * Set one-liner (what user is building)
+ * @param {string} oneLiner - One-liner description
+ */
+function setOneLiner(oneLiner) {
+  _oneLiner = oneLiner;
+}
+
+/**
+ * Get current one-liner
+ * @returns {string|null} Current one-liner or null
+ */
+function getOneLiner() {
+  return _oneLiner;
+}
+
+/**
+ * Check if user is authenticated
+ * @returns {boolean} True if token exists
+ */
+function isAuthenticated() {
+  return !!_token;
+}
+
+/**
+ * Clear all auth state (for logout/reset)
+ */
+function clear() {
+  _token = null;
+  _handle = null;
+  _oneLiner = null;
+  console.error('[auth-store] Cleared');
+}
+
+/**
+ * Get full auth state (for debugging)
+ * @returns {object} Current auth state
+ */
+function getState() {
+  return {
+    token: _token ? _token.substring(0, 20) + '...' : null,
+    handle: _handle,
+    oneLiner: _oneLiner,
+    hydrated: _hydrated,
+    isAuthenticated: !!_token
+  };
+}
+
+module.exports = {
+  hydrate,
+  setToken,
+  getToken,
+  setHandle,
+  getHandle,
+  setOneLiner,
+  getOneLiner,
+  isAuthenticated,
+  clear,
+  getState
+};