AI导哈

Productboard API服务器

一个提供对Productboard REST API全面访问的模型上下文协议（MCP）服务器，支持智能动态工具加载、基于类别的过滤和基于角色的配置文件。

  • by cfdude
  • TypeScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 cfdude/productboard-mcp

使用说明

产品板MCP服务器

模型上下文协议（MCP）服务器，通过智能动态工具加载、基于类别的过滤和基于角色的配置文件，提供对Productboard的REST API的全面访问。

🚀 主要特点

  • 动态工具加载：按需加载119+个API操作，以最大限度地减少内存使用
  • 基于类别的组织：工具分为15+个逻辑类别
  • 压缩数据视图：灵活的细节级别（基本/标准/完整），以优化响应
  • 基于角色的配置文件：为不同用户类型预先配置的工具集
  • 自动生成的工具：直接从OpenAPI规范生成工具实现
  • 多工作区支持：无缝管理多个Productboard实例
  • 完全支持TypeScript：具有全面接口的类型安全实现
  • 向后兼容：需要时退回到静态工具

📦 安装

选项1：通过Smithery（推荐）

smithery install productboard

然后添加到您的Claude Desktop配置中：

{
  "mcpServers": {
    "productboard": {
      "command": "node",
      "args": ["${SMITHERY_PATH}/productboard/build/index.js"],
      "env": {
        "PRODUCTBOARD_API_TOKEN": "your-api-token"
      }
    }
  }
}

选项2:Docker

# Using Docker Compose (recommended)
git clone https://github.com/cfdude/productboard-mcp.git
cd productboard-mcp

# Create .env file
echo "PRODUCTBOARD_API_TOKEN=your-api-token" > .env

# Run the server
docker-compose up -d

# Or using Docker directly
docker run -d \
  --name productboard-mcp \
  -e PRODUCTBOARD_API_TOKEN="your-api-token" \
  ghcr.io/cfdude/productboard-mcp:latest

选项3:NPM包

npm install @the_cfdude/productboard-mcp

选项4：来源

git clone https://github.com/cfdude/productboard-mcp.git
cd productboard-mcp
npm install
npm run build

注： generated/ 目录是在构建过程中自动创建的。清单和工具文件是根据OpenAPI规范生成的。

🔧 配置

基本设置

创建一个 .productboard-config.json 项目根目录中的文件：

{
  "instances": {
    "default": {
      "apiToken": "YOUR_API_TOKEN",
      "baseUrl": "https://api.productboard.com",
      "rateLimitPerMinute": 60
    }
  },
  "defaultInstance": "default",
  "toolCategories": {
    "enabled": ["*"] // Enable all tools
  }
}

高级配置

基于角色的配置文件

{
  "toolCategories": {
    "activeProfile": "product-manager" // or "customer-success", "developer"
  }
}

自定义工具选择

{
  "toolCategories": {
    "enabled": ["notes", "features", "companies", "releases"],
    "disabled": ["jiraintegrations", "pluginintegrations"]
  }
}

多工作区设置

{
  "instances": {
    "production": {
      "apiToken": "PROD_TOKEN",
      "baseUrl": "https://api.productboard.com"
    },
    "staging": {
      "apiToken": "STAGING_TOKEN",
      "baseUrl": "https://api-staging.productboard.com"
    }
  },
  "workspaces": {
    "main": {
      "instance": "production",
      "workspaceId": "main-workspace"
    },
    "test": {
      "instance": "staging",
      "workspaceId": "test-workspace"
    }
  }
}

📚 工具类别

核心产品管理

  • 特征 （22个工具）：功能管理、路线图和优先级
  • 组件 （3个工具）：组件层次结构和组织
  • 产品 （3个工具）：产品线管理
  • 发布 （5个工具）：发布计划和跟踪
  • 发布组 （4个工具）：多团队发布协调

客户洞察

  • 笔记 （15个工具）：客户反馈、见解和研究
  • 公司 （5个工具）：公司/账户管理
  • 用户 （2个工具）：用户概况和细分
  • 公司和用户 （18个工具）：组合客户数据操作

规划与战略

  • 目标 （11个工具）：战略目标和OKR
  • 关键结果 （5个工具）：可衡量的结果和关键绩效指标
  • 倡议 （11个工具）：高级别战略举措
  • 状态 （1个工具）：功能状态工作流

定制

  • 自定义字段 （6个工具）：自定义字段定义和值
  • 层次结构实体自定义字段 （3个工具）：特定于实体的自定义字段

集成

  • 网上挂钩 （4个工具）：事件通知和订阅
  • 插件集成 （10个工具）：第三方集成管理
  • jira集成 （4个工具）：Jira特定的集成

🔍 压缩数据视图

许多工具支持灵活的细节级别，以优化响应大小和性能：

细节级别

  • basic -最小字段（id、名称和基本标识符）
  • standard -典型用例的常用字段（默认）
  • full -所有可用字段，包括嵌套数据

支持的工具

具有压缩数据支持的工具包括：

  • get_features / list_features
  • get_components / list_components
  • get_products / list_products
  • get_releases / list_releases
  • get_notes / list_notes
  • get_companies / list_companies
  • get_users / list_users
  • get_objectives / list_objectives
  • get_initiatives / list_initiatives
  • get_webhooks / list_webhooks

使用示例

// Get basic feature information (minimal fields)
{
  "tool": "get_features",
  "arguments": {
    "detail": "basic",
    "limit": 100
  }
}

// Get standard feature details (default)
{
  "tool": "get_features",
  "arguments": {
    "detail": "standard"
  }
}

