Vector Indexer MCP

矢量索引器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服务运行，用于自动启动和进程管理。

安装

1. 复制服务文件：

sudo cp mcp-sse-vector-indexer-mcp.service /etc/systemd/system/
sudo systemctl daemon-reload

1. 启用并启动服务：

sudo systemctl enable mcp-sse-vector-indexer-mcp
sudo systemctl start mcp-sse-vector-indexer-mcp

1. 检查状态：

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

事件类型

演出

• 组块：约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.py

MCP服务器使用情况（第4阶段）

可用工具

1. 搜索_语义 -概念的向量相似性搜索
2. search_lexical -全文搜索精确关键字
3. search_hybrid -语义+词汇相结合（两者兼而有之）
4. 索引状态 -获取索引运行状况统计数据
5. reindex_path -强制重新索引文件或目录
6. get_file_chunks -查看文件是如何分块的
7. 搜索_类似文件 -查找与参考文件类似的文件

快速开始

# 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 -安装指南

许可证

麻省理工学院