矢量索引器MCP-实时矢量索引系统
状态：第4阶段完成✓ 版本: 0.4.0
用于代码库和文档的自动实时矢量索引系统。监控配置的目录，生成语义嵌入，并通过MCP服务器启用矢量搜索。
建筑
该系统由三个协同工作的组件组成：
守护者守护进程（第3阶段）- daemon/watcher.py
- 使用inotify（监视器库）监视配置的目录
- 检测文件更改：创建、修改、删除、移动
- 快速变化（100ms窗口）
- 按扩展名过滤并排除模式
- 批量将事件插入
index_queue
工人守护进程（第2阶段）- daemon/worker.py
- 民意调查
index_queue对于未决事件 - 通过索引管道处理文件：
1. 文本块 -令牌感知分块（tiktoken） 1. 嵌入式生成器 -384个暗向量（句子变换器） 1. 数据库存储 -Supabase中的块+嵌入
- 基于SHA256哈希的更改检测（跳过未更改的文件）
- 队列状态跟踪错误处理
MCP服务器（第4阶段）- src/server.py
- 通过模型上下文协议向Claude公开7个工具
- 搜索工具：语义、词汇、混合搜索
- 管理工具：index_status、reindex_path、get_file_chunks、search_similar_files
- 延迟加载嵌入模型（仅限第一个查询）
- 所有工具的响应信封格式
管道流量
File System → Watcher → Queue → Worker → Vector Database → MCP Server → Claude
(inotify) (debounce) (async) (chunk) (embeddings) (search) (query)数据库模式
工作人员需要这些表（在阶段1中创建）：
file_metadata-文件信息和索引状态file_chunks-带有行/标记元数据的文本块file_embeddings-384个带pgvector的dim向量index_queue-文件更改事件队列index_stats-索引统计
安装
cd /srv/latvian_mcp/servers/vector-indexer-mcp
# Install dependencies
pip install -r requirements.txt
# Or install as package
pip install -e .配置
复制 .env.example 到 .env 并配置：
# Supabase
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your_service_role_key
# Embedding model
EMBEDDING_MODEL=paraphrase-multilingual-MiniLM-L12-v2
# Chunking
MAX_TOKENS=500
OVERLAP_TOKENS=50
# Worker
WORKER_BATCH_SIZE=10
WORKER_POLL_INTERVAL=5运行系统
需要两种服务
对于实时索引，请将这两个守护进程作为用户服务运行：
# Start watcher (monitors file changes)
systemctl --user start vector-indexer
systemctl --user enable vector-indexer
# Start worker (processes queue)
systemctl --user start vector-indexer-worker
systemctl --user enable vector-indexer-worker
# Enable lingering for persistence after logout
loginctl enable-linger $USER
# Check status
systemctl --user status vector-indexer vector-indexer-worker
# Monitor logs
journalctl --user -u vector-indexer -u vector-indexer-worker -f备注：服务以用户模式（而非系统模式）运行，以提高安全性和隔离性。这 loginctl enable-linger 命令确保服务在注销后仍然存在。
发展模式
无需systemd即可直接运行：
# Terminal 1: Watcher
python -m daemon.watcher
# Terminal 2: Worker
python -m daemon.worker使用示例
自动索引
在两个服务都运行的情况下，文件更改会自动编入索引：
# Create a file in watched directory
echo "# Test Document" > /srv/latvian_mcp/test.md
echo "This is a test." >> /srv/latvian_mcp/test.md
# Watcher detects change → adds to queue → worker processes手动插入队列
您还可以手动触发索引：
-- Add file to index queue
INSERT INTO index_queue (file_path, event, priority)
VALUES ('/path/to/file.txt', 'create', 1);
-- Worker automatically processes:
-- 1. Read file content
-- 2. Calculate SHA256 hash
-- 3. Generate chunks (respecting token limits)
-- 4. Generate embeddings (384-dim vectors)
-- 5. Store in file_chunks and file_embeddings tables
-- 6. Update index_stats系统化服务
矢量索引器可以作为systemd服务运行，用于自动启动和进程管理。
安装
- 复制服务文件：
sudo cp mcp-sse-vector-indexer-mcp.service /etc/systemd/system/
sudo systemctl daemon-reload- 启用并启动服务：
sudo systemctl enable mcp-sse-vector-indexer-mcp
sudo systemctl start mcp-sse-vector-indexer-mcp- 检查状态：
sudo systemctl status mcp-sse-vector-indexer-mcp特性
- 港口冲突预防：启动前检查端口5568是否已在使用中
- 自动重新启动：10秒后出现故障时重新启动
- 安全关机：优雅终止超时30秒
- 日志记录：查看日志
journalctl -u mcp-sse-vector-indexer-mcp -f
管理
# Stop service
sudo systemctl stop mcp-sse-vector-indexer-mcp
# Restart service
sudo systemctl restart mcp-sse-vector-indexer-mcp
# Disable auto-start
sudo systemctl disable mcp-sse-vector-indexer-mcp事件类型
| 事件 | 描述 | 操作 |
|---|---|---|
create | 添加新文件 | 生成块+嵌入 |
modify | 文件内容已更改 | 如果哈希值不同，则重新生成 |
delete | 文件已删除 | 删除块+嵌入 |
move | 文件路径已更改 | 更新元数据中的File_path |
演出
- 组块：约10000行/秒
- 嵌入：~50块/秒（批处理模式）
- 代币计数：使用tiktoken（与GPT模型相同）
- 记忆：~2GB用于嵌入模型
监控
检查工人状态：
-- Queue status
SELECT status, COUNT(*)
FROM index_queue
GROUP BY status;
-- Index stats
SELECT * FROM index_stats;
-- Recent errors
SELECT file_path, error_message, processed_at
FROM index_queue
WHERE status = 'failed'
ORDER BY processed_at DESC
LIMIT 10;错误处理
worker使用队列状态进行错误跟踪：
pending-等待处理processing-目前正在处理中completed-已成功处理failed-处理失败（请参阅error_message）
失败的项目仍在队列中等待手动检查/重试。
发展
运行测试：
pytest tests/代码格式：
black daemon/
ruff daemon/类型检查：
mypy daemon/配置（监视器）
编辑 config/watcher.yaml 自定义：
watcher:
watch_paths:
- /srv/latvian_mcp
- /srv/latvian_xtts
- /srv/latvian_learning
- /srv/claude-mpm
exclude_patterns:
- __pycache__
- .git
- venv
- "*.log"
include_extensions:
- .py
- .md
- .txt
- .json
- .yaml
max_file_size_mb: 10
debounce_ms: 100
batch_size: 50测试
# Test watcher components
python test_watcher_core.py
# Test worker pipeline
python test_pipeline.py
# Test MCP server
python test_mcp_server.pyMCP服务器使用情况（第4阶段）
可用工具
- 搜索_语义 -概念的向量相似性搜索
- search_lexical -全文搜索精确关键字
- search_hybrid -语义+词汇相结合（两者兼而有之）
- 索引状态 -获取索引运行状况统计数据
- reindex_path -强制重新索引文件或目录
- get_file_chunks -查看文件是如何分块的
- 搜索_类似文件 -查找与参考文件类似的文件
快速开始
# Run MCP server standalone
cd /srv/latvian_mcp/servers/vector-indexer-mcp
source venv/bin/activate
python -m src注册Claude
添加 ~/.config/claude/mcp_servers.json:
{
"vector-indexer": {
"command": "/srv/latvian_mcp/servers/vector-indexer-mcp/venv/bin/python",
"args": ["-m", "src"],
"env": {
"SUPABASE_URL": "https://zbhddlduxcwhgibhbeuu.supabase.co",
"SUPABASE_SERVICE_KEY": "your_service_key_here"
}
}
}文档
- 阶段4_MCP_SERVER.md -第4阶段MCP服务器（新）
- 第3阶段_夏季.md -第3阶段文件监视器
- 阶段3_WATCHER.md -详细的观察者文档
- 实施\_ SUMMARY.md -第二阶段索引工作者
- 安装.md -安装指南
许可证
麻省理工学院