MCP框架

Name: MCP框架
Author: aigo666

作者：aigo66615 星标更新：2025-05-15

安装使用来源：spider==github.com

项目介绍

MCP 开发框架

一个强大的MCP（模型上下文协议）开发框架，用于创建与大型语言模型交互的自定义工具。该框架提供了一整套工具，可以轻松扩展光标IDE的功能，支持高级功能如网页内容检索、文件处理（PDF、Word、Excel、CSV、Markdown）以及AI对话。它具有强大的MCP工具扩展能力，使开发者能够快速构建和集成各种自定义工具。

<a href="https://glama.ai/mcp/servers/@aigo666/mcp-framework"> <img width="380" height="200" src="https://gips2.baidu.com/it/u=3872302720,1309051052&fm=3081&app=3081&f=PNG?w=760&h=400" /> </a> <details> <summary>🔥 最新特性：文档图片内容显示与理解</summary>

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

直接显示图像内容 文档中的图表、图像等可以直接在对话中显示，无需额外工具。
OCR文本识别 自动从图像中提取文本内容，支持中文和英文等多种语言。
理解图像内容 大型模型可以“看到”文档中的图像，并根据图像内容进行分析和回答。
完整文档内容返回 实现对文档内容的全面理解，包括文本、表格和图像。

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

</details>

主要功能

<details> <summary>点击展开查看框架提供的核心功能</summary>

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

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 - 文件编码格式（可选，默认自动检测）
返回：
- 文件的基本信息（文件名、行数、列数）
- 列名列表
- 数据预览（前五行）
- 描述性统计信息
特性：
- 自动编码检测
- 支持多种编码格式（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秒超时保护
- 维护连接配置优化

</details>

技术特点

此框架采用各种技术以优化文件处理性能：

智能文件类型识别
- 根据文件扩展名自动选择适当的处理工具
- 提供统一的文件处理接口
高效的文档处理
- PDF处理：支持快速预览和完整解析两种模式
- Word处理：准确提取文本、表格和图像
- Excel处理：高效处理大量表格数据
强大的MCP工具扩展能力
- 插件架构设计，易于扩展
- 统一的工具注册和调用接口
- 支持同步和异步工具开发
- 丰富的工具开发API和辅助功能
内存优化
- 使用临时文件管理大文件
- 自动清理临时资源
- 大文档分块处理
错误处理
- 完整的异常捕获和处理
- 详细的错误消息反馈
- 优雅的失败处理机制

项目结构

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

mcp_tool/
├── tools/
│   ├── __init__.py        # 定义工具基类和注册器
│   ├── loader.py          # 工具加载器，自动加载所有工具
│   ├── file_tool.py       # 综合文件处理工具
│   ├── pdf_tool.py        # PDF解析工具
│   ├── word_tool.py       # Word文档解析工具
│   ├── excel_tool.py      # Excel文件处理工具
│   ├── csv_tool.py        # CSV文件处理工具
│   ├── markdown_tool.py   # Markdown文件解析工具
│   ├── url_tool.py        # URL工具实现
│   └── maxkb_tool.py      # MaxKB AI对话工具
├── __init__.py
├── __main__.py
└── server.py              # MCP服务器实现

开发指南

如何开发新工具

在tools目录下创建一个新的Python文件，例如your_tool.py
导入必要的依赖项和基类
创建一个继承自BaseTool的工具类别
使用@ToolRegistry.register装饰器注册工具
实现工具的execute方法

工具模板示例

import mcp.types as types
from . import BaseTool, ToolRegistry

@ToolRegistry.register
class YourTool(BaseTool):
    """您的工具描述"""
    name = "your_tool_name"  # 工具的唯一标识符
    description = "您的工具描述"  # 工具的描述信息，将显示给用户
    input_schema = {
        "type": "object",
        "required": ["param1"],  # 必需的参数
        "properties": {
            "param1": {
                "type": "string",
                "description": "参数1的描述",
            },
            "param2": {
                "type": "integer",
                "description": "参数2的描述（可选）",
            }
        },
    }
  
    async def execute(self, arguments: dict) -> list[types.TextContent | types.ImageContent | types.EmbeddedResource]:
        """执行工具逻辑"""
        # 参数验证
        if "param1" not in arguments:
            return [types.TextContent(
                type="text",
                text="Error: Missing required argument 'param1'"
            )]
          
        # 获取参数
        param1 = arguments["param1"]
        param2 = arguments.get("param2", 0)  # 获取可选参数，提供默认值
      
        # 执行工具逻辑
        result = f"处理参数: {param1}, {param2}"
      
        # 返回结果
        return [types.TextContent(
            type="text",
            text=result
        )]

