proxywhirl.mcp.server
=====================

.. py:module:: proxywhirl.mcp.server

.. autoapi-nested-parse::

   MCP Server implementation for ProxyWhirl.

   Production-ready MCP server with unified tool interface, auto-loading from database,
   proper lifecycle management, FastMCP v2 Context support, and middleware-based auth.



Classes
-------

.. autoapisummary::

   proxywhirl.mcp.server.ProxyWhirlMCPServer


Functions
---------

.. autoapisummary::

   proxywhirl.mcp.server.cleanup_rotator
   proxywhirl.mcp.server.get_auth
   proxywhirl.mcp.server.get_proxy_config
   proxywhirl.mcp.server.get_proxy_health
   proxywhirl.mcp.server.get_rate_limit_status
   proxywhirl.mcp.server.get_rotator
   proxywhirl.mcp.server.list_proxies
   proxywhirl.mcp.server.main
   proxywhirl.mcp.server.mcp_lifespan
   proxywhirl.mcp.server.proxy_selection_workflow
   proxywhirl.mcp.server.proxy_status
   proxywhirl.mcp.server.recommend_proxy
   proxywhirl.mcp.server.rotate_proxy
   proxywhirl.mcp.server.set_auth
   proxywhirl.mcp.server.set_rotator


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

.. py:class:: ProxyWhirlMCPServer(proxy_manager = None)

   ProxyWhirl MCP Server using FastMCP.

   This server exposes proxy management functionality to AI assistants
   via the Model Context Protocol using FastMCP's decorator-based API.

   Example::

       # Basic usage
       server = ProxyWhirlMCPServer()
       server.run()

       # With custom rotator
       rotator = AsyncProxyWhirl()
       server = ProxyWhirlMCPServer(proxy_manager=rotator)
       await server.initialize()  # Must call for async setup
       server.run()

   Initialize ProxyWhirl MCP server.

   Note: If providing a proxy_manager, you must call initialize() to set it up.

   :param proxy_manager: ProxyWhirl proxy manager instance (AsyncProxyWhirl)


   .. py:method:: initialize()
      :async:


      Initialize the server asynchronously.

      Call this method after construction if you provided a custom proxy_manager.
      This properly sets up the rotator in an async context.



   .. py:method:: run(transport = 'stdio')

      Run the MCP server.

      :param transport: Transport type ('stdio', 'http', 'sse', or 'streamable-http')



.. py:function:: cleanup_rotator()
   :async:


   Clean up global rotator resources.

   Closes HTTP clients and releases all resources held by the rotator.
   Safe to call multiple times.


.. py:function:: get_auth()

   Get or create the global MCPAuth instance.

   :returns: MCPAuth instance


.. py:function:: get_proxy_config()
   :async:


   Wrapper to call shared get_proxy_config implementation.


.. py:function:: get_proxy_health()
   :async:


   Wrapper to call shared get_proxy_health implementation.


.. py:function:: get_rate_limit_status(proxy_id, api_key = None)
   :async:


   Get rate limiting status for a specific proxy (backward compatibility wrapper).

   Note: Rate limiting info is now included in the health action response.
   This wrapper is kept for backward compatibility.

   :param proxy_id: UUID of the proxy to check
   :param api_key: Optional API key for authentication

   :returns: Rate limit information.
   :rtype: dict[str, Any]


.. py:function:: get_rotator()
   :async:


   Get or create the global AsyncProxyWhirl instance with auto-loading.

   On first initialization:
   1. If database exists (from PROXYWHIRL_MCP_DB env or proxywhirl.db), loads proxies
   2. If pool is still empty, auto-fetches proxies from public sources

   :returns: AsyncProxyWhirl instance


.. py:function:: list_proxies(api_key = None)
   :async:


   Wrapper to call shared list_proxies implementation.

   :param api_key: Optional API key for authentication

   :returns: Proxy list and pool statistics.
   :rtype: dict[str, Any]


.. py:function:: main()

   CLI entry point for running the MCP server.

   This enables `uvx proxywhirl[mcp]` or `proxywhirl-mcp` to start the server.

   Environment variables:
       PROXYWHIRL_MCP_API_KEY: API key for authentication
       PROXYWHIRL_MCP_DB: Path to proxy database file
       PROXYWHIRL_MCP_LOG_LEVEL: Log level (debug, info, warning, error)


.. py:function:: mcp_lifespan()
   :async:


   Lifespan context manager for MCP server (legacy wrapper).

   Note: FastMCP v2 uses the lifespan passed to FastMCP() constructor.
   This is kept for backward compatibility with direct usage.

   :Yields: None


.. py:function:: proxy_selection_workflow()
   :async:


   Workflow prompt for guiding proxy selection decisions.


.. py:function:: proxy_status(proxy_id, api_key = None)
   :async:


   Wrapper to call shared proxy_status implementation.

   :param proxy_id: UUID of the proxy to check
   :param api_key: Optional API key for authentication

   :returns: Proxy status and metrics.
   :rtype: dict[str, Any]


.. py:function:: recommend_proxy(region = None, performance = 'medium', api_key = None)
   :async:


   Wrapper to call shared recommend_proxy implementation.

   :param region: Optional region filter (country code)
   :param performance: Performance tier (high, medium, low)
   :param api_key: Optional API key for authentication

   :returns: Recommendation and alternatives.
   :rtype: dict[str, Any]


.. py:function:: rotate_proxy(api_key = None)
   :async:


   Wrapper to call shared rotate_proxy implementation.

   :param api_key: Optional API key for authentication

   :returns: Selected proxy information.
   :rtype: dict[str, Any]


.. py:function:: set_auth(auth)

   Set the global MCPAuth instance.

   :param auth: MCPAuth instance to use, or None to disable authentication


.. py:function:: set_rotator(rotator)
   :async:


   Set the global AsyncProxyWhirl instance (thread-safe).

   :param rotator: AsyncProxyWhirl instance to use