使用说明
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_API_KEY |
- | OpenAI API密钥（必需） |
DB_PATH |
./data/vectors.db |
SQLite数据库路径 |
PORT |
3000 |
HTTP服务器端口 |
LOG_LEVEL |
info |
日志记录级别 |
CHUNK_SIZE |
700 |
文本块大小 |
CHUNK_OVERLAP |
100 |
文本块重叠 |
DEFAULT_TOP_K |
10 |
默认搜索结果计数 |
EMBEDDING_MODEL |
text-embedding-3-small |
OpenAI嵌入模型 |
EMBEDDING_DIMENSIONS |
1536 |
嵌入向量维度 |
EMBEDDING_BATCH_SIZE |
100 |
每个嵌入批次的最大文本数 |
EMBEDDING_PROVIDER |
openai |
嵌入提供程序（仅限openai） |
EMBEDDING_ENCODING_FORMAT |
float |
编码格式（浮点/base64） |
嵌入模型
支持的OpenAI模型及其维度范围：
| 型号 | 最小尺寸 | 最大尺寸 | 默认 |
|---|---|---|---|
text-embedding-3-small |
512 | 1536 | 1536 |
text-embedding-3-large |
256 | 3072 | 3072 |
text-embedding-ada-002 |
1536 | 1536 | 1536 |
批量加载
该服务器包括一个批加载实用程序，用于有效地从各种文件格式导入多个文档。
快速开始
# 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
数据库模式
系统使用两个表：
- 块 （sqlite-vec虚拟表）：存储带有ULID键的嵌入
- 组块元数据：存储文本内容、元数据和关系
演出
- 目标：M1 Mac上10k块的P95<300ms
- sqlite-vec使用暴力KNN（对于大于1M的块考虑ANN）
- 启用并发读取的WAL模式
- 嵌入批处理（最多100条文本/请求）
样品数据
看 示例_QUERIES.md 用于：
- 跨不同类别的测试文档示例
- 具有预期结果的示例搜索查询
- 跨域搜索示例
- 测试指南
测试文件可在 samples/test-documents.json 20份样本文件涵盖：
- 技术（云、人工智能）
- 烹饪（日语、意大利语）
- 健康与体育
- 商业与教育
- 旅游与环境
- 艺术与科学
文档
许可证
麻省理工学院