uk-parliament-mcp 1.0.0__tar.gz

uk_parliament_mcp-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: |
+          ruff check src/
+          ruff format --check src/
+
+      - name: Type check with mypy
+        run: mypy src/
+
+      - name: Run tests
+        run: pytest

uk_parliament_mcp-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,47 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # Required for Trusted Publishing
+
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

uk_parliament_mcp-1.0.0/.gitignore

@@ -0,0 +1,48 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# Type checking
+.mypy_cache/
+
+# Linting
+.ruff_cache/
+
+# Local settings
+.claude/settings.local.json

uk_parliament_mcp-1.0.0/.python-version

@@ -0,0 +1 @@
+3.11

uk_parliament_mcp-1.0.0/AGENTS.md

@@ -0,0 +1,73 @@
+# AGENTS.md - Operational Reference
+
+## Project: UK Parliament MCP Server (Python Migration)
+
+### Quick Reference
+
+```bash
+# Create virtual environment
+uv venv
+.venv\Scripts\activate     # Windows
+source .venv/bin/activate  # Linux/Mac
+
+# Install dependencies
+uv pip install -e ".[dev]"
+
+# Run MCP server
+python -m uk_parliament_mcp
+
+# Run tests
+pytest
+
+# Type checking
+mypy src/
+
+# Linting
+ruff check src/
+ruff format src/
+
+# All checks (must pass before commit)
+pytest && mypy src/ && ruff check src/
+```
+
+### Project Structure
+
+```
+uk-parliament-mcp-lab/
+├── specs/python-migration-spec.md    # Migration specification
+├── src/uk_parliament_mcp/            # Python package
+│   ├── __main__.py                   # Entry point
+│   ├── server.py                     # FastMCP setup
+│   ├── http_client.py                # HTTP with retry
+│   └── tools/                        # 14 tool modules
+├── tests/                            # pytest tests
+├── context/                          # API spec JSONs
+└── OpenData.Mcp.Server/              # C# reference (DO NOT DELETE)
+```
+
+### Key Conventions
+
+- House IDs: 1 = Commons, 2 = Lords
+- Date format: YYYY-MM-DD
+- All tools are read-only and idempotent
+- Tool response format: `{"url": "...", "data": "..."}` or `{"url": "...", "error": "...", "statusCode": N}`
+
+### Tool Count Target
+
+86 tools across 14 modules. Verify with:
+```python
+server = create_server()
+assert len(list(server.list_tools())) == 86
+```
+
+### C# Reference
+
+Keep `OpenData.Mcp.Server/` as reference during migration. Only delete after all 86 tools verified working.
+
+### Commit Format
+
+```
+feat: Add {module} tools ({count} tools)
+fix: Correct {issue} in {module}
+test: Add tests for {module}
+```

uk_parliament_mcp-1.0.0/CLAUDE.md

