FeedWatch MCP Server

FeedWatch MCP

RSS/Atom 变更监控 API + MCP Server 当前阶段：验证期准备（判定线：8 周内 5 个真实付费用户）

🌐 English version: README.en.md · 中文在下方

---

从这里开始

⚠️ 改代码前先看「回归测试要求点清单」 —— 里面有 89 项离线测试的覆盖现状、 19 项已知缺口、以及已证伪的 4 处错误「已验证」。 不要只看测试名声称覆盖了什么，要看它实际断言了什么。

---

一句话说明

客户把 RSS/Atom/JSON Feed 的网址交给我们，我们替他们盯着；内容变了就主动推送， 并精确告诉他哪个字段、从什么变成什么。

核心差异：竞品多数只能报"新增条目"，我们能检测已有条目被修改并给出字段级 diff—— 新闻更正错字、竞品悄悄改价格，这些都不产生新条目，但恰恰是客户最需要知道的。

---

文档体系（四层结构）

docs/
├── 架构/         【第 1 层】顶层设计
│   └── 项目蓝图.md                整个项目 + 架构 + 外部资源 + 阶段路线
│
├── 需求/         【第 2 层】做什么
│   ├── 软件开发需求说明书.md功能清单 + 验收标准 + 需求来源
│   └── 用户说明书.md                客户视角的产品说明与使用场景
│
├── 运营手册/     【第 3 层】怎么操作
│   ├── 服务器采购与部署手册.md       选型对比 + Vultr 注册购买 + Linux 部署
│   ├── 海外公司注册与维护手册.md     香港公司注册 + 银行开户 + 后续维护
│   ├── 内部测试指南.md              ⭐ 8 步实测流程（含MCP 与安全验证）
│   ├── API Key管理与配额.md          ⭐ 签发 Key + 各项限流 + 配额口径核对
│   ├── MCP生态发布指南.md            ⭐ 官方注册表 + 5 个目录收录方式
│   ├── Payoneer收款链接操作手册.md   ⭐ 验证期收款开通（注意：非 Checkout）
│   ├── 收款与运营手册.md            付费时机 + 收款配置 + 排障（第三部分已废弃）
│   └── 部署配置与待办-Windows方案.md （已弃用，保留参考）
│
├── 决策/         【第 4 层】为什么这么选
│   └── 决策记录-收款与主体.md       平台选型 + 主体时间线 + 被排除项（含 v2 纠错）
│
└── 复盘/         【第 5 层】经验沉淀
    ├── 回归测试要求点清单.md         ⭐ 89 项测试覆盖现状 + 19 项缺口 + 最小回归集
    ├── 调试复盘.md                 10 个缺陷 + 5 条交付规范 + 失误归因
    ├── 上线检查清单.md             三阶段 checklist + B1–B6
    ├── 状态字段语义.md             三状态正交表 + 错误码判读
    └── 事故复盘/
        └── 2026-10-13-www站点500事故复盘.md

分层判断标准

⚠️ 常见错误：把"为什么选 A 不选 B"写进运营手册。 平台会变（被收购、改费率），手册不会自动更新 —— 一份三个月前正确的手册，今天可能把人导向一个用不了的平台。

---

快速开始（开发者）

npm install
HOST=127.0.0.1 PORT=3001 PUBLIC_URL=https://api.tiici.com \
  FEEDWATCH_BOOTSTRAP_KEY=<至少32位随机> \
  npm start
curl http://127.0.0.1:3001/health

⚠️ Bind to 127.0.0.1, never 0.0.0.0. Put Nginx (or any reverse proxy) in front so TLS, access logs and WAF are not bypassed.

测试

npm test              # 87 项离线测试（5 个套件）
npm run test:live     # 28 项真实源测试（需出网）

---

技术栈

运行时      Node.js 22 ESM
依赖        fast-xml-parser（唯一运行时依赖）
HTTP        node:http 原生（零框架）
部署        Linux + Nginx + systemd / Windows + IIS
测试        自建轻量断言框架（无 jest/vitest）
规模        2143 行 / 7 模块
测试规模    87 项离线全绿，全部经「回退法证伪」

