Productplan MCP Server

🚀 ProductPlan MCP Server

借助人工智能与您的产品路线图进行交互。通过与Claude、Cursor或其他AI助手进行自然对话，您可以提出问题、产生新想法、检查OKR进度并管理产品发布。

🚀 快速开始

步骤1：获取您的ProductPlan API令牌

1. 登录 ProductPlan。
2. 前往 设置 → API（或直接访问 此链接）。
3. 复制您的API令牌。

步骤2：下载应用程序

前往 发布页面，为您的计算机下载合适的文件：

在Mac/Linux系统上，打开终端并运行以下两条命令（将文件名替换为您下载的文件）：

chmod +x ~/Downloads/productplan-darwin-arm64
sudo mv ~/Downloads/productplan-darwin-arm64 /usr/local/bin/productplan

系统会提示您输入密码，这是正常现象。

在Windows系统上：

1. 创建一个用于存放二进制文件的文件夹（如果该文件夹不存在）：

   mkdir C:\Tools
   

2. 将下载的 .exe 文件移动到该文件夹并重新命名：

   move %USERPROFILE%\Downloads\productplan-windows-amd64.exe C:\Tools\productplan.exe
   

3. 在您的AI助手配置中使用完整路径 C:\Tools\productplan.exe（步骤3会展示）。

注意：您可以跳过将其添加到系统路径的步骤，只需在配置中使用完整的文件路径即可。

步骤3：连接到您的AI助手

选择您使用的工具：

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

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

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

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

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

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

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

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

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

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

步骤4：开始提问

打开您的AI助手并尝试以下问题：

• "列出我的ProductPlan路线图"
• "路线图 [名称] 上有哪些项目？"
• "展示我们的OKR"
• "处于探索阶段的想法有哪些？"

✨ 主要特性

• 自然语言交互：无需在ProductPlan界面中进行繁琐的点击操作，只需通过自然语言与AI助手对话，即可获取所需信息。
• 多角色适用：适用于产品经理、团队领导以及使用AI助手的各类人员，无需编写代码。
• 实时数据访问：AI能够快速获取您的真实ProductPlan数据，并在数秒内给出响应。
• 丰富的数据操作：支持对ProductPlan中的各种数据进行查看、创建、编辑和删除等操作。

📦 安装指南

按照上述快速开始部分的步骤1 - 2进行操作，即可完成应用程序的下载和安装。

💻 使用示例

基础用法

在连接好AI助手后，您可以直接向其提问，例如：

"第一季度的路线图上有什么？"

高级用法

您还可以使用更复杂的问题来获取特定信息，例如：

"列出所有标记为'客户请求'的想法"

📚 详细文档

实际应用场景

每日站会准备

"总结过去一周我们产品路线图上的变化"

利益相关者更新

"列出第一季度的所有目标及其进度"

想法筛选

"展示所有标记为'企业级'但未设置优先级的想法"

发布协调

"一月份发布的任务中，还有哪些未完成？"

快速查询

"移动应用v2项目计划何时开始？"

可访问的ProductPlan数据

工作原理

┌─────────────────┐      spawns       ┌─────────────────┐      API calls     ┌─────────────────┐
│   AI Assistant  │ ───────────────── │   MCP Server    │ ─────────────────▶ │   ProductPlan   │
│ (Claude, Cursor)│ ◀───────────────▶ │   (this binary) │ ◀───────────────── │      API        │
└─────────────────┘   stdin/stdout    └─────────────────┘     JSON data      └─────────────────┘
      your computer                        your computer                         cloud

为什么需要在本地运行？

MCP（模型上下文协议）通过子进程模型工作。您的AI助手不会连接到远程服务器，而是将二进制文件作为本地进程启动，并通过标准输入/输出进行通信。这种架构意味着：

1. 二进制文件必须本地存在，因为您的AI助手将其作为子进程运行。
2. 您的API令牌保留在本地机器上，不会通过第三方服务器。
3. 实现实时、同步通信，避免了AI与MCP服务器之间的网络延迟。
4. 支持离线使用缓存数据（不过，调用ProductPlan API仍需要网络连接）。

当您询问 "第一季度的路线图上有什么？" 时，会发生以下过程：

1. 您的AI助手识别到需要ProductPlan数据。
2. 它向MCP服务器进程发送结构化请求。
3. 二进制文件将此请求转换为ProductPlan API调用。
4. ProductPlan返回JSON数据。
5. 二进制文件对结果进行格式化并返回给您的AI。
6. 您的AI以自然语言呈现答案。

代理技能

预构建的工作流指南，可指导AI助手如何有效使用ProductPlan工具。每个技能针对特定角色提供定制化的工作流。

共享原则

所有技能遵循以下输出约定：

• 不输出原始JSON：将响应格式化为易读的文本和表格。
• 使用人类可读的日期：使用 "2025年3月" 或 "2025年第一季度"，而不是 "2025-03-15"。
• 总结长列表：避免列出50项内容让用户感到困惑，可提供展开查看的选项。

特定角色的变化：

• 产品经理：包含 bar_id 以便进行后续操作。
• 高管：以执行摘要开头，隐藏实施细节。
• 面向客户：完全省略内部ID、车道名称和OKR。

使用技能的方法： 将 SKILL.md 文件复制到您的Claude Code技能目录：

# 复制一个技能（示例：产品经理技能）
cp skills/productplan-pm/SKILL.md ~/.claude/skills/productplan-pm.md

或者在您的提示中直接引用技能：

"使用productplan-pm工作流展示我们第一季度的路线图"

故障排除

"Command not found" 或 "spawn ENOENT"

