OptiCat MCP AtlasContract · flow · evidence · ideas
System atlasPart relationshipslookup_part_interchanges
Part relationships · cross_reference

Cross-reference validation gates

Return only explicit PIES interchange relationships and validate a bounded candidate set through identity, category, product evidence, and vehicle-verification boundaries.

Run the example Inspect contract
Visual model · gates

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.

lookup_part_interchangesArgumentsGenerated JSON Schema
read only
requestInterchangeLookupInputrequired
brandstring | nulloptional
default null
max_validationsintegeroptional
default 10min 0max 25
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
target_brandstring | nulloptional

Optional target brand name or code used to filter returned interchange relationships

default null
target_brandsstring[]optional

Optional target brand names or codes; combined with target_brand and deduplicated

validate_candidatesbooleanoptional

Retrieve candidate details and validate category/specification evidence for a bounded result set

default true
Example MCP argumentsMatches the existing demo handoff
{
  "request": {
    "part_number": "EUR1924",
    "brand": "Akebono",
    "validate_candidates": true,
    "max_validations": 10
  }
}
Show interchanges for Akebono EUR1924
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 direct source or recover explicit reverse references.
Requires
part_number · optional brand/type
Produces
source identity · reverse relationships · decoy categories
Validation
Similar digits are irrelevant; only exact product or explicit returned relationship evidence proceeds.
02
getAutoCarePartDetailsRead typed source relationships and product context.
Requires
resolved brandCode · partNumber
Produces
INTERCHANGE relationships · attributes · part type · assets
Validation
Supersession kinds are excluded and target-brand filtering uses returned identities.
03
getAutoCarePartDetailsValidate a bounded candidate set with target details.
When candidate validation is enabled
Requires
candidate identities · max_validations
Produces
category agreement · unit-aware comparisons · missing checks
Validation
Category conflicts reject; missing product or application checks remain conditional.
Decision logic

Every important branch has a named outcome.

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

Explicit relationship + category agreementcatalog_confirmed

Still names vehicle application as a missing installation check.

Product evidence is incomplete or conflictsconditional

Return matching, conflicting, and missing checks.

Categories conflictrejected

The relationship is visible but must not be recommended.

Candidate exceeds validation capunvalidated relationship

Enumerate it in metadata rather than implying validation.

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 evidence4 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
source identitytarget identitiestyped relationshipcategory matchattribute comparisonmissing checksunvalidated remainder
Grounding guaranteesRules against invented certainty
  • Interchange is not supersession
  • Interchange is not vehicle fitment
  • Wrong-category exact matches are disclosed
  • Validation caps remain visible
Implementation sourcesSymbols behind the visual
Handlerlookup_part_interchangespoc/opticat-mcp-v2/src/opticat_mcp_v2/service.py
Validation_validate_interchangespoc/opticat-mcp-v2/src/opticat_mcp_v2/service.py
Design standardfive validation gatesdiscovery/product/interchange-validation-design.md
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 repaired reverse Kia path needs live validation

  2. 02

    OE versus aftermarket ranking has only an initial heuristic

  3. 03

    Vehicle application is not automatically checked for every candidate

Next
Evidence comparison

Place source and candidate attributes, lifecycle, and missing checks side by side.

Product concept · not implemented
Explore
Vehicle-qualified cross-reference

Continue selected candidates through fitment verification for a supplied vehicle.

Product concept · not implemented