Markdown Rag MCP

Markdown RAG MCP服务器

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

📚 其他MCP资源： - Atlassian Rovo MCP服务器设置指南 -了解如何通过MCP连接到Atlassian（Jira、Confluence） 🎥 在这里找到演示： - 棕色包课程1-RAG入职演示

特性

• 📄 摄取和索引降价文件
• 🔍 基于向量嵌入的语义搜索
• 🤖 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重新启动

1. 验证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  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 
 

例子：

# 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 

______________________________________________________________________

将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.

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

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

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

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

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

1. 出现问题时手动移除容器：如果 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

______________________________________________________________________

配置

环境变量

可以配置以下环境变量：

常量（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集成

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

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

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

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

1. 摄入管道 (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系统将从您的文档中检索相关上下文

______________________________________________________________________

编码愉快！ 🎉