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

Build a category-by-category parts job

Build a category-by-category parts job

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.

search_catalog_jobArgumentsGenerated JSON Schema
read only
interactionInteractionContext | nulloptional
default null
requestCatalogJobInputrequired
actionpropose | searchoptional
default "propose"2 allowed values
base_vehicle_idinteger | nulloptional
default null
base_vehicle_region_idinteger | nulloptional
default null
brandsstring[]optional
categoriesstring[]required

Categories named or confirmed by the customer; proposals are not repair requirements

makestring | nulloptional
default null
make_hintstring | nulloptional
default null
max_resultsintegeroptional
default 100min 1max 200
max_results_per_categoryintegeroptional
default 50min 1max 100
modelstring | nulloptional
default null
model_hintstring | nulloptional
default null
namestringoptional
default "Parts job"max length 120
pageintegeroptional
default 1min 1
part_typestring | nulloptional
default null
qualifier_filtersobjectoptional
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
submodelstring | nulloptional
default null
yearintegerrequired
min 1886max 2100
year_abbreviatedbooleanoptional
default false
Example MCP argumentsMatches the existing demo handoff
{
  "request": {
    "year": 2018,
    "model": "Mustang",
    "categories": [
      "Disc Brake Pad Set",
      "Disc Brake Rotor"
    ],
    "action": "propose"
  }
}
Propose the categories for a brake job on a 2018 Mustang
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
Handlersearch_catalog_jobpoc/opticat-mcp-v2/src/opticat_mcp_v2/jobs.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