@kanbodev/mcp 1.0.2

package/docs/SETUP.md

@@ -0,0 +1,216 @@
+# 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)
+
+The easiest way to get started. One command to authenticate, then configure your AI assistant.
+
+### Step 1: Authenticate
+
+```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
+
+You'll see a success message when complete:
+
+```
+  ✓ Successfully authenticated!
+
+    Email: you@example.com
+    Organization: My Team
+    API Key: kanbo_pat_a1b2...
+
+  Config saved to: ~/.kanbo/config.json
+```
+
+### Step 2: Configure Claude Desktop
+
+Add Kanbo to your Claude Desktop configuration:
+
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "kanbo": {
+      "command": "npx",
+      "args": ["@kanbodev/mcp"]
+    }
+  }
+}
+```
+
+That's it! Restart Claude Desktop and you can start managing your projects with AI.
+
+### Other CLI Commands
+
+```bash
+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
+
+### Cursor
+
+Add to your Cursor MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "kanbo": {
+      "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.
+
+### Claude Code CLI
+
+```bash
+claude mcp add kanbo -- 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 | `npx @kanbodev/mcp login` |
+| Check status | `npx @kanbodev/mcp whoami` |
+| Logout | `npx @kanbodev/mcp logout` |
+| Start server | `npx @kanbodev/mcp` |
+| Show help | `npx @kanbodev/mcp help` |

package/docs/VSCODE.md

@@ -0,0 +1,207 @@
+# Using Kanbo MCP with VS Code
+
+Connect Kanbo to your VS Code environment and manage projects, tickets, and workflows through AI-powered conversation — without leaving your editor.
+
+## Prerequisites
+
+**Authenticate first** (one-time setup):
+
+```bash
+npx @kanbodev/mcp login
+```
+
+This opens your browser, signs you in, and stores your credentials locally at `~/.kanbo/config.json`.
+
+Verify it worked:
+
+```bash
+npx @kanbodev/mcp whoami
+```
+
+---
+
+## VS Code Native MCP (v1.99+)
+
+VS Code 1.99 and later has built-in MCP support through GitHub Copilot Chat. This is the simplest way to get started.
+
+### Workspace-level setup
+
+Add to `.vscode/settings.json` in your project:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "kanbo": {
+        "command": "npx",
+        "args": ["@kanbodev/mcp"]
+      }
+    }
+  }
+}
+```
+
+### User-level setup
+
+To make Kanbo available across all your projects, add the same config to your **User Settings** (JSON):
+
+1. Open Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`)
+2. Select **Preferences: Open User Settings (JSON)**
+3. Add the `mcp` block above
+
+### Using a manual API key
+
+If you prefer environment variables over the login flow:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "kanbo": {
+        "command": "npx",
+        "args": ["@kanbodev/mcp"],
+        "env": {
+          "KANBO_API_KEY": "kanbo_pat_your_token_here"
+        }
+      }
+    }
+  }
+}
+```
+
+### Verify
+
+1. Reload the VS Code window (`Cmd+Shift+P` → **Developer: Reload Window**)
+2. Open Copilot Chat (`Cmd+Shift+I` / `Ctrl+Shift+I`)
+3. Switch to **Agent** mode
+4. You should see Kanbo tools listed under the tools icon
+
+---
+
+## Claude Code Extension
+
+If you use the [Claude Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code) for VS Code:
+
+### Via CLI
+
+Open the terminal in VS Code and run:
+
+```bash
+claude mcp add kanbo -- npx @kanbodev/mcp
+```
+
+This writes the config to `~/.claude.json` (global) by default.
+
+### Via config file
+
+Create or edit `.mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "kanbo": {
+      "command": "npx",
+      "args": ["@kanbodev/mcp"]
+    }
+  }
+}
+```
+
+Then restart Claude Code.
+
+---
+
+## Cursor
+
+Add to your Cursor MCP settings (Settings → MCP → Add Server):
+
+```json
+{
+  "mcpServers": {
+    "kanbo": {
+      "command": "npx",
+      "args": ["@kanbodev/mcp"]
+    }
+  }
+}
+```
+
+---
+
+## Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "kanbo": {
+      "command": "npx",
+      "args": ["@kanbodev/mcp"]
+    }
+  }
+}
+```
+
+---
+
+## Troubleshooting
+
+### Server not appearing
+
+- Make sure you've reloaded the VS Code window after adding the config
+- Check that `npx @kanbodev/mcp` works in your terminal: `npx @kanbodev/mcp whoami`
+- Ensure Node.js 18+ is installed: `node --version`
+
+### "Not authenticated" error
+
+```bash
+npx @kanbodev/mcp login
+```
+
+### Tools not showing up in Copilot Chat
+
+- Switch to **Agent** mode in the Copilot Chat panel (not Ask or Edit mode)
+- Click the tools icon to verify Kanbo is listed
+- Try reloading the window
+
+### Using a specific version
+
+Pin to a version to avoid unexpected updates:
+
+```json
+{
+  "command": "npx",
+  "args": ["@kanbodev/mcp@1.0.0"]
+}
+```
+
+Or always use the latest:
+
+```json
+{
+  "command": "npx",
+  "args": ["@kanbodev/mcp@latest"]
+}
+```
+
+### Logs
+
+Check the MCP server output in VS Code:
+
+1. Open Command Palette → **Output: Show Output Channel**
+2. Select the Kanbo MCP channel from the dropdown
+
+---
+
+## What You Can Do
+
+Once connected, switch to Agent mode in Copilot Chat and try:
+
+- *"What Kanbo projects do I have?"*
+- *"Show me my assigned tickets"*
+- *"Create a bug ticket in the Frontend project: login button unresponsive on mobile"*
+- *"Move PROJ-123 to In Progress"*
+- *"What's overdue this week?"*
+
+See the full [User Guide](../README.md#user-guide) for all available commands.

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@kanbodev/mcp",
+  "version": "1.0.2",
+  "description": "MCP (Model Context Protocol) server for Kanbo - AI-native project management",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "kanbo-mcp": "./dist/index.js"
+  },
+  "scripts": {
+    "dev": "bun run --watch src/index.ts",
+    "dev:http": "TRANSPORT=http bun run --watch src/index.ts",
+    "build": "bun build src/index.ts --outdir dist --target bun --format esm",
+    "build:node": "bun build src/index.ts --outdir dist --target node --format esm",
+    "start": "bun run dist/index.js",
+    "start:http": "TRANSPORT=http bun run dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "test:coverage": "bun test --coverage",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "elysia": "^1.0.0",
+    "open": "^11.0.0",
+    "pino": "^10.3.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.1.0",
+    "typescript": "^5.3.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "kanbo",
+    "ai",
+    "project-management",
+    "claude",
+    "cursor"
+  ],
+  "author": "Kanbo",
+  "license": "MIT"
+}