OptiCat MCP AtlasContract · flow · evidence · ideas
System atlasFitment evidenceget_part_fitments
Fitment evidence · part_fitment without a full vehicle

Part to vehicle applications

Resolve one exact catalog product and fan out its paged ACES application rows with vehicle identity, quantity, notes, and qualifiers intact.

Run the example Inspect contract
Visual model · fanout

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.

get_part_fitmentsArgumentsGenerated JSON Schema
read only
requestPartFitmentsInputrequired
brandstring | nulloptional
default null
cursor_markstring | nulloptional
default null
max_resultsintegeroptional
default 100min 1max 200
pageinteger | nulloptional
default null
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
Example MCP argumentsMatches the existing demo handoff
{
  "request": {
    "part_number": "9619",
    "brand": "Bosch",
    "max_results": 100
  }
}
What cars does Bosch 9619 fit?
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 brand, number, and optional part type to one exact catalog identity.
Requires
part_number · optional brand/part type
Produces
brandCode · part identity · reverse references · choices
Validation
Punctuation is normalized; bounded or ambiguous identity sets remain explicit.
02
getAutoCarePartApplicationsPage ACES applications for the resolved product.
Requires
brandCode · partNumber · optional continuation
Produces
vehicle rows · qualifiers · quantity · notes · total/paging
Validation
Every row retains configuration evidence; paging limits prevent all-vehicles claims.
Decision logic

Every important branch has a named outcome.

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

Identity is ambiguous or boundedclarification_required

Carry catalog IDs in the choices.

Number exists only as a referencepartial

Return referencing products and guidance, not fabricated applications.

Applications remain unfetchedpartial / paging_limited

The returned page is never described as all vehicles.

Complete set contains rowscomplete

Return the exact part with its fitment collection.

Complete set is emptynot_found

A negative is grounded only after completeness is established.

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 evidence1 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
exact part identityvehiclesapplication qualifiersquantitynotespaging state
Grounding guaranteesRules against invented certainty
  • Identity selection precedes applications
  • Reverse references are not direct products
  • A first page is never described as complete
Implementation sourcesSymbols behind the visual
Handlerget_part_fitmentspoc/opticat-mcp-v2/src/opticat_mcp_v2/service.py
Identity resolverPartResolver.resolvepoc/opticat-mcp-v2/src/opticat_mcp_v2/resolvers.py
Web mappingmcpToolForPlan · part_fitmentlib/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

    Account behavior for totals without continuation needs confirmation

  2. 02

    Vehicle assets are not enriched on demand

Next
Application heatmap

Visualize application density by year, model, engine, and position without flattening qualifiers.

Product concept · not implemented
Explore
Coverage compare

Compare the verified vehicle coverage of two exact catalog products.

Product concept · not implemented