uk-parliament-mcp 1.0.0__tar.gz → 1.0.1__tar.gz

uk_parliament_mcp-1.0.1/CLAUDE.md

@@ -0,0 +1,294 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+UK Parliament MCP Server - A Model Context Protocol server that bridges AI assistants with official UK Parliament data APIs. Built with Python 3.11+, it provides 94 tools covering MPs/Lords, bills, votes, committees, Hansard, and more.
+
+## Installation
+
+```bash
+# From PyPI (recommended)
+pip install uk-parliament-mcp
+
+# Or run without installing
+uvx uk-parliament-mcp
+```
+
+## Development Setup
+
+```bash
+# Create virtual environment and install dependencies
+python -m venv .venv
+source .venv/bin/activate  # Linux/Mac
+# .venv\Scripts\activate   # Windows
+
+pip install -e ".[dev]"
+
+# Run the MCP server (stdio transport)
+python -m uk_parliament_mcp
+
+# Run tests
+pytest
+
+# Type checking
+mypy src/
+
+# Linting
+ruff check src/
+ruff format src/
+```
+
+## CI/CD
+
+GitHub Actions workflows in `.github/workflows/`:
+
+- **ci.yml**: Runs on push/PR - linting (ruff), type checking (mypy), tests (pytest)
+- **publish.yml**: Runs on GitHub Release - builds and publishes to PyPI via Trusted Publishing
+
+**Release process:**
+1. Update version in `src/uk_parliament_mcp/__init__.py`
+2. Commit and push
+3. Create GitHub Release with tag (e.g., `v1.0.1`)
+4. Package auto-publishes to PyPI
+
+## Architecture
+
+```
+AI Assistant ──(MCP/stdio)──> uk_parliament_mcp ──(HTTP)──> UK Parliament APIs
+```
+
+**Key Components:**
+
+- **`__main__.py`**: Entry point. Configures logging to stderr (stdout reserved for MCP protocol), creates and runs the FastMCP server.
+
+- **`server.py`**: FastMCP server setup. Creates the MCP server with server-level instructions and registers all tool modules.
+
+- **`http_client.py`**: HTTP client with retry logic. Provides:
+  - HTTP request handling with 3-retry exponential backoff
+  - 30-second timeout protection
+  - URL building with parameter filtering (`build_url`)
+  - Consistent response format: `{url, data}` or `{url, error, statusCode}`
+
+- **`tools/*.py`**: 15 tool modules (94 total tools) each targeting a specific Parliament API:
+  | Module | API Domain | Purpose |
+  |--------|------------|---------|
+  | composite.py | Multiple APIs | High-level tools combining multiple API calls |
+  | members.py | members-api.parliament.uk | MPs, Lords, constituencies, parties |
+  | bills.py | bills-api.parliament.uk | Legislation, amendments, stages |
+  | commons_votes.py | commonsvotes-api.parliament.uk | Commons divisions |
+  | lords_votes.py | lordsvotes-api.parliament.uk | Lords divisions |
+  | committees.py | committees-api.parliament.uk | Committee info, evidence |
+  | hansard.py | hansard-api.parliament.uk | Parliamentary record |
+  | oral_questions.py | oralquestionsandmotions-api.parliament.uk | EDMs, questions |
+  | interests.py | interests-api.parliament.uk | Register of interests |
+  | now.py | now-api.parliament.uk | Live chamber activity |
+  | whatson.py | whatson-api.parliament.uk | Calendar, sessions |
+  | statutory_instruments.py | statutoryinstruments-api.parliament.uk | Acts, SIs |
+  | treaties.py | treaties-api.parliament.uk | International treaties |
+  | erskine_may.py | erskinemay-api.parliament.uk | Procedure rules |
+  | core.py | N/A | Session management & agent guidance |
+
+- **`context/`**: OpenAPI spec JSON files for each Parliament API (reference documentation)
+
+## Adding New Tools
+
+Follow the established pattern in any `tools/*.py` file:
+
+```python
+"""New API tools for [description]."""
+from urllib.parse import quote
+
+from mcp.server.fastmcp import FastMCP
+
+from uk_parliament_mcp.http_client import build_url, get_result
+
+NEW_API_BASE = "https://api.parliament.uk"
+
+
+def register_tools(mcp: FastMCP) -> None:
+    """Register new tools with the MCP server."""
+
+    @mcp.tool()
+    async def get_something(param: str) -> str:
+        """Action | keywords, synonyms | Use case | Returns format
+
+        Args:
+            param: Description of the parameter.
+
+        Returns:
+            Description of what is returned.
+        """
+        url = f"{NEW_API_BASE}/endpoint?param={quote(param)}"
+        return await get_result(url)
+```
+
+Tool descriptions use a 4-part semantic format: `Action | Keywords | Use case | Returns`
+
+Then register in `server.py`:
+```python
+from uk_parliament_mcp.tools import new_api
+# ...
+new_api.register_tools(mcp)
+```
+
+## Key Conventions
+
+- **House IDs**: 1 = Commons, 2 = Lords
+- **Date format**: YYYY-MM-DD throughout
+- **Pagination**: `skip`/`take` parameters where supported
+- All tools are read-only and idempotent
+- Raw JSON responses from Parliament APIs are passed through (not transformed)
+- Use `build_url(base, params)` for URL construction with parameter filtering
+- Use `await get_result(url)` for HTTP requests with retry logic
+
+## Server Instructions (Automatic Context)
+
+The server provides automatic context to MCP clients via the `instructions` parameter in FastMCP. This means:
+
+- **No initialization required**: Clients receive guidance during MCP handshake without needing to call `hello_parliament()` or `/parliament` first
+- **Automatic behavior**: Per MCP spec, clients may add these instructions to the system prompt
+- **Consistent sessions**: Every session starts with proper guidance about data sources and citation requirements
+
+The instructions use the same `SYSTEM_PROMPT` from `core.py`, ensuring consistency across all initialization methods.
+
+**How clients receive context:**
+1. Client connects to MCP server
+2. Server responds with `instructions` in initialize response
+3. Client incorporates instructions (implementation varies by client)
+4. Assistant automatically knows to use Parliament tools and cite sources
+
+## Agent Skill (MCP Prompt)
+
+The server also provides a `/parliament` agent skill that appears in the "/" command menu in MCP clients like Claude Desktop:
+
+### `/parliament` (or `parliament` prompt)
+Initialize a UK Parliament research session. Invocable as a slash command in Claude Desktop.
+
+**Parameters:**
+- `topic` (optional) - Jump directly to detailed guidance for a specific domain
+
+**Example usage in Claude Desktop:**
+```
+/parliament              # Start session with quick reference
+/parliament members      # Start session + detailed members guidance
+```
+
+This prompt is separate from the guidance **tools** below - prompts appear in the "/" menu and provide session context, while tools are called explicitly during research.
+
+## Composite Tools
+
+High-level tools that combine multiple API calls for common research tasks. Use these first for efficiency:
+
+### `get_mp_profile(name)`
+Get comprehensive MP/Lord profile in one call. Combines member search + biography + interests + voting.
+- Returns: Basic info, biography, registered interests, recent votes
+- Example: `get_mp_profile("Keir Starmer")`
+
+### `check_mp_vote(mp_name, topic)`
+Check how an MP voted on a specific topic. Combines member search + division lookup.
+- Returns: MP info and divisions on the topic where they voted
+- Example: `check_mp_vote("Boris Johnson", "climate")`
+
+### `get_bill_overview(search_term)`
+Get comprehensive bill overview. Combines bill search + details + stages + publications.
+- Returns: Bill details, legislative stages, associated documents
+- Example: `get_bill_overview("Online Safety")`
+
+### `get_committee_summary(topic)`
+Get comprehensive committee summary. Combines committee search + details + evidence + publications.
+- Returns: Committee info, witness testimonies, written submissions, reports
+- Example: `get_committee_summary("Treasury")`
+
+## Agent Guidance Tools
+
+The server also includes guidance **tools** to help AI assistants navigate the 94 available tools:
+
+### `hello_parliament()`
+Initialize a parliamentary research session (optional with server instructions). Returns:
+- System prompt with data source transparency requirements
+- Quick reference of all tool categories with entry points
+- Key conventions (house IDs, date formats, pagination)
+
+### `goodbye_parliament()`
+End the parliamentary session and restore normal assistant behavior.
+
+### `parliament_guide(topic)`
+Get detailed guidance for a specific domain. Available topics:
+- `composite` - 4 high-level tools combining multiple API calls
+- `members` - 26 tools for MPs, Lords, constituencies, parties
+- `bills` - 21 tools for legislation, amendments, stages
+- `votes` - 10 tools for Commons and Lords divisions
+- `committees` - 12 tools for committee info, meetings, evidence
+- `hansard` - Parliamentary record search
+- `questions` - EDMs, oral questions
+- `interests` - Register of Interests
+- `live` - Current activity, calendar (now + whatson)
+- `legislation` - SIs, treaties
+- `procedures` - Erskine May, bill types, stage definitions
+- `all` - Condensed reference of all 94 tools
+- `conventions` - Date formats, house IDs, pagination
+- `workflows` - Overview of common research patterns
+
+### `parliament_workflow(query)`
+Get step-by-step workflow for a research task. Matches queries to predefined patterns:
+- "How did my MP vote on X?" → MP voting workflow
+- "Track bill progress" → Bill tracking workflow
+- "What committee examined X?" → Committee research workflow
+- "Does MP have conflicts of interest?" → Interests workflow
+- "What's happening now?" → Live activity workflow
+- And more (backgrounds, Hansard, elections, EDMs, treaties)
+
+Example usage:
+```
+# Start session
+hello_parliament()
+
+# Get detailed guidance
+parliament_guide("members")
+
+# Plan a research task
+parliament_workflow("How did my MP vote on climate?")
+```
+
+## Dependencies
+
+- mcp (>=1.0.0) - Anthropic's official MCP library
+- httpx (>=0.27.0) - Async HTTP client
+- tenacity (>=8.2.0) - Retry logic (available but manual retry used)
+
+### Dev Dependencies
+
+- pytest (>=8.0.0) - Testing
+- pytest-asyncio (>=0.23.0) - Async test support
+- pytest-httpx (>=0.30.0) - HTTP mocking
+- ruff (>=0.3.0) - Linting and formatting
+- mypy (>=1.8.0) - Type checking
+
+## Project Structure
+
+```
+src/uk_parliament_mcp/
+├── __init__.py
+├── __main__.py         # Entry point
+├── server.py           # FastMCP server setup
+├── http_client.py      # HTTP client with retry
+└── tools/
+    ├── __init__.py
+    ├── core.py         # Session management & guidance (4 tools)
+    ├── composite.py    # High-level composite tools (4 tools)
+    ├── members.py      # Member tools (26 tools)
+    ├── bills.py        # Bills tools (21 tools)
+    ├── committees.py   # Committees tools (12 tools)
+    ├── commons_votes.py    # Commons votes (5 tools)
+    ├── lords_votes.py      # Lords votes (5 tools)
+    ├── hansard.py          # Hansard (1 tool)
+    ├── oral_questions.py   # Questions (3 tools)
+    ├── interests.py        # Interests (3 tools)
+    ├── now.py              # Live activity (2 tools)
+    ├── whatson.py          # Calendar (3 tools)
+    ├── statutory_instruments.py  # SIs (2 tools)
+    ├── treaties.py         # Treaties (1 tool)
+    └── erskine_may.py      # Procedure (1 tool)
+```

