Functional reliability PRD

OptiCat MCP Functional Reliability Upgrade

1. Product vision

Give a user a natural-language way to find and understand OptiCat catalog information while ensuring that every part number, fitment statement, cross-reference, and replacement claim comes from the current catalog response for that request.

The product should feel helpful and decisive without guessing. It should ask one focused question when a missing detail changes the result, show clearly labeled conditional options when that is more useful, and say when the catalog is unavailable or cannot verify an answer.

2. Problem statement

The proof of concept already retrieves useful catalog data, but the customer journey is not consistently complete:

• rich API responses are reduced to prose before the AI receives them;
• partial result lists do not always say that they are partial;
• engine, side, position, and other fitment conditions may not remain attached to each result;
• the AI may need to select a part identity or brand before a cross-reference lookup;
• immediate supersession relationships are shown without full lifecycle context;
• part image information is dropped before the model can use it;
• authentication and API failures can look like empty catalog results;
• different deployment paths expose different tool sets;
• host instructions can encourage conflicting clarification behavior;
• there is no uniform live baseline covering the API, tools, and final agent answer.

3. Goals

3.1 Functional goals

1. Complete the four core customer journeys:
   • vehicle to verified parts;
   • exact part-plus-vehicle fitment;
   • exact part to cross-reference;
   • exact part to lifecycle and supersession.
2. Add VIN-to-parts when entitlement is confirmed.
3. Return verified part imagery when the asset contract is confirmed.
4. Preserve every catalog field needed to explain why a result is valid.
5. Distinguish complete zero, partial results, invalid input, not entitled, and service unavailable.
6. Prevent unsupported part numbers and fitment claims from reaching the final answer.
7. Make the approved evaluation set a release requirement.

3.2 Business goals

• Demonstrate value from the existing investment rather than fund a rewrite.
• Give executives a clear readiness view by customer journey.
• Give engineering a buildable sequence and acceptance criteria.
• Give catalog/API owners a repeatable method to separate code loss, data absence, entitlement, and ground-truth drift.
• Keep the architecture portable across host agents and optional demo interfaces.

4. Non-goals

• Replacing the OptiCat catalog or repairing upstream data.
• Building a partner-management platform.
• Production security certification, penetration testing, or SLA operations.
• Using prompt wording as the sole accuracy control.
• Moving the core service to Vercel or Supabase without a functional reason.
• Supporting every possible catalog question in the first demonstration build.
• Returning remembered automotive knowledge when the catalog evidence is insufficient.

5. Users

Counter or support user

Needs a correct answer quickly and should not be expected to know brand codes, base-vehicle IDs, or API terminology.

Catalog specialist

Needs to see the exact identity, fitment conditions, lifecycle, and relationship type behind the answer.

Product or demonstration owner

Needs predictable supported journeys, clear fallback behavior, and evidence that the system does not invent catalog facts.

Engineering and platform team

Needs stable contracts, one deployed tool surface, testable error states, safe secret handling, and reproducible releases.

API/data owner

Needs test evidence that separates missing data from code loss, key scope, or an incorrect expected answer.

6. Core customer journeys

6.1 Vehicle to parts

User intent

“Show me brake pads for my 2018 Canyon.”

Required behavior

1. Resolve year, make, model, and base vehicle.
2. Retrieve vehicle-specific attributes that materially change fitment.
3. Ask one focused question if a missing engine, side, position, or configuration changes the result.
4. Search the catalog with the resolved vehicle and part type.
5. Retrieve required pages or mark the result incomplete.
6. Return parts with the conditions and evidence that apply to each part.

Acceptance

• No part is presented as fitting unless the matching application evidence supports it.
• Every truncated result discloses total, returned, and continuation status.
• Engine, side, position, quantity, and notes remain attached when the API supplies them.
• An unavailable or unauthorized API response is never presented as “no parts found.”

6.2 Exact fitment verification

User intent

“Does Denso 210-1084 fit my 2015 Tacoma 2.7L?”

Required behavior

1. Resolve the exact brand and part number.
2. Resolve the exact vehicle configuration.
3. Query applications and compare all decision-making qualifiers.
4. Return yes, no, conditional, or unverified.

