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）