uk-parliament-mcp 1.1.0__py3-none-any.whl

uk_parliament_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""UK Parliament MCP Server - bridges AI assistants with UK Parliament APIs."""
+
+__version__ = "1.1.0"

uk_parliament_mcp/__main__.py

@@ -0,0 +1,23 @@
+"""Entry point for the UK Parliament MCP Server."""
+
+import logging
+import sys
+
+from uk_parliament_mcp.server import create_server
+
+
+def main() -> None:
+    """Run the MCP server with stdio transport."""
+    # Configure logging to stderr (stdout is for MCP protocol)
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+        stream=sys.stderr,
+    )
+
+    server = create_server()
+    server.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

uk_parliament_mcp/config.py

@@ -0,0 +1,20 @@
+"""Centralized configuration for UK Parliament MCP Server."""
+
+# API Base URLs
+MEMBERS_API_BASE = "https://members-api.parliament.uk/api"
+BILLS_API_BASE = "https://bills-api.parliament.uk/api/v1"
+COMMONS_VOTES_API_BASE = "http://commonsvotes-api.parliament.uk/data"
+LORDS_VOTES_API_BASE = "https://lordsvotes-api.parliament.uk/data"
+COMMITTEES_API_BASE = "https://committees-api.parliament.uk/api"
+HANSARD_API_BASE = "https://hansard-api.parliament.uk/api/v1"
+INTERESTS_API_BASE = "https://interests-api.parliament.uk/api/v1"
+NOW_API_BASE = "https://now-api.parliament.uk/api"
+WHATSON_API_BASE = "https://whatson-api.parliament.uk/calendar"
+STATUTORY_INSTRUMENTS_API_BASE = "https://statutoryinstruments-api.parliament.uk/api/v2"
+TREATIES_API_BASE = "https://treaties-api.parliament.uk/api"
+ERSKINE_MAY_API_BASE = "https://erskinemay-api.parliament.uk/api"
+ORAL_QUESTIONS_API_BASE = "https://oralquestionsandmotions-api.parliament.uk"
+
+# Common constants
+HOUSE_COMMONS = 1
+HOUSE_LORDS = 2

uk_parliament_mcp/http_client.py

@@ -0,0 +1,237 @@
+"""HTTP client with retry logic for Parliament API requests."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from datetime import datetime, timedelta
+from typing import Any, NotRequired, TypedDict
+from urllib.parse import urlencode
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+
+# Response type definitions
+class SuccessResponse(TypedDict):
+    """Response structure for successful API calls."""
+
+    url: str
+    data: str
+
+
+class ErrorResponse(TypedDict):
+    """Response structure for failed API calls."""
+
+    url: str
+    error: str
+    statusCode: NotRequired[int]
+
+
+# Union type for API responses
+APIResponse = SuccessResponse | ErrorResponse
+
+
+class CacheEntry(TypedDict):
+    """Cache entry structure for storing API responses."""
+
+    data: str
+    expires: datetime
+
+
+# Configuration constants (matching C# implementation)
+HTTP_TIMEOUT = 30.0  # seconds
+MAX_RETRY_ATTEMPTS = 3
+RETRY_DELAY_BASE = 1.0  # seconds
+
+# HTTP status codes that should trigger a retry
+TRANSIENT_STATUS_CODES = frozenset({408, 429, 500, 502, 503, 504})
+
+# Cache configuration
+CACHE_TTL = timedelta(minutes=15)
+_cache: dict[str, CacheEntry] = {}
+
+
+def build_url(base_url: str, parameters: dict[str, Any]) -> str:
+    """
+    Build URL with query parameters, filtering out None and empty values.
+
+    Equivalent to C# BaseTools.BuildUrl()
+
+    Args:
+        base_url: The base URL without query parameters
+        parameters: Dictionary of parameter names to values
+
+    Returns:
+        URL with query string, or just base_url if no valid parameters
+    """
+    valid_params = {
+        k: str(v).lower() if isinstance(v, bool) else str(v)
+        for k, v in parameters.items()
+        if v is not None and v != ""
+    }
+
+    if not valid_params:
+        return base_url
+
+    return f"{base_url}?{urlencode(valid_params)}"
+
+
+def _is_retryable_status(status_code: int) -> bool:
+    """Check if HTTP status code is transient and should be retried."""
+    return status_code in TRANSIENT_STATUS_CODES
+
+
+class ParliamentHTTPClient:
+    """Async HTTP client with retry logic for Parliament APIs."""
+
+    def __init__(self) -> None:
+        self._client: httpx.AsyncClient | None = None
+
+    async def _get_client(self) -> httpx.AsyncClient:
+        """Get or create the HTTP client."""
+        if self._client is None:
+            self._client = httpx.AsyncClient(timeout=HTTP_TIMEOUT)
+        return self._client
+
+    async def close(self) -> None:
+        """Close the HTTP client."""
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+    async def get_result(self, url: str) -> str:
+        """
+        Make HTTP GET request with retry logic.
+
+        Returns JSON serialized response matching C# format:
+        - Success: {"url": "...", "data": "..."}
+        - Error: {"url": "...", "error": "...", "statusCode": N}
+
+        Equivalent to C# BaseTools.GetResult()
+        """
+        client = await self._get_client()
+
+        for attempt in range(MAX_RETRY_ATTEMPTS):
+            try:
+                logger.info(
+                    "Making HTTP request to %s (attempt %d/%d)",
+                    url,
+                    attempt + 1,
+                    MAX_RETRY_ATTEMPTS,
+                )
+
+                response = await client.get(url)
+
+                if response.is_success:
+                    data = response.text
+                    logger.info("Successfully retrieved data from %s", url)
+                    return json.dumps({"url": url, "data": data})
+
+                if _is_retryable_status(response.status_code):
+                    logger.warning(
+                        "Transient failure for %s: %d. Attempt %d/%d",
+                        url,
+                        response.status_code,
+                        attempt + 1,
+                        MAX_RETRY_ATTEMPTS,
+                    )
+                    if attempt < MAX_RETRY_ATTEMPTS - 1:
+                        await asyncio.sleep(RETRY_DELAY_BASE * (attempt + 1))
+                        continue
+
+                # Non-retryable error or final attempt
+                error_message = (
+                    f"HTTP request failed with status {response.status_code}: "
+                    f"{response.reason_phrase}"
+                )
+                logger.error("Final failure for %s: %d", url, response.status_code)
+                return json.dumps(
+                    {"url": url, "error": error_message, "statusCode": response.status_code}
+                )
+
+            except httpx.TimeoutException:
+                logger.warning(
+                    "Request to %s timed out. Attempt %d/%d",
+                    url,
+                    attempt + 1,
+                    MAX_RETRY_ATTEMPTS,
+                )
+                if attempt == MAX_RETRY_ATTEMPTS - 1:
+                    return json.dumps(
+                        {"url": url, "error": "Request timed out after multiple attempts"}
+                    )
+                await asyncio.sleep(RETRY_DELAY_BASE * (attempt + 1))
+
+            except httpx.NetworkError as e:
+                logger.warning(
+                    "Network error for %s: %s. Attempt %d/%d",
+                    url,
+                    str(e),
+                    attempt + 1,
+                    MAX_RETRY_ATTEMPTS,
+                )
+                if attempt == MAX_RETRY_ATTEMPTS - 1:
+                    return json.dumps({"url": url, "error": f"Network error: {e!s}"})
+                await asyncio.sleep(RETRY_DELAY_BASE * (attempt + 1))
+
+            except Exception as e:
+                logger.error("Unexpected error for %s: %s", url, str(e))
+                return json.dumps({"url": url, "error": f"Unexpected error: {e!s}"})
+
+        return json.dumps({"url": url, "error": "Maximum retry attempts exceeded"})
+
+
+# Global client instance for reuse across tools
+_client = ParliamentHTTPClient()
+
+
+async def get_result(url: str) -> str:
+    """Convenience function using global client."""
+    return await _client.get_result(url)
+
+
+async def get_result_cached(url: str, cache_key: str | None = None) -> str:
+    """
+    Get result with optional caching for reference data.
+
+    Use this for frequently accessed reference data that rarely changes,
+    such as bill types, bill stages, committee types, etc.
+
+    Args:
+        url: API URL to fetch
+        cache_key: Optional cache key. If None, no caching is used.
+
+    Returns:
+        JSON response string in the same format as get_result()
+    """
+    key = cache_key or url
+
+    # Check cache
+    if key in _cache:
+        entry = _cache[key]
+        if datetime.now() < entry["expires"]:
+            logger.debug("Cache hit for %s", key)
+            return entry["data"]
+        else:
+            # Expired entry, remove it
+            del _cache[key]
+            logger.debug("Cache expired for %s", key)
+
+    # Fetch fresh data
+    result = await get_result(url)
+
+    # Cache if successful and cache_key provided
+    if cache_key and '"error"' not in result:
+        _cache[key] = {"data": result, "expires": datetime.now() + CACHE_TTL}
+        logger.debug("Cached result for %s", key)
+
+    return result
+
+
+def clear_cache() -> None:
+    """Clear all cached data."""
+    _cache.clear()
+    logger.debug("Cache cleared")

