Local Knowledge Rag MCP

本地知识RAG MCP服务器

一个使用向量嵌入的本地文档语义搜索和检索系统。由MCP（模型上下文协议）提供支持。

该项目基于RAG的实施 黑曜石智能作曲器. 我们将其改编为独立的MCP服务器，专注于本地文档搜索和知识管理。

使用向量嵌入和相似性搜索在本地文档中提供语义搜索，并支持多个嵌入提供者（OpenAI、Ollama和OpenAI兼容的API）。

______________________________________________________________________

概述

本地知识RAG MCP服务器支持对本地文档集合进行人工智能语义搜索。它不是基于关键字的搜索，而是理解查询的含义，并通过向量嵌入找到相关内容。

关键能力：

• 基于向量嵌入的语义搜索
• 支持多个嵌入提供者（OpenAI、Ollama、LiteLLM和任何与OpenAI兼容的API）
• 基于会话的搜索结果缓存
• 使用多个模板生成可定制的报告
• PostgreSQL与pgvector用于高性能向量相似性搜索
• HNSW索引用于快速近似最近邻搜索
• 增量索引和完全重建

______________________________________________________________________

为什么是这个项目？

在尝试Dify和RAGFlow等各种RAG（检索增强生成）解决方案时，我们遇到了几个局限性：

1. 知识库管理成本高：添加、删除和更新文档需要耗时的手动步骤
2. 引用可用性差：引用引用的是内部知识库资源，而不是实际的源文件，这使得它们难以使用
3. 输出格式灵活性有限：报告生成很僵化，无法轻松定制

黑曜石智能作曲器 通过直接处理本地文件，完美地解决了问题#1和#2。这激励我们将同样的体验带到VS Code中，许多开发人员将大部分时间花在了VS Code上。

本地知识RAG MCP服务器的独特之处：

• 灵活的报告模板：使用模板文件自由自定义RAG输出格式（与其他解决方案中的刚性输出格式不同）
• 可扩展到大型知识库：使用PostgreSQL的pgvector扩展进行高效的向量相似性搜索，处理大型文档集合
• 内置索引管理器：用于监控索引进度和管理知识库的基于Web的界面
• VS代码集成：与Claude Code扩展无缝集成，将RAG功能直接带入您的开发工作流程

______________________________________________________________________

推荐环境

此MCP服务器针对以下环境进行了优化：

• 集成开发环境: VS代码
• 扩展: VS Code 的 Claude 代码
• AI模型：克劳德十四行诗4.5（最新版）

虽然服务器可以与任何兼容MCP的客户端一起工作，但上述组合提供了最佳性能和集成的最佳体验。

______________________________________________________________________

快速开始

只需5个步骤即可开始跑步：

1.使用pgvector设置PostgreSQL

使用Docker（最简单）：

docker run -d \
  --name local-knowledge-rag-db \
  -e POSTGRES_DB=local_knowledge_rag \
  -e POSTGRES_USER=user \
  -e POSTGRES_PASSWORD=password \
  -p 5432:5432 \
  -v local-knowledge-rag-data:/var/lib/postgresql/data \
  --restart unless-stopped \
  ankane/pgvector

注： 以上证书仅用于当地发展。如果端口5432已经在使用中。， -p 5433:5432)并更新 DATABASE_URL 因此。

2.克隆并构建项目

git clone https://github.com/patakuti/local-knowledge-rag-mcp.git
cd local-knowledge-rag-mcp
npm install
npm run build

3.配置环境变量

# Copy the example file
cp .env.example .env

# Edit .env with your settings
# Minimal configuration:
DATABASE_URL=postgresql://user:password@localhost:5432/local_knowledge_rag

# Choose ONE embedding provider:
# Option A: OpenAI
OPENAI_API_KEY=sk-your-openai-api-key