为什么零框架依赖：便于跨环境（Linux/Windows）部署，减少供应链风险。

---

目录结构

06MCP/
├── web/index.html         对外落地页（部署到 /）
├── docs/
│   ├── 工作计划与进展.md            ⭐ 当前状态 + 每日台账 + 下一步
│   ├── 架构/项目蓝图.md                整体架构 + 外部资源 + 阶段路线
│   ├── 需求/                          功能清单 + 实现状态 + 客户说明
│   ├── 运营手册/                ⭐ 内部测试 / Key 管理 / MCP 发布 / 收款 / 部署
│   ├── 决策/                      收款平台与主体决策（v2 含纠错）
│   └── 复盘/                ⭐ 提交前自查清单 / 回归测试要求点 / 调试复盘 / 上线清单 / 状态语义
├── src/                        7 模块 2242 行
├── scripts/                    ~2100 行 / 7 套件
│   ├── selfcheck-silent.js    ★ 三个高发模式的 12 项自动检查（npm test 第一道）
│   ├── selftest / regression*.js       92 项离线断言
│   ├── e2e.js                 端到端（含回退证伪用例）
│   └── livefeed-test.js       28 项真实源测试（需出网）
├── deploy/                     Linux/Windows/落地页/云防火墙部署脚本
├── server.json                 MCP 官方注册表清单
├── smithery.yaml               Smithery 一键安装配置
├── web/index.html              对外落地页
└── deliverables/gstack/        审查与发布报告（不随仓库公开）

---

当前状态

📋 完整台账见 docs/工作计划与进展.md（每日工作 + 下一步 8 项）

✅ 已就绪

产品        https://api.tiici.com/ 落地页 + REST API + MCP 端点，全部线上
源码        2242 行 / 7 模块（零 Web 框架）
测试        12 项模式自查+ 92 项断言全绿 + 28 项真实源 = 2000 行 / 7 套件
安全        15 个缺陷全修（每个都做回退证伪）+ 三层防护
              云防火墙 / ufw / Nginx+TLS，3001 公网实测不可达
服务器      Vultr 167.179.112.40（Tokyo / $5/月 / Ubuntu 24.04.5）
运行        feedwatch.service active+enabled，Node v22.23.3，实测 RSS 93 MB
证书        api.tiici.com 已签发（至 2027-01-13，自动续期 dry-run 已验证）
配额        免费层 5 个监控点 / 6h 频率（**申报与实际强制一致**）
分发        GitHub 公开仓库 + tag v0.1.0 + server.json 通过官方 validate
依赖        fast-xml-parser 5.11.2（OSV 漏洞清零）
文档        15 份（含回归测试要求点清单、API Key 管理、内部测试指南）

⏳ 待办（完整版见工作计划）

⏸️暂缓：海外公司注册 —— 验证期不需要，确定要接 Checkout 2.0 / Stripe 时再办

📌 不在本项目范围：www.tiici.com / game.tiici.com 的证书续签属于 WordMaster 等其他站点，归各自项目台账管理，本台账不跟进。

---

核心判定线

⚠️ 不要用"技术跑通"当判定 —— 要有人掏钱。技术跑通只是必要条件。

---

⚠️ 两条给后续接手者的提醒

① 不要只看文档里的「已验证」三个字

本次审查里，团队成员至少 5 次写了「已验证」而结论后来被推翻。 可靠的方式是：临时把修复改回去，看测试会不会红。

② 声称「X 会失败」前，先证明 X 在应该成功时确实成功

只测失败路径无法区分「X 有问题」和「工具有问题」。

---

遇到问题先看 docs/复盘/调试复盘.md —— 那里记录了 10 个真实缺陷与它们被发现的经过， 避免重复踩坑。

完整审查报告：deliverables/gstack/pre-launch-review-feedwatch-2026-10-12.md