# 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:

```bash
# 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`:

```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
```bash
# 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
```bash
# Using Homebrew
brew tap mongodb/brew
brew install mongodb-community@6.0
brew services start mongodb-community@6.0
```

##### Windows
1. Download the MongoDB 6.0 installer from the [MongoDB Download Center](https://www.mongodb.com/try/download/community)
2. Run the installer and follow the setup wizard
3. Start MongoDB from the Windows Services console

### Verify MongoDB Installation

To verify that MongoDB is running properly:
```bash
mongosh --eval "db.version()"
```

## Manual Installation

```bash
# 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

```bash
# 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:

```json
{
  "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:

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

## Building Your Own Docker Image

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

```bash
# 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:

```json
{
  "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:

```json
{
  "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.