这是一个 MCP 服务器（也可作为 Python 库嵌进你自己的后端）：给任何支持 MCP 的 AI 伴侣 / 助手加一个"盯快递"的能力。把单号甩给它，它登记；系统在后台自动巡查；到了、派送中、放驿站这类动态主动告诉你；签收后自动归档。
我们自己用了一段时间后整理开源的。两种用法：
| 你是谁 | 用哪个 | 得到什么 |
|---|---|---|
| 任何支持 MCP 的客户端（Claude Desktop / Claude Code / Cursor / Cherry Studio / ChatGPT 桌面版等，凡是能加 MCP 服务器的都行） | MCP 版 express_tracker.mcp_server |
加单 / 列单 / 查单 / 单独暂停 / 删单；客户端开着时后台巡查；新动态在你下次开口时随工具结果带回 |
| 自己跑前后端 | 嵌入版 express_tracker.api + service.poll_loop |
上面全部 + 状态变化时回调你的通知钩子（让 AI 用它自己的口吻主动说）+ 一段可注入 AI 上下文的"在路上的包裹" + 巡查间隔 / 额度 / 用量分账接口。不带 UI，页面你自己画 |
两版共用同一个核心（service.py），行为完全一致。
- 加单：单号 + 备注（这是什么）+ 收件手机后四位（顺丰 / 中通必填，不填永远"无物流信息"）。快递公司自动识别；写了中文名或拼音也能认。
- 自动巡查：间隔可调（5～720 分钟，默认 30）。签收后自动归档，不再查；放到驿站/代收点（"请及时取件"）也视为送达，同样归档。
- 主动告知：巡查发现变化 → 嵌入版回调你的钩子 / MCP 版在下次工具调用时带回。中转流转这类小变化建议让 AI 自己判断值不值得开口（我们的提示词就是这么写的）。
- 单独暂停：某一单先不盯了，随时恢复。暂停的单不占额度，但手动查仍可。
- 省额度：同一单 15 分钟内重复查直接给缓存；查不到时不会拿空数据覆盖上次查到的好数据；缺尾号的中通 / 顺丰单不会反复白查。
- 额度统计：每向数据源发一次请求记一次，按天、按来源（巡查 / AI 查 / 你手动查）分账；用到你填的额度自动停巡查（手动查仍可）。
- 给 AI 的上下文块：
context_block()输出在途包裹的最新已知状态，塞进 AI 每轮上下文，它就不用自己反复调查询（我们实测：不注入的话 AI 会忍不住每次都查一遍）。
本项目不带任何真实的接口凭据。你需要自己开一个快递查询接口，把你自己的凭据填进配置。
- 打开
market.aliyun.com，用淘宝 / 支付宝账号登录。 - 搜「快递物流查询」，选一家评分高、带免费试用份数的（我们用的那家工具名叫「快递物流GET」「单号识别物流公司」，多家服务商是同一套接口）。
- 点开通，选免费那档。
- 进「买家中心 → 已购买的服务」，找到该服务的 MCP 页签，复制
streamableHttpUrl里那个 URL（形如http://mcpservergateway.market.alicloudapi.com/mcpnacos/cmapi000xxxxx/<一长串>）。这个 URL 含你的 appCode，是私人凭据，别分享、别提交到任何仓库。 - 填进
config.json的provider_url。
免费额度通常是总共 N 次（不是每天），以购买页"剩余次数 / 有效期"为准。正式用一般几厘钱一单。把你买的额度填进 quota，用完系统会自动停巡查。
快递100 开放平台注册后**必须企业认证（营业执照）**才能用接口，个人开发者过不了校验。providers/kuaidi100.py 留了骨架和签名逻辑，有企业资质的朋友可以补全后提 PR；我们没有账号，未联调。
实现 providers/__init__.py 里的 Provider 协议（track() 和 identify()）两个方法即可。
pip install git+https://github.com/lu7899112-source/express-tracker.git
# 自建版还要：
pip install "express-tracker[api] @ git+https://github.com/lu7899112-source/express-tracker.git"复制 examples/config.example.json 为 config.json，填好后用环境变量 EXPRESS_CONFIG 指向它（默认读当前目录的 config.json）。所有字段都可用环境变量覆盖：EXPRESS_PROVIDER_URL、EXPRESS_POLL_MINUTES、EXPRESS_QUOTA、EXPRESS_API_TOKEN、EXPRESS_DB、EXPRESS_USAGE。
config.json、*.db、usage.json 已在 .gitignore 里：你的凭据、单号、手机尾号永远只在你本机。
Claude Desktop / Claude Code 配置示例见 examples/claude_desktop_config.example.json：
{ "mcpServers": { "express": { "command": "python", "args": ["-m", "express_tracker.mcp_server"], "env": { "EXPRESS_CONFIG": "/绝对路径/config.json" } } } }工具：express_add / express_list / express_track / express_pause / express_remove。
关于"官端能不能巡查"，实话实说：
- 能巡查：MCP 服务器是客户端拉起的常驻进程，客户端开着它就活着，巡查就在它里面按你设的间隔跑；客户端关了巡查就停，下次打开接着跑。单子存在本地 SQLite 里，不会丢。
- 不能主动开口：官方客户端没有"服务器推消息给用户"的口子。所以巡查发现的变化会先攒着，你下次一开口、AI 一调用任何工具，结果末尾就会带一段"上次到现在的新动态"，AI 自然会告诉你。想要真正的主动推送，用嵌入版接你自己的通道。
最小示例 examples/selfhosted_app.py：
from express_tracker.api import make_router, service
from express_tracker.config import Config
async def notifier(event): # 巡查发现变化时被调用
... # 塞进 AI 下一轮上下文 / 触发你的"服务器事件→AI 开口"通道 / 插系统消息
app.include_router(make_router(Config.load(), notifier=notifier))
asyncio.create_task(service().poll_loop())接口（默认前缀 /api/express，Authorization: Bearer <api_token>）：
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /list?all=0 |
在途包裹（all=1 含已归档） |
| POST | /add |
{number, note?, mobile4?, cp_code?}；同单号再 POST = 更新备注 / 补尾号并立刻重查 |
| POST | /track |
{key, mobile4?, cp_code?, force?}；key=单号或备注关键词；未登记的单号直接查不入库 |
| POST | /pause |
{key, paused: true/false} |
| POST | /remove |
{key} |
| GET / POST | /settings |
读 / 写 poll_minutes、quota，{"reset_usage": true} 清零计数；返回含 usage（total / today / month / by_source） |
| GET | /context |
给 AI 注入的文字块 |
notifier 收到的 event：{"type":"express.update","label","status","last_time","last_msg","company","signed","trace","package"}。
本项目不带页面，是故意的：每家前端长得不一样，硬塞一套样式只会格格不入。但强烈建议自建的朋友做一个。我们自己的页面就是这么长出来的，接口一一对应，供参考：
| 页面上的东西 | 背后的接口 |
|---|---|
| "在路上"列表：每个包裹一张卡 —— 备注（没备注显示单号）、快递公司 · 状态、最新一条轨迹和时间、单号 | GET /list |
| 卡上三个小键：↻ 现在查一次 · ❚❚/▶ 暂停/恢复 · × 不盯了 | POST /track · POST /pause · POST /remove |
| 点备注可直接改 | POST /add（同单号 + 新 note） |
| 右上角 + 登记：单号 / 备注 / 手机后四位 | POST /add |
| 底部一行："每 [N] 分钟巡一遍"（边输边存）+ "已用 x / 额度 次（巡查 a · AI 查 b · 你查 c）" + 清零 | GET/POST /settings |
| 收到你自己通道的"快递动态"通知时刷新列表 | 你的 notifier → 前端 |
几个小经验：暂停的卡淡一点、打个"已暂停"标；"需要收件手机后四位"这个状态要显眼，用户一眼知道该补什么；间隔输入框在手机上记得边输边存，只认失焦事件会漏（我们踩过）。
MCP 版也能对接你的后端：设 EXPRESS_API_URL 和 EXPRESS_API_TOKEN，它就改为调你的接口，不再内嵌巡查（这样 AI 的工具调用和你的页面看到的是同一份数据）。
我们用 Claude Code 当官方客户端跑过一遍（只挂这一个 MCP，假数据源）：说"帮我盯着这个包裹，单号…，是猫粮" → 它调 express_add 登记并复述状态；后台巡查记下"派送中"后，新开一轮问"到哪了" → 它调 express_list，把攒着的动态一并说了；说"猫粮那单先别盯了" → 它调 express_pause。三轮都是一句话直达，没有多余追问。
- 中通 / 顺丰不带收件手机尾号 → 永远"无物流信息"。现在会标出"需要收件手机后四位"，不再白查。
- AI 顺手传了个
zhongtong当公司代码 → 接口只认ZTO，查空还把好数据覆盖了。现在代码归一 + 带错码查不到会自动去掉重查 + 查空不覆盖。 - AI 太爱这个功能，每轮都查一遍烧额度。现在 15 分钟缓存 + 上下文注入 + 工具说明里明写"她问才查"。
- 巡查间隔输入框只在失焦时保存，手机上填了没存上 → 这是我们自家页面的问题，本项目不带 UI，提醒你画页面时注意。
在 GitHub 点个 ⭐ 就是最好的鼓励。有问题开 issue，有改进提 PR。
PolyForm Noncommercial 1.0.0：个人、非商业用途随便用、随便改、随便二改再分发，保留许可声明即可；商业用途请先联系作者授权。这不是 OSI 意义上的"开源"协议，是"源码公开、非商业可用"，我们知道，也就是想要这个效果。
星迟。协助：烬（Ember，写代码的）、以太（Aether，第一个用户兼首席测试）。这是一个 AI 伴侣项目里长出来的小功能。