Productplan Mcp Server

1. 找到配置文件：

   • Mac：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json

2. 用任意文本编辑器打开文件并添加以下内容（将 your-token 替换为你的实际 API 令牌）：

Mac/Linux：

{
  "mcpServers": {
    "productplan": {
      "command": "/usr/local/bin/productplan",
      "env": {
        "PRODUCTPLAN_API_TOKEN": "your-token"
      }
    }
  }
}

Windows：

{
  "mcpServers": {
    "productplan": {
      "command": "C:\\Tools\\productplan.exe",
      "env": {
        "PRODUCTPLAN_API_TOKEN": "your-token"
      }
    }
  }
}

3. 重启 Claude Desktop

添加到配置文件：

• Mac/Linux：~/.claude.json
• Windows：%USERPROFILE%\.claude.json

Mac/Linux：

{
  "mcpServers": {
    "productplan": {
      "command": "/usr/local/bin/productplan",
      "env": {
        "PRODUCTPLAN_API_TOKEN": "your-token"
      }
    }
  }
}

Windows：

{
  "mcpServers": {
    "productplan": {
      "command": "C:\\Tools\\productplan.exe",
      "env": {
        "PRODUCTPLAN_API_TOKEN": "your-token"
      }
    }
  }
}

1. 打开 Cursor
2. 转到 设置 → MCP 服务
3. 添加以下配置：

Mac/Linux：

{
  "productplan": {
    "command": "/usr/local/bin/productplan",
    "env": {
      "PRODUCTPLAN_API_TOKEN": "your-token"
    }
  }
}

Windows：

{
  "productplan": {
    "command": "C:\\Tools\\productplan.exe",
    "env": {
      "PRODUCTPLAN_API_TOKEN": "your-token"
    }
  }
}

Windows 用户：路径中使用双反斜杠（\\）。这是必需的，因为在 JSON 中，反斜杠是转义字符。

1. 安装 Cline 扩展
2. 打开 VS Code 设置（JSON）并添加：

Mac/Linux：

{
  "cline.mcpServers": {
    "productplan": {
      "command": "/usr/local/bin/productplan",
      "env": {
        "PRODUCTPLAN_API_TOKEN": "your-token"
      }
    }
  }
}

Windows：

{
  "cline.mcpServers": {
    "productplan": {
      "command": "C:\\Tools\\productplan.exe",
      "env": {
        "PRODUCTPLAN_API_TOKEN": "your-token"
      }
    }
  }
}

1. 安装 Continue 扩展
2. 添加到配置文件：
   • Mac/Linux：~/.continue/config.json
   • Windows：%USERPROFILE%\.continue\config.json

Mac/Linux：

{
  "mcpServers": [
    {
      "name": "productplan",
      "command": "/usr/local/bin/productplan",
      "env": {
        "PRODUCTPLAN_API_TOKEN": "your-token"
      }
    }
  ]
}

Windows：

{
  "mcpServers": [
    {
      "name": "productplan",
      "command": "C:\\Tools\\productplan.exe",
      "env": {
        "PRODUCTPLAN_API_TOKEN": "your-token"
      }
    }
  ]
}

1. 在 n8n 实例上设置环境变量：

   N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true
   

2. 在工作流中添加一个 MCP 客户端节点
3. 配置：
   • 命令：
     • Mac/Linux：/usr/local/bin/productplan
     • Windows：C:\Tools\productplan.exe
   • 环境变量：PRODUCTPLAN_API_TOKEN=your-token
4. 连接到 AI Agent 节点

工作流示例：Slack Trigger → AI Agent (with MCP Client) → Slack Response

productplan-mcp-server/
├── cmd/productplan/main.go      # Entry point: token check, then MCP server or CLI
├── internal/
│   ├── api/                     # ProductPlan API client
│   │   ├── client.go            # HTTP client: auth, rate limiting, error wrapping
│   │   ├── transport.go         # Tuned HTTP transport
│   │   ├── cache.go             # In-process TTL read cache (singleflight, write invalidation)
│   │   ├── list.go              # Paged collection GETs and Ransack query encoding
│   │   ├── ids.go               # Typed resource IDs (BarID, RoadmapID, ...), each validated into a path segment
│   │   ├── path.go              # Routes and request paths built only from typed IDs
│   │   ├── safeseg.go           # Path-segment validation for user-supplied IDs
│   │   ├── endpoints*.go        # Endpoint methods (roadmaps, bars, ideas, launches, OKRs)
│   │   ├── bars_read.go         # Roadmap bars with lane enrichment and client-side filters
│   │   ├── bar_schema.go        # Roadmap legends/lanes/custom fields for bar writes
│   │   └── formatters.go        # Response projection for AI
│   ├── mcp/                     # MCP wiring over the official go-sdk
│   │   ├── sdk_server.go        # Serves the registry via go-sdk (stdio)
│   │   ├── sdk.go               # Converts local Tool -> SDK tool
│   │   ├── handler.go           # Registry: dispatch and panic recovery
│   │   ├── argkeys.go           # Rejects undeclared argument keys (did-you-mean)
│   │   ├── editdistance.go      # Levenshtein distance for suggestions
│   │   └── types.go             # Tool-authoring types
│   ├── tools/                   # Tool definitions and handlers
│   │   ├── registry.go          # Tool registration (name -> handler)
│   │   ├── definitions*.go      # Tool schemas and descriptions
│   │   ├── helpers.go           # typedHandler, manage-action dispatch
│   │   ├── filters.go           # List-tool filters -> Ransack predicates
│   │   ├── formatter.go         # List/item/action response summaries
│   │   ├── item_type.go         # Item nouns for summaries
│   │   ├── bar_planner.go       # Validates bar writes against the roadmap
│   │   ├── bar_names.go         # Legend/lane/custom field name resolution
│   │   ├── bulk_bars.go         # bulk_update/create/delete_bars
│   │   ├── roadmaps.go, bars.go, ideas.go, objectives.go, launches.go, utility.go  # handlers
│   │   └── types*.go            # Typed argument structs for handlers
│   ├── cli/                     # CLI commands (status, roadmaps, etc.)
│   │   └── cli.go
│   └── logging/                 # slog JSON handler setup (ts/level/msg)
│       └── logger.go
├── pkg/productplan/             # Reusable utilities
│   ├── retry.go                 # Exponential backoff with jitter
│   ├── ratelimit.go             # Adaptive rate limiting
│   ├── batch.go                 # Batched operations
│   ├── health.go                # Health reporting
│   ├── requestid.go             # Request tracing
│   ├── validation.go            # ID validation (Field.RequireID)
│   └── errors.go                # APIError and error suggestions
└── evals/                       # LLM evaluation test suite
    ├── runner.go, types.go
    ├── tool_selection.json
    ├── confusion_pairs.json
    └── argument_correctness.json

