使用说明

MCP 知识探索器

🎉 状态：第4B阶段M2已完成 - 关键词搜索功能就绪！ 第四阶段B的里程碑2（关键词搜索路径）已100%完成，具备可投入生产的全文搜索功能。完整的TEXT_EXTRACT（文本提取）→ CHUNK（分块）→ FTS_INDEX（全文搜索索引）流水线、采用三元组分词器的FTS5搜索、PermissionPostprocessor安全层以及search_fulltext MCP工具（第8个工具）均已投入运行，并通过了49项以上的全面测试。现已准备好实施M3语义搜索。

快速入门

# Start the entire system with one command
# This will now start FOUR services: backend, frontend, indexer, and Qdrant
docker-compose up --build

# Access the services
# Frontend UI: http://localhost:5173
# Backend API: http://localhost:8000
# MCP HTTP: http://localhost:8000/mcp (for AI clients)
# Qdrant API: http://localhost:6333 (vector database)

# View logs for a specific service
docker-compose logs -f backend
docker-compose logs -f frontend
docker-compose logs -f indexer
docker-compose logs -f qdrant

测试

MCP智慧综合测试套件

使用全面的测试程序验证所有MCP功能：

# Quick test (validates current environment)
./scripts/test-mcp-wisdom.sh

# Full comprehensive test suite
./scripts/test-mcp-wisdom.sh --comprehensive

# Create isolated test environment
./scripts/test-mcp-wisdom.sh --isolated

# View previous test results
./scripts/test-mcp-wisdom.sh --report-only

特点：

✅ 自适应预验证（检查工作区和权限）
✅ 测试所有8种MCP工具，启用权限强制执行
✅ 安全测试（目录遍历、未经授权访问）
✅ 性能验证（响应时间低于25毫秒）
✅ 提供带有详细指标的JSON报告

4B阶段测试套件

验证新的4B阶段基础：

# Run Phase 4B database schema tests
cd backend && python -m pytest tests/phase4b/test_database_schema.py -v

# Run Phase 4B Qdrant integration tests
cd backend && python -m pytest tests/phase4b/test_qdrant_integration.py -v

# Run all Phase 4B tests
cd backend && python -m pytest tests/phase4b/ -v

测试覆盖率：

✅ 11个数据库模式测试（DocumentChunk、FTS5、触发器）
✅ 8个Qdrant集成测试（连接、集合、向量）
✅ 临时数据库隔离，确保测试可靠性
✅ 当依赖项不可用时优雅地跳过

强制重新索引操作

“Force Reindex”功能为管理员提供了一个强大的工具，用于从头开始重建内容索引或刷新索引标志。该功能可通过Web用户界面（UI）和命令行界面（CLI）访问，以提供最大的灵活性。

网页用户界面访问

导航至 索引器 在网页界面（http://localhost:5173）中点击选项卡，并使用 强制重新索引 下拉按钮：

**软重新索引（推荐）**非破坏性重新索引，保留现有数据
硬重置彻底重建，清除所有现有数据

CLI 操作

通过编程方式触发和管理数据库的重新索引操作：

# Trigger soft reindex (keeps existing data, recommended)
python scripts/trigger_reindex.py trigger --mode soft

# Trigger hard reset (purges and rebuilds data)
python scripts/trigger_reindex.py trigger --mode hard

# Filter by path for targeted reindexing
python scripts/trigger_reindex.py trigger --mode soft --path /projects

# Include all file types (not just text files)
python scripts/trigger_reindex.py trigger --mode soft --no-text-only

# Dry run to see what would be reindexed
python scripts/trigger_reindex.py trigger --mode soft --dry-run

# Check batch status with real-time monitoring
python scripts/trigger_reindex.py status <batch_id>
python scripts/trigger_reindex.py status <batch_id> --watch

# List all batches
python scripts/trigger_reindex.py list --all

# Control batch execution
python scripts/trigger_reindex.py pause <batch_id>
python scripts/trigger_reindex.py resume <batch_id>
python scripts/trigger_reindex.py cancel <batch_id>

# System management
python scripts/trigger_reindex.py system
python scripts/trigger_reindex.py clear-maintenance

