@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

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"]
    }
  }
}

For the development environment:

{
  "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

# 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