npm package: @kschmidtlarsen/kanban-mcp-server
Description: MCP server for Kanban Board project management integration
Author: Kristian Schmidt-Larsen
Latest version: 1.0.0

# Kanban Board MCP Server

Model Context Protocol server for interacting with the Kanban Board project management system.

## Overview

This MCP server provides Claude with direct access to the Kanban board API, enabling automated project and task management through conversation.

## Installation

```bash
cd /data/appdata/binhex-code-server/home/.claude/kanban-mcp
npm install
npm run build
```

## Configuration

Add to your `mcp.json`:

```json
{
  "mcpServers": {
    "kanban": {
      "type": "stdio",
      "command": "node",
      "args": ["/config/home/.claude/kanban-mcp/dist/index.js"],
      "env": {
        "KANBAN_URL": "http://192.168.0.20:3010",
        "KANBAN_WRITE_ENABLED": "true"
      }
    }
  }
}
```

### Environment Variables

- `KANBAN_URL`: Base URL of the Kanban API (default: `http://localhost:3010`)
- `KANBAN_WRITE_ENABLED`: Enable write operations (`true` or `false`, default: `false`)

## Available Tools

### Projects (Read)

- **list_projects**: List all projects with statistics
- **get_project**: Get detailed information about a specific project

### Projects (Write)

- **create_project**: Create a new project
  - Required: `name`
  - Optional: `color`, `repo`
- **update_project**: Update project properties
  - Required: `projectId`
  - Optional: `name`, `description`, `color`, `repo`, `theme`, `status`, `url`, `umamiId`
- **delete_project**: Delete a project
  - Required: `projectId`

### Cards (Read)

- **list_cards**: List cards with optional filters
  - Optional: `projectId`, `columnId`
- **get_card**: Get detailed card information
  - Required: `cardId`
- **get_card_history**: Get change history for a card
  - Required: `cardId`

### Cards (Write)

- **create_card**: Create a new task/card
  - Required: `title`, `projectId`
  - Optional: `description`, `columnId`, `priority`, `type`, `labels`, `storyPoints`, `assignee`, `reporter`, `dueDate`
- **update_card**: Update card properties
  - Required: `cardId`
  - Optional: `title`, `description`, `priority`, `type`, `labels`, `storyPoints`, `assignee`, `dueDate`
- **move_card**: Move card to a different column
  - Required: `cardId`, `columnId`
  - Optional: `pauseReason` (required if moving to paused column)
- **delete_card**: Delete a card
  - Required: `cardId`
- **update_checklist**: Toggle checklist items
  - Required: `cardId`, `item`
  - Optional: `value`
  - Items: `codeComplete`, `testsWritten`, `codeReviewed`, `documentationUpdated`, `rollbackProcedure`

### Pipeline (4 tools)

- **list_pipeline_stages**: List all pipeline stages with descriptions
  - Returns: Stage numbers (1-7) with names and descriptions
  - **Use this first** to understand which stage to update
- **get_card_pipeline_status**: Get current pipeline status with intelligent suggestions
  - Required: `cardId`
  - Returns: Current stage, status, errors, retry count, and suggested next stage
  - **Recommended:** Use this before updating pipeline to know what to do next
- **update_pipeline_stage**: Update CI/CD pipeline stage
  - Required: `cardId`, `stage` (1-7), `status` (running/passed/failed)
  - Optional: `error` (required if status is failed)
- **clear_pipeline_stage**: Clear/reset pipeline stage
  - Required: `cardId`

### Board & Statistics

- **list_columns**: List all Kanban board columns
- **get_statistics**: Get project statistics and metrics
  - Optional: `projectId`, `timeRange` (1month/3months/6months/12months)
- **get_board**: Get entire board (projects + columns + cards)

## Column IDs

- `backlog`: Ideas and raw tasks
- `discovered`: Tasks refined with acceptance criteria
- `in-development`: Active development
- `paused`: Blocked tasks (requires pause reason)
- `verify-release`: Verification and release
- `done`: Completed tasks
- `cancelled`: Archived tasks