更新 - 2025年09月30日： 现在，硬重置操作会修剪共享文件系统上已不存在的文件的数据库记录，重建Phase 4B全文搜索（FTS）表，然后将新的TEXT_EXTRACT作业加入队列。这样可以防止陈旧作业重新出现并处理已删除的路径。

提示： 在进行大规模硬重置后，如果索引器仪表板仍显示正在处理作业，而实际上队列为空，请重启索引器容器或发送POST /control/resume请求以刷新状态信息。

API集成

强制重新索引操作可以通过REST API集成到自动化工作流中：

# Create new reindex batch
curl -X POST http://localhost:8000/admin/reindex/force \
  -H "X-Admin-Key: admin-secret-key-change-me" \
  -H "Content-Type: application/json" \
  -d '{"mode": "soft", "scope": {"path_prefix": "/projects", "text_only": true}}'

# Monitor batch progress
curl -H "X-Admin-Key: admin-secret-key-change-me" \
  http://localhost:8000/admin/reindex/batches/{batch_id}

# Control batch execution
curl -X POST http://localhost:8000/admin/reindex/batches/{batch_id}/pause \
  -H "X-Admin-Key: admin-secret-key-change-me"

特点：

✅ 双模式软重索引（非破坏性）和硬重置（完全重建）
✅ 分块处理为了内存效率，每块处理5000个文件
✅ 路径过滤指定特定目录以重新索引
✅ 翻译为中文是：“✅”（这个符号本身在中文中通常表示“正确”或“已完成”，没有直接的翻译文字，所以保持原样或根据上下文解释为“正确”、“确认”等意思）。如果要给出一个类似的中文表达，可以是“正确”或“确认”。 维护模式在操作过程中防止竞态条件
✅ 翻译成中文是“正确”或“对”。 批次管理完全控制，具备暂停/恢复/取消功能
✅ 进度跟踪实时进度及预计到达时间计算
✅ 管理员安全由管理员API密钥认证保护
✅ 模拟运行支持预览操作而不进行更改
✅ 错误恢复支持回滚的事务性操作

性能特性：

软重索引：每1000个文件约需2-5秒
硬重置：每1000个文件约需10-30秒（取决于数据块数量）
内存使用情况：处理过程中额外增加的内存<100MB
批量状态查询的响应时间在一秒之内

MCP与AI客户端的集成

Claude Desktop（推荐）

Claude Desktop 拥有成熟的 MCP 支持，并且可以直接与本地主机连接工作：

# Add MCP server (HTTP transport recommended)
claude mcp add --transport http wisdom http://localhost:8000/mcp

# Test connection
curl -X POST http://localhost:8000/mcp -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

可用形式：

mcp__wisdom__read_file - 读取文件内容并进行权限检查
mcp__wisdom__list_files - 列出目录内容及其元数据
mcp__wisdom__write_file - 写入文件内容（受权限限制）
mcp__wisdom__list_all_files - 列出工作区中所有已索引的文件
mcp__wisdom__search_files_by_metadata - 按照元数据标准搜索文件
mcp__wisdom__get_file_info - 获取文件的详细信息和元数据
mcp__wisdom__get_search_statistics - 获取索引和搜索统计信息
mcp__wisdom__search_fulltext - 使用FTS5进行全文搜索并过滤

ChatGPT 桌面版

ChatGPT Desktop 预期 可流式传输的HTTP传输 (MCP 2025-03-26 规范) 并且可能具有本地主机访问限制。我们的服务器使用基本的HTTP JSON-RPC传输方式，因此我们需要一个兼容层。

解决方案：代理+隧道方法

步骤1：安装依赖项

pip install aiohttp

步骤2：启动代理服务器

# Start the compatibility proxy (bridges ChatGPT ↔ MCP server)
python chatgpt_proxy.py

这会在9000端口启动一个代理，将请求转发到8000端口上的MCP服务器。

步骤3：创建公共隧道

ChatGPT Desktop 可能无法直接访问本地主机。请创建一个公共隧道：

