jadu/modgov-mcp-server

Modgov MCP Server

A comprehensive Model Context Protocol (MCP) server that provides access to modgov council APIs for retrieving councillor information, committee details, meeting schedules, election results, and parish council data across UK local councils.

Table of Contents

• Quick Start
  • Prerequisites
  • Build & Run
  • Docker Deployment
• Features
• Critical Server Bug Workarounds
  • Parameter Requirements Mismatch
  • Automatic Workarounds Applied
  • Testing Results
• Testing
  • Test Structure
  • Running Tests
  • Test Results
• Documentation
  • OpenAPI/Swagger Specification
  • Developer Resources
• Installation
  • Native Node.js (Recommended for Development)
  • Docker (Recommended for Production)
• MCP Transport Options
  • STDIO Transport (Default)
  • HTTP Transport (Streamable)
  • MCP Inspector
• Usage
  • Docker (Production)
  • HTTP API Endpoints
  • Docker Logging
• Available Tools
  • Councillor Information
  • Governance & Committees
  • Events & Calendar
  • Local Government Structure
  • Elections & Democracy
  • Digital Services
  • Council Discovery & Management
• Tool Usage Examples
  • Councillor Information
  • Governance & Committees
  • Local Government Structure
• Response Format
• Rate Limiting
• Error Handling
• Development
  • Development Environment
  • Running Tests
  • Building
  • Stopping Development Environment
• Docker Configuration
  • Production Container
  • Testing Docker Setup
  • MCP Server Behavior
• Architecture
• Supported Council Sites
  • Complete Council Database
  • Coverage Statistics
  • Verified Working Examples
  • Special Features
  • Council Discovery
• API Discovery
• Examples
  • Quick Test
  • Configuration Notes
  • MCP Client Configuration
• Best Practices
• Error Handling Examples
• Contributing
• License

Quick Start

Prerequisites

• Node.js (version 18+)
• Docker & Docker Compose (for production deployment)

Build & Run

1. Clone and Build:

   git clone <repository-url>
   cd modgov-mcp-server
   npm install
   npm run build
   

2. Run with STDIO transport:

   node dist/index.js
   

3. Run with HTTP transport:

   MCP_TRANSPORT=http node dist/index.js
   # Server available at: http://localhost:3003/mcp
   

4. Test with MCP Inspector:

   npx @modelcontextprotocol/inspector node dist/index.js
   

Docker Deployment

For production deployment, use Docker:

# Build and run
make build && make up

# Server available at: http://localhost:3003/mcp
# Health check: http://localhost:3003/health

Features

• 100% Success Rate: 9/9 endpoints fully functional with automatic server bug workarounds
• Complete API Coverage: All major ModGov endpoints (councillors, committees, meetings, elections, etc.)
• Multi-site support: Tested across 3 UK council sites (Lichfield, Kirklees, Liverpool)
• Server Bug Handling: Automatic workarounds for WSDL vs actual server discrepancies
• Flexible querying: Multiple ways to access council data (by ward, committee, date, etc.)
• Rate limiting: Built-in rate limiting (1 request/second per domain) to prevent API abuse
• Error handling: Robust error handling with meaningful error messages
• Council lookup: Smart fuzzy matching to find councils by name or region

🚨 Critical Server Bug Workarounds

Major discrepancies exist between official WSDL documentation and actual ModGov server implementations. This MCP server automatically handles these issues:

Parameter Requirements Mismatch

Many parameters marked as "optional" in WSDL are actually required by servers:

Automatic Workarounds Applied

The MCP server transparently applies these fixes:

• Missing dates: Defaults to current year range (YYYY-01-01 to YYYY-12-31)
• Missing committee IDs: Defaults to Cabinet (138)
• Missing boolean flags: Provides sensible defaults (true for global calendar, etc.)
• Missing user IDs: Defaults to 0 for public access

Testing Results

All tested sites exhibit identical server bugs and all are handled automatically.

🧪 Testing

Test Structure

