Brain Server - MCP Knowledge Embedding Service

Brain Server - MCP ナレッジ埋め込みサービス

ナレッジ埋め込みとベクトル検索を管理するための、高機能な MCP（Model Context Protocol）サーバーです。

特長

• ベクトル埋め込み：ナレッジコンテンツの高品質な埋め込みを生成します
• セマンティック検索：キーワードだけでなく、意味に基づいてナレッジを検索します
• MCP 準拠：AI との統合に向けて Model Context Protocol に準拠しています
• Brain 管理：ナレッジをドメインごとの Brain に整理します
• コンテキストを考慮した検索：理解を深めるため、周辺のコンテキストも含めます
• 進捗の追跡：時間のかかる処理をリアルタイムで監視します

埋め込みモデル

このサーバーでは、埋め込みモデルを使ってテキストをベクトル表現に変換します。

• 初回実行時に、サーバーが埋め込みモデルを自動的にダウンロードします
• デフォルトでは、HuggingFace の Xenova/all-MiniLM-L6-v2 を使用します
• モデルは初回ダウンロード後、ローカルにキャッシュされます
• テスト用に、ランダムなベクトルを生成する MockEmbeddingProvider を利用できます

.env ファイルで使用するモデルを設定できます。

EMBEDDING_MODEL=Xenova/all-MiniLM-L6-v2

対応モデルは次のとおりです。

• Xenova/all-MiniLM-L6-v2（デフォルト、384 次元）
• Xenova/bge-small-en-v1.5（384 次元）
• Xenova/bge-base-en-v1.5（768 次元）
• Xenova/e5-small-v2（384 次元）

Docker ですぐに始める

Brain Server を実行する最も簡単な方法は、Docker と Docker Compose を使用することです。

# Clone the repository
git clone https://github.com/patrickdeluca/mcp-brain-server.git
cd mcp-brain-server

# Start the server with Docker Compose
docker-compose up -d

# View logs
docker-compose logs -f

サーバーは http://localhost:3000 で利用でき、MongoDB は同じコンテナ内で実行されます。

Claude Desktop で Docker を使用する

Docker 化された Brain Server を Claude Desktop で使用するには、claude_desktop_config.json を更新します。

{
  "brain-server": {
    "command": "docker",
    "args": ["run", "--rm", "-p", "3000:3000", "patrickdeluca/mcp-brain-server:latest"],
    "env": {}
  }
}

ローカルインストールの前提条件

MongoDB のインストール

Docker を使用しない場合、Brain Server には MongoDB が必要です（ベクトル検索にはバージョン 6.0 以降を推奨します）。

最新のインストール方法（推奨）

Ubuntu/Debian

# Import public key
wget -qO - https://www.mongodb.org/static/pgp/server-6.0.asc | sudo tee /etc/apt/trusted.gpg.d/mongodb-6.0.asc
# Add MongoDB repository
echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu focal/mongodb-org/6.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-6.0.list
# Update package database and install MongoDB
sudo apt-get update
sudo apt-get install -y mongodb-org
# Start MongoDB service
sudo systemctl start mongod

macOS

# Using Homebrew
brew tap mongodb/brew
brew install [email protected]
brew services start [email protected]

Windows

1. MongoDB ダウンロードセンターから MongoDB 6.0 インストーラーをダウンロードします
2. インストーラーを実行し、セットアップウィザードの手順に従います
3. Windows の「サービス」コンソールから MongoDB を起動します

MongoDB のインストールを確認する

MongoDB が正常に実行されていることを確認するには、次のコマンドを実行します。

mongosh --eval "db.version()"

手動インストール

# Clone the repository
git clone https://github.com/patrickdeluca/mcp-brain-server.git
cd mcp-brain-server

# Install dependencies
npm install

# Configure environment 
cp .env.example .env
# Edit .env with your settings

# Build the project
npm run build

設定

.env ファイル内の環境変数を使用してサーバーを設定します。

# Server Configuration
PORT=3000

# MongoDB Configuration
MONGODB_URI=mongodb://localhost:27017/brain_db

# Model Configuration
EMBEDDING_MODEL=Xenova/all-MiniLM-L6-v2
MAX_CHUNK_SIZE=1024

使用方法

サーバーの起動

