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

uk_parliament_mcp-1.1.0/.github/dependabot.yml

@@ -0,0 +1,12 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

{uk_parliament_mcp-1.0.0 → uk_parliament_mcp-1.1.0}/.github/workflows/ci.yml

@@ -20,6 +20,7 @@ jobs:
         uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
+          cache: 'pip'
 
       - name: Install dependencies
         run: |
@@ -34,5 +35,13 @@ jobs:
       - name: Type check with mypy
         run: mypy src/
 
-      - name: Run tests
-        run: pytest
+      - name: Run tests with coverage
+        run: pytest --cov=uk_parliament_mcp --cov-report=xml --cov-report=term-missing
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        with:
+          files: ./coverage.xml
+          fail_ci_if_error: false
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

uk_parliament_mcp-1.1.0/.pre-commit-config.yaml

@@ -0,0 +1,14 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.3.0
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.8.0
+    hooks:
+      - id: mypy
+        additional_dependencies: [types-all]
+        args: [--strict]

uk_parliament_mcp-1.1.0/AGENTS.md

@@ -0,0 +1,56 @@
+# AGENTS.md - Operational Guide
+
+Keep this file under 60 lines. It's loaded every iteration.
+
+## Build Commands
+
+```bash
+# Install dependencies (dev mode)
+pip install -e ".[dev]"
+
+# Run the MCP server
+python -m uk_parliament_mcp
+```
+
+## Test Commands
+
+```bash
+pytest                              # Run all tests
+pytest tests/test_tools/            # Run tool tests only
+pytest --cov=uk_parliament_mcp      # Run with coverage
+```
+
+## Validation (run before committing)
+
+```bash
+ruff check src/                     # Lint check
+ruff format --check src/            # Format check
+mypy src/                           # Type check
+pytest                              # Tests
+
+# All at once:
+ruff check src/ && ruff format --check src/ && mypy src/ && pytest
+```
+
+## Fixing Issues
+
+```bash
+ruff check src/ --fix               # Auto-fix lint issues
+ruff format src/                    # Auto-format code
+```
+
+## Project Notes
+
+- Python 3.11+ required
+- Tool descriptions use semantic format: `Action | Keywords | Use case | Returns`
+- House IDs: 1 = Commons, 2 = Lords
+- Date format: YYYY-MM-DD
+- API base URLs should be in `src/uk_parliament_mcp/config.py` (after Phase 2.1)
+- Test files mirror source structure: `tools/members.py` -> `test_tools/test_members.py`
+
+## Key Files
+
+- `docs/IMPROVEMENT_PLAN.md` - Master improvement plan
+- `docs/PHASE*.md` - Detailed phase specifications
+- `IMPLEMENTATION_PLAN_IMPROVEMENTS.md` - Current task tracking
+- `CLAUDE.md` - Project documentation for Claude Code

uk_parliament_mcp-1.1.0/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.1.0] - 2026-02-03
+
+### Added
+- Centralized API configuration in `config.py`
+- TypedDict for HTTP client response types
+- Expanded test coverage for all tool modules
+- pytest-cov for code coverage tracking
+- CHANGELOG.md and CONTRIBUTING.md
+- README badges (PyPI version, Python 3.11+, MIT License, CI status)
+- README table of contents
+- Configuration decision matrix in README
+- Collapsible example prompt sections in README
+
+### Changed
+- Restructured README with improved organization and navigation
+- Corrected tool count from 94 to 92 in all documentation
+- Safer dictionary access patterns in composite tools
+
+### Removed
+- Unused tenacity dependency
+
+## [1.0.1] - 2026-02-01
+
+### Added
+- Server-level instructions for automatic context via MCP `instructions` parameter
+- Composite tools documentation in CLAUDE.md
+- Composite tools for common workflows (`get_mp_profile`, `check_mp_vote`, `get_bill_overview`, `get_committee_summary`)
+- Agent guidance system with `/parliament` MCP prompt
+- `parliament_guide()` and `parliament_workflow()` tools for navigating available tools
+
+### Changed
+- Improved documentation clarity in CLAUDE.md
+- Enhanced LLM efficiency with high-level composite tools
+
+### Fixed
+- Getting Started section references to configuration steps
+
+## [1.0.0] - 2026-01-28
+
+### Added
+- Initial Python release of UK Parliament MCP Server
+- 92 tools covering 15 Parliament APIs (members, bills, votes, committees, Hansard, etc.)
+- Support for Claude Desktop and VS Code via MCP protocol
+- HTTP client with automatic retry logic and timeout protection
+- Comprehensive documentation in CLAUDE.md and README.md
+- CI/CD pipeline with GitHub Actions (linting, type checking, tests)
+- PyPI publishing via Trusted Publishing
+- Test infrastructure with pytest and pytest-asyncio
+- Type checking with mypy
+- Code quality enforcement with ruff
+
+### Changed
+- Migrated from C# implementation to Python 3.11+
+- Adopted FastMCP framework for simplified MCP server development

