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

uk_parliament_mcp/tools/erskine_may.py

@@ -0,0 +1,25 @@
+"""Erskine May API tools for parliamentary procedure."""
+
+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
+
+
+def register_tools(mcp: FastMCP) -> None:
+    """Register Erskine May tools with the MCP server."""
+
+    @mcp.tool()
+    async def search_erskine_may(search_term: str) -> str:
+        """Search Erskine May parliamentary procedure manual. Use when you need to understand parliamentary rules, procedures, or precedents. Erskine May is the authoritative guide to parliamentary procedure.
+
+        Args:
+            search_term: Search term for parliamentary procedure rules (e.g. 'Speaker', 'amendment', 'division').
+
+        Returns:
+            Erskine May paragraphs matching the search term.
+        """
+        url = f"{ERSKINE_MAY_API_BASE}/Search/ParagraphSearchResults/{quote(search_term)}"
+        return await get_result(url)

uk_parliament_mcp/tools/hansard.py

@@ -0,0 +1,39 @@
+"""Hansard API tools for searching the official parliamentary record."""
+
+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
+
+
+def register_tools(mcp: FastMCP) -> None:
+    """Register Hansard tools with the MCP server."""
+
+    @mcp.tool()
+    async def search_hansard(
+        house: int,
+        start_date: str,
+        end_date: str,
+        search_term: str,
+    ) -> 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.
+
+        Args:
+            house: House number: 1 for Commons, 2 for Lords.
+            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').
+
+        Returns:
+            Hansard records matching the search criteria.
+        """
+        url = build_url(
+            f"{HANSARD_API_BASE}/search.json",
+            {
+                "queryParameters.house": house,
+                "queryParameters.startDate": start_date,
+                "queryParameters.endDate": end_date,
+                "queryParameters.searchTerm": search_term,
+            },
+        )
+        return await get_result(url)

uk_parliament_mcp/tools/interests.py

@@ -0,0 +1,43 @@
+"""Interests API tools for Register of Interests."""
+
+from mcp.server.fastmcp import FastMCP
+
+from uk_parliament_mcp.config import INTERESTS_API_BASE
+from uk_parliament_mcp.http_client import get_result
+
+
+def register_tools(mcp: FastMCP) -> None:
+    """Register interests tools with the MCP server."""
+
+    @mcp.tool()
+    async def search_roi(member_id: int) -> str:
+        """Search member's Register of Interests for financial and business declarations | register of interests, ROI, financial interests, conflicts of interest, directorships, consultancies, gifts, external roles, transparency | Use for investigating potential conflicts, researching member finances, or checking declared interests | Returns declared interests including directorships, consultancies, gifts, and other financial interests
+
+        Args:
+            member_id: Parliament member ID. Required: get from member search first. Returns all declared interests.
+
+        Returns:
+            Declared interests including directorships, consultancies, gifts, and other financial interests.
+        """
+        url = f"{INTERESTS_API_BASE}/Interests/?MemberId={member_id}"
+        return await get_result(url)
+
+    @mcp.tool()
+    async def interests_categories() -> str:
+        """Get categories of interests that MPs and Lords must declare in the Register of Interests. Use when you need to understand what types of financial or other interests parliamentarians must declare.
+
+        Returns:
+            Categories of interests that must be declared.
+        """
+        url = f"{INTERESTS_API_BASE}/Categories"
+        return await get_result(url)
+
+    @mcp.tool()
+    async def get_registers_of_interests() -> str:
+        """Get list of published Registers of Interests. Use when you need to see all available interest registers or understand the transparency framework for parliamentary interests.
+
+        Returns:
+            List of published Registers of Interests.
+        """
+        url = f"{INTERESTS_API_BASE}/Registers"
+        return await get_result(url)

uk_parliament_mcp/tools/lords_votes.py

@@ -0,0 +1,149 @@
+"""Lords Votes API tools for House of Lords divisions and voting records."""
+
+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
+
+
+def register_tools(mcp: FastMCP) -> None:
+    """Register Lords votes tools with the MCP server."""
+
+    @mcp.tool()
+    async def search_lords_divisions(search_term: str) -> str:
+        """Search House of Lords voting records (divisions). Use when you want to find how Lords voted on specific issues, bills, or amendments in the upper chamber.
+
+        Args:
+            search_term: Search term for Lords division topics (e.g. 'brexit', 'climate', 'NHS').
+
+        Returns:
+            Lords divisions matching the search term.
+        """
+        url = f"{LORDS_VOTES_API_BASE}/divisions/search?queryParameters.searchTerm={quote(search_term)}"
+        return await get_result(url)
+
+    @mcp.tool()
+    async def get_lords_voting_record_for_member(
+        member_id: int,
+        search_term: str | None = None,
+        include_when_member_was_teller: bool | None = None,
+        start_date: str | None = None,
+        end_date: str | None = None,
+        division_number: int | None = None,
+        skip: int = 0,
+        take: int = 25,
+    ) -> str:
+        """Get complete voting record of a Lord in House of Lords divisions. Use when analyzing how a specific Lord votes, their voting patterns, or their stance on particular issues through their voting history.
+
+        Args:
+            member_id: Parliament member ID to get Lords voting record for.
+            search_term: Optional: search term to filter divisions.
+            include_when_member_was_teller: Optional: include votes where member was a teller.
+            start_date: Optional: start date in YYYY-MM-DD format.
+            end_date: Optional: end date in YYYY-MM-DD format.
+            division_number: Optional: specific division number.
+            skip: Number of records to skip (for pagination).
+            take: Number of records to return (default 25, max 100).
+
+        Returns:
+            Complete Lords voting record for the member.
+        """
+        url = build_url(
+            f"{LORDS_VOTES_API_BASE}/Divisions/membervoting",
+            {
+                "MemberId": member_id,
+                "SearchTerm": search_term,
+                "IncludeWhenMemberWasTeller": include_when_member_was_teller,
+                "StartDate": start_date,
+                "EndDate": end_date,
+                "DivisionNumber": division_number,
+                "skip": skip,
+                "take": take,
+            },
+        )
+        return await get_result(url)
+
+    @mcp.tool()
+    async def get_lords_division_by_id(division_id: int) -> str:
+        """Get detailed information about a specific House of Lords division by ID. Use when you need complete details about a particular Lords vote including who voted content/not content, tellers, and voting totals.
+
+        Args:
+            division_id: Unique Lords division ID number.
+
+        Returns:
+            Detailed information about the Lords division.
+        """
+        url = f"{LORDS_VOTES_API_BASE}/Divisions/{division_id}"
+        return await get_result(url)
+
+    @mcp.tool()
+    async def get_lords_divisions_grouped_by_party(
+        search_term: str | None = None,
+        member_id: int | None = None,
+        start_date: str | None = None,
+        end_date: str | None = None,
+        division_number: int | None = None,
+        include_when_member_was_teller: bool | None = None,
+    ) -> str:
+        """Get House of Lords divisions grouped by party voting patterns. Use when analyzing how different parties voted on issues in the Lords or understanding party-line voting behavior. Shows vote counts by party rather than individual Lords.
+
+        Args:
+            search_term: Optional: search term to filter divisions.
+            member_id: Optional: member ID to filter divisions.
+            start_date: Optional: start date in YYYY-MM-DD format.
+            end_date: Optional: end date in YYYY-MM-DD format.
+            division_number: Optional: specific division number.
+            include_when_member_was_teller: Optional: include when member was a teller.
+
+        Returns:
+            Lords divisions grouped by party.
+        """
+        url = build_url(
+            f"{LORDS_VOTES_API_BASE}/Divisions/groupedbyparty",
+            {
+                "SearchTerm": search_term,
+                "MemberId": member_id,
+                "StartDate": start_date,
+                "EndDate": end_date,
+                "DivisionNumber": division_number,
+                "IncludeWhenMemberWasTeller": include_when_member_was_teller,
+            },
+        )
+        return await get_result(url)
+
+    @mcp.tool()
+    async def get_lords_divisions_search_count(
+        search_term: str | None = None,
+        member_id: int | None = None,
+        start_date: str | None = None,
+        end_date: str | None = None,
+        division_number: int | None = None,
+        include_when_member_was_teller: bool | None = None,
+    ) -> str:
+        """Get total count of House of Lords divisions matching search criteria. Use when you need to know how many Lords divisions match your search parameters before retrieving the actual results.
+
+        Args:
+            search_term: Optional: search term to filter divisions.
+            member_id: Optional: member ID to filter divisions.
+            start_date: Optional: start date in YYYY-MM-DD format.
+            end_date: Optional: end date in YYYY-MM-DD format.
+            division_number: Optional: specific division number.
+            include_when_member_was_teller: Optional: include when member was a teller.
+
+        Returns:
+            Total count of matching Lords divisions.
+        """
+        url = build_url(
+            f"{LORDS_VOTES_API_BASE}/Divisions/searchTotalResults",
+            {
+                "SearchTerm": search_term,
+                "MemberId": member_id,
+                "StartDate": start_date,
+                "EndDate": end_date,
+                "DivisionNumber": division_number,
+                "IncludeWhenMemberWasTeller": include_when_member_was_teller,
+            },
+        )
+        return await get_result(url)