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
interactionInteractionContext | nulloptional
default null
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.

include_maximumbooleanoptional
default true
include_minimumbooleanoptional
default true
maximumnumber | nulloptional
default null
minimumnumber | nulloptional
default null
namestringrequired

Catalog attribute name, resolved through PAdb evidence

min length 1max length 120
operatoreq | approx | range | gt | gte | lt | lteoptional
default "approx"7 allowed values
source_textstring | nulloptional

Original customer wording; not catalog evidence

default null
tolerancenumber | nulloptional

Relative tolerance for approximate equality only; default 0.01, disclosed in the result

default null
unitstring | nulloptional
default null
valuestring | number | integer | nulloptional
default null
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
makestring | nulloptional

Vehicle make explicitly supplied by the customer. May be omitted when year and model are known.

default null
make_hintstring | nulloptional

Optional non-authoritative make recommendation from the calling AI. The MCP validates it against OptiCat before use and falls back to catalog vehicle resolution when it does not match.

default null
max_resultsintegeroptional

Bounded records to retrieve across pages before comparing application qualifiers. Remaining results expose continuation.

default 200min 1max 500
modelstring | nulloptional

Vehicle model explicitly supplied by the customer.

default null
model_hintstring | nulloptional

Optional non-authoritative model recommendation; validated with make/year/submodel before use.

default null
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. Unique catalog facet values are applied as typed upstream filters; unresolved values use conservative application-row validation.

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
submodelstring | nulloptional

Customer-supplied trim, badge, or VCdb submodel, such as King Ranch or Denali.

default null
yearintegerrequired
min 1886max 2100
year_abbreviatedbooleanoptional
default false
Example MCP argumentsMatches the existing demo handoff
{
  "request": {
    "year": 1997,
    "make": null,
    "make_hint": "Ford",
    "model": "Mustang",
    "part_type": "Disc Brake Pad Set",
    "qualifiers": [],
    "max_results": 50
  }
}
brake pads for a 97 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
getAutoCareVehicleResultsValidate an explicit make or advisory AI make hint for the year.
Requires
year · optional make or make_hint
Produces
makeId · makeName · facet completeness
Validation
Hints are recommendations only; they must resolve in the catalog before use.
02
getAutoCareVehicleResultsResolve the model to one base vehicle, across makes when necessary.
Requires
year · model · optional makeId
Produces
baseVehicleId · makeName · modelName · region
Validation
Exactly one complete catalog 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
next_pageinteger | nulloptional
default null
pages_fetchedintegeroptional
default 0
paging_modenone | page | cursor | capped | unknownoptional
default "none"5 allowed values
returnedintegeroptional
default 0
source_end_reachedbooleanoptional

This response reached the known end of the source query, even when earlier pages were returned separately.

default false
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
  • AI make hints are catalog-validated
  • No first-match identity selection
  • Incomplete model facets ask for the make
  • 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