@coldev-ai/mcp-server

ColDev MCP Server connects Claude Code (or any MCP-compatible AI agent) to a ColDev workspace. Your agent gets native tools to browse tasks, claim work, update progress, and read PRDs -- all without manual API calls.

Quick Start

1. Go to your ColDev workspace Settings > Agent Setup
2. Create a token and copy the generated .mcp.json
3. Paste into your project root
4. Add .mcp.json to .gitignore
5. Done -- your agent now has coldev_* tools available

Manual Setup

Prerequisites: Node.js 18+, a ColDev workspace

1. Create an agent token in your workspace settings (or via the API: POST /orgs/{orgId}/workspaces/{wsId}/tokens)

2. Create .mcp.json in your project root:

{
  "mcpServers": {
    "coldev": {
      "command": "npx",
      "args": ["-y", "@coldev-ai/mcp-server"],
      "env": {
        "COLDEV_API_URL": "https://your-coldev-instance.com",
        "COLDEV_TOKEN": "coldev_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "COLDEV_ORG_ID": "your-org-id",
        "COLDEV_WORKSPACE_ID": "your-workspace-id"
      }
    }
  }
}

3. Add .mcp.json to your .gitignore

CLAUDE.md Setup

For the best agent experience, add a CLAUDE.md file to your project root:

1. Download the template from your workspace settings, or copy CLAUDE.md.template from this package
2. Fill in {WORKSPACE_NAME}, {ORG_NAME}, and {PROJECT_SPECIFIC_CONVENTIONS}
3. Place it in your project root

Available Tools

| Tool | Description | |------|-------------| | coldev_workspace_context | Get board overview: task counts, ready work, recent activity | | coldev_list_tasks | List tasks, optionally filtered by status or epic | | coldev_get_task | Get full task details with dependencies | | coldev_claim_task | Claim a ready task | | coldev_update_task_status | Transition task status (in_progress, in_review, blocked) | | coldev_create_task | Create a new task | | coldev_update_task | Update task fields | | coldev_list_epics | List all epics | | coldev_get_epic | Get epic details with progress | | coldev_list_prds | List all PRDs | | coldev_get_prd | Get full PRD content and comments | | coldev_get_activity | Get recent workspace activity |

Example Session

Human: "Check the board and start working on the next task"

Agent: [calls coldev_workspace_context]
Agent: "There are 3 ready tasks. The highest priority is TASK-42:
        Add input validation to /api/users endpoint."
Agent: [calls coldev_claim_task with taskId]
Agent: [calls coldev_get_task to read full details]
Agent: [calls coldev_update_task_status -> in_progress]
Agent: [does the implementation work...]
Agent: [calls coldev_update_task_status -> in_review with message]
Agent: "I've completed the task and submitted it for review."

Security

• Never commit .mcp.json with tokens to version control
• Add .mcp.json to your .gitignore
• For shared configs, use environment variable references:

{
  "mcpServers": {
    "coldev": {
      "command": "npx",
      "args": ["-y", "@coldev-ai/mcp-server"],
      "env": {
        "COLDEV_API_URL": "${COLDEV_API_URL}",
        "COLDEV_TOKEN": "${COLDEV_TOKEN}",
        "COLDEV_ORG_ID": "${COLDEV_ORG_ID}",
        "COLDEV_WORKSPACE_ID": "${COLDEV_WORKSPACE_ID}"
      }
    }
  }
}

Development

# Install dependencies
pnpm install

# Build
pnpm --filter @coldev-ai/mcp-server build

# Type-check
pnpm --filter @coldev-ai/mcp-server typecheck

# Watch mode
pnpm --filter @coldev-ai/mcp-server dev

# Run tests
pnpm --filter @coldev-ai/mcp-server test