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.
Two remote surfaces for J’s quoteTools: REST routes under /external/v1/quotes and a Streamable HTTP MCP server at /mcp.
Every route and MCP tool declares scopes, the service rechecks scopes internally, and getQuote now applies the same quote access guards as the app.
Claude Code, Codex, partner systems, or custom agents can run context → preview → create using Dealops pricing, approvals, idempotency, and preview-token safeguards.
New Mocha unit tests, HTTP MCP tests, oRPC surface tests, and e2e suites cover both transports; e2e is intentionally left to CI.
1. Why this exists
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/quotesnamespace. - No remote MCP server for model clients.
- External model clients needed a bridge or agent-shaped integration.
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.
apps/server/src/dealops2/quoteTools and apps/server/src/orpc/router/v1/quotes; there is no Prisma migration.
2. What changes
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-policyGET /quotes/context/approval-rules |
Lookups | quote:read |
Single-document reads, exempted from pagination contract expectations. |
quotes. The router surface test pins every route, method, and scope.
New server package: apps/server/src/dealops2/quoteTools/mcp/*. It mounts at /mcp before body parsers and uses @modelcontextprotocol/sdk@1.32.1.
get_quote_context, preview_quote, create_quote, search_opportunities, get_quote, product/policy/rule lookups, and get_quoting_guidance.
dealops://quote-context exposes the organization quote context as JSON.
quoting_guide carries drafting rules and the “preview, show assumptions, get explicit approval, then create” workflow.
x-api-key or Bearer.Mcp-Session-Id stored in Redis.contextHash.MCP_TOOL_AUTH.entrypoint: MCP + client name.createQuote(actor, input, { origin }) can now record where a remote create came from.
- REST default:
entrypoint: 'API',client: 'quote-tools'. - MCP:
entrypoint: 'MCP', client from MCPclientInfo.name.
MCP creates get a separate thread per client/user/opportunity.
quote-tools:mcp:<client>:<user>:<opportunity>
The API default stays quote-tools:<user>:<opportunity>.
getQuote now calls enforceQuoteAccess through a constructed tRPC auth context.
This closes the gap where quote-by-id exposure could bypass owner restriction and agent-quote gates.
mcp/__tests__/server.test.ts covers tool/resource/prompt surface, JSON Schema, auth refusal, origin recording, rejection mapping, safe errors, and session pinning.
mcp/__tests__/http.test.ts drives the real Streamable HTTP endpoint with the SDK client, including sessions, Bearer auth, 401/404/405/429, and DELETE.
New e2e suites cover REST routes and MCP flow over real HTTP using the existing quote tool chain steps via new transport adapters.
Adds docs/integrations/mcp-quote-tools.md and updates knowledge/concepts/quote-tools.md.
3. How it works
/external/v1 and /mcp both read the raw request stream themselves.
x-api-key first, then Authorization: Bearer.
AuthMeta; the quote service then re-authorizes the actor before doing work.
create_quote requires previewToken, explicit opportunityId, and idempotencyKey. MCP intentionally omits conversationId.
409 or 412 with data.issue; MCP tool errors include the caller-safe issue payload.
consumeRateLimit is extracted from oRPC middleware so /mcp shares the org’s /external/v1 Redis sliding-window budget.
/quotes/preview → tools.previewQuote(actor, input)/quotes → tools.createQuote(actor, input)/quotes/{quoteId} → tools.getQuote(actor, input)preview_quote → standard quote draft JSON Schema.create_quote → origin { entrypoint: 'MCP', client }.dealops://quote-context → pinned org context.4. What it doesn't change
- No Dealops agent is introduced between the caller’s model and the quote tools.
- No Prisma migration;
ApiConversationEntrypoint.MCPalready exists. - The core preview → create contract is unchanged: a ready preview token gates creation.
- The existing API conversation default for REST remains
API / quote-tools. - OAuth 2.1 is not implemented in this PR.
- The external API rate limiter behavior is intended to stay the same; it is only extracted for reuse.
- Renewals, amendments, and expansions are still out of scope for these quote tools.
5. Risks / rollback / open questions
- Edge metering gap: the edge Worker currently routes
api.dealops.com/external/*, so/mcpreaches origin directly and is not edge-metered. - OAuth follow-up: API keys work for Claude Code and Codex, but claude.ai and ChatGPT connectors need OAuth 2.1 per the MCP authorization spec.
- Session behavior: MCP sessions are Redis-backed, 24h sliding TTL, bound to the opening API key. Unknown or wrong-key sessions return 404 so clients reinitialize.
- CI dependency: unit/lint/type checks are reported clean locally; the new e2e suites were not run locally and are left to CI.
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.
The external API docs workflow should publish the new /quotes routes to the public reference after merge to main.