# Option B: LiteLLM (recommended - supports multiple providers)
OPENAI_COMPATIBLE_BASE_URL=http://localhost:4000/v1
OPENAI_COMPATIBLE_API_KEY=your-litellm-key
EMBEDDING_MODEL=cl-nagoya/ruri-v3-310m

# Option C: Ollama (local, offline)
OLLAMA_BASE_URL=http://localhost:11434/v1
EMBEDDING_MODEL=nomic-embed-text

4.添加到克劳德代码

将此MCP服务器添加到克劳德代码中：

# Add globally (available in all projects)
claude mcp add -s user local-knowledge-rag -- node /path/to/local-knowledge-rag-mcp/dist/mcp-server.js

# Add to a specific project
cd /path/to/your/project
claude mcp add local-knowledge-rag -- node /path/to/local-knowledge-rag-mcp/dist/mcp-server.js

注： 环境变量从以下位置加载 .env 文件自动。出于安全原因，不要将它们添加到MCP服务器配置中。

5.开始使用它！

重新启动Claude Code并开始对话：

1. 打开索引管理器：对克劳德说：“打开指数管理器”
2. 生成索引：在打开的web界面中，单击“更新索引”按钮
3. 开始搜索：对克劳德说：“在我的文档中搜索有关\[你的主题\]的信息，并创建一份报告”

就是这样！Claude将自动使用RAG工具搜索您的文档并生成报告。

看 使用示例 了解更多详情。

______________________________________________________________________

特性

• 语义搜索：使用向量嵌入来查找语义相似的内容
• 多个嵌入提供程序：OpenAI、Ollama或任何与OpenAI兼容的API
• 多工作区支持：将同一数据库用于多个独立的工作区
• 会话管理：跨多个查询缓存和重用搜索结果
• 模板驱动报告：使用可定制的模板生成格式化的Markdown报告
• pgvector扩展：使用PostgreSQL进行高性能向量相似性搜索
• HNSW索引：快速近似最近邻搜索大型数据集
• 灵活的文件模式：包含/排除文件模式以进行细粒度控制
• MCP集成：与Claude Code和其他MCP客户端无缝集成
• 实时进度跟踪：基于Web的进度查看器显示索引操作期间的实时更新，包括完成百分比、文件计数和正在处理的当前文件

______________________________________________________________________

配置

所有配置都是通过环境变量完成的 .env 文件。看 快速开始 用于基本设置。

常见配置任务：

• 更改嵌入模型：编辑 .env，跑 reload_config 工具，然后重建索引
• 调整搜索参数：编辑 .env RAG设置，重新启动MCP服务器
• 文件模式：编辑 RAG_INCLUDE_PATTERNS 和 RAG_EXCLUDE_PATTERNS 在 .env

有关完整的配置参考，请参阅 docs/configuration.md.

______________________________________________________________________

多工作区支持

多个工作区可以共享同一个PostgreSQL数据库。每个工作区根据其绝对路径自动维护自己的隔离索引。

主要特点：

• ✅ 多个工作区共享同一个 DATABASE_URL （配置于 .env)
• ✅ 每个工作区都有自己的独立索引（没有数据冲突）
• ✅ 并发更新是安全的（受PostgreSQL咨询锁保护）

只需为所有项目使用相同的数据库，系统就会自动处理工作区隔离。

______________________________________________________________________

使用示例

创建索引

在搜索之前，您需要创建文档索引：

1. 对克劳德说：“打开指数管理器”
2. 在web界面中，单击 “更新索引” 为文档建立索引的按钮
3. 等待索引完成-您将在界面中看到实时进度

注： 索引管理器将仅索引与您的模式匹配的文件（默认值： **/*.md 和 **/*.txt).你可以在你的 .env 文件。

搜索您的文档

一旦你的索引准备好了，自然地和克劳德谈谈：

简单搜索：

• “在我的文档中搜索有关React钩子的信息并创建报告”
• “查找有关数据库设置的文档并创建摘要”
• “查找错误处理示例并创建报告”

在特定文件夹中搜索：

