OptiCat MCP AtlasContract · flow · evidence · ideas
System atlasVehicle discoverysearch_parts_for_vehicle
Vehicle discovery · vehicle_to_part

Vehicle to verified part candidates

Resolve readable vehicle and part-type language to catalog identities, apply optional brand and attribute constraints, and return paged candidates without hiding fitment qualifiers.

Run the example Inspect contract
Visual model · funnel

Follow the implementation from request to evidence.

Every node corresponds to a real resolver, operation, validation boundary, or response surface in the current code.

Registered input contract

The exact arguments the MCP server accepts.

This schema is generated from the registered Python tool. Required fields, defaults, nested models, and constraints are not maintained by hand.

search_parts_for_vehicleArgumentsGenerated JSON Schema
read only
requestVehicleSearchInputrequired
attribute_filtersAttributeFilter[]optional

Filter returned parts by PIES product attributes (unit-aware, applied in-process over the retrieved result set). Parts with no attribute data are excluded and disclosed in metadata.attribute_filter_report, never returned as exact matches.

namestringrequired

PAdb attribute name, e.g. 'Height'

min length 1
tolerancenumber | nulloptional

Optional relative tolerance override for numeric comparison (default 0.01)

default null
unitstring | nulloptional

Unit of the supplied value, e.g. 'mm' or 'in'

default null
valuestring | number | integerrequired

Required value; numeric values compare unit-aware

base_vehicle_idinteger | nulloptional
default null
base_vehicle_region_idinteger | nulloptional
default null
brandstring | nulloptional

Optional catalog brand name or code

default null
brandsstring[]optional

Optional brand names or codes. Matching brands are resolved against the vehicle-filtered brand facet and passed upstream as brandCodes; a requested brand absent from the facet returns a grounded not_found naming the brands that do exist.

cursor_markstring | nulloptional
default null
makestringrequired
min length 1
max_resultsintegeroptional
default 50min 1max 500
modelstringrequired
min length 1
pageinteger | nulloptional
default null
part_typestringrequired
min length 1
qualifier_filtersobjectoptional

Natural qualifier names and values extracted from the request, such as Engine Base=2.0L or Drive Type=AWD. These filter returned ACES rows using the same synonym-safe comparison as exact fitment verification.

qualifiersQualifierSelection[]optional
typestringrequired

ACES attribute type name or API type token, such as EngineBaseId or PositionId

value_idinteger | stringrequired

ACES attribute value ID returned by a prior clarification

value_namestring | nulloptional

Optional readable label retained for answer assembly

default null
yearintegerrequired
min 1886max 2100
Example MCP argumentsMatches the existing demo handoff
{
  "request": {
    "year": 1997,
    "make": "Ford",
    "model": "Mustang",
    "part_type": "Disc Brake Pad Set",
    "qualifiers": [],
    "max_results": 50
  }
}
brake pads for a 1997 Ford Mustang
Operation sequence

What each upstream call needs—and earns.

Conditional calls are labeled. Validation describes the exact rule that allows evidence to advance to the next stage.

01
getAutoCareVehicleResultsPage make facets and resolve the requested make for the year.
Requires
year · make
Produces
makeId · makeName · facet completeness
Validation
Exact/contained normalized ranking; ambiguity is returned, never auto-selected.
02
getAutoCareVehicleResultsPage base-vehicle facets for the resolved make.
Requires
year · makeId · model
Produces
baseVehicleId · modelName · region
Validation
Exactly one base identity must resolve or the user receives choices.
03
getAutoCareSearchResultsResolve the readable part type from paged facets with fuzzy suggestions.
Requires
part_type · vehicle scope
Produces
partTypeId · partTypeName · did_you_mean
Validation
Exact, contained, then bounded fuzzy ranking; ambiguous taxonomy pauses the search.
04
getAutoCareSearchResultsResolve requested brands against the vehicle/type brand facet.
Only when brand filters are supplied
Requires
baseVehicleId · partTypeId · optional brands
Produces
brandCodes · available_brands
Validation
A missing requested brand can become a grounded negative only from the scoped facet.
05
getAutoCareSearchResultsRetrieve parts, per-part fitments, paging state, and ACES qualifier facets.
Requires
baseVehicleId · partTypeId · optional brandCodes/qualifiers
Produces
parts · fitments · total · continuation · qualifier facets
Validation
Truncation, no-linkage flags, open qualifiers, and in-process attribute-filter limits stay visible.
Decision logic

