Pixabay MCP Server

# 产品待办清单

更新时间：2025-09-28

## 产品愿景
为创作者、自动化代理与 AI 助手提供“低延迟 + 高可靠 + 可组合”的 Pixabay 媒体检索能力；通过标准化 MCP 协议降低多客户端集成门槛，并在安全与可观测性上比直接调用官方 API 更易用。

## 目标用户画像
| 角色 | 需求 | 关键价值 |
| ---- | ---- | ---- |
| AI 助手 / Agent | 快速检索与后续推理组合 | 标准化工具 schema，结构化返回 |
| 内容创作者 | 按主题/方向挑选素材 | 过滤/排序、分页、质量信息 |
| 开发集成者 | 稳定、明确错误语义 | 结构化错误 + 文档示例 |

## 核心指标 (北极星 + 支撑)
| 指标 | 描述 | 目标 (v0.5) |
| ---- | ---- | ---- |
| 成功检索率 | 成功响应 / 总请求 | ≥ 99% |
| 超时率 | 超时请求占比 | < 1% |
| 平均首字节延迟 | 工具调用到首响应 | < 1200ms |
| 返回结构化利用率 | 使用结构化 payload 的客户端占比 | ≥ 60% |

## 里程碑概览
| 版本 | 时间 (预估) | 主题 | 关键交付 |
| ---- | -------- | ---- | ---- |
| v0.3 (当前) | 已发布 | 基础稳定 | 图片/视频搜索 + 基础校验 |
| v0.4 | +2 周 | 可观测 & 结构化 | 结构化结果、统一错误模型、超时设置 |
| v0.5 | +4 周 | 体验增强 | 分页/排序、重试、测试覆盖、缓存雏形 |
| v0.6 | +6 周 | 多源扩展探索 | 其他源调研 + 抽象适配层 |

## 近期优先事项（下一个版本：v0.4）
| 优先级 | 标题 | 类型 | 验收标准 (DoD) | 价值 |
| --- | --- | --- | --- | --- |
| P0 | Axios 超时 + 可配置 | 可用性 | 默认 10s 超时；env: `PIXABAY_TIMEOUT_MS` 覆盖；超时返回结构化错误 | 避免悬挂请求 |
| P0 | 结构化错误返回 | DX | 所有错误附带 `{ status?, code, hint }` | 便于客户端分类处理 |
| P0 | 结构化结果 payload | 功能 | 每次调用返回 `text` + `json` 两种内容；json 含核心字段 | 上层自动化可直接解析 |
| P1 | 统一日志级别 | 维护 | info/ warn / error 分类；不含敏感参数 | 便于排查 | 
| P1 | 基础单元测试 | 质量 | 覆盖率 ≥ 行 40% / 分支 30%；关键路径 4 类用例 | 防回归 |
| P2 | 文档使用示例扩展 | 文档 | README 增加结构化返回示例与错误示例 | 降低集成咨询成本 |

## 下一阶段 (v0.5) 候选
| 优先级 | Backlog 项 | 说明 | 备注 |
| --- | --- | --- | --- |
| P0 | 分页参数 page 支持 | 传递并返回 `page`, `totalPages` | 需合并 rate 限制提示 |
| P0 | 简单重试策略 | 对网络/5xx 重试最多 2 次（指数退避） | 可开关 env | 
| P1 | 排序 order 支持 | `popular` / `latest` | 来自 Pixabay API 支持 |
| P1 | 可选缓存层 | 最近 N 组 query+参数 LRU（内存） | 降低重复请求时延 |
| P1 | 颜色/类别过滤 | 进阶过滤 | 需评估 API 参数映射 |
| P2 | 请求统计输出 | 每 50 次输出聚合日志 | 用于观察使用模式 |
| P2 | CI 集成 | GitHub Actions 构建 + test | 推进开源协作 |

## 技术债 & 优化项
| 类别 | 项目 | 影响 | 解决策略 | 目标版本 |
| ---- | ---- | ---- | ---- | ---- |
| 结构 | 单文件 >500 行 | 扩展困难 | 模块化拆分 | v0.5 |
| 测试 | 目前 0 测试 | 回归风险 | 引入 Vitest | v0.4 |
| 错误模型 | 纯文本 | 不利消费 | 结构化封装 | v0.4 |
| 复用 | 参数校验重复 | 冗余 | 提炼 util | v0.5 |

## 风险清单
| 风险 | 场景 | 影响 | 缓解 |
| ---- | ---- | ---- | ---- |
| 上游 API 不稳定 | Pixabay 间歇 5xx | 失败率上升 | 超时+重试+缓存 |
| 滥用/高频 | 大量高并发请求 | 触发上游限流 | 本地节流 + 缓存 |
| 结构化输出变更 | 字段演进 | 破坏向后兼容 | 版本化 `schemaVersion` 字段 |
| 单人维护 | 认知集中 | 瓶颈 / Bus factor | 添加贡献指南与测试 |

## 需求拆分模板（示例：结构化结果）
| 子任务 | 说明 | 完成标准 |
| ---- | ---- | ---- |
| 数据模型定义 | 设计返回 JSON 字段集合 | `types.ts` 中导出接口 | 
| Handler 改造 | 在成功路径附加 JSON 内容 | 工具返回包含 `json` 内容块 | 
| 错误模型统一 | 新增错误封装函数 | 所有 catch 使用统一函数 | 
| 文档更新 | README 添加示例 | 示例可直接复制运行 |
| 测试 | 正常 / 空结果 / 错误 | 测试通过 |

## 不做列表（暂缓）
| 项目 | 原因 | 复审时间 |
| ---- | ---- | ---- |
| 服务端持久缓存/数据库 | 复杂度高，现阶段收益低 | v0.7 再评估 |
| 多云部署脚本 | 仅 CLI 运行即可 | 若出现 Server 模式需求再评估 |

## 附录：Roadmap 汇总视图
v0.4: 结构化 + 可观测 + 基础测试
v0.5: 分页/排序/重试 + 模块化 + 缓存试验
v0.6: 多源抽象调研 & 统一媒体模型
v0.7+: 统计与运营能力（可选）

（文件版本：2025-09-28）