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 瞭解詳細信息。