@theholetruth/supabase-foia-mcp

MCP server providing AI agents with searchable access to U.S. FOIA statutes via Supabase

🚀 Quick Start

# 1. Install globally
npm install -g @theholetruth/supabase-foia-mcp

# 2. Run interactive setup
supabase-foia-mcp setup

# 3. Restart Claude Desktop or Claude Code

# 4. Test in Claude
# "Search Texas FOIA statutes for penalties"

That's it! The MCP server auto-configures Claude with your Supabase credentials.

✨ Features

9 Powerful Tools for FOIA Research

1. search_statutes - Hybrid BM25 + vector semantic search across all U.S. states
2. get_status - Database health and statistics
3. inspect_section - Retrieve full statute text by citation
4. find_discrimination - Identify discriminatory residency requirements
5. list_statutes_by_state - Complete statute inventory for a state
6. get_exemptions - Exemption categories and common exemptions
7. search_by_state - State-specific hybrid search
8. compare_states - Multi-jurisdiction comparison analysis
9. get_topic_rules - Practitioner guidance for common scenarios

Authoritative Data

• 1,382 statute sections across 36 U.S. states
• Dual-sourced (Justia + LexisNexis) for accuracy
• Official .gov citations and references
• Vector embeddings for semantic search
• BM25 keyword ranking for precision

📦 Installation

Requirements

• Node.js: 18.0.0 or higher
• npm: 7.0.0 or higher
• Claude Desktop or Claude Code installed
• Supabase account with deployed Edge Function

Install Package

npm install -g @theholetruth/supabase-foia-mcp

Run Setup

supabase-foia-mcp setup

The setup wizard will:

• ✅ Detect Claude Desktop or Claude Code installation
• ✅ Prompt for Supabase credentials
• ✅ Validate credentials against your Supabase project
• ✅ Automatically write configuration
• ✅ Show next steps

Example output:

╭─────────────────────────────────────────────╮
│  Supabase FOIA MCP - Setup Wizard          │
╰─────────────────────────────────────────────╯

✓ Found Claude Code
  Config: ~/.config/claude-code/mcp.json

📝 Supabase Configuration

? Supabase Project URL: https://your-project.supabase.co
? Supabase Service Role Key: •••••••••••••••••••
? Test connection before saving? Yes

✓ Validating credentials...
✓ Credentials valid
  Database: 1,382 sections, 36 states
✓ Configuration saved

╭─────────────────────────────────────────────╮
│  Setup Complete! 🎉                         │
╰─────────────────────────────────────────────╯

Next steps:
  1. Restart Claude Code to load the new server
  2. Test with: supabase-foia-mcp test
  3. Try in Claude: "Search Texas FOIA statutes for penalties"

🔧 CLI Commands

setup - Initial Configuration

Interactive setup wizard for first-time installation.

supabase-foia-mcp setup

test - Verify Installation

Test that the MCP server is working correctly.

supabase-foia-mcp test

Output example:

✓ Found Claude Code
✓ Configuration found
✓ Credentials valid
  Database: 1,382 sections, 36 states
✓ MCP protocol working

╭─────────────────────────────────────────────╮
│  All Tests Passed! ✓                        │
╰─────────────────────────────────────────────╯

Available tools:
  • search_statutes - Hybrid search across all states
  • get_status - Database health and statistics
  • inspect_section - Get full statute by citation
  [... 6 more tools ...]

reconfigure - Update Credentials

Update Supabase credentials without reinstalling.

supabase-foia-mcp reconfigure

uninstall - Remove Configuration

Remove MCP server configuration from Claude.

supabase-foia-mcp uninstall

Then remove the package:

npm uninstall -g @theholetruth/supabase-foia-mcp

💡 Usage Examples

Basic Statute Search

User: Search Texas FOIA statutes for penalties

Claude uses: search_statutes
  query: "penalties for denied requests"
  state: "TX"
  limit: 10

Returns: Ranked results with citations, full text, relevance scores

Multi-State Comparison

User: Compare how Texas and California handle expedited processing

Claude uses: compare_states
  topic: "expedited processing"
  states: ["TX", "CA"]

Returns: Side-by-side comparison of statutes and requirements

Exemption Analysis

User: What exemptions exist in New York FOIA law?

Claude uses: get_exemptions
  state: "NY"