// Get full feature data including all nested objects
{
  "tool": "get_features",
  "arguments": {
    "detail": "full",
    "includeSubData": true
  }
}

性能提示

  1. 使用 basic 详细程度：

    • 大型数据集
    • 按ID/名称快速查找
    • 初步探究

  2. 使用 standard 详细程度：

    • 最常见的操作
    • 平衡细节与性能

  3. 使用 full 详细程度：

    • 完成数据导出
    • 详细的分析
    • 当所有字段都需要时

  4. 这 includeSubData 参数：

    • 当 true：返回所有嵌套的JSON数据
    • 当 false：基于细节级别的过滤器
    • 可用于控制响应大小

🎯 使用示例

使用克劳德桌面

选项A：使用Claude桌面连接器（新！）

  1. 打开克劳德桌面设置
  2. 导航到“连接器”部分
  3. 点击“添加连接器”
  4. 搜索“产品板MCP”
  5. 输入您的API令牌并选择您的首选工具配置文件
  6. 点击“连接”

选项B：手动配置

添加到您的Claude Desktop配置中：

{
  "mcpServers": {
    "productboard": {
      "command": "node",
      "args": ["/path/to/productboard-mcp/build/index.js"],
      "env": {
        "PRODUCTBOARD_API_TOKEN": "your-api-token"
      }
    }
  }
}

常用工具示例

// Create a note from customer feedback
notes_create({
  title: 'Feature request: Dark mode',
  content: 'Customer wants dark mode support',
  tags: ['ui', 'enhancement'],
  user: { email: 'customer@example.com' },
});

// List features with filtering
features_list({
  limit: 50,
  status: 'in-progress',
  includeRaw: false,
});

// Create a release
releases_create({
  name: 'Q1 2025 Release',
  description: 'Major feature updates',
  startDate: '2025-01-01',
  endDate: '2025-03-31',
});

🛠️ 发展

从OpenAPI生成工具

# 1. Generate tool manifest (required first)
npm run generate-manifest

# 2. Generate missing tool implementations
npm run generate-tools

# 3. Build the TypeScript project
npm run build

测试

# Run the MCP inspector
npm run dev

# Test dynamic loading system
npx tsx scripts/test-dynamic-loading.ts

项目结构

productboard-mcp/
├── src/
│   ├── tools/
│   │   ├── registry.ts        # Dynamic tool loading system
│   │   ├── index-dynamic.ts   # Dynamic tool handler
│   │   └── *.ts              # Tool implementations
│   ├── utils/
│   │   └── tool-wrapper.ts   # API client wrapper
│   └── productboard-server.ts # Main server class
├── generated/
│   ├── manifest.json          # Tool metadata
│   └── tools/                 # Auto-generated tools
├── scripts/
│   ├── generate-manifest.ts   # Manifest generator
│   └── generate-tools.ts      # Tool generator
└── .productboard-config.json  # Your configuration

🔍 动态加载架构

服务器使用三层方法：

  1. 发现：工具清单提供元数据而不加载代码
  2. 注册：工具在惰性加载器中注册
  3. 执行：仅在调用工具时加载实现

这使得：

  • 快速启动时间
  • 最小内存使用
  • 动态工具过滤
  • 运行时配置更新

🔐 安全

  • API令牌应存储在 .productboard-config.json （忽略）
  • 使用CI/CD的环境变量： PRODUCTBOARD_API_TOKEN
  • 示例配置使用占位符值
  • 永远不要将真正的令牌提交给版本控制

📊 演出

  • 初始负载：~50ms（仅清单）
  • 第一次工具调用：~100ms（包括动态导入）
  • 后续调用：<10ms（缓存处理程序）
  • 内存使用量：约20MB基本+每个加载类别1-2MB

🤝 贡献

  1. 分叉存储库
  2. 创建要素分支
  3. 跑 npm run generate-manifest API变更后
  4. 提交拉取请求

📄 许可证

MIT许可证-有关详细信息，请参阅许可证文件

🔗 资源

📝 未来改进

根据代码审查反馈，以下是对未来开发的改进建议：

类型安全增强

  • []替换 any 在整个代码库中使用正确的TypeScript接口的类型
  • []为API响应创建特定类型，而不是使用泛型类型
  • []为工具参数和返回值添加更严格的类型检查

错误处理改进

  • []针对不同的API故障场景实现更细粒度的错误类型
  • []添加针对瞬态故障的指数回退重试逻辑
  • []改进错误消息，为用户提供可操作的建议

代码组织

  • []考虑将大型工具文件（features.ts、notes.ts）拆分为较小的模块
  • []将常见模式提取到共享实用程序中
  • []实现适当的依赖注入模式以获得更好的可测试性

测试增强功能

  • []添加模拟Productboard API的集成测试
  • []提高边缘情况和错误场景的测试覆盖率
  • []添加动态工具加载的性能基准

文档

  • []为所有公共函数和接口添加JSDoc注释
  • []为复杂的工具使用模式创建详细的示例
  • []更彻底地记录工具生成过程

性能优化

  • []为多个API调用实现请求批处理
  • []添加具有可配置TTL的响应缓存
  • []优化清单生成以加快启动速度

增强的安全性

  • []为所有工具参数添加输入验证
  • []在MCP服务器级别实施速率限制
  • []为敏感操作添加审核日志记录

🏗️ Roadmap

  • []为常用工具添加缓存层
  • []实施工具使用分析
  • []添加GraphQL支持
  • []创建工具组合工作流
  • []添加速率限制处理策略

内置于❤️ 面向Productboard社区

相关 MCP