文档导航器MCP-SUSE版
Docs Navigator MCP - SUSE Edition
一 AI驱动的文档导航器 构建为模型上下文协议（MCP）服务器，可使用以下工具对SUSE、Rancher、K3s、RKE2、Longhorn、Harvester、NeuVector和Kubewarden文档进行智能搜索、摘要和探索 开源人工智能模型.
✨ 新 生产就绪，具有SQLite缓存、高级分析、并发索引支持和有组织的代码库！
🎨 查看实时演示 -查看GitHub Pages上的UI演示！
📚 文档
- 架构概述 -系统设计和组件
- 安装指南 -详细的设置说明
- 文档来源 -所有可用资源和使用指南
- 索引指南 -理解缓存与索引⭐
- 快速参考 -命令参考
- 使用示例 -常见使用模式
- Web GUI指南 -Web界面文档
- MCP客户端设置 -配置MCP客户端
- SQLite迁移指南 -SQLite缓存详细信息
- 变化检测 -用于监控文档更改的自动更新系统⭐
- -将UI展示部署到GitHub页面
- 贡献 -贡献指南
🌟 特性
核心能力
- 🌐 Web图形用户界面 -美观的本地主机web界面，便于访问
- 🔍 语义文档搜索 -使用自然语言查询查找相关文档
- 🤖 本地开源AI -由Ollama（Llama、Mistral等）提供动力-不需要API密钥
- 📚 多源支持 -浏览SUSE、Rancher、K3s、RKE2、Longhorn、Harvester、NeuVector、Kubewarden文档
- 💬 会话界面 -提问并获得源引用的答案
- 📝 智能摘要 -生成简明或详细的文档摘要
- 🔌 MCP协议 -与Claude Desktop和其他MCP兼容客户端集成
- ⚡ 矢量搜索 -基于嵌入的快速语义检索
- 🎯 灵活的人工智能提供商 -支持Ollama（本地）、OpenAI或Anthropic
生产特性（新增！）
- 💾 SQLite缓存 -使用SQLite进行高效的页面缓存，可扩展到1000个文档
- 📊 分析报告 -全面的缓存分析和运行状况监控
- 🔍 高级查询 -按来源、状态、日期范围筛选缓存文档
- 🔒 并发索引 -具有自动锁定功能的安全多进程索引
- 📈 缓存管理 -验证、清除、重建和优化缓存
- 🎯 智能索引 -有条件的GET请求、ETag/上次修改支持、内容哈希检测
- 🔄 变化检测 -监控文档的更新并自动触发重新索引
- 📦 有组织的代码库 -干净的目录结构，CLI/services/tests/utils分离
🏗️ 建筑
graph TB
subgraph "Client Layer"
WEB[🌐 Web Browser
localhost:3000]
CLAUDE[🤖 Claude Desktop
MCP Client]
CLI[⌨️ CLI Tools
npm commands]
end
subgraph "Application Layer"
WEBSERVER[🖥️ Web Server
Express.js
Port 3000]
MCP[📡 MCP Server
index.js
stdio protocol]
CLITOOLS[🛠️ CLI Tools
indexer, analytics,
cache manager]
end
subgraph "Service Layer"
DOCSERVICE[📚 Documentation Service
- Fetch & Parse HTML
- Content Extraction
- Sitemap Processing]
AISERVICE[🧠 AI Service
- LLM Integration
- Prompt Management
- Response Formatting]
VECTORSERVICE[🔍 Vector Service
- Embedding Generation
- Semantic Search
- Similarity Ranking]
CACHESERVICE[💾 Cache Service
- SQLite Operations
- Page Management
- Lock Handling]
end
subgraph "Storage Layer"
SQLITE[(🗄️ SQLite Database
page-cache.db
- Pages Table
- Locks Table)]
VECTORS[(📊 Vector Index
vectra/index.json
- Embeddings
- Metadata)]
HTMLCACHE[📁 HTML Cache
data/html/
cached pages]
end
subgraph "External Services"
OLLAMA[🦙 Ollama
Local LLMs
localhost:11434]
OPENAI[🌐 OpenAI API
GPT Models
Embeddings]
ANTHROPIC[🔷 Anthropic API
Claude Models]
DOCS[📖 Documentation Sites
- docs.k3s.io
- ranchermanager.docs
- documentation.suse.com
- etc.]
end
%% Client connections
WEB -->|HTTP/REST API| WEBSERVER
CLAUDE -->|stdio/MCP| MCP
CLI -->|Node.js| CLITOOLS
%% Application layer connections
WEBSERVER -->|Use Services| DOCSERVICE
WEBSERVER -->|Use Services| AISERVICE
WEBSERVER -->|Use Services| VECTORSERVICE
MCP -->|Use Services| DOCSERVICE
MCP -->|Use Services| AISERVICE
MCP -->|Use Services| VECTORSERVICE
CLITOOLS -->|Use Services| DOCSERVICE
CLITOOLS -->|Use Services| CACHESERVICE
%% Service layer connections
DOCSERVICE -->|Read/Write| CACHESERVICE
DOCSERVICE -->|Fetch| DOCS
DOCSERVICE -->|Store HTML| HTMLCACHE
AISERVICE -->|Query LLM| OLLAMA
AISERVICE -->|Query LLM| OPENAI
AISERVICE -->|Query LLM| ANTHROPIC
VECTORSERVICE -->|Generate Embeddings| OLLAMA
VECTORSERVICE -->|Generate Embeddings| OPENAI
VECTORSERVICE -->|Read/Write| VECTORS
CACHESERVICE -->|SQL Operations| SQLITE
%% Styling
classDef clientStyle fill:#e1f5ff,stroke:#01579b,stroke-width:2px
classDef appStyle fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
classDef serviceStyle fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
classDef storageStyle fill:#fff3e0,stroke:#e65100,stroke-width:2px
classDef externalStyle fill:#fce4ec,stroke:#880e4f,stroke-width:2px
class WEB,CLAUDE,CLI clientStyle
class WEBSERVER,MCP,CLITOOLS appStyle
class DOCSERVICE,AISERVICE,VECTORSERVICE,CACHESERVICE serviceStyle
class SQLITE,VECTORS,HTMLCACHE storageStyle
class OLLAMA,OPENAI,ANTHROPIC,DOCS externalStyle关键组件
- Web图形用户界面：用于交互式文档搜索的现代类React界面
- MCP服务器：Claude Desktop集成的模型上下文协议实现
- CLI工具：用于索引、分析和缓存管理的命令行实用程序
- 文档服务：处理文档页面的获取、解析和缓存
- 人工智能服务：管理LLM互动，支持多个提供商（Ollama、OpenAI、Anthropic）
- 矢量服务：生成嵌入并使用Vectra执行语义搜索
- 缓存服务：基于SQLite的缓存系统，具有并发操作锁定功能
🆕 最近更新（2025年12月）
阶段3：生产就绪SQLite迁移
新增内容：
- SQLite缓存系统
- 从JSON迁移到SQLite以获得更好的可扩展性 - 支持1000个文档而不会降低性能 - 自动创建模式，对源、状态、时间戳进行索引 - 向后兼容-可以还原为JSON USE_JSON_CACHE=true
- 高级分析和查询
- npm run analytics -全面的缓存运行状况报告 - npm run query-cache -按来源、状态、日期范围筛选 - 缓存效率指标、过时页面检测、自动推荐 - 按来源细分，显示指数/总比率
- 并发索引安全
- 基于表的锁定可防止竞争条件 - 30分钟锁定超时，自动过期 - npm run clear-locks 用于手动锁清理 - 可以安全地同时运行多个索引过程
- 有组织的代码库
- 干净的目录结构： cli/, services/, tests/, utils/ - 15个文件从根目录重新组织到逻辑文件夹中 - 更好的可维护性和开发人员体验 - 综合文档 src/README.md
- 性能优化
- 支持ETag/上次修改的智能缓存 - 内容哈希检测跳过未更改的文档 - 站点地图优化在获取之前预过滤URL - 有条件的GET请求减少了不必要的下载
迁移：
- 现有用户：运行
npm run migrate-sqlite转换JSON缓存 - 新用户：默认为SQLite，无需任何操作
- 看 docs/SQLITE_MIGRATION.md 详情
🚀 快速开始
先决条件
步骤1：安装依赖项
# Clone the repository
git clone https://github.com/mso-docs/Docs-Navigator-MCP-SUSE-Edition.git
cd Docs-Navigator-MCP-SUSE-Edition
# Install Node.js dependencies
npm install第二步：安装AI模型
选项A：Ollama本地AI（免费，建议问答）
# Install Ollama from https://ollama.ai
# Pull required models
ollama pull llama3.2:latest # For answering questions
ollama pull nomic-embed-text # For embeddings (alternative)
# Verify Ollama is running
ollama list选项B:OpenAI（推荐用于嵌入）
# Get API key from https://platform.openai.com/api-keys
# Add to .env file: OPENAI_API_KEY=your_key_here混合方法（最佳性能）：
- 使用OpenAI进行嵌入（快速、可靠）
- 使用Ollama进行问答（免费，私人）
步骤3：配置环境
# Copy example environment file
cp .env.example .env
# Edit .env with your settings
nano .env # or use your favorite editor基本配置：
# For Ollama-only setup
AI_PROVIDER=ollama
EMBEDDING_PROVIDER=ollama
OLLAMA_MODEL=llama3.2:latest
EMBEDDING_MODEL=nomic-embed-text
# For OpenAI embeddings + Ollama Q&A (Recommended)
AI_PROVIDER=ollama
EMBEDDING_PROVIDER=openai
OPENAI_API_KEY=sk-your-key-here
OLLAMA_MODEL=llama3.2:latest
# Cache settings (SQLite is default)
PAGE_CACHE_PATH=./data/page-cache.db
EMBEDDING_CACHE_PATH=./data/embedding-cache.json步骤4：索引文档
# Index all documentation sources (SUSE, Rancher, K3s)
npm run index all
# Or index individual sources
npm run index k3s
npm run index rancher
npm run index suse首次索引需要5-15分钟 这取决于您的互联网速度和AI提供商。由于缓存，后续运行要快得多。
第五步：开始使用！
Web界面（最简单）：
npm run web然后打开 在您的浏览器中。
MCP服务器（用于克劳德桌面）：
npm start看 docs/MCP_CLIENT_CONFIG.md 用于克劳德桌面设置。
🎉 你准备好了！
试着问以下问题：
- “如何在SUSE上安装K3？”
- “K3和RKE2之间有什么区别？”
- “显示Rancher备份程序”
看 docs/EXAMPLES.md 了解更多使用示例。
🛠️ 可用工具
MCP服务器提供以下工具：
search_docs
使用语义搜索搜索文档。
{
"query": "How do I install K3s on SUSE?",
"source": "all",
"limit": 5
}ask_question
询问有关文档的问题，并获得人工智能生成的答案。
{
"question": "What are the differences between K3s and RKE2?",
"context": "deployment on SUSE Linux Enterprise"
}summarize_doc
生成文档页面的AI摘要。
{
"url": "https://docs.k3s.io/installation",
"format": "bullet-points"
}get_doc_section
检索特定的文档内容。
{
"url": "https://documentation.suse.com/sles/15-SP5/"
}index_documentation
索引文档以加快搜索速度。
{
"source": "k3s",
"forceRefresh": false
}list_doc_sources
查看所有可用的文档源及其状态。
📖 使用示例
Web界面（最简单！）
启动web界面并从浏览器访问它：
npm run web然后打开 http://localhost:3000 在您的浏览器中。看 docs/WEB_GUI.md 了解详情。
使用克劳德桌面
- 配置Claude桌面（请参阅 docs/INSTALL.md)
- 让克劳德使用这些工具：
"Can you search the SUSE documentation for information about container security?"
"Use the docs navigator to find K3s installation instructions"
"Summarize the Rancher high availability setup documentation"直接MCP使用
# Start the MCP server
npm start
# The server communicates via stdio using MCP protocol命令行工具
# Indexing
npm run index [source] # Index documentation (k3s, rancher, suse, all)
npm run index all # Index all sources
npm run index k3s --force # Force refresh (ignore cache)
# Cache Management
npm run stats # Show cache statistics
npm run analytics # Comprehensive analytics report
npm run query-cache [opts] # Query cache with filters
npm run clear-cache # Clear all caches
npm run validate # Validate cache integrity
npm run clear-locks # Clear expired indexing locks
# Utilities
npm run fix-sources # Fix legacy cache entries
npm run mark-indexed # Mark documents as indexed
npm run migrate-sqlite # Migrate JSON cache to SQLite
# Testing
npm test # Run test suite🏗️ 建筑
┌─────────────────────────────────────────────────────────────┐
│ User Interfaces │
├─────────────────┬─────────────────┬──────────────────────────┤
│ Web Browser │ Claude Desktop │ Direct MCP Client │
│ (port 3000) │ (MCP stdio) │ (stdio/JSON) │
└────────┬────────┴────────┬────────┴────────┬─────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────┐
│ Application Layer (Node.js) │
├─────────────────┬───────────────────────┬───────────────────┤
│ web-server.js │ index.js (MCP) │ CLI Tools │
│ (Express) │ (stdio protocol) │ (index-docs.js) │
└────────┬────────┴───────────┬───────────┴────────┬──────────┘
│ │ │
└────────────────────┼────────────────────┘
▼
┌─────────────────────────────────────────────────────────────┐
│ Service Layer │
├──────────────────┬──────────────────┬──────────────────────┤
│ AI Service │ Vector Service │ Doc Service │
│ - Ollama Q&A │ - Vectra DB │ - HTTP fetching │
│ - OpenAI embed │ - Embeddings │ - HTML parsing │
│ - Summarization │ - Similarity │ - Cache management │
└────────┬─────────┴────────┬─────────┴──────────┬───────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────┐
│ Data Layer │
├───────────────┬─────────────────┬────────────────────────────┤
│ SQLite Cache │ Vectra Vectors │ Embedding Cache (JSON) │
│ - Page cache │ - Doc chunks │ - Text hash → vector │
│ - Metadata │ - Embeddings │ - Fast deduplication │
└───────────────┴─────────────────┴────────────────────────────┘关键组件
- MCP服务器 (
index.js)：通过stdio实现工具执行的模型上下文协议 - Web服务器 (
web-server.js)：Express服务器提供基于浏览器的用户界面 - 人工智能服务：处理LLM互动问答和总结（Ollama/OpenAI/Anthropic）
- 缓存服务：基于SQLite的页面缓存，具有高级查询和分析功能
- 矢量服务：使用Vectra矢量数据库管理语义搜索
- 文档服务：使用智能缓存获取、解析和索引文档
数据流
- 索引：文档→ 获取→ 解析→ 块→ 嵌入→ 存储在Vectra+Cache中
- 搜索：查询→ 嵌入→ 矢量搜索→ 检索文档→ 返回结果
- 问答：问题→ 上下文搜索→ LLM → 引用答案
🔧 配置
编辑 .env 配置：
# AI Provider (ollama, openai, anthropic)
AI_PROVIDER=ollama
# Ollama Settings
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=llama3.2:latest
EMBEDDING_MODEL=nomic-embed-text
# Documentation Sources
SUSE_DOCS_BASE_URL=https://documentation.suse.com
RANCHER_DOCS_URL=https://ranchermanager.docs.rancher.com
K3S_DOCS_URL=https://docs.k3s.io
# Vector Database
VECTOR_DB_PATH=./data/vectors📁 项目结构
Docs-Navigator-MCP-SUSE-Edition/
├── docs/ # Documentation files
│ ├── ARCHITECTURE.md # System design and components
│ ├── INSTALL.md # Detailed installation guide
│ ├── QUICKREF.md # Command quick reference
│ ├── EXAMPLES.md # Usage examples
│ ├── WEB_GUI.md # Web interface guide
│ ├── MCP_CLIENT_CONFIG.md # MCP client configuration
│ ├── SQLITE_MIGRATION.md # SQLite caching guide
│ └── CONTRIBUTING.md # Contribution guidelines
│
├── scripts/ # Setup and utility scripts
│ ├── setup.sh # Linux/macOS setup script
│ └── setup.bat # Windows setup script
│
├── src/ # Source code (organized by purpose)
│ ├── cli/ # Command-line tools
│ │ ├── index-docs.js # Main indexing CLI
│ │ ├── cache-analytics.js # Analytics reports
│ │ ├── query-cache.js # Cache queries
│ │ └── clear-locks.js # Lock management
│ │
│ ├── services/ # Core business logic
│ │ ├── ai-service.js # AI/LLM integration
│ │ ├── cache-service.js # SQLite cache management
│ │ ├── documentation-service.js # Doc fetching & parsing
│ │ └── vector-service.js # Vector database ops
│ │
│ ├── tests/ # Test scripts
│ │ ├── test.js # Main test suite
│ │ ├── test-cache.js # Cache tests
│ │ ├── test-concurrent-locks.js # Lock tests
│ │ └── test-ollama.js # Ollama integration tests
│ │
│ ├── utils/ # Maintenance utilities
│ │ ├── migrate-to-sqlite.js # JSON→SQLite migration
│ │ ├── fix-cache-sources.js # Cache repair tools
│ │ └── mark-indexed.js # Status updates
│ │
│ ├── index.js # MCP server entry point
│ └── web-server.js # Web UI server
│
├── public/ # Web GUI assets (HTML, CSS, JS)
├── data/ # Data storage
│ ├── vectors/ # Vector database (Vectra)
│ ├── page-cache.db # SQLite page cache
│ ├── embedding-cache.json # Embedding cache
│ └── html/ # Cached HTML files
│
└── .env # Environment configuration🔧 故障排除
安装问题
问题： npm install 失败
# Clear npm cache and retry
npm cache clean --force
rm -rf node_modules package-lock.json
npm install问题：Node.js版本太旧
# Check version (needs 18+)
node --version
# Update Node.js from https://nodejs.org/
# Or use nvm:
nvm install 18
nvm use 18Ollama问题
问题：“连接被拒绝”或“ECONNREFUSED”
# Check if Ollama is running
curl http://localhost:11434/api/tags
# Start Ollama
ollama serve
# Or check Ollama is installed
ollama --version问题：找不到模型
# List installed models
ollama list
# Pull required models
ollama pull llama3.2:latest
ollama pull nomic-embed-text
# Verify models work
ollama run llama3.2:latest "Hello"问题：Ollama太慢了
# Use OpenAI for embeddings instead
# Edit .env:
EMBEDDING_PROVIDER=openai
OPENAI_API_KEY=your_key_here
# Keep Ollama for Q&A (free and private)
AI_PROVIDER=ollama索引问题
问题：索引失败，显示“项目已存在”
# This happens with parallel indexing - use sequential mode
# In .env file:
FETCH_BATCH_SIZE=1
# Or clear vectors and reindex
npm run clear-cache
npm run index all问题：“另一个索引进程已在运行”
# Clear stale locks
npm run clear-locks
# Then retry indexing
npm run index all问题：索引速度非常慢
# Use OpenAI embeddings (much faster than Ollama)
# Edit .env:
EMBEDDING_PROVIDER=openai
OPENAI_API_KEY=your_key_here
# Ollama embeddings take ~30 min for 110 docs
# OpenAI embeddings take ~2 min for same docs问题：索引过程中出现“404 Not Found”
# Some documentation URLs may have changed
# Check cache analytics for details
npm run analytics
# Rebuild specific source
npm run rebuild suse缓存问题
问题：UI显示“0个文档已索引”
# Check actual cache status
npm run stats
# If cache exists but UI shows 0, restart web server
npm run web
# If genuinely empty, index documentation
npm run index all问题：缓存内容已过时
# Force refresh all caches
npm run index all --force
# Or clear and reindex
npm run clear-cache
npm run index all问题：缓存损坏
# Validate cache integrity
npm run validate
# If errors found, rebuild
npm run clear-cache
npm run migrate-sqlite # If migrating from JSON
npm run index allWeb界面问题
问题：Web服务器无法启动
# Check if port 3000 is in use
lsof -i :3000 # Linux/Mac
netstat -ano | findstr :3000 # Windows
# Kill process using port 3000 or change port
# Edit src/web-server.js: const PORT = 3001;问题：web UI中“未找到结果”
# Verify documents are indexed
npm run stats
# Check AI service is working
npm test
# Verify Ollama/OpenAI connection
curl http://localhost:11434/api/tags # OllamaMCP服务器问题
问题：Claude Desktop无法连接
# Verify MCP server starts
npm start
# Check Claude Desktop config file location:
# macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
# Windows: %APPDATA%\Claude\claude_desktop_config.json
# Validate config syntax (must be valid JSON)
# See docs/MCP_CLIENT_CONFIG.md for examples问题：工具未出现在Claude中
# Restart Claude Desktop completely
# Check server logs for errors
npm start 2>&1 | tee server.log性能问题
问题：搜索速度慢
# Check cache stats
npm run analytics
# Ensure documents are indexed
npm run stats
# Try rebuilding vector index
npm run clear-cache vectors
npm run index all问题：内存使用率高
# Reduce batch sizes in .env:
FETCH_BATCH_SIZE=1
EMBEDDING_CONCURRENCY=1
# Or use OpenAI embeddings (more efficient)
EMBEDDING_PROVIDER=openai数据库问题
问题：SQLite数据库已锁定
# Close all processes accessing database
pkill -f "node src"
# Clear locks
npm run clear-locks
# If persists, delete and rebuild
rm data/page-cache.db
npm run index all问题：想要还原到JSON缓存
# Edit .env file:
USE_JSON_CACHE=true
PAGE_CACHE_PATH=./data/page-cache.json
# Restart services
npm run web获取帮助
- 检查日志：在终端输出中查找错误消息
- 运行诊断程序:
npm run stats和npm run analytics - 验证设置:
npm test运行测试套件 - 检查文件：参见
docs/详细指南文件夹 - GitHub问题：在存储库问题页面报告错误
常见错误消息
| 错误 | 解决方案 |
|---|---|
ECONNREFUSED | Ollama没有跑步-从开始 ollama serve |
Item already exists | 使用 FETCH_BATCH_SIZE=1 在.env中 |
Lock held by another process | 快跑 npm run clear-locks |
No such table: locks | 首次运行时正常-自动创建表 |
404 Not Found | 文档URL已更改-运行 npm run rebuild |
ENOENT: no such file | 创建数据目录： mkdir -p data/{vectors,html} |
🤝 贡献
欢迎投稿！该项目始于 黑客周25.
看 docs/CONTRIBUTING.md 作为指导方针。
📄 许可证
看 许可证 文件以获取详细信息。
🎯 用例
- DevOps工程师：快速查找部署和配置信息
- 系统管理员：高效浏览SUSE Linux文档
- Kubernetes用户：获取有关K3和Rancher的即时答案
- 技术作家：研究和交叉参考文件
- 支持团队：通过语义搜索更快地找到解决方案
🔗 资源
平台和工具
文档来源
______________________________________________________________________
内置于❤️ 黑客周25