ProductPlan MCP

产品计划MCP服务器

 

使用AI与你的路线图对话。 通过与Claude、Cursor或其他人工智能助手的自然对话，提出问题、创造想法、检查OKR进度并管理发布。

你能用这个做什么？

不要点击ProductPlan的界面，只需问：

“我们的Q1路线图上有什么？”

“显示所有落后于计划的目标”

“为移动应用程序改进创造新想法”

“本月将推出哪些产品？”

“列出标记为“客户请求”的所有想法”

AI会获取您的真实ProductPlan数据，并在几秒钟内做出响应。

这是给谁的？

• 产品经理 谁想要更快地访问路线图数据
• 团队领导 需要快速更新状态而无需切换上下文
• 任何使用AI助手的人 （Claude、Cursor等）希望将ProductPlan集成到他们的工作流程中

无需编码。您将复制一个文件并粘贴一些设置。

______________________________________________________________________

快速启动（5分钟）

步骤1：获取ProductPlan API令牌

1. 登录 产品计划
2. 首选 设置 → API （或参观 这个链接 直接）
3. 复制您的API令牌

第二步：下载应用程序

去 发布页面 并为您的计算机下载正确的文件：

在Mac/Linux上，打开终端并运行以下两个命令（用下载的文件名替换文件名）：

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

系统会要求您输入密码。这很正常。

在Windows上:

1. 为二进制文件创建一个文件夹（如果它不存在）：

   mkdir C:\Tools

1. 移动已下载的 .exe 转到该文件夹并重命名：

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

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

备注：您可以跳过添加到PATH。只需在配置中使用完整的文件路径。

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

选择您使用的工具：

Claude Desktop (click to expand)

1. 查找您的配置文件：

- 苹果电脑: ~/Library/Application Support/Claude/claude_desktop_config.json - 视窗: %APPDATA%\Claude\claude_desktop_config.json

1. 在任何文本编辑器中打开它并添加此内容（替换 your-token 使用您的实际API令牌）：

Mac/Linux：

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

1. 重新启动克劳德桌面

Claude Code (Terminal)

添加到您的配置文件中：

• Mac/Linux: ~/.claude.json
• 视窗: %USERPROFILE%\.claude.json

Mac/Linux：

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

Cursor

1. 打开的游标
2. 首选 设置 → MCP服务器
3. 添加此配置：

Mac/Linux：

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

窗户：

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

windows用户：使用双反睫毛(\\)在路上。这是必需的，因为反斜杠是JSON中的转义字符。

VS Code + Cline

1. 安装 临床扩展
2. 打开VS代码设置（JSON）并添加：

Mac/Linux：

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

VS Code + Continue

1. 安装 继续扩展
2. 添加到您的配置文件中：

- Mac/Linux: ~/.continue/config.json - 视窗: %USERPROFILE%\.continue\config.json

Mac/Linux：

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

n8n (Workflow Automation)

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

   N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true

1. 添加一个 MCP客户端 节点到工作流
2. 配置：

- 命令: - Mac/Linux： /usr/local/bin/productplan - 窗户： C:\Tools\productplan.exe - 环境变量: PRODUCTPLAN_API_TOKEN=your-token

1. 连接到 AI 代理 节点

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

第四步：开始提问

打开你的AI助手，尝试：

• “列出我的产品计划路线图”
• “路线图上有哪些条\[名称\]？”
• “给我看看我们的OKR”
• “发现中有什么想法？”

______________________________________________________________________

真实世界的用例

晨间站立准备

“总结上周我们的产品路线图发生了什么变化”

利益相关者更新

“列出所有Q1目标及其进展”

想法分类

“显示所有标记为“企业”但没有设置优先级的想法”

启动协调

“1月份的发射还有哪些任务没有完成？”

快速查找

“计划何时启动‘移动应用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助手没有连接到远程服务器；它将二进制文件作为本地进程生成，并通过stdin/stdout进行通信。这种架构意味着：

1. 二进制文件必须在本地存在 因为你的AI助手将其作为子进程运行
2. 您的API令牌保留在您的计算机上，从不通过第三方服务器
3. 实时同步通信 AI和MCP服务器之间没有网络延迟
4. 离线工作 用于缓存数据（尽管ProductPlan API调用仍然需要互联网）

当你问“我们的Q1路线图上有什么？”时，会发生以下情况：

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

______________________________________________________________________

代理技能

预构建的工作流程指南，教人工智能助手如何有效地使用ProductPlan工具。每种技能都针对一个特定的角色，提供量身定制的工作流程。

共享原则

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

• 没有原始JSON -将响应格式化为可读文本和表格
• 人类可读日期 -使用“2025年3月”或“2025年第一季度”，而不是“2025-03-15”
• 汇总大列表 -不要被50个项目压垮；提供扩展

Persona特定变体：

• 项目经理 包括 bar_id 后续行动
• 领导力 以执行摘要开头，隐藏实施细节
• 面向客户的 完全省略了内部ID、通道名称和OKR

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

