slashvibe-mcp 0.3.21 → 0.3.23

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Slash Vibe, Inc.
+
+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

@@ -1,83 +1,316 @@
-# vibe-mcp
+# /vibe MCP Server
 
-Social layer for AI-assisted coding. DMs, presence, and connection between developers.
+[![npm version](https://img.shields.io/npm/v/slashvibe-mcp.svg)](https://www.npmjs.com/package/slashvibe-mcp)
+[![license](https://img.shields.io/npm/l/slashvibe-mcp.svg)](./LICENSE)
+[![node](https://img.shields.io/node/v/slashvibe-mcp.svg)](https://nodejs.org)
+[![CI](https://github.com/VibeCodingInc/vibe-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/VibeCodingInc/vibe-mcp/actions/workflows/ci.yml)
 
-**Works in:** Claude Code • Cursor • Any MCP-compatible IDE
+The social layer for AI coding. DMs, presence, discovery, and games between developers — without leaving your editor.
 
-## Quick Start
+Works with Claude Code, Cursor, VS Code, Windsurf, Cline, Continue.dev, JetBrains, and any MCP-compatible client.
 
-**Claude Code:**
+## Install
+
+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:
 ```bash
-npx slashvibe-mcp setup
+claude mcp add vibe -- npx -y slashvibe-mcp
 ```
+</details>
 
-**Cursor:** See [Cursor Setup Guide](docs/CURSOR_SETUP.md)
+<details>
+<summary><strong>Cursor</strong></summary>
 
-**Other IDEs:** Any editor supporting MCP protocol can use the manual config below.
+Add to `~/.cursor/mcp.json`:
+```json
+{
+  "mcpServers": {
+    "vibe": {
+      "command": "npx",
+      "args": ["-y", "slashvibe-mcp"]
+    }
+  }
+}
+```
+</details>
 
-## Installation
+<details>
+<summary><strong>VS Code (GitHub Copilot)</strong></summary>
 
-```bash
-# Install globally
-npm install -g vibe-mcp
+Add to `.vscode/mcp.json` in your workspace:
+```json
+{
+  "servers": {
+    "vibe": {
+      "command": "npx",
+      "args": ["-y", "slashvibe-mcp"]
+    }
+  }
+}
+```
 
-# Or add to Claude Code MCP config
-claude mcp add vibe-mcp
+Or add to your `settings.json`:
+```json
+{
+  "mcp": {
+    "servers": {
+      "vibe": {
+        "command": "npx",
+        "args": ["-y", "slashvibe-mcp"]
+      }
+    }
+  }
+}
 ```
+</details>
 
-## Manual Setup
+<details>
+<summary><strong>Windsurf</strong></summary>
 
-Add to `~/.claude.json`:
+Add to `~/.codeium/windsurf/mcp_config.json`:
+```json
+{
+  "mcpServers": {
+    "vibe": {
+      "command": "npx",
+      "args": ["-y", "slashvibe-mcp"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><strong>Cline (VS Code)</strong></summary>
 
+Open Cline > MCP Servers icon > Configure > Edit JSON, then add:
 ```json
 {
   "mcpServers": {
     "vibe": {
       "command": "npx",
-      "args": ["vibe-mcp"],
-      "env": {
-        "VIBE_API_URL": "https://www.slashvibe.dev"
-      }
+      "args": ["-y", "slashvibe-mcp"]
     }
   }
 }
 ```
+</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 (39)
+
+### Core — Identity & Session
+
+| 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_bye` | End your session |
+
+### Core — Messaging
+
+| Tool | What it does |
+|------|-------------|
+| `vibe_dm` | Send a direct message |
+| `vibe_inbox` | Check your unread messages |
+| `vibe_ping` | Send a quick wave to someone |
+| `vibe_react` | React to a message |
+| `vibe_open` | Open a conversation thread with someone |
+
+### Presence
+
+| Tool | What it does |
+|------|-------------|
+| `vibe_who` | See who's online and what they're building |
+| `vibe_status` | Set your mood or what you're working on |
+| `vibe_away` | Set yourself away |
+| `vibe_back` | Return from away |
+
+### Creative — Ship & Share
+
+| Tool | What it does |
+|------|-------------|
+| `vibe_ship` | Share with the community: ship (default), idea, or request via `type` param |
+| `vibe_session_save` | Save your coding session — makes it replayable, discoverable, and forkable |
+| `vibe_session_fork` | Fork an existing session to build on it |
+| `vibe_feed` | See what people are shipping and sharing |
+| `vibe_context` | Share what you're working on |
+
+### Discovery
+
+| Tool | What it does |
+|------|-------------|
+| `vibe_discover` | Find people, skills, and partners. Subcommands: suggest, search, interests, active, skills, partner |
+| `vibe_invite` | Generate an invite link |
+
+### Memory
+
+| 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 |
+
+### Games — 27 Multiplayer & Solo Games
+
+| Tool | What it does |
+|------|-------------|
+| `vibe_game` | All games via one tool. Multiplayer (tictactoe, chess), solo (hangman, rps, memory), party (twotruths, werewolf), AI (tictactoe-ai), collaborative (drawing, crossword, wordassociation, wordchain, storybuilder) |
+
+### Artifacts
+
+| Tool | What it does |
+|------|-------------|
+| `vibe_create_artifact` | Create a shareable guide, workspace, or learning |
+| `vibe_view_artifact` | View shared artifacts |
+
+### File Coordination
+
+| Tool | What it does |
+|------|-------------|
+| `vibe_reserve` | Reserve files for editing |
+| `vibe_release` | Release file reservations |
+| `vibe_reservations` | List active file reservations |
+
+### Infrastructure
+
+| Tool | What it does |
+|------|-------------|
+| `vibe_handoff` | Create an AIRC context handoff for another tool |
+| `vibe_report` | Report issues or inappropriate behavior |
+| `vibe_suggest_tags` | Get tag suggestions for your profile |
+
+### Diagnostics
+
+| Tool | What it does |
+|------|-------------|
+| `vibe_help` | Show available commands |
+| `vibe_doctor` | Full health check — API, auth, storage, presence |
+| `vibe_update` | Check for and apply updates |
+
+### Settings
+
+| Tool | What it does |
+|------|-------------|
+| `vibe_settings` | Configure preferences |
+| `vibe_notifications` | Configure notification channels |
+| `vibe_presence_agent` | Background presence agent |
+| `vibe_mute` | Mute a user |
+| `vibe_summarize` | Summarize session context |
+
+## 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
 
-## Features
+## Troubleshooting
 
-- **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
+**"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
 
-## Commands
+**"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
 
-Once installed, use these in Claude Code:
+**"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
 
-| 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 |
+**"I see 'Unknown tool' errors"**
+- You may be running an older version. Run `vibe update` or reinstall: `npm install -g slashvibe-mcp`
 
-## API
+## Configuration
 
-The MCP server connects to `slashvibe.dev` for:
-- User presence and discovery
-- Message routing
-- Identity verification
+Config lives at `~/.vibecodings/config.json` (primary) or `~/.vibe/config.json` (legacy fallback).
 
-## Related
+Local message database: `~/.vibecodings/sessions.db` (SQLite, shared with Vibe Terminal desktop app).
 
-- [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
+## Contributing
+
+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)
 
 ## License
 
-MIT
+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)

package/auto-update.js

@@ -3,14 +3,16 @@
  * Checks for updates and prompts user to update
  */
 
-const { exec } = require('child_process');
-const { promisify } = require('util');
-const fs = require('fs').promises;
-const path = require('path');
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
 
 const execAsync = promisify(exec);
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
-async function checkForUpdates() {
+export async function checkForUpdates() {
   try {
     // Read local version
     const versionPath = path.join(__dirname, 'version.json');
@@ -45,7 +47,7 @@ async function checkForUpdates() {
   }
 }
 
-async function performUpdate() {
+export async function performUpdate() {
   try {
     const repoPath = path.join(__dirname, '..');
 
@@ -82,7 +84,7 @@ async function performUpdate() {
   }
 }
 
-function compareVersions(v1, v2) {
+export function compareVersions(v1, v2) {
   const parts1 = v1.split('.').map(Number);
   const parts2 = v2.split('.').map(Number);
 
@@ -94,7 +96,7 @@ function compareVersions(v1, v2) {
   return 0;
 }
 
-function formatUpdateNotification(update) {
+export function formatUpdateNotification(update) {
   if (!update) return null;
 
   let message = `\n${'='.repeat(60)}\n`;
@@ -121,10 +123,3 @@ function formatUpdateNotification(update) {
 
   return message;
 }
-
-module.exports = {
-  checkForUpdates,
-  performUpdate,
-  compareVersions,
-  formatUpdateNotification
-};

package/config.js

@@ -10,8 +10,8 @@ const path = require('path');
 
 const VIBE_DIR = path.join(process.env.HOME, '.vibe');
 const VIBECODINGS_DIR = path.join(process.env.HOME, '.vibecodings');
-const PRIMARY_CONFIG = path.join(VIBECODINGS_DIR, 'config.json');  // Primary
-const FALLBACK_CONFIG = path.join(VIBE_DIR, 'config.json');        // Fallback
+const PRIMARY_CONFIG = path.join(VIBECODINGS_DIR, 'config.json'); // Primary
+const FALLBACK_CONFIG = path.join(VIBE_DIR, 'config.json'); // Fallback
 const CONFIG_FILE = PRIMARY_CONFIG;
 
 function ensureDir() {
@@ -70,15 +70,17 @@ function save(config) {
     // Notification level
     notifications: config.notifications || existing.notifications || null,
     // GitHub Activity settings
-    github_activity_enabled: config.github_activity_enabled !== undefined ? config.github_activity_enabled : existing.github_activity_enabled,
+    github_activity_enabled:
+      config.github_activity_enabled !== undefined ? config.github_activity_enabled : existing.github_activity_enabled,
     github_activity_privacy: config.github_activity_privacy || existing.github_activity_privacy || null,
-    // OAuth token (persisted across MCP process restarts)
-    authToken: config.authToken || config.privyToken || existing.authToken || existing.privyToken || null,
+    // Privy OAuth token (persisted across MCP process restarts)
+    privyToken: config.privyToken || existing.privyToken || null,
     authMethod: config.authMethod || existing.authMethod || null
   };
   fs.writeFileSync(PRIMARY_CONFIG, JSON.stringify(data, null, 2));
 }
 
+/** @returns {string|null} Current user handle */
 function getHandle() {
   // Prefer session-specific handle over shared config
   const sessionHandle = getSessionHandle();
@@ -88,6 +90,7 @@ function getHandle() {
   return config.handle || null;
 }
 
+/** @returns {string|null} Current user one-liner */
 function getOneLiner() {
   // Prefer session-specific one_liner over shared config
   const sessionOneLiner = getSessionOneLiner();
@@ -97,6 +100,7 @@ function getOneLiner() {
   return config.one_liner || null;
 }
 
+/** @returns {boolean} Whether user identity is set */
 function isInitialized() {
   // Check session first, then shared config
   const sessionHandle = getSessionHandle();
@@ -109,6 +113,7 @@ function isInitialized() {
 // Now stores full identity (handle + one_liner), not just sessionId
 const SESSION_FILE = path.join(VIBECODINGS_DIR, `.session_${process.pid}`);
 
+/** @returns {string} New session ID (sess_*) */
 function generateSessionId() {
   return 'sess_' + Date.now().toString(36) + Math.random().toString(36).substring(2, 10);
 }
@@ -217,52 +222,43 @@ function getAuthToken() {
 
   // Fall back to shared config (persisted across MCP process restarts)
   const cfg = load();
-  return cfg?.authToken || cfg?.privyToken || null;
+  return cfg?.privyToken || null;
 }
 
 /**
- * Save auth token (used after browser OAuth flow)
- * @param {string} token - JWT access token from GitHub OAuth
+ * Save Privy JWT token (used after browser OAuth flow)
+ * @param {string} token - Privy access token
  */
-function saveAuthToken(token) {
+function savePrivyToken(token) {
   // Save to session data
   const data = getSessionData() || {};
   saveSessionData({
     ...data,
     sessionId: data.sessionId || generateSessionId(),
     token,
-    authMethod: 'github'  // Track that this is GitHub OAuth
+    authMethod: 'privy' // Track that this is a Privy token
   });
 
   // Also save to shared config for persistence across MCP restarts
   const cfg = load();
-  cfg.authToken = token;
-  cfg.authMethod = 'github';
+  cfg.privyToken = token;
+  cfg.authMethod = 'privy';
   save(cfg);
 }
 
-// Backwards compatibility alias
-const savePrivyToken = saveAuthToken;
-
 /**
- * Check if user has OAuth auth (vs legacy keypair)
- * Accepts 'github', 'privy', and 'browser' as valid auth methods (backwards compat)
+ * Check if user has Privy auth (vs legacy keypair)
  */
-function hasOAuth() {
-  const validAuthMethods = ['github', 'privy', 'browser'];
-
+function hasPrivyAuth() {
   const data = getSessionData();
-  if (validAuthMethods.includes(data?.authMethod) && data?.token) return true;
+  if (data?.authMethod === 'privy' && data?.token) return true;
 
   const cfg = load();
-  return validAuthMethods.includes(cfg?.authMethod) && (cfg?.authToken || cfg?.privyToken);
+  return cfg?.authMethod === 'privy' && cfg?.privyToken;
 }
 
-// Backwards compatibility alias
-const hasPrivyAuth = hasOAuth;
-
 /**
- * Remove keypair after migration to GitHub OAuth
+ * Remove keypair after migration to Privy
  * Clears private key from config (security improvement)
  */
 function removeKeypair() {
@@ -368,7 +364,7 @@ function setGithubActivityPrivacy(level) {
   save(config);
 }
 
-// API URL — central endpoint for all API calls
+/** @returns {string} API base URL */
 function getApiUrl() {
   return process.env.VIBE_API_URL || 'https://www.slashvibe.dev';
 }
@@ -380,10 +376,22 @@ function getApiUrl() {
 // ─────────────────────────────────────────────────────────────
 const sessionState = {};
 
+/**
+ * Get ephemeral session state value
+ * @param {string} key - State key
+ * @param {*} [defaultValue=null] - Default if not set
+ * @returns {*} Stored value or default
+ */
 function get(key, defaultValue = null) {
   return sessionState[key] !== undefined ? sessionState[key] : defaultValue;
 }
 
+/**
+ * Set ephemeral session state value
+ * @param {string} key - State key
+ * @param {*} value - Value to store
+ * @returns {*} The stored value
+ */
 function set(key, value) {
   sessionState[key] = value;
   return value;
@@ -418,10 +426,7 @@ module.exports = {
   getGithubActivityPrivacy,
   setGithubActivityPrivacy,
   getApiUrl,
-  // OAuth helpers
-  saveAuthToken,
-  hasOAuth,
-  // Backwards compatibility aliases
+  // Privy OAuth helpers
   savePrivyToken,
   hasPrivyAuth,
   removeKeypair,

package/crypto.js

@@ -106,12 +106,7 @@ function verify(obj, publicKeyBase64) {
     });
 
     // Verify
-    return crypto.verify(
-      null,
-      Buffer.from(canonical, 'utf8'),
-      publicKey,
-      Buffer.from(signature, 'base64')
-    );
+    return crypto.verify(null, Buffer.from(canonical, 'utf8'), publicKey, Buffer.from(signature, 'base64'));
   } catch (e) {
     console.error('[crypto] Verification failed:', e.message);
     return false;

package/debug.js

@@ -0,0 +1,12 @@
+/**
+ * Debug logging — conditional on VIBE_DEBUG env var
+ *
+ * @param {...*} args Arguments to log
+ */
+function debug(...args) {
+  if (process.env.VIBE_DEBUG === 'true') {
+    console.error(...args);
+  }
+}
+
+module.exports = debug;