@rip-user/rls-debugger-mcp/examples/README.md

AI-powered MCP server for debugging Supabase Row Level Security policies with Claude structured outputs

# Configuration Examples

This directory contains example configuration files for the RLS Debugger MCP server.

## Files

### `.mcp.json`
Example MCP server configuration for Claude Code. Copy this to your project root as `.mcp.json` (project-specific) or `~/.mcp.json` (global).

**Usage**:
```bash
# Project-specific (committed to git)
cp examples/.mcp.json .mcp.json

# User-global (all projects)
cp examples/.mcp.json ~/.mcp.json

# Local override (gitignored)
cp examples/.mcp.json .mcp.local.json
```

### `.env.example`
Example environment variables. While MCP configuration typically includes env vars inline, you can also use a `.env` file for development.

**Usage**:
```bash
cp examples/.env.example .env
# Edit .env with your actual credentials
```

**Note**: Never commit `.env` files to git. They are in `.gitignore` by default.

## Configuration Scopes

Claude Code supports three configuration scopes:

1. **Project** (`.mcp.json`):
   - Committed to git
   - Shared with team
   - Project-specific servers

2. **User** (`~/.mcp.json`):
   - Global across all projects
   - Personal configuration
   - Not in git

3. **Local** (`.mcp.local.json`):
   - Gitignored
   - Overrides project config
   - For development/testing

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `SUPABASE_URL` | Yes | Your Supabase project URL (e.g., `https://abc.supabase.co`) |
| `SUPABASE_SERVICE_KEY` | Yes | Service role key from Supabase settings → API |
| `ANTHROPIC_API_KEY` | Yes | Get from https://console.anthropic.com/ |
| `CLAUDE_MODEL` | No | Model to use (default: `claude-sonnet-4-5-20250514`) |
| `MEMORY_DIR` | No | Knowledge storage location (default: `./.rls-memory`) |

## Getting Credentials

### Supabase

1. Go to your project at https://supabase.com/dashboard
2. Navigate to **Settings** → **API**
3. Copy:
   - **Project URL** → `SUPABASE_URL`
   - **service_role secret** → `SUPABASE_SERVICE_KEY` (⚠️ Keep this secret!)

### Anthropic

1. Go to https://console.anthropic.com/
2. Navigate to **API Keys**
3. Create a new key
4. Copy the key → `ANTHROPIC_API_KEY`

## Model Selection

The `CLAUDE_MODEL` environment variable controls which Claude model is used for analysis:

### claude-sonnet-4-5-20250514 (Default)
- **Best for**: General debugging, most use cases
- **Speed**: Fast
- **Cost**: Most cost-effective
- **Quality**: High quality analysis

### claude-opus-4-1-20250514
- **Best for**: Complex policy interactions, thorough analysis
- **Speed**: Slower
- **Cost**: More expensive
- **Quality**: Maximum detail and thoroughness

**Recommendation**: Start with Sonnet. Only switch to Opus for exceptionally complex scenarios.

## Installation Methods

### Via npx (No installation)
```bash
# Server runs from npm registry
"command": "npx",
"args": ["-y", "@rip-user/rls-debugger-mcp"]
```

### Via global install
```bash
npm install -g @rip-user/rls-debugger-mcp

# Then use:
"command": "rls-debugger-mcp"
```

### From source (Development)
```bash
git clone https://github.com/rip-user/rls-debugger-mcp
cd rls-debugger-mcp
npm install
npm run build

# Then use:
"command": "node",
"args": ["/absolute/path/to/rls-debugger-mcp/dist/index.js"]
```

## Troubleshooting

### Server not connecting

1. Check environment variables are set correctly
2. Verify Supabase URL and service key
3. Ensure Anthropic API key is valid
4. Check Claude Code logs: **View** → **Output** → Select "MCP"

### Invalid credentials

```bash
# Test Supabase connection
curl https://your-project.supabase.co/rest/v1/ \
  -H "apikey: your-service-role-key"

# Test Anthropic API
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: your-api-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-5-20250514","max_tokens":1024,"messages":[{"role":"user","content":"Hi"}]}'
```

### Model not found

If you get an error about the model:
1. Check you're using a valid model name
2. Ensure your Anthropic API key has access to the model
3. Try removing `CLAUDE_MODEL` to use the default

## Security Notes

⚠️ **Never commit secrets to git**:
- Add `.env` to `.gitignore`
- Use `.mcp.local.json` for personal credentials
- Never share your service role key publicly

⚠️ **Service role key has admin access**:
- Can bypass all RLS policies
- Can access all data in your database
- Only use server-side (never expose to clients)

## Additional Resources

- [MCP Documentation](https://spec.modelcontextprotocol.io/)
- [Claude Code Documentation](https://code.claude.com/)
- [Supabase RLS Guide](https://supabase.com/docs/guides/auth/row-level-security)
- [Anthropic API Reference](https://docs.anthropic.com/)