Brain Server - MCP Knowledge Embedding Service by ruca-radio - MCP Server

Brain Server - MCP Knowledge Embedding Service

A powerful MCP (Model Context Protocol) server for managing knowledge embeddings and vector search.

Features

Vector Embeddings: Generate high-quality embeddings for knowledge content
Semantic Search: Find knowledge based on meaning, not just keywords
MCP Compliance: Follows Model Context Protocol for AI integration
Brain Management: Organize knowledge into domain-specific brains
Context-Aware Retrieval: Includes surrounding context for better understanding
Progress Tracking: Real-time monitoring of long-running operations

Embedding Models

The server uses embedding models to convert text into vector representations:

On first run, the server will automatically download the embedding models
By default, it uses Xenova/all-MiniLM-L6-v2 from HuggingFace
Models are cached locally after first download
For testing, a MockEmbeddingProvider is available that generates random vectors

You can configure which model to use in the .env file:

EMBEDDING_MODEL=Xenova/all-MiniLM-L6-v2

Supported models include:

Xenova/all-MiniLM-L6-v2 (default, 384 dimensions)
Xenova/bge-small-en-v1.5 (384 dimensions)
Xenova/bge-base-en-v1.5 (768 dimensions)
Xenova/e5-small-v2 (384 dimensions)

Quick Start with Docker

The easiest way to run Brain Server is using Docker and 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

The server will be available at http://localhost:3000 with MongoDB running inside the same container.

Using Docker with Claude Desktop

To use the dockerized Brain Server with Claude Desktop, update your claude_desktop_config.json:

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

Prerequisites for Local Installation

MongoDB Installation

If you're not using Docker, the Brain Server requires MongoDB (version 6.0 or later recommended for vector search):

Modern Installation (Recommended)

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 mongodb-community@6.0
brew services start mongodb-community@6.0

Windows

Download the MongoDB 6.0 installer from the MongoDB Download Center
Run the installer and follow the setup wizard
Start MongoDB from the Windows Services console

Verify MongoDB Installation

To verify that MongoDB is running properly:

mongosh --eval "db.version()"

Manual Installation

# 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

Configuration

Configure the server using environment variables in the .env file:

# 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

Usage

Starting the Server

# Development mode
npm run dev

# Production mode
npm start

Using with Claude Desktop

Add the brain server to your Claude Desktop configuration by adding this to your claude_desktop_config.json file:

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

Using with MCP Inspector

To debug or test the server, you can use the MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

Building Your Own Docker Image

If you want to build and run your own Docker image:

# 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

The Docker image includes both the Brain Server and MongoDB for a self-contained deployment.

MCP Resources

The server exposes the following MCP resources:

embedding_config: Current embedding configuration
embedding_models: Available embedding models and their configurations
service_status: Current status of the embedding service

MCP Tool Usage

The server exposes the following MCP tools:

addKnowledge: Add new knowledge to the vector database
searchSimilar: Find semantically similar content
updateKnowledge: Update existing knowledge entries
deleteKnowledge: Remove knowledge entries
batchAddKnowledge: Add multiple knowledge entries in a batch
getEmbedding: Generate embeddings for text content

Development

Project Structure

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

Tool Schema Examples

Here's an example of using the addKnowledge tool:

{
  "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"
  }
}

And the searchSimilar tool:

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

Troubleshooting

Docker Issues

Check container logs: docker logs brain-server
Ensure ports are correctly mapped: docker ps
Verify MongoDB is running in the container: docker exec brain-server ps aux | grep mongod

MongoDB Connection Issues

Verify MongoDB is running: ps aux | grep mongod
Check MongoDB logs: sudo cat /var/log/mongodb/mongod.log
Ensure your firewall allows connections to MongoDB (default port 27017)
Verify your connection string in .env: MONGODB_URI=mongodb://localhost:27017/brain_db

Missing Vector Index Capabilities

If you encounter errors related to vector index capabilities:

Ensure you're using MongoDB 6.0+ for optimal vector search support
For older MongoDB versions, the server will fall back to approximate nearest neighbors search

Available Scripts

npm run build: Build the TypeScript project
npm start: Run the built application
npm run dev: Run in development mode with hot reloading
npm test: Run tests
npm run lint: Run linter

License

This project is licensed under the ISC License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

ruca-radio/mcp-brain-server