MCP开发框架

一个强大的MCP（Model Context Protocol）开发框架，用于创建与大语言模型交互的自定义工具。该框架提供了一套完整的工具集，可以轻松地扩展Cursor IDE的功能，实现网页内容获取、文件处理（PDF、Word、Excel、CSV、Markdown）以及AI对话等高级功能。它具有强大的MCP工具扩展能力，使开发者能够快速构建和集成各种自定义工具。

最新版本现在支持在PDF和Word文档处理中，直接返回原始图片内容并进行OCR识别，使大语言模型能够同时理解文档中的文本和图像内容：

• 图片内容直接显示：文档中的图表、图像等可以直接在对话中显示，无需额外工具

• OCR文本识别：自动提取图片中的文字内容，支持中英文多语言

• 图片内容理解：大模型可以"看到"文档中的图片，并基于图片内容进行分析和回答

• 完整文档内容返回：真正实现文档的全内容理解，包括文本、表格和图像

这使得AI模型能够更全面地理解和分析文档内容，特别是对于包含图表、表单、流程图或其他可视化信息的文档尤为有价值。

主要功能

本框架提供了以下核心功能：

1. 综合文件处理

使用parse_file工具可以自动识别文件类型并选择合适的处理方式，支持PDF、Word、Excel、CSV和Markdown文件。

• 用法: parse_file /path/to/document

• 支持格式:

  • PDF文件 (.pdf)

  • Word文档 (.doc, .docx)

  • Excel文件 (.xls, .xlsx, .xlsm)

  • CSV文件 (.csv)

  • Markdown文件 (.md)

• 参数: file_path - 文件的本地路径

• 返回: 根据文件类型返回相应的处理结果

2. PDF文档处理

使用parse_pdf工具可以处理PDF文档，支持两种处理模式：

• 用法: parse_pdf /path/to/document.pdf [mode]

• 参数:

  • file_path - PDF文件的本地路径

  • mode - 处理模式（可选）：

    • quick - 快速预览模式，仅提取文本内容

    • full - 完整解析模式，提取文本、图片内容和OCR文本（默认）

• 返回:

  • 快速预览模式：文档的文本内容

  • 完整解析模式：文档的文本内容、原始图片和OCR识别结果

3. Word文档解析

使用parse_word工具可以解析Word文档，提取文本、表格和图片信息。

• 用法: parse_word /path/to/document.docx

• 功能: 解析Word文档并提取文本内容、表格和图片

• 参数: file_path - Word文档的本地路径

• 返回: 文档的文本内容、表格和原始图片

• 特点: 同时提供文档内嵌图像的显示和分析功能

4. Excel文件处理

使用parse_excel工具可以解析Excel文件，提供完整的表格数据和结构信息。

• 用法: parse_excel /path/to/spreadsheet.xlsx

• 功能: 解析Excel文件的所有工作表

• 参数: file_path - Excel文件的本地路径

• 返回:

  • 文件基本信息（文件名、工作表数量）

  • 每个工作表的详细信息：

    • 行数和列数

    • 列名列表

    • 完整的表格数据

• 特点:

  • 使用pandas和openpyxl提供高质量的表格数据处理

  • 支持多工作表处理

  • 自动处理数据类型转换

5. CSV文件处理

使用parse_csv工具可以解析CSV文件，提供完整的数据分析和预览功能。

• 用法: parse_csv /path/to/data.csv

• 功能: 解析CSV文件并提供数据分析

• 参数:

  • file_path - CSV文件的本地路径

  • encoding - 文件编码格式（可选，默认自动检测）

• 返回:

  • 文件基本信息（文件名、行数、列数）

  • 列名列表

  • 数据预览（前5行）

  • 描述性统计信息

• 特点:

  • 自动编码检测

  • 支持多种编码格式（UTF-8、GBK等）

  • 提供数据统计分析

  • 智能数据类型处理

6. Markdown文件解析

使用parse_markdown工具可以解析Markdown文件，提取文本内容、标题结构和列表等信息。

• 用法: parse_markdown /path/to/document.md

• 功能: 解析Markdown文件并提取标题结构、列表和文本内容

• 参数: file_path - Markdown文件的本地路径

• 返回:

  • 文件基本信息（文件名、大小、修改时间等）

  • 标题结构层级展示

  • 内容元素统计（代码块、列表、链接、图片、表格等）

  • 原始Markdown内容

• 特点:

  • 自动识别各级标题和结构

  • 智能统计内容元素

  • 完整的标题层级展示

7. 网页内容获取

使用url工具可以获取任何网页的内容。

• 用法: url https://example.com

• 参数: url - 要获取内容的网站URL

• 返回: 网页的文本内容

• 特点:

  • 完整的HTTP错误处理

  • 超时管理

  • 自动编码处理

8. MaxKB AI对话

使用maxkb工具可以与MaxKB API进行交互，实现智能对话功能。