# Development mode
npm run dev

# Production mode
npm start

Claude Desktop での使用

claude_desktop_config.json ファイルに次の設定を追加して、Brain Server を Claude Desktop に登録します。

{
  "brain-server": {
    "command": "node",
    "args": ["path/to/mcp-brain-server/dist/index.js"],
    "env": {
      "MONGODB_URI": "mongodb://localhost:27017/brain_db"
    }
  }
}

MCP Inspector での使用

サーバーのデバッグやテストには、MCP Inspector を使用できます。

npx @modelcontextprotocol/inspector node dist/index.js

独自の Docker イメージをビルドする

独自の Docker イメージをビルドして実行する場合は、次の手順に従います。

# Build the Docker image
docker build -t mcp-brain-server .

# Run the container
docker run -p 3000:3000 -d --name brain-server mcp-brain-server

Docker イメージには Brain Server と MongoDB の両方が含まれており、単体でデプロイできます。

MCP リソース

サーバーは次の MCP リソースを公開します。

• embedding_config：現在の埋め込み設定
• embedding_models：利用可能な埋め込みモデルとその設定
• service_status：埋め込みサービスの現在の状態

MCP ツールの使用方法

サーバーは次の MCP ツールを公開します。

• addKnowledge：ベクトルデータベースに新しいナレッジを追加します
• searchSimilar：意味的に類似したコンテンツを検索します
• updateKnowledge：既存のナレッジ項目を更新します
• deleteKnowledge：ナレッジ項目を削除します
• batchAddKnowledge：複数のナレッジ項目を一括で追加します
• getEmbedding：テキストコンテンツの埋め込みを生成します

開発

プロジェクト構成

src/
├── config/          # Configuration settings
├── controllers/     # Route controllers
├── errors/          # Error definitions
├── middleware/      # Express middleware
├── models/          # Data models and types
├── services/        # Business logic
│   ├── embeddings/  # Embedding providers
│   ├── ingestion/   # Knowledge ingestion
│   ├── processing/  # Knowledge processing
│   └── storage/     # Storage services
├── tools/           # MCP tool definitions
├── types/           # TypeScript type definitions
├── utils/           # Utility functions
├── server.ts        # MCP server setup
└── index.ts         # Application entry point

ツールスキーマの例

addKnowledge ツールの使用例を示します。

{
  "content": "The Model Context Protocol (MCP) is a standardized interface for AI models to interact with external systems.",
  "metadata": {
    "brainId": "tech-knowledge",
    "userId": "user123",
    "source": "documentation",
    "type": "definition"
  }
}

searchSimilar ツールの例です。

{
  "query": "What is MCP?",
  "options": {
    "limit": 5,
    "minConfidence": 0.7,
    "filters": {
      "metadata.brainId": "tech-knowledge"
    }
  }
}

トラブルシューティング

Docker の問題

• コンテナのログを確認します：docker logs brain-server
• ポートが正しく割り当てられていることを確認します：docker ps
• コンテナ内で MongoDB が実行されていることを確認します：docker exec brain-server ps aux | grep mongod

MongoDB の接続に関する問題

• MongoDB が実行中であることを確認します：ps aux | grep mongod
• MongoDB のログを確認します：sudo cat /var/log/mongodb/mongod.log
• ファイアウォールで MongoDB への接続が許可されていることを確認します（デフォルトのポートは 27017 です）。
• .env 内の接続文字列を確認します：MONGODB_URI=mongodb://localhost:27017/brain_db

ベクトルインデックス機能の不足

ベクトルインデックス機能に関するエラーが発生した場合：

• ベクトル検索を最適にサポートする MongoDB 6.0 以降を使用していることを確認します。
• 古いバージョンの MongoDB では、サーバーは近似最近傍検索にフォールバックします。

利用可能なスクリプト

• npm run build：TypeScript プロジェクトをビルドします
• npm start：ビルド済みのアプリケーションを実行します
• npm run dev：ホットリロードを有効にして開発モードで実行します
• npm test：テストを実行します
• npm run lint：リンターを実行します

ライセンス

このプロジェクトは ISC License のもとでライセンスされています。詳細については LICENSE ファイルをご覧ください。

コントリビューション

コントリビューションを歓迎します！お気軽にプルリクエストを送信してください。