E2: MCP Servers — Epic Design Doc#

Status: 🔄 In Refinement (Step 0) Authors: Dan Hannah & Clay Created: 2026-04-18 Parent: QuoteAI Project Design Doc

Overview#

Goals & Non-Goals#

Goals:

• Build two MCP servers: @quoteai/equipment and @quoteai/quotes
• Expose tools that let Claude Code (demo) or a future Anthropic-API-backed app (Full MVP) retrieve the exact context needed to assemble a draft quote
• Wire the servers into the Claude Code config so the demo experience works end-to-end
• Ship a templates/brehob-quote.md reference artifact extracted from the 4M Industries doc, so CC has the target template

Non-Goals:

• No pricing tools (pricing is the salesperson's job, per John)
• No write tools (no creating/updating quotes via MCP — CC or the app does that directly)
• No inventory/CRM tools (post-MVP)
• No auth on MCP servers (stdio transport only for Demo)
• No SSE/hosted transport (post-MVP)

Problem Statement#

The MCP servers are the bridge between the ingested data (E1) and the generation layer (Claude Code in Demo, app in Full MVP). Without them, CC has no way to query the description library and will hallucinate equipment language instead of using John's proven phrasing.

Every MCP tool either makes the demo better (better retrieval = better draft) or adds friction. Ship the minimum set that serves the user flow in the main design doc; nothing else.

What Is This Epic?#

Two independent MCP servers (stdio transport, TypeScript, @modelcontextprotocol/sdk) exposing the tools needed for quote assembly:

• @quoteai/equipment — product catalog search + lookup
• @quoteai/quotes — past-quote semantic search + description retrieval

Both servers share a Postgres connection to the pgvector DB populated by E1. CC is configured to load both during the demo.

Context#

Dependents#

• Claude Code demo experience — CC calls these tools every time it assembles a draft
• E3 (UI) — the UI triggers a flow that ends with CC assembling a draft via these tools
• Future Full MVP app — the in-app Anthropic API call uses the same tools

Dependencies#

• E0 (Foundation) — DB connection layer, env conventions
• E1 (Ingestion + Vector DB) — hard dependency; MCP tools are useless without data

Current State#

No MCP servers exist. The design doc sketches the tool surface; E2 builds it. Anvil's MCP server design (projects/anvil/epics/mcp-tools.md) is a useful reference pattern, but tools are QuoteAI-specific (not reused).

Affected Systems#

Design#

Tool Surface#

@quoteai/equipment#

@quoteai/quotes#

Note on line-item filters. quote_line_items has no structured spec columns today — just description, quantity, prices, product_id FK, embedding, markdown (see db/migrations/001_init.sql). Haiku extracts HP/CFM/PSI as part of the description text, not as structured fields, and product_id isn't populated by the loader, so neither direct nor JOIN-based filtering works without schema changes + re-ingest. MVP accepts vector-only retrieval here — the verbatim description already contains literals like "100HP" / "oilless" / "food-grade" which the embedding picks up.

Post-demo follow-up — if vector-only underperforms on real queries, the cheapest structured filter to add is category?: string (e.g., "ROTARY SCREW AIR COMPRESSOR"). The extractor already produces this per line item via LineItemSchema.category; it just isn't stored. One ALTER + backfill (or re-ingest) adds it.

get_descriptions considered and dropped — it was a thin wrapper over search_line_items with a different input shape. CC can construct the equivalent query string directly; two tools doing similar things raises the odds of CC picking the wrong one.

Hybrid Search Logic (Critical)#

Pure vector search misses filter-style constraints ("100HP", "food-grade"). Hybrid approach applies to search_equipment only — search_line_items is vector-only for MVP (see Tool Surface note).

When any structured filter is provided — filter-then-rank:

1. Generate query embedding via OpenAI
2. SELECT ... WHERE <structured filters> ORDER BY embedding <=> $query_embedding LIMIT $top_k
3. Return top_k

Filter-first ensures hard constraints like "exactly 100HP food-grade" are enforced. The vector step ranks within the eligible set, so a qualifying row can't be missed because it fell outside the N nearest neighbors by embedding distance. This is the opposite of rank-then-filter — which was the earlier proposal but only works when filters are soft signals, not hard requirements.

When no structured filters — rank-only:

1. Generate query embedding via OpenAI
2. SELECT ... ORDER BY embedding <=> $query_embedding LIMIT $top_k
3. Return top_k

If hybrid underperforms (golden test fails): add BM25 full-text search via Postgres ts_vector and merge scores with rrf (reciprocal rank fusion). Deferred until we see where the gaps actually are.

Template Reference#

The 4M Industries template is compressor-specific (CFM/PSI/cooling). Brehob also quotes vacuums, dryers, blowers — each has a different natural spec set. Rather than one monolithic template, split into an outer skeleton plus per-category partials.

Outer skeleton — templates/brehob-quote.md:

• Header (date, proposal number, company info, attention, salutation)
• Intro paragraph ("Brehob Corporation is pleased to have the opportunity…")
• Per-line-item placeholder — CC inserts one characteristics block per line item, selected by that line's extracted category
• Installation (conditional, when present)
• Exclusions, Totals, Terms (Net 30, 30-day validity, FOB Factory)
• Capability pitch, signature, footer (five Brehob offices)

Per-category characteristics partials — templates/characteristics/<category>.md:

• compressor.md — Manufacturer, Series/Model, Cooling, Pressure (PSI), Capacity (CFM), Electric Motor (HP/RPM/ODP/SF), Voltage, Drive System, Dimensions, Weight
• Additional categories (vacuum, dryer, blower, etc.) ship only when a category appears in the ingested subset. The LineItemSchema.category field in ingestion/extractor/schemas.ts drives the lookup — same taxonomy selects the partial AND (post-demo) the optional category filter on search_line_items.

Demo scope — compressor only unless the ingested subset already contains another category that we want in the demo flow. Spot-check the DB during S7 (SELECT DISTINCT category FROM quote_line_items … once the markdown is extracted, or eyeball the line-item markdown) to decide whether to ship a second partial (Henry Ford is noted as "vacuum" in the session handoff — confirm and either add vacuum.md or leave Henry Ford out of the demo golden path).

Compressor characteristics block (first cut — extract verbatim shape from 4M reference during S7):

[CATEGORY IN CAPS]

CHARACTERISTICS
Manufacturer:    [value]
Series / Model:  [value]
Cooling:         [Air/Water]
Pressure:        [PSI]
Capacity CFM:    [value]
Electric Motor:  [HP, RPM, ODP, SF]
Voltage:         [value]
Drive System:    [value]
Dimensions:      [L x W x H]
Weight:          [lbs]

[Warranty block — manufacturer-specific]

Model [X] as described above    Net $[PRICE] Each
Delivery: [estimated timeframe]

CC reads the outer skeleton plus the matching characteristics partial(s) when assembling a draft. This is the "house template" contract.

Data Model Changes#

None — all queries are read-only against E1's data.

API / Interface Changes#

Each MCP server:

• Exports via stdio transport (simplest; CC spawns as child process)
• Uses @modelcontextprotocol/sdk with standard tool registration
• Loads DATABASE_URL and OPENAI_API_KEY from app/.env.local at startup — same source of truth as the ingestion CLI and Next.js app. Avoids re-specifying secrets in the CC config and avoids depending on CC's shell env.
• Ships as an npm workspace package under mcp-servers/* (local dev only — not published)

Env-loading pattern matches the ingestion CLI (which already solved this): use dotenv preload with DOTENV_CONFIG_PATH pointing at app/.env.local. CC config references the compiled entrypoint plus the dotenv preloader; the path to .env.local is absolute (CC's mcp.json does not interpolate workspace variables).

CC config example (replace <repo-root> with the absolute path to ~/Documents/Code/quoteai):

{
  "mcpServers": {
    "quoteai-equipment": {
      "command": "node",
      "args": ["-r", "dotenv/config", "<repo-root>/mcp-servers/equipment/dist/index.js"],
      "env": { "DOTENV_CONFIG_PATH": "<repo-root>/app/.env.local" }
    },
    "quoteai-quotes": {
      "command": "node",
      "args": ["-r", "dotenv/config", "<repo-root>/mcp-servers/quotes/dist/index.js"],
      "env": { "DOTENV_CONFIG_PATH": "<repo-root>/app/.env.local" }
    }
  }
}

S8 ships a short README snippet walking through the absolute-path substitution so first-time demo setup isn't a scavenger hunt.

Edge Cases & Gotchas#

Testing Strategy#

Test Layers#

Required Fixtures#

Verification Rules#

1. Every tool has at least one integration test against seeded DB.
2. Golden retrieval test runs green before demo.
3. Manual E2E walkthrough before showing anyone — open CC, fill mock form, watch it call tools, inspect output against the 4M template.

Stories#

Stories are split into two phases. Phase A is the vertical slice — the minimum set that answers "can CC assemble a good draft from these tools?" If Phase A fails, Phase B is noise; we'd re-scope. If Phase A passes, Phase B fills in breadth.

Phase A — Vertical slice (demo-path minimum):

Phase A explicitly skips the equipment server. If the spike shows CC needs product-spec lookups to fill template fields cleanly, we promote S0 + S2 out of Phase B before finishing Phase B's other work.

Phase B — Breadth (fills in after Phase A demonstrates the loop):

Known Issues / Tech Debt#

Risks#

Decisions Log#

E2 is the bridge. Shipping means CC can call these tools, get good results, and assemble a quote that looks like the 4M template. Nothing else.

Status (as of 2026-04-21): E2 is closed. All 9 stories shipped; both phase walkthroughs passed; two follow-ups (#1 lubrication, #6 confidence) landed from Phase B feedback; Sonnet validated for Full MVP. Deferred Phase B walkthrough findings (#3 category filter, #4 markdown rendering, #5 installation scope, #7 data gap, #8 get_product utility) are captured in next.md as post-demo pickups.