Returns: Exemption categories and specific exemptions with citations

Practitioner Guidance

User: How do I request police records in Texas?

Claude uses: get_topic_rules
  topic_slug: "police_investigative_records"
  state: "TX"

Returns: Strategic guidance on handling police record requests

🔐 Configuration

Manual Configuration (Advanced)

If you prefer manual configuration, add to your Claude config file:

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "supabase-foia": {
      "command": "node",
      "args": [
        "/usr/local/lib/node_modules/@theholetruth/supabase-foia-mcp/dist/index.js"
      ],
      "env": {
        "SUPABASE_URL": "https://your-project.supabase.co",
        "SUPABASE_SECRET_KEY": "your-service-role-key"
      }
    }
  }
}

Claude Code (~/.config/claude-code/mcp.json):

{
  "mcpServers": {
    "supabase-foia": {
      "command": "node",
      "args": [
        "/usr/local/lib/node_modules/@theholetruth/supabase-foia-mcp/dist/index.js"
      ],
      "env": {
        "SUPABASE_URL": "https://your-project.supabase.co",
        "SUPABASE_SECRET_KEY": "your-service-role-key"
      }
    }
  }
}

Getting Supabase Credentials

1. Supabase URL: https://your-project.supabase.co

   • Find in: Supabase Dashboard → Settings → API → Project URL

2. Service Role Key: JWT token starting with eyJ...

   • Find in: Supabase Dashboard → Settings → API → service_role (secret)
   • ⚠️ Keep this secret! It has admin access to your database.

🛠️ Development

Build from Source

# Clone repository
git clone https://github.com/theholetruth/hole-backend.git
cd hole-backend/apps/mcp-supabase-installable

# Install dependencies
npm install

# Build
npm run build

# Test locally
npm run dev

Project Structure

apps/mcp-supabase-installable/
├── src/
│   ├── index.ts              # Main MCP server (stdio transport)
│   ├── cli/
│   │   ├── main.ts           # CLI entry point
│   │   ├── setup.ts          # Setup wizard
│   │   ├── test.ts           # Test command
│   │   ├── reconfigure.ts    # Reconfigure command
│   │   ├── uninstall.ts      # Uninstall command
│   │   └── utils/
│   │       ├── config.ts     # Config file management
│   │       ├── detect.ts     # Installation detection
│   │       ├── validate.ts   # Credential validation
│   │       └── prompts.ts    # Interactive prompts
│   └── shared/
│       └── constants.ts      # Shared constants
└── docs/
    ├── installation.md       # Detailed installation guide
    ├── usage.md              # Usage examples
    └── troubleshooting.md    # Troubleshooting guide

🐛 Troubleshooting

Server Not Detected in Claude

Problem: Claude doesn't show the server after setup

Solutions:

1. Restart Claude Desktop or Claude Code completely
2. Verify configuration: supabase-foia-mcp test
3. Check config file exists and is valid JSON
4. Run setup again: supabase-foia-mcp reconfigure

Credentials Invalid

Problem: Validation fails during setup

Solutions:

1. Check Supabase URL format:

   • Must start with https://
   • Must end with .supabase.co
   • Example: https://czkkmsdrsnkhbcamtgkg.supabase.co

2. Check Service Role Key:

   • Must start with eyJ (JWT token)
   • Get from: Supabase Dashboard → Settings → API → service_role
   • Use the service_role key, not anon key

3. Check Edge Function deployed:

   supabase functions list
   # Should show "foia-search" function

Edge Function Not Accessible

Problem: Credentials valid but Edge Function returns errors

Solutions:

1. Deploy Edge Function:

   cd /path/to/hole-backend
   supabase functions deploy foia-search

2. Check Edge Function logs:

   supabase functions logs foia-search

3. Verify database has data:

   • Should have 1,382+ statute sections
   • Run in Supabase SQL Editor: SELECT COUNT(*) FROM statute_sections;

More Help

• 📖 Installation Guide
• 📖 Usage Examples
• 📖 Troubleshooting Guide
• 🐛 Report Issues
• 📧 Contact

📄 License

MIT © The HOLE Foundation

🙏 Acknowledgments

• Built with Model Context Protocol
• Powered by Supabase
• Data sourced from official state .gov websites

The HOLE Foundation - Transparency through technology

https://theholetruth.org | https://docs.theholetruth.org