Self-hosted LLM MCP Server

# 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 ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ MCP Client │ │ MCP Server │ │ Supabase DB │ │ │◄──►│ │◄──►│ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ ▼ ┌─────────────────┐ │ Ollama LLM │ │ (Self-hosted) │ └─────────────────┘ ``` ## Quick Start ### Prerequisites - Docker and Docker Compose - Node.js 18+ (for local development) - Supabase account and project ### 1. Clone and Setup ```bash git clone <repository-url> cd mcp-server-selfhosted cp env.example .env ``` ### 2. Configure Environment Edit `.env` file with your configuration: ```env # Supabase Configuration SUPABASE_URL=your_supabase_url_here SUPABASE_ANON_KEY=your_supabase_anon_key_here SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key_here # Self-hosted LLM Configuration LLM_BASE_URL=http://localhost:11434 LLM_MODEL=llama2 LLM_TIMEOUT=30000 # MCP Server Configuration MCP_SERVER_PORT=3000 MCP_SERVER_HOST=localhost # Logging LOG_LEVEL=info LOG_FORMAT=json ``` ### 3. Start with Docker Compose ```bash docker-compose up -d ``` This will start: - Ollama service (self-hosted LLM) - MCP Server - Health checks and monitoring ### 4. Verify Installation ```bash # Check if services are running docker-compose ps # Test MCP server health curl http://localhost:3000/health # Test Ollama connection curl http://localhost:11434/api/tags ``` ### 5. Test Build Locally (Optional) ```bash # Test TypeScript compilation npm run build # Test HTTP server npm run start:http # Test health endpoint curl http://localhost:3000/health ``` ## 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:** ```json { "name": "query_database", "arguments": { "query": "SELECT * FROM users WHERE active = true", "table": "users" } } ``` ### 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:** ```json { "name": "generate_text", "arguments": { "prompt": "Explain quantum computing in simple terms", "maxTokens": 500, "temperature": 0.7 } } ``` ### 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:** ```json { "name": "store_data", "arguments": { "table": "documents", "data": { "title": "My Document", "content": "Document content here", "author": "John Doe" } } } ``` ### 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:** ```json { "name": "retrieve_data", "arguments": { "table": "documents", "filters": { "author": "John Doe" }, "limit": 10 } } ``` ## Development ### Local Development Setup 1. **Install Dependencies:** ```bash npm install ``` 2. **Start Ollama (if not using Docker):** ```bash # Install Ollama curl -fsSL https://ollama.ai/install.sh | sh # Pull a model ollama pull llama2 # Start Ollama ollama serve ``` 3. **Start Supabase (if using local instance):** ```bash # Install Supabase CLI npm install -g supabase # Start local Supabase supabase start ``` 4. **Run Development Server:** ```bash npm run dev ``` ### Testing The project includes comprehensive testing: ```bash # Run unit tests npm test # Run tests with coverage npm run test:coverage # Run E2E tests npm run test:e2e # Run all tests npm run test && npm run test:e2e ``` ### Code Quality ```bash # Lint code npm run lint # Fix linting issues npm run lint:fix ``` ## 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** ```bash # Check if Ollama is running curl http://localhost:11434/api/tags # Restart Ollama service docker-compose restart ollama ``` 2. **Supabase Connection Failed** ```bash # 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** ```bash # Check logs docker-compose logs mcp-server # Check health curl http://localhost:3000/health ``` 4. **Docker Build Fails with "tsc: not found"** ```bash # 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** ```bash # 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