@@ -0,0 +1,160 @@
+# 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 86 tools covering MPs/Lords, bills, votes, committees, Hansard, and more.
+
+## Build Commands
+
+```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/
+```
+
+## 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 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`**: 14 tool modules (86 total tools) each targeting a specific Parliament API:
+  | Module | API Domain | Purpose |
+  |--------|------------|---------|
+  | 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 prompts |
+
+- **`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
+
+## 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 (2 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.0.0/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,227 @@
+# Implementation Plan
+
+> Generated by Ralph Wiggum planning phase
+
+## Status Summary
+
+- **Total tools required:** 86
+- **Tools implemented:** 86
+- **Core infrastructure:** COMPLETE
+- **Python files exist:** YES
+
+## Priority 1: Project Setup
+
+- [x] Create `pyproject.toml` with dependencies (mcp, httpx, tenacity, pytest, ruff, mypy)
+- [x] Create `.python-version` file (3.11)
+- [x] Create `src/uk_parliament_mcp/__init__.py`
+- [x] Create `src/uk_parliament_mcp/tools/__init__.py`
+
+## Priority 2: Core Infrastructure
+
+- [x] Create `src/uk_parliament_mcp/http_client.py` - HTTP client with retry logic
+- [x] Create `src/uk_parliament_mcp/server.py` - FastMCP server setup
+- [x] Create `src/uk_parliament_mcp/__main__.py` - Entry point
+- [x] Verify server starts: `python -m uk_parliament_mcp`
+
+## Priority 3: Core Tools (2 tools)
+
+- [x] `tools/core.py` - hello_parliament
+- [x] `tools/core.py` - goodbye_parliament
+
+## Priority 4: Members Tools (25 tools)
+
+- [x] `tools/members.py` - get_member_by_name
+- [x] `tools/members.py` - get_answering_bodies
+- [x] `tools/members.py` - get_member_by_id
+- [x] `tools/members.py` - edms_for_member_id
+- [x] `tools/members.py` - parties_list_by_house
+- [x] `tools/members.py` - get_departments
+- [x] `tools/members.py` - get_contributions
+- [x] `tools/members.py` - get_constituencies
+- [x] `tools/members.py` - get_election_results_for_constituency
+- [x] `tools/members.py` - get_lords_interests_staff
+- [x] `tools/members.py` - get_members_biography
+- [x] `tools/members.py` - get_members_contact
+- [x] `tools/members.py` - search_members
+- [x] `tools/members.py` - search_members_historical
+- [x] `tools/members.py` - get_member_experience
+- [x] `tools/members.py` - get_member_focus
+- [x] `tools/members.py` - get_member_registered_interests
+- [x] `tools/members.py` - get_member_staff
+- [x] `tools/members.py` - get_member_synopsis
+- [x] `tools/members.py` - get_member_voting
+- [x] `tools/members.py` - get_member_written_questions
+- [x] `tools/members.py` - get_members_history
+- [x] `tools/members.py` - get_member_latest_election_result
+- [x] `tools/members.py` - get_member_portrait_url
+- [x] `tools/members.py` - get_member_thumbnail_url
+
+## Priority 5: Bills Tools (21 tools)
+
+- [x] `tools/bills.py` - get_recently_updated_bills
+- [x] `tools/bills.py` - search_bills
+- [x] `tools/bills.py` - bill_types
+- [x] `tools/bills.py` - bill_stages
+- [x] `tools/bills.py` - get_bill_by_id
+- [x] `tools/bills.py` - get_bill_stages
+- [x] `tools/bills.py` - get_bill_stage_details
+- [x] `tools/bills.py` - get_bill_stage_amendments
+- [x] `tools/bills.py` - get_amendment_by_id
+- [x] `tools/bills.py` - get_bill_stage_ping_pong_items
+- [x] `tools/bills.py` - get_ping_pong_item_by_id
+- [x] `tools/bills.py` - get_bill_publications
+- [x] `tools/bills.py` - get_bill_stage_publications
+- [x] `tools/bills.py` - get_publication_document
+- [x] `tools/bills.py` - get_bill_news_articles
+- [x] `tools/bills.py` - get_all_bills_rss
+- [x] `tools/bills.py` - get_public_bills_rss
+- [x] `tools/bills.py` - get_private_bills_rss
+- [x] `tools/bills.py` - get_bill_rss
+- [x] `tools/bills.py` - get_publication_types
+- [x] `tools/bills.py` - get_sittings
+
+## Priority 6: Committees Tools (12 tools)
+
+- [x] `tools/committees.py` - get_committee_meetings
+- [x] `tools/committees.py` - search_committees
+- [x] `tools/committees.py` - get_committee_types
+- [x] `tools/committees.py` - get_committee_by_id
+- [x] `tools/committees.py` - get_events
+- [x] `tools/committees.py` - get_event_by_id
+- [x] `tools/committees.py` - get_committee_events
+- [x] `tools/committees.py` - get_committee_members
+- [x] `tools/committees.py` - get_publications
+- [x] `tools/committees.py` - get_publication_by_id
+- [x] `tools/committees.py` - get_written_evidence
+- [x] `tools/committees.py` - get_oral_evidence
+
+## Priority 7: Commons Votes Tools (5 tools)
+
+- [x] `tools/commons_votes.py` - search_commons_divisions
+- [x] `tools/commons_votes.py` - get_commons_voting_record_for_member
+- [x] `tools/commons_votes.py` - get_commons_division_by_id
+- [x] `tools/commons_votes.py` - get_commons_divisions_grouped_by_party
+- [x] `tools/commons_votes.py` - get_commons_divisions_search_count
+
+## Priority 8: Lords Votes Tools (5 tools)
+
+- [x] `tools/lords_votes.py` - search_lords_divisions
+- [x] `tools/lords_votes.py` - get_lords_voting_record_for_member
+- [x] `tools/lords_votes.py` - get_lords_division_by_id
+- [x] `tools/lords_votes.py` - get_lords_divisions_grouped_by_party
+- [x] `tools/lords_votes.py` - get_lords_divisions_search_count
+
+## Priority 9: Hansard Tools (1 tool)
+
+- [x] `tools/hansard.py` - search_hansard
+
+## Priority 10: Oral Questions Tools (3 tools)
+
+- [x] `tools/oral_questions.py` - get_recently_tabled_edms
+- [x] `tools/oral_questions.py` - search_early_day_motions
+- [x] `tools/oral_questions.py` - search_oral_question_times
+
+## Priority 11: Interests Tools (3 tools)
+
+- [x] `tools/interests.py` - search_roi
+- [x] `tools/interests.py` - interests_categories
+- [x] `tools/interests.py` - get_registers_of_interests
+
+## Priority 12: Now Tools (2 tools)
+
+- [x] `tools/now.py` - happening_now_in_commons
+- [x] `tools/now.py` - happening_now_in_lords
+
+## Priority 13: Whats On Tools (3 tools)
+
+- [x] `tools/whatson.py` - search_calendar
+- [x] `tools/whatson.py` - get_sessions
+- [x] `tools/whatson.py` - get_non_sitting_days
+
+## Priority 14: Statutory Instruments Tools (2 tools)
+
+- [x] `tools/statutory_instruments.py` - search_statutory_instruments
+- [x] `tools/statutory_instruments.py` - search_acts_of_parliament
+
+## Priority 15: Treaties Tools (1 tool)
+
+- [x] `tools/treaties.py` - search_treaties
+
+## Priority 16: Erskine May Tools (1 tool)
+
+- [x] `tools/erskine_may.py` - search_erskine_may
+
+## Priority 17: Testing
+
+- [x] Create `tests/__init__.py`
+- [x] Create `tests/conftest.py` - pytest fixtures
+- [x] Create `tests/test_http_client.py` - HTTP client unit tests
+- [x] Create `tests/test_tools/__init__.py`
+- [x] Create `tests/test_tools/test_core.py`
+- [x] Run `pytest` - all 24 tests pass
+- [x] Run `mypy src/` - type checking passes (no issues in 19 files)
+- [x] Run `ruff check src/` - linting passes
+- [x] Verified all Python syntax via ast.parse() (19 source files, 5 test files)
+
+## Priority 18: Documentation & Config
+
+- [x] Update `CLAUDE.md` for Python development
+- [x] Update `README.md` for Python installation
+- [x] Create `config/claude_desktop_config.json.example`
+- [x] Create `config/vscode_mcp_config.json.example`
+
+## Priority 19: Final Verification
+
+- [x] Server starts: `python -m uk_parliament_mcp`
+- [x] Verify 86 tools registered
+- [x] Test `hello_parliament` returns system prompt
+- [x] Test `get_member_by_name("Keir Starmer")` returns valid JSON (Sir Keir Starmer, Labour)
+- [x] Test `search_bills("climate")` returns valid JSON (20 bills found)
+- [ ] Configure Claude Desktop and verify working
+
+## Priority 20: Cleanup (ONLY after verification)
+
+- [x] Delete `OpenData.Mcp.Server/` folder
+- [x] Delete `OpenDataMcpServer.sln`
+- [ ] Final commit with Python-only project
+
+---
+
+## Task Count Summary
+
+| Priority | Category | Tasks | Status |
+|----------|----------|-------|--------|
+| 1 | Project Setup | 4 | COMPLETE |
+| 2 | Core Infrastructure | 4 | COMPLETE |
+| 3 | Core Tools | 2 | COMPLETE |
+| 4 | Members Tools | 25 | COMPLETE |
+| 5 | Bills Tools | 21 | COMPLETE |
+| 6 | Committees Tools | 12 | COMPLETE |
+| 7 | Commons Votes Tools | 5 | COMPLETE |
+| 8 | Lords Votes Tools | 5 | COMPLETE |
+| 9 | Hansard Tools | 1 | COMPLETE |
+| 10 | Oral Questions Tools | 3 | COMPLETE |
+| 11 | Interests Tools | 3 | COMPLETE |
+| 12 | Now Tools | 2 | COMPLETE |
+| 13 | Whats On Tools | 3 | COMPLETE |
+| 14 | Statutory Instruments Tools | 2 | COMPLETE |
+| 15 | Treaties Tools | 1 | COMPLETE |
+| 16 | Erskine May Tools | 1 | COMPLETE |
+| 17 | Testing | 8 | COMPLETE |
+| 18 | Documentation | 4 | COMPLETE |
+| 19 | Verification | 6 | 5/6 (Claude Desktop pending) |
+| 20 | Cleanup | 3 | 2/3 (commit pending) |
+| **Total** | | **114** | |
+
+---
+
+## Next Action
+
+1. **Configure Claude Desktop** and verify MCP server works end-to-end
+2. **Priority 20: Cleanup** - Delete old C# files after verification
+
+## Reference Files
+
+- Migration spec: `specs/python-migration-spec.md`
+- C# reference: `OpenData.Mcp.Server/Tools/*.cs`
+- Operational guide: `AGENTS.md`