README.md•14.4 kB
# MCP开发框架
[](https://mseep.ai/app/34780cde-ee17-4a7b-b9ee-356f41fc9e77) [](https://smithery.ai/server/@aigo666/mcp-framework)
一个强大的MCP(Model Context Protocol)开发框架,用于创建与大语言模型交互的自定义工具。该框架提供了一套完整的工具集,可以轻松地扩展Cursor 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://glama.ai/mcp/servers/@aigo666/mcp-framework/badge" />
</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` - 文件编码格式(可选,默认自动检测)
- **返回**:
- 文件基本信息(文件名、行数、列数)
- 列名列表
- 数据预览(前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秒超时保护
- 保持连接配置优化
</details>
## 技术特点
本框架采用了多种技术来优化文件处理性能:
1. **智能文件类型识别**
- 自动根据文件扩展名选择合适的处理工具
- 提供统一的文件处理接口
2. **高效的文档处理**
- PDF处理:支持快速预览和完整解析两种模式
- Word处理:精确提取文本、表格和图片
- Excel处理:高效处理大型表格数据
3. **强大的MCP工具扩展能力**
- 插件化架构设计,易于扩展
- 统一的工具注册和调用接口
- 支持同步和异步工具开发
- 丰富的工具开发API和辅助函数
4. **内存优化**
- 使用临时文件管理大型文件
- 自动清理临时资源
- 分块处理大型文档
5. **错误处理**
- 完整的异常捕获和处理
- 详细的错误信息反馈
- 优雅的失败处理机制
## 项目结构
本框架采用模块化设计,便于扩展和维护:
```
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服务器实现
```
## 开发指南
### 如何开发新工具
1. 在`tools`目录下创建一个新的Python文件,如`your_tool.py`
2. 导入必要的依赖和基类
3. 创建一个继承自`BaseTool`的工具类
4. 使用`@ToolRegistry.register`装饰器注册工具
5. 实现工具的`execute`方法
### 工具模板示例
```python
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`文件中配置以下环境变量:
```bash
# Server Configuration
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 # 容器内挂载路径
```
### 本地目录挂载
框架支持将本地目录挂载到容器中,以便工具可以访问本地文件。配置方法:
1. 在`.env`文件中设置`HOST_MOUNT_SOURCE`和`HOST_MOUNT_TARGET`环境变量
2. `HOST_MOUNT_SOURCE`是你本地机器上的目录路径
3. `HOST_MOUNT_TARGET`是容器内的挂载路径(默认为`/host_files`)
使用工具时,可以直接引用本地文件路径,框架会自动将其转换为容器内的路径。例如:
```
# 使用PDF工具处理本地文件
pdf "/Users/username/Documents/example.pdf"
# 框架会自动将路径转换为容器内路径
# 例如:"/host_files/example.pdf"
```
这样,你就可以在不修改工具代码的情况下,轻松访问本地文件。
### Docker部署(推荐)
1. 初始设置:
```bash
# 克隆仓库
git clone https://github.com/aigo666/mcp-framework.git
cd mcp-framework
# 创建环境文件
cp .env.example .env
```
2. 使用Docker Compose:
```bash
# 构建并启动
docker compose up --build -d
# 查看日志
docker compose logs -f
# 管理容器
docker compose ps
docker compose pause
docker compose unpause
docker compose down
```
3. 访问服务:
- SSE端点: http://localhost:8000/sse
4. Cursor IDE配置:
- 设置 → 功能 → 添加MCP服务器
- 类型: "sse"
- URL: `http://localhost:8000/sse?token=<your-token>` (替换 `<your-token>` 为您的 JWT Token)
## 鉴权配置
<details>
<summary>点击展开查看详细的鉴权配置信息</summary>
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
- 该实现提供了完整的用户注册、登录、令牌生成和验证功能
- 可以无缝集成到本框架的鉴权流程中
</details>
## 部署方式
### 传统Python部署
1. 安装系统依赖:
```bash
# 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
```
2. 安装Python依赖:
```bash
# 创建虚拟环境
python -m venv venv
source venv/bin/activate # Linux/Mac
# 或
.\venv\Scripts\activate # Windows
# 安装依赖
pip install -r requirements.txt
```
3. 启动服务:
```bash
python -m mcp_tool
```
## 依赖项
主要依赖:
- `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](LICENSE)文件。