Acceptance

• yes requires exact application evidence.
• conditional names the unresolved or differing condition.
• no requires complete evidence, not absence from a partial page.
• unverified explains whether the cause is missing entitlement, unavailable API, ambiguous identity, or insufficient catalog evidence.

6.3 Cross-reference and interchange

User intent

“I have Ford OE D3PZ 17543 C. What is the Gates equivalent?”

Required behavior

1. Normalize punctuation and part-number formatting without changing identity.
2. Find all plausible part identities.
3. Ask for brand or part type when multiple identities remain.
4. Read interchanges only for the resolved part.
5. Preserve brand, part number, relationship type, direction, and notes.
6. Verify fitment separately when the user asks whether an interchange fits a vehicle.

Acceptance

• A reused part number never silently selects the first product category.
• Interchange is never labeled as supersession or fitment.
• Target-brand filtering occurs after identity resolution.
• The answer distinguishes OE, aftermarket, equivalent, and other relationship types when supplied.

6.4 Supersession and lifecycle

User intent

“My manual lists AC Delco 41-962. Is there a current replacement?”

Required behavior

1. Resolve the exact part.
2. Return lifecycle status when available.
3. Follow replaces and replaced by relationships to a bounded depth.
4. Detect cycles and repeated nodes.
5. Keep cross-reference relationships separate.

Acceptance

• The current part is identified when the chain is complete.
• The answer states when only one step is available.
• Discontinued, superseded, current, and unknown remain distinct.
• The chain is capped and cycle-safe.

6.5 VIN to requested task

User intent

“Find wiper blades for this VIN.”

Required behavior

1. Validate VIN format before the API call.
2. Call the documented VIN operation.
3. Distinguish invalid VIN, not entitled, no decode, multiple matches, and service unavailable.
4. Resolve the returned vehicle and available configuration.
5. Continue into the requested part lookup.

Acceptance

• VIN status is accurate and entitlement-aware.
• A successful decode continues to the customer’s requested task.
• The system does not promise engine/trim precision unless those fields are returned and verified.

6.6 Part details and imagery

User intent

“Show me the product details and image for this part.”

Required behavior

1. Resolve exact part identity.
2. Return descriptions, attributes, units, lifecycle, country information, and relationships selected for the product contract.
3. Return associated part-image metadata or usable URLs.
4. State access/lifetime behavior for asset URLs.

Acceptance

• The image belongs to the resolved part.
• The user never needs to supply or invent an internal asset ID.
• Missing imagery is reported as missing imagery, not a failed part lookup.

7. Functional response contract

Every data tool should return a complete result record plus optional readable text.

{
  "request": {
    "normalized": {},
    "unresolved_questions": []
  },
  "status": "complete | partial | invalid | not_entitled | unavailable",
  "completeness": {
    "total": 0,
    "returned": 0,
    "truncated": false,
    "next_cursor": null
  },
  "results": [
    {
      "part": {},
      "fitment": {},
      "relationships": [],
      "attributes": [],
      "assets": [],
      "evidence": []
    }
  ],
  "warnings": [],
  "error": null
}

Contract rules

• returned < total requires truncated=true and a continuation or explicit non-pageable reason.
• A fitment claim requires exact part and application evidence.
• Unknown units remain unknown; they are not omitted or inferred.
• Every relationship has a type and direction.
• Every asset attaches to the resolved part or vehicle.
• Authentication, entitlement, rate limit, timeout, and upstream failure are typed errors.
• A caught error cannot be serialized as an ordinary successful catalog answer.

8. Clarification and answer policy

Retrieve first

Use the catalog to determine whether a question is actually needed.

Ask one material question

Ask only when one missing answer changes identity, fitment, or the requested relationship.

Group when useful

If several valid options can be labeled accurately—for example front/rear or driver/passenger—show the groups instead of blocking discovery.

Do not ask when the request is complete

An exact part, vehicle, and engine request should be verified directly.

Abstain honestly

