AI导哈

Markdown文档RAG服务器

一个基于检索增强生成（RAG）技术的Markdown文档处理服务器，提供语义搜索和文档管理功能，支持与Cursor IDE集成。

  • by SowmeshSharma0
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 SowmeshSharma0/markdown-rag-mcp

使用说明

Markdown RAG MCP服务器

一种模型上下文协议（MCP）服务器，为markdown文档提供RAG（检索增强生成）功能。该服务器使用Qdrant进行矢量存储，Ollama进行嵌入，并与Cursor IDE无缝集成。

📚 其他MCP资源：

🎥 在这里找到演示：

特性

  • 📄 摄取和索引降价文件
  • 🔍 基于向量嵌入的语义搜索
  • 🤖 Ollama驱动的嵌入（nomic嵌入文本）
  • 💾 Qdrant矢量数据库用于高效检索
  • 🔌 MCP协议与Cursor IDE的集成
  • 🐳 基于Docker的设置，易于部署

先决条件（全新笔记本电脑设置）

1.安装Homebrew（macOS软件包管理器）

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安装后，按照屏幕上的说明将Homebrew添加到PATH中。

2.按照仓库中的说明安装pnpm和node：https://github.com/Sixt/com.sixt.web.public/edit/master/README.md

3.安装Rancher桌面

  1. 下载Rancher Desktop for Mac（英特尔或硅-M系列芯片）：https://rancherdesktop.io/
  2. 安装应用程序
  3. 打开Rancher桌面
  4. 在Rancher桌面首选项中：
    • 选择 容器运行时间：dockerd（moby） （用于Docker API兼容性）
    • 应用设置并等待Rancher重新启动
  5. 验证Docker是否正在运行：
docker --version
docker-compose --version

5.安装Git（如果尚未安装）

brew install git

6.安装Cursor IDE

  1. 从以下位置下载游标：https://cursor.com/download
  2. 安装应用程序
  3. 打开的游标

项目设置

1.克隆或下载项目

cd ~/Desktop/Workspace
# If using git:
git clone <your-repo-url> markdown-rag-mcp
cd markdown-rag-mcp

# Or if you already have the folder, just navigate to it:
cd markdown-rag-mcp

2.安装项目依赖项

pnpm install

这将安装所有必需的软件包，包括：

  • @modelcontextprotocol/sdk -MCP-SDK
  • @qdrant/js-client-rest -Qdrant客户端
  • ollama -Ollama客户
  • express -HTTP服务器
  • 以及其他依赖关系

3.启动Docker服务

pnpm run docker:up

或

pnpm run docker:reset

此命令将：

  • 启动Qdrant矢量数据库（在端口6333、6334上）
  • 启动Ollama嵌入服务（在端口11434上）

⏳ 等待1-2分钟 以便初始化服务。

4.设置Olama模型

Docker服务运行后，拉取并设置嵌入模型：

pnpm run docker:setup-model

这将下载 nomic-embed-text 型号（2GB）。以下情况之后需要执行此步骤：

  • 首次设置
  • 跑步 pnpm run docker:reset
  • 跑步 pnpm run docker:up 在清新的环境中

💡 ProTip： 在运行此命令之前，请禁用Cato VPN或任何公司VPN。不要担心最后的错误。

5.验证Docker服务是否正在运行

# Check Qdrant is running
pnpm run docker:check-qdrant

# Check Ollama is running
pnpm run docker:check-ollama

# View logs if needed
pnpm run docker:logs

6.构建TypeScript项目

pnpm run build

这将TypeScript代码编译为JavaScript dist/ 文件夹。

7.摄入样本文件-您想对其提问

如果您有markdown文件要摄取：

pnpm run ingest add <pathName> <repoName>

例子：

# Ingest a single markdown file
pnpm run ingest add ./sampleInputs/web_README.md com.sixt.web.public

# Or with a relative path
pnpm run ingest add path/to/your/document.md com.sixt.web.public

要删除文档，请执行以下操作：

pnpm run ingest delete <filename>

将MCP服务器连接到游标

1.找到Cursor的MCP配置文件

使用Cursor的设置：

  1. 打开的游标
  2. 按 Cmd + Shift + P （命令面板）
  3. 键入“首选项：打开用户设置（JSON）”
  4. 查找MCP配置部分