uk_parliament_mcp-1.1.0/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 92 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 (92 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 92 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` - 25 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 92 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 (25 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.1.0/CONTRIBUTING.md

@@ -0,0 +1,119 @@
+# Contributing to UK Parliament MCP
+
+Thank you for your interest in contributing! This document provides guidelines and instructions.
+
+## Development Setup
+
+1. **Clone the repository:**
+   ```bash
+   git clone https://github.com/ChrisBrooksbank/uk-parliament-mcp-lab.git
+   cd uk-parliament-mcp-lab
+   ```
+
+2. **Create virtual environment:**
+   ```bash
+   python -m venv .venv
+   source .venv/bin/activate  # Linux/Mac
+   .venv\Scripts\activate     # Windows
+   ```
+
+3. **Install with dev dependencies:**
+   ```bash
+   pip install -e ".[dev]"
+   ```
+
+## Code Style
+
+We use automated tools to maintain consistency:
+
+- **Ruff** for linting and formatting
+- **MyPy** for type checking
+
+Run before committing:
+```bash
+ruff check src/
+ruff format src/
+mypy src/
+```
+
+## Adding New Tools
+
+1. Create or update a module in `src/uk_parliament_mcp/tools/`
+2. Follow the established pattern:
+
+```python
+"""Description of API tools."""
+from mcp.server.fastmcp import FastMCP
+from uk_parliament_mcp.config import API_BASE
+from uk_parliament_mcp.http_client import build_url, get_result
+
+def register_tools(mcp: FastMCP) -> None:
+    """Register tools with the MCP server."""
+
+    @mcp.tool()
+    async def my_new_tool(param: str) -> str:
+        """Action | keywords | Use case | Returns format
+
+        Args:
+            param: Description.
+
+        Returns:
+            What is returned.
+        """
+        url = f"{API_BASE}/endpoint?param={param}"
+        return await get_result(url)
+```
+
+3. Register in `server.py`:
+```python
+from uk_parliament_mcp.tools import my_module
+my_module.register_tools(mcp)
+```
+
+4. Add tests in `tests/test_tools/test_my_module.py`
+
+5. Update documentation in `CLAUDE.md`
+
+## Testing
+
+Run the test suite:
+```bash
+pytest
+```
+
+With coverage:
+```bash
+pytest --cov=uk_parliament_mcp --cov-report=term-missing
+```
+
+**Requirements:**
+- All new tools must have tests
+- Tests should verify URL construction
+- Target 80%+ coverage
+
+## Pull Request Process
+
+1. Create a feature branch from `main`
+2. Make your changes
+3. Ensure all checks pass:
+   ```bash
+   ruff check src/
+   ruff format --check src/
+   mypy src/
+   pytest
+   ```
+4. Update documentation if needed
+5. Submit PR with clear description
+
+## Reporting Issues
+
+Please include:
+- Python version
+- OS and version
+- Steps to reproduce
+- Expected vs actual behavior
+- Error messages if applicable
+
+## Questions?
+
+Open an issue with the "question" label.

{uk_parliament_mcp-1.0.0 → uk_parliament_mcp-1.1.0}/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)
 
 ---
 
@@ -223,5 +223,60 @@
 ## Reference Files
 
 - Migration spec: `specs/python-migration-spec.md`
-- C# reference: `OpenData.Mcp.Server/Tools/*.cs`
+- Agent guidance spec: `specs/agent-guidance-spec.md`
+- Improvement spec: `specs/improvement-spec.md`
+- **v2.0 Improvements spec: `specs/v2-improvements-spec.md`**
 - Operational guide: `AGENTS.md`
+
+---
+
+## v2.0 Improvements (spec: v2-improvements-spec.md)
+
+### Phase 1: Foundation (P1)
+
+- [ ] Create `normalize_house()` helper in validators.py (spec: 1.1)
+- [ ] Update `parties_list_by_house()` to use normalize_house (spec: 1.1)
+- [ ] Update `search_members()` house parameter (spec: 1.1)
+- [ ] Update `get_member_registered_interests()` house parameter (spec: 1.1)
+- [ ] Update `get_member_voting()` house parameter (spec: 1.1)
+- [ ] Update `search_hansard()` house parameter (spec: 1.1)
+- [ ] Update `search_calendar()` house parameter (spec: 1.1)
+- [ ] Update `get_non_sitting_days()` house parameter (spec: 1.1)
+- [ ] Update `get_sittings()` house parameter (spec: 1.1)
+- [ ] Enable caching for `bill_types()` (spec: 1.2)
+- [ ] Enable caching for `bill_stages()` (spec: 1.2)
+- [ ] Enable caching for `parties_list_by_house()` (spec: 1.2)
+- [ ] Enable caching for `get_publication_types()` (spec: 1.2)
+- [ ] Enable caching for `get_answering_bodies()` (spec: 1.2)
+- [ ] Add `validate_date()` function (spec: 1.3)
+- [ ] Add `validate_positive_int()` function (spec: 1.3)
+- [ ] Add `validate_pagination()` function (spec: 1.3)
+- [ ] Apply validation to tools with date parameters (spec: 1.3)
+- [ ] Apply validation to tools with ID parameters (spec: 1.3)
+
+### Phase 2: Discoverability (P2)
+
+- [ ] Add cross-references to members.py docstrings (spec: 2.1)
+- [ ] Add cross-references to bills.py docstrings (spec: 2.1)
+- [ ] Add cross-references to committees.py docstrings (spec: 2.1)
+- [ ] Add "Uses" section to composite.py tools (spec: 2.2)
+
+### Phase 3: New Capabilities (P2)
+
+- [ ] Implement `compare_mp_voting()` composite tool (spec: 3.1)
+- [ ] Implement `search_parliament()` aggregated search (spec: 3.2)
+- [ ] Implement `get_bills_by_sponsor()` tool (spec: 3.3)
+- [ ] Add tests for new composite tools
+
+### Phase 4: Code Quality (P3)
+
+- [ ] Standardize oral_questions.py docstrings (spec: 4.1)
+- [ ] Standardize erskine_may.py docstrings (spec: 4.1)
+- [ ] Standardize interests.py docstrings (spec: 4.1)
+- [ ] Add error recovery guidance to composite tools (spec: 4.2)
+
+### Phase 5: Project Quality (P4)
+
+- [ ] Create LICENSE file (spec: 5.1)
+- [ ] Create CHANGELOG.md (spec: 5.2)
+- [ ] Create .pre-commit-config.yaml (spec: 5.3)