## Card Types

- `feature`: New functionality
- `bug`: Bug fixes
- `documentation`: Documentation updates
- `other`: Other work items

## Priority Levels

- `low`: Low priority
- `medium`: Medium priority (default)
- `high`: High priority

## Architecture

```
┌─────────────────┐
│  Claude/Skills  │
└────────┬────────┘
         │ MCP Protocol (JSON-RPC 2.0)
         │ stdio transport
┌────────▼────────┐
│  Kanban MCP     │
│    Server       │
└────────┬────────┘
         │ REST API (HTTP)
┌────────▼────────┐
│  Kanban Board   │
│   Backend       │
│  (Node.js)      │
└────────┬────────┘
         │ PostgreSQL
┌────────▼────────┐
│  Urd Database   │
│  (PostgreSQL)   │
└─────────────────┘
```

## Usage Examples

### List all projects
```typescript
// Claude will call: list_projects
// Returns: Array of projects with stats
```

### Create a new card
```typescript
// Claude will call: create_card
// Arguments: {
//   title: "Implement user authentication",
//   projectId: "my-project",
//   type: "feature",
//   priority: "high",
//   storyPoints: 5
// }
```

### Move card through workflow
```typescript
// Claude will call: move_card
// Arguments: {
//   cardId: "card-abc123",
//   columnId: "in-development"
// }
```

### Check pipeline status and update intelligently
```typescript
// Step 1: Get current status and suggestions
// Claude will call: get_card_pipeline_status
// Arguments: { cardId: "card-abc123" }
// Returns: {
//   currentPipeline: { stage: 2, stageName: "Implementation", status: "passed" },
//   suggestion: "Stage 2 passed. Next: stage 3 (Security Audit)",
//   nextStage: { stage: 3, name: "Security Audit", description: "..." }
// }

// Step 2: Update to next stage based on suggestion
// Claude will call: update_pipeline_stage
// Arguments: {
//   cardId: "card-abc123",
//   stage: 3,  // From suggestion
//   status: "running"
// }
```

### List all pipeline stages
```typescript
// Claude will call: list_pipeline_stages
// Returns: [
//   { stage: 1, name: "Preparation", description: "Load card, create branch" },
//   { stage: 2, name: "Implementation", description: "Apply dev conventions" },
//   { stage: 3, name: "Security Audit", description: "Check OWASP Top 10" },
//   { stage: 4, name: "Quality Assurance", description: "Validate requirements" },
//   { stage: 5, name: "Deployment", description: "Push to GitHub, trigger build" },
//   { stage: 6, name: "Verification", description: "Automated tests" },
//   { stage: 7, name: "Complete", description: "All checks passed" }
// ]
```

## Development

### Build
```bash
npm run build
```

### Watch mode
```bash
npm run watch
```

### Testing
```bash
# Test tool listing
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | \
  KANBAN_URL="http://localhost:3010" \
  KANBAN_WRITE_ENABLED="true" \
  node dist/index.js
```

## Safety Features

- **Write Protection**: Set `KANBAN_WRITE_ENABLED=false` to make server read-only
- **Error Handling**: All API errors are caught and returned as MCP errors
- **Input Validation**: Zod schema validation on all tool inputs

## Dependencies

- `@modelcontextprotocol/sdk`: Official MCP SDK
- `zod`: Runtime type validation
- `typescript`: Type safety during development

## Version

Current version: `0.2.0`

## Changelog

### v0.2.0 - Pipeline Intelligence
- Added `list_pipeline_stages` - List all stages with descriptions
- Added `get_card_pipeline_status` - Get current status with intelligent next-step suggestions
- Agents can now understand pipeline stages without hardcoding stage numbers

### v0.1.0 - Initial Release
- 18 basic tools for project and card management

## License

MIT