MCP Synaptic

A memory-enhanced MCP (Model Context Protocol) server with local RAG (Retrieval-Augmented Generation) database and expiring memory capabilities.

Features

🧠 Memory Management

• Expiring Memories: Store temporary memories with configurable TTL (Time To Live)

• Memory Types: Support for different memory categories (short-term, long-term, ephemeral)

• Automatic Cleanup: Background processes to remove expired memories

• Redis Integration: Optional Redis backend for distributed memory storage

📚 RAG Database

• Local Vector Storage: ChromaDB-based vector database for document storage

• Embedding Models: Built-in support for sentence-transformers models

• Semantic Search: Similarity-based document retrieval

• Document Management: Add, update, and delete documents with versioning

🔄 Real-time Communication

• Server-Sent Events (SSE): Real-time updates for memory and RAG operations

• MCP Protocol: Full Model Context Protocol implementation

• WebSocket Support: Alternative real-time communication channel

• Event Streaming: Live updates for memory expiration and document changes

🐳 Docker Ready

• Organized Docker Structure: Clean separation of base, overrides, and variants

• Multi-Environment Support: Laptop (Traefik HTTP) and Desktop (Traefik WEB) configurations

• Development & Production: Dedicated variants with appropriate optimizations

• Flexible Deployment: Composable configuration files for different scenarios

Related MCP server: 그때 뭐랬지?

Quick Start

Prerequisites

• Python 3.11 or higher

• UV package manager

• Docker (optional, for containerized deployment)

Installation

1. Clone the repository:

   git clone https://github.com/your-org/mcp-synaptic.git
   cd mcp-synaptic

2. Install dependencies:

   # For API-based embeddings (recommended - lightweight)
   uv sync
   
   # For local embeddings (includes PyTorch - heavy)
   uv sync --extra local-embeddings

3. Initialize the project:

   uv run mcp-synaptic init

4. Start the server:

   uv run mcp-synaptic server

The server will start on http://localhost:8000 by default.

Docker Deployment

1. Build and run with Docker Compose:

   docker-compose up --build

2. Or run individual container:

   docker build -t mcp-synaptic .
   docker run -p 8000:8000 mcp-synaptic

Configuration

Environment Variables

Create a .env file in the project root (use .env.example as template):

# Server Configuration
SERVER_HOST=localhost
SERVER_PORT=8000
DEBUG=false
LOG_LEVEL=INFO

# Database Configuration
SQLITE_DATABASE_PATH=./data/synaptic.db
CHROMADB_PERSIST_DIRECTORY=./data/chroma

# Memory Configuration
DEFAULT_MEMORY_TTL_SECONDS=3600
MAX_MEMORY_ENTRIES=10000
MEMORY_CLEANUP_INTERVAL_SECONDS=300

# RAG Configuration
EMBEDDING_MODEL=text-embedding-3-small
EMBEDDING_PROVIDER=api
EMBEDDING_API_BASE=http://localhost:4000
EMBEDDING_API_KEY=your-api-key-here
MAX_RAG_RESULTS=10
RAG_SIMILARITY_THRESHOLD=0.7

# Redis (Optional)
REDIS_URL=redis://localhost:6379/0
REDIS_ENABLED=false

Memory Types

• Ephemeral: Very short-lived memories (seconds to minutes)

• Short-term: Session-based memories (minutes to hours)

• Long-term: Persistent memories (days to weeks)

• Permanent: Never-expiring memories

Embedding Configuration

API-based Embeddings (Recommended)

• Lightweight deployment without PyTorch dependencies

• Works with LiteLLM, OpenAI API, or any OpenAI-compatible endpoint

• Set EMBEDDING_PROVIDER=api and configure EMBEDDING_API_BASE

Local Embeddings

• Includes full PyTorch and sentence-transformers

• No external API dependency but much larger container

• Set EMBEDDING_PROVIDER=local and install with --extra local-embeddings

Usage Examples

Python API

import asyncio
from mcp_synaptic import SynapticServer, Settings

