Brain Server - MCP Knowledge Embedding Service

Brain Server - MCP 知识嵌入服务

一款功能强大的 MCP（Model Context Protocol）服务，用于管理知识嵌入和向量搜索。

功能

• 向量嵌入：为知识内容生成高质量的嵌入
• 语义搜索：根据含义而非仅根据关键词查找知识
• 符合 MCP 规范：遵循 Model Context Protocol，便于与 AI 集成
• 知识库管理：将知识整理到特定领域的知识库中
• 感知上下文的检索：包含周边上下文，以便更好地理解
• 进度跟踪：实时监控长时间运行的操作

嵌入模型

该服务使用嵌入模型将文本转换为向量表示：

• 首次运行时，服务会自动下载嵌入模型
• 默认使用来自 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

要在 Claude Desktop 中使用 Docker 化的 Brain Server，请更新你的 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 文件，即可在 Claude Desktop 配置中添加 Brain Server：

{
  "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 文件。

贡献

欢迎贡献！欢迎提交 Pull Request。