README.md

---
title: BioGuideMCP
emoji: 👁
colorFrom: purple
colorTo: yellow
sdk: gradio
sdk_version: 5.49.1
app_file: gradio_app.py
pinned: false
license: mit
short_description: 'An MCP allowing users to analyze congressional biographies. '
---

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

# Congressional Bioguide MCP Server

A Model Context Protocol (MCP) server that provides access to Congressional member profiles with both structured SQL queries and semantic search capabilities.

## Deployment Options

### 1. Gradio MCP (Hugging Face Spaces)

Run this MCP as a Gradio app with web interface + MCP server:

```bash
python gradio_app.py
```

This will launch a web interface at `http://localhost:7860` with 9 tools exposed as both a web UI and MCP tools.

**Deploy to Hugging Face Spaces:**
1. Create a new Space on Hugging Face
2. Set SDK to `gradio` (version 5.49.1+)
3. Upload all files including `gradio_app.py`, `congress.db`, `congress_faiss.index`, and `congress_bio_ids.pkl`
4. The app will automatically launch with `mcp_server=True`

### 2. Traditional MCP Server

Use the original MCP server for integration with Claude Desktop or other MCP clients:

```bash
python server.py
```

Test the server backend with `npx @modelcontextprotocol/inspector python server.py` or integrate it into your Claude setup.

## Features

### Gradio MCP Tools (9 Tools)

The Gradio app (`gradio_app.py`) exposes these 9 MCP tools:

1. **search_by_name** - Search members by name (first/last name)
2. **search_by_party** - Find by political party affiliation
3. **search_by_state** - Search by state/region representation
4. **semantic_search_biography** - AI-powered natural language search of biographies
5. **get_member_profile** - Get complete profile by Bioguide ID
6. **count_members_by_party** - Count members grouped by party
7. **count_members_by_state** - Count members grouped by state
8. **execute_sql_query** - Execute custom SQL queries (read-only)
9. **get_database_schema** - View database structure

### Traditional MCP Server Tools (14 Tools)

The traditional server (`server.py`) provides all tools:

**Search Tools** (return concise results by default):
1. **search_by_name** - Search members by name (returns: name, dates, party, congress)
2. **search_by_party** - Find by political party affiliation
3. **search_by_state** - Search by state/region representation
4. **search_by_congress** - Get all members from specific Congress
5. **search_by_date_range** - Find members who served during specific dates
6. **semantic_search_biography** - Natural language AI search of biographies
7. **search_biography_regex** - Regex pattern search (keywords, phrases)
8. **search_by_relationship** - Find members with family relationships

**Aggregation & Analysis Tools** (efficient for large datasets):
9. **count_members** - Count members by party, state, position, congress, or year
10. **temporal_analysis** - Analyze trends over time (party shifts, demographics, etc.)
11. **count_by_biography_content** - Count members mentioning specific keywords (e.g., "Harvard", "lawyer")

**Profile & Query Tools**:
12. **get_member_profile** - Get complete profile by Bioguide ID
13. **execute_sql_query** - Execute custom SQL queries (read-only)
14. **get_database_schema** - View database structure

### Database Schema

- **members** - Core biographical data (13,047+ profiles)
- **job_positions** - Congressional positions and affiliations
- **images** - Profile images
- **relationships** - Family relationships between members
- **creative_works** - Publications by members
- **assets** - Additional media assets

## Requirements

- **Python 3.10+** including Python 3.14
- ✅ **Python 3.14 is now supported!** (with single-threaded mode for FAISS)

## Setup

### Quick Start

```bash
./setup.sh
```

This automated script will:
1. Create a Python virtual environment
2. Install all dependencies
3. Ingest all Congressional profiles into SQLite
4. Build the FAISS semantic search index

### Manual Setup

If you prefer manual setup:

#### 1. Install Dependencies

```bash
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
```

#### 2. Ingest Data

Run the ingestion script to create the SQLite database and FAISS index:

```bash
python3 ingest_data.py
```

This will:
- Create `congress.db` SQLite database (13,047+ members)
- Build `congress_faiss.index` for semantic search
- Generate `congress_bio_ids.pkl` for ID mapping

Expected output:
```
Starting Congressional Bioguide ingestion...
============================================================
✓ Database schema created
Ingesting 13047 profiles...
  Processed 1000/13047 profiles...
  ...
✓ Ingested 13047 profiles into database
Building FAISS index for semantic search...
  Encoding 13047 biographies...
    Encoded 3200/13047 biographies...
    ...
✓ FAISS index created with 13047 vectors
  Index dimension: 384
============================================================
✓ Ingestion complete!
```

**Note**: Ingestion takes approximately 5-10 minutes depending on your system.

#### 3. Test the System (Optional)

```bash
python3 test_queries.py
```

#### 4. Run the Server

```bash
python3 server.py
```

## Usage Examples

### Name Search
```json
{
  "name": "search_by_name",
  "arguments": {
    "family_name": "Lincoln"
  }
}
```

### Party Search
```json
{
  "name": "search_by_party",
  "arguments": {
    "party": "Republican",
    "congress_number": 117
  }
}
```

