API manual reconciliation

Purpose

Reconcile the current OptiCat OnLine Web Services Manual, the live public WSDL, the supplied use-case workbook, and the MCP repository into one implementation reference.

Sources:

• Google Doc: OptiCat OnLine Web Services Manual, marked updated 2024-07-09.
• Public WSDL: https://webservice.opticatonline.com/autocare/v1/services/Catalog.soapEndpoint?doc.
• JSON endpoint: https://webservice.opticatonline.com/autocare/v1/services/Catalog.jsonEndpoint.
• Hosted tester: https://webservice.opticatonline.com/autocare/v1/tester.html.
• Repository source: src/opticat_mcp/server.py at commit 3da43bf.
• Supplied workbook: OptiCat MCP Planning 202512.xlsx.

How OptiCat documents the service

The hosted tester is the fastest raw-API verification surface:

1. Obtain a development key from OptiCat through a secure channel.
2. Open the tester.
3. Enter the key and paste one wrapped JSON operation.
4. Submit and retain the raw response.
5. Compare the raw response with the MCP tool output and final agent answer.
6. For a disputed case, retain the call, response, and expected difference.

Authentication options documented by OptiCat:

• X-Api-Key request header;
• api_key query parameter; or
• Basic Auth username with a blank password.

The MCP’s X-Api-Key header is the preferred option because it does not place the credential in the URL. A key can restrict the returned catalog to specific brands; written entitlement is therefore part of test metadata, not an administrative detail.

Current operation surface

The manual’s main operation overview predates VIN, while the current public WSDL lists it. Use the live WSDL as the current operation registry and the manual as the detailed request/response reference.

Data contracts that matter to accuracy

Vehicle resolution

getAutoCareVehicleResults provides the facet IDs needed to resolve years, makes, models, base vehicles, regions, vehicle types, and additional vehicle attributes. The current MCP returns some readable facet names but often drops the IDs needed for a refined follow-up query.

Part search and paging

getAutoCareSearchResults supports combinations of baseVehicleId, region, part type IDs, brand codes, categories, and ACES attribute ID/value filters. It can return:

• total and maxAllowedPage;
• part and hierarchy facets;
• optional full PIES items with includeParts;
• optional part fitments;
• ACES attribute filters; and
• deep paging through nextCursorMark/cursorMark when the key is enabled.

The current MCP requests up to 20 parts, prints 10, and does not expose page/cursor/completeness state. That is a serialization defect even when deep paging is not entitled.

Exact fitment

getAutoCarePartApplications returns ACES rows for an exact brand and part number. Documented fields include baseVehicleId/name, part type, quantity, notes, and application attributes such as position with both IDs and readable names. The current get_part_applications formatter drops notes and attributes; check_part_fitment_for_vehicle treats any base-vehicle application as FITS without comparing all decision-making attributes.

Exact product and images

getAutoCarePartDetails returns the same PIES item structure used by Search Results, including descriptions, extended information such as lifecycle/country, attributes, relationships, and digital assets/image URLs. The current formatter selects a small subset and drops the image path and lifecycle fields.

getAutoCareVehicleAssets is a separate base-vehicle ACES asset flow. It should not be described as the part-image API.

Key scope and errors

OptiCat documents that API keys can be issued with different brand filters. The public JSON endpoint may return a body-level status such as 401 while the HTTP response is 200. The shared client must therefore classify the JSON body before a tool interprets an empty array as “no results.”

Accurate current flow

User question
  -> host agent selects one of 16 MCP tools
  -> tool function builds one or more wrapped OptiCat operations
  -> shared client POSTs JSON with X-Api-Key
  -> OptiCat returns structured ACES/PIES/facets/paging/assets/status
  -> tool-specific formatter reduces the response to prose and limited rows
  -> host agent assembles the final answer

The implementation contains both task-shaped tools (search_parts_by_vehicle, check_part_fitment_for_vehicle) and endpoint-shaped tools. The principal loss occurs between the structured OptiCat response and model-visible output.

Recommended flow

User question
  -> task router
  -> exact vehicle/part identity resolver
  -> entitlement-aware OptiCat adapter
  -> paging and field-preserving normalizer
  -> fitment/relationship/completeness verification gate
  -> structured evidence response
  -> host final-answer verification
  -> grounded answer, clarification, qualification, or abstention

Live proof sequence

1. Rotate the exposed key and install the replacement as a server-only secret.
2. Call getAutoCareVersion and classify body status.
3. Record the non-secret key scope: brands, VIN, paging, rate limits, and TecDoc if any.
4. Run a raw API request from each workbook journey.
5. Run the corresponding MCP tool.
6. Run the full host agent.
7. Compare raw API, MCP output, and final answer field by field.
8. Grade accuracy, completeness, clarification, abstention, latency, and evidence coverage.

No credential should be committed to GitHub, passed in a URL, embedded in client code, or included in generated evidence.