MCP服务搭建实战指南

它解决什么问题

把分散在四处的产品数据变成 AI Agent 能直接调用的查询能力，是这一步真正难的地方。真实场景里，产品信息往往不在一个表里：一份 型号总表（10 个系列、289 条）、一份膜世界全部产品型号目录（K 系列手机壳、87 款）、一份按月导出的商品 Excel（6 个月销售数据），外加手工整理的 Top30 热销数据。字段口径、编号体系都不一致，Agent 如果靠自然语言去翻这些文件，既慢又不可靠。

这个技能记录的，就是把这些数据收敛成一个 MCP（Model Context Protocol）服务、让模型用统一接口查询的完整过程。

它是怎么工作的

核心做法是「合并 → 封装 → 发布」三段：

1. 数据合并：以产品型号总表为基础主键，把 K 系列型号和销售数据补进去，最终输出一份 JSON 数据文件，而不是继续维护多张表格。
2. 接口设计：在 Python HTTP 服务上暴露 4 个查询接口，全部支持 GET 请求、返回 JSON：

- product_query：按 q=型号名 匹配产品列表
- top_selling：按 limit=数量 返回热销排行
- compatible_models：按 model=型号 查兼容产品
- stock_status：按 product_id=编号 查库存状态

1. 服务化与发布：实现层是 Python HTTP 服务 + JSON 数据文件，约 200 行参考代码（mcp_server.py）。对外交付时按技能规范整理成 SKILL.md，frontmatter 中必须包含 slug、displayName、version，其中版本号要符合 SemVer 格式（写成 1.0.0，不能只写 1.0）。发布前用 --dry-run 验证，再带 --changelog 正式提交。

适用边界与注意点

• 数据规模：演示基于 535 个 SKU，属于轻量单机方案，没有做索引、缓存或数据库依赖。数据量上万后，product_query 的模糊匹配和直接读 JSON 的方式需要重新设计。
• 只读查询：4 个接口全部是查询语义，没有写入、下单、改库存等写操作，也不含鉴权。放到生产环境必须自行补齐认证与并发控制。
• 路径是环境相关的：资料里给出的 ~/Desktop/学习池/...、~/.agents/skills/... 等参考路径来自作者本机，迁移到自己项目时需要替换成实际目录。
• 数据质量取决于上游：合并逻辑依赖型号总表的准确性，如果源表本身存在重复型号或命名不统一，合并结果会继承这些问题。
• 规范细节：version 必须是三段式 SemVer，漏写小版本号会被校验拦下；发布前务必先跑 --dry-run。

适合作为「已有结构化产品数据、想给 Agent 加一层查询接口」时的参考实现，而不是一个开箱即用的成品服务。