# Option A: Specific subdomain (preferred, if available)
npx localtunnel --port 8000 --subdomain wisdom-direct
npx localtunnel --port 9000 --subdomain wisdom-proxy

# Option B: Random subdomain (fallback if specific fails)
npx localtunnel --port 8000  # Gets random URL like https://abc-def.loca.lt
npx localtunnel --port 9000  # Gets random URL like https://xyz-123.loca.lt

步骤4：配置ChatGPT桌面版

在ChatGPT桌面版的连接器设置中，使用以下其中一个URL：

# Direct connection (bypasses proxy)
https://[your-subdomain].loca.lt/mcp

# Through proxy (for debugging/logging)
https://[proxy-subdomain].loca.lt/mcp

流程管理

ChatGPT的集成需要 3个正在运行的进程：

Docker Compose （您的主MCP服务器）- 端口8000
代理服务器 (python chatgpt_proxy.py) - 端口9000
隧道工艺/隧道处理过程 (npx localtunnel --port XXXX) - 创建公共URL

索引器与全文搜索（FTS）故障排除指南

FTS5 报告 invalid file format (found 0, expected 4 or 5) - 删除并重新创建 chunks_fts 虚拟表，然后重建索引：

python - <<'PY'
import sqlite3
conn = sqlite3.connect('data/database.db')
cur = conn.cursor()
cur.executescript("""
  DROP TRIGGER IF EXISTS chunks_fts_insert;
  DROP TRIGGER IF EXISTS chunks_fts_update;
  DROP TRIGGER IF EXISTS chunks_fts_delete;
  DROP TABLE IF EXISTS chunks_fts;
  CREATE VIRTUAL TABLE chunks_fts USING fts5(
      text,
      content='document_chunks',
      content_rowid='id',
      tokenize='trigram'
  );
  CREATE TRIGGER chunks_fts_insert AFTER INSERT ON document_chunks BEGIN
      INSERT INTO chunks_fts(rowid, text) VALUES (new.id, new.text);
  END;
  CREATE TRIGGER chunks_fts_update AFTER UPDATE ON document_chunks BEGIN
      INSERT INTO chunks_fts(chunks_fts, rowid, text) VALUES('delete', old.id, old.text);
      INSERT INTO chunks_fts(rowid, text) VALUES (new.id, new.text);
  END;
  CREATE TRIGGER chunks_fts_delete AFTER DELETE ON document_chunks BEGIN
      INSERT INTO chunks_fts(chunks_fts, rowid, text) VALUES('delete', old.id, old.text);
  END;
  INSERT INTO chunks_fts(chunks_fts) VALUES('rebuild');
""")
conn.commit()
conn.close()
PY

仪表板显示正在处理作业，但队列为空 - 打电话 POST /control/resume 或者重启索引器容器以刷新缓存的队列统计信息。数据库视图（SELECT status, COUNT(*) FROM index_jobs GROUP BY status) 是真理的源泉。
4B阶段的工作任务反复重新排队 - 确保索引器服务已更新到包含队列修复的最新版本（TEXT_EXTRACT 现在会重用现有的 CHUNK/FTS 作业）。清除所有死信条目，使用 UPDATE index_jobs SET status='pending' ... 在重启工作进程之前。

解决连接问题

问题：ChatGPT 显示“URL 无效”或连接失败

解决方案：

尝试明确使用IPv4： 使用 127.0.0.1 而不是 localhost
检查开发者模式： 确保已启用开发者模式的ChatGPT Pro/Plus

手动测试隧道：

curl -X POST https://your-tunnel-url.loca.lt/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "initialize", "id": 1, "params": {"protocolVersion": "2025-03-26", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0"}}}'

问题：隧道连接被拒绝或防火墙错误

解决方案：

尝试不使用特定子域名：

npx localtunnel --port 8000  # Let it assign random subdomain

使用替代的隧道服务：

# If you have ngrok installed
ngrok http 8000

问题：代理未收到请求

检查代理日志——如果没有显示任何请求，则说明ChatGPT无法访问隧道URL。

调试步骤：

验证隧道是否正在运行：在浏览器中访问隧道URL
使用curl直接测试隧道（如上所示）
检查ChatGPT桌面版的网络限制

