uk-parliament-mcp 1.0.1__py3-none-any.whl → 1.2.0__py3-none-any.whl

uk_parliament_mcp/__init__.py

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

uk_parliament_mcp/config.py

@@ -0,0 +1,21 @@
+"""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"
+WRITTEN_QUESTIONS_API_BASE = "https://writtenquestions-api.parliament.uk/api"
+
+# Common constants
+HOUSE_COMMONS = 1
+HOUSE_LORDS = 2

uk_parliament_mcp/http_client.py

@@ -5,13 +5,42 @@ from __future__ import annotations
 import asyncio
 import json
 import logging
-from typing import Any
+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
@@ -20,6 +49,10 @@ 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:
     """
@@ -158,3 +191,47 @@ _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

@@ -2,7 +2,6 @@
 
 from mcp.server.fastmcp import FastMCP
 
-from uk_parliament_mcp.tools.core import SYSTEM_PROMPT
 from uk_parliament_mcp.tools import (
     bills,
     committees,
@@ -19,7 +18,9 @@ from uk_parliament_mcp.tools import (
     statutory_instruments,
     treaties,
     whatson,
+    written_questions,
 )
+from uk_parliament_mcp.tools.core import SYSTEM_PROMPT
 
 
 def create_server() -> FastMCP:
@@ -42,6 +43,7 @@ def create_server() -> FastMCP:
     statutory_instruments.register_tools(mcp)
     treaties.register_tools(mcp)
     erskine_may.register_tools(mcp)
+    written_questions.register_tools(mcp)
 
     # Register prompts (agent skills)
     core.register_prompts(mcp)

uk_parliament_mcp/tools/bills.py

@@ -4,10 +4,9 @@ from urllib.parse import quote
 
 from mcp.server.fastmcp import FastMCP
 
+from uk_parliament_mcp.config import BILLS_API_BASE
 from uk_parliament_mcp.http_client import build_url, get_result
 
-BILLS_API_BASE = "https://bills-api.parliament.uk/api/v1"
-
 
 def register_tools(mcp: FastMCP) -> None:
     """Register bills tools with the MCP server."""

uk_parliament_mcp/tools/committees.py

@@ -4,10 +4,9 @@ from urllib.parse import quote
 
 from mcp.server.fastmcp import FastMCP
 
+from uk_parliament_mcp.config import COMMITTEES_API_BASE
 from uk_parliament_mcp.http_client import build_url, get_result
 
-COMMITTEES_API_BASE = "https://committees-api.parliament.uk/api"
-
 
 def register_tools(mcp: FastMCP) -> None:
     """Register committees tools with the MCP server."""

uk_parliament_mcp/tools/commons_votes.py

@@ -2,10 +2,9 @@
 
 from mcp.server.fastmcp import FastMCP
 
+from uk_parliament_mcp.config import COMMONS_VOTES_API_BASE
 from uk_parliament_mcp.http_client import build_url, get_result
 
-COMMONS_VOTES_API_BASE = "http://commonsvotes-api.parliament.uk/data"
-
 
 def register_tools(mcp: FastMCP) -> None:
     """Register Commons votes tools with the MCP server."""

uk_parliament_mcp/tools/composite.py

@@ -8,15 +8,15 @@ from typing import Any
 
 from mcp.server.fastmcp import FastMCP
 
+from uk_parliament_mcp.config import (
+    BILLS_API_BASE,
+    COMMITTEES_API_BASE,
+    COMMONS_VOTES_API_BASE,
+    INTERESTS_API_BASE,
+    MEMBERS_API_BASE,
+)
 from uk_parliament_mcp.http_client import build_url, get_result
 
-# API bases
-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"
-COMMITTEES_API_BASE = "https://committees-api.parliament.uk/api"
-INTERESTS_API_BASE = "https://interests-api.parliament.uk/api/v1"
-
 
 def _parse_response(response: str) -> dict[str, Any]:
     """Parse JSON response and extract data."""
@@ -75,7 +75,8 @@ def register_tools(mcp: FastMCP) -> None:
 
         # Get basic info from search result
         basic_info = member_data.get("items", [{}])[0].get("value", {})
-        house = 1 if basic_info.get("latestHouseMembership", {}).get("house") == 1 else 2
+        latest_membership = basic_info.get("latestHouseMembership") or {}
+        house = latest_membership.get("house", 1)
 
         # Step 2: Parallel requests for details
         biography_url = f"{MEMBERS_API_BASE}/Members/{member_id}/Biography"

uk_parliament_mcp/tools/core.py

@@ -16,7 +16,7 @@ Convert raw data into human-readable summaries while preserving accuracy, but al
 
 GOODBYE_PROMPT = """You are now interacting as a normal assistant. There are no special restrictions or requirements for using UK Parliament MCP data. You may answer questions using any available data or knowledge, and you do not need to append MCP API URLs or limit yourself to MCP sources. Resume normal assistant behavior."""
 
-QUICK_REFERENCE = """## Quick Reference: UK Parliament MCP Tools (94 tools)
+QUICK_REFERENCE = """## Quick Reference: UK Parliament MCP Tools (92 tools)
 
 ### Composite Tools (Start Here for Common Queries!)
 These tools combine multiple API calls - use them first for efficiency:
@@ -35,7 +35,7 @@ These tools combine multiple API calls - use them first for efficiency:
 | Module | Tools | Start With |
 |--------|-------|------------|
 | composite | 4 | get_mp_profile(name) |
-| members | 26 | get_member_by_name(name) |
+| members | 25 | get_member_by_name(name) |
 | bills | 21 | search_bills(search_term) |
 | committees | 12 | search_committees(search_term) |
 | commons_votes | 5 | search_commons_divisions(search_term) |
@@ -93,7 +93,7 @@ Use the individual tools (in members, bills, etc.) when you need:
 - Pagination through large result sets
 - Access to specific endpoints not covered by composite tools
 - More control over which data is fetched""",
-    "members": """## Members Tools (26 tools)
+    "members": """## Members Tools (25 tools)
 
 ### Primary Search Tools
 - search_members(name, location, party_id, house, is_current_member, skip, take) - Comprehensive member search with filters
@@ -376,12 +376,12 @@ International agreements requiring parliamentary scrutiny:
 5. Third Reading: Final debate
 6. Lords/Commons stages: Mirror process in other House
 7. Royal Assent: Becomes law""",
-    "all": """## All UK Parliament MCP Tools (94 tools)
+    "all": """## All UK Parliament MCP Tools (92 tools)
 
 ### Composite (4 tools) - Use These First!
 get_mp_profile, check_mp_vote, get_bill_overview, get_committee_summary
 
-### Members (26 tools)
+### Members (25 tools)
 Search: search_members, get_member_by_name, search_members_historical
 Details: get_member_by_id, get_members_biography, get_members_contact, get_member_synopsis, get_member_experience, get_member_focus
 Activity: get_member_voting, get_commons_voting_record_for_member, get_lords_voting_record_for_member, get_member_written_questions, get_contributions, edms_for_member_id

uk_parliament_mcp/tools/erskine_may.py

@@ -4,10 +4,9 @@ from urllib.parse import quote
 
 from mcp.server.fastmcp import FastMCP
 
+from uk_parliament_mcp.config import ERSKINE_MAY_API_BASE
 from uk_parliament_mcp.http_client import get_result
 
-ERSKINE_MAY_API_BASE = "https://erskinemay-api.parliament.uk/api"
-
 
 def register_tools(mcp: FastMCP) -> None:
     """Register Erskine May tools with the MCP server."""

uk_parliament_mcp/tools/hansard.py

@@ -2,10 +2,9 @@
 
 from mcp.server.fastmcp import FastMCP
 
+from uk_parliament_mcp.config import HANSARD_API_BASE
 from uk_parliament_mcp.http_client import build_url, get_result
 
-HANSARD_API_BASE = "https://hansard-api.parliament.uk"
-
 
 def register_tools(mcp: FastMCP) -> None:
     """Register Hansard tools with the MCP server."""
@@ -16,6 +15,9 @@ def register_tools(mcp: FastMCP) -> None:
         start_date: str,
         end_date: str,
         search_term: str,
+        member_id: int | None = None,
+        skip: int = 0,
+        take: int = 20,
     ) -> str:
         """Search Hansard (official parliamentary record) for speeches and debates. Use when researching what was said in Parliament on specific topics, by specific members, or in specific time periods. House: 1=Commons, 2=Lords.
 
@@ -24,6 +26,9 @@ def register_tools(mcp: FastMCP) -> None:
             start_date: Start date in YYYY-MM-DD format.
             end_date: End date in YYYY-MM-DD format.
             search_term: Search term for speeches or debates (e.g. 'climate change', 'NHS').
+            member_id: Optional member ID to filter results to a specific MP/Lord.
+            skip: Number of results to skip for pagination (default 0).
+            take: Number of results to return (default 20, max varies by endpoint).
 
         Returns:
             Hansard records matching the search criteria.
@@ -35,6 +40,133 @@ def register_tools(mcp: FastMCP) -> None:
                 "queryParameters.startDate": start_date,
                 "queryParameters.endDate": end_date,
                 "queryParameters.searchTerm": search_term,
+                "queryParameters.memberId": member_id,
+                "queryParameters.skip": skip,
+                "queryParameters.take": take,
+            },
+        )
+        return await get_result(url)
+
+    @mcp.tool()
+    async def get_debate_by_id(debate_section_id: str) -> str:
+        """Get full debate transcript | Hansard, speeches, contributions |
+        Use after search_hansard to get complete debate with all member speeches.
+        Returns debate title, date, house, and all contributions.
+
+        Args:
+            debate_section_id: External ID from search_hansard results.
+
+        Returns:
+            Full debate with all member contributions.
+        """
+        url = f"{HANSARD_API_BASE}/debates/debate/{debate_section_id}.json"
+        return await get_result(url)
+
+    @mcp.tool()
+    async def get_member_hansard_contributions(
+        member_id: int,
+        debate_section_id: str,
+    ) -> str:
+        """Get all speeches by a specific MP/Lord in a debate | Hansard, member speeches |
+        Use to extract just one member's contributions from a debate.
+        Returns all contributions by that member in the specified debate.
+
+        Args:
+            member_id: Parliament member ID (from members API).
+            debate_section_id: External ID of debate section (from search_hansard).
+
+        Returns:
+            All contributions by that member in the debate.
+        """
+        url = f"{HANSARD_API_BASE}/debates/memberdebatecontributions/{member_id}.json?debateSectionExtId={debate_section_id}"
+        return await get_result(url)
+
+    @mcp.tool()
+    async def get_debate_divisions(debate_section_id: str) -> str:
+        """Get votes that occurred during a debate | Hansard, divisions, voting |
+        Use to find divisions (votes) that took place in a specific debate.
+        Returns list of divisions with aye/noe counts.
+
+        Args:
+            debate_section_id: External ID of debate section (from search_hansard).
+
+        Returns:
+            List of divisions with vote counts.
+        """
+        url = f"{HANSARD_API_BASE}/debates/divisions/{debate_section_id}.json"
+        return await get_result(url)
+
+    @mcp.tool()
+    async def get_division_details(
+        division_id: str,
+        is_evel: bool = False,
+    ) -> str:
+        """Get full division details including how each member voted | Hansard, division, voting records |
+        Use to see individual voting records for a specific division.
+        Returns division with debate title, counts, and member voting records.
+
+        Args:
+            division_id: External ID of division (from get_debate_divisions).
+            is_evel: Filter to EVEL (English Votes for English Laws) voters only.
+
+        Returns:
+            Division details with member voting records.
+        """
+        url = build_url(
+            f"{HANSARD_API_BASE}/debates/division/{division_id}.json",
+            {"isEvel": is_evel if is_evel else None},
+        )
+        return await get_result(url)
+
+    @mcp.tool()
+    async def get_hansard_sitting_day(
+        sitting_date: str,
+        house: int,
+    ) -> str:
+        """Get full agenda/sections for a sitting day | Hansard, daily business, agenda |
+        Use to see all debates and business for a specific day.
+        Returns all debate sections for that day.
+
+        Args:
+            sitting_date: Date in YYYY-MM-DD format.
+            house: House number: 1 for Commons, 2 for Lords.
+
+        Returns:
+            All debate sections for that day.
+        """
+        url = build_url(
+            f"{HANSARD_API_BASE}/overview/sectionsforday.json",
+            {
+                "date": sitting_date,
+                "house": house,
+            },
+        )
+        return await get_result(url)
+
+    @mcp.tool()
+    async def get_hansard_calendar(
+        year: int,
+        month: int,
+        house: int,
+    ) -> str:
+        """Get all sitting dates for a month | Hansard, calendar, sitting days |
+        Use to discover which days have Hansard records available.
+        Returns list of sitting dates with Hansard available.
+
+        Args:
+            year: Year (e.g. 2024).
+            month: Month number (1-12).
+            house: House number: 1 for Commons, 2 for Lords.
+
+        Returns:
+            List of sitting dates for the month.
+        """
+        url = build_url(
+            f"{HANSARD_API_BASE}/overview/calendar.json",
+            {
+                "year": year,
+                "month": month,
+                "house": house,
             },
         )
         return await get_result(url)

uk_parliament_mcp/tools/interests.py

@@ -2,10 +2,9 @@
 
 from mcp.server.fastmcp import FastMCP
 
+from uk_parliament_mcp.config import INTERESTS_API_BASE
 from uk_parliament_mcp.http_client import get_result
 
-INTERESTS_API_BASE = "https://interests-api.parliament.uk/api/v1"
-
 
 def register_tools(mcp: FastMCP) -> None:
     """Register interests tools with the MCP server."""

uk_parliament_mcp/tools/lords_votes.py

@@ -4,10 +4,9 @@ from urllib.parse import quote
 
 from mcp.server.fastmcp import FastMCP
 
+from uk_parliament_mcp.config import LORDS_VOTES_API_BASE
 from uk_parliament_mcp.http_client import build_url, get_result
 
-LORDS_VOTES_API_BASE = "http://lordsvotes-api.parliament.uk/data"
-
 
 def register_tools(mcp: FastMCP) -> None:
     """Register Lords votes tools with the MCP server."""

uk_parliament_mcp/tools/members.py

@@ -4,10 +4,9 @@ from urllib.parse import quote
 
 from mcp.server.fastmcp import FastMCP
 
+from uk_parliament_mcp.config import MEMBERS_API_BASE
 from uk_parliament_mcp.http_client import build_url, get_result
 
-MEMBERS_API_BASE = "https://members-api.parliament.uk/api"
-
 
 def register_tools(mcp: FastMCP) -> None:
     """Register member tools with the MCP server."""

uk_parliament_mcp/tools/now.py

@@ -2,10 +2,9 @@
 
 from mcp.server.fastmcp import FastMCP
 
+from uk_parliament_mcp.config import NOW_API_BASE
 from uk_parliament_mcp.http_client import get_result
 
-NOW_API_BASE = "https://now-api.parliament.uk/api"
-
 
 def register_tools(mcp: FastMCP) -> None:
     """Register now tools with the MCP server."""

uk_parliament_mcp/tools/oral_questions.py

@@ -4,10 +4,9 @@ from urllib.parse import quote
 
 from mcp.server.fastmcp import FastMCP
 
+from uk_parliament_mcp.config import ORAL_QUESTIONS_API_BASE
 from uk_parliament_mcp.http_client import get_result
 
-ORAL_QUESTIONS_API_BASE = "https://oralquestionsandmotions-api.parliament.uk"
-
 
 def register_tools(mcp: FastMCP) -> None:
     """Register oral questions tools with the MCP server."""

uk_parliament_mcp/tools/statutory_instruments.py

@@ -4,10 +4,9 @@ from urllib.parse import quote
 
 from mcp.server.fastmcp import FastMCP
 
+from uk_parliament_mcp.config import STATUTORY_INSTRUMENTS_API_BASE
 from uk_parliament_mcp.http_client import get_result
 
-STATUTORY_INSTRUMENTS_API_BASE = "https://statutoryinstruments-api.parliament.uk/api/v2"
-
 
 def register_tools(mcp: FastMCP) -> None:
     """Register statutory instruments tools with the MCP server."""

uk_parliament_mcp/tools/treaties.py

@@ -4,10 +4,9 @@ from urllib.parse import quote
 
 from mcp.server.fastmcp import FastMCP
 
+from uk_parliament_mcp.config import TREATIES_API_BASE
 from uk_parliament_mcp.http_client import get_result
 
-TREATIES_API_BASE = "https://treaties-api.parliament.uk/api"
-
 
 def register_tools(mcp: FastMCP) -> None:
     """Register treaties tools with the MCP server."""

uk_parliament_mcp/tools/whatson.py

@@ -2,10 +2,9 @@
 
 from mcp.server.fastmcp import FastMCP
 
+from uk_parliament_mcp.config import WHATSON_API_BASE
 from uk_parliament_mcp.http_client import build_url, get_result
 
-WHATSON_API_BASE = "https://whatson-api.parliament.uk/calendar"
-
 
 def register_tools(mcp: FastMCP) -> None:
     """Register whatson tools with the MCP server."""