tests/
├── integration/        # End-to-end integration tests
├── debugging/         # Debug and investigation scripts
├── utils/            # Utility test scripts
└── README.md         # Test documentation

Running Tests

Unit Tests (in Docker)

# Run Jest unit tests in Docker container
make test

# Or use Docker Compose directly
docker-compose run --rm modgov-mcp-server npm test

Integration Tests (in Docker)

# Test all 9 endpoints end-to-end in Docker
docker-compose run --rm modgov-mcp-server npm run test:integration

Debug Tests (in Docker)

# Investigate endpoint compatibility across sites
docker-compose run --rm modgov-mcp-server npm run test:debug

# Verify parameter handling
docker-compose run --rm modgov-mcp-server npm run test:params

Test Results

• ✅ 100% Success Rate: 9/9 endpoints working
• ✅ Server Bug Workarounds: All WSDL discrepancies handled automatically
• ✅ Cross-Site Compatibility: Tested across 3 council sites

📚 Documentation

OpenAPI/Swagger Specification

• File: modgov-openapi-spec.yaml
• Status: ✅ Complete and Authoritative
• Coverage: All 9 supported endpoints with real-world examples
• Features:
  • Server bug workarounds clearly documented
  • Request/response examples
  • Parameter validation rules
  • Cross-site compatibility notes

Developer Resources

• Robustness Report: MCP_ROBUSTNESS_REPORT.md - Testing and performance details
• Test Documentation: tests/README.md - Complete test suite guide
• Implementation Notes: Server bug workarounds and best practices (see sections above)

Installation

Native Node.js (Recommended for Development)

# Clone and install
git clone <repository-url>
cd modgov-mcp-server
npm install
npm run build

# Run with STDIO transport (default)
node dist/index.js

# Run with HTTP transport
MCP_TRANSPORT=http node dist/index.js

Docker (Recommended for Production)

# Using Makefile (recommended)
make build && make up

# Or using Docker Compose directly
docker-compose up --build

Available Make Commands:

• make build - Build production image
• make up - Start production container
• make test - Run tests in container
• make logs - View container logs
• make clean - Remove containers and images
• make shell - Open shell in container for debugging

MCP Transport Options

The Modgov MCP Server supports both STDIO and HTTP transports:

STDIO Transport (Default)

Perfect for development and MCP client integration:

# Start with STDIO transport
node dist/index.js

# Test with MCP Inspector
npx @modelcontextprotocol/inspector node dist/index.js

STDIO transport characteristics:

• Default transport mode
• Interactive stdin/stdout communication
• Perfect for MCP clients (Claude Desktop, Cursor, etc.)
• Terminates after client disconnects

HTTP Transport (Streamable)

Ideal for web services and API integration:

# Start with HTTP transport
MCP_TRANSPORT=http node dist/index.js

# Or with custom port
MCP_TRANSPORT=http MCP_PORT=3005 node dist/index.js

HTTP transport endpoints:

• MCP Protocol: http://localhost:3003/mcp
• Health Check: http://localhost:3003/health

HTTP transport characteristics:

• Runs as persistent web server
• RESTful MCP protocol over HTTP
• Supports streaming responses
• Built-in health monitoring

MCP Inspector

Test your server with the official MCP Inspector:

# For STDIO transport (default)
npx @modelcontextprotocol/inspector node dist/index.js

# For HTTP transport
npx @modelcontextprotocol/inspector http://localhost:3003/mcp

The inspector provides:

• ✅ Interactive tool testing
• ✅ Protocol validation
• ✅ Request/response debugging
• ✅ Schema verification

Usage

Docker (Production)

Production with HTTP Transport

# Build and run production container
make build && make up

# Or using Docker Compose directly
docker-compose up --build modgov-mcp-server

The server automatically starts in HTTP mode on port 3003 when the container starts.

HTTP API Endpoints

The MCP server runs in Docker and exposes these endpoints on port 3003:

MCP Protocol Endpoint

POST http://localhost:3003/mcp
Content-Type: application/json

# Example request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_councillors",
    "arguments": {
      "site_url": "https://democracy.lichfielddc.gov.uk/mgWebService.asmx?WSDL"
    }
  }
}

