# codecks-mcp

TypeScript MCP server for [Codecks](https://codecks.io) project management. Exposes 32+ tools for managing cards, decks, milestones, tags, and PM workflows via the [Model Context Protocol](https://modelcontextprotocol.io).

Built with [@modelcontextprotocol/server](https://www.npmjs.com/package/@modelcontextprotocol/server), [zod](https://zod.dev), and [Express](https://expressjs.com).

## Quick Start

```bash
# Run directly (no install needed)
npx codecks-mcp

# Or install globally
npm install -g codecks-mcp
codecks-mcp
```

## Configuration

Create a `.env` file in your working directory:

```env
CODECKS_TOKEN=your_session_cookie
CODECKS_ACCOUNT=your_account_slug
```

### Tokens

| Variable | Source | Expires |
|----------|--------|---------|
| `CODECKS_TOKEN` | Browser DevTools > Cookie `at` | Yes |
| `CODECKS_REPORT_TOKEN` | CLI `generate-token` command | No |
| `CODECKS_ACCOUNT` | Your Codecks account slug | N/A |
| `CODECKS_USER_ID` | Auto-discovered if unset | N/A |

### Optional Settings

| Variable | Default | Description |
|----------|---------|-------------|
| `CODECKS_MCP_RESPONSE_MODE` | `legacy` | `legacy` or `envelope` |
| `CODECKS_HTTP_TIMEOUT_SECONDS` | `30` | Request timeout |
| `CODECKS_HTTP_MAX_RETRIES` | `2` | Retry count |

## Transports

### stdio (default)

```bash
codecks-mcp
```

### HTTP

```bash
codecks-mcp --transport http --port 3000
```

Endpoints:
- `POST /mcp` — MCP protocol (Streamable HTTP)
- `GET /ping` — Health check

## IDE Setup

### Claude Code

```json
{
  "mcpServers": {
    "codecks": {
      "command": "npx",
      "args": ["-y", "codecks-mcp"]
    }
  }
}
```

### Cursor

```json
{
  "mcpServers": {
    "codecks": {
      "command": "npx",
      "args": ["-y", "codecks-mcp"]
    }
  }
}
```

### Remote (HTTP)

```json
{
  "mcpServers": {
    "codecks": {
      "url": "http://localhost:3000/mcp"
    }
  }
}
```

## Tools

### Read (10)
| Tool | Description |
|------|-------------|
| `get_account` | Current account info |
| `list_cards` | List/filter cards with pagination |
| `get_card` | Full card details |
| `list_decks` | All decks |
| `list_projects` | Projects with decks |
| `list_milestones` | Milestones |
| `list_tags` | Project-level tags |
| `list_activity` | Recent activity feed |
| `pm_focus` | PM dashboard (blocked, stale, suggested) |
| `standup` | Daily standup summary |

### Hand (3)
| Tool | Description |
|------|-------------|
| `list_hand` | Personal work queue |
| `add_to_hand` | Add cards to hand |
| `remove_from_hand` | Remove cards from hand |

### Mutation (9)
| Tool | Description |
|------|-------------|
| `create_card` | Create card (supports sub-cards) |
| `update_cards` | Batch update properties |
| `mark_done` | Mark cards done |
| `mark_started` | Mark cards started |
| `archive_card` | Archive (reversible) |
| `unarchive_card` | Restore archived |
| `delete_card` | Permanent delete |
| `scaffold_feature` | Hero + lane sub-cards |
| `split_features` | Batch-split features |

### Comments (5)
| Tool | Description |
|------|-------------|
| `create_comment` | Start thread |
| `reply_comment` | Reply to thread |
| `close_comment` | Resolve thread |
| `reopen_comment` | Reopen thread |
| `list_conversations` | List threads |

### PM Session (3)
| Tool | Description |
|------|-------------|
| `get_pm_playbook` | Methodology guide |
| `get_workflow_preferences` | Load preferences |
| `save_workflow_preferences` | Save preferences |

### Feedback (2)
| Tool | Description |
|------|-------------|
| `save_cli_feedback` | Save feedback |
| `get_cli_feedback` | Read feedback |

## Security

- Prompt injection detection (6 regex patterns)
- `[USER_DATA]` boundary tagging on user-authored content
- Input validation with zod schemas + length limits
- UUID validation on all card IDs
- Control character stripping

## Development

```bash
# Install
pnpm install

# Dev mode (tsx, auto-reload)
pnpm dev

# Build
pnpm build

# Test
pnpm test

# Lint + format
pnpm lint
pnpm format:check

# Type check
pnpm typecheck
```

## Also Available

- **Python version**: [codecks-mcp-python](https://github.com/rangogamedev/codecks-mcp-python) — same tools, Python runtime
- **Full CLI**: [codecks-cli](https://github.com/rangogamedev/codecks-cli) — CLI + library with formatters, GDD sync, and more

## License

MIT