npm package: @product-planner/mcp
Description: MCP server for Product Planner — exposes work items, boards, personas to AI assistants via stdio
Latest version: 1.0.0

# @product-planner/mcp

MCP server for [Product Planner](https://product-planner.com) — exposes work items, boards, personas, and more to AI assistants (GitHub Copilot, Claude, etc.) via the [Model Context Protocol](https://modelcontextprotocol.io/).

## Quick Start

```bash
npx @product-planner/mcp
```

On first run, a browser window opens for authentication. After login, tokens are cached locally so subsequent launches connect instantly.

## VS Code Configuration

Add to `.vscode/mcp.json` in your project:

```json
{
  "servers": {
    "product-planner": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@product-planner/mcp"]
    }
  }
}
```

For the development environment:

```json
{
  "servers": {
    "product-planner-dev": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@product-planner/mcp"],
      "env": {
        "PP_BASE_URL": "https://dev.product-planner.com",
        "PP_AUTH_ISSUER_BASE_URL": "https://auth.dev.product-planner.com"
      }
    }
  }
}
```

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `PP_BASE_URL` | `https://product-planner.com` | Product Planner BFF base URL |
| `PP_AUTH_ISSUER_BASE_URL` | `https://auth.product-planner.com` | OIDC issuer (OpenIddict) |
| `PP_AUTH_CLIENT_ID` | `d7301baa-3f8c-4e30-a952-d55b376e34d3` | OAuth client ID |
| `PP_AUTH_CLIENT_SECRET` | *(empty)* | OAuth client secret (optional) |
| `PP_AUTH_CALLBACK_PORT` | `17329` | Local port for OIDC callback |

## Authentication

The server uses **Authorization Code + PKCE** via your browser:

1. On first connection, checks `~/.nimles/mcp-tokens.json` for cached tokens
2. If tokens are valid → uses them (no browser popup)
3. If tokens are expired → attempts refresh via refresh token
4. If no tokens or refresh fails → opens browser for OIDC login
5. After successful login → caches tokens for next time

Token cache location: `~/.nimles/mcp-tokens.json`

## Available Tools

### Read Tools

| Tool | Description |
|------|-------------|
| `whoami` | Show the currently authenticated user |
| `list_workspaces` | List all workspaces the user has access to |
| `list_work_items` | List work items, optionally filtered by type/status/workspace |
| `get_work_item` | Get full details of a work item by ID |
| `get_work_item_tree` | Get hierarchical tree view starting from a work item |
| `search_work_items` | Search work items by title/description text |
| `list_boards` | List boards (Kanban/sprint) |
| `get_board` | Get board details including columns |
| `list_personas` | List user personas |
| `get_comments` | Get comments on a work item |
| `list_work_item_types` | List available work item types and their states |
| `get_ost_context` | Get the Opportunity Solution Tree for a workspace |
| `get_usm_context` | Get the User Story Map for a workspace |

### Write Tools

| Tool | Description |
|------|-------------|
| `create_workspace` | Create a new workspace |
| `create_work_item` | Create a new work item (by type name or GUID) |
| `update_work_item` | Update work item fields |
| `patch_work_item` | Apply RFC 6902 JSON Patch to a work item |
| `delete_work_item` | Delete a work item |
| `create_link` | Create a hierarchy or relationship link |
| `delete_link` | Delete a link |
| `add_comment` | Add a comment to a work item |
| `create_persona` | Create a user persona |
| `patch_persona` | Apply RFC 6902 JSON Patch to a persona |
| `create_board` | Create a new board |

## Work Item Types

Common types: `solution`, `userStory`, `opportunity`, `epic`, `feature`, `task`, `bug`, `assumption`, `experiment`, `activity`, `userTask`, `businessOutcome`, `productOutcome`

Use the `list_work_item_types` tool to see all available types and their valid states.

## Development

```bash
# Clone and install
git clone <repo-url>
cd product-planner-mcp
npm install

# Build
npm run build

# Run locally
node dist/index.js
```

## License

MIT