feat: comprehensive API integration + automatic project detection & enhanced authentication

[ringo380]

Summary

This PR dramatically expands the Supabase MCP server from ~25 tools covering ~20% of the Supabase Management API to 120+ tools covering ~90% of the API surface. Additionally, it introduces comprehensive authentication enhancements including automatic project detection and enhanced token management for seamless developer workflows.

🆕 Authentication Enhancements (Latest Update)

Automatic Project Detection

• Smart Working Directory Detection: Automatically detects Supabase project configuration from current working directory
• Multi-File Support: Scans .env, .env.local, .supabase/config.toml, and .supabase/.env files with priority system
• Framework Agnostic: Supports Next.js, React, Vite, and other framework-specific environment variables
• Zero Configuration: Projects with proper .env setup work immediately without manual configuration

Enhanced Personal Access Token Detection

• CLI Integration: Automatic detection from ~/.supabase/access-token (created by supabase login)
• Multiple Sources: Supports environment variables, CLI directory, and config files
• Smart Fallback: Comprehensive fallback chain ensures reliable authentication
• Seamless Workflow: Works perfectly with existing supabase login workflow

Dual Authentication Architecture

• Personal Token Mode: Uses Supabase Management API with personal access tokens
• Project Keys Mode: Uses project-specific anon/service keys when available
• Automatic Switching: Intelligently switches between modes based on available credentials
• Secure Fallback: Graceful degradation when credentials are unavailable

Developer Experience Improvements

• Zero Setup: Simply run npx @supabase/mcp-server-supabase from any Supabase project directory
• Auto-Discovery: Server automatically discovers and switches to local project context
• Framework Support: Works with Next.js, React, Vite environment variable conventions
• CLI Harmony: Perfect integration with Supabase CLI workflows

🚀 Comprehensive API Integration (Core Features)

New Tool Categories

• Analytics Tools (6 tools): Project insights, performance reports, usage analytics, and traffic monitoring
• Auth Configuration Tools (15 tools): Third-party providers, SSO configuration, JWT management, and signing keys
• Billing Tools (12 tools): Subscription management, usage tracking, add-on management, and cost monitoring
• Domain Tools (8 tools): Custom domain creation, DNS management, certificate handling, and subdomain configuration
• Network Security Tools (15 tools): IP restrictions, SSL enforcement, network bans, and read replica management
• Project Management Tools (25 tools): Complete project lifecycle, configuration management, and administrative operations
• Secrets Tools (12 tools): API key management, JWT templates, and security token operations
• Runtime Tools (8 tools): Claude CLI optimized mode management and project switching

Enhanced Existing Categories

• Database Tools: Added comprehensive configuration and backup management
• Storage Tools: Enhanced with advanced configuration options
• Edge Functions: Maintained existing functionality with improved type safety

🏗️ Architecture Updates

Authentication System Overhaul

• Project Context Detection (src/config/project-context.ts): Core module for working directory scanning
• Enhanced Token Detection (src/config/supabase-config.ts): Multiple token source support with CLI integration
• Dual Authentication Modes (src/auth.ts): Smart switching between personal tokens and project keys
• Platform Integration (src/platform/api-platform.ts): Enhanced to leverage project context for key resolution

Platform Architecture Updates

• Expanded Platform Interfaces: Updated all platform operation interfaces to support the full API surface
• Type Safety: Maintained strict TypeScript compliance across all 120+ tools
• Injectable Tool Pattern: Consistent use of the injectable tool pattern with proper annotations
• Feature Group System: New feature groups: analytics, auth, billing, domains, network, project, secrets, runtime

Key Features

• Full API Coverage: 90% coverage of Supabase Management API v1 (135 total endpoints)
• Backward Compatibility: All existing tools and interfaces remain unchanged
• Read-Only Mode Support: Proper read-only restrictions for all new tools
• Project Scoping: Full support for project-scoped vs account-wide operations
• Comprehensive Annotations: Proper tool annotations for MCP client UI/display
• Claude CLI Integration: Enhanced runtime tools specifically optimized for Claude CLI workflows

🧪 Testing

• ✅ All existing tests continue to pass
• ✅ TypeScript compilation succeeds with no errors
• ✅ New authentication features tested with comprehensive unit tests
• ✅ Project detection tested across multiple framework types
• ✅ Token resolution tested with multiple source priorities
• ✅ Injectable tool pattern maintained consistently
• ✅ Proper error handling and read-only mode restrictions
• ⚠️ Some e2e tests expected to fail due to missing API keys (existing limitation)

🔄 Breaking Changes

None - This is purely additive functionality. All existing tools and interfaces remain unchanged.

📝 Migration Guide

No migration required - This is a backward-compatible enhancement. Users can:

1. Continue using existing tools - No changes to current functionality
2. Benefit from automatic detection - Projects with .env files work automatically
3. Use enhanced CLI integration - supabase login now works seamlessly
4. Gradually adopt new features - Use --features flag to enable specific new tool groups

New Usage Patterns

# Zero configuration - works automatically in Supabase project directories
npx -y @supabase/mcp-server-supabase@latest

# Still works with manual configuration
npx -y @supabase/mcp-server-supabase@latest --project-ref=<project-ref>

# Use with Supabase CLI workflow
supabase login
npx -y @supabase/mcp-server-supabase@latest

# Enable specific feature groups
npx -y @supabase/mcp-server-supabase@latest --features=database,analytics,auth,billing

🔧 Implementation Details

Authentication Architecture

• Priority System: CLI flags → Environment variables → Project context → Config files → None
• Framework Support: Automatically detects Next.js, React, Vite environment variable patterns
• Security: Proper file permission checking and credential validation
• Error Handling: Comprehensive error messages and fallback behavior

Code Quality

• 46 files changed with 4,715 insertions, 735 deletions
• Comprehensive test coverage for authentication and API functionality
• Proper error handling and validation throughout
• Consistent code style using existing Biome configuration

🚀 Future Considerations

This expansion provides the foundation for:

• Remote MCP Server: Full API coverage enables comprehensive remote MCP deployment
• Advanced Integrations: Rich tool set supports complex automation workflows
• Enterprise Features: Comprehensive billing, security, and management capabilities
• AI Assistant Workflows: 120+ tools enable sophisticated AI-driven Supabase management
• Enhanced Developer Experience: Automatic detection removes setup friction

📚 Documentation Updates

• README: Updated with automatic detection features and enhanced setup instructions
• CHANGELOG: Comprehensive documentation of all new features and enhancements
• Claude Project Memory: Updated with detailed architecture and feature descriptions

---

Note: This PR maintains the project's pre-1.0 philosophy of rapid feature development while ensuring backward compatibility and type safety. The comprehensive API coverage combined with intelligent authentication makes this the definitive solution for AI assistant integration with Supabase projects.

[ringo380]

This PR has been superseded by #160 which includes:

• All features from this PR
• Security improvements (cleaned branch with comprehensive scanning)
• Write mode as default with clear warnings
• Response size management improvements
• Latest upstream improvements from v0.5.6 (simplified get_logs API)
• Restored advanced filtering functionality

Please review #160 instead.