{uk_parliament_mcp-1.0.0 → uk_parliament_mcp-1.0.1}/IMPLEMENTATION_PLAN.md

@@ -183,7 +183,7 @@
 
 - [x] Delete `OpenData.Mcp.Server/` folder
 - [x] Delete `OpenDataMcpServer.sln`
-- [ ] Final commit with Python-only project
+- [x] Final commit with Python-only project (03ca315)
 
 ---
 

{uk_parliament_mcp-1.0.0 → uk_parliament_mcp-1.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: uk-parliament-mcp
-Version: 1.0.0
+Version: 1.0.1
 Summary: UK Parliament MCP Server - bridges AI assistants with UK Parliament APIs
 Author: Chris Brooksbank
 License: MIT
@@ -24,35 +24,29 @@ Description-Content-Type: text/markdown
 
 # UK Parliament AI Assistant
 
-This project helps Artificial Intelligence (AI) assistants, like Microsoft Copilot, answer questions using comprehensive official data from the UK Parliament. It acts as a bridge, allowing the AI to access up-to-date, reliable information directly from the source, covering members, bills, voting records, committees, debates, procedures, and much more.
+Access official UK Parliament data through AI assistants. Query MPs, Lords, bills, votes, committees, debates, and more.
 
-## 🔥 ESSENTIAL: System Prompt (Required for Best Results!)
+## Quick Install
 
-**IMPORTANT**: You MUST use the starting system prompt when starting a new conversation. This is critical for accurate responses.
-
-The easiest way to do this is to start all new conversations with the prompt  "Hello Parliament".
-
-Or you can copy and past the following instead : 
-
-```plaintext
-You are a helpful assistant that answers questions using only data from UK Parliament MCP servers.
-
-When the session begins, introduce yourself with a brief message such as:
-
-"Hello! I’m a parliamentary data assistant. I can help answer questions using official data from the UK Parliament MCP APIs. Just ask me something, and I’ll fetch what I can — and I’ll always show you which sources I used."
+```bash
+# Install from PyPI (recommended)
+pip install uk-parliament-mcp
 
-When responding to user queries, you must:
+# Or run without installing
+uvx uk-parliament-mcp
+```
 
-Only retrieve and use data from the MCP API endpoints this server provides.
+## Getting Started
 
-Avoid using any external sources or inferred knowledge.
+**Step 1:** Install the package (see Quick Install above)
 
-After every response, append a list of all MCP API URLs used to generate the answer.
+**Step 2:** Configure your AI assistant (see [Claude Desktop](#add-mcp-server-in-claude-desktop-application) or [VS Code](#add-mcp-server-in-vs-code) setup below)
 
-If no relevant data is available via the MCP API, state that clearly and do not attempt to fabricate a response.
+**Step 3:** Start a parliamentary research session:
+- Use the `/parliament` slash command (in Claude Desktop or compatible MCP clients)
+- Or say "Hello Parliament" to initialize the session
 
-Convert raw data into human-readable summaries while preserving accuracy, but always list the raw URLs used.
-```
+This gives your AI assistant the context it needs to effectively use the 94 available tools.
 
 ## What Can I Ask?
 
@@ -68,42 +62,17 @@ You can ask questions about virtually all aspects of UK Parliament data. Here ar
 *   **Official Documents:** "Are there any statutory instruments about housing?" or "What treaties involve trade agreements?"
 *   **Transparency Data:** "Show register of interests for Treasury ministers" or "What are the declared interests categories?"
 
-## Disconnecting from parliament
-
-Start a new chat session, or to keep context but disconnect from Parliament MCP servers prompt : "Goodbye Parliament"
-
-## How Does It Work?
-
-When you ask a question to an AI assistant connected to this tool, it doesn't just guess the answer. Instead, the assistant uses this project to query the official UK Parliament database and provides a response based on the data it finds.
+## Disconnecting from Parliament
 
-This means the answers you get are more likely to be accurate and based on facts.
+Start a new chat session, or say "Goodbye Parliament" to end the parliamentary session while keeping context.
 
 ---
 
-## Installation and Usage Guide
+## Full Installation Guide
 
-This project makes public UK Parliamentary data accessible to large language models (LLMs/AIs) using the [Model Context Protocol (MCP)](https://www.anthropic.com/news/model-context-protocol).
+This project uses the [Model Context Protocol (MCP)](https://www.anthropic.com/news/model-context-protocol) to make UK Parliamentary data accessible to AI assistants like Claude Desktop and Microsoft Copilot.
 
-It enables AI tools (e.g. Microsoft Copilot) to answer questions about UK Parliamentary data, as long as they support the MCP protocol.
-
-> ✅ This project provides comprehensive coverage of UK Parliamentary data including members, bills, amendments, voting records, committees, debates, procedures, constituencies, and official documents.
-> Additional data sources and endpoints are continuously being added.
-
-Since AI is involved, some responses may be inaccurate. See **Prompting Tips** below to improve reliability.
-
-### Quick Install (Recommended)
-
-Install directly from PyPI:
-
-```bash
-pip install uk-parliament-mcp
-```
-
-Or run without installing using uvx:
-
-```bash
-uvx uk-parliament-mcp
-```
+> **Note**: Since AI is involved, some responses may be inaccurate. See **Prompting Tips** below to improve reliability.
 
 ### Installation from Source
 
@@ -233,9 +202,9 @@ What is happening now in the House of Commons?
 
 ### Prompting Tips
 
-#### ✅ System Prompt
+#### ✅ Initialize Your Session
 
-Always begin your session with the **System Prompt** defined at the top of this guide. This is the most crucial step for ensuring the AI assistant stays on track, uses only the provided data, and cites its sources correctly.
+Always begin your session with `/parliament` or "Hello Parliament". This ensures the AI assistant uses the correct tools and cites its sources properly.
 
 #### 🔄 Clear Context
 

{uk_parliament_mcp-1.0.0 → uk_parliament_mcp-1.0.1}/README.md

@@ -1,34 +1,28 @@
 # UK Parliament AI Assistant
 
-This project helps Artificial Intelligence (AI) assistants, like Microsoft Copilot, answer questions using comprehensive official data from the UK Parliament. It acts as a bridge, allowing the AI to access up-to-date, reliable information directly from the source, covering members, bills, voting records, committees, debates, procedures, and much more.
+Access official UK Parliament data through AI assistants. Query MPs, Lords, bills, votes, committees, debates, and more.
 
-## 🔥 ESSENTIAL: System Prompt (Required for Best Results!)
+## Quick Install
 
-**IMPORTANT**: You MUST use the starting system prompt when starting a new conversation. This is critical for accurate responses.
-
-The easiest way to do this is to start all new conversations with the prompt  "Hello Parliament".
-
-Or you can copy and past the following instead : 
-
-```plaintext
-You are a helpful assistant that answers questions using only data from UK Parliament MCP servers.
-
-When the session begins, introduce yourself with a brief message such as:
-
-"Hello! I’m a parliamentary data assistant. I can help answer questions using official data from the UK Parliament MCP APIs. Just ask me something, and I’ll fetch what I can — and I’ll always show you which sources I used."
+```bash
+# Install from PyPI (recommended)
+pip install uk-parliament-mcp
 
-When responding to user queries, you must:
+# Or run without installing
+uvx uk-parliament-mcp
+```
 
-Only retrieve and use data from the MCP API endpoints this server provides.
+## Getting Started
 
-Avoid using any external sources or inferred knowledge.
+**Step 1:** Install the package (see Quick Install above)
 
-After every response, append a list of all MCP API URLs used to generate the answer.
+**Step 2:** Configure your AI assistant (see [Claude Desktop](#add-mcp-server-in-claude-desktop-application) or [VS Code](#add-mcp-server-in-vs-code) setup below)
 
-If no relevant data is available via the MCP API, state that clearly and do not attempt to fabricate a response.
+**Step 3:** Start a parliamentary research session:
+- Use the `/parliament` slash command (in Claude Desktop or compatible MCP clients)
+- Or say "Hello Parliament" to initialize the session
 
-Convert raw data into human-readable summaries while preserving accuracy, but always list the raw URLs used.
-```
+This gives your AI assistant the context it needs to effectively use the 94 available tools.
 
 ## What Can I Ask?
 
@@ -44,42 +38,17 @@ You can ask questions about virtually all aspects of UK Parliament data. Here ar
 *   **Official Documents:** "Are there any statutory instruments about housing?" or "What treaties involve trade agreements?"
 *   **Transparency Data:** "Show register of interests for Treasury ministers" or "What are the declared interests categories?"
 
-## Disconnecting from parliament
-
-Start a new chat session, or to keep context but disconnect from Parliament MCP servers prompt : "Goodbye Parliament"
-
-## How Does It Work?
-
-When you ask a question to an AI assistant connected to this tool, it doesn't just guess the answer. Instead, the assistant uses this project to query the official UK Parliament database and provides a response based on the data it finds.
+## Disconnecting from Parliament
 
-This means the answers you get are more likely to be accurate and based on facts.
+Start a new chat session, or say "Goodbye Parliament" to end the parliamentary session while keeping context.
 
 ---
 
-## Installation and Usage Guide
+## Full Installation Guide
 
-This project makes public UK Parliamentary data accessible to large language models (LLMs/AIs) using the [Model Context Protocol (MCP)](https://www.anthropic.com/news/model-context-protocol).
+This project uses the [Model Context Protocol (MCP)](https://www.anthropic.com/news/model-context-protocol) to make UK Parliamentary data accessible to AI assistants like Claude Desktop and Microsoft Copilot.
 
-It enables AI tools (e.g. Microsoft Copilot) to answer questions about UK Parliamentary data, as long as they support the MCP protocol.
-
-> ✅ This project provides comprehensive coverage of UK Parliamentary data including members, bills, amendments, voting records, committees, debates, procedures, constituencies, and official documents.
-> Additional data sources and endpoints are continuously being added.
-
-Since AI is involved, some responses may be inaccurate. See **Prompting Tips** below to improve reliability.
-
-### Quick Install (Recommended)
-
-Install directly from PyPI:
-
-```bash
-pip install uk-parliament-mcp
-```
-
-Or run without installing using uvx:
-
-```bash
-uvx uk-parliament-mcp
-```
+> **Note**: Since AI is involved, some responses may be inaccurate. See **Prompting Tips** below to improve reliability.
 
 ### Installation from Source
 
@@ -209,9 +178,9 @@ What is happening now in the House of Commons?
 
 ### Prompting Tips
 
-#### ✅ System Prompt
+#### ✅ Initialize Your Session
 
-Always begin your session with the **System Prompt** defined at the top of this guide. This is the most crucial step for ensuring the AI assistant stays on track, uses only the provided data, and cites its sources correctly.
+Always begin your session with `/parliament` or "Hello Parliament". This ensures the AI assistant uses the correct tools and cites its sources properly.
 
 #### 🔄 Clear Context