upkeep-mcp

upkeep-mcp

用于 MCP 的服务，负责网站持续维护中的定期检查： 域名、SSL 证书、运行时间、技术 SEO 和无障碍性——所有信息均来自 公开可用的数据。

适用于长期负责维护多个客户网站的人，而不只是单个域名。目标是快速回答 一个问题：本周有哪些事项需要关注？

状态

仍处于早期开发阶段，按阶段公开开发。所有无需浏览器的功能都已实现，并且目前已可使用。

工具	用途	状态
domain_check	注册到期时间、注册商、名称服务器一致性、DNS 记录、DNSSEC	可用
ssl_check	证书到期时间、颁发者、证书链有效性、SAN 覆盖范围、TLS 版本	可用
uptime_check	HTTP 状态、响应时间、重定向链、HTTPS 升级、安全标头	可用
health	服务名称、版本、Node.js 版本、运行时间	可用
seo_audit	标题、元信息、标题层级、规范链接、robots.txt、站点地图、失效链接	可用
site_crawl	整个网站中的重复标题、失效链接和意外的 noindex	可用
portfolio_report	汇总多个网站的上述检查结果，并按紧急程度排序	可用
accessibility_audit	通过真实浏览器中的 axe-core 检查 WCAG 违规项	可用

它还提供 portfolio://sites 资源（网站列表，客户端无需调用工具即可读取）和 quarterly_report 提示词（将网站组合的检查结果整理成客户实际会阅读的报告）。

已发布到 npm，因此只需一条命令即可安装——参见 安装。此外还在运行一个公共实例，方便不想运行任何程序、而希望直接把 URL 提供给客户的人——参见 托管实例。

效果展示

> Is example.com about to expire?

example.com expires 2027-08-13 (346 days).
Registrar: RESERVED-Internet Assigned Numbers Authority.
Nameservers: elliott.ns.cloudflare.com, hera.ns.cloudflare.com.
Resolves: apex yes, www yes. DNSSEC: delegation signed.

> Check the certificate on expired.badssl.com

expired.badssl.com:443 certificate expires 2015-04-12 (-4159 days).
Issued by COMODO RSA Domain Validation Secure Server CA.
Chain does not verify (CERT_HAS_EXPIRED). Negotiated TLSv1.2.
Host matched via *.badssl.com.
Revocation not established: http://ocsp.comodoca.com could not answer: the
responder is not authorised to answer for this certificate.

Needs attention:
- [critical] The certificate expired 4159 days ago.
- [critical] The certificate chain does not verify: CERT_HAS_EXPIRED.

> Check the certificate on revoked.grc.com

revoked.grc.com:443 certificate expires 2026-10-18 (42 days).
Issued by Certera RSA DV SSL CA 2.
Chain verifies. Negotiated TLSv1.2.
Host matched via revoked.grc.com.
Revoked on 2025-09-18.

Needs attention:
- [critical] The certificate was revoked on 2025-09-18; browsers that check
  revocation will refuse the site.

注意第二个示例的结果：证书链验证通过。Node 不会自行查询证书吊销状态，因此该证书能够完成握手，并被报告为可信。只有向其颁发者查询，才能发现问题。

每个工具还会在文本之外返回结构化数据，因此可以对结果进行排序、筛选并用于生成报告。每个工具的完整输入和输出见 examples/，整个网站组合会话——包括每周分流、深入检查，以及与上次运行结果对比时会和不会得出的结论——见 examples/conversation.md。

工具

domain_check

输入：domain — 裸域名、完整 URL 或国际化名称。子域名会简化为其可注册域名，因为注册信息归属于该域名。

返回到期日期和剩余天数、注册商及其 IANA ID、注册局状态、A/AAAA/NS/MX/TXT/CAA 记录、顶点域名和 www 是否能解析、委派是否已通过 DNSSEC 签名，以及该域名的 SPF 和 DMARC 记录对哪些人可以使用它发送邮件作何规定。

邮件身份验证信息从域名自身的 DNS 中读取——顶点域名处的 SPF 记录，以及 _dmarc 处的 DMARC 记录。记录不存在时会作为信息报告，因为这是长期改进事项，而不是本周才出现的问题。记录存在但配置错误时会作为警告，因为它现在就会失效：两条 SPF 记录会导致接收方完全跳过 SPF，而 +all 则授权整个互联网使用该域名发送邮件。

