MCP Synaptic

MCP Synaptic

一个支持记忆增强的 MCP（Model Context Protocol）服务，具备本地 RAG（检索增强生成）数据库和记忆过期功能。

特性

🧠 记忆管理

• 过期记忆：存储可配置 TTL（生存时间）的临时记忆
• 记忆类型：支持不同类别的记忆（短期、长期、短暂）
• 自动清理：通过后台进程移除过期记忆
• Redis 集成：可选的 Redis 后端，用于分布式记忆存储

📚 RAG 数据库

• 本地向量存储：基于 ChromaDB 的向量数据库，用于存储文档
• 嵌入模型：内置支持 sentence-transformers 模型
• 语义搜索：基于相似度检索文档
• 文档管理：添加、更新和删除文档，并支持版本管理

🔄 实时通信

• 服务器发送事件（SSE）：为记忆和 RAG 操作提供实时更新
• MCP 协议：完整实现 Model Context Protocol
• WebSocket 支持：可选的实时通信渠道
• 事件流：实时更新记忆过期和文档变更信息

🐳 支持 Docker

• 有序的 Docker 结构：清晰分离基础配置、覆盖配置和变体
• 多环境支持：笔记本电脑（Traefik HTTP）和桌面设备（Traefik WEB）配置
• 开发与生产：提供专用变体并进行相应优化
• 灵活部署：可组合配置文件，适用于不同场景

快速开始

先决条件

• Python 3.11 或更高版本
• UV 包管理器
• Docker（可选，用于容器化部署）

安装

1. 克隆仓库：

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

2. 安装依赖项：

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

3. 初始化项目：

   uv run mcp-synaptic init
   

4. 启动服务：

   uv run mcp-synaptic server
   

服务默认将在 http://localhost:8000 上启动。

Docker 部署

1. 使用 Docker Compose 构建并运行：

   docker-compose up --build
   

2. 或运行单个容器：

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

配置

环境变量

在项目根目录创建 .env 文件（使用 .env.example 作为模板）：

# 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

记忆类型

• 短暂：生命周期极短的记忆（数秒至数分钟）
• 短期：基于会话的记忆（数分钟至数小时）
• 长期：持久记忆（数天至数周）
• 永久：永不过期的记忆

嵌入配置

基于 API 的嵌入（推荐）

• 轻量级部署，无需 PyTorch 依赖项
• 可与 LiteLLM、OpenAI API 或任何兼容 OpenAI 的端点配合使用
• 设置 EMBEDDING_PROVIDER=api 并配置 EMBEDDING_API_BASE

本地嵌入

• 包含完整的 PyTorch 和 sentence-transformers
• 无需依赖外部 API，但容器体积大得多
• 设置 EMBEDDING_PROVIDER=local 并使用 --extra local-embeddings 安装

使用示例

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 用法

# 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 客户端示例

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 端点

记忆管理

• POST /memory - 添加新记忆
• GET /memory/{key} - 按键检索记忆
• DELETE /memory/{key} - 删除记忆
• GET /memory - 列出所有记忆

RAG 数据库

• POST /rag/documents - 添加文档
• GET /rag/documents/{id} - 按 ID 获取文档
• POST /rag/search - 搜索文档
• DELETE /rag/documents/{id} - 删除文档

实时事件

• GET /events - 用于实时更新的 SSE 端点
• GET /ws - WebSocket 端点（可选）

开发

设置开发环境

# 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

项目结构

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

贡献

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 发起 Pull Request

开发指南

• 遵循 PEP 8 风格指南
• 为所有函数添加类型提示
• 编写全面的测试
• 为新功能更新文档
• 使用约定式提交消息

测试

# 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/

性能

基准测试

• 内存操作：每秒 10,000 次以上
• RAG 搜索：响应时间低于 100 毫秒
• 并发连接：1,000 个以上 SSE 连接
• 内存占用：基线低于 100MB

优化提示

• 在分布式部署中使用 Redis
• 根据使用场景调整嵌入模型
• 配置适当的 TTL 值
• 监控内存清理间隔

部署

生产环境部署

# 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

监控

• 健康检查端点：GET /health
• 指标端点：GET /metrics
• 管理界面：GET /admin

许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

致谢

• Model Context Protocol，提供 MCP 规范
• ChromaDB，提供向量数据库功能
• FastAPI，提供 Web 框架
• Sentence Transformers，提供嵌入功能

支持

• 📖 文档
• 🐛 问题跟踪
• 💬 讨论
• 📧 邮件支持

---

MCP Synaptic - 为智能 AI 系统连接记忆与知识。