vibe-annotations-server 0.1.5 → 0.1.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Raphael Regnier
+
+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,35 +1,154 @@
 # vibe-annotations-server
 
-This is the npm wrapper for [vibe-annotations-server](https://github.com/RaphaelRegnier/vibe-annotations-server), the MCP server component of Vibe Annotations.
+Global MCP server for Vibe Annotations browser extension.
 
-## Quick Start
+## Installation
 
 ```bash
-npx vibe-annotations-server
+npm install -g vibe-annotations-server
 ```
 
-This will automatically:
-1. Install the latest version from GitHub if not already installed
-2. Start the vibe-annotations server
+## Usage
 
-## What is Vibe Annotations?
+### Start the server
 
-AI-powered development annotations for localhost projects. Drop comments on your localhost apps and let your AI coding agent implement the fixes automatically.
+```bash
+vibe-annotations-server start
+```
+
+The server will run in the background on port 3846.
+
+### Stop the server
+
+```bash
+vibe-annotations-server stop
+```
+
+### Check server status
+
+```bash
+vibe-annotations-server status
+```
+
+### Restart the server
+
+```bash
+vibe-annotations-server restart
+```
+
+### View logs
+
+```bash
+vibe-annotations-server logs
+# or follow logs
+vibe-annotations-server logs -f
+```
+
+## AI Coding Agent Integration
+
+After starting the server, connect it to your AI coding agent. The server supports multiple agents via the MCP (Model Context Protocol) using SSE (Server-Sent Events) transport.
+
+### Claude Code
+
+In your project directory, run:
+
+```bash
+claude mcp add --transport sse vibe-annotations http://127.0.0.1:3846/sse
+```
+
+### Cursor
+
+1. Open Cursor → Settings → Cursor Settings
+2. Go to the Tools & Integrations tab
+3. Click + Add new global MCP server
+4. Enter the following configuration and save:
+
+```json
+{
+  "mcpServers": {
+    "vibe-annotations": {
+      "url": "http://127.0.0.1:3846/sse"
+    }
+  }
+}
+```
+
+### Windsurf
+
+1. Navigate to Windsurf → Settings → Advanced Settings
+2. Scroll down to the Cascade section
+3. Click "Add new server" or edit the raw JSON config file
+4. Add the following configuration:
+
+```json
+{
+  "mcpServers": {
+    "vibe-annotations": {
+      "serverUrl": "http://127.0.0.1:3846/sse"
+    }
+  }
+}
+```
+
+### VS Code
+
+1. Install an AI extension that supports MCP (like GitHub Copilot Chat or Continue)
+2. Go to Code → Settings → Settings or use the shortcut ⌘,
+3. In the search bar, type "MCP"
+4. Look for MCP server configurations in your AI extension settings
+5. Add the following SSE configuration:
 
-- 🏠 Works on localhost development projects
-- 🤖 Integrates with AI coding agents via MCP
-- ⚡ Instant visual feedback system
-- 📑 Multi-page annotation support
+```json
+{
+  "mcpServers": {
+    "vibe-annotations": {
+      "type": "sse",
+      "url": "http://127.0.0.1:3846/sse"
+    }
+  }
+}
+```
+
+**Note:** MCP support varies by AI extension. Check your extension's documentation for specific setup instructions.
+
+### Other Editors
+
+Other code editors and tools that support SSE (Server-Sent Events) can also connect to the Vibe Annotations MCP server. If you're using a different editor or tool, check its documentation to confirm it supports SSE-based communication. If it does, you can manually add the server using this configuration:
+
+```json
+{
+  "mcpServers": {
+    "vibe-annotations": {
+      "url": "http://127.0.0.1:3846/sse"
+    }
+  }
+}
+```
 
-## Documentation
+**Note:** The Vibe Annotations MCP server communicates over the SSE protocol. Use your editor's steps for setting up an SSE-compatible MCP server, and use the URL: `http://127.0.0.1:3846/sse`
 
-For full documentation, Chrome extension installation, and setup instructions, visit:
-https://github.com/RaphaelRegnier/vibe-annotations
+## Architecture
 
-## Source Code
+The server provides:
+- **SSE Endpoint** (`/sse`): For AI coding agent MCP connections
+- **HTTP API** (`/api/annotations`): For Chrome extension communication
+- **Health Check** (`/health`): For status monitoring
 
-The actual server source code is maintained at:
-https://github.com/RaphaelRegnier/vibe-annotations-server
+Data is stored in `~/.vibe-annotations/annotations.json`.
+
+## Development
+
+```bash
+# Clone the repository
+git clone <repo-url>
+cd vibe-annotations-server
+
+# Install dependencies
+npm install
+
+# Run in development mode
+npm run dev
+```
 
 ## License
 

package/bin/cli.js

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { spawn, exec } from 'child_process';
+import { promisify } from 'util';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync, openSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import chalk from 'chalk';
+import { homedir } from 'os';
+import fs from 'fs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Read version from package.json automatically
+const packageJson = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf8'));
+
+const execAsync = promisify(exec);
+const program = new Command();
+
+// Configuration paths
+const CONFIG_DIR = join(homedir(), '.vibe-annotations');
+const PID_FILE = join(CONFIG_DIR, 'server.pid');
+const LOG_FILE = join(CONFIG_DIR, 'server.log');
+const PORT = 3846;
+
+// Ensure config directory exists
+if (!existsSync(CONFIG_DIR)) {
+  mkdirSync(CONFIG_DIR, { recursive: true });
+}
+
+// Helper functions
+function isServerRunning() {
+  if (!existsSync(PID_FILE)) {
+    return false;
+  }
+  
+  try {
+    const pid = readFileSync(PID_FILE, 'utf8').trim();
+    process.kill(parseInt(pid), 0); // Check if process exists
+    return true;
+  } catch (e) {
+    // Process doesn't exist
+    if (existsSync(PID_FILE)) {
+      // Clean up stale PID file
+      unlinkSync(PID_FILE);
+    }
+    return false;
+  }
+}
+
+async function checkPort() {
+  try {
+    const response = await fetch(`http://127.0.0.1:${PORT}/health`);
+    return response.ok;
+  } catch (error) {
+    return false;
+  }
+}
+
+// Commands
+program
+  .name('vibe-annotations-server')
+  .description('Global MCP server for Vibe Annotations browser extension')
+  .version(packageJson.version);
+
+program
+  .command('start')
+  .description('Start the Vibe Annotations server')
+  .option('-d, --daemon', 'Run as daemon (background process)')
+  .action(async (options) => {
+    if (isServerRunning()) {
+      console.log(chalk.yellow('✓ Server is already running'));
+      console.log(chalk.gray(`  Port: ${PORT}`));
+      console.log(chalk.gray(`  PID: ${readFileSync(PID_FILE, 'utf8').trim()}`));
+      return;
+    }
+
+    console.log(chalk.blue('Starting Vibe Annotations server...'));
+
+    const serverPath = join(dirname(__dirname), 'lib', 'server.js');
+    
+    if (options.daemon) {
+      // Run as daemon
+      const out = fs.openSync(LOG_FILE, 'a');
+      const err = fs.openSync(LOG_FILE, 'a');
+      
+      const child = spawn('node', [serverPath], {
+        detached: true,
+        stdio: ['ignore', out, err],
+        env: { ...process.env, NODE_ENV: 'production' }
+      });
+      
+      child.unref();
+      writeFileSync(PID_FILE, child.pid.toString());
+      
+      // Wait for server to start
+      let attempts = 0;
+      while (attempts < 10) {
+        if (await checkPort()) {
+          console.log(chalk.green('✅ Vibe Annotations server running on http://127.0.0.1:3846/sse'));
+          console.log(chalk.gray(`   PID: ${child.pid}`));
+          console.log(chalk.gray(`   Logs: ${LOG_FILE}`));
+          break;
+        }
+        await new Promise(resolve => setTimeout(resolve, 500));
+        attempts++;
+      }
+      
+      if (attempts >= 10) {
+        console.log(chalk.red('❌ Failed to start server. Check logs at:'));
+        console.log(chalk.gray(`   ${LOG_FILE}`));
+      }
+    } else {
+      // Run in foreground
+      const child = spawn('node', [serverPath], {
+        stdio: 'inherit',
+        env: { ...process.env, NODE_ENV: 'production' }
+      });
+      
+      writeFileSync(PID_FILE, child.pid.toString());
+      
+      child.on('exit', () => {
+        if (existsSync(PID_FILE)) {
+          unlinkSync(PID_FILE);
+        }
+      });
+    }
+  });
+
+program
+  .command('stop')
+  .description('Stop the Vibe Annotations server')
+  .action(() => {
+    if (!isServerRunning()) {
+      console.log(chalk.yellow('Server is not running'));
+      return;
+    }
+    
+    try {
+      const pid = readFileSync(PID_FILE, 'utf8').trim();
+      process.kill(parseInt(pid), 'SIGTERM');
+      
+      if (existsSync(PID_FILE)) {
+        unlinkSync(PID_FILE);
+      }
+      
+      console.log(chalk.green('✅ Server stopped'));
+    } catch (error) {
+      console.log(chalk.red('❌ Failed to stop server:'), error.message);
+    }
+  });
+
+program
+  .command('restart')
+  .description('Restart the Vibe Annotations server')
+  .action(async () => {
+    console.log(chalk.blue('Restarting server...'));
+    
+    // Stop if running
+    if (isServerRunning()) {
+      try {
+        const pid = readFileSync(PID_FILE, 'utf8').trim();
+        process.kill(parseInt(pid), 'SIGTERM');
+        
+        if (existsSync(PID_FILE)) {
+          unlinkSync(PID_FILE);
+        }
+        
+        // Wait for process to stop
+        await new Promise(resolve => setTimeout(resolve, 1000));
+      } catch (error) {
+        console.log(chalk.yellow('Warning:'), error.message);
+      }
+    }
+    
+    // Start with daemon flag
+    program.parse(['node', 'cli.js', 'start', '--daemon'], { from: 'user' });
+  });
+
+program
+  .command('status')
+  .description('Check server status')
+  .action(async () => {
+    const running = isServerRunning();
+    const portAvailable = await checkPort();
+    
+    if (running && portAvailable) {
+      console.log(chalk.green('✅ Server is running'));
+      console.log(chalk.gray(`   PID: ${readFileSync(PID_FILE, 'utf8').trim()}`));
+      console.log(chalk.gray(`   Port: ${PORT}`));
+      console.log(chalk.gray(`   URL: http://127.0.0.1:${PORT}/sse`));
+    } else if (running && !portAvailable) {
+      console.log(chalk.yellow('⚠️  Server process exists but is not responding'));
+      console.log(chalk.gray('   Try running: vibe-annotations-server restart'));
+    } else {
+      console.log(chalk.gray('○ Server is not running'));
+    }
+  });
+
+program
+  .command('logs')
+  .description('View server logs')
+  .option('-f, --follow', 'Follow log output')
+  .option('-n, --lines <number>', 'Number of lines to show', '50')
+  .action((options) => {
+    if (!existsSync(LOG_FILE)) {
+      console.log(chalk.gray('No logs available yet'));
+      return;
+    }
+    
+    if (options.follow) {
+      // Use tail -f
+      const tail = spawn('tail', ['-f', LOG_FILE], { stdio: 'inherit' });
+      
+      process.on('SIGINT', () => {
+        tail.kill();
+        process.exit();
+      });
+    } else {
+      // Show last N lines
+      const tail = spawn('tail', ['-n', options.lines, LOG_FILE], { stdio: 'inherit' });
+    }
+  });
+
+program.parse(process.argv);