此处有意不报告 DKIM。DKIM 密钥位于 <selector>._domainkey，而 selector 无法被发现——只能猜测，每猜一次就要进行一次 DNS 查询。这属于子域名枚举，本项目不会这样做，因此无法区分没有 DKIM 的域名和未猜中 selector 的域名，不会把后者报告成前者。

随后会直接通过 TCP 端口 53 向域名自身的每台名称服务器查询该区域，并关闭递归。这是递归解析器无法回答的唯一问题：递归解析器会返回某台服务器告诉它的内容，却不会说明是哪台服务器返回的。这样可以发现迁移后仍留在委派中的服务器——它会回复 REFUSED，或者自身的主机名已无法解析，导致每个查询落到它那里的解析器都变慢或失败；也可以发现持有不同区域版本的名称服务器，这正是“我这里能用，但我同事那里不行”这类故障的成因。

故障与尚未确认的情况会分别评级。解析器首先通过 UDP 查询，而此服务只能使用 TCP，因此拒绝 TCP 的名称服务器并非故障：sapo.pt 的四台服务器都拒绝 TCP，但该域名完全可以正常解析。序列号不同也仅标记为信息——github.com 使用两家彼此不传送区域数据的服务商，因此四台名称服务器报告 1656468023，另四台报告 1，但一切正常。主机名无法解析，或响应中不包含该区域的权威信息，都会影响所有人，因此会作为警告。传入 checkNameservers: false 可跳过整个检查——portfolio_report 就是这样做的，因为组合报告需要对每个站点执行此检查，而无法开放端口 53 的部署会导致所有站点都被评为尚未确认。 docs/adr/0020 记录了为何要手动处理 DNS，以及有意不检查哪些内容。

ssl_check

输入：domain，可选的 port（默认为 443）。

返回证书过期时间和剩余天数、颁发者、证书链是否通过验证，以及未通过时的原因、证书覆盖的主机名及其对应的 SAN 条目、协商出的 TLS 版本和密码套件，以及证书是否已被吊销。对于已过期、自签名和不受信任的证书，系统会检查并报告，而不会拒绝——这些才是值得找出的证书。

通过 OCSP 检查吊销状态。优先使用服务器在握手时附带的响应，因为这完全不需要额外请求；如果没有，则直接向证书中指定的响应者查询。只有在响应签名通过颁发机构的验证，且确认其中的 CertID 对应实际提供的证书后，才会采信该响应——否则，服务器可以在提供已吊销证书的同时，为另一张证书提供有效响应，轻易伪造出正常结果。

许多正常的证书根本无法检查：自 2025 年起，最大的两家颁发机构 Let's Encrypt 和 Google Trust Services 不再提供 OCSP 响应者，而是通过 CRL 发布吊销信息。这种情况会作为 unavailableReason 报告，且不会产生发现项，因为这是证书颁发机构的决定，网站所有者对此无能为力。向响应者发出查询但未得到答复则不同，会产生一条 unknown。

uptime_check

输入：url——完整 URL 或裸域名；裸域名会通过 HTTPS 尝试访问。

返回状态码、响应时间、重定向链中的每一跳、是否将纯 HTTP 升级为 HTTPS、HSTS 策略，以及值得报告的安全标头。

seo_audit

输入：url——要审计的页面，以及可选的 checkLinks（默认值为 true）和 maxLinks（默认值为 25）。

返回标题和元描述及其长度、标题结构、canonical、lang、viewport、Open Graph、hreflang 替代项、缺少 alt 属性的图片、robots.txt 和站点地图的状态，以及失效的内部链接。

读取压缩的 gzip 站点地图前会先解压。是否为 gzip 格式取决于前两个字节，而非文件名或内容类型，因为许多名为 .xml.gz 的文件并非 gzip 格式，许多实际为 gzip 格式的文件却被标记为 text/xml。

