@product-planner/mcp

MCP server for Product Planner — exposes work items, boards, personas, and more to AI assistants (GitHub Copilot, Claude, etc.) via the Model Context Protocol.

Quick Start

npx @product-planner/mcp              # production
npx @product-planner/mcp development  # dev environment

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:

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

For the development environment:

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

Environment Argument

product-planner-mcp [environment] — the first positional argument selects the target:

| Argument | BFF URL | Issuer | |----------|---------|--------| | (omitted), production, prod | https://product-planner.com | https://auth.product-planner.com | | development, dev | https://dev.product-planner.com | https://auth.dev.product-planner.com | | <host> (e.g. my.example.com) | https://<host> | https://auth.<host> |

Environment Variables

Set these only to override the environment argument.

| Variable | Description | |----------|-------------| | PP_BASE_URL | Product Planner BFF base URL | | PP_AUTH_ISSUER_BASE_URL | OIDC issuer (OpenIddict) | | PP_AUTH_CLIENT_ID | OAuth client ID (default: d7301baa-3f8c-4e30-a952-d55b376e34d3) | | PP_AUTH_CLIENT_SECRET | OAuth client secret (optional) | | PP_AUTH_CALLBACK_PORT | Local port for OIDC callback (default: 17329) |

Authentication

The server uses Authorization Code + PKCE via your browser:

1. On first connection, checks ~/.nimles/mcp-tokens.<issuer>.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.<issuer>.json — one file per environment, so production and development sessions do not overwrite each other.

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 | | set_work_item_persona | Set or clear the persona of a work item (e.g. an opportunity) | | set_opportunity_metrics | Set which outcome metrics an opportunity aims to move | | add_comment | Add a comment to a work item | | add_external_link | Link a work item to a work item in Azure DevOps by URL | | remove_external_link | Remove a hand-added Azure DevOps link | | 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.

Agent Skill

skills/product-planner/SKILL.md teaches an AI assistant to work with Opportunity Solution Trees and User Story Maps through this server, and to break a Product Planner work item down into Azure DevOps work items with the Azure DevOps MCP server, linking them back.

Copy the product-planner folder into your skills folder, e.g. .github/skills/ in your repository (GitHub Copilot) or .claude/skills/ (Claude Code). The skill is also included in the npm package, under skills/.

Development

# 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