Brain Server - MCP 知识嵌入服务

一个强大的 MCP (模型上下文协议) 服务器，用于管理知识嵌入和向量搜索。

特性

• 向量嵌入: 为知识内容生成高质量的嵌入
• 语义搜索: 基于含义查找知识，而不仅仅是关键词
• MCP 兼容: 遵循模型上下文协议以进行 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：

# 克隆仓库
git clone https://github.com/patrickdeluca/mcp-brain-server.git
cd mcp-brain-server

# 使用 Docker Compose 启动服务器
docker-compose up -d

# 查看日志
docker-compose logs -f

服务器将在 http://localhost:3000 上可用，MongoDB 在同一容器内运行。

将 Docker 与 Claude Desktop 结合使用

要将 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

# 导入公钥
wget -qO - https://www.mongodb.org/static/pgp/server-6.0.asc | sudo tee /etc/apt/trusted.gpg.d/mongodb-6.0.asc
# 添加 MongoDB 仓库
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
# 更新软件包数据库并安装 MongoDB
sudo apt-get update
sudo apt-get install -y mongodb-org
# 启动 MongoDB 服务
sudo systemctl start mongod

macOS

# 使用 Homebrew
brew tap mongodb/brew
brew install mongodb-community@6.0
brew services start mongodb-community@6.0

Windows

1. 从 MongoDB 下载中心 下载 MongoDB 6.0 安装程序
2. 运行安装程序并按照设置向导进行操作
3. 从 Windows 服务控制台启动 MongoDB

验证 MongoDB 安装

要验证 MongoDB 是否正常运行：

mongosh --eval "db.version()"

手动安装

# 克隆仓库
git clone https://github.com/patrickdeluca/mcp-brain-server.git
cd mcp-brain-server

# 安装依赖
npm install

# 配置环境
cp .env.example .env
# 使用您的设置编辑 .env

# 构建项目
npm run build

配置

使用 .env 文件中的环境变量配置服务器：

# 服务器配置
PORT=3000

# MongoDB 配置
MONGODB_URI=mongodb://localhost:27017/brain_db

# 模型配置
EMBEDDING_MODEL=Xenova/all-MiniLM-L6-v2
MAX_CHUNK_SIZE=1024

用法

启动服务器

# 开发模式
npm run dev

# 生产模式
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 镜像：

# 构建 Docker 镜像
docker build -t mcp-brain-server .

# 运行容器
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/          # 配置设置
├── controllers/     # 路由控制器
├── errors/          # 错误定义
├── middleware/      # Express 中间件
├── models/          # 数据模型和类型
├── services/        # 业务逻辑
│   ├── embeddings/  # 嵌入提供程序
│   ├── ingestion/   # 知识摄取
│   ├── processing/  # 知识处理
│   └── storage/     # 存储服务
├── tools/           # MCP 工具定义
├── types/          # TypeScript 类型定义
├── utils/           # 实用函数
├── server.ts        # MCP 服务器设置
└── index.ts         # 应用程序入口点

工具模式示例

以下是使用 addKnowledge 工具的示例：

{
  "content": "模型上下文协议 (MCP) 是 AI 模型与外部系统交互的标准化接口。",
  "metadata": {
    "brainId": "tech-knowledge",
    "userId": "user123",
    "source": "documentation",
    "type": "definition"
  }
}

以及 searchSimilar 工具：

{
  "query": "什么是 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: 运行 linter

许可证

该项目已获得 ISC 许可证的许可 - 有关详细信息，请参阅 LICENSE 文件。

贡献

欢迎贡献！ 请随时提交 Pull Request。