2.添加MCP服务器配置

将此配置添加到您的 mcp.json file（如果不存在，则创建它）：

{
  "mcpServers": {
    "markdown-rag": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

注： 此配置假定：

  • MCP服务器在端口3000上运行（默认）
  • Docker服务（Qdrant和Ollama）已经在运行

3.启动MCP服务器

在连接Cursor之前，请确保启动MCP服务器：

# Make sure Docker services are running first
pnpm run docker:up
pnpm run docker:setup-model

# Build and start the MCP server
pnpm run build
pnpm start

服务器将在以下时间运行 http://localhost:3000/mcp 并且在使用Cursor时必须保持运行。

4.验证MCP连接

在Cursor中，您现在应该可以访问MCP工具。您可以通过以下方式进行验证：

  1. 打开光标聊天/AI面板
  2. markdown rag服务器应出现在可用的MCP服务器列表中
  3. 您应该可以使用以下工具：
    • ingest_markdown：摄取降价文件
    • search：搜索摄入的文档
    • list_documents：列出所有摄入的文件
    • delete_document：删除特定文档

⚠️ 重要提示

  1. 端口配置：仅在必要时更改默认端口（3000、6333、11434）。如果这样做，请更新两者 docker-compose.yml 和 mcp.json.

  2. 禁用VPN：首次下载模型或启动Docker服务时，请关闭Cato VPN或企业VPN。

  3. 先验证容器：在使用MCP之前，始终检查容器是否正在运行： docker ps

  4. 使用绝对路径：In mcp.json，使用完整路径，如 /Users/you/path/to/dist/index.js，而不是相对路径。

  5. 更改后重建：运行 pnpm run build 代码更改后。如果你修改 docker-compose.yml，使用以下命令重新启动容器 pnpm run docker:restart。然后完全重新启动Cursor（Cmd+Q）。

  6. 在第一次设置时要有耐心：初始设置需要3-5分钟才能下载图像和模型。不要打断。

  7. 出现问题时手动移除容器：如果 pnpm docker:down / pnpm docker:reset 如果无法按预期工作，请转到牧场主，停止并手动删除容器。

使用MCP服务器

摄取Markdown文档

您可以使用MCP工具通过Cursor的AI聊天或通过命令行摄取markdown文件：

pnpm run ingest

服务器将：

  1. 解析markdown文件
  2. 将它们拆分为语义块
  3. 使用Olama生成嵌入
  4. 将它们存储在Qdrant矢量数据库中

搜索文档

使用Cursor的AI聊天功能搜索您的文档。MCP服务器将：

  1. 使用Ollama将查询转换为嵌入
  2. 搜索Qdrant矢量数据库
  3. 返回包含元数据的相关文档块

游标用法示例

You: "Search for documentation about API authentication"

MCP服务器将从您摄入的markdown文档中检索相关块。

可用命令

Docker管理

# Start services
pnpm run docker:up

# Stop services
pnpm run docker:down

# View all logs
pnpm run docker:logs

# View Qdrant logs only
pnpm run docker:logs:qdrant

# View Ollama logs only
pnpm run docker:logs:ollama

# Restart services
pnpm run docker:restart

# Check Ollama models
pnpm run docker:list-models

# Setup Ollama model manually
pnpm run docker:setup-model

# Complete reset (removes all data)
pnpm run docker:clean

# Clean and restart
pnpm run docker:reset

发展

# Install dependencies
pnpm install

# Build TypeScript
pnpm run build

# Start MCP server
pnpm start

# Build and start
pnpm run dev

# Ingest documents
pnpm run ingest

# Run tests
pnpm test

项目结构

markdown-rag-mcp/
├── src/
│   ├── index.ts           # MCP server entry point
│   ├── server.ts          # MCP server implementation
│   ├── ingest.ts          # Document ingestion logic
│   ├── constants.ts       # Configuration constants
│   └── services/
│       ├── embeddings.ts  # Ollama embedding service
│       └── qdrant.ts      # Qdrant vector store service
├── dist/                  # Compiled JavaScript output
├── sampleInputs/          # Sample markdown files
├── qdrant_data/           # Qdrant database storage
├── ollama_data/           # Ollama models storage
├── docker-compose.yml     # Docker services configuration
├── tsconfig.json          # TypeScript configuration
├── package.json           # Node.js dependencies
└── README.md             # This file

配置

环境变量

可以配置以下环境变量：

变量 默认值 描述
PORT 3000 MCP服务器端口
QDRANT_URL http://localhost:6333 Qdrant数据库URL
OLLAMA_URL http://localhost:11434 Ollama服务URL

常量（src/constrations.ts）

  • COLLECTION_NAME：Qdrant集合名称(markdown_docs)
  • EMBEDDING_DIMENSIONS：矢量维度(768 用于nomic嵌入文本）
  • DEFAULT_CHUNK_SIZE：文档块大小(1000 字符）
  • DEFAULT_SEARCH_LIMIT：搜索结果数量(5)
  • DEFAULT_EMBEDDING_MODEL：Olama模型(nomic-embed-text)

故障排除

Docker容器无法启动

# Check Docker Desktop is running
docker ps

# Check logs for errors
pnpm run docker:logs

# Try resetting
pnpm run docker:down
pnpm run docker:up

Olama型号不可用

# Manually pull the model
pnpm run docker:setup-model

# Check if model is loaded
pnpm run docker:list-models

# Check Ollama logs
pnpm run docker:logs:ollama

MCP服务器未在Cursor中连接

  1. 验证服务器构建是否成功： pnpm run build
  2. 检查路径 mcp.json 正确（使用绝对路径）
  3. 确保Docker服务正在运行： pnpm run docker:up
  4. 检查服务器日志是否有错误
  5. 完全重新启动游标(Cmd + Q，然后重新打开）

系统要求

  • 操作系统： macOS（Linux/Windows，稍作调整）
  • 猛撞： 最低8GB（建议使用16GB以获得更好的性能）
  • 磁盘空间： 5GB用于Docker镜像和模型
  • Node.js： v18或更高版本
  • Docker： 最新版本
  • 互联网： 初始模型下载需要

建筑

组件

  1. MCP服务器 (src/server.ts)

    • 实现模型上下文协议
    • 公开文档管理和搜索工具
    • 作为HTTP服务器运行，用于Cursor集成

  2. 嵌入服务 (src/services/embeddings.ts)

    • 与Ollama的接口
    • 使用nomic嵌入文本生成768个维度嵌入

  3. 向量存储 (src/services/qdrant.ts)

    • 管理Qdrant矢量数据库
    • 处理文档存储和检索
    • 执行语义相似性搜索

  4. 摄入管道 (src/ingest.ts)

    • 解析markdown文档
    • 将文本分块以实现最佳检索
    • 生成并存储嵌入

数据流

Markdown Files
    ↓
Ingestion Pipeline
    ↓
Text Chunking
    ↓
Ollama Embeddings (nomic-embed-text)
    ↓
Qdrant Vector Store
    ↓
MCP Server ←→ Cursor IDE
    ↓
Semantic Search Results

MCP工具

服务器公开了以下MCP工具：

ingest add

将降价文档引入矢量数据库。

参数：

  • content （string）：要摄取的Markdown内容
  • metadata （object）：可选元数据（标题、来源等）

search_knowledge

使用语义相似性搜索摄入的文档。

参数：

  • query （string）：搜索查询
  • limit （数字，可选）：结果数量（默认值：5）

退货： 带有分数和元数据的相关文档块数组

ingest delete

从矢量数据库中删除特定文档。

参数：

  • documentId （string）：要删除的文档的ID

贡献

欢迎投稿！请遵循以下指南：

  1. 分叉存储库
  2. 创建要素分支
  3. 进行更改
  4. 彻底测试
  5. 提交拉取请求

许可证

ISC许可证

支持

对于问题、疑问或贡献：

  • 在存储库中创建问题
  • 检查现有文档
  • 查看故障排除部分

后续步骤

  1. ✅ 完成上述设置步骤
  2. 📄 将您的markdown文档添加到文件夹中
  3. 🔧 使用MCP ingest_markdown 通过Cursor为文档建立索引的工具
  4. 💬 通过Cursor的AI聊天询问有关文档的问题
  5. 🚀 RAG系统将从您的文档中检索相关上下文

编码愉快！ 🎉

相关 MCP