sqlite v MCP server

MCP矢量服务器（sqlite-vec）

一种模型上下文协议（MCP）服务器，使用SQLite和SQLite-vec扩展提供向量相似性搜索功能。专为使用OpenAI嵌入存储日语文档而设计。

特性

• 矢量搜索：使用sqlite-vec进行高效的余弦相似性搜索
• 文本组块：针对日语内容优化的智能文本分割（700个字符+100个重叠）
• OpenAI嵌入：尺寸可调的可配置型号（3-small、3-large、ada-002）
• 批量加载：从JSON、CSV或文本文件导入多个文档
• 双模式：HTTP服务器（JSON-RPC 2.0）和用于直接MCP通信的stdio模式
• TypeScript：全型安全，严格模式

先决条件

• Node.js 20 LTS
• OpenAI API密钥
• macOS或Linux（由于sqlite-vec限制，不支持Windows）

安装

# Install dependencies
npm install

# Copy environment configuration
cp .env.example .env

# Edit .env and set your OpenAI API key
# OPENAI_API_KEY=sk-your-openai-api-key-here

# Run database migrations
npm run migrate

# Build the project
npm run build

用法

HTTP模式（JSON-RPC 2.0）

# Start HTTP server (default port 3000)
npm start -- --http

# Start with custom port
npm start -- --http --port 8080

stdio模式（MCP协议）

# Start in stdio mode
npm start -- --stdio

开发模式

# Development server with hot reload
npm run dev

API端点（HTTP模式）

GET/工具

返回MCP工具清单。

POST/rpc

用于工具执行的JSON-RPC 2.0主端点。

GET/健康

健康检查端点。

MCP工具

insert_document

插入具有自动分块和嵌入生成功能的文档。

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "insert_document",
    "arguments": {
      "text": "Your document text here...",
      "metadata": { "title": "Document Title", "author": "Author Name" }
    }
  }
}

答复：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "doc_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "chunk_count": 5
  }
}

查找_类似_文档

使用向量相似度搜索相似文档。

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "find_similar_documents",
    "arguments": {
      "text": "Search query text",
      "top_k": 10
    }
  }
}

答复：

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "results": [
      {
        "chunk_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
        "doc_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
        "text": "Matching text chunk...",
        "score": 0.95
      }
    ]
  }
}

删除文档

删除文档及其所有块。

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "delete_document",
    "arguments": {
      "doc_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV"
    }
  }
}

答复：

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "deleted_chunks": 5
  }
}

配置

环境变量：

嵌入模型

支持的OpenAI模型及其维度范围：

批量加载

该服务器包括一个批加载实用程序，用于有效地从各种文件格式导入多个文档。

快速开始

# Load documents from JSON
npm run batch-load samples/test-documents.json

# Preview without inserting (dry run)
npm run batch-load samples/documents.csv --dry-run

# Load with custom batch size
npm run batch-load data.json --batch-size 5

支持格式

• 对象符号：包含文本/元数据的字符串或对象数组
• CSV文件：必须有一个“text”列，其他列将成为元数据
• 文本：带有双换行符分隔或元数据标题的纯文本
• 自定义格式：参见 docs/batch-reading.md 详见

示例

# Load the provided test documents
npm run batch-load samples/test-documents.json

# Run the interactive example
node examples/batch-load-example.js

有关批量加载的详细文档，请参阅 docs/batch-reading.md.

发展

# Run tests
npm test

# Lint code
npm run lint

# Format code
npm run format

# Build
npm run build

# Development server
npm run dev

数据库模式

系统使用两个表：

1. 块 （sqlite-vec虚拟表）：存储带有ULID键的嵌入
2. 组块元数据：存储文本内容、元数据和关系

演出

• 目标：M1 Mac上10k块的P95\<300ms
• sqlite-vec使用暴力KNN（对于大于1M的块考虑ANN）
• 启用并发读取的WAL模式
• 嵌入批处理（最多100条文本/请求）

样品数据

看 示例_QUERIES.md 用于：

• 跨不同类别的测试文档示例
• 具有预期结果的示例搜索查询
• 跨域搜索示例
• 测试指南

测试文件可在 samples/test-documents.json 20份样本文件涵盖：

• 技术（云、人工智能）
• 烹饪（日语、意大利语）
• 健康与体育
• 商业与教育
• 旅游与环境
• 艺术与科学

文档

• 日语文档
• 批量加载指南 | 日本语
• 嵌入配置指南 | 日本语

许可证

麻省理工学院