随后会按照协议规则检查站点地图，因为文件能返回 200 且可解析，并不代表它就能正常工作：缺少 sitemaps.org 命名空间的根元素会被整体丢弃；其他主机上的条目会被丢弃；一个未转义的 & 会使文档成为格式错误的 XML，并导致其后所有条目都无法读取。每条违反的规则只报告一次，并附上违反规则的条目数量和一个示例，因此在五万个 URL 中重复出现的错误会被归纳为一项待修复问题。只会损失提示信息的规则——例如 <lastmod> 不是 W3C Datetime 格式，或 <changefreq> 不属于七个允许值之一——会标记为 info；会导致条目或文件被丢弃的规则则标记为 warning。

读取其他任何内容之前，先读取 robots.txt 并遵守其规则——无论是页面本身还是每个内部链接都一样。若此爬虫无权读取某个页面，会将其报告为无权访问，并且绝不会获取该页面；根据 RFC 9309 的要求，无法读取的 robots.txt 将被视为禁止访问所有内容。

> Audit the homepage of example.com

https://example.com/ answered 200. Title: "Example Domain".
1 h1, 0 images without alt, 0 internal links (0 checked, 0 broken).
Sitemap: the sitemap URL answered 404.

Needs attention:
- [warning] The page has no meta description, so search engines will write their own summary of it.
- [info] The page declares no canonical URL, which is how duplicate addresses for the same page get separated.
- [info] The page has no og:title or no og:image, so it will share poorly on social networks and in messaging apps.
- [info] There is no sitemap at https://example.com/sitemap.xml: the sitemap URL answered 404.
- [info] The site publishes no robots.txt. Nothing is blocked, but the sitemap cannot be declared there either.

site_crawl

输入：url——起始页面；以及可选的 maxPages（默认值为 25，最多 100）和 maxDepth（默认值为 3）。

从该页面开始，以广度优先方式遍历网站，并报告单个页面无法告诉你的信息：哪些页面标题相同，因此会争夺同一个搜索结果；哪些页面的元描述相同；哪些内部链接已失效，以及关键的，哪个页面链接到了它们；重建后哪些页面仍然要求不要被索引；以及整个网站有多少内容可以访问。

爬取范围仅限于起始页面所在的源站——https://example.com 和 https://www.example.com 是不同的源站，如果爬取时在两者之间跳转，就会把一个网站的页面报告为另一个网站的重复页面。重定向到站外的链接会计入统计，但不会继续访问：已读取的 robots.txt 仅对当前源站有效，不代表其他任何网站。

爬取受三项限制：页面数、深度和两分钟的截止时间。报告会说明是哪项限制结束了爬取，以及发现了多少个 URL、其中多少个尚未访问，因为一份不说明自己只查看了网站四分之一内容的报告，还不如没有报告。请求任何 URL 前，都会先读取并遵守 robots.txt；若无法读取，则根据 RFC 9309，直接拒绝爬取。

它有意不属于 portfolio_report。跨整个作品集爬取每个网站 25 个页面，成本规模截然不同；而 docs/adr/0010 所预见的 docs/adr/0021 记录了原因：它应该是独立工具，而不是 seo_audit 上的 depth 参数。

> Crawl example.com and tell me what needs fixing

Crawled 25 pages of https://example.com, 3 levels deep.
2 broken internal links, 1 title used more than once.
Stopped at the page budget; 11 URLs were not visited.

Needs attention:
- [warning] 2 internal links are broken: https://example.com/old-pricing (it answered 404) linked from https://example.com/, https://example.com/team/ana (it answered 404) linked from https://example.com/team.
- [warning] 1 title is used by more than one page, so those pages compete with each other in search results; the widest is "Services" on 4 pages.
- [info] 6 of 25 pages have no meta description, so search engines will write their own summary of them.
- [info] The crawl stopped at the page budget with 11 URLs found and not visited, so everything here describes the part of the site that was looked at.

portfolio_report

输入：内联的 sites，或 file（默认为 sites.json），以及可选的 checks 和 tags。

以有限并发对整个作品集运行所有检查，并返回一份报告，按优先处理事项排序：无法访问的站点、最早到期的项目，以及自上次运行以来出现回退的项目。无法检查的站点会成为一条发现，而不会导致整份报告失败。

