@kanbodev/mcp 1.1.8 → 1.2.0

package/docs/SETUP.md

@@ -1,254 +1,254 @@
-# Kanbo MCP Setup Guide
-
-This guide covers two ways to set up the Kanbo MCP server for use with AI assistants like Claude.
-
----
-
-## Option 1: Install via npm (Recommended)
-
-One command to authenticate and register the MCP server with your editors.
-
-### Step 1: Login
-
-```bash
-npx @kanbodev/mcp login
-```
-
-This will:
-1. Open your browser to sign in with your Kanbo account
-2. Let you select which organization to use
-3. Automatically create and store an API key
-4. **Auto-register the MCP server** with detected editors (VS Code, VS Code Insiders, Cursor, Windsurf, Claude Code, Claude Desktop, Claude Code CLI)
-
-You'll see output like:
-
-```
-  ✓ Successfully authenticated!
-
-    Email: you@example.com
-    Organization: My Team
-    API Key: kanbo_pat_a1b2...
-
-  Config saved to: ~/.kanbo/config.json
-
-  MCP server registered with:
-    ✓ Registered in VS Code
-    ✓ Registered via Claude Code CLI
-
-  Reload your editor to activate the Kanbo MCP server.
-```
-
-### Step 2: Reload your editor
-
-Reload your editor window and you're ready to go. No manual config needed.
-
-### Re-register with new editors
-
-If you install a new editor after logging in, run:
-
-```bash
-npx @kanbodev/mcp install
-```
-
-This re-detects editors and registers the MCP server where needed. It's idempotent — already-registered editors are skipped.
-
-### Other CLI Commands
-
-```bash
-npx @kanbodev/mcp install   # Register MCP server with detected editors
-npx @kanbodev/mcp whoami    # Check current authentication status
-npx @kanbodev/mcp logout    # Remove stored credentials
-npx @kanbodev/mcp help      # Show all available commands
-```
-
----
-
-## Option 2: Manual Setup with API Key
-
-If you prefer to manage your API key manually, or need to configure multiple environments.
-
-### Step 1: Create an API Key
-
-1. Go to your Kanbo dashboard
-2. Navigate to **Settings → API Keys**
-3. Click **Create API Key**
-4. Give it a name (e.g., "Claude Desktop")
-5. Copy the token (it will only be shown once!)
-
-The token looks like: `kanbo_pat_a1b2c3d4e5f6...`
-
-### Step 2: Configure Claude Desktop
-
-Add Kanbo to your Claude Desktop configuration with the API key:
-
-**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
-**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
-
-```json
-{
-  "mcpServers": {
-    "kanbo": {
-      "command": "npx",
-      "args": ["@kanbodev/mcp"],
-      "env": {
-        "KANBO_API_KEY": "kanbo_pat_your_token_here"
-      }
-    }
-  }
-}
-```
-
-### Step 3: Restart Claude Desktop
-
-Close and reopen Claude Desktop to load the new configuration.
-
----
-
-## Configuration Options
-
-### Environment Variables
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `KANBO_API_KEY` | Your Personal Access Token | (from ~/.kanbo/config.json) |
-| `KANBO_API_URL` | API server URL | `https://api.kanbo.dev` |
-| `KANBO_ORG_ID` | Override organization ID | (from token) |
-
-### Priority Order
-
-The MCP server loads configuration in this order (first found wins):
-
-1. **Environment variables** - Set in Claude Desktop config or shell
-2. **Config file** - `~/.kanbo/config.json` (created by `login` command)
-
-This means you can:
-- Use `npx @kanbodev/mcp login` for easy setup
-- Override with env vars for specific use cases
-
----
-
-## Using with Other AI Tools
-
-> **Note:** `npx @kanbodev/mcp login` auto-registers with VS Code, VS Code Insiders, Cursor, Windsurf, Claude Code, Claude Desktop, and Claude Code CLI. The manual configs below are only needed if auto-registration didn't detect your editor.
-
-### Cursor
-
-Add to `~/.cursor/mcp.json`:
-
-```json
-{
-  "servers": {
-    "kanbodev": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["@kanbodev/mcp"]
-    }
-  }
-}
-```
-
-### VS Code
-
-See the full [VS Code setup guide](VSCODE.md) for native MCP support (v1.99+), Claude Code extension, and Cursor/Windsurf.
-
-### Windsurf
-
-Add to `~/.codeium/windsurf/mcp_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "kanbodev": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["@kanbodev/mcp"]
-    }
-  }
-}
-```
-
-### Claude Code (VS Code Extension)
-
-Add to `~/.claude/settings.json`:
-
-```json
-{
-  "mcpServers": {
-    "kanbodev": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["@kanbodev/mcp"]
-    }
-  }
-}
-```
-
-### Claude Code CLI
-
-```bash
-claude mcp add kanbodev -- npx @kanbodev/mcp
-```
-
----
-
-## Troubleshooting
-
-### "Not authenticated" error
-
-Run `npx @kanbodev/mcp whoami` to check your auth status. If not logged in:
-
-```bash
-npx @kanbodev/mcp login
-```
-
-### "Invalid API key" error
-
-Your API key may have been revoked. Create a new one:
-
-1. Go to Kanbo dashboard → Settings → API Keys
-2. Revoke the old key
-3. Create a new one
-4. Update your configuration
-
-### Connection issues
-
-Check the API URL is correct:
-
-```bash
-# Test with explicit URL
-KANBO_API_URL=https://api.kanbo.dev npx @kanbodev/mcp whoami
-```
-
-### Clear stored credentials
-
-```bash
-npx @kanbodev/mcp logout
-```
-
-Or manually delete the config file:
-
-```bash
-rm ~/.kanbo/config.json
-```
-
----
-
-## Security Notes
-
-- **API keys are stored securely** in `~/.kanbo/config.json` with owner-only permissions (0600)
-- **Never commit API keys** to version control
-- **Revoke unused keys** from the Kanbo dashboard
-- **Each key is organization-scoped** - it can only access data in that organization
-
----
-
-## Quick Reference
-
-| Task | Command |
-|------|---------|
-| Authenticate + register | `npx @kanbodev/mcp login` |
-| Register with editors | `npx @kanbodev/mcp install` |
-| Check status | `npx @kanbodev/mcp whoami` |
-| Logout | `npx @kanbodev/mcp logout` |
-| Start server | `npx @kanbodev/mcp` |
-| Show help | `npx @kanbodev/mcp help` |
+# Kanbo MCP Setup Guide
+
+This guide covers two ways to set up the Kanbo MCP server for use with AI assistants like Claude.
+
+---
+
+## Option 1: Install via npm (Recommended)
+
+One command to authenticate and register the MCP server with your editors.
+
+### Step 1: Login
+
+```bash
+npx @kanbodev/mcp login
+```
+
+This will:
+1. Open your browser to sign in with your Kanbo account
+2. Let you select which organization to use
+3. Automatically create and store an API key
+4. **Auto-register the MCP server** with detected editors (VS Code, VS Code Insiders, Cursor, Windsurf, Claude Code, Claude Desktop, Claude Code CLI)
+
+You'll see output like:
+
+```
+  ✓ Successfully authenticated!
+
+    Email: you@example.com
+    Organization: My Team
+    API Key: kanbo_pat_a1b2...
+
+  Config saved to: ~/.kanbo/config.json
+
+  MCP server registered with:
+    ✓ Registered in VS Code
+    ✓ Registered via Claude Code CLI
+
+  Reload your editor to activate the Kanbo MCP server.
+```
+
+### Step 2: Reload your editor
+
+Reload your editor window and you're ready to go. No manual config needed.
+
+### Re-register with new editors
+
+If you install a new editor after logging in, run:
+
+```bash
+npx @kanbodev/mcp install
+```
+
+This re-detects editors and registers the MCP server where needed. It's idempotent — already-registered editors are skipped.
+
+### Other CLI Commands
+
+```bash
+npx @kanbodev/mcp install   # Register MCP server with detected editors
+npx @kanbodev/mcp whoami    # Check current authentication status
+npx @kanbodev/mcp logout    # Remove stored credentials
+npx @kanbodev/mcp help      # Show all available commands
+```
+
+---
+
+## Option 2: Manual Setup with API Key
+
+If you prefer to manage your API key manually, or need to configure multiple environments.
+
+### Step 1: Create an API Key
+
+1. Go to your Kanbo dashboard
+2. Navigate to **Settings → API Keys**
+3. Click **Create API Key**
+4. Give it a name (e.g., "Claude Desktop")
+5. Copy the token (it will only be shown once!)
+
+The token looks like: `kanbo_pat_a1b2c3d4e5f6...`
+
+### Step 2: Configure Claude Desktop
+
+Add Kanbo to your Claude Desktop configuration with the API key:
+
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "kanbo": {
+      "command": "npx",
+      "args": ["@kanbodev/mcp"],
+      "env": {
+        "KANBO_API_KEY": "kanbo_pat_your_token_here"
+      }
+    }
+  }
+}
+```
+
+### Step 3: Restart Claude Desktop
+
+Close and reopen Claude Desktop to load the new configuration.
+
+---
+
+## Configuration Options
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `KANBO_API_KEY` | Your Personal Access Token | (from ~/.kanbo/config.json) |
+| `KANBO_API_URL` | API server URL | `https://api.kanbo.dev` |
+| `KANBO_ORG_ID` | Override organization ID | (from token) |
+
+### Priority Order
+
+The MCP server loads configuration in this order (first found wins):
+
+1. **Environment variables** - Set in Claude Desktop config or shell
+2. **Config file** - `~/.kanbo/config.json` (created by `login` command)
+
+This means you can:
+- Use `npx @kanbodev/mcp login` for easy setup
+- Override with env vars for specific use cases
+
+---
+
+## Using with Other AI Tools
+
+> **Note:** `npx @kanbodev/mcp login` auto-registers with VS Code, VS Code Insiders, Cursor, Windsurf, Claude Code, Claude Desktop, and Claude Code CLI. The manual configs below are only needed if auto-registration didn't detect your editor.
+
+### Cursor
+
+Add to `~/.cursor/mcp.json`:
+
+```json
+{
+  "servers": {
+    "kanbodev": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["@kanbodev/mcp"]
+    }
+  }
+}
+```
+
+### VS Code
+
+See the full [VS Code setup guide](VSCODE.md) for native MCP support (v1.99+), Claude Code extension, and Cursor/Windsurf.
+
+### Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "kanbodev": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["@kanbodev/mcp"]
+    }
+  }
+}
+```
+
+### Claude Code (VS Code Extension)
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "kanbodev": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["@kanbodev/mcp"]
+    }
+  }
+}
+```
+
+### Claude Code CLI
+
+```bash
+claude mcp add kanbodev -- npx @kanbodev/mcp
+```
+
+---
+
+## Troubleshooting
+
+### "Not authenticated" error
+
+Run `npx @kanbodev/mcp whoami` to check your auth status. If not logged in:
+
+```bash
+npx @kanbodev/mcp login
+```
+
+### "Invalid API key" error
+
+Your API key may have been revoked. Create a new one:
+
+1. Go to Kanbo dashboard → Settings → API Keys
+2. Revoke the old key
+3. Create a new one
+4. Update your configuration
+
+### Connection issues
+
+Check the API URL is correct:
+
+```bash
+# Test with explicit URL
+KANBO_API_URL=https://api.kanbo.dev npx @kanbodev/mcp whoami
+```
+
+### Clear stored credentials
+
+```bash
+npx @kanbodev/mcp logout
+```
+
+Or manually delete the config file:
+
+```bash
+rm ~/.kanbo/config.json
+```
+
+---
+
+## Security Notes
+
+- **API keys are stored securely** in `~/.kanbo/config.json` with owner-only permissions (0600)
+- **Never commit API keys** to version control
+- **Revoke unused keys** from the Kanbo dashboard
+- **Each key is organization-scoped** - it can only access data in that organization
+
+---
+
+## Quick Reference
+
+| Task | Command |
+|------|---------|
+| Authenticate + register | `npx @kanbodev/mcp login` |
+| Register with editors | `npx @kanbodev/mcp install` |
+| Check status | `npx @kanbodev/mcp whoami` |
+| Logout | `npx @kanbodev/mcp logout` |
+| Start server | `npx @kanbodev/mcp` |
+| Show help | `npx @kanbodev/mcp help` |