OptiCat MCP AtlasContract · flow · evidence · ideas
System atlasFoundationget_catalog_status
Foundation · catalog_status

Catalog readiness and key scope

Prove that OptiCat is reachable, classify access correctly, expose reference-data versions, and describe the configured key’s non-secret brand and VIN scope.

Run the example Inspect contract
Visual model · circuit

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_catalog_statusArgumentsGenerated JSON Schema
read only
interactionInteractionContext | nulloptional
default null
Example MCP argumentsMatches the existing demo handoff
{}
Check catalog status
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
getAutoCareVersionEstablish catalog reachability and reference-data versions.
Requires
X-Api-Key
Produces
PCdb/VCdb/PAdb versions · body status · latency
Validation
HTTP and JSON body status are classified independently; access failure is never an empty catalog.
02
getAutoCareBrandsLastUpdatedDatesBuild a non-secret brand-scope and freshness profile.
Requires
accepted key
Produces
entitled brand count · freshness sample
Validation
An unrecognized or unavailable result is disclosed inside key_scope instead of failing the readiness result.
03
getAutoCareVehiclesByVINProbe VIN entitlement with a syntactically valid disposable VIN.
Best-effort scope probe
Requires
accepted key · probe VIN
Produces
enabled · not_entitled · unknown
Validation
The decode result is discarded; only the entitlement class is returned.
Decision logic

Every important branch has a named outcome.

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

Version call succeedscomplete

Return versions plus best-effort key-scope probes.

Brand or VIN probe failscomplete with scoped metadata

The primary readiness result survives and the probe’s limitation is explicit.

Access is rejectednot_entitled

Never translated into a catalog-negative statement.

Retryable upstream failureunavailable

Return structured retryability and evidence.

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
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 evidence0 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.
Observability2 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
readinessversion metadatabrand-scope countVIN entitlementlatencyerror class
Grounding guaranteesRules against invented certainty
  • No secret values are returned
  • Access failure is not no-data
  • Probe failures do not erase the primary result
Implementation sourcesSymbols behind the visual
Registrationget_catalog_statuspoc/opticat-mcp-v2/src/opticat_mcp_v2/server.py
HandlerOptiCatCatalogService.get_catalog_statuspoc/opticat-mcp-v2/src/opticat_mcp_v2/service.py
Client classificationOptiCatClient.callpoc/opticat-mcp-v2/src/opticat_mcp_v2/client.py
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

    Key scope is not yet surfaced in the operator console

  2. 02

    There is no scheduled readiness history

  3. 03

    Live paging ceilings are not described per operation

Next
Readiness history

Trend latency, versions, and entitlement changes over deployments.

Product concept · not implemented
Explore
Entitlement drift radar

Alert when brand, VIN, or paging scope changes before customer answers regress.

Product concept · not implemented