1. 引言

1.1。目的

这个项目是一个 生产就绪的模型上下文协议（MCP）服务器 这使得AI代理能够安全地与您的本地文件系统进行交互。它提供了一个基于网页的管理界面，用于实时监控和细粒度的权限控制，并且正在扩展一个强大、以本地优先的搜索和检索引擎。

1.2。当前状态 - ✅ 第四阶段A部分 100% 完成

第4A阶段的高级搜索基础设施已全面实施，并为第4B阶段的开发提供了全面的文档支持：

🎯 第四阶段A（4A）成果总结

✅ 搜索基础设施完备带有文件监视、作业队列和元数据提取功能的索引服务
✅ 7个MCP工具已投入运营3个核心文件系统 + 4个带有光标分页的新搜索工具
✅ 数据库集成具有WAL模式的4A阶段模型（IndexedFile、IndexJob、ControlSetting）
✅ 性能已验证响应时间低于100毫秒，崩溃恢复，全面测试
✅ 生产问题已解决独立审查发现的所有3个关键漏洞均已修复
✅ 文档编制完成实施概要及第4B阶段开发指南

🚨 关键生产修复（v4.0.1）- 已解决

✅ 第013期数据库URL配置错误导致工作区API响应为空
✅ 第014期索引器导入错误导致服务无法启动
✅ 第015期当工作区列表为空时，前端出现404级联错误
✅（勾选标记，通常表示确认、正确或完成） 额外修复SQLAlchemy 参数格式、环境变量、跨容器导入

📖 第四阶段B（4B）阶段准备文件

📖 书籍 docs/Phase4A-Implementation-Summary.md - 完成4A阶段成就概览
📖 代表书本的符号，可翻译为“书本”或根据上下文具体翻译为相应的书籍相关词汇，如“书籍”、“读物”等。在这里，直接翻译该符号本身，可以表示为“书本（符号）”。 docs/Phase4B-Development-Guide.md - 详细的语义搜索实施方案
📖 书籍或阅读的象征 indexer/README.md - 全面的索引器服务文档
🎯（目标） 下一阶段基于向量嵌入的语义搜索，文档聚类，4种新的语义MCP工具

2. 建筑愿景：“索引器-查询”模型

为了支持高级搜索，该架构遵循了一个稳健的设计 “Indexer-Query”翻译为中文是“索引器-查询” 模式。此设计将应用程序划分为独立且相互协作的服务，以实现最佳性能和高韧性：

后端服务（查询引擎）： 现有的FastAPI应用程序仍然是所有API/MCP请求的中心枢纽。它负责对索引执行快速搜索，并且最重要的是，实时对所有结果应用安全权限。
索引器服务（后台处理器）： 一个新的独立服务，持续监控文件系统。它负责处理繁重的任务：解析文件、提取文本（包括OCR识别）、计算嵌入向量以及填充搜索索引。
前端服务（用户界面）： 现有的React应用程序将新增一个“索引器仪表板”功能，以让用户能够全面了解并控制（暂停/继续）索引过程。

这种分离确保了密集的后台处理永远不会影响主应用程序的响应性。

3. 系统架构

3.1。架构图

我们综合的Mermaid图表中展示了完整的系统架构：

📊（表格） 查看交互式架构图

此图展示了包含所有组件、数据流和（相关）的完整三服务Docker架构 .env 配置控制。关键架构元素包括：

前端服务带有索引器仪表板的React用户界面
后端服务集成LlamaIndex的FastAPI查询引擎
索引服务具有容错作业队列的后台处理
数据存储SQLite（WAL模式）、Qdrant向量数据库、HuggingFace模型缓存
配置全面的 .env 硬件适配系统

3.2。高级流程（或高水平流程）

User/Agent → Frontend/MCP → Backend (Query Engine) → Permission Filter → Results
                                ↓
File System ← Indexer ← Job Queue ← File Watcher
    ↓           ↓
SQLite FTS ← Embedding Model → Qdrant Vector DB

4. MCP协议实现

