OptiCat MCP AtlasContract · flow · evidence · ideas
System atlasVehicle discoveryread_catalog_result
Vehicle discovery · vehicle_to_part

Browse exact captured catalog records

Browse exact captured catalog records

Run the example Inspect contract
Visual model · record

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.

read_catalog_resultArgumentsGenerated JSON Schema
read only
interactionInteractionContext | nulloptional
default null
requestCatalogResultReadInputrequired
actionpage | detail | continue | refineoptional
default "page"4 allowed values
limitintegeroptional
default 24min 1max 200
offsetintegeroptional
default 0min 0max 10000
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
record_idstring | nulloptional
default null
result_set_idstringrequired
Example MCP argumentsMatches the existing demo handoff
{
  "request": {
    "result_set_id": "11111111-1111-4111-8111-111111111111",
    "action": "page",
    "offset": 0,
    "limit": 24
  }
}
Load more records from the selected catalog result
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 requested category or check the captured source version when the action needs it.
Only when searching, continuing upstream, or refreshing source versions; stored reads need no vendor request.
Requires
authorized session · validated request
Produces
captured evidence · coverage
Validation
Page/detail reads and exact comparisons do not re-resolve part numbers.
Decision logic

Every important branch has a named outcome.

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

Stale, foreign or missing record referenceinvalid_input

Refresh or select a valid record; never substitute a similarly numbered product.

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.

Outcome1 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 + completeness1 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 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 controls0 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 variantSource scopeOriginal quantitiesUnresolved conditionsCoverageCaptured time
Grounding guaranteesRules against invented certainty
  • Owner and expiry checked on every read
  • No client-provided product facts
  • Missing evidence remains unknown
  • Job proposals are not repair prescriptions
Implementation sourcesSymbols behind the visual
Handlerread_resultpoc/opticat-mcp-v2/src/opticat_mcp_v2/result_sets.py
StoreResultStorepoc/opticat-mcp-v2/src/opticat_mcp_v2/result_store.py
Web routingmcpToolForPlanlib/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

    Live supplier acceptance, production storage configuration and actual native hosts require release validation

Explore
Supplier snapshot identifiers

Use vendor-issued immutable revision IDs when the API supplies them.

Product concept · not implemented