OptiCat MCP AtlasContract · flow · evidence · ideas
System atlasFitment evidenceverify_part_fitment
Fitment evidence · part_fitment with year, make, and model

Exact part and vehicle decision

Resolve the part and vehicle independently, retrieve filtered ACES applications, and return yes, no, conditional, or unverified without guessing through qualifier gaps.

Run the example Inspect contract
Visual model · decision

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.

verify_part_fitmentArgumentsGenerated JSON Schema
read only
requestFitmentCheckInputrequired
base_vehicle_idinteger | nulloptional
default null
base_vehicle_region_idinteger | nulloptional
default null
brandstring | nulloptional
default null
makestringrequired
min length 1
modelstringrequired
min length 1
part_numberstringrequired
min length 1
part_typestring | nulloptional

Optional readable part-type hint (e.g. 'Engine Oil Filter'). Used to prefer the intended category when a part number exists in multiple unrelated categories; best effort, never erases evidence.

default null
part_type_idinteger | nulloptional
default null
qualifiersobjectoptional
yearintegerrequired
min 1886max 2100
Example MCP argumentsMatches the existing demo handoff
{
  "request": {
    "part_number": "730-0003",
    "brand": "GMB",
    "year": 2013,
    "make": "Chevrolet",
    "model": "Impala",
    "qualifiers": {}
  }
}
Does GMB 730-0003 fit a 2013 Chevrolet Impala?
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
getAutoCareSearchResultsResolve the exact part identity and optional readable part type.
Requires
part_number · brand · optional part type
Produces
brandCode · partTypeId · identity choices
Validation
Whole-token product-line matching prevents GM→GMB while allowing GMB→GMB North America.
02
getAutoCareVehicleResultsResolve make and model to one baseVehicleId.
Requires
year · make · model
Produces
makeId · baseVehicleId
Validation
Caller-provided IDs are later cross-checked against returned application identity.
03
getAutoCarePartApplicationsRetrieve applications filtered to the resolved base vehicle.
Requires
brandCode · partNumber · baseVehicleId
Produces
matching rows · qualifiers · paging state
Validation
The decision engine canonicalizes keys/values and requires completeness before no.
04
getAutoCarePartDetailsEnrich a completed fitment decision with product details.
Best-effort enrichment
Requires
resolved product
Produces
attributes · assets · lifecycle
Validation
An enrichment failure adds a warning and never erases the fitment decision.
Decision logic

Every important branch has a named outcome.

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

Matching row; no unresolved material qualifieryes

Exact application evidence supports the requested configuration.

Complete rows conflict with supplied qualifiersno

Name every blocking qualifier and the values the catalog records.

Material qualifier remains or cannot be evaluatedconditional

List unresolved or unevaluated qualifier families.

The relevant application set is incompleteunverified

A definitive no is forbidden.

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 + completeness2 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 evidence3 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 controls1 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
fitment statusexplanationmatching rowsunresolved qualifiersblocking qualifiersunevaluated qualifiersproduct enrichment
Grounding guaranteesRules against invented certainty
  • Part and vehicle resolve independently
  • Unknown qualifier types default to material
  • No definitive no on truncated evidence
  • Detail enrichment cannot overwrite the decision
Implementation sourcesSymbols behind the visual
Handlerverify_part_fitmentpoc/opticat-mcp-v2/src/opticat_mcp_v2/service.py
Decision engine_fitment_decisionpoc/opticat-mcp-v2/src/opticat_mcp_v2/service.py
Web qualifiersfitmentQualifierslib/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

    The material/informational qualifier table still needs domain sign-off

  2. 02

    The repaired GMB path needs a current live retest

Next
Decision explainer

Let users inspect exactly which requested and catalog qualifier values drove the state.

Product concept · not implemented
Explore
Batch fitment verification

Verify a parts list against one saved vehicle while retaining an independent decision per product.

Product concept · not implemented