# Copy a skill (example: PM skill)
cp skills/productplan-pm/SKILL.md ~/.claude/skills/productplan-pm.md

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

“使用productplan pm工作流向我展示我们的Q1路线图”

______________________________________________________________________

故障排除

“找不到命令”或“生成ENOENT”

你的AI助手找不到二进制文件。这意味着：

• Mac/Linux：文件不在 /usr/local/bin/productplan，或者你忘了跑 chmod +x
• 视窗：配置中的路径与您保存的路径不匹配 .exe

修复：验证配置中的路径是否存在二进制文件。跑 ls -la /usr/local/bin/productplan （Mac/Linux）或检查 C:\Tools\productplan.exe 存在（Windows）。

Windows路径问题

Windows上的常见错误：

Windows使用反斜杠(\)对于路径，JSON将反斜杠视为转义符。你必须加倍(\\)在您的配置文件中。

“API令牌无效”

请仔细检查您的令牌 产品计划设置→ API令牌可以过期或重新生成。确保复制了完整的令牌，没有多余的空格。

“未找到路线图”

API令牌仅访问您有权在ProductPlan中查看的数据。检查您的帐户是否可以访问您正在寻找的路线图。

AI助手看不到ProductPlan工具

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

Mac/Linux上的“权限被拒绝”

二进制文件需要执行权限。运行：

chmod +x /usr/local/bin/productplan

______________________________________________________________________

命令行（可选）

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

# First, set your token
export PRODUCTPLAN_API_TOKEN="your-token"

# Then run commands
productplan status           # Check connection
productplan roadmaps         # List all roadmaps
productplan bars 12345       # List bars in roadmap #12345
productplan objectives       # List all OKRs
productplan ideas            # List all ideas
productplan opportunities    # List all opportunities
productplan launches         # List all launches

______________________________________________________________________

背景信息

什么是MCP？

模型上下文协议（MCP） 是一个开放标准，允许AI助手连接到外部工具。人为创造了它；其他AI提供商也在采用它。此服务器实现了MCP，因此您的AI助手可以读取和写入ProductPlan数据。

什么是产品计划？

产品计划 是4000多个产品团队使用的路线图软件。它处理路线图、OKR、创意发现和启动协调。

______________________________________________________________________

对于开发者

Project structure

productplan-mcp-server/
├── cmd/productplan/main.go      # Entry point (~100 lines)
├── internal/
│   ├── api/                     # ProductPlan API client
│   │   ├── client.go            # HTTP client with caching, retry, rate limiting
│   │   ├── endpoints.go         # 40+ API endpoint methods
│   │   └── formatters.go        # Response enrichment for AI
│   ├── mcp/                     # MCP protocol implementation
│   │   ├── server.go            # JSON-RPC server, stdio I/O
│   │   ├── handler.go           # Tool dispatch via registry
│   │   └── types.go             # Protocol types
│   ├── tools/                   # Tool definitions and handlers
│   │   ├── registry.go          # Tool registration and dispatch
│   │   └── types.go             # Typed argument structs for handlers
│   ├── cli/                     # CLI commands (status, roadmaps, etc.)
│   │   └── cli.go
│   └── logging/                 # Structured JSON logging
│       └── logger.go
├── pkg/productplan/             # Reusable utilities
│   ├── cache.go                 # LRU cache with TTL
│   ├── retry.go                 # Exponential backoff with jitter
│   ├── ratelimit.go             # Adaptive rate limiting
│   ├── registry.go              # ToolBuilder for schema generation
│   ├── requestid.go             # Request tracing
│   └── errors.go                # Error suggestions
└── evals/                       # LLM evaluation test suite
    ├── tool_selection.json
    ├── confusion_pairs.json
    └── argument_correctness.json

Build from source

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

Testing

运行所有测试：

go test ./...

跑步覆盖：

go test ./... -cover

运行基准测试：

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

运行评估套件：

./scripts/run-evals.sh

覆盖目标：

MCP tool reference

47个可用工具：35个READ工具和12个WRITE工具（基于动作）：

阅读工具：

• 路线图： 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
• OKRs： 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
• OKRs： 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"}}

Architecture

服务器使用干净的分层架构：

┌──────────────────────────────────────────────────────────────┐
│                        cmd/productplan                        │
│                     (entry point, DI)                         │
└──────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
┌───────────────┐    ┌───────────────┐    ┌───────────────┐
│  internal/cli │    │  internal/mcp │    │internal/tools │
│  (CLI cmds)   │    │ (JSON-RPC IO) │    │  (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)
}

// Logger interface (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}

______________________________________________________________________

更新日志

看 更改日志.md 查看发布历史和详细更改。

______________________________________________________________________

喜欢这个项目？

如果此服务器为您节省了时间，请考虑给它一个⭐ 在GitHub上。它帮助其他人发现项目。

______________________________________________________________________

更多MCP服务器

查看我的其他MCP服务器：

______________________________________________________________________

许可证

MIT许可证-请参阅 许可证