Quote tools are now callable over REST and MCP

This PR exposes the Dealops 2 quoteTools service to external callers that bring their own model, without inserting a Dealops agent layer.

PR: #8034 Author: @megnaanand24 Ticket: DEA-8396 Stack: based on #8032 Area: Dealops 2 / apps/server Files: 27 Diff: +3173 / -93 State: open

What it adds

Two remote surfaces for J’s quoteTools: REST routes under /external/v1/quotes and a Streamable HTTP MCP server at /mcp.

What it protects

Every route and MCP tool declares scopes, the service rechecks scopes internally, and getQuote now applies the same quote access guards as the app.

What it enables

Claude Code, Codex, partner systems, or custom agents can run context → preview → create using Dealops pricing, approvals, idempotency, and preview-token safeguards.

Test posture

New Mocha unit tests, HTTP MCP tests, oRPC surface tests, and e2e suites cover both transports; e2e is intentionally left to CI.

quoteTools service
REST /external/v1
MCP /mcp
Redis sessions / rate limit
OpenAPI + docs
Tests

1. Why this exists

Before

The quote tool layer existed as server-side functionality, but callers outside Dealops did not have a first-class way to call it directly.

  • No public /external/v1/quotes namespace.
  • No remote MCP server for model clients.
  • External model clients needed a bridge or agent-shaped integration.
After

The same service functions are exposed through two thin adapters.

  • REST for ordinary API clients.
  • MCP for Claude Code, Codex, and other tool-using clients.
  • No Dealops agent mediates the conversation.
Positioning: this is Dealops 2 server work. It lives under apps/server/src/dealops2/quoteTools and apps/server/src/orpc/router/v1/quotes; there is no Prisma migration.

2. What changes

REST route surface

New router: apps/server/src/orpc/router/v1/quotes/_router.ts. Each route calls exactly one quoteTools function and uses scoped oRPC auth metadata.

Route Function Scopes Notes
POST /quotes/context getQuoteContext quote:read Returns org catalog, discount policy, approval rules, and opportunity questions.
POST /quotes/preview previewQuote quote:read Validates and prices without saving; returns previewToken when ready.
POST /quotes createQuote quote:read, quote:write Creates only from a ready preview token and idempotency key.
POST /quotes/opportunities/search searchOpportunities quote:read, opportunity:read Finds candidate opportunities by name or CRM id.
GET /quotes/{quoteId}
GET /quotes/by-conversation/{conversationId}
getQuote quote:read Now protected by app-equivalent quote access gates.
POST /quotes/context/products getProductDetails quote:read, product:read Filters to caller-visible products.
GET /quotes/context/discount-policy
GET /quotes/context/approval-rules
Lookups quote:read Single-document reads, exempted from pagination contract expectations.
OpenAPI: the generated public spec includes quotes. The router surface test pins every route, method, and scope.

3. How it works

Mount order
before body parsers /external/v1 and /mcp both read the raw request stream themselves.
Authentication
REST uses existing external API key auth. MCP accepts x-api-key first, then Authorization: Bearer.
Authorization
Route/tool metadata uses scoped AuthMeta; the quote service then re-authorizes the actor before doing work.
Preview safety
create_quote requires previewToken, explicit opportunityId, and idempotencyKey. MCP intentionally omits conversationId.
Rejections
REST maps refused creates to 409 or 412 with data.issue; MCP tool errors include the caller-safe issue payload.
Rate limit
Shared budget consumeRateLimit is extracted from oRPC middleware so /mcp shares the org’s /external/v1 Redis sliding-window budget.
REST adapter shape
POST
/quotes/preview → tools.previewQuote(actor, input)
POST
/quotes → tools.createQuote(actor, input)
GET
/quotes/{quoteId} → tools.getQuote(actor, input)
MCP adapter shape
tool
preview_quote → standard quote draft JSON Schema.
tool
create_quote → origin { entrypoint: 'MCP', client }.
res
dealops://quote-context → pinned org context.

4. What it doesn't change

Explicit non-goals

5. Risks / rollback / open questions

Review focus
Rollback lever

The new surfaces are isolated: remove the quotes router registration and the /mcp mount to stop remote access while leaving the underlying quoteTools service intact.

Post-merge

The external API docs workflow should publish the new /quotes routes to the public reference after merge to main.