Holiday Calendar

Modern Mustard Seed 小型企业 MCP 入门套件

为 Claude 部署一个远程 MCP 连接器，确保首次提交就通过 Anthropic 目录审核。

本套件汇集了 Modern Mustard Seed 用于生产环境连接器的实践模式，并将其整理为一个简洁的 Next.js 项目，供你派生使用：

• Next.js App Router 和 mcp-handler 的路由模板：通过单一 URL 为每个连接器提供 Streamable HTTP，且不会发生重定向。
• 加载时强制执行的工具规范：每个工具都必须有标题、readOnlyHint 或 destructiveHint，名称必须采用 snake_case 且不超过 64 个字符，描述应说明功能而非引导用户。违反任一规则都会导致 pnpm test 失败，远早于审核人员看到它。
• 具体的错误消息，而不是 “Bad Request”，以及低于 Claude 限制的输出大小上限。
• **为 Claude 的共享出口 IP 段设计的速率限制。**所有 claude.ai 用户都来自 160.79.104.0/21，因此不会按 IP 地址进行限制，也不会返回 HTTP 429。
• 防止 SSRF 的安全抓取功能，适用于任何读取用户提供 URL 的工具，并附带测试，证明监听中的 loopback 服务器不会收到任何请求。
• 评估测试框架：使用真实提示词测试你的在线 URL，无需模型或 API 密钥。
• 文档、隐私、条款和支持页面模板，以及 /.well-known/security.txt，所有内容均由一个配置文件驱动。
• 提交检查清单：对应目录表单的 10 个步骤和 7 项政策确认，每条规则都附有指向 Anthropic 文档的链接。
• 完整示例：一个美国联邦假日和工作日历，包含 5 个只读工具，并通过了自己的全部 35 项评估。

采用 MIT 许可。由 Modern Mustard Seed 构建。

在线演示

示例连接器已部署并在线运行，直接使用本仓库部署，无需任何修改：

• 连接器 URL：https://starter.modernmustardseed.com/holidays（在 Claude 中选择自定义 > 连接器 > 添加自定义连接器）
• 审核人员查看的文档页面：https://starter.modernmustardseed.com/docs/holidays
• 隐私、条款和支持页面：https://starter.modernmustardseed.com/privacy、[/terms](https://starter.modernmustardseed.com/terms)、[/support](https://starter.modernmustardseed.com/support)
• 官方 MCP Registry 条目：com.modernmustardseed/holiday-calendar

你也可以自行对其运行评估：node eval/holidays.eval.mjs https://starter.modernmustardseed.com

快速入门：10 分钟

你需要 Node 22.6 或更高版本、pnpm 和 Vercel 账号（任何可运行 Next.js 的主机都可以）。

1. 创建副本。（1 分钟）

gh repo create my-connector --template ModernMustardSeed/small-business-mcp-starter --public --clone
cd my-connector
pnpm install

或者在 GitHub 上选择 Use this template。

2. 运行并验证其正常工作。（2 分钟）

pnpm dev

在第二个终端中：

pnpm test
pnpm evals http://localhost:3000

你应该会看到单元测试显示 32 pass，评估显示 35 of 35 passed。打开 http://localhost:3000/docs/holidays，查看审核人员会阅读的文档页面。

3. 打造你自己的版本。（2 分钟）

编辑 lib/site.ts：公司名称、所在地、网站、支持邮箱、安全邮箱和政策日期。所有公开页面和 security.txt 都会读取其中的信息。将 app/icon.svg 和 app/apple-icon.png 替换为你自己的标志；目录列表需要提供图标。

4. 部署。（3 分钟）

在 vercel.com/new 导入仓库，或者在终端中运行：

vercel deploy --prod

Vercel 会设置 VERCEL_PROJECT_PRODUCTION_URL，页面会用它生成链接。对于 MCP 路径，请关闭 Attack Challenge Mode 和任何机器人防护规则：它们会向 Claude 返回挑战页面。

5. 检查部署。（1 分钟）

pnpm preflight https://your-project.vercel.app
pnpm evals https://your-project.vercel.app
npx @modelcontextprotocol/inspector --cli https://your-project.vercel.app/holidays --transport http --method tools/list

Preflight 会检查 HTTPS、是否存在重定向、是否返回 403 或 429、每个公开页面是否返回 200、MCP 握手以及注释规则。

6. 在 Claude 中试用。（1 分钟）

在 Claude 中，打开 Customize > Connectors > Add custom connector，然后粘贴 https://your-project.vercel.app/holidays。询问：“一张日期为 2026-11-20 的发票，须在 10 个工作日内支付。到期日是哪天？”在 Claude Code 中：

claude mcp add --transport http holidays https://your-project.vercel.app/holidays

构建自己的连接器

