oas2mcp.utils.refs

Reference and JSON pointer helpers.

Purpose:

Resolve JSON pointers and schema references against normalized OpenAPI raw spec data.

Design:

• Support local #/... references first.

• Keep helpers read-only and deterministic.

• Return None instead of raising for missing refs in normal lookup flows.

• Provide separate request and response schema ref collection so viewers and agent-context builders can distinguish input from output structure.

Examples

schema = dereference_schema_ref(catalog.raw_spec, "#/components/schemas/Pet")

Functions

collect_operation_schema_refs(→ list[str])	Collect all schema refs mentioned by an operation.
collect_request_schema_refs(→ list[str])	Collect request-body schema refs mentioned by an operation.
collect_response_schema_refs(→ list[str])	Collect response schema refs mentioned by an operation.
dereference_schema_ref(→ dict[str, Any] | None)	Dereference a local schema reference.
resolve_json_pointer(→ Any | None)	Resolve a local JSON pointer within a document.

Module Contents

oas2mcp.utils.refs.collect_operation_schema_refs(operation: oas2mcp.models.normalized.ApiOperation) → list[str]

Collect all schema refs mentioned by an operation.

Parameters:

operation – The normalized API operation.

Returns:

A de-duplicated list of request and response schema refs.

Raises:

None. –

Examples

refs = collect_operation_schema_refs(operation)

oas2mcp.utils.refs.collect_request_schema_refs(operation: oas2mcp.models.normalized.ApiOperation) → list[str]

Collect request-body schema refs mentioned by an operation.

Parameters:

operation – The normalized API operation.

Returns:

A de-duplicated list of request schema refs.

Raises:

None. –

Examples

refs = collect_request_schema_refs(operation)

oas2mcp.utils.refs.collect_response_schema_refs(operation: oas2mcp.models.normalized.ApiOperation) → list[str]

Collect response schema refs mentioned by an operation.

Parameters:

operation – The normalized API operation.

Returns:

A de-duplicated list of response schema refs.

Raises:

None. –

Examples

refs = collect_response_schema_refs(operation)

oas2mcp.utils.refs.dereference_schema_ref(document: dict[str, Any], schema_ref: str) → dict[str, Any] | None

Dereference a local schema reference.

Parameters:

• document – The raw OpenAPI specification dictionary.

• schema_ref – A local schema reference.

Returns:

The resolved schema mapping when found, otherwise None.

Raises:

None. –

Examples

schema = dereference_schema_ref(
    {"components": {"schemas": {"Pet": {"type": "object"}}}},
    "#/components/schemas/Pet",
)

oas2mcp.utils.refs.resolve_json_pointer(document: dict[str, Any], pointer: str) → Any | None

Resolve a local JSON pointer within a document.

Parameters:

• document – The target document.

• pointer – The JSON pointer, such as #/components/schemas/Pet.

Returns:

The resolved value when found, otherwise None.

Raises:

None. –

Examples

value = resolve_json_pointer(
    {"components": {"schemas": {"Pet": {"type": "object"}}}},
    "#/components/schemas/Pet",
)