Pixabay MCP Server

# 代码审查报告 ## 综述 项目 `pixabay-mcp` 提供一个基于 Model Context Protocol (MCP) 的 Pixabay 图片与视频检索服务器，核心实现集中在单文件 `src/index.ts`（~560 行）。结构直观： 1. 常量与类型定义（API URL、枚举、接口） 2. 参数类型守卫 + 运行时校验函数（图片/视频） 3. 统一错误日志函数 `logPixabayError` 4. MCP Server 实例化与工具列表暴露 5. `CallTool` 请求处理逻辑（图片 / 视频分支） 6. 启动入口 `main()` 与 SIGINT 优雅退出 当前版本：代码内 server version = `0.3.0`，`package.json` 亦为 `0.3.0`，已保持一致（较旧审查项已修正）。 ## 积极点 - 单文件集中，便于初学者理解 MCP 最小可行实现。 - 已加入运行时严格枚举/范围参数校验（`assertValidImageSearchParams`、`assertValidVideoSearchParams`）。 - 错误日志函数已脱敏处理，不再输出请求配置与敏感参数。 - 对图片与视频工具分别定义 JSON Schema，便于客户端自动生成表单。 - 使用 TypeScript 接口对 Pixabay 响应进行基本建模，提升可读性。 ## 需要关注的问题与改进建议 | 优先级 | 类别 | 描述 | 影响 | 建议 | | ------ | ---- | ---- | ---- | ---- | | P0 | 健壮性 | 未设置 `axios` 超时，潜在悬挂请求 | 线程/连接占用，用户等待时间不可控 | 统一设置 `timeout` (例如 8~12s) 并在超时报可恢复提示 | | P0 | 错误语义 | 图片/视频错误信息文本仅返回一段字符串，缺少结构化字段 | 上层调用难以区分类型/状态码 | 返回 `{ code, status, hint }` 辅助程序化处理 | | P1 | 可扩展性 | 单文件体积持续增长（>500 行） | 维护/测试困难 | 拆分为 `validation.ts`、`types.ts`、`handlers/`、`server.ts` | | P1 | 可测试性 | 缺少任何自动化测试 | 变更存在回归风险 | 引入 Vitest/Jest，添加 smoke / 参数校验 / 错误路径用例 | | P1 | 性能/弹性 | 无重试策略（偶发 5xx / ENETRESET） | 临时网络抖动导致整体失败 | 视需要增加有限幂次重试（如 2 次，指数退避） | | P2 | 可观测性 | 无简单统计/调用计数 | 难以了解使用模式 | 增加可选 `--verbose` 或统计计数器（仅 stderr 输出） | | P2 | DX | README 中暂无结构化 JSON 输出示例 | 用户可能不清楚如何解析返回文本 | 提供示例与 Roadmap 对齐 | | P3 | i18n | 代码中混合中英文消息 | 信息风格不统一 | 统一语言策略（英文主；或资源化） | ## 代码质量细节分析 ### 结构 目前聚合度高但关注点分离不充分。随着功能增加（排序、分页、更多过滤器），单文件会成为修改热点。拆分建议： - `src/constants.ts`：枚举、范围、URL - `src/types.ts`：Pixabay 接口定义 - `src/validation.ts`：类型守卫 + assert 函数 - `src/handlers/images.ts` / `videos.ts`：具体调用与格式化 - `src/logger.ts`：日志策略 ### 错误处理 优点：对 Axios 错误分支与通用错误分支区分。 缺点：返回给 MCP 客户端的内容未结构化；所有业务错误都落为纯文本。建议： ``` return { content: [{ type: 'text', text: message }], metadata: { status, source: 'pixabay', kind: 'upstream' }, isError: true }; ``` ### 安全 - 已避免直接输出 API Key，风险较低。 - 可以添加：启动时如果 `PIXABAY_API_KEY` 缺失，提示最小化（不要引导用户粘贴敏感 Key 到日志）。 ### 依赖 仅使用 `axios` + `@modelcontextprotocol/sdk`，无明显冗余。若后续仅做简单 GET，也可用原生 `fetch`（Node 18+）减轻依赖体积。 ### 性能 当前调用为 I/O 受限，无批量/循环处理，瓶颈主要在外部 API。潜在优化： 1. 默认 `per_page` 可保持 20；若用户请求 >100，可提醒分页策略。 2. 未来若支持多源聚合，需引入并发控制（p-limit）。 ### 可测试性建议 推荐最小测试集： 1. 参数校验成功/失败（边界：per_page=2,201）。 2. 缺失 `PIXABAY_API_KEY` 时抛出期望错误。 3. 模拟 Axios 200 返回结构格式化正确。 4. 模拟 Axios 超时触发错误路径。 ### 日志策略改进提案 | 级别 | 触发 | 示例 | | ---- | ---- | ---- | | info | 启动/关闭 | `Server started version 0.3.0` | | warn | 非致命参数修正（未来） | `per_page clamped 250 -> 200` | | error | 上游失败 | 已存在（脱敏） | ### 未来可演进方向（与 backlog 对应） - 结构化 JSON 输出：同时返回文本与 machine-readable 列表。 - 排序、分页、时长区间（已部分实现）。 - 多语言输出策略与文案抽离。 - 可选轻量缓存（基于 query + 参数 Hash）。 ## 改进实施优先级（行动版） 1. (P0) 统一 axios 超时 + 结构化错误返回 2. (P1) 拆分文件结构，引入测试框架 3. (P1) 限定重试（可配置），避免瞬时失败 4. (P2) 统计与诊断信息（调用计数） 5. (P3) 国际化与文案统一 ## 风险与缓解 | 风险 | 说明 | 缓解 | | ---- | ---- | ---- | | 单文件耦合 | 修改冲突率高 | 尽早模块化 | | 缺测试 | 回归不可见 | 添加最小单测 | | 上游不稳定 | 高频 5xx/超时影响体验 | 超时+重试 | | 滥用 API | 无速率控制 | 将来加入节流/缓存 | ## 结论 代码基础简洁，适合作为教学/入门示例。为支持持续扩展，应尽快引入：结构化错误 / 模块拆分 / 自动化测试 / 超时与重试。上述改进工作量中低，但能显著提升可维护性与可靠性。 （本报告更新于：2025-09-28）