1. 将 lib/holidays/tools.ts 复制到 lib/<yours>/tools.ts。将每个工具声明为 ToolSpec：名称、标题、描述、zod 输入架构、注释、每分钟限额、可选的全局限额、可安全记录日志的字段，以及返回 ok(data) 或 fail(code, sentence) 的 run 函数。
2. 将 app/holidays/route.ts 复制到 app/<yours>/route.ts，并将其指向你的工具。
3. 将 app/docs/holidays/page.tsx 复制到 app/docs/<yours>/page.tsx。保留“For reviewers”部分：你需要将它粘贴到表单中。
4. 重写 app/privacy/page.tsx，确保其中每句话都准确描述你的工具：它们会接收什么、读取什么、你会保留什么以及保留多久、还有谁会接触这些信息。
5. 复制 eval/holidays.eval.mjs。根据真实用户会输入的提示词编写 20 到 50 个用例，并使用代码之外的权威来源确定预期值。包含错误用例。
6. 如果某个工具要获取用户提供的 URL，请使用 lib/mcp/safe-fetch.ts 中的 safeFetch。切勿直接 fetch 用户提供的 URL。
7. 部署后，针对生产环境运行 pnpm preflight 和 pnpm evals，在 Claude 中测试每个工具，然后按照 docs/SUBMISSION-CHECKLIST.md 逐项检查。

每种模式存在的原因及其对应的规则：docs/PATTERNS.md。

包含内容

路径	作用
app/holidays/route.ts	连接器端点。每个连接器一个文件。
lib/mcp/tool.ts	ToolSpec、registerTools、runTool：约定、限制、错误、大小上限和日志记录。
lib/mcp/limits.ts	按实例和全局设置限制，不按 IP；使用 Redis，并在内存中提供回退方案；还有一个小型缓存。
lib/mcp/safe-fetch.ts	SSRF 安全的抓取：仅限公共地址、受保护的 DNS 查询、检查五次重定向、字节数上限和截止时间。
lib/holidays/	示例连接器：节假日引擎及其五个工具。
lib/site.ts	公司、支持和安全联系信息，以及政策日期。请先编辑此文件。
app/docs、app/privacy、app/terms、app/support	审核人员和用户会打开的页面。
app/.well-known/security.txt	RFC 9116 安全联系信息。
eval/	无依赖的 MCP 客户端，以及示例针对线上 URL 的 35 项检查。
scripts/preflight.mjs	针对已部署 URL 的提交前检查。
scripts/check-prose.mjs	跟踪的文件中若出现 em dash 或 en dash，则检查失败。
test/	针对约定、限制、SSRF 防护和示例引擎的单元测试。
docs/	提交检查清单和模式说明。

环境

示例无需环境变量即可运行。以下变量为可选：

变量	用途
SITE_URL	公共源站；如果你不使用 Vercel，或希望页面链接使用自定义域名，请设置此变量。
UPSTASH_REDIS_REST_URL、UPSTASH_REDIS_REST_TOKEN	用于跨实例共享的全局速率限制和缓存。Vercel Marketplace 集成会改为设置 KV_REST_API_URL 和 KV_REST_API_TOKEN；程序会读取这两组变量。若未使用 Redis，每个实例会在内存中自行限制，限值为全局数值的十分之一。

命令

命令	作用
pnpm dev	在 3000 端口启动本地服务。
pnpm test	单元测试（Node 内置运行器）。
pnpm evals <url>	针对运行中服务执行示例的 eval。
pnpm preflight <url>	针对已部署 URL 执行提交前检查。
pnpm typecheck、pnpm lint、pnpm build	常规命令。
pnpm check:prose	检查跟踪的文件中是否含有 em dash 或 en dash。

关于示例

节假日日历依据 5 U.S.C. 6103（一部公有领域法规）计算 11 个美国联邦节假日，并遵循联邦机构采用的节日观测规则：周六的节假日移至前一个周五，周日的节假日移至后一个周一。它覆盖 2021 至 2100 年。其工具可列出某一年的节假日、查找接下来的节假日、检查某个日期是否为工作日、为某个日期增加工作日，以及统计一段时间内的工作日数量。它不会发起网络请求，也不会存储任何内容。eval 会将其结果与人事管理办公室公布的日程进行核对。

贡献与安全

欢迎提交问题和拉取请求；请参阅 CONTRIBUTING.md。请按照 SECURITY.md 中的说明私下报告漏洞。

本工具包与 Anthropic 无关，也未获其认可。“Claude”是 Anthropic, PBC 的商标。目录规则可能会变化；检查清单将每条规则链接到 Anthropic 的文档，方便你在提交前确认。

由 Modern Mustard Seed 构建

本工具包来自 Modern Mustard Seed，这是一家位于蒙大拿州卡利斯佩尔的 AI 工作室，为小型企业构建网站、AI 语音 Agent 和定制软件，并为你提供端到端的托管服务。

• 示例连接器的在线演示
• 我们如何构建连接器，以及每条规则的由来
• 我们为 Claude 构建的所有连接器
• 我们生产环境中连接器的文档

许可证

MIT，版权所有 (c) 2026 Modern Mustard Seed LLC。