npm package: @plukio/mcp-server
Description: MCP (Model Context Protocol) server that gives AI coding agents access to Pluk tasks. Pull tasks, update status, leave notes for reviewers — all from within Claude Code, Cursor, or any MCP-compatible client.
Latest version: 0.3.0

# @plukio/mcp-server

MCP (Model Context Protocol) server that gives AI coding agents access to Pluk tasks. Pull tasks, update status, leave notes for reviewers — all from within Claude Code, Cursor, or any MCP-compatible client.

## Important: one server per project

Pluk API keys are **scoped to a single site**. Each of your client sites has its own key, its own tasks, and its own context. This means:

- **Configure the MCP server locally in each project repo**, not globally
- Each project gets the API key for its corresponding Pluk site
- Tasks, company defaults, and site context all come from the site tied to that key

This is by design — Pluk operates at the site level so your AI agent always has the right context for the project it's working in, without cross-site data leaking between repos.

## Setup

### 1. Get your site's API key

Generate one from the Pluk dashboard under your site's settings. Keys start with `pluk_`.

### 2. Configure your MCP client

> **Always add this to the project directory** (e.g. `.mcp.json` in the repo root), not to your global config. Each project needs its own Pluk connection tied to the correct site.

#### Claude Code

Add to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "pluk": {
      "command": "npx",
      "args": ["-y", "-p", "@plukio/mcp-server", "plukio-mcp-server"],
      "env": {
        "PLUK_API_KEY": "pluk_your_key_here"
      }
    }
  }
}
```

Or via CLI (run from the project directory):

```bash
claude mcp add pluk -- npx -y -p @plukio/mcp-server plukio-mcp-server
```

Then set `PLUK_API_KEY` in the MCP config's `env` block.

#### Cursor / Other MCP clients

Point to the same command (`npx -y -p @plukio/mcp-server plukio-mcp-server`) with `PLUK_API_KEY` set in the environment. Configure it per-project, not globally.

### Environment variables

| Variable | Required | Description |
|---|---|---|
| `PLUK_API_KEY` | Yes | Your site's Pluk API key (site-scoped) |
| `PLUK_API_URL` | No | API base URL (defaults to `https://pluk.io`) |

## Tools

### `pluk_list_tasks`

List tasks with optional filters. Returns lightweight summaries sorted by priority (expedited first, then standard, in Kanban board order). Only backlog tasks are returned by default.

| Parameter | Type | Description |
|---|---|---|
| `type` | string | Filter by type: `code`, `content`, `design`, `support` |
| `status` | string | Comma-separated: `backlog`, `on_deck`, `in_progress`, `needs_review`, `done` |
| `intent` | string | `expedited` or `standard` |
| `priority` | string | `normal` or `focus` |
| `limit` | number | Max results (default 5, max 100) |
| `offset` | number | Skip N tasks for pagination |

### `pluk_get_task`

Get full task details by ID, including description, custom fields, site info, company defaults, and testing findings (review feedback).

| Parameter | Type | Required | Description |
|---|---|---|---|
| `task_id` | string | Yes | Task UUID |

### `pluk_update_task`

Update a task's status, title, or notes.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `task_id` | string | Yes | Task UUID |
| `title` | string | No | Updated title (use to prepend "NEED INFO - ") |
| `status` | string | No | `backlog`, `on_deck`, `in_progress`, `needs_review`, `done`, `blocked` |
| `ai_coder_notes` | string | No | ELI5 summary for the reviewer. **Required** when setting `needs_review`. |

### `pluk_get_company`

Get company context: tech stack, repo URL, staging URL, and active sites.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `company_id` | string | Yes | Company UUID (from a task's organization field) |

## Workflow

```
pluk_list_tasks (limit=1)     → Get next task
pluk_get_task (task_id)       → Read full details
pluk_update_task (in_progress) → Mark as started
  ... do the work ...
pluk_update_task (needs_review, ai_coder_notes) → Submit for review
```

If a task lacks enough detail to start:

```
pluk_update_task (title="NEED INFO - ...", status=on_deck)
```

## Development

```bash
# Build
pnpm build

# Watch mode
pnpm dev

# Test locally with Claude Code (point .mcp.json at local build)
# "args": ["./packages/mcp-server/dist/index.js"]
```

## License

Private — Pluk.io