现有的文件系统工具仍然功能齐全。第四阶段将引入一套新的搜索工具。

4.1。可用的MCP工具（第4A阶段已完成）

工具	参数	描述	状态
核心文件系统工具
`read_file`	`path: string`	读取完整文件内容	✅ 准备就绪
`list_files`	`path: string`	列出目录内容及其元数据	✅ 准备就绪
`write_file`	`path: string, content: string`	将内容写入文件	✅ 准备就绪
4A阶段搜索工具
`list_all_files`	`limit, cursor, sort_by`	列出所有索引文件，并使用光标分页	✅ 准备就绪
`search_files_by_metadata`	`filename_pattern, file_types, size_range, mtime_range`	根据元数据标准搜索文件	✅ 准备就绪
`get_file_info`	`doc_id: string`	通过文档ID获取详细文件信息	✅ 准备就绪
`get_search_statistics`	-	获取索引进度和搜索统计信息	✅ 已准备就绪
第4B阶段搜索工具
`search_fulltext`	`query: string, limit, cursor, highlight, file_types`	使用FTS5的全文搜索，支持高亮显示和过滤	✅ 准备就绪

4.2。计划中的高级搜索工具（第四阶段B部分M3+）

工具	描述	状态
`search_semantic`	使用嵌入进行语义相似性搜索	📋 计划中
`find_similar`	“类似更多”向量搜索	📋 计划中
`search_hybrid`	将FTS5与向量搜索结合使用RRF	📋 已计划

5. 配置管理