• “在/src/components文件夹中搜索按钮实现并创建报告”
• “在docs目录中查找配置示例并创建摘要”

高级分析：

• “搜索React模式并创建详细的摘要报告”
• “分析我的数据库架构并生成文档”

克劳德将自动：

1. 搜索您的索引文档
2. 基于语义相似度查找相关内容
3. 生成格式化的Markdown报告
4. 将报告保存到 ./rag-reports/ 目录

高级： 有关MCP工具的直接使用和详细参数，请参阅 docs/mcp-tools.md.

报表自定义： 报告保存到 ./rag-reports/ 默认情况下。您可以创建自定义模板（内置： basic, paper, bullet_points, manual)-看 docs/templates.md.

______________________________________________________________________

可用的MCP工具

搜索和报告：

• search_knowledge -执行语义搜索
• get_search_results -检索详细结果
• create_rag_report -生成Markdown报告
• list_search_results -列出缓存会话

索引：

• rebuild_index -重建文档索引
• cancel_index_generation -取消索引
• index_status -检查索引状态

管理层：

• reload_config -重新加载.env配置
• open_index_manager -打开web UI
• reinitialize_schema -重置工作区(⚠️ 破坏性）

有关详细参数和示例，请参阅 docs/mcp-tools.md.

______________________________________________________________________

索引管理

基于Web的界面，用于监控索引进度和管理知识库。在localhost:3456（或下一个可用端口）上作为独立进程运行。

访问权限： 对克劳德说“打开指数管理器”或使用 open_index_manager 工具

特征： 实时进度跟踪、项目统计、索引操作（更新/重建/取消）

日志： /tmp/local-knowledge-rag-mcp/{workspaceId}/index-manager.log

______________________________________________________________________

故障排除

文档未被编入索引

1. 检查日志： /tmp/local-knowledge-rag-mcp/{workspaceId}/index-manager.log
2. 验证 .env 配置（DATABASE_URL、API密钥）
3. 检查文件模式： RAG_INCLUDE_PATTERNS 和 RAG_EXCLUDE_PATTERNS

没有搜索结果

• 尝试不同的搜索词或降低相似性阈值
• 验证索引是否已完成：使用 index_status 工具
• 如果需要，重建索引

API错误

• 验证API密钥是否有效并具有正确的权限
• 检查速率限制（必要时切换到Ollama）

切换嵌入模型

1. 编辑 .env 使用新的模型设置
2. 跑 reload_config 工具
3. 跑 rebuild_index 随着 reindex_all: true

有关完整的故障排除指南，请参阅 docs/故障排除.md.

______________________________________________________________________

安全

API密钥管理

• 永远不要提交API密钥 到版本控制
• 使用 .env 本地文件和 .env.example 在存储库中
• 定期旋转按键
• 尽可能使用特定于环境的密钥

网络安全

• 索引管理器（Web UI）：绑定到 127.0.0.1:3456 （仅环回）无身份验证

- 默认情况下，无法从外部网络访问 - 仅适用于受信任的本地开发环境

本地数据处理

• 默认情况下，所有文档都在本地处理
• 嵌入内容存储在PostgreSQL数据库中
• 进度日志存储在系统临时目录中
• 确保适当的数据库访问控制和备份
• 应只允许来自受信任网络的数据库连接

最佳实践

• 审查 .gitignore 确保敏感文件被排除在外
• 对于敏感数据，考虑使用Ollama进行完全离线、本地处理
• 定期轮换API键，并监控API的使用情况以发现异常模式

______________________________________________________________________

贡献

欢迎投稿！请参阅 贡献.md 作为指导方针。

注： 该项目在有限的时间内进行维护。公关审查可能需要几周时间。安全问题被优先考虑。

______________________________________________________________________

许可证

MIT许可证-请参阅 许可证 了解详情。

______________________________________________________________________

学分

• 黑曜石智能作曲器 -原始RAG实施
• 模型上下文协议（MCP）
• 克劳德代码