GovNavigator

An MCP (Model Context Protocol) server that lets Claude search and navigate Madison, WI municipal ordinances. Ask questions like "Can I build a fence in my front yard?" and get real answers with citations!

What is MCP?

Model Context Protocol is Anthropic's open standard for connecting AI assistants to external tools and data. This project demonstrates building a production MCP server.

┌─────────────────────────────────────────────────────┐
│              Claude Desktop                          │
│         (asks: "fence regulations?")                │
└──────────────────────┬──────────────────────────────┘
                       │ MCP Protocol
                       ▼
┌─────────────────────────────────────────────────────┐
│            GovNavigator MCP Server                  │
│        (searches our ordinance database)            │
└──────────────────────┬──────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────┐
│              TF-IDF Search Index                     │
│        (30+ chapters of Madison city code)          │
└─────────────────────────────────────────────────────┘

Features

• Real Data: Scraped from Madison, WI's actual municipal code
• Semantic Search: TF-IDF based search finds relevant ordinances
• No API Costs: 100% free - no paid APIs needed!
• Citation Support: Returns section numbers and URLs
• MCP Integration: Works with Claude Desktop

Quick Start

1. Install Dependencies

# Create virtual environment
python -m venv .venv

# Activate (Windows PowerShell)
.\.venv\Scripts\Activate.ps1

# Activate (Mac/Linux)
source .venv/bin/activate

# Install dependencies
pip install -e .

2. Scrape Data (Optional - data already included)

python -m src.scraper.municode_scraper

3. Build Search Index

python -m src.search.index

4. Configure Claude Desktop

Add to your Claude Desktop config (%APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "govnavigator": {
      "command": "python",
      "args": ["-m", "src.mcp_server.server"],
      "cwd": "C:\\Users\\Krish\\OneDrive\\Desktop\\GovNavigator"
    }
  }
}

5. Restart Claude Desktop

After adding the config, restart Claude Desktop. You should see "govnavigator" in the MCP tools list.

Example Queries

Once connected, ask Claude:

• "Can I build a 6-foot fence in my front yard in Madison?"
• "What are the short-term rental regulations in Madison?"
• "Do I need a permit to open a food truck?"
• "What are the noise ordinance quiet hours?"
• "What's required for a building permit?"

Project Structure

GovNavigator/
├── src/
│   ├── scraper/          # Web scraper for Municode
│   │   └── municode_scraper.py
│   ├── search/           # TF-IDF search engine
│   │   └── index.py
│   └── mcp_server/       # MCP server implementation
│       └── server.py
├── data/
│   ├── raw/              # Scraped ordinance data
│   └── processed/        # Search index
└── pyproject.toml        # Project configuration

How It Works

1. Web Scraping

Uses Playwright (browser automation) to scrape Madison's municipal code from Municode.com. Handles JavaScript-rendered content.

2. TF-IDF Search

Builds a term-frequency inverse-document-frequency index for semantic search. No AI APIs needed - pure Python math!

3. MCP Server

Exposes two tools to Claude:

• search_ordinance: Search for relevant code sections
• get_ordinance_details: Get full text of a specific section

Tech Stack

• Python 3.10+
• MCP SDK - Anthropic's Model Context Protocol
• Playwright - Browser automation for scraping
• BeautifulSoup - HTML parsing
• Pydantic - Data validation

Learning Resources

This project demonstrates:

• Building MCP servers
• Web scraping with Playwright
• TF-IDF search implementation
• Async Python programming
• Data pipeline design

License

MIT License - Use freely for learning and building!

---

Built with Claude Code by a human learning AI engineering.