gemsAPI
A full-stack interface for managing and executing custom AI instructions ("Gems") with Supabase auth, Gemini multimodal chat, and optional MCP integration.
Since the standard Gemini Gems interface does not currently support direct API access, gemsAPI provides a backend service and web UI for storing, managing, and executing custom AI prompts with current Gemini text and image-capable models.
✨ Features
- Gem Management: Create, edit, and delete custom AI instruction sets ("Gems") stored in Supabase
- Authenticated Web UI: Google OAuth via Supabase with admin detection and protected CRUD/API access
- Flexible Execution: Execute Gems by name or via free-form generation with custom prompts
- Multimodal Chat: Upload or drag/drop image attachments into chat and send them to Gemini
- Inline Image Display: Render generated Gemini image parts directly inside the chat thread
- Model Routing: Use separate configurable default models for text chat and image-capable chat
- MCP Integration: Model Context Protocol (MCP) server for Claude Desktop and other MCP clients
- Authentication: Supabase-based authentication with Row Level Security (RLS)
- Rate Limiting: Built-in rate limiting to prevent abuse
- React UI: Modern web interface for gem management, testing, and multimodal execution
- Docker Ready: Multi-stage container build installs frontend dependencies in the builder image and serves built assets from FastAPI
🏗️ Architecture
System Architecture
gemsAPI is a full-stack application with a React frontend, FastAPI backend, Supabase database, and Google Gemini AI integration. The system supports multiple transport mechanisms including REST API, MCP SSE transport, and MCP STDIO for Claude Desktop.
Key Components:
- Frontend: React 19 + Vite with Tailwind/PostCSS build pipeline, served statically by FastAPI
- Backend: FastAPI with async/await, rate limiting, and CORS
- Database: Supabase (PostgreSQL) with Row Level Security
- AI Integration: Google Gemini API with text/image model routing, image attachment handling, and thinking artifact cleanup
- MCP Server: FastMCP integration for tool-based access
Data Flows
Key Workflows:
- Create/Manage Gem: User → React UI → OAuth → FastAPI → RLS Check → Supabase
- Execute Gem: User → GemChat → optional image attachment / image response mode → Gemini API → cleaned text and inline image parts → chat thread
- MCP Integration: MCP Client → Transport (STDIO/SSE) → FastMCP → API Auth → Database
- Authentication: Google OAuth → Supabase session hydration in
AuthContext→ Bearer token → RLS Enforcement
Database Schema
Tables:
auth.users- Supabase built-in user authenticationpublic.gems- Gem definitions with user ownership and RLSpublic.admin_users- Administrator accounts for full access
Row Level Security (RLS):
- Users can only manage their own gems
- Admin users can manage all gems
- Service role bypasses RLS for backend operations
🚀 Quick Start
Prerequisites
- Docker & Docker Compose
- Supabase account and project
- Google Gemini API key
Installation
1. Clone the repository
git clone https://github.com/sruckh/gemsAPI.git
cd gemsAPI
2. Configure environment variables
Create a .env file in the project root:
cp .env.example .env
Edit .env with your credentials:
# Required
GEMINI_API_KEY=your_gemini_api_key
SUPABASE_URL=your_supabase_project_url
SUPABASE_KEY=your_supabase_service_role_key
VITE_SUPABASE_ANON_KEY=your_supabase_anon_key
# Optional (with defaults)
GEMINI_TEXT_MODEL=gemini-flash-latest
GEMINI_IMAGE_MODEL=gemini-3.1-flash-image
GEMINI_PRO_IMAGE_MODEL=gemini-3-pro-image
PORT=8000
NODE_ENV=production
# MCP Integration
ENABLE_MCP=true
API_TOKEN=your_secure_api_token_for_mcp
3. Start with Docker Compose
docker compose up -d --build
The service will be available at http://localhost:8000
Notes:
- The Docker builder stage runs
npm installinside the container image. No host-side npm install is required when you deploy withdocker compose build. - The frontend uses a local Tailwind/PostCSS build now;
cdn.tailwindcss.comis no longer required at runtime. - In Docker,
docker-compose.ymlpassesSUPABASE_URLinto the frontend build asVITE_SUPABASE_URL.
Local Development (Manual)
If you prefer to run without Docker:
1. Install dependencies
Frontend:
npm install
Backend:
pip install -r requirements.txt
2. Run frontend (development mode)
npm run dev
3. Run backend
uvicorn fastapi_server:app --reload --host 0.0.0.0 --port 8000
Notes:
- The frontend expects
VITE_SUPABASE_URLandVITE_SUPABASE_ANON_KEYat build/dev time. For manual local development, define them in a Vite-readable env file such as.env.local. - The backend expects
SUPABASE_URL,SUPABASE_KEY, andGEMINI_API_KEYat runtime. NODE_ENV=productionis used by the backend, but Vite may warn if that variable is present during frontend builds because it prefers controlling frontend mode itself.
📖 Documentation
API Reference
Gems Management
Execution
MCP Integration
Authentication
Configuration
Database Schema
For the complete database schema with all tables, relationships, and RLS policies, see the ER Diagram above.
Quick Reference:
- Full SQL schema available in
docs/supabase/gems_table.sql - RLS ensures users can only access their own gems (except admins)
- Admin users table for elevated permissions
MCP Integration
gemsAPI provides Model Context Protocol (MCP) integration for tool-based access to gems.
Claude Desktop Setup
- Download the STDIO script:
curl -H "Authorization: Bearer YOUR_TOKEN" \
https://your-domain.com/api/mcp/stdio-script \
-o gemsapi_mcp.py
- Edit your Claude Desktop config:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
- macOS:
{
"mcpServers": {
"gemsapi": {
"command": "python",
"args": ["/path/to/gemsapi_mcp.py"],
"env": {
"GEMSAPI_TOKEN": "YOUR_SUPABASE_ACCESS_TOKEN",
"GEMSAPI_URL": "https://your-domain.com"
}
}
}
}
- Install dependencies:
pip install fastmcp httpx
- Restart Claude Desktop
Available MCP Tools
gems.list: List all gems for authenticated usergems.get: Get a specific gem by ID or namegems.search: Search gems by name or description
Web Chat Behavior
- The chat UI supports plain text prompts, image upload, and drag/drop image attachment.
- If a request includes attached input images, the backend automatically uses the configured image-capable Gemini model.
- If
Image responsesis toggled on in the UI, the backend also allows Gemini to return inline generated image parts. Image responsesdoes not force the model to always return an image. Text-only output can still be correct for a given Gem or prompt.
Security Considerations
Secret hygiene:
- Never add
SUPABASE_KEY(service role) toVITE_*variables - The backend fails to start if service key is exposed to frontend
- Use
API_TOKENfor server-to-server communication only - Run
npm run secret:checkbefore committing to scan for leaked tokens
Authentication:
- All data operations require valid Supabase JWT token
- Row Level Security (RLS) ensures users can only access their own gems
- Admin operations require entry in
admin_userstable - The web UI uses Supabase OAuth and explicitly hydrates the session on load before rendering authenticated views
🧪 Testing
Manual Testing
# Health check
curl http://localhost:8000/healthz
# List gems (requires auth token)
curl -H "Authorization: Bearer YOUR_TOKEN" \
http://localhost:8000/api/gems
# Execute a gem
curl -X POST http://localhost:8000/api/gems/execute \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_TOKEN" \
-d '{"gem_name": "MyGem", "user_prompt": "Hello!"}'
# Free-form generation with image-capable response mode
curl -X POST http://localhost:8000/api/gemini/generate \
-H "Content-Type: application/json" \
-d '{"system_instructions":"You are helpful.","user_prompt":"Describe this image.","images":[{"data":"BASE64_BYTES","mime_type":"image/png","name":"example.png"}],"generate_images":false}'
Security Scan
# Scan for leaked secrets before committing
npm run secret:check
📦 Build & Deployment
Docker Build
# Build image
docker build -t gemsapi:latest .
# Run container
docker run -p 8000:8000 --env-file .env gemsapi:latest
Production Deployment
- Set
NODE_ENV=productionin.env - Ensure
VITE_SUPABASE_KEYis NOT set (security check) - Rebuild the container image so the builder stage installs frontend deps and regenerates
dist - Use reverse proxy (Nginx, Traefik) for SSL
- Configure proper CORS origins via
FRONTEND_URL
Nginx Proxy Manager Example
# Forward proxy configuration
location /gemsapi/ {
proxy_pass http://gemsapi:8000/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
🤝 Contributing
Contributions are welcome! Please follow these guidelines:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Run tests and security checks
- Commit changes (
git commit -m 'Add amazing feature') - Push to branch (
git push origin feature/amazing-feature) - Open a Pull Request
Development Guidelines
- Follow existing code style and patterns
- Add TypeScript types for all new code
- Update documentation for API changes
- Test MCP integration when modifying tools
- Rebuild the container after frontend dependency changes so the builder stage picks them up
- Run
npm run secret:checkbefore committing
📄 License
This project is licensed under the MIT License - see LICENSE for details.
🙏 Acknowledgments
- Google - For the Gemini AI models and API
- Supabase - For the excellent PostgreSQL backend service
- FastAPI - For the modern Python web framework
- React - For the frontend UI framework
- FastMCP - For MCP integration toolkit
📚 Additional Documentation
- Phase 2 MCP Integration - MCP implementation details
- CLAUDE.md - Project-specific guidance for Claude Code
- AGENTS.md - Agent configuration and usage