您的AI助手无法找到二进制文件。这可能意味着：

• Mac/Linux：文件不在 /usr/local/bin/productplan 路径下，或者您忘记运行 chmod +x 命令。
• Windows：配置中的路径与您保存 .exe 文件的位置不匹配。

解决方法：验证二进制文件是否存在于配置中的路径下。在Mac/Linux系统上运行 ls -la /usr/local/bin/productplan，在Windows系统上检查 C:\Tools\productplan.exe 是否存在。

Windows路径问题

Windows系统上常见的错误：

Windows使用反斜杠 (\) 作为路径分隔符，但JSON将反斜杠视为转义字符。因此，在配置文件中必须使用双反斜杠 (\\)。

"Invalid API token"

请在 ProductPlan设置 → API 中仔细检查您的令牌。令牌可能会过期或需要重新生成。确保您复制的令牌完整且没有多余的空格。

"No roadmaps found"

您的API令牌只能访问您在ProductPlan中有权限查看的数据。请检查您的账户是否有权限访问您正在查找的路线图。

AI助手无法识别ProductPlan工具

MCP服务器在AI助手启动时加载，而不是在配置文件更改时加载。编辑配置文件后，请完全退出并重新启动应用程序。在Mac系统上，使用Cmd+Q（而不是仅关闭窗口）。

Mac/Linux系统上的 "Permission denied"

二进制文件需要执行权限。运行以下命令：

chmod +x /usr/local/bin/productplan

命令行使用（可选）

您也可以在终端中直接使用此工具，而无需AI助手：

# 首先，设置您的令牌
export PRODUCTPLAN_API_TOKEN="your-token"

# 然后运行命令
productplan status           # 检查连接
productplan roadmaps         # 列出所有路线图
productplan bars 12345       # 列出路线图 #12345 中的项目
productplan objectives       # 列出所有OKR
productplan ideas            # 列出所有想法
productplan opportunities    # 列出所有机会
productplan launches         # 列出所有发布

背景信息

什么是MCP？

模型上下文协议 (MCP) 是一个开放标准，允许AI助手连接到外部工具。该协议由Anthropic创建，其他AI提供商也在采用。此服务器实现了MCP，使您的AI助手能够读写ProductPlan数据。

什么是ProductPlan？

ProductPlan 是一款路线图软件，被4000多个产品团队使用。它可用于管理路线图、OKR、想法探索和发布协调。

开发者相关

项目结构

productplan-mcp-server/
├── cmd/productplan/main.go      # 入口点 (~100行)
├── internal/
│   ├── api/                     # ProductPlan API客户端
│   │   ├── client.go            # 带有缓存、重试和速率限制的HTTP客户端
│   │   ├── endpoints.go         # 40多个API端点方法
│   │   └── formatters.go        # 为AI丰富响应内容
│   ├── mcp/                     # MCP协议实现
│   │   ├── server.go            # JSON-RPC服务器，标准输入/输出
│   │   ├── handler.go           # 通过注册表进行工具调度
│   │   └── types.go             # 协议类型
│   ├── tools/                   # 工具定义和处理程序
│   │   ├── registry.go          # 工具注册和调度
│   │   └── types.go             # 处理程序的类型化参数结构体
│   ├── cli/                     # CLI命令（状态、路线图等）
│   │   └── cli.go
│   └── logging/                 # 结构化JSON日志记录
│       └── logger.go
├── pkg/productplan/             # 可重用的实用工具
│   ├── cache.go                 # 带有TTL的LRU缓存
│   ├── retry.go                 # 带有抖动的指数退避算法
│   ├── ratelimit.go             # 自适应速率限制
│   ├── registry.go              # 用于模式生成的ToolBuilder
│   ├── requestid.go             # 请求跟踪
│   └── errors.go                # 错误建议
└── evals/                       # LLM评估测试套件
    ├── tool_selection.json
    ├── confusion_pairs.json
    └── argument_correctness.json

从源代码构建

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

覆盖率目标：

MCP工具参考

有47个可用工具：35个读取工具和12个写入工具（基于操作）。

读取工具：

• 路线图：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
• 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_id": "456", "name": "New feature"}}
{"tool": "manage_idea", "arguments": {"action": "create", "name": "Mobile app improvements"}}

架构

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

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

关键接口：

// 工具处理程序接口 (internal/mcp)
type Handler interface {
    Handle(ctx context.Context, args map[string]any) (json.RawMessage, error)
}

// 日志记录器接口 (internal/logging)
type Logger interface {
    Debug(msg string, fields ...Field)
    Info(msg string, fields ...Field)
    Warn(msg string, fields ...Field)
    Error(msg string, fields ...Field)
}

日志记录格式：

{"ts":"2024-12-26T10:30:00Z","level":"info","req_id":"ab12","op":"get_roadmap_bars","dur_ms":245}

变更日志

有关发布历史和详细更改，请参阅 CHANGELOG.md。

喜欢这个项目？

如果这个服务器为您节省了时间，不妨在GitHub上给它点个 ⭐。这有助于其他用户发现该项目。

更多MCP服务器

查看我的其他MCP服务器：

服务器	描述	星标数
gleif-mcp-server	访问GLEIF LEI数据库。查找公司身份，验证法律实体。
mediawiki-mcp-server	将AI连接到任何MediaWiki维基。搜索、读取、编辑维基内容。
miro-mcp-server	使用AI控制Miro白板。包括白板、图表、思维导图等。
nordic-registry-mcp-server	访问北欧商业注册中心。查找挪威、丹麦、芬兰、瑞典的公司信息。

📄 许可证

本项目采用MIT许可证，请参阅 LICENSE 了解详细信息。