Health Check Endpoint

GET http://localhost:3003/health

# Response
{
  "status": "healthy",
  "timestamp": "2025-01-11T10:20:30.000Z",
  "server": "modgov-mcp-server",
  "version": "1.0.0",
  "transport": "streamable-http"
}

Docker Logging

The MCP server includes comprehensive logging for all tool calls when running in Docker:

# View real-time logs
docker logs modgov-mcp-server --follow

# View recent logs
docker logs modgov-mcp-server --tail 20

Example Log Output:

🛠️  Tool called: get_councillors_by_ward
📍 Parameters: site_url=https://democracy.lichfielddc.gov.uk/mgWebService.asmx
✅ Tool completed: get_councillors_by_ward (1280ms)

🛠️  Tool called: get_committees
📍 Parameters: site_url=https://democracy.lichfielddc.gov.uk/mgWebService.asmx
✅ Tool completed: get_committees (320ms)

Each tool call logs:

• 🔧 Tool initiation with emoji and tool name
• 📍 Parameters passed to the tool
• ✅ Completion with execution time in milliseconds

The MCP server runs at http://localhost:3003/mcp and supports the full MCP protocol for testing all registered tools.

Port Conflict Solutions: If you encounter port conflicts:

# Stop all containers
make down

# Or manually kill processes on ports 3003, 6274, 6277
lsof -ti:3003,6274,6277 | xargs kill -9 2>/dev/null || true

Stopping the Server:

# Stop the Docker container
make down

# Or use Docker Compose directly
docker-compose down

Troubleshooting:

• Check container logs: make logs
• Verify container is running: docker ps
• Test health endpoint: curl http://localhost:3003/health

Available Tools

The MCP server exposes 18 tools for querying modgov council APIs and finding councils:

✅ Councillor Information (No Workarounds Needed)

• get_councillors_by_ward - Get all councillors organized by ward with photos and political affiliations
• get_councillors_by_ward_id - Get councillors for a specific ward ID
• get_councillors_by_postcode - Get councillors for a specific postcode
• get_councillor_details - Get comprehensive councillor profiles including surgery times and contact details

✅ Governance & Committees (Automatic Workarounds Applied)

• get_committees - Get all committees (Cabinet, Council, Planning, etc.)
• get_meetings - Get meetings with automatic date range defaults ⚙️
• get_meeting - Get details for a specific meeting by ID
• get_all_meetings_by_date - Get meetings for specific date with committee defaults ⚙️

✅ Events & Calendar (Automatic Workarounds Applied)

• get_calendar_events - Get calendar events with automatic parameter handling ⚙️

✅ Local Government Structure (No Workarounds Needed)

• get_parish_councils - Get parish councils and their information

✅ Elections & Democracy (Automatic Workarounds Applied)

• get_election_results - Get election results with required election ID ⚙️

✅ Digital Services (Automatic Workarounds Applied)

• get_webcast_meetings - Get webcast meetings with date and committee defaults ⚙️
• get_mp_or_meps_and_wards - Get MP/MEP information with boolean flag handling ⚙️
• get_mp_or_mep_and_wards_by_postcode - Get MP/MEP info for specific postcode ⚙️

✅ Council Discovery & Management

• find_council - Find a council by name using fuzzy matching
• search_councils - Search councils with confidence thresholds
• get_council_by_region - Get all councils in a specific region
• get_server_diagnostics - Get server diagnostic information

⚙️ Automatic server bug workarounds applied | ✅ All tools tested and working

Tool Usage Examples

All tools require a site_url parameter pointing to the council's modgov API endpoint.

Councillor Information

Get all councillors by ward:

{
  "site_url": "https://democracy.lichfielddc.gov.uk/mgWebService.asmx?WSDL"
}

Get councillors for a specific ward:

{
  "site_url": "https://democracy.lichfielddc.gov.uk/mgWebService.asmx?WSDL",
  "ward_id": 1
}

Get councillors by postcode:

