bryntum MCP

Bryntum MCP-RAG API文档

一个模块化的、符合SOLID标准的RAG（检索增强生成）系统，用于使用向量嵌入对Bryntum文档进行语义搜索。

建筑

该项目遵循SOLID原则，明确分离关注点：

src/
├── core/              # Interfaces (DIP - Dependency Inversion)
│   ├── VectorStore.js
│   ├── EmbeddingProvider.js
│   └── DocumentSource.js
│
├── adapters/          # Concrete implementations (LSP - Liskov Substitution)
│   ├── vectorstore/
│   │   └── LanceDBAdapter.js
│   ├── embeddings/
│   │   └── OpenAIAdapter.js
│   └── sources/
│       ├── FileSystemSource.js
│       └── ZipSource.js
│
├── services/          # Business logic (SRP - Single Responsibility)
│   ├── DocumentProcessor.js
│   ├── EmbeddingService.js
│   ├── IndexService.js
│   └── QueryService.js
│
├── api/               # HTTP API layer
│   ├── server.js
│   └── routes/
│       ├── index.js      # POST /index (upload zip)
│       ├── search.js     # POST /search
│       └── document.js   # GET /doc/:id
│
├── indexer/           # CLI tool
│   └── cli.js
│
└── utils/             # Shared utilities
    ├── config.js
    ├── logger.js
    └── chunker.js

特性

• 模块化架构：符合SOLID原则的清洁分离
• 矢量搜索：使用LanceDB和OpenAI嵌入的语义搜索
• 多重来源：支持文件系统和zip上传
• 智能分块：支持Markdown的分块，以获得更好的上下文
• RESTful API：用于索引和搜索的简单HTTP接口
• CLI工具：用于批处理的命令行索引器

先决条件

• Node.js v20+
• OpenAI API密钥

安装

1. 安装依赖项：

npm install

1. 创建 .env 文件：

cp .env.example .env

1. 编辑 .env 并添加您的OpenAI API密钥：

OPENAI_API_KEY=your_openai_api_key_here

用法

选项1:CLI索引器

从目录中索引文档：

npm run index -- --source ./temp/docs-llm

zip文件索引：

npm run index -- --zip ./docs-llm.zip

选项2:REST API

启动API服务器：

npm start

服务器将在以下时间启动 http://localhost:3000

上传并索引一个zip文件：

curl -X POST http://localhost:3000/index \
  -F "file=@docs-llm.zip"

搜索文档：

curl -X POST http://localhost:3000/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How do I create a chart?",
    "limit": 5,
    "includeContext": true
  }'

获取特定文档：

curl http://localhost:3000/doc/{document-id}

API终点

POST/索引

上传并索引一个包含markdown文档的zip文件。

请求：

• 内容类型：多部分/表单数据
• 正文：文件（zip文件）

答复：

{
  "success": true,
  "uploadId": "abc123",
  "filename": "docs.zip",
  "documentsProcessed": 426,
  "chunksIndexed": 1234,
  "durationMs": 45000
}

POST/搜索

使用语义相似性搜索文档。

请求：

{
  "query": "How to configure a chart?",
  "limit": 5,
  "filter": {},
  "includeContext": false
}

答复：

{
  "query": "How to configure a chart?",
  "resultCount": 5,
  "durationMs": 250,
  "results": [
    {
      "id": "abc123",
      "text": "...",
      "score": 0.15,
      "relevance": "0.850",
      "metadata": {
        "documentPath": "api/Chart/widget/Chart.md",
        "heading": "Configuring data",
        "chunkIndex": 0
      }
    }
  ]
}

GET/doc/：id

按ID获取特定文档。

答复：

{
  "id": "abc123",
  "text": "...",
  "metadata": {
    "documentPath": "api/Chart/widget/Chart.md",
    "heading": "Configuring data"
  }
}

配置

配置是通过环境变量进行管理的 .env:

# OpenAI Configuration
OPENAI_API_KEY=your_key_here
OPENAI_EMBEDDING_MODEL=text-embedding-3-small

# Server Configuration
PORT=3000
HOST=0.0.0.0

# Storage Configuration
VECTOR_DB_PATH=./data/lancedb
TEMP_UPLOAD_PATH=./temp

# Chunking Configuration
CHUNK_SIZE=1000
CHUNK_OVERLAP=200

# Logging
LOG_LEVEL=info

SOLID原则实施

单一责任原则（SRP）

每个类都有一个职责：

• DocumentProcessor -仅对文档进行块化处理
• EmbeddingService -仅生成嵌入
• QueryService -仅处理查询

开放/封闭原则（OCP）

可以通过扩展来添加新的文档源 DocumentSource 而无需修改现有代码。

利斯科夫替代原理（LSP）

所有适配器都可以与其基本接口交换，而不会破坏功能。

接口隔离原则（ISP）

接口集中且最小化（VectorStore、EmbeddedProvider、DocumentSource）。

依赖倒置原理（DIP）

服务依赖于抽象（接口），而不是具体的实现。

后续步骤

要添加MCP（模型上下文协议）支持，您可以：

1. 创建 src/mcp/ 目录
2. 使用实现MCP服务器 @modelcontextprotocol/sdk
3. 将搜索和文档检索作为MCP工具公开
4. 在Claude Desktop注册

发展

在开发模式下运行并自动重新加载：

npm run dev

许可证

国际协调委员会