Skip to content

Commit 5d9ca75

Browse files
ringo380ringo380
committed
feat: comprehensive Supabase API integration with 120+ tools
- Add analytics tools for project insights and reports - Expand auth configuration with third-party providers and SSO - Add comprehensive billing management and usage tracking - Enhance database configuration with PostgreSQL and pooler settings - Add backup restore functionality with point-in-time recovery - Expand domain management with creation and initialization - Add network security with bans and read replica management - Add comprehensive project lifecycle management tools - Update all platform interfaces to support full API coverage - Maintain type safety and injectable tool patterns - Successfully resolve all TypeScript compilation errors Total tools expanded from ~25 to 120+ covering 90% of Supabase Management API v1
1 parent 199a0c4 commit 5d9ca75

30 files changed

+7048
-28
lines changed

‎packages/mcp-server-supabase/CHANGELOG.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# Changelog
2+
3+
All notable changes to the Supabase MCP Server will be documented in this file.
4+
5+
## [Unreleased]
6+
7+
### Added - Claude CLI Optimization Update
8+
- **Enhanced Authentication System**
9+
- Comprehensive token format validation with sanitization
10+
- Claude CLI specific client detection and error messaging
11+
- Multiple token source support (CLI flags, environment variables, config files)
12+
- Startup token validation to catch errors early
13+
- Context-aware error messages based on detected MCP client
14+
15+
- **~/.supabase Config File Support**
16+
- Automatic detection and parsing of ~/.supabase configuration file
17+
- KEY=value format support with fallback to multiple tokens
18+
- Claude CLI-specific warnings about config file usage
19+
- Environment variable recommendations for Claude CLI users
20+
21+
- **Runtime Mode Management (Claude CLI Optimized)**
22+
- Interactive read-only/write mode toggling with confirmations
23+
- Claude CLI-specific status indicators (🔒 read-only, 🔓 write mode)
24+
- Security validation and warnings for destructive operations
25+
- Real-time mode status monitoring and guidance
26+
27+
- **Interactive Project Switching**
28+
- Multi-project detection and formatted project lists for Claude CLI
29+
- Interactive project selection by ID or name
30+
- Project status indicators and detailed information display
31+
- Seamless runtime project switching with validation
32+
33+
- **New Runtime Tools Feature Group**
34+
- `toggle_read_only_mode`: Interactive mode switching with confirmations
35+
- `get_runtime_mode_status`: Current mode status with security info
36+
- `set_read_only_mode`: Explicit mode setting with validation
37+
- `validate_mode_change`: Pre-validation of mode change requirements
38+
- `switch_project`: Interactive project switching for multi-project setups
39+
- `get_current_project`: Current project details and status
40+
- `list_projects`: All available projects with Claude CLI formatting
41+
42+
- **Comprehensive Test Suite**
43+
- Config file parser tests with various input scenarios
44+
- Mode manager tests covering all Claude CLI interactions
45+
- Enhanced authentication tests for config file integration
46+
- Token resolution tests with multiple source priorities
47+
48+
### Changed
49+
- **Claude CLI Integration Priority**
50+
- Environment variables now preferred over config files for Claude CLI
51+
- All error messages include Claude CLI-specific guidance when detected
52+
- Interactive confirmations optimized for conversational AI interface
53+
- Tool descriptions and help text tailored for Claude CLI context
54+
55+
- **Token Resolution Priority**
56+
- Updated priority: CLI flags → Environment variables → Config file → None
57+
- Enhanced validation with detailed error messages and suggestions
58+
- Multi-token fallback support with sequential validation
59+
60+
- **Feature Group System**
61+
- Added 'runtime' feature group enabled by default
62+
- Updated default features to include runtime tools
63+
- Enhanced feature documentation with Claude CLI focus
64+
65+
### Fixed
66+
- Better handling of malformed or invalid access tokens
67+
- Improved error reporting with client-specific guidance
68+
- Enhanced token parsing to handle whitespace, quotes, and formatting issues
69+
- Config file permission warnings and security validation
70+
- Graceful fallback handling when no valid tokens found
71+
72+
### Security
73+
- Token format validation to prevent injection attacks
74+
- Config file permission checking and warnings
75+
- Interactive confirmations for potentially destructive operations
76+
- Enhanced authentication logging without exposing sensitive information
77+
- Mode change validation with security risk assessment
78+
79+
## [0.5.5] - Previous Release
80+
81+
### Added
82+
- Initial MCP server implementation
83+
- Supabase platform integration
84+
- Basic authentication support
85+
- Core tool functionality
86+
87+
---
88+
89+
This changelog follows the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.

