OptiCat MCP AtlasContract · flow · evidence · ideas
System atlasVehicle discoverydecode_vin_and_search
Vehicle discovery · vin_decode

VIN decode to optional part search

Validate and decode a VIN, preserve every returned configuration detail, require selection when several vehicles resolve, and optionally bridge into the same bounded part taxonomy/search path.

Run the example Inspect contract
Visual model · bridge

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.

decode_vin_and_searchArgumentsGenerated JSON Schema
read only
interactionInteractionContext | nulloptional
default null
requestVinSearchInputrequired
attribute_filtersAttributeFilter[]optional
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
brandsstring[]optional

Optional catalog brand names or codes

cursor_markstring | nulloptional
default null
max_resultsintegeroptional
default 200min 1max 500
pageinteger | nulloptional
default null
part_typestring | nulloptional
default null
qualifier_filtersobjectoptional
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
vinstringrequired
min length 17max length 17
Example MCP argumentsMatches the existing demo handoff
{
  "request": {
    "vin": "4T1BK1EB5GU235558",
    "part_type": "Cabin Air Filter",
    "max_results": 50
  }
}
hvac filter for VIN 4T1BK1EB5GU235558
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
getAutoCareVehiclesByVINDecode a locally validated 17-character VIN.
Requires
VIN
Produces
base vehicles · region · configuration details
Validation
I/O/Q and length are checked locally; entitlement/unavailable/not-found remain separate outcomes.
02
getAutoCareSearchResultsResolve an optional readable part type in vehicle scope.
Only when part_type is supplied
Requires
decoded baseVehicleId · part_type
Produces
partTypeId · taxonomy choices
Validation
Ambiguity pauses the continuation instead of guessing.
03
getAutoCareSearchResultsRetrieve paged parts for the selected decoded vehicle.
Only after one vehicle and one part type resolve
Requires
baseVehicleId · partTypeId
Produces
parts · fitments · completeness
Validation
No-linkage flags and truncated results remain visible.
Decision logic

Every important branch has a named outcome.

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

VIN syntax failsinvalid_input

No upstream call occurs.

Several base vehicles resolveclarification_required

Return each baseVehicleId and preserve decode metadata.

One vehicle; no part typecomplete

Return the decoded identity only.

Part type suppliedcontinue to bounded search

Taxonomy ambiguity can still pause the flow.

Part results truncatepartial

The VIN does not grant permission to overstate completeness.

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 controls2 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.
Observability2 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
decoded vehiclebaseVehicleIdregionVIN configuration metadatapart-type choicespart candidatescompleteness
Grounding guaranteesRules against invented certainty
  • Invalid syntax is distinct from entitlement failure
  • Multiple decoded vehicles require selection
  • VIN storage is masked
  • Unreturned engine/trim data is never promised
Implementation sourcesSymbols behind the visual
Handlerdecode_vin_and_searchpoc/opticat-mcp-v2/src/opticat_mcp_v2/service.py
VIN normalizernormalize_vin_vehiclepoc/opticat-mcp-v2/src/opticat_mcp_v2/normalizers.py
Persistence redactionredactOperationalDatalib/safe-details.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

    There is no post-decode exact engine/submodel selection

  2. 02

    The optional part continuation does not yet use the full material-qualifier gate

Next
Configuration fingerprint

Turn decoded engine, body, drive, and region evidence into a visible completeness profile.

Product concept · not implemented
Explore
Saved vehicle workspace

Reuse a verified VIN-derived identity across searches without repeatedly exposing the VIN.

Product concept · not implemented