### State Search
```json
{
  "name": "search_by_state",
  "arguments": {
    "state_code": "CA",
    "congress_number": 117
  }
}
```

### Semantic Search
```json
{
  "name": "semantic_search_biography",
  "arguments": {
    "query": "Civil War veterans who became lawyers",
    "top_k": 5
  }
}
```

### Regex Search - Find Keywords
```json
{
  "name": "search_biography_regex",
  "arguments": {
    "pattern": "Harvard",
    "limit": 5
  }
}
```

### Regex Search - Filter by Party
```json
{
  "name": "search_biography_regex",
  "arguments": {
    "pattern": "lawyer",
    "filter_party": "Republican",
    "limit": 10
  }
}
```

### Regex Search - Filter by State and Congress
```json
{
  "name": "search_biography_regex",
  "arguments": {
    "pattern": "served.*Confederate Army",
    "filter_state": "VA",
    "limit": 5
  }
}
```

**Note**: Regex search returns concise results (name, dates, party, state) by default. Set `return_full_profile: true` to get biography text.

### Count Members by Party
```json
{
  "name": "count_members",
  "arguments": {
    "group_by": "party"
  }
}
```

### Count Republicans by State in 117th Congress
```json
{
  "name": "count_members",
  "arguments": {
    "group_by": "state",
    "filter_party": "Republican",
    "filter_congress": 117
  }
}
```

### Temporal Analysis - Party Changes Over Time
```json
{
  "name": "temporal_analysis",
  "arguments": {
    "analysis_type": "party_over_time",
    "time_unit": "congress",
    "start_date": "1900-01-01",
    "end_date": "2000-12-31"
  }
}
```

### Demographics Analysis - Average Age by Congress
```json
{
  "name": "temporal_analysis",
  "arguments": {
    "analysis_type": "demographics",
    "time_unit": "congress"
  }
}
```

### Count Members Who Attended Harvard
```json
{
  "name": "count_by_biography_content",
  "arguments": {
    "keywords": ["Harvard"]
  }
}
```

### Count Lawyers by Party
```json
{
  "name": "count_by_biography_content",
  "arguments": {
    "keywords": ["lawyer", "attorney"],
    "breakdown_by": "party"
  }
}
```

### Count Members Who Were Both Lawyers AND Veterans
```json
{
  "name": "count_by_biography_content",
  "arguments": {
    "keywords": ["lawyer", "military", "army"],
    "match_all": false,
    "breakdown_by": "state"
  }
}
```

### SQL Query - Find Longest Serving Members
```json
{
  "name": "execute_sql_query",
  "arguments": {
    "query": "SELECT family_name, given_name, COUNT(DISTINCT congress_number) as congresses FROM members m JOIN job_positions j ON m.bio_id = j.bio_id GROUP BY m.bio_id HAVING congresses > 5 ORDER BY congresses DESC LIMIT 10"
  }
}
```

### Get Full Member Profile
```json
{
  "name": "get_member_profile",
  "arguments": {
    "bio_id": "L000313"
  }
}
```

### Search by Congress Number
```json
{
  "name": "search_by_congress",
  "arguments": {
    "congress_number": 117,
    "chamber": "Senator"
  }
}
```

### Search by Date Range
```json
{
  "name": "search_by_date_range",
  "arguments": {
    "start_date": "1861-03-04",
    "end_date": "1865-03-04"
  }
}
```

### Find Family Relationships
```json
{
  "name": "search_by_relationship",
  "arguments": {
    "relationship_type": "father"
  }
}
```

### Complex SQL - Party Transitions
```json
{
  "name": "execute_sql_query",
  "arguments": {
    "query": "SELECT m.bio_id, m.family_name, m.given_name, GROUP_CONCAT(DISTINCT j.party) as parties FROM members m JOIN job_positions j ON m.bio_id = j.bio_id WHERE j.party IS NOT NULL GROUP BY m.bio_id HAVING COUNT(DISTINCT j.party) > 1 LIMIT 20"
  }
}
```

## Data Source

Data comes from the US Congressional Bioguide, containing biographical information for all members of Congress throughout history.

## Technical Details

- **Database**: SQLite for structured queries
- **Semantic Search**: FAISS with sentence-transformers (all-MiniLM-L6-v2)
- **Embedding Dimension**: 384
- **Index Type**: Flat IP (Inner Product) with L2 normalization for cosine similarity

## MCP Configuration

Add to your MCP settings file (usually `~/.config/claude/claude_desktop_config.json` on macOS/Linux or `%APPDATA%\Claude\claude_desktop_config.json` on Windows):

```json
{
  "mcpServers": {
    "congressional-bioguide": {
      "command": "/Users/electron/workspace/Nanocentury AI/NIO/BioGuideMCP/venv/bin/python",
      "args": [
        "/Users/electron/workspace/Nanocentury AI/NIO/BioGuideMCP/server.py"
      ],
      "cwd": "/Users/electron/workspace/Nanocentury AI/NIO/BioGuideMCP"
    }
  }
}
```

**Note**: This uses the virtual environment's Python which has all the required dependencies installed.

## License

Data is public domain from the US Congressional Bioguide.