5.1。环境变量 (`.env`）

该系统采用全面的 .env 配置以支持在不同硬件环境中灵活部署：

硬件与模型选择

# GPU/CPU switching - critical for RTX 4060 users
INDEX_EMBED_DEVICE=cpu           # or 'gpu' when RTX 4060 available
INDEX_EMBED_QUANT=fp16           # Future: 4bit/8bit/fp16 for VRAM management
INDEX_EMBED_MODEL=paraphrase-multilingual-MiniLM-L12-v2

功能开关（或特性开关）

# Resource-intensive features with user control
OCR_ENABLED=true                 # Tesseract OCR processing
RERANK_ENABLED=false             # Optional cross-encoder reranker

性能调优

# Search and indexing behavior
RETRIEVAL_MODE=hybrid            # hybrid/fts/vector - invaluable for debugging
INDEXER_BATCH_SIZE=50            # Files per batch - tune memory vs speed
INDEXER_MAX_WORKERS=2            # Parallel processing control

这种配置策略使得在笔记本电脑（仅CPU）和台式机（RTX 4060）环境之间能够实现无缝切换，同时保持每种设置下的最佳性能。

前端API基础URL（新）

# Point the frontend to a non-default backend origin if needed
VITE_API_BASE_URL=http://localhost:8000

共享文件系统挂载：主机路径与容器路径

在 Docker 中，你的主机文件夹（例如。， C:\Users\<you>\MCP Test被安装到容器中时 /source。
后端API和索引器始终使用 /source 在容器内部访问文件。
其中的验证器 config/env_config.py 现在治疗 /source 在Docker中具有权威性，因此一个Windows路径字符串在 .env 将不再触发错误警告。

Docker Compose 映射示例：

volumes:
  - ${SHARED_FS_PATH:-./shared-fs}:/source  # host:container

保持 SHARED_FS_PATH 指向你的宿主文件夹。在容器内部，代码使用 /source。

6. 技术栈

类别	技术	目的	状态
集装箱化	Docker Compose	四服务编排：后端、前端、索引器、Qdrant	✅ 第4B阶段M1
后端 FastAPI	MCP/API 端点和带有搜索工具的查询引擎	✅ 第4A阶段
前端	React, Vite	带索引器仪表板和控件的Web用户界面	✅ 第四阶段A
索引器	Python/Watchdog	背景文件监控与任务处理	✅ 第四阶段A
数据库应用程序	SQLite (WAL)	并发存储：工作区、权限、文件、作业、数据块	✅ 第4B阶段 M1
全文搜索	SQLite FTS5	耐拼写错误的关键词搜索的三元组分词器	✅ 第四阶段B 第一月
作业队列	SQLite	具有原子性抢占功能的容错作业队列	✅ 第四阶段A
向量数据库	Qdrant 版本 1.7.4	高性能的向量嵌入存储与检索	✅ 第四阶段B版M1
RAG框架	LlamaIndex（注：LlamaIndex是一个用于构建和查询文档数据库的索引工具，这里直接保留原名，不进行意译）	数据摄入、索引和查询的核心工具包	✅ 第四阶段B第1个月
嵌入模型	`paraphrase-multilingual-MiniLM-L12-v2`	基于CPU的多语言语义搜索模型	📋 第四阶段B M2+
OCR引擎	Tesseract（注：这是一个专有名词，通常不翻译，直接保留原名，但在此提供音译以供参考）	从图片和扫描文档中提取文本	📋 第4B阶段 M3+

6. 项目结构

MCPFileServer/
├── 📁 backend/                  # Python FastAPI backend (Query Engine)
├── 📁 frontend/                 # React TypeScript frontend (UI)
├── 📁 indexer/                  # Python background service for indexing
├── 📁 config/                   # Global configuration
├── 📁 data/                     # SQLite database (gitignored)
├── 📁 docs/                     # Phase documentation and guides
├── 📁 scripts/                  # Testing and utility scripts
├── 📄 docker-compose.yml        # 4-service orchestration: backend, frontend, indexer, qdrant
├── 📄 chatgpt_proxy.py          # MCP compatibility proxy for ChatGPT Desktop
├── 📄 .env                      # Environment variables
├── 📄 README.md                 # This file
└── 📄 CLAUDE.md                 # Project context for Claude

7. 监控与调试

7.1。日志访问

# View all container logs
docker-compose logs

# Follow logs for a specific service in real-time
docker-compose logs -f backend
docker-compose logs -f frontend
docker-compose logs -f indexer

7.2。服务健康监测

索引器服务状态：

# Check indexer health
curl http://localhost:8002/live    # Liveness check
curl http://localhost:8002/ready   # Readiness check with database validation

# Monitor indexing status
curl http://localhost:8002/status/system   # Overall system status
curl http://localhost:8002/status/jobs     # Job queue statistics
curl http://localhost:8002/status/files    # Indexed file statistics

后端服务状态：

# Check backend health
curl http://localhost:8000/         # Health check
curl http://localhost:8000/docs     # API documentation

# Database diagnostic (useful for troubleshooting)
curl http://localhost:8000/api/system/db-info

强制重新索引管理：

# Check reindex system status
curl http://localhost:8000/admin/reindex/status

# List active reindex batches
curl -H "X-Admin-Key: admin-secret-key-change-me" \
  http://localhost:8000/admin/reindex/batches

# Get specific batch status
curl -H "X-Admin-Key: admin-secret-key-change-me" \
  http://localhost:8000/admin/reindex/batches/{batch_id}

# Access web UI for visual management
# Navigate to Indexer tab -> Force Reindex dropdown

7.3。 MCP工具测试

7.4。索引器仪表板警报

前端的索引器视图现在与后端的状态数据相匹配：

当服务停止、无法访问或积压任务增多时，表面积会显示横幅警告。
显示各阶段的队列深度（TEXT_EXTRACT、CHUNK、FTS_INDEX），并突出显示失败/死信作业。
进度条分段显示已索引文件与待处理文件，并标记出仍缺少文本块的已索引文件。
拉力；拉动；拉（的动作） service_error， job_backlog，和 integrity_stats 来自 /api/indexer/status因此，Docker 操作员可以立即看到第 4B 阶段的流水线是否停滞。

完成MCP协议验证：

# Test all 8 MCP tools with comprehensive suite
./scripts/test-mcp-wisdom.sh --comprehensive

# Quick validation
curl -X POST http://localhost:8000/mcp -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

📋 对于4B阶段开发：

见 docs/Phase4A-Implementation-Summary.md 以获取完整的成就详情
见 docs/Phase4B-Development-Guide.md 语义搜索实施计划
看 indexer/README.md 用于全面的索引器服务文档