mcp-server

solidus85/mcp-server

3.2

If you are the rightful owner of mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Model Context Protocol (MCP) server is a comprehensive platform designed for building AI-powered applications, integrating vector databases, PostgreSQL, and LLM capabilities.

MCP Server - Model Context Protocol Server with LLM Integration

A comprehensive Model Context Protocol (MCP) server implementation with vector database support, PostgreSQL integration, and LLM capabilities. This server provides a robust platform for building AI-powered applications with email management, document processing, and semantic search capabilities.

Features

Core Capabilities

  • Model Context Protocol (MCP) - Full implementation with stdio transport
  • Vector Database - ChromaDB integration for semantic search and embeddings
  • PostgreSQL Database - Relational data storage with async SQLAlchemy
  • LLM Integration - Support for OpenAI and Anthropic Claude APIs
  • REST API - FastAPI-based API with authentication and rate limiting
  • Email Management - Comprehensive email ingestion and organization system

Email Management System

  • Automatic person and project discovery from emails
  • Thread tracking and conversation management
  • Domain-based project assignment
  • Rich metadata storage using PostgreSQL JSONB
  • Full-text and semantic search capabilities

Technical Features

  • Async/await throughout for high performance
  • Database migrations with Alembic
  • Comprehensive logging and monitoring
  • Docker support for easy deployment
  • JWT-based authentication
  • Rate limiting and request throttling

Quick Start

Prerequisites

  • Python 3.12+
  • PostgreSQL 16+
  • Docker and Docker Compose (optional)

Local Development Setup

  1. Clone the repository
git clone https://github.com/yourusername/mcp-server.git
cd mcp-server
  1. Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
  1. Install dependencies
pip install -r requirements.txt
  1. Set up environment variables
cp .env.template .env
# Edit .env with your configuration
  1. Set up PostgreSQL database
# Create database and user
sudo -u postgres psql
CREATE DATABASE mcp_db;
CREATE USER mcp_user WITH PASSWORD 'your-secure-password';
GRANT ALL PRIVILEGES ON DATABASE mcp_db TO mcp_user;
\q

# Run setup script
sudo -u postgres psql -d mcp_db -f scripts/setup_database.sql
  1. Run database migrations
alembic upgrade head
  1. Start the server
python -m uvicorn src.api.app:app --reload

The API will be available at http://localhost:8000

Docker Setup

  1. Start all services
docker-compose up -d
  1. View logs
docker-compose logs -f mcp-server
  1. Stop services
docker-compose down

API Documentation

Once the server is running, you can access:

  • Interactive API docs: http://localhost:8000/docs
  • ReDoc documentation: http://localhost:8000/redoc
  • OpenAPI schema: http://localhost:8000/openapi.json

Key Endpoints

Email Management
  • POST /api/v1/emails/ingest - Ingest a new email
  • GET /api/v1/emails/ - Search emails
  • GET /api/v1/emails/{email_id} - Get email details
  • PATCH /api/v1/emails/{email_id} - Update email properties
People Management
  • POST /api/v1/people/ - Create a person
  • GET /api/v1/people/ - Search people
  • GET /api/v1/people/{person_id} - Get person details
  • POST /api/v1/people/{person_id}/projects/{project_id} - Assign person to project
Project Management
  • POST /api/v1/projects/ - Create a project
  • GET /api/v1/projects/ - Search projects
  • GET /api/v1/projects/{project_id} - Get project details
Vector Search
  • POST /api/v1/vectors/embed - Generate embeddings
  • POST /api/v1/vectors/search - Semantic search
  • POST /api/v1/vectors/index - Index documents
Authentication
  • POST /auth/register - Register new user
  • POST /auth/login - Login and get JWT token
  • GET /auth/me - Get current user info

Configuration

Environment Variables

Key environment variables (see .env.template for full list):

# Database
DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/mcp_db

# ChromaDB
CHROMA_HOST=localhost
CHROMA_PORT=8000
CHROMA_COLLECTION=mcp_vectors

# API Keys
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

# JWT Settings
JWT_SECRET=your-secret-key
JWT_ALGORITHM=HS256
JWT_EXPIRATION_HOURS=24

# Server Settings
MCP_SERVER_HOST=0.0.0.0
MCP_SERVER_PORT=8000
DEBUG=false
LOG_LEVEL=INFO

Project Structure

