用途
ProductPlan MCP Server 是一个 MCP（模型上下文协议）服务器，用于将 AI 助手（如 Claude、Cursor 等）连接到 ProductPlan，使用户能通过自然语言对话与路线图、OKR、创意发现和发布功能交互，无需手动点击界面。
主要能力
用户可提出诸如“Q1 路线图里有什么？”“显示所有延期目标”“为移动应用改进创建一个新想法”“本月有哪些发布？”等问题。AI 会获取真实的 ProductPlan 数据并在数秒内回复。支持批量修改多个 bar，所有 bar 在写入前会逐一验证，并支持先执行 dry run。
服务器提供 50 个工具：35 个 READ 工具和 15 个 WRITE 工具（12 个基于 action 的 manage_* 加上 3 个 bulk_* bar 工具）。
- 路线图：list_roadmaps、get_roadmap、get_roadmap_bars、get_roadmap_lanes、get_roadmap_milestones、get_roadmap_legends、get_roadmap_comments、get_roadmap_complete
- Bar：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 个 bar）、manage_objective、manage_key_result、manage_idea、manage_opportunity、manage_launch、manage_launch_section、manage_launch_task
使用方式
快速开始（约 5 分钟）：
- 获取 ProductPlan API 令牌：登录 ProductPlan，进入 Settings → API，复制 API 令牌。
- 下载应用：从 Releases 页面下载对应操作系统的文件。Mac/Linux 需在终端运行命令并可能输入密码；Windows 需创建文件夹并将 .exe 移动到该文件夹并重命名，例如 C:\Tools\productplan.exe。
- 连接 AI 助手：根据所用工具配置。Claude Desktop 的配置文件在 Mac 为 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 为 %APPDATA%\Claude\claude_desktop_config.json，添加配置并替换令牌，然后重启。Cline、Continue、n8n 等也有对应配置方式。Windows 路径需使用双反斜杠。
- 开始提问：例如“列出我的 ProductPlan 路线图”“路线图 [名称] 上有哪些 bar？”“显示我们的 OKR”“发现中有哪些想法？”
可选：在终端直接使用该工具，无需 AI 助手。可选设置 PRODUCTPLAN_CACHE_TTL 控制读取结果在内存中的缓存时间（默认 60 秒，0 表示关闭缓存）。通过服务器所做的任何更改会立即清除缓存。
适用场景
- 产品经理快速访问路线图数据
- 团队负责人快速获取状态更新，避免上下文切换
- 任何使用 AI 助手（Claude、Cursor 等）并希望将 ProductPlan 集成到工作流中的人 实际用例包括：晨会准备（总结过去一周路线图变化）、干系人更新（列出 Q1 目标及进度）、发布协调（哪些任务未完成、bar 何时开始）。
限制
- ProductPlan API 本身不允许的操作，工具也无法完成：创建图例、设置泳道颜色、写评论、将已嵌套的 bar 从其容器中移除、创建 Azure DevOps 或 Jira 集成链接（通过 API 创建的链接是普通网页链接）。
- 需要本地运行二进制文件，因为 AI 助手将其作为子进程运行。API 令牌保留在用户机器上，不经过第三方服务器。
- 需要 Go 1.26 或更高版本进行构建。
- 颜色通过图例名称设置，而非 ID。6.0.0 之前的版本发送 legend_id，ProductPlan 会将其视为移除颜色。
- 自 6.0.0 起，服务器会拒绝工具没有的参数，并建议最接近的有效参数。
- 如果 AI 助手看不到 ProductPlan 工具，可能需要在编辑配置文件后完全退出并重启应用。
- 权限问题：API 令牌只能访问你在 ProductPlan 中有权限查看的数据。令牌可能过期或需要重新生成。
- 各平台路径和权限配置需注意，如 Mac/Linux 需要执行权限，Windows 路径需使用双反斜杠。
其他信息
该项目使用 MIT 许可证。提供预构建的工作流指南（技能），教 AI 助手如何有效使用 ProductPlan 工具，针对特定角色定制工作流。常见问题包括“Command not found”或“spawn ENOENT”、Windows 路径问题、“Invalid API token”、“No roadmaps found”、颜色未更改、“unknown argument”错误、Mac/Linux 上的“Permission denied”。
