OptiCat MCP AtlasContract · flow · evidence · ideas
System atlasPart relationshipslookup_part_supersession
Part relationships · supersession

Lifecycle and replacement lineage

Resolve a starting product and traverse only replaces/replaced-by evidence through a bounded, cycle-safe chain while keeping interchange fallbacks distinctly labeled.

Run the example Inspect contract
Visual model · chain

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_supersessionArgumentsGenerated JSON Schema
read only
max_hopsintegeroptional

Maximum replacement records to retrieve

default 10min 1max 10
requestPartLookupInputrequired
brandstring | 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": "19210284",
    "brand": "GM"
  },
  "max_hops": 10
}
What supersedes GM 19210284?
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 starting product or explicit reverse relationship evidence.
Requires
part_number · optional brand/type
Produces
starting identity · reverse replacements · possible decoys
Validation
A lifecycle query cannot proceed from an assumed same-number identity.
02
getAutoCarePartDetailsBreadth-first traversal of lifecycle and replacement edges.
Requires
identity at each node · max_hops
Produces
lifecycle · REPLACES · REPLACED_BY · interchange fallback
Validation
Visited identities prevent cycles; only replacement kinds extend the chain; budget/hop stops are disclosed.
Decision logic

Every important branch has a named outcome.

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

Explicit replacement edges existcomplete

Return directed lineage and lifecycle records.

Hop or request budget stops traversalpartial

Return the collected chain with a capped completeness state.

Lifecycle is no longer current but successor is absentpartial

Never report active; possible same-brand matches remain candidates only.

Only interchange-family edges existpartial fallback

Show them separately and never relabel them as replacement.

No explicit or fallback evidencenot_found

Only after exact identity and returned details are evaluated.

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 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
lifecycle statusdirected relationshipschain recordshop boundaryfallback typepossible successorsevidence
Grounding guaranteesRules against invented certainty
  • Interchange never becomes supersession
  • Traversal is breadth-first and cycle-safe
  • A missing successor does not imply an active part
Implementation sourcesSymbols behind the visual
Handlerlookup_part_supersessionpoc/opticat-mcp-v2/src/opticat_mcp_v2/service.py
Relationship normalizationnormalize_relationshipspoc/opticat-mcp-v2/src/opticat_mcp_v2/normalizers.py
Web mappingmcpToolForPlan · supersessionlib/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

    There is no live-verified positive chain

  2. 02

    Brand-scope limitations can hide OE relationships

  3. 03

    The client still needs three positive and three negative ground-truth chains

Next
Lineage navigator

Explore bidirectional replacement history with lifecycle state and stop reasons on every node.

Product concept · not implemented
Explore
Approved chain library

Maintain client-approved positive and negative lineages as executable production anchors.

Product concept · not implemented