> What needs attention across my sites this week?

3 sites checked: 0 critical, 2 warning, 0 unknown, 1 fine.

Needs action:
- [warning] Example Ltd: Plain HTTP does not redirect to HTTPS.
- [warning] Example Ltd: No Strict-Transport-Security header is sent.
- [warning] Example Net: Plain HTTP does not redirect to HTTPS.
- [warning] Example Net: No Strict-Transport-Security header is sent.

No change is reported: this server has not run a report on this portfolio before,
and the portfolio names no history file, so nothing survived the last restart.
History for this portfolio is kept in memory only. To compare across restarts,
add a "history" path to the portfolio file.

Nothing to do: Example Foundation.

跨重启进行比较。 默认情况下，上一次运行只保存在此服务进程中，不会存放到其他地方，因此每天重启的客户端只能获得跨度不超过一天的比较结果，完全无法生成季度环比报告。在作品集文件中添加一行：

{ "version": 1, "history": "upkeep-history.json", "sites": [...] }

这样，运行结果就会写入该文件，保存在作品集文件旁边。之后无论重启多少次，下一份报告都会与它进行比较，最长可追溯九十天。该文件会列出你的客户端，并标明哪些客户端已损坏，因此创建时只有你的账户可读取，且每次运行都会覆盖；如果不添加这一行，则不会写入任何内容。docs/adr/0018 记录了相关原因。

每个站点都可以设置 maxLinks，指定 seo 检查可以请求多少个内部链接；设为 0 则表示不检查。此设置决定一次运行的成本：对 20 个站点进行测量时，不启用 seo 约需 8 秒，启用后约需 40 秒，因为链接检查会逐个请求链接，并在同一主机上的请求之间间隔半秒。

作品集文件格式详见 sites.example.json。将其复制为 sites.json——该文件已列入 gitignore，因此真实的客户端列表不会被提交。file 路径会相对于客户端启动服务时所在的目录解析；如果该目录不属于你，请提供完整路径。

accessibility_audit

输入：url，以及可选的 standard（默认为 wcag2aa；也可使用 wcag2a、 wcag21aa、wcag22aa、best-practice）。

在无头浏览器中打开页面，并在页面上运行 axe-core。返回未通过的规则、每条规则未通过的元素数量、前几个元素的 CSS 选择器，以及 axe 无法自行判断的规则数量。

这是唯一需要浏览器的工具，而且是可选的：安装此项目时不会下载任何内容。如果需要，可以运行一次 npx playwright install chromium。如果没有安装，工具会说明这一点并列出该命令，其他检查则会照常进行。

自动化规则只能发现大约三分之一的无障碍问题。页面没有违规项，表示它通过了机器可检查的部分，但这并不等同于页面可用——因此会同时报告无法判断的规则数量。

安装

需要 Node.js 22 或更高版本。除此之外没有其他要求：安装时不会下载浏览器，除 accessibility_audit 外，所有检查都可在没有浏览器的情况下运行。

Claude Code

claude mcp add upkeep -- npx -y upkeep-mcp

Claude Desktop

将服务添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "upkeep": {
      "command": "npx",
      "args": ["-y", "upkeep-mcp"]
    }
  }
}

重启客户端，并让它运行 health 工具。该工具会返回服务版本、Node.js 版本，以及进程已运行的时长。

桌面客户端会在自行选择的目录中启动服务，通常是 /。这只会影响一件事：portfolio_report 和 portfolio://sites 资源会在该目录中查找 sites.json。可以内联传入 sites，也可以向 portfolio_report 提供完整路径——file: "/Users/you/sites.json"。

从源代码运行

用于开发或运行某个分支：

git clone https://github.com/tiagocalado86/upkeep-mcp.git
cd upkeep-mcp
npm install
npm run build
claude mcp add upkeep -- node /absolute/path/to/upkeep-mcp/dist/index.js

托管实例

如果无法或不想运行服务，可以使用一个公开实例：

https://upkeep-mcp-1080119881249.europe-west1.run.app/mcp

将任何接受远程服务 URL 的 MCP 客户端指向该实例——在 Claude 中，可将其添加为自定义连接器。在浏览器中打开此主机，会显示一个介绍它的简单页面。