When the API is unavailable, the key is not entitled, the identity is unresolved, or evidence is incomplete, state that limitation and do not supply a remembered part number.

9. Final-answer verification

Before the answer reaches the user:

1. Extract every part number, fitment statement, attribute, and relationship claim.
2. Match each claim to an evidence record returned for the current request.
3. Reject or revise unsupported claims.
4. Convert incomplete evidence into qualified language or clarification.
5. Preserve evidence identifiers and completeness status for the transcript.

Tool-level verification and host-level final-answer verification are both required. The MCP service prevents unsupported data from appearing in tool results; the host check prevents the model from adding unsupported claims afterward.

10. API and access requirements

Current public operations

The current public service description lists nine operations: combined search, version, part details, AutoCare search, brand update dates, vehicle assets, vehicle results, VIN, and part applications.

The detailed manual confirms that Search Results is the general filtering/paging workhorse, Part Applications is the source of application-level ACES fitment, Part Details is the source of complete PIES product data and part image URLs, and Vehicle Assets is a separate base-vehicle asset flow. The current public WSDL adds VIN to the documented operation surface even though the manual’s overview predates that addition.

Key requirements

• Authenticate with X-Api-Key.
• Keep the key out of URLs even though the manual also supports an api_key query parameter and Basic Auth username.
• Use a rotated development key provided through a secret manager or approved secure channel.
• Record a non-secret key-scope identifier.
• Obtain written brands, datasets, VIN, paging, and rate-limit entitlement.
• Validate access with the version operation before catalog cases.
• Inspect body-level statuses even when HTTP returns 200.
• Treat nextCursorMark/cursorMark as entitlement-dependent deep paging and fall back to explicit partial-result status when it is not enabled.
• Never print, log, commit, or include the raw key in command arguments or generated artifacts.

Access readiness checklist

• running prototype endpoint and connection method;
• deployed repository revision;
• deployed model, prompt, settings, and tool bindings;
• rotated key and entitlement statement;
• current API documentation and rate limits;
• approved read-only test budget;
• canonical QA set and expected outcomes;
• named OptiCat API/catalog adjudicator.

11. Evaluation plan

Test sources

1. The 18 populated workbook examples define intended business journeys.
2. The 50 historical cases define the main regression and failure corpus.
3. Deterministic fixtures prove request, serialization, pagination, error, and qualifier behavior.
4. Additional contract tests cover zero, partial, unavailable, not-entitled, and ambiguous cases.

Three-layer replay

Run every approved case at three layers:

1. Raw API: determine what the key and catalog actually return.
2. MCP tool: determine whether the service preserves the required information.
3. Full agent: determine whether the final answer remains grounded, complete, and appropriately clarified.

Required run metadata

• repository and deployed revision;
• host/model configuration version;
• tool manifest version;
• non-secret key-scope identifier;
• API documentation/version reference;
• request and response timestamps;
• raw redacted request/response;
• final answer and tool trace;
• human grade and adjudicator;
• failure layer and reason.

Grading

• grounded correct;
• grounded incomplete;
• correctly clarified;
• correctly abstained;
• unsupported positive;
• false negative;
• qualifier error;
• relationship error;
• contradiction;
• infrastructure failure;
• data/entitlement unresolved.

12. Success metrics

13. Implementation workstreams

M0. Safe access and reproducible baseline

• rotate exposed credentials;
• freeze the deployed context;
• confirm entitlement and rate limits;
• reconcile workbook and 50-case expectations;
• run API/tool/agent baseline;
• adjudicate data-versus-code disagreements.

M1. Result and API foundation

• structured response contract;
• paging and completeness;
• shared client and time budget;
• body-status classification;
• health and entitlement readiness;
• safe logging and correlation.

M2. Part identity and relationships

• exact part resolver;
• ambiguity responses;
• cross-reference relationship types;
• lifecycle status and bounded supersession;
• task-shaped tools that hide internal identifiers.

M3. Vehicle, fitment, details, images, and VIN

• vehicle configuration resolution;
• row-level qualifiers and notes;
• exact fitment verification;
• complete selected product fields;
• verified part assets;
• entitlement-aware VIN-to-task flow.