mcp-server/
ā”œā”€ā”€ src/
ā”‚   ā”œā”€ā”€ mcp/              # MCP protocol implementation
ā”‚   ā”‚   ā”œā”€ā”€ server.py      # MCP server core
ā”‚   ā”‚   ā”œā”€ā”€ tools.py       # Tool definitions
ā”‚   ā”‚   ā””ā”€ā”€ resources.py   # Resource management
ā”‚   ā”œā”€ā”€ database/          # Database layer
ā”‚   ā”‚   ā”œā”€ā”€ connection.py  # Database connection manager
ā”‚   ā”‚   ā”œā”€ā”€ models.py      # SQLAlchemy models
ā”‚   ā”‚   ā”œā”€ā”€ email_models.py # Email-specific models
ā”‚   ā”‚   ā”œā”€ā”€ repositories.py # Repository pattern implementation
ā”‚   ā”‚   ā””ā”€ā”€ migrations/    # Alembic migrations
ā”‚   ā”œā”€ā”€ api/              # REST API
ā”‚   ā”‚   ā”œā”€ā”€ app.py        # FastAPI application
ā”‚   ā”‚   ā”œā”€ā”€ routes/       # API endpoints
ā”‚   ā”‚   ā”œā”€ā”€ schemas/      # Pydantic schemas
ā”‚   ā”‚   ā””ā”€ā”€ middleware.py # Middleware stack
ā”‚   ā”œā”€ā”€ vector/           # Vector database
ā”‚   ā”‚   ā”œā”€ā”€ database.py   # ChromaDB integration
ā”‚   ā”‚   ā””ā”€ā”€ embeddings.py # Embedding generation
ā”‚   ā”œā”€ā”€ llm/              # LLM integration
ā”‚   ā”‚   ā”œā”€ā”€ client.py     # LLM client abstraction
ā”‚   ā”‚   ā””ā”€ā”€ prompts.py    # Prompt management
ā”‚   ā””ā”€ā”€ utils/            # Utilities
ā”œā”€ā”€ scripts/              # Utility scripts
ā”œā”€ā”€ tests/               # Test suite
ā”œā”€ā”€ config/              # Configuration files
ā”œā”€ā”€ docker-compose.yml   # Docker composition
ā”œā”€ā”€ Dockerfile          # Docker image definition
ā”œā”€ā”€ requirements.txt    # Python dependencies
ā””ā”€ā”€ README.md          # This file

Testing

Run Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

# Run specific test file
pytest tests/test_email_pipeline.py

Test Email Pipeline

python scripts/test_email_pipeline.py

Check Database Connection

python scripts/check_db.py

Development

Database Migrations

Create a new migration:

alembic revision --autogenerate -m "Description of changes"

Apply migrations:

alembic upgrade head

Rollback migration:

alembic downgrade -1

Adding New LLM Providers

  1. Create provider client in src/llm/providers/
  2. Implement the BaseLLMClient interface
  3. Register in src/llm/client.py

Extending the Email System

  1. Add new fields to models in src/database/email_models.py
  2. Create migration: alembic revision --autogenerate -m "Add new fields"
  3. Update schemas in src/api/schemas/email_schemas.py
  4. Add business logic to src/database/email_repositories.py

Production Deployment

Security Considerations

  1. Environment Variables: Never commit .env files
  2. Database Passwords: Use strong, unique passwords
  3. JWT Secret: Generate a secure random key
  4. API Keys: Store securely, rotate regularly
  5. HTTPS: Always use HTTPS in production
  6. Rate Limiting: Configure appropriate limits

Scaling

  • Use PostgreSQL connection pooling
  • Deploy multiple API server instances behind a load balancer
  • Consider Redis for caching and session storage
  • Use dedicated ChromaDB cluster for vector storage
  • Implement horizontal scaling for compute-intensive operations

Monitoring

  • Health check endpoint: /health
  • Metrics endpoint: /metrics (Prometheus format)
  • Structured logging with correlation IDs
  • Database query performance monitoring
  • API response time tracking

Troubleshooting

Common Issues

  1. Database Connection Error

    • Check PostgreSQL is running
    • Verify credentials in .env
    • Run scripts/check_db.py to test connection

  2. Permission Denied for Schema Public

    • Run: sudo -u postgres psql -d mcp_db -f scripts/setup_database.sql

  3. ChromaDB Connection Failed

    • Ensure ChromaDB is running
    • Check CHROMA_HOST and CHROMA_PORT settings

  4. LLM API Errors

    • Verify API keys are set correctly
    • Check rate limits and quotas

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests for new functionality
  5. Run tests and linting
  6. Submit a pull request

License

MIT License - see LICENSE file for details

Support

For issues and questions:

Acknowledgments

  • Model Context Protocol specification
  • FastAPI framework
  • ChromaDB vector database
  • PostgreSQL database
  • SQLAlchemy ORM
  • Anthropic and OpenAI for LLM APIs