@vibescope/mcp-server 0.0.1 → 0.2.0

package/README.md

@@ -1,98 +1,113 @@
-# @vibescope/mcp-server
-
-MCP server for Vibescope - enables AI agents to track project progress, tasks, blockers, and decisions.
-
-## Installation Options
-
-### Option 1: From GitHub Package Registry (Recommended)
-
-```bash
-# Authenticate with GitHub (one-time)
-npm login --registry=https://npm.pkg.github.com
-
-# Install globally
-npm install -g @vibescope/mcp-server --registry=https://npm.pkg.github.com
-```
-
-### Option 2: From Source (Local Development)
-
-```bash
-# Clone the repo
-git clone https://github.com/Nonatomic/Vibescope.git
-cd Vibescope
-
-# Install dependencies and build
-pnpm install
-pnpm build
-
-# Link globally
-cd packages/mcp-server
-npm link
-```
-
-### Option 3: Direct Path (No Installation)
-
-Point your MCP config directly to the built file:
-
-```json
-{
-  "mcpServers": {
-    "vibescope": {
-      "command": "node",
-      "args": ["/path/to/Vibescope/packages/mcp-server/dist/index.js"],
-      "env": {
-        "VIBESCOPE_API_KEY": "your-api-key"
-      }
-    }
-  }
-}
-```
-
-## Configuration
-
-Add to your Claude Code MCP config (`~/.claude/claude_desktop_config.json` or project `.claude/settings.local.json`):
-
-```json
-{
-  "mcpServers": {
-    "vibescope": {
-      "command": "vibescope-mcp",
-      "env": {
-        "VIBESCOPE_API_KEY": "your-api-key"
-      }
-    }
-  }
-}
-```
-
-## Getting an API Key
-
-1. Sign up at [vibescope.dev](https://vibescope.dev)
-2. Go to Settings
-3. Generate an API key
-
-## Available Tools
-
-The MCP server provides these tools for AI agents:
-
-| Tool | Description |
-|------|-------------|
-| `start_work_session` | Initialize a work session for a project |
-| `get_project_context` | Get full project context including tasks, blockers, and user updates |
-| `get_tasks` | List tasks, optionally filtered by status |
-| `get_next_task` | Get the highest priority pending task |
-| `add_task` | Create a new task |
-| `update_task` | Update task status, progress, or details |
-| `complete_task` | Mark a task as completed |
-| `log_progress` | Log a progress update |
-| `add_blocker` | Flag a blocker needing human input |
-| `resolve_blocker` | Mark a blocker as resolved |
-| `log_decision` | Record an architectural or technical decision |
-| `add_idea` | Record an improvement idea |
-| `create_project` | Create a new project |
-| `update_project` | Update project details |
-
-## Rate Limits
-
-- 60 requests per minute per API key
-- Warning shown when quota drops below 10 requests
+# @vibescope/mcp-server
+
+MCP server for Vibescope - enables AI agents to track project progress, tasks, blockers, and decisions.
+
+## Installation
+
+### Option 1: npx (Recommended - No Installation)
+
+Use directly in your MCP config without installing:
+
+```json
+{
+  "mcpServers": {
+    "vibescope": {
+      "command": "npx",
+      "args": ["-y", "-p", "@vibescope/mcp-server", "vibescope-mcp"],
+      "env": {
+        "VIBESCOPE_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+### Option 2: Global Install
+
+```bash
+npm install -g @vibescope/mcp-server
+```
+
+Then configure:
+
+```json
+{
+  "mcpServers": {
+    "vibescope": {
+      "command": "vibescope-mcp",
+      "env": {
+        "VIBESCOPE_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+### Option 3: From Source (Development)
+
+```bash
+# Clone the repo
+git clone https://github.com/Nonatomic/Vibescope.git
+cd Vibescope
+
+# Install dependencies and build
+pnpm install
+pnpm build
+
+# Point your MCP config to the built file
+```
+
+```json
+{
+  "mcpServers": {
+    "vibescope": {
+      "command": "node",
+      "args": ["/path/to/Vibescope/packages/mcp-server/dist/index.js"],
+      "env": {
+        "VIBESCOPE_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+## Quick Start with Claude Code
+
+The easiest way to get started:
+
+```bash
+claude mcp add vibescope npx @vibescope/mcp-server \
+  --env VIBESCOPE_API_KEY=your_key
+```
+
+## Getting an API Key
+
+1. Sign up at [vibescope.dev](https://vibescope.dev)
+2. Go to Settings
+3. Generate an API key
+
+## Available Tools
+
+The MCP server provides these tools for AI agents:
+
+| Tool | Description |
+|------|-------------|
+| `start_work_session` | Initialize a work session for a project |
+| `get_project_context` | Get full project context including tasks, blockers, and user updates |
+| `get_tasks` | List tasks, optionally filtered by status |
+| `get_next_task` | Get the highest priority pending task |
+| `add_task` | Create a new task |
+| `update_task` | Update task status, progress, or details |
+| `complete_task` | Mark a task as completed |
+| `log_progress` | Log a progress update |
+| `add_blocker` | Flag a blocker needing human input |
+| `resolve_blocker` | Mark a blocker as resolved |
+| `log_decision` | Record an architectural or technical decision |
+| `add_idea` | Record an improvement idea |
+| `create_project` | Create a new project |
+| `update_project` | Update project details |
+
+## Rate Limits
+
+- 60 requests per minute per API key
+- Warning shown when quota drops below 10 requests