Main Street MCP

A free, industry-specific MCP server that gives a small business's AI assistants (ChatGPT, Claude, etc.) reliable answers about the business itself — hours, menu/services, FAQs, staff, and how to book — instead of hallucinating them. One business.yaml file per business; no code changes required to run it.

Quickstart (business owner)

1. Install Node.js 20+ (or use the version already on your machine — check with node -v).

2. Generate a starter config for your industry:

   npx -y mainstreet-mcp init --industry restaurant

   Replace restaurant with your industry. Supported industries: restaurant, dental, law-firm, home-services, salon-spa, fitness-studio, real-estate-agent, auto-repair, insurance-agency, church.

   This writes business.yaml in the current directory — edit it with your business's real name, hours, menu/services, FAQs, etc. (Use --out <path> for a different name; every other command then needs --config <path>.)

3. Check your edits are valid:

   npx -y mainstreet-mcp validate

   A broken file (bad YAML, a typo'd industry, a field that doesn't fit) prints a specific, readable error instead of a stack trace.

4. Point your AI assistant at it. For a local MCP client (e.g. Claude Desktop) that spawns stdio servers, add an entry like:

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

   To serve over HTTP instead (e.g. for a hosted deployment), run:

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

   The HTTP server only binds to 127.0.0.1 and validates the Host/Origin headers on every request — put a reverse proxy in front of it for anything beyond local testing.

Related MCP server: essetech-ai-readiness-mcp

What it gives an AI assistant

Every business gets 7 universal tools regardless of industry:

• get_business_profile — name, description, contact info, address, policies

• check_open_status — open/closed right now (or at a given time), in the business's own timezone, including overnight hours and holiday/exception overrides

• search_offerings — free-text search over whatever the business sells/offers

• answer_question — looks up configured FAQs; returns found: false rather than a guess when nothing matches confidently

• list_staff — configured staff, roles, bios, credentials

• get_booking_options — how to actually book (phone/online/walk-in/email)

• submit_inquiry — lets a customer leave a message; rate-limited, sanitized, and screened by industry-specific guardrails before it's accepted

On top of that, each industry preset turns on a handful of capabilities — pluggable tool modules — matched to that industry:

Every tool ships an outputSchema and returns structuredContent, so a calling agent gets typed data back, not just prose to parse.

Guardrails

Some presets screen submit_inquiry messages before accepting them, on top of the universal sanitization (HTML/control-char stripping, length caps, rate limiting):

• dental — rejects messages containing an SSN-shaped pattern, and long messages with clinical/health detail keywords (tells the patient to call the office instead).

• law-firm — caps the message to one line / 280 characters (a topic, not case details).

• salon-spa / fitness-studio — rejects messages containing health/medical detail keywords (pregnancy, injury, medication, etc.), directing the customer to tell staff in person instead.

price_estimate outputs always carry is_estimate: true plus a disclaimer — never present as a firm quote.

Install

Claude Desktop (one-click, no terminal)

Download the latest mainstreet-mcp.mcpb from the releases page (or build it yourself — see mcpb/ below), then double-click it. Claude Desktop opens it as a Desktop Extension install prompt; it asks for one thing — the path to your business.yaml — then installs. No Node.js install or terminal needed.

To build the .mcpb yourself:

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

Claude Code (plugin)

Install the bundled plugin, which registers the MCP server and adds a setup-my-business skill that interviews you and writes business.yaml for you:

claude plugin install ./plugin

The plugin's MCP config expects business.yaml at your project root (${CLAUDE_PROJECT_DIR}/business.yaml), which is exactly what init writes — run the setup-my-business skill, or npx -y mainstreet-mcp init --industry <yours>, from that directory.

Claude Code (direct MCP add, no plugin)

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

Generic JSON config (any MCP client)

For any client that spawns stdio servers from a JSON config (Claude Desktop's manual config, other MCP clients):

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

Example configs

examples/ has one working <industry>.business.yaml per supported industry — the same files init copies from and the E2E test suite runs against.

Development

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

Stack: @modelcontextprotocol/server@2.0.0 (MCP spec 2026-07-28), TypeScript strict/ESM, Zod for all schemas and config validation, yaml for parsing business.yaml. All dependencies are pinned to exact versions (no ^).

Project layout

• src/config/schema.ts — the business.yaml Zod schema (BusinessConfigSchema) and types.

• src/config/load.ts — loads + validates a config file, including per-capability config and the industry/capability compatibility check.

• src/hours.ts — timezone-aware open/closed logic (Intl-based), overnight ranges, date exceptions, forward-scanning for the next open/close time.

• src/search.ts — the recall-first free-text search used by search_offerings and answer_question.

• src/inquiries.ts — InquirySink: sanitization, rate limiting, guardrail hook, and file/webhook delivery for submit_inquiry.

• src/capabilities/* — the 9 pluggable capability modules (config schema + tool registration each).

• src/presets/* — the 10 industry presets: which capabilities are on, the instructions text injected into the server, and any guardHooks.

• src/tools/universal.ts — the 7 universal tools every business gets.

• src/server.ts — createServer(config): builds the McpServer for a loaded config.

• src/cli.ts — mainstreet-mcp entry point (stdio default, init, validate, serve --http).

• src/test/*.test.js (compiled from .ts) — unit tests (schema, search, hours, inquiries/ guardrails) plus an E2E suite that spawns the built stdio server for every example config and drives it with the real MCP client SDK.

Testing notes

• npm test runs both unit tests and the E2E suite (src/test/e2e.test.ts), which spawns dist/cli.js as a child process via StdioClientTransport for every file in examples/, calls tools/list, then calls every registered tool and asserts it returns structuredContent without isError.

• serve --http binds a local port, which some sandboxed shells block by default; test it outside such a sandbox if EPERM/listen errors appear.

Status

Presets, capabilities, universal tools, CLI, and all 10 example configs are built and verified (build, unit tests, E2E stdio tests, CLI validate success/failure paths, and an HTTP smoke test all pass — see the build's final report for exact output). This is a first build, not yet published or deployed anywhere.