mainstreet-mcp

Main Street MCP

一款免费的行业专用 MCP 服务，可让小型企业的 AI 助手 （ChatGPT、Claude 等）可靠地回答有关企业本身的问题——营业时间、菜单／服务、 常见问题、员工以及如何预约——而不是凭空编造。每家企业只需一个 business.yaml 文件； 无需更改代码即可运行。

快速入门（企业主）

1. 安装 Node.js 20+（或使用机器上已有的版本——使用 node -v 查看）。

2. 为你的行业生成入门配置：

   npx -y mainstreet-mcp init --industry restaurant
   

   将 restaurant 替换为你的行业。支持的行业：restaurant、dental、 law-firm、home-services、salon-spa、fitness-studio、real-estate-agent、 auto-repair、insurance-agency、church。

   此命令会在当前目录写入 business.yaml——请编辑该文件，填写企业的真实名称、营业时间、 菜单／服务、常见问题等。（使用 --out <path> 可指定其他文件名； 之后的每条命令都需要使用 --config <path>。）

3. 检查修改后的文件是否有效：

   npx -y mainstreet-mcp validate
   

   如果文件有问题（YAML 格式错误、行业名称拼写错误、不适用的字段），命令会输出具体、 易读的错误信息，而不是堆栈跟踪。

4. 将 AI 助手连接到它。对于会启动 stdio 服务的本地 MCP 客户端（例如 Claude Desktop），添加如下条目：

   {
     "mcpServers": {
       "my-business": {
         "command": "npx",
         "args": ["-y", "mainstreet-mcp", "--config", "/absolute/path/to/business.yaml"]
       }
     }
   }
   

   若要改用 HTTP 提供服务（例如用于托管部署），请运行：

   npx -y mainstreet-mcp serve --http --port 3000
   

   HTTP 服务仅绑定到 127.0.0.1，并会对每个请求验证 Host／Origin 标头——除本地测试外， 请在它前面部署反向代理。

它能为 AI 助手提供什么

无论行业如何，每家企业都会获得 7 个通用工具：

• get_business_profile — 名称、描述、联系信息、地址、政策
• check_open_status — 当前（或指定时间）的营业状态，使用企业所在时区，并涵盖跨夜营业时间及节假日／例外情况覆盖设置
• search_offerings — 对企业销售／提供的内容进行自由文本搜索
• answer_question — 查询已配置的常见问题；如果没有足够把握的匹配项，则返回 found: false，而不是猜测
• list_staff — 已配置的员工、职位、简介、资质
• get_booking_options — 实际预约方式（电话／在线／到店／电子邮件）
• submit_inquiry — 允许客户留言；该工具设有速率限制、会清理内容，并在接受留言前通过行业专用防护规则筛查

此外，每个行业预设都会启用若干与该行业相匹配的功能——可插拔的工具模块：

行业	功能／工具
restaurant	menu → get_menu
dental	insurance_accepted → check_insurance_accepted
law-firm	practice_areas → list_practice_areas（始终附带非法律建议免责声明）
home-services	service_area → check_service_area、price_estimate → get_price_estimate
salon-spa	class_schedule → get_class_schedule
fitness-studio	class_schedule → get_class_schedule
real-estate-agent	listings → search_listings
auto-repair	service_area、price_estimate、insurance_accepted
insurance-agency	coverage_lines → list_coverage_lines
church	service_times → get_service_times

每个工具都会提供 outputSchema 并返回 structuredContent，因此调用工具的 Agent 会获得类型化数据， 而不只是需要解析的文字。

防护措施

某些预设会在接受 submit_inquiry 消息前对其进行筛查，此外还会执行通用清理（剥除 HTML 和控制字符、限制长度、速率限制）：

• dental — 拒绝包含类似 SSN 格式的模式的消息，以及包含临床／健康详情关键词的长消息（会告知患者改为致电办公室）。
• law-firm — 将消息限制为单行／280 个字符（仅限主题，不包含案件详情）。
• salon-spa / fitness-studio — 拒绝包含健康／医疗详情关键词（怀孕、受伤、药物等）的消息，并引导客户改为当面告知工作人员。

price_estimate 的输出始终带有 is_estimate: true 和免责声明，绝不会将其呈现为正式报价。

安装

Claude Desktop（一键安装，无需终端）

从 releases 页面下载最新的 mainstreet-mcp.mcpb（也可以自行构建——请参见下方的 mcpb/），然后双击。Claude Desktop 会将其作为桌面扩展安装提示打开；它只会询问一项内容——用于存放 business.yaml 的文件夹。选择一个方便日后找到的文件夹即可；“文稿”文件夹也可以。无需安装 Node.js，也无需使用终端。

安装前无需准备 business.yaml。 如果文件夹为空，服务会以设置模式启动：让 Claude“设置我的业务”，它会列出行业、将初始文件写入该文件夹，并通过询问来填写你的实际营业时间、服务和价格。完成后关闭并重新开启该扩展，业务工具就会显示出来。你选择的文件夹始终不变。

要自行构建 .mcpb：

npx @anthropic-ai/mcpb pack mcpb build/mainstreet-mcp.mcpb

Claude Code（插件）

安装捆绑的插件，它会注册 MCP 服务，并添加一个 setup-my-business 技能，通过询问来为你创建 business.yaml：

claude plugin install ./plugin