uk_parliament_mcp/server.py

@@ -0,0 +1,49 @@
+"""FastMCP server configuration and tool registration."""
+
+from mcp.server.fastmcp import FastMCP
+
+from uk_parliament_mcp.tools import (
+    bills,
+    committees,
+    commons_votes,
+    composite,
+    core,
+    erskine_may,
+    hansard,
+    interests,
+    lords_votes,
+    members,
+    now,
+    oral_questions,
+    statutory_instruments,
+    treaties,
+    whatson,
+)
+from uk_parliament_mcp.tools.core import SYSTEM_PROMPT
+
+
+def create_server() -> FastMCP:
+    """Create and configure the MCP server with all tools registered."""
+    mcp = FastMCP(name="uk-parliament-mcp", instructions=SYSTEM_PROMPT)
+
+    # Register all tool modules
+    core.register_tools(mcp)
+    composite.register_tools(mcp)
+    members.register_tools(mcp)
+    bills.register_tools(mcp)
+    committees.register_tools(mcp)
+    commons_votes.register_tools(mcp)
+    lords_votes.register_tools(mcp)
+    hansard.register_tools(mcp)
+    oral_questions.register_tools(mcp)
+    interests.register_tools(mcp)
+    now.register_tools(mcp)
+    whatson.register_tools(mcp)
+    statutory_instruments.register_tools(mcp)
+    treaties.register_tools(mcp)
+    erskine_may.register_tools(mcp)
+
+    # Register prompts (agent skills)
+    core.register_prompts(mcp)
+
+    return mcp

uk_parliament_mcp/tools/__init__.py

@@ -0,0 +1 @@
+"""UK Parliament MCP Server tools modules."""