MCP Server with Self-hosted LLM and Supabase Integration

A comprehensive Model Context Protocol (MCP) server that integrates with self-hosted LLM models via Ollama and Supabase database for data persistence and retrieval.

Features

• MCP Protocol Support: Full implementation of the Model Context Protocol specification

• Self-hosted LLM Integration: Support for Ollama-based LLM models (Llama2, CodeLlama, etc.)

• Supabase Database Integration: Complete CRUD operations with Supabase

• Docker Support: Containerized deployment with Docker Compose

• Comprehensive Testing: Unit tests with ≥90% coverage, integration tests, and E2E tests

• TypeScript: Fully typed implementation for better development experience

• Logging: Structured logging with configurable levels and formats

Architecture

Quick Start

Prerequisites

• Docker and Docker Compose

• Node.js 18+ (for local development)

• Supabase account and project

1. Clone and Setup

2. Configure Environment

Edit .env file with your configuration:

3. Start with Docker Compose

This will start:

• Ollama service (self-hosted LLM)

• MCP Server

• Health checks and monitoring

4. Verify Installation

5. Test Build Locally (Optional)

Available Tools

The MCP server provides the following tools:

1. query_database

Execute SQL queries on the Supabase database.

Parameters:

• query (string, required): SQL query to execute

• table (string, optional): Table name for context

Example:

2. generate_text

Generate text using the self-hosted LLM.

Parameters:

• prompt (string, required): Text prompt for the LLM

• maxTokens (number, optional): Maximum tokens to generate

• temperature (number, optional): Temperature for generation (0.0-1.0)

Example:

3. store_data

Store data in the Supabase database.

Parameters:

• table (string, required): Table name to store data

• data (object, required): Data to store

Example:

4. retrieve_data

Retrieve data from the Supabase database.

Parameters:

• table (string, required): Table name to retrieve data from

• filters (object, optional): Filters to apply

• limit (number, optional): Maximum number of records to retrieve

Example:

Development

Local Development Setup

1. Install Dependencies:

2. Start Ollama (if not using Docker):

3. Start Supabase (if using local instance):

4. Run Development Server:

Testing

The project includes comprehensive testing:

Code Quality

Docker Configuration

Dockerfile

The Dockerfile creates an optimized production image:

• Node.js 18 Alpine base

• Non-root user for security

• Health checks

• Multi-stage build for smaller image size

Docker Compose

The docker-compose.yml orchestrates:

• Ollama service for LLM

• MCP Server

• Health checks and dependencies

• Volume persistence for Ollama models

Security Considerations

1. SQL Injection Protection: Basic sanitization of SQL queries

2. Environment Variables: Sensitive data stored in environment variables

3. Non-root Container: Docker containers run as non-root user

4. Input Validation: Zod schemas for input validation

5. Error Handling: Comprehensive error handling without information leakage

Monitoring and Logging

Log Levels

• DEBUG: Detailed debugging information

• INFO: General information messages

• WARN: Warning messages

• ERROR: Error messages

Log Formats

• text: Human-readable format

• json: Structured JSON format for log aggregation

Health Checks

• HTTP endpoint: GET /health

• Docker health checks

• Service dependency checks

Troubleshooting

Common Issues

1. Ollama Connection Failed

   # Check if Ollama is running curl http://localhost:11434/api/tags # Restart Ollama service docker-compose restart ollama

2. Supabase Connection Failed

   # Verify environment variables echo $SUPABASE_URL echo $SUPABASE_ANON_KEY # Test connection curl -H "Authorization: Bearer $SUPABASE_ANON_KEY" $SUPABASE_URL/rest/v1/

3. MCP Server Not Starting

   # Check logs docker-compose logs mcp-server # Check health curl http://localhost:3000/health

4. Docker Build Fails with "tsc: not found"

   # This is fixed in the current Dockerfile # The issue was NODE_ENV=production preventing dev dependencies installation # Solution: Set NODE_ENV=development during build phase # If you still encounter issues, try: docker-compose build --no-cache

5. TypeScript Compilation Errors

   # Test build locally first npm run build # Check for missing dependencies npm install # Clear node_modules and reinstall rm -rf node_modules package-lock.json npm install

Performance Optimization

1. LLM Performance

   • Use GPU-enabled Ollama for better performance

   • Adjust model parameters (temperature, max_tokens)

   • Consider model size vs. quality trade-offs

2. Database Performance

   • Use connection pooling

   • Optimize SQL queries

   • Consider indexing strategies

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests for new functionality

5. Ensure all tests pass

6. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

• Create an issue in the repository

• Check the troubleshooting section

• Review the test cases for usage examples