oas2mcp.utils.names
===================

.. py:module:: oas2mcp.utils.names

.. autoapi-nested-parse::

   Naming helpers for normalized catalogs and MCP preparation.

   Purpose:
       Create stable slugs, tool names, and resource URIs from normalized OpenAPI
       metadata.

   Design:
       - Keep naming deterministic.
       - Prefer operation identifiers when available.
       - Fall back to method + path when ``operationId`` is missing.

   .. rubric:: Examples

   .. code-block:: python

       slug = make_operation_slug(operation)
       tool_name = make_tool_name(catalog_name="petstore", operation=operation)



Functions
---------

.. autoapisummary::

   oas2mcp.utils.names.make_catalog_slug
   oas2mcp.utils.names.make_operation_resource_uri
   oas2mcp.utils.names.make_operation_slug
   oas2mcp.utils.names.make_resource_uri
   oas2mcp.utils.names.make_tag_slug
   oas2mcp.utils.names.make_tool_name
   oas2mcp.utils.names.slugify


Module Contents
---------------

.. py:function:: make_catalog_slug(catalog_name: str) -> str

   Create a stable catalog slug.

   :param catalog_name: The catalog display name.

   :returns: The catalog slug.

   :raises None.:

   .. rubric:: Examples

   .. code-block:: python

       slug = make_catalog_slug("Swagger Petstore - OpenAPI 3.0")


.. py:function:: make_operation_resource_uri(*, catalog_name: str, operation: oas2mcp.models.normalized.ApiOperation) -> str

   Create a resource URI or URI template for one operation.

   :param catalog_name: The API catalog name.
   :param operation: The normalized API operation.

   :returns: A stable URI for read-only resources or a URI template for parameterized
             read operations.


.. py:function:: make_operation_slug(operation: oas2mcp.models.normalized.ApiOperation) -> str

   Create a stable operation slug.

   :param operation: The normalized API operation.

   :returns: The operation slug.

   :raises None.:

   .. rubric:: Examples

   .. code-block:: python

       slug = make_operation_slug(operation)


.. py:function:: make_resource_uri(*, catalog_name: str, resource_kind: str, identifier: str) -> str

   Create a suggested MCP-style resource URI.

   :param catalog_name: The API catalog name.
   :param resource_kind: The logical resource kind, such as ``operation`` or
                         ``schema``.
   :param identifier: The resource identifier or slug.

   :returns: A suggested resource URI.

   :raises None.:

   .. rubric:: Examples

   .. code-block:: python

       uri = make_resource_uri(
           catalog_name="Petstore",
           resource_kind="operation",
           identifier="get-pet-by-id",
       )


.. py:function:: make_tag_slug(tag_name: str) -> str

   Create a stable tag slug.

   :param tag_name: The tag name.

   :returns: The tag slug.

   :raises None.:

   .. rubric:: Examples

   .. code-block:: python

       slug = make_tag_slug("pet")


.. py:function:: make_tool_name(*, catalog_name: str, operation: oas2mcp.models.normalized.ApiOperation) -> str

   Create a suggested MCP tool name.

   :param catalog_name: The API catalog name.
   :param operation: The normalized API operation.

   :returns: A suggested tool name.

   :raises None.:

   .. rubric:: Examples

   .. code-block:: python

       tool_name = make_tool_name(
           catalog_name="Petstore",
           operation=operation,
       )


.. py:function:: slugify(value: str) -> str

   Convert a string into a simple slug.

   :param value: The input string.

   :returns: A lowercase slug.

   :raises None.:

   .. rubric:: Examples

   .. code-block:: python

       assert slugify("Swagger Petstore - OpenAPI 3.0") == "swagger-petstore-openapi-3-0"