**这是一个演示实例。**它没有身份验证、可用性承诺或支持，并且可能会在不通知的情况下关闭。运行此服务的受支持方式是 npx -y upkeep-mcp；如果这些检查对你的工作很重要，就应该使用这种方式。

这里的所有工具都可用，包括 accessibility_audit——镜像内置了浏览器，且该浏览器发出的每个请求都会遵循与服务其余部分相同的规则。无法自行运行服务的人，不应该比能够运行服务的人使用更弱的工具。

有一项确实不同，但这是公开运行的特性，而非妥协：它只连接公开地址，且仅限三个端口——443、用于检查纯 HTTP 是否升级的 80，以及域名自行发布的名称服务器所用的 53。因此，它拒绝检查你自己的网络上的任何内容，包括 localhost。如需检查这些内容，请使用 stdio 服务。

通过 HTTP 运行自己的实例

传输方式与托管实例使用的相同：

npm run build
npm run start:http -- --port 8080

HTTP 入口并不是加上套接字的 stdio 入口：发起请求的人可能不是启动进程的人，因此它会应用上述地址和端口规则，并通过按调用方设置的速率限制来接收流量。 docs/deploying.md 介绍了如何在 Google Cloud Run 上运行它，而 docs/adr/0012 解释了防护机制及其无法防范的情况。

安全与隐私

此服务从不索取、接受或存储凭据。它只读取任何人使用浏览器或 DNS 解析器都能读取的信息。

• 不需要任何服务的 API 密钥、令牌或密码，绝无例外。
• 不会进行侵入性操作：不会扫描端口、暴力枚举子域名或探测漏洞。它检查的是公开配置，并非攻击性工具。
• 抓取任何页面时都会遵守 robots.txt，并对每个主机进行速率限制，同时使用带有联系 URL 的可识别 User-Agent。
• 不会持久化敏感状态。缓存仅存于内存中，并设有 TTL。没有数据库。此服务唯一会写入的文件是作品集运行快照，且只有当作品集文件指定了该快照的 history 路径时才会写入。
• 唯一联系的第三方是掌握答案的服务：注册局自己的 RDAP 服务、IANA 的 RDAP 引导文件，以及 cloudflare-dns.com，用于询问 node:dns 无法查询的问题（DNSSEC 委派是否已签名）。SECURITY.md 列出了这些服务及其各自能获知的信息。

限制

坦诚说明，因为隐藏自身能力边界的工具，还不如少做一些的工具。

