OptiCat MCP AtlasContract · flow · evidence · ideas
System atlasProduct intelligenceget_part_details
Product intelligence · part_details

Complete PIES product record

Resolve one exact product and expose the selected PIES record: identity, descriptions, unit-bearing attributes, lifecycle, origin, extended information, typed relationships, and classified assets.

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.

get_part_detailsArgumentsGenerated JSON Schema
read only
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": "9619",
    "brand": "Bosch"
  }
}
Show attributes and images for Bosch 9619
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 exact catalog identity before requesting details.
Requires
part_number · optional brand/type
Produces
brandCode · partTypeId · identity choices · reverse references
Validation
Same-number products are not interchangeable identities; bounded searches stay disclosed.
02
getAutoCarePartDetailsRetrieve and normalize the selected PIES item.
Requires
brandCode · partNumber
Produces
descriptions · attributes + units · extended info · lifecycle · origin · relationships · assets
Validation
Missing data means not returned; only classified HTTPS image resources render as images.
Decision logic

Every important branch has a named outcome.

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

Identity is ambiguousclarification_required

Return exact brand/type options before details.

Number exists only as a referencepartial

Return referencing products; details belong to their identities.

Details contain no PIES itemnot_found

Do not synthesize a product record from the search row.

PIES item is returnedcomplete

Preserve all normalized detail families and typed relationships.

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
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 evidence2 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
exact identitydescriptionsattributes with unitsextended informationlifecycle and origintyped relationshipsclassified assets
Grounding guaranteesRules against invented certainty
  • Exact identity precedes details
  • Missing attributes are not negative claims
  • Vehicle assets are not part images
  • Non-image resources remain labeled links
Implementation sourcesSymbols behind the visual
Handlerget_part_detailspoc/opticat-mcp-v2/src/opticat_mcp_v2/service.py
Normalizernormalize_partpoc/opticat-mcp-v2/src/opticat_mcp_v2/normalizers.py
Host shapingitemForPartlib/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

    A known entitled image-bearing product still needs live proof

  2. 02

    Asset URLs are not checked for reachability

  3. 03

    360-degree grouping needs domain validation

Next
Media and document viewer

Present image sets, 360 groups, marketing resources, and documents according to verified media type.

Product concept · not implemented
Explore
Unit-aware product compare

Compare two selected PIES records with normalized units and explicit incomparable fields.

Product concept · not implemented