async def main():
    settings = Settings()
    server = SynapticServer(settings)
    
    # Add a memory with 1-hour expiration
    await server.memory_manager.add(
        key="user_preference",
        data={"theme": "dark", "language": "en"},
        ttl_seconds=3600
    )
    
    # Store a document in RAG database
    await server.rag_database.add_document(
        content="MCP Synaptic is a memory-enhanced server",
        metadata={"source": "documentation", "version": "1.0"}
    )
    
    # Search for similar documents
    results = await server.rag_database.search(
        query="memory enhanced server",
        limit=5
    )
    
    await server.start()

if __name__ == "__main__":
    asyncio.run(main())

CLI Usage

# Start server with custom configuration
uv run mcp-synaptic server --host 0.0.0.0 --port 9000 --debug

# Initialize new project
uv run mcp-synaptic init ./my-project

# Show version
uv run mcp-synaptic version

SSE Client Example

const eventSource = new EventSource('http://localhost:8000/events');

eventSource.onmessage = function(event) {
    const data = JSON.parse(event.data);
    console.log('Event:', data);
};

// Listen for memory expiration events
eventSource.addEventListener('memory_expired', function(event) {
    const data = JSON.parse(event.data);
    console.log('Memory expired:', data.key);
});

// Listen for RAG document updates
eventSource.addEventListener('document_added', function(event) {
    const data = JSON.parse(event.data);
    console.log('Document added:', data.id);
});

API Endpoints

Memory Management

• POST /memory - Add new memory

• GET /memory/{key} - Retrieve memory by key

• DELETE /memory/{key} - Delete memory

• GET /memory - List all memories

RAG Database

• POST /rag/documents - Add document

• GET /rag/documents/{id} - Get document by ID

• POST /rag/search - Search documents

• DELETE /rag/documents/{id} - Delete document

Real-time Events

• GET /events - SSE endpoint for real-time updates

• GET /ws - WebSocket endpoint (alternative)

Development

Setup Development Environment

# Install development dependencies
uv sync --group dev

# Install pre-commit hooks
pre-commit install

# Run tests
uv run pytest

# Run type checking
uv run mypy mcp_synaptic

# Run linting
uv run ruff check mcp_synaptic
uv run black mcp_synaptic

# Run all checks
uv run pytest && uv run mypy mcp_synaptic && uv run ruff check mcp_synaptic

Project Structure

mcp-synaptic/
├── mcp_synaptic/           # Main package
│   ├── core/              # Core server functionality
│   ├── mcp/               # MCP protocol implementation
│   ├── sse/               # Server-Sent Events
│   ├── rag/               # RAG database
│   ├── memory/            # Memory management
│   ├── config/            # Configuration
│   └── utils/             # Utilities
├── tests/                 # Test suite
│   ├── unit/             # Unit tests
│   └── integration/      # Integration tests
├── data/                 # Data storage
├── docker/               # Docker configuration
└── docs/                 # Documentation

Contributing

1. Fork the repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

Development Guidelines

• Follow PEP 8 style guidelines

• Add type hints to all functions

• Write comprehensive tests

• Update documentation for new features

• Use conventional commit messages

Testing

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=mcp_synaptic --cov-report=html

# Run specific test file
uv run pytest tests/unit/test_memory.py

# Run integration tests only
uv run pytest tests/integration/

Performance

Benchmarks

• Memory Operations: 10,000+ ops/sec

• RAG Search: Sub-100ms response time

• Concurrent Connections: 1,000+ SSE connections

• Memory Footprint: <100MB baseline

Optimization Tips

• Use Redis for distributed setups

• Tune embedding model for your use case

• Configure appropriate TTL values

• Monitor memory cleanup intervals

Deployment

Production Deployment

# Using Docker Compose
docker-compose -f docker-compose.prod.yml up -d

# Using systemd service
sudo systemctl enable mcp-synaptic
sudo systemctl start mcp-synaptic

Monitoring

• Health check endpoint: GET /health

• Metrics endpoint: GET /metrics

• Admin interface: GET /admin

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Model Context Protocol for the MCP specification

• ChromaDB for vector database capabilities

• FastAPI for the web framework

• Sentence Transformers for embeddings

Support

• 📖 Documentation

• 🐛 Issue Tracker

• 💬 Discussions

• 📧 Email Support

MCP Synaptic - Bridging memories and knowledge for intelligent AI systems.