M4. Host answer behavior

• one clarification/abstention policy;
• evidence-only tool descriptions;
• final-answer verification;
• concise customer response assembly;
• transcript and evidence retention.

M5. Release and demonstration readiness

• one deployed tool manifest;
• dependency pinning or MCP v2 migration;
• full test replay and regression gate;
• performance and failure testing;
• security cleanup verification;
• demonstration script and fallback plan;
• technical handoff.

14. Deployment and platform decisions

Core recommendation

Keep the MCP service in Python and keep the OptiCat API adapter platform-neutral. Select one supported remote MCP deployment and generate its tool manifest from the canonical registry.

MCP SDK

The source uses the v1 FastMCP API while current unbounded requirements can install MCP v2. Choose one explicit path:

1. Pin a supported v1 release as a short-term demonstration stabilization step; or
2. Migrate deliberately to MCP v2 with protocol, transport, serialization, and registry tests.

Do not allow an unbounded upgrade to choose the migration implicitly.

Vercel option

Use Vercel only for a demo interface or stakeholder dashboard if it accelerates presentation and sharing. It should call the same versioned MCP/service contract.

The current proof includes a platform-neutral natural-language planner at discovery/poc/opticat_query_planner.py. It classifies the five supplied journey types, shows the ordered API plan, exposes unresolved information, validates body-level access errors, and can run a limited read-only evidence probe when a rotated key is supplied through the server environment. A Vercel implementation should wrap this logic in an authenticated, rate-limited server route; it must not move the key or raw catalog payloads into the browser.

Supabase option

Use Supabase only if durable evaluation records, redacted transcripts, judgments, or KPI history are needed. It should not become the source of automotive catalog truth.

Decision rule

Platform choices must improve a named customer journey, evaluation need, or operational requirement. They should not be introduced to solve accuracy problems that belong in the service contract.

15. Security, governance, and observability

Required before live testing

• revoke/rotate exposed or tracked credentials;
• remove secret values from documentation and failure messages;
• use approved secret injection;
• scan repository and generated artifacts for secrets;
• obtain explicit read-only testing authorization and call budget.

Required for demonstration readiness

• request/correlation ID;
• tool and upstream operation count;
• latency and retry count;
• returned, total, and truncated fields;
• error class and entitlement state;
• evidence coverage for answer claims;
• redacted test transcripts;
• approved model/prompt/tool configuration version.

AI governance rule

The system must be measured on unsupported claims, not only whether an answer sounds useful. A fluent answer without catalog evidence is a failed result.

16. SOW traceability

17. Dependencies

• safe development credential and written entitlement;
• running prototype and deployed host export;
• named catalog/API adjudicator;
• approved test traffic and rate limits;
• agreed canonical cases and expected outcomes;
• decision on core demonstration journeys;
• decision on VIN and imagery scope;
• decision on deployed runtime and MCP SDK path;
• commercial approval for Phase 2 scope, staffing, and price.

18. Risks

19. Open decisions

1. Which four journeys are mandatory for the first demonstration?
2. Are VIN-to-parts and part imagery mandatory or conditional?
3. Which deployment runtime becomes canonical?
4. Is short-term MCP v1 pinning acceptable, or is v2 migration required immediately?
5. Which fitment qualifiers are mandatory by part category?
6. What paging depth or result limit is acceptable for the demonstration?
7. Which relationship types does OptiCat consider authoritative interchange versus supersession?
8. What evidence may be shown to customers versus retained only for audit?
9. Will a Vercel demo interface or Supabase evaluation store materially improve the approved scope?
10. Who can approve the fixed scope, staffing, pricing, and acceptance criteria?

20. Definition of done

The functional reliability upgrade is complete when:

• the approved customer journeys complete end to end;
• all required access and entitlement states are observable;
• every catalog claim is verified against current request evidence;
• incomplete and unavailable outcomes remain honest;
• the approved test set passes the agreed safety and accuracy gates;
• the deployed tool surface and host policy match the versioned release;
• secrets are managed safely;
• OptiCat product, catalog, engineering, and demonstration owners accept the run evidence.