@kanbodev/mcp 1.0.2

package/README.md

@@ -0,0 +1,258 @@
+# 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 (Claude, Cursor, VS Code, Claude Code) to Kanbo and manage tickets, projects, releases, and workflows through natural conversation.
+
+## Quick Setup
+
+### 1. Authenticate
+
+```bash
+npx @kanbodev/mcp login
+```
+
+This opens your browser to sign in, select your organization, and store credentials locally.
+
+### 2. Connect to your AI assistant
+
+**Claude Desktop** — add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "kanbo": {
+      "command": "npx",
+      "args": ["@kanbodev/mcp"]
+    }
+  }
+}
+```
+
+**Claude Code CLI:**
+
+```bash
+claude mcp add kanbo -- npx @kanbodev/mcp
+```
+
+**VS Code** (v1.99+) — add to `.vscode/settings.json`:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "kanbo": {
+        "command": "npx",
+        "args": ["@kanbodev/mcp"]
+      }
+    }
+  }
+}
+```
+
+**Cursor** — add to your MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "kanbo": {
+      "command": "npx",
+      "args": ["@kanbodev/mcp"]
+    }
+  }
+}
+```
+
+Then restart your AI assistant. See [docs/SETUP.md](docs/SETUP.md) for manual API key setup, troubleshooting, and [VS Code guide](docs/VSCODE.md) for detailed editor setup.
+
+---
+
+## 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, find available statuses, priorities, and sizes, then create the ticket. 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.
+
+### 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"
+
+### 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'"
+
+### 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 via browser
+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
+```
+
+## License
+
+MIT