# Lawmesh MCP Server

A comprehensive Model Context Protocol (MCP) server providing AI agents with powerful tools to access U.S. legislative data through the OpenStates API v3.

## Live Deployment

**Public MCP Server**: https://pk-dev-Lawmesh.hf.space/mcp

The server is deployed on Hugging Face Spaces and ready for immediate use with any MCP-compatible client.

## Available Tools

Lawmesh provides four comprehensive tools for querying U.S. legislative information:

### 1. `list_jurisdictions`
Retrieve all available U.S. jurisdictions (states, territories, federal districts) with optional filtering.

**Parameters:**
- `classification` (optional): Filter by type ("state", "municipality", "country")
- `include` (optional): Additional data ("organizations", "legislative_sessions", "latest_runs")
- `page`, `per_page`: Pagination support

### 2. `get_jurisdiction`
Get detailed metadata for a specific jurisdiction.

**Parameters:**
- `jurisdiction` (required): State abbreviation, full name, or OpenStates ID
- `include` (optional): Additional data to include

### 3. `get_people`
Search for legislators, governors, and government officials.

**Parameters:**
- `jurisdiction`, `name`, `id`: Filter criteria (at least one required)
- `org_classification`: Role filter ("upper", "lower", "executive")
- `district`: District filter
- `include`: Additional biographical data
- Pagination support

### 4. `get_bills`
Search legislative bills, resolutions, and documents.

**Parameters:**
- `jurisdiction`, `session`, `chamber`: Basic filters
- `identifier`: Specific bill numbers
- `classification`: Bill type ("bill", "resolution")
- `subject`, `sponsor`: Content and sponsor filters
- `q`: Full-text search
- `updated_since`, `created_since`, `action_since`: Date filters
- `include`: Additional data (votes, actions, documents, etc.)
- `sort`: Sort options
- Pagination support

## Architecture

Lawmesh is built using:
- **FastMCP**: Modern MCP server framework
- **Streamable HTTP Transport**: Optimized for web deployment
- **OpenStates API v3**: Authoritative source for U.S. legislative data
- **Async Architecture**: High-performance concurrent request handling

```
┌─────────────────┐    HTTP/MCP     ┌─────────────────┐    HTTPS/API    ┌─────────────────┐
│   MCP Client    │ <-------------> │  Lawmesh Server │ <-------------> │  OpenStates API │
│  (Claude, etc.) │                │   (FastMCP)     │                │      (v3)       │
└─────────────────┘                └─────────────────┘                └─────────────────┘
```

## Quick Start with MCP Client

### Example: Python MCP Client

```python
import asyncio
from mcp import create_client_session
from mcp.client.transports.http import create_http_transport

async def main():
    # Connect to the deployed Lawmesh server
    transport = create_http_transport("https://pk-dev-Lawmesh.hf.space/mcp")
    
    async with create_client_session(transport) as session:
        # List available tools
        tools = await session.list_tools()
        print("Available tools:", [tool.name for tool in tools.tools])
        
        # Example: Get California jurisdictions
        result = await session.call_tool("list_jurisdictions", {
            "classification": "state",
            "per_page": 10
        })
        print("Jurisdictions:", result.content)
        
        # Example: Search for bills about education in California
        bills = await session.call_tool("get_bills", {
            "jurisdiction": "ca",
            "subject": "education",
            "per_page": 5
        })
        print("Education bills:", bills.content)

if __name__ == "__main__":
    asyncio.run(main())
```

### Example: Using with Claude Desktop

Add to your Claude Desktop MCP configuration:

```json
{
  "mcpServers": {
    "lawmesh": {
      "url": "https://pk-dev-Lawmesh.hf.space/mcp"
    }
  }
}
```

## Local Development Setup

### Prerequisites

1. **Python 3.13+**
2. **OpenStates API Key**: Get one at [OpenStates.org](https://openstates.org/api/)
3. **Environment Setup**

### Installation

1. **Clone the repository:**
```bash
git clone <repository-url>
cd Lawmesh
```

2. **Install dependencies:**
```bash
# Using pip
pip install -r requirements.txt

# Or using uv (recommended)
uv sync
```

3. **Environment Configuration:**
Create a `.env` file:
```bash
# .env
OPENSTATES_API_KEY=your_openstates_api_key_here
```

4. **Run the server:**
```bash
# Development mode
python app.py

# Or with uvicorn
uvicorn app:app --host 0.0.0.0 --port 7860 --reload
```

The server will be available at: `http://localhost:7860/mcp`

### Local Testing

Test your local server with MCP Inspector:
```bash
npx @modelcontextprotocol/inspector http://localhost:7860/mcp
```

## Docker Deployment

### Using the included Dockerfile:

```bash
# Build the image
docker build -t lawmesh-mcp .

# Run with environment variable
docker run -p 7860:7860 -e OPENSTATES_API_KEY=your_key_here lawmesh-mcp
```

### Docker Compose:

```yaml
# docker-compose.yml
version: '3.8'
services:
  lawmesh:
    build: .
    ports:
      - "7860:7860"
    environment:
      - OPENSTATES_API_KEY=${OPENSTATES_API_KEY}
    env_file:
      - .env
```

## Dependencies

Core dependencies from `pyproject.toml`:

- **fastmcp>=2.12.3**: MCP server framework
- **httpx>=0.28.1**: Async HTTP client for API calls
- **uvicorn>=0.36.0**: ASGI server
- **python-dotenv>=1.1.1**: Environment variable management
- **mcp[cli]>=1.14.1**: MCP protocol support

## Security & Configuration

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `OPENSTATES_API_KEY` | Yes | Your OpenStates API key |
| `PORT` | No | Server port (default: 7860) |
| `HOST` | No | Server host (default: 0.0.0.0) |

### API Key Security

- Never commit API keys to version control
- Use environment variables or secure secret management
- For Hugging Face Spaces: Configure as Repository Secrets

## Use Cases

- **Political Research**: Track legislation and voting patterns
- **Government Transparency**: Access public legislative records
- **Civic Engagement**: Build tools for citizen participation
- **Academic Research**: Study U.S. political processes
- **News & Media**: Automated legislative monitoring
- **Legal Research**: Access bill text and legislative history

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

## License

This project is open source. Please check the LICENSE file for details.

## Support

- **Issues**: Report bugs and feature requests via GitHub Issues
- **Documentation**: OpenStates API v3 docs at [docs.openstates.org](https://docs.openstates.org/api-v3/)
- **MCP Protocol**: Learn more at [modelcontextprotocol.io](https://modelcontextprotocol.io/)

---

**Built with ❤️ using FastMCP and OpenStates API**