MCP Synaptic

MCP突触

具有本地RAG（检索增强生成）数据库和过期内存功能的内存增强型MCP（模型上下文协议）服务器。

特性

🧠 内存管理

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

📚 RAG数据库

• 本地矢量存储：用于文档存储的基于ChromaDB的矢量数据库
• 嵌入模型：内置支持句子转换器模型
• 语义搜索：基于相似性的文档检索
• 文档管理：使用版本控制添加、更新和删除文档

🔄 实时通信

• 服务器发送事件（SSE）：内存和RAG操作的实时更新
• MCP协议：完整的模型上下文协议实现
• WebSocket支持：替代实时通信通道
• 事件流：内存过期和文档更改的实时更新

🐳 Docker就绪

• 有组织的Docker结构：基础、覆盖和变体的干净分离
• 多环境支持：笔记本电脑（Traefik HTTP）和台式机（TraefikWEB）配置
• 开发与生产：具有适当优化的专用变体
• 灵活部署：不同场景的可组合配置文件

快速开始

先决条件

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

安装

1. 克隆存储库：

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

1. 安装依赖项：

   # For API-based embeddings (recommended - lightweight)
   uv sync

   # For local embeddings (includes PyTorch - heavy)
   uv sync --extra local-embeddings

1. 初始化项目：

   uv run mcp-synaptic init

1. 启动服务器：

   uv run mcp-synaptic server

服务器将于启动 http://localhost:8000 默认情况下。

Docker部署

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

   docker-compose up --build

1. 或者运行单个容器：

   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和句子转换器
• 没有外部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. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

开发指南

• 遵循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/

演出

基准测试

• 存储器操作：10000+次/秒
• RAG搜索：低于100毫秒的响应时间
• 并发连接：1000+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许可证获得许可-请参阅 许可证 文件以获取详细信息。

致谢

• 模型上下文协议 对于MCP规范
• ChromaDB 矢量数据库功能
• 快速 API 对于web框架
• 句子转换 用于嵌入

支持

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

______________________________________________________________________

MCP突触 -连接智能人工智能系统的记忆和知识。