Parliament MCP Server

# Parliament MCP Server An MCP server that roughly maps onto a subset of https://developer.parliament.uk/, as well as offering additional semantic search capabilities. ## Architecture This project provides: - **MCP Server**: FastMCP-based server - **Python package**: A small python package for querying and loading parliamentary data from https://developer.parliament.uk/ into Qdrant - **Qdrant**: Vector database for semantic search over Hansard and Parliamentary Questions data. - **Claude Integration**: Connect to Claude Desktop via `mcp-remote` proxy ## Features ### MCP Tools Available The MCP Server exposes 13 tools to assist in parliamentary research: #### Members & Elections 1. **`get_election_results`** - Get election results for constituencies or specific members 2. **`search_members`** - Search for members of the Commons or Lords by various criteria (includes location/postcode search) 3. **`get_detailed_member_information`** - Get comprehensive member information including biography, contact, interests, voting record, and committee membership #### Parliamentary Structure 4. **`get_state_of_the_parties`** - Get state of the parties for a house on a specific date 5. **`list_ministerial_roles`** - Get exhaustive list of all government or opposition posts and their current holders 6. **`get_departments`** - Get reference data for government departments #### Committees 7. **`list_all_committees`** - List all parliamentary committees by status and house 8. **`get_committee_details`** - Get comprehensive committee information including members, publications, evidence, and upcoming events 9. **`get_committee_document`** - Retrieve committee documents including oral evidence, written evidence, and publications #### Parliamentary Business 10. **`search_parliamentary_questions`** - Search Parliamentary Written Questions (PQs) by topic, date, party, or member 11. **`search_debate_titles`** - Search through debate titles to find relevant debates 12. **`find_relevant_contributors`** - Find members who have contributed most on specific topics 13. **`search_contributions`** - Search Hansard parliamentary records for actual spoken contributions during debates ## Quick Start (local qdrant) You will need - Docker and Docker Compose - Node.js (for mcp-remote) - Claude Desktop (or another MCP client) - **Azure OpenAI account with API access** Create a `.env` file by copying the `.env.example` in the project root and replace the necessary variables. After configuring your `.env` file, run the following command for a one shot setup of the MCP server and the Qdrant database with some example data from June 2025. ```bash make dev_setup_from_scratch ``` Once this is run, you can connect to the MCP server using this config ```bash # Add this to your Claude Desktop config, or another MCP client: # On macOS Claude Desktop config is located at `~/Library/Application\ Support/Claude/claude_desktop_config.json` { "mcpServers": { "parliament-mcp": { "command": "npx", "args": ["mcp-remote", "http://localhost:8080/mcp/", "--allow-http", "--debug"] } } } ``` ## Manual Setup ### 1. Clone, setup environment, and start services #### Note on Qdrant Configuration The system supports connecting to Qdrant: 1. **Local/Self-hosted**: Use `QDRANT_URL` (defaults to localhost:6333) 2. **Qdrant Cloud**: Use `QDRANT_URL` and `QDRANT_API_KEY` for cloud deployments ```bash # Clone the repo git clone git@github.com:i-dot-ai/parliament-mcp.git cd parliament-mcp # Set up the environment and complete the .env file cp .env.example .env nano .env # Start Qdrant and MCP server docker-compose up --build ``` The services will be available at: - **MCP Server**: `http://localhost:8080/mcp/` - **Qdrant**: `http://localhost:6333` ### 3. Initialize Qdrant and Load Data ```bash # Initialise Qdrant docker compose exec mcp-server uv run parliament-mcp --log-level INFO init-qdrant # Load 2025-06-23 to 2025-06-27 hansard data docker compose exec mcp-server uv run parliament-mcp load-data hansard --from-date 2025-06-23 --to-date 2025-06-27 # Load 2025-06-23 to 2025-06-27 parliamentary questions docker compose exec mcp-server uv run parliament-mcp --log-level WARNING load-data parliamentary-questions --from-date 2025-06-23 --to-date 2025-06-27 ``` ### 2. Install mcp-remote ```bash npm install -g mcp-remote ``` ### 3. Configure Claude Desktop Add the following to your Claude Desktop configuration file: **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows**: `%APPDATA%/Claude/claude_desktop_config.json` ```json { "mcpServers": { "parliament-mcp": { "command": "npx", "args": [ "mcp-remote", "http://localhost:8080/mcp/", "--allow-http", "--debug" ] } } } ``` You can also generate this configuration automatically: ```bash make mcp_claude_config ``` ### 4. Restart Claude Desktop Claude should now have access to the Parliament MCP tools. ## Development ### Prerequisites for Local Development - Python >= 3.12 - [uv](https://docs.astral.sh/uv/) (Python package manager) - Docker and Docker Compose - Node.js (for mcp-remote) ### Local Development Setup 1. **Install uv** (if not already installed): ```bash curl -LsSf https://astral.sh/uv/install.sh | sh ``` 2. **Clone and set up the project**: ```bash git clone <repository> cd parliament-mcp # Install dependencies with uv uv sync --extra dev ``` 3. **Available Make commands**: ```bash make install # Install all dependencies make test # Run tests make test_integration # Run integration tests (slow on first run) make lint # Check code formatting make format # Format and fix code make safe # Run security checks # Pre-commit hooks make pre-commit-install # Install pre-commit hooks make pre-commit # Run pre-commit on all files # Docker operations make run # Start services with Docker Compose make stop # Stop Docker services make logs # View MCP server logs # Development helpers make mcp_test # Test MCP server connection make qdrant_health # Check Qdrant health ``` 4. **Run the MCP server locally**: ```bash make run_mcp_server # Or directly with uv: uv run parliament-mcp serve ``` ### Project Structure ``` parliament-mcp/ ├── parliament_mcp/ # Main Python package │ ├── cli.py # CLI interface │ ├── models.py # Data models │ ├── mcp_server/ # MCP server implementation │ │ ├── api.py # Core API endpoints and search tools │ │ ├── committees.py # Committee-related tools and handlers │ │ ├── members.py # Member-related tools and handlers │ │ ├── qdrant_query_handler.py # Qdrant search handlers │ │ ├── main.py # FastAPI application setup │ │ └── utils.py # Utility functions │ └── ... # Other modules ├── tests/ # Test suite │ ├── mcp_server/ # MCP server tests │ └── ... # Other tests ├── Dockerfile.mcp-server # MCP server container configuration ├── docker-compose.yaml # Service orchestration └── README.md # This file ``` ### CLI Commands The project includes a unified CLI for data management and server operations: ```bash # Initialize Qdrant collections parliament-mcp init-qdrant # Run the MCP server parliament-mcp serve # Load data with flexible date parsing parliament-mcp load-data hansard --from-date "3 days ago" --to-date "today" parliament-mcp load-data parliamentary-questions --from-date "2025-01-01" # Delete all data parliament-mcp delete-qdrant ``` ### Data Structure The system works with two main types of parliamentary documents: **Parliamentary Questions** (Collection: `parliamentary_questions`): - Written Questions with semantic search on question and answer text - Member information for asking and answering members - Date, reference numbers, and department details **Hansard Contributions** (Collection: `hansard_contributions`): - Spoken contributions from parliamentary debates - Semantic search on full contribution text - Speaker information and debate context - House (Commons/Lords) and sitting date **Data Loading Process**: 1. **Fetch** from Parliamentary APIs (Hansard API, Parliamentary Questions API) 2. **Transform** into structured models with computed fields 3. **Embed** using Azure OpenAI for semantic search 4. **Index** into Qdrant with proper vector configurations Data is loaded automatically from official Parliamentary APIs - no manual document creation needed. ### Daily Data Ingestion To keep the data in Qdrant up-to-date, a daily ingestion mechanism is provided. This loads the last two days of data from both `hansard` and `parliamentary-questions` sources. To run the daily ingestion manually: ```bash make ingest_daily ``` This runs the equivalent of: ```bash parliament-mcp load-data hansard --from-date "2 days ago" --to-date "today" parliament-mcp load-data parliamentary-questions --from-date "2 days ago" --to-date "today" ``` For automated daily ingestion, you can use a cron job. Here are examples for standard cron and AWS EventBridge cron. **Standard Cron** This cron job will run every day at 4am. ``` 0 4 * * * cd /path/to/parliament-mcp && make ingest_daily ``` **AWS EventBridge Cron** This AWS EventBridge cron expression will run every day at 4am UTC. ``` cron(0 4 * * ? *) ``` ### Notes on AWS Lambda Deployment for Daily ingestion A docker based AWS lambda image is provided to run daily ingestion tasks. **1. Build the Lambda Container Image** Build the Docker image using the provided `Makefile` target: ```bash make docker_build_lambda ``` This will create a Docker image named `parliament-mcp-lambda:latest`. **2. Test the Lambda locally** You can test the Lambda function locally using the AWS Lambda Runtime Interface Emulator (RIE), which is included in the base image. **Prerequisites:** - Your local Qdrant container must be running (`docker compose up -d qdrant`). - The Lambda container image must be built (`make docker_build_lambda`). **Run the container:** A convenient way to provide the necessary environment variables is to use the `--env-file` flag with your `.env` file. You still need to override the `ELASTICSEARCH_HOST` to ensure the container can connect to the service running on your local machine. ```bash docker run --rm -p 9000:8080 \ --env-file .env \ -e QDRANT_HOST="host.docker.internal" \ parliament-mcp-lambda:latest ``` **Trigger the function:** Open a new terminal and run the following `curl` command to send a test invocation. The `from_date` and `to_date` parameters are optional. If not provided, it will default to loading everything from the last 2 days. ```bash curl -X POST "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{"from_date": "2025-06-23", "to_date": "2025-06-27"}' ``` 3. Configure the Lambda in AWS With the image pushed to ECR, you can create the Lambda with the following configurations - Use `QDRANT_HOST` and `QDRANT_PORT` to point to your Qdrant instance - Increase the default timeout to ~10 minutes to ensure the ingestion has enough time to complete - Use AWS's flavour of cron to schedule the task for ~4am every day - `cron(0 4 * * ? *)` * Remember to increase the default timeout to ~10 minutes to ensure the ingestion has enough time to complete. ## Usage Examples Once connected to Claude, you can use natural language queries like: **Parliamentary Questions:** - "Search for parliamentary questions about climate change policy" - "Find questions asked by Conservative MPs about healthcare funding" - "Show me recent questions about education from the last week" **Hansard Contributions:** - "Search for contributions about the budget debate" - "Find speeches by Keir Starmer about economic policy" - "Show me debates from the House of Lords about immigration" **Member Information:** - "Get detailed information about the MP for Birmingham Edgbaston" - "Search for Labour MPs elected in 2024" - "Find constituency information for postcode SW1A 0AA" **Parliamentary Structure:** - "Show me the current government ministers" - "Get the state of the parties in the House of Commons" - "List all opposition shadow cabinet positions" **Committees:** - "List all current Commons select committees" - "Get details about the Public Accounts Committee including members and recent publications" - "Show me oral evidence from the Treasury Committee" - "Find committees dealing with environmental issues" **General Queries:** - "Search for debates about artificial intelligence regulation" - "Find election results for marginal constituencies" - "Show me government departments and their responsibilities" ### Logs and Debugging **View server logs**: ```bash docker-compose logs mcp-server ``` **Enable debug mode** in Claude config by adding `--debug` flag. **Check Qdrant status**: ```bash curl http://localhost:6333/healthz # Or use the make command: make qdrant_health ``` ## Troubleshooting ### Common Issues **MCP Connection Issues** - Ensure MCP server is running on port 8080 - The MCP server runs on `/{MCP_ROOT_PATH}/mcp`, not `/MCP_ROOT_PATH` - Verify Claude Desktop configuration is correct **Data Loading Failures** - Check Azure OpenAI credentials in `.env` file - Ensure Qdrant is running and accessible - Verify network connectivity to Parliamentary APIs - Use `--ll DEBUG` flag for detailed logging **Qdrant issues** - Verify collections are created: `parliament-mcp init-qdrant` - Use the Qdrant Web UI at http://localhost:6333/dashboard to inspect collections ## Contributing Contributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md) for details on how to get started. ## License MIT License - see LICENSE file for details