MCP Synaptic

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

特性

🧠 记忆管理

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

📚 RAG数据库

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

🔄 实时通信

• 服务器发送事件（SSE）：实时更新记忆和RAG操作
• MCP协议：完整的模型上下文协议实现
• 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. 安装依赖项：

   # 对于基于API的嵌入（推荐 - 轻量级）
   uv sync
   
   # 对于本地嵌入（包含PyTorch - 较重）
   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_HOST=localhost
SERVER_PORT=8000
DEBUG=false
LOG_LEVEL=INFO

# 数据库配置
SQLITE_DATABASE_PATH=./data/synaptic.db
CHROMADB_PERSIST_DIRECTORY=./data/chroma

# 内存配置
DEFAULT_MEMORY_TTL_SECONDS=3600
MAX_MEMORY_ENTRIES=10000
MEMORY_CLEANUP_INTERVAL_SECONDS=300

# RAG配置
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（可选）
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)
    
    # 添加一个1小时过期的记忆
    await server.memory_manager.add(
        key="user_preference",
        data={"theme": "dark", "language": "en"},
        ttl_seconds=3600
    )
    
    # 在RAG数据库中存储文档
    await server.rag_database.add_document(
        content="MCP Synaptic是一款增强型服务器",
        metadata={"source": "文档", "version": "1.0"}
    )
    
    # 搜索相似文档
    results = await server.rag_database.search(
        query="增强型服务器",
        limit=5
    )
    
    await server.start()

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

CLI使用

# 使用自定义配置启动服务器
uv run mcp-synaptic server --host 0.0.0.0 --port 9000 --debug

# 初始化新项目
uv run mcp-synaptic init ./my-project

# 显示版本
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('事件:', data);
};

// 监听记忆过期事件
eventSource.addEventListener('memory_expired', function(event) {
    const data = JSON.parse(event.data);
    console.log('记忆过期:', data.key);
});

// 监听RAG文档更新
eventSource.addEventListener('document_added', function(event) {
    const data = JSON.parse(event.data);
    console.log('文档添加:', 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端点（替代方案）

开发

设置开发环境

# 安装开发依赖项
uv sync --group dev

# 安装预提交钩子
pre-commit install

# 运行测试
uv run pytest

# 运行类型检查
uv run mypy mcp_synaptic

# 运行代码检查
uv run ruff check mcp_synaptic
uv run black mcp_synaptic

# 运行所有检查
uv run pytest && uv run mypy mcp_synaptic && uv run ruff check mcp_synaptic

项目结构

mcp-synaptic/
├── mcp_synaptic/           # 主包
│   ├── core/              # 核心服务器功能
│   ├── mcp/               # MCP协议实现
│   ├── sse/               # 服务器发送事件
│   ├── rag/               # RAG数据库
│   ├── memory/            # 记忆管理
│   ├── config/            # 配置
│   └── utils/             # 工具
├── tests/                 # 测试套件
│   ├── unit/             # 单元测试
│   └── integration/      # 集成测试
├── data/                 # 数据存储
├── docker/               # Docker配置
└── docs/                 # 文档

贡献

1. 分叉仓库
2. 创建特性分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m '添加神奇特性'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 打开拉取请求

开发指南

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

测试

# 运行所有测试
uv run pytest

# 运行覆盖率测试
uv run pytest --cov=mcp_synaptic --cov-report=html

# 运行特定测试文件
uv run pytest tests/unit/test_memory.py

# 只运行集成测试
uv run pytest tests/integration/

性能

基准测试

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

优化建议

• 使用Redis进行分布式设置
• 根据用例调整嵌入模型
• 配置合适的TTL值
• 监控内存清理间隔

部署

生产部署

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

# 使用systemd服务
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系统中的记忆与知识桥梁。