# Supabase Lite MCP Server

## Overview

The Supabase Lite MCP Server is a lightweight Model Context Protocol (MCP) server that provides essential Supabase database management commands. This focused implementation reduces token usage from ~14,800 to ~3,700 tokens by exposing only 8 core commands instead of the full 26.

## Features

- 🚀 **Minimal Token Usage**: Only ~3,700 tokens vs ~14,800 for the full Supabase MCP
- 🎯 **Essential Commands Only**: 8 carefully selected database management commands
- 📦 **Easy Installation**: Automated setup script with environment validation
- 🔧 **TypeScript**: Full type safety and modern ES modules
- 🔐 **Secure**: Uses service role keys with proper environment variable handling
- 🛠️ **Production Ready**: Error handling, logging, and MCP protocol compliance

## Quick Start

### Automated Installation

```bash
# Clone the repository
git clone https://github.com/your-username/supabase-lite-mcp.git
cd supabase-lite-mcp

# Run the setup script
./setup.sh
```

The setup script will:
- Check Node.js version (requires v22+)
- Install dependencies
- Guide you through configuration
- Build the TypeScript code
- Optionally test the server

### Manual Installation

1. **Install dependencies:**
   ```bash
   npm install
   ```

2. **Configure environment:**
   ```bash
   cp .env.example .env
   # Edit .env with your Supabase credentials
   ```

3. **Build the project:**
   ```bash
   npm run build
   ```

4. **Test the server:**
   ```bash
   npm run dev
   ```

## Configuration

### Environment Variables

Create a `.env` file with your Supabase credentials:

```env
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
SUPABASE_PROJECT_REF=your-project-ref  # Optional
```

Get these from your Supabase dashboard:
- **URL**: Settings → API → Project URL
- **Service Key**: Settings → API → Service role key (NOT anon key!)
- **Project Ref**: Settings → General → Reference ID

### Claude Integration

Add to your MCP configuration file (`.mcp.json`):

```json
{
  "mcpServers": {
    "supabase-lite": {
      "command": "node",
      "args": ["path/to/supabase-lite-mcp/dist/index.js"],
      "env": {
        "SUPABASE_URL": "${SUPABASE_URL}",
        "SUPABASE_SERVICE_KEY": "${SUPABASE_SERVICE_KEY}"
      }
    }
  }
}
```

Or use npm link for global access:

```bash
cd supabase-lite-mcp
npm link
```

Then use `"command": "supabase-lite-mcp"` in your MCP config.

## Available Commands

### 1. list_tables
Lists all tables in specified schemas.
- **Use case**: Discovering database structure
- **Token cost**: 457 tokens

### 2. list_extensions
Shows installed PostgreSQL extensions.
- **Use case**: Checking available database features
- **Token cost**: 413 tokens

### 3. list_migrations
Displays migration history.
- **Use case**: Tracking schema changes
- **Token cost**: 413 tokens

### 4. apply_migration
Applies DDL changes to the database.
- **Use case**: Creating tables, indexes, etc.
- **Token cost**: 485 tokens

### 5. execute_sql
Runs SQL queries for data operations.
- **Use case**: Querying and modifying data
- **Token cost**: 474 tokens

### 6. get_logs
Retrieves service logs from the last minute.
- **Use case**: Debugging issues
- **Token cost**: 516 tokens

### 7. get_advisors
Provides security and performance recommendations.
- **Use case**: Database optimization
- **Token cost**: 516 tokens

### 8. generate_typescript_types
Creates TypeScript interfaces from schema.
- **Use case**: Type-safe development
- **Token cost**: 417 tokens

## Architecture

### How It Works

The server implements the Model Context Protocol (MCP) to communicate with Claude:

```
Claude ↔️ MCP Protocol (stdio) ↔️ Server ↔️ Supabase API
```

### Key Components

- **MCP Server**: Handles protocol communication via stdio
- **Tool Registry**: Defines available commands and their schemas
- **Command Handlers**: Execute Supabase operations
- **Type Safety**: Full TypeScript with strict typing
- **Error Handling**: Graceful error reporting in MCP format

## Extending the Server

### Adding New Commands

1. Add command to `ALLOWED_COMMANDS` in `src/index.ts`
2. Define tool schema in `getToolDefinitions()`
3. Add case in `executeCommand()` switch
4. Implement handler method

Example:
```typescript
// 1. Add to ALLOWED_COMMANDS
const ALLOWED_COMMANDS = [
  // ... existing commands
  'custom_command'
] as const;

// 2. Add tool definition
tools.push({
  name: 'custom_command',
  description: 'My custom command',
  inputSchema: {
    type: 'object',
    properties: {
      param: { type: 'string' }
    }
  }
});

// 3. Add case in executeCommand
case 'custom_command':
  return await this.customCommand(args);

// 4. Implement handler
private async customCommand(args: any): Promise<any> {
  // Your implementation
  return {
    content: [{
      type: 'text',
      text: 'Result'
    }]
  };
}
```

## Development

### Scripts

- `npm run build` - Build TypeScript to JavaScript
- `npm run dev` - Run in development mode with hot reload
- `npm start` - Run production build
- `npm run clean` - Clean build artifacts

### Project Structure

```
supabase-lite-mcp/
├── src/
│   └── index.ts        # Main server implementation
├── dist/              # Compiled JavaScript (generated)
├── .env               # Environment variables (create from .env.example)
├── .env.example       # Environment template
├── package.json       # Node.js configuration
├── tsconfig.json      # TypeScript configuration
├── setup.sh          # Installation script
└── README.md         # Documentation
```

## Comparison with Full Supabase MCP

| Feature | Full Supabase MCP | Supabase Lite MCP |
|---------|------------------|-------------------|
| Commands | 26 | 8 (essential only) |
| Token Usage | ~14,800 | ~3,700 |
| Startup Time | ~2s | <1s |
| Memory Usage | ~50MB | ~30MB |
| Focus | Complete platform | Database only |

## Security

- 🔒 Never commit `.env` files
- 🔑 Use service role keys carefully (full database access)
- 🔄 Rotate keys regularly
- 🌐 Consider network isolation for production

## Troubleshooting

### Common Issues

**Server won't start:**
- Check Node.js version: `node --version` (requires v22+)
- Verify `.env` file exists with valid credentials
- Run `npm run build` to compile TypeScript

**Authentication errors:**
- Ensure you're using the service role key, not anon key
- Check if the key has been regenerated in Supabase dashboard

**Build errors:**
- Run `npm install` to install dependencies
- Check TypeScript version: `npx tsc --version`

## License

MIT

## Contributing

Contributions are welcome! Please open an issue or submit a pull request.

## Acknowledgments

Built with:
- [Model Context Protocol SDK](https://github.com/modelcontextprotocol/sdk)
- [Supabase JavaScript Client](https://github.com/supabase/supabase-js)
- [TypeScript](https://www.typescriptlang.org/)