Every important branch has a named outcome.

These are response decisions in the implemented service—not possible future behavior.

Vehicle or part type is ambiguousclarification_required

Return typed catalog choices instead of choosing the first match.

Material ACES dimensions remainclarification_required

Candidates are visible but cannot be promoted to verified fitment.

More results existpartial

Expose total, returned, paging mode, cursor, and a no-negative warning.

Complete result set is emptynot_found

A negative is permitted only after the scoped search is complete.

Records returned without open qualifierscomplete

Return grounded candidates and per-part evidence.

Response anatomy

One shared schema, highlighted for this tool.

Bright fields are populated by this path. Dimmed fields remain part of CatalogResponse but are not a normal output of this tool.

Outcome2 active
statusResultStatusrequired
No nested fields. This value uses the type shown above.
summarystringrequired
No nested fields. This value uses the type shown above.
reason_codeReasonCode | null
No nested fields. This value uses the type shown above.
Context + completeness3 active
queryobject
No nested fields. This value uses the type shown above.
metadataobject
No nested fields. This value uses the type shown above.
completenessCompleteness
next_cursorstring | nulloptional
default null
pages_fetchedintegeroptional
default 0
paging_modenone | page | cursor | capped | unknownoptional
default "none"5 allowed values
returnedintegeroptional
default 0
totalinteger | nulloptional
default null
truncatedbooleanoptional
default false
Domain evidence2 active
vehiclesVehicleIdentity[]
No nested fields. This value uses the type shown above.
partsPartRecord[]
No nested fields. This value uses the type shown above.
relationshipsRelationshipRecord[]
No nested fields. This value uses the type shown above.
relationship_outcomeRelationshipOutcome | null
No nested fields. This value uses the type shown above.
fitmentFitmentDecision | null
No nested fields. This value uses the type shown above.
interchange_validationsInterchangeValidation[]
No nested fields. This value uses the type shown above.
Conversation controls3 active
clarificationClarification | null
No nested fields. This value uses the type shown above.
pending_clarificationsClarification[]

Every open clarification dimension in one round (clarification stays = the first). Ask them together instead of one round trip per dimension.

No nested fields. This value uses the type shown above.
warningsstring[]
No nested fields. This value uses the type shown above.
Observability1 active
errorCatalogError | null
No nested fields. This value uses the type shown above.
evidenceEvidenceRecord[]
No nested fields. This value uses the type shown above.
What reaches the answerPreserved output families
resolved vehiclepart identityfitment rowsavailable brandsattribute reportqualifier choicescompleteness
Grounding guaranteesRules against invented certainty
  • No first-match identity selection
  • All material clarification dimensions return together
  • Partial results cannot support brand-negative claims
  • No-linkage parts are explicitly disclosed
Implementation sourcesSymbols behind the visual
Handlersearch_parts_for_vehiclepoc/opticat-mcp-v2/src/opticat_mcp_v2/service.py
ResolversVehicleResolver / PartTypeResolverpoc/opticat-mcp-v2/src/opticat_mcp_v2/resolvers.py
Web mappingmcpToolForPlan · vehicle_to_partlib/mcp.ts
Boundaries and ideas

What is known, and what could become possible.

Current gaps stay separate from product concepts so the visual never implies that an idea has already shipped.

Known gapsVerified limitations in the current path
  1. 01

    Deep paging still depends on account entitlement

  2. 02

    The material qualifier gate uses facets from the final fetched page

  3. 03

    Vehicle-scoped brand aliases need broader live validation

Next
Configuration coverage map

Show which engine, trim, position, and drive combinations are covered before selection.

Product concept · not implemented
Explore
Complete-the-job bundles

Compose several verified part types into a service job while preserving evidence per item.

Product concept · not implemented