部署指南

环境变量配置

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

# 服务器配置
MCP_SERVER_PORT=8000        # 服务器端口
MCP_SERVER_HOST=0.0.0.0     # 服务器主机

# 鉴权配置
MCP_AUTH_URL=http://170.106.105.206:4000/users  # 鉴权服务地址

# MaxKB配置
MAXKB_HOST=http://host.docker.internal:8080  # MaxKB API主机地址
MAXKB_CHAT_ID=your_chat_id_here              # MaxKB聊天ID
MAXKB_APPLICATION_ID=your_application_id_here # MaxKB应用ID
MAXKB_AUTHORIZATION=your_authorization_key    # MaxKB授权密钥

# 调试模式
DEBUG=false                 # 是否启用调试模式

# 用户代理
MCP_USER_AGENT="MCP Test Server (github.com/modelcontextprotocol/python-sdk)"

# 本地目录挂载配置
HOST_MOUNT_SOURCE=/path/to/your/local/directory  # 本地目录路径
HOST_MOUNT_TARGET=/host_files                    # 容器内挂载路径

本地目录挂载

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

在.env文件中设置HOST_MOUNT_SOURCE和HOST_MOUNT_TARGET环境变量
HOST_MOUNT_SOURCE是您本地机器上的目录路径
HOST_MOUNT_TARGET是容器内的挂载路径（默认为）/host_files）

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

# 使用PDF工具处理本地文件
pdf "/Users/username/Documents/example.pdf"

# 框架会自动将路径转换为容器内路径
# 例如："/host_files/example.pdf"

这样，您可以轻松访问本地文件而无需修改工具代码。

Docker部署（推荐）

初始设置：

# 克隆仓库
git clone https://github.com/aigo666/mcp-framework.git
cd mcp-framework

# 创建环境文件
cp .env.example .env

使用Docker Compose：

# 构建并启动
docker compose up --build -d

# 查看日志
docker compose logs -f

# 管理容器
docker compose ps
docker compose pause
docker compose unpause
docker compose down

访问服务：
- SSE端点：http://localhost:8000/sse
Cursor IDE配置：

设置 → 函数 → 添加MCP服务器
类型："sse"
URL：http://localhost:8000/sse?token=<your-token>（替换）<your-token>为您的JWT Token

鉴权配置

<details> <summary>点击展开查看详细的鉴权配置信息</summary>

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

配置认证服务地址：
- 在.env文件中设置MCP_AUTH_URL环境变量（默认为）http://170.106.105.206:4000/users此认证地址仅供测试使用，不保证长期稳定性。建议使用以下项目进行自行部署
客户端配置：
- 在配置Cursor插件时，需要在URL中添加token查询参数
- 格式为http://your-server:8000/sse?token=<your-token>
- 服务器会自动将token转换为Bearer <your-token>格式发送给认证服务
认证过程：
- 当SSE服务接收到请求时，从URL中提取token参数
- 然后向配置的认证地址发送请求，并传递Authorization: Bearer <your-token>头部
- 只有认证成功的请求（返回状态码200）才会被处理
- 认证失败的请求将收到401 Unauthorized响应
推荐JWT认证服务：
- 我们推荐使用Jason Watmore的Node.js JWT认证服务作为参考实现
- 详细文档和示例代码：https://jasonwatmore.com/nodejs-jwt-authentication-tutorial-with-example-api
- 此实现提供了完整的用户注册、登录、生成和验证令牌功能
- 可以无缝集成到此框架的认证过程中

</details>

部署方法

传统Python部署

安装系统依赖：

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y poppler-utils tesseract-ocr tesseract-ocr-chi-sim

# macOS
brew install poppler tesseract tesseract-lang

# Windows
# 1. 下载并安装Tesseract: https://github.com/UB-Mannheim/tesseract/wiki
# 2. 将Tesseract添加到系统PATH

安装Python依赖：

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
.\venv\Scripts\activate  # Windows

# 安装依赖
pip install -r requirements.txt

启动服务：

python -m mcp_tool

依赖项

主要依赖项：

mcp - 模型上下文协议的实现
PyMuPDF - PDF文档处理
python-docx - Word文档处理
pandas 和 openpyxl - Excel文件处理
httpx - 异步HTTP客户端
anyio - 异步I/O支持
click - 命令行界面

贡献指南

分叉仓库
创建功能分支（git checkout -b feature/amazing-feature）
提交更改（git commit -m 'Add some amazing feature'）
推送到分支（git push origin feature/amazing-feature）
打开Pull Request

许可证

本项目采用MIT许可证 - 请参阅详细信息许可证文档。