GovNavigator - MCP Municipal Code Assistant

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.

GovNavigator