• 不会下载证书吊销列表。 吊销状态只通过 OCSP 检查。CRL 是一份包含某个颁发机构曾吊销过的所有序列号的文件，体积可达数 MB，为了回答关于一张证书的一个问题而下载它并不划算。因此，如果证书的颁发者没有发布响应器，工具会说明原因并将状态报告为“未检查”，而不是根据工具选择不读取的文件作出判断。自 2025 年起，Let's Encrypt 和 Google Trust Services 都属于这种情况，它们覆盖了网络上的很大一部分。参见 docs/adr/0017。
• OCSP 响应反映的是某个时间点，而不是持续订阅。 响应器会提前约一周签署响应，因此 good 表示“截至 thisUpdate 时尚未吊销”；一张一小时前吊销的证书，在颁发机构发布下一份响应前仍可能显示为良好。工具会报告 producedAt、thisUpdate 和 nextUpdate，让响应的新旧程度一目了然，而不是留给人猜测。
• 有些注册局不会公布到期日期。 .de、.nl、.no、.au 和 .fi 不会通过任何协议公布到期日期。结果会注明注册局并说明这一点，而不是显示含糊不清的“未知”。注册数据仅来自 RDAP；没有 WHOIS 回退机制，原因见 docs/adr/0004。
• 不会验证 DNSSEC。 工具会报告委派是否已签名以及这一信息的来源，但绝不会声称已验证链。
• 不会对比父区的委派与区域自身的委派。 “注册商处的名称服务器与区域中的名称服务器不一致”是另一种常见的委派故障。要回答这个问题，需要查询父区域的服务器以获取转介记录，这意味着要多经过一跳，也属于另一项功能。此处检查的是区域自身的名称服务器是否彼此一致。
• 响应时间包含连接建立时间。 计时从请求开始到收到第一个响应标头，包含 DNS、TCP 和 TLS 阶段，因此并不代表服务器的处理时间。
• seo_audit 只审计单个页面，不审计整个站点。 它会请求页面中的内部链接以查找失效链接，但不会进行爬取：不会继续检查第二层页面。要审计整个站点，需对重要页面分别调用它。
• 站点地图只依据协议规则检查，不依据 XSD 检查。 工具会确认文档是否存在、是否声明了 <urlset> 或 <sitemapindex>、包含多少个 <loc> 条目，以及文档是否经过 gzip 压缩——读取前会先解压 sitemap.xml.gz，解压后限制为 16 MiB，以便拒绝解压缩炸弹，而不是将其解压。随后，工具会检查决定使用方是否保留某个条目的规则：命名空间是否正确、是否存在 <loc>、是否为绝对地址、是否经过转义、长度是否不超过 2048 个字符、是否位于站点地图所在的主机上、<lastmod> 是否为 W3C Datetime、<changefreq> 和 <priority> 是否在各自范围内，以及条目数是否不超过 50,000。这里没有 XML 解析器或架构验证器，因此有意不检查四项规则——50 MB 的大小限制、索引列出另一个索引、重复条目，以及 <lastmod> 是否真实。 docs/adr/0019 列出了这些规则并说明原因。检查依据是已读取的内容，因此，如果站点地图超过读取上限，工具只会根据截断前的条目进行判断，并在报告中注明内容已截断；nodejs.org 上多出的、指向其他主机的条目位于截断部分之后，因此不会被报告。
• 如果页面嵌套深达数千层，工具会拒绝审计。 HTML 解析的开销大致与嵌套深度的平方成正比，因此，刻意构造得极其复杂的文档可能会让服务器阻塞数分钟。seo_audit 会先测量深度，再报告拒绝审计。
• 无障碍检查只能做到机器能力所及的程度。 自动化规则只能发现真实问题的大约三分之一。对于 axe 无法判断的情况，工具会如实报告，而不会将其计为通过；但这里的任何绿色结果都不代表无障碍声明。
• 这里不会判断页面的排名。 seo_audit 报告的是 HTML 中的内容。排名取决于公共端点无法提供的信息。
• “与上次相比发生了什么变化”只会保留到服务器进程结束，除非你另行设置。 默认情况下，上一次运行的结果只保存在内存中，不会写入任何位置。因此，重启后的服务器——对桌面 MCP 客户端而言，这种情况每天都会发生——没有可供比较的数据；工具会明确说明这一点，而不会暗示没有变化。在 portfolio 文件中添加 history 路径后，比较结果便可在重启后保留，最长 90 天；如果不添加该路径，就不会写入任何内容。只有两次运行采用相同方式测量的站点才会进行比较，因此，仅检查正常运行时间的快速扫描不会导致下一次运行凭空出现回归。关于其中的取舍，参见 docs/adr/0011 和 docs/adr/0018。
• 只保留上一次运行的结果，不保存一系列记录。 每次运行都会替换上一次结果。按季度查看趋势属于另一项功能，也涉及不同的存储问题，目前尚未有人提出此需求。
• 证书和域名采用不同的时间范围进行评估。 注册信息在 30 天内到期时会发出警告；证书则只在 14 天内到期时才会警告。ACME 客户端会在剩余 30 天时续期，因此若提前这么久就发出警告，几乎每个运行正常的站点都会触发。

文档

• CONTRIBUTING.md — 开发环境设置，以及如何添加工具
• docs/architecture.md — 请求的处理流程，以及如何在不连接网络的情况下测试
• docs/prior-art.md — 已经实现其中部分功能的 MCP 服务、它们的优势，以及本项目填补的空白
• docs/deploying.md — 如何运行 HTTP 实例，以及它的不同之处
• docs/adr/ — 每项结构性决策的简短记录，包括为何浏览器是可选的
• SECURITY.md — 威胁模型和报告政策
• CHANGELOG.md

许可证

MIT — 详见 LICENSE。