kanban-mcp

Model Context Protocol (MCP) server for kanban project management.

Architecture

This MCP server delegates all operations to the kanban CLI via subprocess execution. This architecture provides:

• Single source of truth: CLI is the canonical implementation
• Automatic capability inheritance: New CLI commands automatically become available
• Decoupled runtime: Only binary dependency, no shared Rust library code
• Natural conflict handling: Each subprocess reloads state from disk
• Retry with backoff: Automatic retry on file conflicts

┌─────────────────┐
│  Claude/MCP     │
│    Client       │
└────────┬────────┘
         │ JSON-RPC
         ▼
┌─────────────────────────────────────────────┐
│              kanban-mcp                      │
│  ┌─────────────────────────────────────┐    │
│  │  MCP Tool Handlers                   │    │
│  │  - create_board → spawn CLI          │    │
│  │  - list_cards → spawn CLI            │    │
│  │  - move_card → spawn CLI             │    │
│  └─────────────────────────────────────┘    │
│  ┌─────────────────────────────────────┐    │
│  │  CliExecutor                         │    │
│  │  - spawn("kanban", args)             │    │
│  │  - parse CliResponse<T>              │    │
│  │  - retry on conflict                 │    │
│  └─────────────────────────────────────┘    │
└────────┬────────────────────────────────────┘
         │ subprocess
         ▼
┌─────────────────┐
│  kanban CLI     │
│  (executable)   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  kanban.json    │  ← Atomic writes + conflict detection
└─────────────────┘

Installation

From Nix (recommended)

nix build .#kanban-mcp

The Nix derivation automatically wraps the binary with the kanban CLI in PATH.

From Cargo

cargo install --path crates/kanban-mcp

# Ensure kanban CLI is in PATH
cargo install --path crates/kanban-cli

Usage

kanban-mcp /path/to/kanban.json

MCP Client Configuration

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "kanban": {
      "command": "kanban-mcp",
      "args": ["/path/to/kanban.json"]
    }
  }
}

Available Tools

Concurrency Model

The kanban CLI uses optimistic concurrency control with file metadata:

1. Load: Read file + capture metadata (mtime, size, hash)
2. Modify: Execute operation in memory
3. Save: Verify metadata unchanged, then atomic write
4. Conflict: If metadata changed, return error

When conflicts occur, the MCP server automatically retries with exponential backoff:

Attempt 1 → ConflictDetected → Wait 50ms
Attempt 2 → ConflictDetected → Wait 100ms
Attempt 3 → Success ✓

Default Configuration:

• Max attempts: 3
• Initial delay: 50ms
• Max delay: 1000ms
• Backoff multiplier: 2.0x

Testing

# Unit tests
cargo test --package kanban-mcp

# With logging
RUST_LOG=debug cargo test --package kanban-mcp

CLI Command Mapping

CLI Response Format

The kanban CLI outputs JSON responses:

{
  "success": true,
  "api_version": "0.1.0",
  "data": { ... }
}

On error:

{
  "success": false,
  "api_version": "0.1.0",
  "error": "Error message"
}