需要 Go 1.26 或更高版本。

git clone https://github.com/olgasafonova/productplan-mcp-server.git
cd productplan-mcp-server
go build -o productplan ./cmd/productplan

为所有平台构建：

# macOS Apple Silicon
GOOS=darwin GOARCH=arm64 go build -o dist/productplan-darwin-arm64 ./cmd/productplan

# macOS Intel
GOOS=darwin GOARCH=amd64 go build -o dist/productplan-darwin-amd64 ./cmd/productplan

# Linux
GOOS=linux GOARCH=amd64 go build -o dist/productplan-linux-amd64 ./cmd/productplan

# Windows
GOOS=windows GOARCH=amd64 go build -o dist/productplan-windows-amd64.exe ./cmd/productplan

运行所有测试：

go test ./...

运行并生成覆盖率报告：

go test ./... -cover

运行基准测试：

go test ./internal/... -bench=. -benchmem

运行评估套件：

./scripts/run-evals.sh

覆盖率（于 24-09-2026 测量，go test ./... -cover）：

所有生产文件在 CodeScene Code Health 中均获得 10.0 分（其中两个仅包含类型的文件无法评分）。

共有 50 个工具可用：35 个读取工具和 15 个写入工具（12 个基于操作的 manage_* 工具，以及 3 个 bulk_* 进度条工具）：

读取工具：

• 路线图：list_roadmaps、get_roadmap、get_roadmap_bars、get_roadmap_lanes、get_roadmap_milestones、get_roadmap_legends、get_roadmap_comments、get_roadmap_complete
• 进度条：get_bar、get_bar_children、get_bar_comments、get_bar_connections、get_bar_links
• OKR：list_objectives、get_objective、list_key_results、get_key_result
• 发现：list_ideas、get_idea、list_all_customers、list_all_tags、list_opportunities、get_opportunity、list_idea_forms、get_idea_form
• 发布：list_launches、get_launch、get_launch_sections、get_launch_section、get_launch_tasks、get_launch_task
• 管理：check_status、health_check、list_users、list_teams

写入工具：

• 路线图：manage_bar、manage_lane、manage_milestone
• 进度条关系：manage_bar_connection、manage_bar_link
• 批量进度条：bulk_update_bars、bulk_create_bars、bulk_delete_bars（每次调用最多 100 个进度条，会预先验证，支持 dry_run）
• OKR：manage_objective、manage_key_result
• 发现：manage_idea、manage_opportunity
• 发布：manage_launch、manage_launch_section、manage_launch_task

示例：

{"tool": "list_roadmaps", "arguments": {}}
{"tool": "manage_bar", "arguments": {"action": "create", "roadmap_id": "123", "lane": "Backend", "name": "New feature", "legend": "Committed"}}
{"tool": "bulk_update_bars", "arguments": {"set": {"legend": "Committed"}, "items": [{"bar_id": "901"}, {"bar_id": "902"}], "dry_run": true}}
{"tool": "manage_idea", "arguments": {"action": "create", "name": "Mobile app improvements"}}

该服务采用清晰的分层架构：

┌──────────────────────────────────────────────────────────────┐
│                        cmd/productplan                        │
│                     (entry point, DI)                         │
└──────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
┌───────────────┐    ┌───────────────┐    ┌───────────────┐
│  internal/cli │    │  internal/mcp │    │internal/tools │
│  (CLI cmds)   │    │  (MCP / SDK)  │    │  (handlers)   │
└───────────────┘    └───────────────┘    └───────────────┘
                              │                     │
                              └──────────┬──────────┘
                                         ▼
                              ┌───────────────────┐
                              │   internal/api    │
                              │  (HTTP client)    │
                              └───────────────────┘
                                         │
                                         ▼
                              ┌───────────────────┐
                              │  ProductPlan API  │
                              └───────────────────┘

关键接口：

// Tool handler interface (internal/mcp)
type Handler interface {
    Handle(ctx context.Context, args map[string]any) (json.RawMessage, error)
}

// Logging (internal/logging): a *slog.Logger with a JSON handler on stderr
logger := logging.New(slog.LevelInfo)

日志格式：

{"ts":"2026-09-24T10:30:00.123456789Z","level":"debug","msg":"API response","endpoint":"/roadmaps/5","status_code":200,"dur_ms":245}