‎packages/mcp-server-supabase/CLAUDE_CLI_IMPROVEMENTS.md‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
# Claude CLI Integration Improvements
2+
3+
This document summarizes the enhancements made to improve the Supabase MCP server's integration with Claude CLI and other MCP clients.
4+
5+
## Overview
6+
7+
The improvements focus on three main areas:
8+
1. **Enhanced Authentication & Token Handling**
9+
2. **Claude CLI-Specific Error Messaging**
10+
3. **Improved User Experience & Debugging**
11+
12+
## Key Improvements
13+
14+
### 1. Enhanced Token Validation (`src/auth.ts`)
15+
16+
**New Features:**
17+
- **Token Format Validation**: Validates Supabase token format (`sbp_*`) with proper regex patterns
18+
- **Token Sanitization**: Removes quotes, whitespace, and other common formatting issues
19+
- **Early Validation**: Validates tokens at startup rather than waiting for API calls
20+
- **Flexible Token Length**: Supports various Supabase token lengths while maintaining security
21+
22+
**Code Example:**
23+
```typescript
24+
const result = validateAndSanitizeToken(' "sbp_1234567890abcdef" ');
25+
// Returns: { isValid: true, sanitizedToken: 'sbp_1234567890abcdef' }
26+
```
27+
28+
### 2. Client Detection & Context-Aware Messaging
29+
30+
**New Features:**
31+
- **Claude CLI Detection**: Automatically detects when running under Claude CLI
32+
- **Context-Aware Errors**: Provides different error messages based on the detected client
33+
- **User Agent Analysis**: Uses client info and user agent for better detection
34+
35+
**Code Example:**
36+
```typescript
37+
const clientContext = detectClientContext(clientInfo, userAgent);
38+
if (clientContext.isClaudeCLI) {
39+
// Provide Claude CLI-specific guidance
40+
}
41+
```
42+
43+
### 3. Enhanced Error Handling (`src/management-api/index.ts`)
44+
45+
**Improvements:**
46+
- **Detailed Debug Logging**: Enhanced 401 error logging with client context
47+
- **Progressive Error Messages**: Structured error messages with actionable steps
48+
- **Client-Specific Guidance**: Different troubleshooting steps for Claude CLI vs other clients
49+
50+
**Before:**
51+
```
52+
Unauthorized. Please provide a valid access token to the MCP server via the --access-token flag or SUPABASE_ACCESS_TOKEN.
53+
```
54+
55+
**After:**
56+
```
57+
Unauthorized: Invalid or expired access token.
58+
59+
For Claude CLI users:
60+
1. Ensure SUPABASE_ACCESS_TOKEN is set in your environment
61+
2. Restart Claude CLI after setting the environment variable
62+
3. Check your MCP server configuration in Claude CLI settings
63+
64+
Token validation issues:
65+
- Supabase access tokens must start with "sbp_"
66+
- Generate a new token at https://supabase.com/dashboard/account/tokens
67+
68+
General troubleshooting:
69+
- Verify the token at https://supabase.com/dashboard/account/tokens
70+
- Ensure the token has not expired
71+
- Check that the token has appropriate permissions
72+
```
73+
74+
### 4. Startup Authentication Validation (`src/transports/stdio.ts`)
75+
76+
**New Features:**
77+
- **Startup Token Resolution**: Validates tokens before server initialization
78+
- **Multiple Token Sources**: CLI flags, environment variables with proper priority
79+
- **Warning System**: Provides warnings for suboptimal configurations
80+
- **Graceful Failure**: Clear error messages when authentication fails
81+
82+
### 5. Comprehensive Testing (`src/auth.test.ts`)
83+
84+
**Test Coverage:**
85+
- Token format validation and sanitization
86+
- Client context detection for Claude CLI
87+
- Error message generation for different scenarios
88+
- Token resolution with multiple sources
89+
- Authentication setup validation
90+
91+
## Usage Examples
92+
93+
### For Claude CLI Users
94+
95+
1. **Set Environment Variable:**
96+
```bash
97+
export SUPABASE_ACCESS_TOKEN="sbp_your_token_here"
98+
```
99+
100+
2. **Restart Claude CLI** to pick up the new environment variable
101+
102+
3. **The server will automatically:**
103+
- Detect Claude CLI usage
104+
- Validate token format
105+
- Provide Claude CLI-specific error messages if issues occur
106+
107+
### For Other MCP Clients
108+
109+
The improvements are backward compatible and provide enhanced error messaging for all MCP clients, with specific optimizations for Claude CLI.
110+
111+
## Configuration Files Updated
112+
113+
### `server.json`
114+
- Enhanced environment variable description with token format information
115+
- Added link to Supabase token generation page
116+
117+
### `README.md`
118+
- New "Claude CLI Configuration" section
119+
- Detailed troubleshooting guide
120+
- Enhanced setup instructions
121+
122+
## Security Considerations
123+
124+
- **Token Validation**: Prevents malformed tokens from reaching the API
125+
- **Input Sanitization**: Safely handles user input with proper validation
126+
- **Error Information**: Avoids leaking sensitive information in error messages
127+
- **Debug Logging**: Comprehensive logging for security monitoring without exposing secrets
128+
129+
## Migration Guide
130+
131+
These improvements are **fully backward compatible**. Existing MCP server configurations will continue to work without any changes.
132+
133+
**Optional Improvements:**
134+
- Set `SUPABASE_ACCESS_TOKEN` as an environment variable for better Claude CLI experience
135+
- Update MCP client configurations to use environment variables instead of CLI flags
136+
137+
## Testing
138+
139+
Run the comprehensive test suite:
140+
```bash
141+
pnpm test:unit -- src/auth.test.ts
142+
```
143+
144+
All existing tests continue to pass, with additional coverage for the new authentication features.
145+
146+
## Future Enhancements
147+
148+
Potential areas for future improvement:
149+
1. **Token Expiration Detection**: Check token expiration before API calls
150+
2. **Credential Refresh**: Automatic token refresh mechanisms
151+
3. **Multiple Token Support**: Support for different token types
152+
4. **Advanced Client Detection**: More sophisticated client detection logic
153+
5. **Metrics & Analytics**: Usage analytics for different client types

‎packages/mcp-server-supabase/server.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@
5252
"environment_variables": [
5353
{
5454
"name": "SUPABASE_ACCESS_TOKEN",
55-
"description": "Personal access token for Supabase API",
55+
"description": "Personal access token for Supabase API (format: sbp_...). Generate at https://supabase.com/dashboard/account/tokens",
5656
"format": "string",
5757
"is_required": true,
5858
"is_secret": true

0 commit comments

Comments
 (0)