{
  "site_url": "https://democracy.lichfielddc.gov.uk/mgWebService.asmx?WSDL",
  "postcode": "WS14 9AB"
}

Governance & Committees

Get all committees:

{
  "site_url": "https://democracy.lichfielddc.gov.uk/mgWebService.asmx?WSDL"
}

Get meetings for a specific committee:

{
  "site_url": "https://democracy.lichfielddc.gov.uk/mgWebService.asmx?WSDL",
  "committee_id": 1
}

Get a specific meeting by ID:

{
  "site_url": "https://democracy.lichfielddc.gov.uk/mgWebService.asmx?WSDL",
  "meeting_id": 123
}

Local Government Structure

Get parish councils:

{
  "site_url": "https://democracy.lichfielddc.gov.uk/mgWebService.asmx?WSDL"
}

## Response Format

The tool returns JSON data with the following structure:

```json
{
  "site_url": "https://democracy.lichfielddc.gov.uk/mgWebService.asmx?WSDL",
  "total_wards": 25,
  "total_councillors": 47,
  "wards": [
    {
      "ward_name": "Alrewas and Fradley",
      "councillor_count": "3",
      "councillors": [
        {
          "id": "570",
          "name": "Councillor Sonia Claverley",
          "party": "The Conservative Party",
          "group": "Conservative Group",
          "district": "Lichfield District Council",
          "representing": "Lichfield District Council",
          "photos": {
            "small": "https://democracy.lichfielddc.gov.uk/UserData/0/7/5/Info00000570/smallpic.jpg",
            "large": "https://democracy.lichfielddc.gov.uk/UserData/0/7/5/Info00000570/bigpic.jpg"
          },
          "additional_info": "...",
          "key_posts": "..."
        }
      ]
    }
  ]
}

Rate Limiting

The server implements rate limiting of 1 request per second per domain to prevent abuse and respect API limits.

Error Handling

The server provides comprehensive error handling:

• Network errors: Connection timeouts, DNS resolution failures
• API errors: Invalid responses, malformed XML
• Rate limiting: Automatic retry with exponential backoff
• Validation errors: Invalid parameters, missing required fields

Development

Development Environment

All development happens within Docker containers:

# Start development environment with live code mounting
make dev

# This mounts your source code and provides hot reloading

Running Tests

Unit Tests (in Docker)

# Run Jest unit tests in development container
make test

# Or run tests in watch mode for development
docker-compose --profile dev exec modgov-mcp-dev npm run test:watch

Integration Tests (in Docker)

Test the full MCP server functionality with real API calls:

# Start development environment (Terminal 1)
make dev

# Run integration tests (Terminal 2)
docker-compose --profile dev exec modgov-mcp-dev npm run test:mcp

The integration tests include:

• Health endpoint validation
• MCP protocol compliance
• Tool discovery and execution
• Council data retrieval and validation

See for detailed testing documentation.

Building

The build process happens automatically in the Docker container:

# Manual build in container
docker-compose --profile dev exec modgov-mcp-dev npm run build

Stopping Development Environment

# Stop development containers
make down

This stops all development containers and cleans up resources.

Docker Configuration

Production Container

The production container is optimized for deployment:

docker build -t modgov-mcp-server .
docker run -p 3003:3003 modgov-mcp-server

Features:

• Multi-stage build for minimal image size
• Non-root user for security
• Health checks
• Only production dependencies
• Always runs on port 3003 with HTTP transport

Testing Docker Setup

Verify your Docker container works:

# Build and test
make build
make up

# Check health endpoint
curl http://localhost:3003/health

Expected health response:

{
  "status": "healthy",
  "timestamp": "2025-01-11T10:20:30.000Z",
  "server": "modgov-mcp-server",
  "version": "1.0.0",
  "transport": "streamable-http"
}

MCP Server Behavior

Important: The MCP server runs continuously in HTTP mode inside the Docker container. This is different from stdio mode where servers exit after each request.

• The server stays running and listens on port 3003
• Each MCP request is handled over HTTP
• The container will show as running (not exited)
• Use make logs to monitor the server output

Architecture

The server consists of three main components:

1. ModgovClient: Handles HTTP requests to modgov APIs, XML parsing, and rate limiting
2. ModgovServer: MCP server implementation with tool registration and request handling
3. Type Definitions: TypeScript interfaces for API responses and data structures

Supported Council Sites

The server works with any modgov-enabled council website. Our database includes 44 verified councils across all UK regions.

Complete Council Database

Coverage Statistics

• Total Councils: 44
• Regions Covered: 11 (all UK regions)
• Council Types: 10 different authority types
• Tested Sites: 3 (Lichfield, Kirklees, Liverpool - 100% success rate)

Verified Working Examples

Special Features

• London Borough of Sutton: Includes detailed endpoint documentation with parameter specifications, response formats, and working examples
• Council Discovery: Built-in fuzzy matching to find councils by name (find_council)
• Regional Search: Find all councils in a specific region (get_council_by_region)
• Confidence Scoring: Search with configurable confidence thresholds (search_councils)

Council Discovery

Use the built-in council finder tools:

# Find a specific council
curl -X POST http://localhost:3003/mcp \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/call", "params": {"name": "find_council", "arguments": {"council_name": "Leeds"}}}'

# Search councils by region
curl -X POST http://localhost:3003/mcp \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/call", "params": {"name": "get_council_by_region", "arguments": {"region": "West Midlands"}}}'

API Discovery

To discover available operations for a specific council site, you can inspect the WSDL:

curl "https://democracy.lichfielddc.gov.uk/mgWebService.asmx?WSDL" | grep -i "council"

Examples

See the directory for complete configuration examples:

• Cursor: examples/cursor-mcp.json
• Claude Desktop: examples/claude-desktop-config.json
• VS Code: examples/vscode-mcp.json
• Docker Production: examples/docker-compose.production.yml
• Nginx Configuration: examples/nginx.conf
• Test Client: examples/test-mcp-client.js
• Postman Collection: examples/postman-collection.json
• Environment Config: examples/env-example.txt

Quick Test

Test your setup with the provided script:

./examples/test-setup.sh

Configuration Notes

The MCP server supports both native Node.js execution and Docker deployment. Choose the configuration that matches your deployment method.

MCP Client Configuration

Choose the configuration that matches your transport preference:

✅ HTTP Transport (Recommended for production):

{
  "mcpServers": {
    "modgov-council": {
      "url": "http://localhost:3003/mcp",
      "headers": {
        "Content-Type": "application/json",
        "Accept": "application/json, text/event-stream"
      }
    }
  }
}

✅ STDIO Transport (Recommended for development):

{
  "mcpServers": {
    "modgov-council": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/modgov-mcp-server"
    }
  }
}

Server Requirements:

For HTTP Transport:

• Start the server: MCP_TRANSPORT=http node dist/index.js
• Or with Docker: make build && make up
• Server available at: http://localhost:3003/mcp
• Health check: curl http://localhost:3003/health

For STDIO Transport:

• Build the project: npm run build
• Client will spawn: node dist/index.js
• No persistent server required

🎯 Best Practices

1. Always use the MCP server - It handles all server bugs automatically
2. Don't rely on WSDL alone - Test actual server behavior
3. Handle 500 errors gracefully - May indicate server bugs, not client errors
4. Use sensible defaults - The MCP provides them automatically
5. Test across multiple sites - Behavior is consistent but verify
6. Use council discovery tools - Find councils by name or region easily

🔧 Error Handling Examples

// The MCP server handles these automatically, but for direct API usage:
try {
  const result = await modgovClient.getMeetings(siteUrl, 138);
} catch (error) {
  if (error.message.includes('Missing parameter')) {
    // This indicates a server bug, not client error
    console.log('Server implementation bug detected - use MCP server instead');
  }
}

Contributing

1. Follow TDD principles - write tests first
2. Ensure all tests pass before committing
3. Add new features with comprehensive test coverage
4. Update documentation for any API changes

License

MIT