MCP Synaptic

MCP Synaptic

ローカル RAG（検索拡張生成）データベースと有効期限付きメモリ機能を備えた、メモリ拡張型の MCP（Model Context Protocol）サーバーです。

機能

🧠 メモリ管理

• 有効期限付きメモリ：設定可能な TTL（有効期間）を指定して、一時的なメモリを保存します
• メモリの種類：さまざまなメモリカテゴリ（短期、長期、一時）に対応します
• 自動クリーンアップ：期限切れのメモリを削除するバックグラウンド処理を実行します
• Redis 統合：分散メモリストレージ用に、オプションで Redis バックエンドを利用できます

📚 RAG データベース

• ローカルベクトルストレージ：ドキュメントを保存する ChromaDB ベースのベクトルデータベースです
• 埋め込みモデル：sentence-transformers モデルを標準でサポートします
• セマンティック検索：類似度に基づいてドキュメントを取得します
• ドキュメント管理：バージョン管理を伴うドキュメントの追加、更新、削除ができます

🔄 リアルタイム通信

• Server-Sent Events（SSE）：メモリ操作と RAG 操作のリアルタイム更新に対応します
• MCP プロトコル：Model Context Protocol を完全に実装しています
• WebSocket 対応：代替のリアルタイム通信チャネルを利用できます
• イベントストリーミング：メモリの有効期限切れやドキュメントの変更をリアルタイムで更新します

🐳 Docker 対応

• 整理された Docker 構成：ベース、オーバーライド、バリアントを明確に分離しています
• 複数の環境に対応：Laptop（Traefik HTTP）と Desktop（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. リポジトリをフォークします
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/

パフォーマンス

ベンチマーク

• メモリ操作：毎秒 10,000 件以上
• RAG 検索：応答時間 100 ms 未満
• 同時接続数：1,000 件以上の SSE 接続
• メモリ使用量：ベースラインで 100 MB 未満

最適化のヒント

• 分散構成では 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 ファイルを参照してください。

謝辞

• MCP 仕様については、Model Context Protocol に感謝します
• ベクトルデータベース機能については、ChromaDB に感謝します
• Web フレームワークについては、FastAPI に感謝します
• 埋め込みについては、Sentence Transformers に感謝します

サポート

• 📖 ドキュメント
• 🐛 課題トラッカー
• 💬 ディスカッション
• 📧 メールサポート

---

MCP Synaptic - インテリジェントな AI システムのために、記憶と知識をつなぎます。