oas2mcp.normalize.spec_to_catalog

OpenAPI-to-catalog normalization helpers.

Purpose:

Convert parsed OpenAPI data into the normalized ApiCatalog model used by oas2mcp.

Design:

• Accept either LangChain OpenAPISpec objects or plain dictionaries.

• Resolve relative server URLs against the original source URI.

• Flatten OpenAPI path items into reusable normalized operations.

• Preserve raw fragments where useful for later inspection or enrichment.

• Prefer normalized model field names over alias names during model construction to keep Python call sites valid and readable.

Examples

from oas2mcp.loaders import load_openapi_spec_from_url
from oas2mcp.normalize import openapi_spec_to_catalog

source_uri = "https://petstore3.swagger.io/api/v3/openapi.json"
spec = load_openapi_spec_from_url(source_uri)
catalog = openapi_spec_to_catalog(spec, source_uri=source_uri)

print(catalog.name)
print(catalog.operation_count)

Functions

openapi_spec_to_catalog(...)	Normalize a LangChain OpenAPISpec into an ApiCatalog.
spec_dict_to_catalog(...)	Normalize a dumped OpenAPI specification into an ApiCatalog.

Module Contents

oas2mcp.normalize.spec_to_catalog.openapi_spec_to_catalog(spec: langchain_community.utilities.openapi.OpenAPISpec, *, source_uri: str) → oas2mcp.models.normalized.ApiCatalog

Normalize a LangChain OpenAPISpec into an ApiCatalog.

Parameters:

• spec – The parsed LangChain OpenAPI spec.

• source_uri – The URI from which the spec originated.

Returns:

A normalized ApiCatalog.

Raises:

ValueError – If source_uri is empty.

Examples

from oas2mcp.loaders import load_openapi_spec_from_url
from oas2mcp.normalize import openapi_spec_to_catalog

source_uri = "https://petstore3.swagger.io/api/v3/openapi.json"
spec = load_openapi_spec_from_url(source_uri)
catalog = openapi_spec_to_catalog(spec, source_uri=source_uri)

oas2mcp.normalize.spec_to_catalog.spec_dict_to_catalog(spec_dict: collections.abc.Mapping[str, Any], *, source_uri: str) → oas2mcp.models.normalized.ApiCatalog

Normalize a dumped OpenAPI specification into an ApiCatalog.

Parameters:

• spec_dict – A plain-Python OpenAPI specification mapping.

• source_uri – The URI from which the spec originated. This is used for source tracking and for resolving relative server URLs.

Returns:

A normalized ApiCatalog.

Raises:

ValueError – If source_uri is empty.

Examples

from oas2mcp.normalize import spec_dict_to_catalog

catalog = spec_dict_to_catalog(
    {
        "openapi": "3.1.0",
        "info": {"title": "Example API", "version": "1.0.0"},
        "paths": {},
    },
    source_uri="https://example.com/openapi.json",
)