该插件的 MCP 配置要求 business.yaml 位于项目根目录（${CLAUDE_PROJECT_DIR}/business.yaml），这正是 init 写入文件的位置——请在该目录中运行 setup-my-business 技能，或运行 npx -y mainstreet-mcp init --industry <yours>。

Claude Code（直接添加 MCP，无需插件）

claude mcp add mainstreet -- npx -y mainstreet-mcp --config /absolute/path/to/business.yaml

通用 JSON 配置（任意 MCP 客户端）

适用于任何通过 JSON 配置启动标准输入／输出服务的客户端（Claude Desktop 的手动配置、其他 MCP 客户端）：

{
  "mcpServers": {
    "my-business": {
      "command": "npx",
      "args": ["-y", "mainstreet-mcp", "--config", "/absolute/path/to/business.yaml"]
    }
  }
}

配置示例

examples/ 中为每个受支持的行业提供了一份可用的 <industry>.business.yaml 文件——这些文件也是 init 复制的来源，并会用于 E2E 测试套件。

开发

npm install
npm run build     # tsc -> dist/
npm test          # builds, then runs node --test against dist/test/*.test.js

技术栈：@modelcontextprotocol/[email protected]（MCP 规范 2026-07-28）、TypeScript 严格模式／ESM、Zod 用于所有架构和配置验证、yaml 用于解析 business.yaml。所有依赖项均固定为精确版本（不使用 ^）。

项目布局

• src/config/schema.ts — business.yaml 的 Zod 模式（BusinessConfigSchema）和类型。
• src/config/load.ts — 加载并验证配置文件，包括各能力的配置和行业/能力兼容性检查。
• src/hours.ts — 基于时区的营业/休息逻辑（基于 Intl）、跨夜时间段、日期例外，以及向前扫描以查找下一个营业/休息时间。
• src/search.ts — search_offerings 和 answer_question 使用的召回优先型全文搜索。
• src/inquiries.ts — InquirySink：数据清理、速率限制、护栏钩子，以及用于 submit_inquiry 的文件/ Webhook 投递。
• src/capabilities/* — 9 个可插拔能力模块（每个模块都包含配置模式和工具注册）。
• src/presets/* — 10 个行业预设：启用的能力、注入服务的说明文本，以及任何 guardHooks。
• src/tools/universal.ts — 每家企业都会获得的 7 个通用工具。
• src/server.ts — createServer(config)：为已加载的配置构建 McpServer。
• src/cli.ts — mainstreet-mcp 入口点（默认使用 stdio，支持 init、validate、serve --http）。
• src/test/*.test.js（由 .ts 编译而来）— 单元测试（模式、搜索、营业时间、咨询/护栏），以及一个端到端测试套件：针对每个示例配置启动构建好的 stdio 服务，并使用真实的 MCP 客户端 SDK 驱动它。

测试说明

• npm test 会运行单元测试和端到端测试套件（src/test/e2e.test.ts）。该套件会针对 examples/ 中的每个文件，通过 StdioClientTransport 将 dist/cli.js 作为子进程启动，调用 tools/list，然后调用所有已注册的工具，并断言它们返回 structuredContent 且没有 isError。
• serve --http 会绑定本地端口，某些沙盒 shell 默认会阻止此操作；如果出现 EPERM/listen 错误，请在此类沙盒之外测试。

状态

预设、能力、通用工具、CLI 和全部 10 个示例配置均已构建并通过验证（构建、单元测试、E2E stdio 测试、CLI 验证成功/失败路径，以及 HTTP 冒烟测试全部通过——确切输出请参见构建的最终报告）。这是首次构建，尚未在任何地方发布或部署。

工作流套件：由调用方提供事实以生成审核资料包

0.1.4 版新增了三个无状态套件。每个套件恰好提供两个工具：analyze_workflow 和 prepare_workflow_draft。它们根据明确的示例策略评估提供的结构化事实，并在输入充分时准备一份未发送的审核草稿。套件不包含服务商账户、实时来源验证、存储、消息、资金转移或履约变更。你的 MCP 主机可能会将工具输入发送给其模型服务商；请先使用虚构输入，并遵循所在组织的数据规则。

npx -y [email protected] kit quote-followup
npx -y [email protected] kit invoice-discrepancies
npx -y [email protected] kit order-handoff

每个已配置的 MCP 服务使用一个套件。试用虚构演示，并申请范围明确的实现方案。这些免费套件不包含已连接的客户系统。委托定制集成前，请先检查原生 CRM、会计或订单软件。

{ "mcpServers": { "quote-review": { "command": "npx", "args": ["-y", "[email protected]", "kit", "quote-followup"] } } }

请询问：“使用提供的时间戳和跟进策略审核此报价。只有在工具表示已就绪时才准备草稿。”发送已发布工具架构中的所有必填字段，未知事实使用 null。needs_review 表示需要核实来源；no_action 表示根据提供的事实和策略，无需准备草稿。示例输入和预期状态已打包在 dist/workflows/core.js 中。这些初始套件支持 USD、EUR、GBP、CAD 和 AUD，每个主要货币单位为 100 分；其他货币需要单独审核规则。金额使用整数分，货币必须一致，日期使用 UTC ISO 秒或三位毫秒。七天的时效窗口和先付款后生产规则是供你的业务审核的示例策略。asOf 由调用方提供，并非实时钟表或验证时间戳。

这些 CLI 套件通过 stdio 与兼容的 MCP 主机配合使用。桌面套件保留原有的业务设置流程；不会自动启用工作流套件。更改命令即可选择套件。确切的主机配置请参阅演示的安装说明。