# 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