@kanbodev/mcp 1.1.8 → 1.2.0

package/README.md

@@ -1,323 +1,323 @@
-# Kanbo MCP Server
-
-[![npm version](https://img.shields.io/npm/v/@kanbodev/mcp.svg)](https://www.npmjs.com/package/@kanbodev/mcp)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-AI-native project management via [Model Context Protocol](https://modelcontextprotocol.io). Connect your AI assistant (VS Code, Cursor, Windsurf, Claude Code, Claude Desktop) to [Kanbo](https://www.kanbo.dev/) and manage tickets, projects, releases, and workflows through natural conversation.
-
-[Try the demo](https://www.kanbo.dev/demo) | [See a live project](https://hub.kanbo.dev/dev/default)
-
-## Quick Setup
-
-```bash
-npx @kanbodev/mcp login
-```
-
-That's it. This single command will:
-
-1. Open your browser to sign in and select your organization
-2. Store credentials locally at `~/.kanbo/config.json`
-3. **Auto-register the MCP server** with detected editors (VS Code, VS Code Insiders, Cursor, Windsurf, Claude Code, Claude Desktop, Claude Code CLI)
-
-Reload your editor and start using Kanbo tools immediately.
-
-### Already logged in? Register manually
-
-If you authenticated previously and need to register with a new editor:
-
-```bash
-npx @kanbodev/mcp install
-```
-
-### Manual setup
-
-If auto-registration doesn't detect your editor, add the config manually:
-
-**VS Code / VS Code Insiders / Cursor** — add to `mcp.json`:
-
-```json
-{
-  "servers": {
-    "kanbodev": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["@kanbodev/mcp"]
-    }
-  }
-}
-```
-
-**Claude Desktop / Windsurf / Claude Code** — add to config with `mcpServers` key:
-
-```json
-{
-  "mcpServers": {
-    "kanbodev": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["@kanbodev/mcp"]
-    }
-  }
-}
-```
-
-**Claude Code CLI:**
-
-```bash
-claude mcp add kanbodev -- npx @kanbodev/mcp
-```
-
-<details>
-<summary>Config file locations</summary>
-
-| Editor | Config Path |
-|--------|-------------|
-| VS Code | `~/Library/Application Support/Code/User/mcp.json` (macOS) / `%APPDATA%\Code\User\mcp.json` (Windows) |
-| VS Code Insiders | `~/Library/Application Support/Code - Insiders/User/mcp.json` (macOS) / `%APPDATA%\Code - Insiders\User\mcp.json` (Windows) |
-| Cursor | `~/.cursor/mcp.json` |
-| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
-| Claude Code | `~/.claude/settings.json` |
-| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) / `%APPDATA%\Claude\claude_desktop_config.json` (Windows) |
-
-</details>
-
-### Manual API key setup
-
-If you prefer environment variables over the login flow:
-
-1. Go to your Kanbo dashboard → **Settings → API Keys**
-2. Create a new key and copy the token
-3. Add `"env": { "KANBO_API_KEY": "kanbo_pat_..." }` to your editor's MCP config
-
-### Environment variables
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `KANBO_API_KEY` | Personal Access Token (overrides config file) | from `~/.kanbo/config.json` |
-| `KANBO_API_URL` | API server URL | `https://api.kanbo.dev` |
-| `KANBO_WEB_URL` | Web app URL for login | `https://kanbo.dev` |
-
----
-
-## User Guide
-
-Once connected, you interact with Kanbo through natural language. Here's what you can do and how to ask for it.
-
-### Getting oriented
-
-Start by asking your AI assistant to discover your workspace:
-
-> "What Kanbo organizations do I have access to?"
->
-> "List all my projects"
->
-> "Show me the project stats for the frontend project"
-
-The assistant will call `list_organizations`, `list_projects`, and `get_project_stats` behind the scenes.
-
-### Creating a ticket
-
-You can create tickets with as much or as little detail as you want:
-
-> "Create a ticket in the Frontend project called 'Fix login button not responding on mobile'"
-
-The assistant will look up your project, check for similar/related tickets, find available statuses, priorities, and sizes, then create the ticket with acceptance criteria. You can also be more specific:
-
-> "Create a high-priority bug in Frontend: 'Payment form crashes on Safari'. Assign it to me and put it in the To Do column."
-
-For AI-assisted creation:
-
-> "I need a ticket about improving the search performance. Can you polish the title, generate a description, and suggest the right priority and type?"
-
-This uses the AI tools (`polish_title`, `generate_description`, `suggest_attributes`) to craft a well-defined ticket before creating it.
-
-### Acceptance criteria
-
-Every ticket includes structured acceptance criteria — specific, testable conditions that define "done":
-
-> "Add acceptance criteria to PROJ-123: users can export in CSV and JSON, progress shows for large exports, and errors display a retry option"
->
-> "Show me the acceptance criteria for PROJ-45"
-
-The assistant uses Given/When/Then format and includes both happy-path and edge-case criteria automatically.
-
-### Related tickets and subtasks
-
-The assistant checks for duplicates and related work before creating tickets, and supports parent-child relationships for breaking down work:
-
-> "Create a subtask under PROJ-100: 'Write unit tests for auth module'"
->
-> "Show me the child tickets of PROJ-100"
->
-> "Find tickets similar to 'password reset not working'"
-
-### Finding and viewing tickets
-
-> "Show me all my assigned tickets"
->
-> "What tickets are in the backlog for the API project?"
->
-> "Get ticket PROJ-123"
->
-> "What tickets are overdue?"
->
-> "Show me tickets due in the next 3 days"
->
-> "Search for tickets related to 'authentication'"
-
-### Moving tickets through the workflow
-
-> "Move PROJ-123 to In Progress"
->
-> "Complete ticket PROJ-45"
->
-> "Move all the QA-approved tickets to Done"
-
-The assistant respects your workflow transition rules — it checks which status transitions are allowed before moving tickets.
-
-### Managing the backlog
-
-> "Move PROJ-78 to the backlog"
->
-> "Pull PROJ-78 back to the board and put it in To Do"
->
-> "Show me the backlog for the mobile project"
->
-> "Restore the deleted ticket PROJ-99 and put it in the backlog"
-
-### Comments and collaboration
-
-> "Add a comment to PROJ-123: 'Tested on Chrome and Firefox, both working now'"
->
-> "Show me the comments on PROJ-45"
->
-> "What are my unread notifications?"
->
-> "Mark all notifications as read"
-
-### Tags and labels
-
-> "List all tags in the Frontend project"
->
-> "Create a tag called 'performance' with color orange"
->
-> "Tag PROJ-123 with 'performance' and 'backend'"
-
-### Release management
-
-> "Create a release called 'v2.1.0' with target date March 15"
->
-> "Add tickets PROJ-10, PROJ-11, and PROJ-12 to the v2.1.0 release"
->
-> "Show me the burndown for v2.1.0"
->
-> "Ship the v2.1.0 release"
-
-### Bulk operations
-
-> "Complete all tickets in the Done column"
->
-> "Assign all unassigned tickets in Sprint 5 to me"
->
-> "Move these 10 tickets to the QA status"
-
-Batch operations work on up to 50 tickets at once.
-
-### AI features
-
-> "Find tickets similar to 'user can't reset password'"
->
-> "Fix the grammar in this ticket description: ..."
->
-> "Make this description clearer: ..."
->
-> "Check if this title is clear enough: 'fix thing'"
->
-> "Create a ticket from my notes: users need to be able to export reports as PDF, it should respect filters, and show a progress bar for large exports"
-
-The last example passes your raw notes directly to `generate_description` — the AI organizes, structures, and expands them into a full ticket description rather than generating from scratch.
-
-### Analytics and reporting
-
-> "Show me the team analytics for the Frontend project"
->
-> "What's the average cycle time for tickets?"
->
-> "Show the ticket distribution by priority and type"
-
-### Checking usage
-
-> "How many MCP requests have I used today?"
->
-> "What's my AI usage this week?"
-
----
-
-## Example Workflows
-
-### Daily standup
-
-> "Show me my tickets, any overdue items, and what's due this week"
-
-### Sprint planning
-
-> "Create a release called 'Sprint 12' with target date Feb 28. Then show me the backlog so I can pick tickets to include."
-
-### Triage new bugs
-
-> "Show me all tickets tagged 'bug' that don't have an assignee. For each one, suggest a priority and size."
-
-### End of sprint
-
-> "Show me all tickets in Sprint 11. Complete the ones in the Done column, and move any incomplete ones to the backlog."
-
----
-
-## Available Tools (125)
-
-| Category | Count | Key Tools |
-|----------|-------|-----------|
-| **Tickets** | 24 | `create_ticket`, `update_ticket`, `move_ticket`, `complete_ticket`, `get_my_tickets`, `get_overdue_tickets` |
-| **Projects** | 11 | `list_projects`, `create_project`, `get_project_stats`, `get_project_summaries` |
-| **Releases** | 17 | `create_release`, `assign_tickets_to_release`, `mark_release_shipped`, `get_release_burndown`, `get_release_history` |
-| **Workflow** | 8 | `list_statuses`, `get_available_transitions`, `create_status`, `create_transition` |
-| **Tags** | 8 | `list_tags`, `create_tag`, `add_tag_to_ticket`, `set_ticket_tags` |
-| **AI** | 8 | `polish_title`, `generate_description`, `find_similar_tickets`, `suggest_attributes` |
-| **Organization** | 6 | `list_organizations`, `set_organization`, `list_organization_members` |
-| **Comments** | 5 | `add_comment`, `list_comments`, `update_comment` |
-| **Notifications** | 5 | `list_notifications`, `get_unread_count`, `mark_all_notifications_read` |
-| **Priorities** | 5 | `list_priorities`, `create_priority`, `update_priority` |
-| **Sizes** | 5 | `list_sizes`, `create_size`, `update_size` |
-| **Ticket Types** | 5 | `list_ticket_types`, `create_ticket_type` |
-| **Members** | 4 | `add_project_member`, `remove_project_member`, `update_project_member_role` |
-| **Batch** | 3 | `batch_move_tickets`, `batch_complete_tickets`, `batch_assign_tickets` |
-| **Analytics** | 3 | `get_member_analytics`, `get_cycle_time_analytics`, `get_distribution_analytics` |
-| **History** | 2 | `get_ticket_history`, `get_project_activity` |
-| **Watchers** | 2 | `get_watch_status`, `toggle_watch` |
-| **Usage** | 2 | `get_mcp_usage`, `get_ai_usage` |
-| **Attachments** | 1 | `list_attachments` |
-| **Help** | 1 | `get_help` |
-
----
-
-## CLI Commands
-
-```bash
-npx @kanbodev/mcp login    # Authenticate + auto-register MCP server
-npx @kanbodev/mcp install  # Register MCP server with detected editors
-npx @kanbodev/mcp whoami   # Check auth status
-npx @kanbodev/mcp logout   # Remove credentials
-npx @kanbodev/mcp help     # Show help
-npx @kanbodev/mcp version  # Show version
-```
-
-## Links
-
-- [Kanbo Website](https://www.kanbo.dev/)
-- [Interactive Demo](https://www.kanbo.dev/demo)
-- [Public Project Hub](https://hub.kanbo.dev/dev/default)
-- [npm Package](https://www.npmjs.com/package/@kanbodev/mcp)
-
-## License
-
-MIT
+# Kanbo MCP Server
+
+[![npm version](https://img.shields.io/npm/v/@kanbodev/mcp.svg)](https://www.npmjs.com/package/@kanbodev/mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+AI-native project management via [Model Context Protocol](https://modelcontextprotocol.io). Connect your AI assistant (VS Code, Cursor, Windsurf, Claude Code, Claude Desktop) to [Kanbo](https://www.kanbo.dev/) and manage tickets, projects, releases, and workflows through natural conversation.
+
+[Try the demo](https://www.kanbo.dev/demo) | [See a live project](https://hub.kanbo.dev/dev/default)
+
+## Quick Setup
+
+```bash
+npx @kanbodev/mcp login
+```
+
+That's it. This single command will:
+
+1. Open your browser to sign in and select your organization
+2. Store credentials locally at `~/.kanbo/config.json`
+3. **Auto-register the MCP server** with detected editors (VS Code, VS Code Insiders, Cursor, Windsurf, Claude Code, Claude Desktop, Claude Code CLI)
+
+Reload your editor and start using Kanbo tools immediately.
+
+### Already logged in? Register manually
+
+If you authenticated previously and need to register with a new editor:
+
+```bash
+npx @kanbodev/mcp install
+```
+
+### Manual setup
+
+If auto-registration doesn't detect your editor, add the config manually:
+
+**VS Code / VS Code Insiders / Cursor** — add to `mcp.json`:
+
+```json
+{
+  "servers": {
+    "kanbodev": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["@kanbodev/mcp"]
+    }
+  }
+}
+```
+
+**Claude Desktop / Windsurf / Claude Code** — add to config with `mcpServers` key:
+
+```json
+{
+  "mcpServers": {
+    "kanbodev": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["@kanbodev/mcp"]
+    }
+  }
+}
+```
+
+**Claude Code CLI:**
+
+```bash
+claude mcp add kanbodev -- npx @kanbodev/mcp
+```
+
+<details>
+<summary>Config file locations</summary>
+
+| Editor | Config Path |
+|--------|-------------|
+| VS Code | `~/Library/Application Support/Code/User/mcp.json` (macOS) / `%APPDATA%\Code\User\mcp.json` (Windows) |
+| VS Code Insiders | `~/Library/Application Support/Code - Insiders/User/mcp.json` (macOS) / `%APPDATA%\Code - Insiders\User\mcp.json` (Windows) |
+| Cursor | `~/.cursor/mcp.json` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
+| Claude Code | `~/.claude/settings.json` |
+| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) / `%APPDATA%\Claude\claude_desktop_config.json` (Windows) |
+
+</details>
+
+### Manual API key setup
+
+If you prefer environment variables over the login flow:
+
+1. Go to your Kanbo dashboard → **Settings → API Keys**
+2. Create a new key and copy the token
+3. Add `"env": { "KANBO_API_KEY": "kanbo_pat_..." }` to your editor's MCP config
+
+### Environment variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `KANBO_API_KEY` | Personal Access Token (overrides config file) | from `~/.kanbo/config.json` |
+| `KANBO_API_URL` | API server URL | `https://api.kanbo.dev` |
+| `KANBO_WEB_URL` | Web app URL for login | `https://kanbo.dev` |
+
+---
+
+## User Guide
+
+Once connected, you interact with Kanbo through natural language. Here's what you can do and how to ask for it.
+
+### Getting oriented
+
+Start by asking your AI assistant to discover your workspace:
+
+> "What Kanbo organizations do I have access to?"
+>
+> "List all my projects"
+>
+> "Show me the project stats for the frontend project"
+
+The assistant will call `list_organizations`, `list_projects`, and `get_project_stats` behind the scenes.
+
+### Creating a ticket
+
+You can create tickets with as much or as little detail as you want:
+
+> "Create a ticket in the Frontend project called 'Fix login button not responding on mobile'"
+
+The assistant will look up your project, check for similar/related tickets, find available statuses, priorities, and sizes, then create the ticket with acceptance criteria. You can also be more specific:
+
+> "Create a high-priority bug in Frontend: 'Payment form crashes on Safari'. Assign it to me and put it in the To Do column."
+
+For AI-assisted creation:
+
+> "I need a ticket about improving the search performance. Can you polish the title, generate a description, and suggest the right priority and type?"
+
+This uses the AI tools (`polish_title`, `generate_description`, `suggest_attributes`) to craft a well-defined ticket before creating it.
+
+### Acceptance criteria
+
+Every ticket includes structured acceptance criteria — specific, testable conditions that define "done":
+
+> "Add acceptance criteria to PROJ-123: users can export in CSV and JSON, progress shows for large exports, and errors display a retry option"
+>
+> "Show me the acceptance criteria for PROJ-45"
+
+The assistant uses Given/When/Then format and includes both happy-path and edge-case criteria automatically.
+
+### Related tickets and subtasks
+
+The assistant checks for duplicates and related work before creating tickets, and supports parent-child relationships for breaking down work:
+
+> "Create a subtask under PROJ-100: 'Write unit tests for auth module'"
+>
+> "Show me the child tickets of PROJ-100"
+>
+> "Find tickets similar to 'password reset not working'"
+
+### Finding and viewing tickets
+
+> "Show me all my assigned tickets"
+>
+> "What tickets are in the backlog for the API project?"
+>
+> "Get ticket PROJ-123"
+>
+> "What tickets are overdue?"
+>
+> "Show me tickets due in the next 3 days"
+>
+> "Search for tickets related to 'authentication'"
+
+### Moving tickets through the workflow
+
+> "Move PROJ-123 to In Progress"
+>
+> "Complete ticket PROJ-45"
+>
+> "Move all the QA-approved tickets to Done"
+
+The assistant respects your workflow transition rules — it checks which status transitions are allowed before moving tickets.
+
+### Managing the backlog
+
+> "Move PROJ-78 to the backlog"
+>
+> "Pull PROJ-78 back to the board and put it in To Do"
+>
+> "Show me the backlog for the mobile project"
+>
+> "Restore the deleted ticket PROJ-99 and put it in the backlog"
+
+### Comments and collaboration
+
+> "Add a comment to PROJ-123: 'Tested on Chrome and Firefox, both working now'"
+>
+> "Show me the comments on PROJ-45"
+>
+> "What are my unread notifications?"
+>
+> "Mark all notifications as read"
+
+### Tags and labels
+
+> "List all tags in the Frontend project"
+>
+> "Create a tag called 'performance' with color orange"
+>
+> "Tag PROJ-123 with 'performance' and 'backend'"
+
+### Release management
+
+> "Create a release called 'v2.1.0' with target date March 15"
+>
+> "Add tickets PROJ-10, PROJ-11, and PROJ-12 to the v2.1.0 release"
+>
+> "Show me the burndown for v2.1.0"
+>
+> "Ship the v2.1.0 release"
+
+### Bulk operations
+
+> "Complete all tickets in the Done column"
+>
+> "Assign all unassigned tickets in Sprint 5 to me"
+>
+> "Move these 10 tickets to the QA status"
+
+Batch operations work on up to 50 tickets at once.
+
+### AI features
+
+> "Find tickets similar to 'user can't reset password'"
+>
+> "Fix the grammar in this ticket description: ..."
+>
+> "Make this description clearer: ..."
+>
+> "Check if this title is clear enough: 'fix thing'"
+>
+> "Create a ticket from my notes: users need to be able to export reports as PDF, it should respect filters, and show a progress bar for large exports"
+
+The last example passes your raw notes directly to `generate_description` — the AI organizes, structures, and expands them into a full ticket description rather than generating from scratch.
+
+### Analytics and reporting
+
+> "Show me the team analytics for the Frontend project"
+>
+> "What's the average cycle time for tickets?"
+>
+> "Show the ticket distribution by priority and type"
+
+### Checking usage
+
+> "How many MCP requests have I used today?"
+>
+> "What's my AI usage this week?"
+
+---
+
+## Example Workflows
+
+### Daily standup
+
+> "Show me my tickets, any overdue items, and what's due this week"
+
+### Sprint planning
+
+> "Create a release called 'Sprint 12' with target date Feb 28. Then show me the backlog so I can pick tickets to include."
+
+### Triage new bugs
+
+> "Show me all tickets tagged 'bug' that don't have an assignee. For each one, suggest a priority and size."
+
+### End of sprint
+
+> "Show me all tickets in Sprint 11. Complete the ones in the Done column, and move any incomplete ones to the backlog."
+
+---
+
+## Available Tools (125)
+
+| Category | Count | Key Tools |
+|----------|-------|-----------|
+| **Tickets** | 24 | `create_ticket`, `update_ticket`, `move_ticket`, `complete_ticket`, `get_my_tickets`, `get_overdue_tickets` |
+| **Projects** | 11 | `list_projects`, `create_project`, `get_project_stats`, `get_project_summaries` |
+| **Releases** | 17 | `create_release`, `assign_tickets_to_release`, `mark_release_shipped`, `get_release_burndown`, `get_release_history` |
+| **Workflow** | 8 | `list_statuses`, `get_available_transitions`, `create_status`, `create_transition` |
+| **Tags** | 8 | `list_tags`, `create_tag`, `add_tag_to_ticket`, `set_ticket_tags` |
+| **AI** | 8 | `polish_title`, `generate_description`, `find_similar_tickets`, `suggest_attributes` |
+| **Organization** | 6 | `list_organizations`, `set_organization`, `list_organization_members` |
+| **Comments** | 5 | `add_comment`, `list_comments`, `update_comment` |
+| **Notifications** | 5 | `list_notifications`, `get_unread_count`, `mark_all_notifications_read` |
+| **Priorities** | 5 | `list_priorities`, `create_priority`, `update_priority` |
+| **Sizes** | 5 | `list_sizes`, `create_size`, `update_size` |
+| **Ticket Types** | 5 | `list_ticket_types`, `create_ticket_type` |
+| **Members** | 4 | `add_project_member`, `remove_project_member`, `update_project_member_role` |
+| **Batch** | 3 | `batch_move_tickets`, `batch_complete_tickets`, `batch_assign_tickets` |
+| **Analytics** | 3 | `get_member_analytics`, `get_cycle_time_analytics`, `get_distribution_analytics` |
+| **History** | 2 | `get_ticket_history`, `get_project_activity` |
+| **Watchers** | 2 | `get_watch_status`, `toggle_watch` |
+| **Usage** | 2 | `get_mcp_usage`, `get_ai_usage` |
+| **Attachments** | 1 | `list_attachments` |
+| **Help** | 1 | `get_help` |
+
+---
+
+## CLI Commands
+
+```bash
+npx @kanbodev/mcp login    # Authenticate + auto-register MCP server
+npx @kanbodev/mcp install  # Register MCP server with detected editors
+npx @kanbodev/mcp whoami   # Check auth status
+npx @kanbodev/mcp logout   # Remove credentials
+npx @kanbodev/mcp help     # Show help
+npx @kanbodev/mcp version  # Show version
+```
+
+## Links
+
+- [Kanbo Website](https://www.kanbo.dev/)
+- [Interactive Demo](https://www.kanbo.dev/demo)
+- [Public Project Hub](https://hub.kanbo.dev/dev/default)
+- [npm Package](https://www.npmjs.com/package/@kanbodev/mcp)
+
+## License
+
+MIT