• 用法: maxkb "您的问题或指令"

• 功能: 发送消息到MaxKB API并获取AI回复

• 参数:

  • message - 要发送的消息内容（必需）

  • re_chat - 是否重新开始对话（可选，默认false）

  • stream - 是否使用流式响应（可选，默认true）

• 返回: AI的回复内容

• 特点:

  • 支持流式响应

  • 自动重试机制

  • 完整的错误处理

  • 60秒超时保护

  • 保持连接配置优化

技术特点

本框架采用了多种技术来优化文件处理性能：

1. 智能文件类型识别

   • 自动根据文件扩展名选择合适的处理工具

   • 提供统一的文件处理接口

2. 高效的文档处理

   • PDF处理：支持快速预览和完整解析两种模式

   • Word处理：精确提取文本、表格和图片

   • Excel处理：高效处理大型表格数据

3. 强大的MCP工具扩展能力

   • 插件化架构设计，易于扩展

   • 统一的工具注册和调用接口

   • 支持同步和异步工具开发

   • 丰富的工具开发API和辅助函数

4. 内存优化

   • 使用临时文件管理大型文件

   • 自动清理临时资源

   • 分块处理大型文档

5. 错误处理

   • 完整的异常捕获和处理

   • 详细的错误信息反馈

   • 优雅的失败处理机制

项目结构

本框架采用模块化设计，便于扩展和维护：

开发指南

如何开发新工具

1. 在tools目录下创建一个新的Python文件，如your_tool.py

2. 导入必要的依赖和基类

3. 创建一个继承自BaseTool的工具类

4. 使用@ToolRegistry.register装饰器注册工具

5. 实现工具的execute方法

工具模板示例

部署指南

环境变量配置

在.env文件中配置以下环境变量：

本地目录挂载

框架支持将本地目录挂载到容器中，以便工具可以访问本地文件。配置方法：

1. 在.env文件中设置HOST_MOUNT_SOURCE和HOST_MOUNT_TARGET环境变量

2. HOST_MOUNT_SOURCE是你本地机器上的目录路径

3. HOST_MOUNT_TARGET是容器内的挂载路径（默认为/host_files）

使用工具时，可以直接引用本地文件路径，框架会自动将其转换为容器内的路径。例如：

这样，你就可以在不修改工具代码的情况下，轻松访问本地文件。

Docker部署（推荐）

1. 初始设置：

2. 使用Docker Compose：

3. 访问服务：

   • SSE端点: http://localhost:8000/sse

4. Cursor IDE配置：

• 设置 → 功能 → 添加MCP服务器

• 类型: "sse"

• URL: http://localhost:8000/sse?token=<your-token> (替换 <your-token> 为您的 JWT Token)

鉴权配置

SSE 服务现在支持 API 鉴权机制，每个请求都需要携带有效的认证信息：

1. 配置鉴权服务地址：

   • 在 .env 文件中设置 MCP_AUTH_URL 环境变量（默认为 http://170.106.105.206:4000/users 该鉴权地址仅供测试，不保证长期稳定，建议使用以下项目自行部署）

2. 客户端配置：

   • 在 Cursor 插件中配置时，需要在 URL 中添加 token 查询参数

   • 格式为 http://your-server:8000/sse?token=<your-token>

   • 服务器会自动将 token 转换为 Bearer <your-token> 格式发送到鉴权服务

3. 鉴权流程：

   • 当 SSE 服务收到请求时，会从 URL 中提取 token 参数

   • 然后向配置的鉴权地址发送请求，并传递 Authorization: Bearer <your-token> 头

   • 只有鉴权成功（返回 200 状态码）的请求才会被处理

   • 鉴权失败的请求会收到 401 Unauthorized 响应

4. 推荐JWT鉴权服务：

   • 我们推荐使用Jason Watmore的Node.js JWT鉴权服务作为参考实现

   • 详细文档和示例代码：https://jasonwatmore.com/nodejs-jwt-authentication-tutorial-with-example-api

   • 该实现提供了完整的用户注册、登录、令牌生成和验证功能

   • 可以无缝集成到本框架的鉴权流程中

部署方式

传统Python部署

1. 安装系统依赖：

2. 安装Python依赖：

3. 启动服务：

依赖项

主要依赖：

• mcp: Model Context Protocol实现

• PyMuPDF: PDF文档处理

• python-docx: Word文档处理

• pandas和openpyxl: Excel文件处理

• httpx: 异步HTTP客户端

• anyio: 异步I/O支持

• click: 命令行接口

贡献指南

1. Fork仓库

2. 创建功能分支 (git checkout -b feature/amazing-feature)

3. 提交更改 (git commit -m 'Add some amazing feature')

4. 推送到分支 (git push origin feature/amazing-feature)

5. 打开Pull Request

许可证

本项目采用MIT许可证 - 详情请参阅LICENSE文件。