# WJHMCPService

**Repository Path**: agent-project/wjhmcpservice

## Basic Information

- **Project Name**: WJHMCPService
- **Description**: MCP服务
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-02
- **Last Updated**: 2026-03-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MCP (Model Context Protocol) AI 工具服务

这是一个基于MCP协议的Python服务项目，为AI模型提供多种工具能力，包括图片处理、信息获取等功能，支持与AI模型（如LLM）进行工具交互。

## 项目特性

- **标准MCP协议支持** - 完全符合MCP 2024-11-05协议规范
- **多种工具支持** - 支持图片处理、视频流处理、信息获取等多种工具功能
- **FastMCP 2.11.0** - 使用最新的FastMCP框架
- **双传输模式** - 支持 stdio 和 HTTP 两种传输模式
- **异步处理** - 基于asyncio的高性能异步处理
- **详细日志** - 完整的请求处理和错误日志记录
- **模块化架构** - 工具方法与服务器启动逻辑分离，便于维护和扩展

## 项目结构

```
mcpDemo03/
├── README.md              # 项目说明文档
├── requirements.txt       # Python依赖包
├── start_mcp.py          # MCP服务器启动脚本（核心）
├── config.py             # 配置文件
├── start_linux.sh        # Linux启动脚本（虚拟环境）

├── venv/                 # 虚拟环境目录（自动创建）
└── utils/
    ├── mcp_tools.py      # MCP工具模块
    ├── imgToBase64.py    # 图片处理工具模块
    ├── image_bbox.py     # 图片标框工具模块
    ├── videoToImg.py     # 视频流转图片工具模块
    └── minio_upload.py   # MinIO文件上传工具模块

```

## 快速开始



### 1. 安装依赖

#### 方式一：虚拟环境安装（推荐）
```bash
# Linux系统
chmod +x start_linux.sh
./start_linux.sh install

# Windows系统
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
```

#### 方式二：全局安装
```bash
pip install -r requirements.txt
```

### 2. 启动服务

#### Windows/Linux 通用方式
```bash
# HTTP 传输模式（推荐）
python start_mcp.py

# 或 stdio 传输模式
python start_mcp.py --transport stdio
```

#### Linux 专用启动脚本（虚拟环境）
```bash
# 给脚本执行权限
chmod +x start_linux.sh

# 安装依赖（自动创建虚拟环境）
./start_linux.sh install

# 启动服务（默认端口9000）
./start_linux.sh

# 后台启动服务（默认端口9000）
./start_linux.sh background

# 停止服务
./start_linux.sh stop

# 查看服务状态
./start_linux.sh status

# 查看所有实例状态
./start_linux.sh all-status
```

#### 多实例支持（解决端口冲突）

**问题**: 同一套代码在不同目录使用不同端口时，启动一个实例会停止另一个实例。

**原因**: 原脚本使用 `pgrep -f "start_mcp.py"` 查找所有相关进程，会停止所有实例。

**解决方案**: 新版本脚本支持多实例独立运行：

```bash
# 实例1：使用端口9000
cd /path/to/instance1
MCP_PORT=9000 ./start_linux.sh background

# 实例2：使用端口9004  
cd /path/to/instance2
MCP_PORT=9004 ./start_linux.sh background

# 查看所有实例状态
./start_linux.sh all-status

# 停止特定实例
cd /path/to/instance1
MCP_PORT=9000 ./start_linux.sh stop

cd /path/to/instance2
MCP_PORT=9004 ./start_linux.sh stop
```

**特性**:
- 每个实例使用独立的PID文件和日志文件
- 实例ID格式：`目录名_端口号`
- 支持通过环境变量 `MCP_PORT` 指定端口
- 进程查找基于端口号，避免误杀其他实例

## 配置说明

### 服务配置
- **默认地址**: `http://0.0.0.0:9000`
- **健康检查**: `http://localhost:9000/health`
- **API端点**: `/tools/*`

### 环境变量
```bash
# 创建环境变量文件
cat > .env << EOF
DEBUG=False
LOG_LEVEL=INFO
HTTP_HOST=0.0.0.0
HTTP_PORT=9000
HTTP_WORKERS=4
EOF
```

## 功能特性

### MCP工具

#### 1. convert_image_to_base64
将网络图片URL转换为base64编码

**参数**:
- `url` (必需): 图片的URL地址
- `format` (可选): 图片格式，支持 jpeg、png、gif、webp

#### 2. extract_video_frame_to_base64
从视频流地址提取第一帧并转换为base64编码

**参数**:
- `stream_url` (必需): 视频流地址
- `timeout` (可选): 连接超时时间（秒），默认10秒

#### 3. get_image_info
获取网络图片的基本信息

**参数**:
- `url` (必需): 图片的URL地址

#### 4. draw_image_bbox
在图片上绘制边界框

**参数**:
- `bbox` (必需): 边界框数据列表，每个元素包含:
  - `conf` (float): 置信度
  - `class` (str): 目标标签（英文，如：person, car, dog等）
  - `coordinate` (list): [x1, y1, x2, y2] 左上右下坐标
- `image` (必需): base64编码的图片数据

**返回**:
- `bbox` (list): 原始边界框数据
- `imageBbox` (str): 标框后的base64图片数据

#### 5. draw_image_bbox_url
从网络图片URL下载图片并在其上绘制边界框

**参数**:
- `bbox` (必需): 边界框数据列表，每个元素包含:
  - `conf` (float): 置信度
  - `class` (str): 目标标签（英文，如：person, car, dog等）
  - `coordinate` (list): [x1, y1, x2, y2] 左上右下坐标
- `image_url` (必需): 网络图片的URL地址
- `timeout` (可选): 网络请求超时时间（秒），默认30秒

**返回**:
- `bbox` (list): 原始边界框数据
- `imageBbox` (str): 标框后的base64图片数据
- `original_url` (str): 原始图片URL

**特性**:
- 支持HTTP/HTTPS图片URL
- 图片文件大小限制为10MB
- 自动检测图片格式
- 标签文字显示为英文，如 "person 0.67"、"car 0.85" 等

#### 6. upload_file_to_minio
上传本地文件到MinIO对象存储

**参数**:
- `file_path` (必需): 要上传的本地文件路径
- `bucket_name` (必需): MinIO存储桶名称
- `object_name` (可选): 对象名称（文件在MinIO中的路径），如果为None则使用原文件名
- `endpoint` (可选): MinIO服务器地址，默认"localhost:9000"
- `access_key` (可选): MinIO访问密钥，默认"minioadmin"
- `secret_key` (可选): MinIO秘密密钥，默认"minioadmin"
- `secure` (可选): 是否使用HTTPS连接，默认True
- `max_file_size` (可选): 最大文件大小（字节），默认100MB

**返回**:
- `success` (bool): 是否成功
- `message` (str): 详细的状态信息
- `file_url` (str): 文件的完整访问URL
- `bucket_name` (str): 存储桶名称
- `object_name` (str): 对象名称
- `file_size` (int): 文件大小（字节）
- `content_type` (str): 文件MIME类型
- `upload_time` (str): 上传时间

#### 7. upload_url_to_minio
从URL下载并上传文件到MinIO对象存储

**参数**:
- `url` (必需): 要下载的文件URL地址
- `bucket_name` (必需): MinIO存储桶名称
- `object_name` (可选): 对象名称（文件在MinIO中的路径），如果为None则使用原文件名
- `endpoint` (可选): MinIO服务器地址，默认"localhost:9000"
- `access_key` (可选): MinIO访问密钥，默认"minioadmin"
- `secret_key` (可选): MinIO秘密密钥，默认"minioadmin"
- `secure` (可选): 是否使用HTTPS连接，默认True
- `timeout` (可选): 下载超时时间（秒），默认30秒
- `max_file_size` (可选): 最大文件大小（字节），默认100MB

**返回**:
- `success` (bool): 是否成功
- `message` (str): 详细的状态信息
- `file_url` (str): 文件的完整访问URL
- `bucket_name` (str): 存储桶名称
- `object_name` (str): 对象名称
- `file_size` (int): 文件大小（字节）
- `content_type` (str): 文件MIME类型
- `upload_time` (str): 上传时间
- `source_url` (str): 原始URL

## 使用示例

### HTTP API调用
```bash
# 健康检查
curl http://localhost:9000/health

# 图片转换
curl -X POST http://localhost:9000/tools/convert_image_to_base64 \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/image.jpg"}'

# 视频帧提取
curl -X POST http://localhost:9000/tools/extract_video_frame_to_base64 \
  -H "Content-Type: application/json" \
  -d '{"stream_url": "rtsp://example.com/stream"}'

# 图片标框（base64图片）
curl -X POST http://localhost:9000/tools/draw_image_bbox \
  -H "Content-Type: application/json" \
  -d '{
    "bbox": [{"conf": 0.67, "class": "person", "coordinate": [1178, 535, 1245, 593]}],
    "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ..."
  }'

# 图片标框（网络URL）
curl -X POST http://localhost:9000/tools/draw_image_bbox_url \
  -H "Content-Type: application/json" \
  -d '{
    "bbox": [{"conf": 0.67, "class": "person", "coordinate": [1178, 535, 1245, 593]}],
    "image_url": "https://example.com/image.jpg"
  }'

# 上传本地文件到MinIO
curl -X POST http://localhost:9000/tools/upload_file_to_minio \
  -H "Content-Type: application/json" \
  -d '{
    "file_path": "/path/to/file.jpg",
    "bucket_name": "my-bucket",
    "endpoint": "minio.example.com:9000",
    "access_key": "my-access-key",
    "secret_key": "my-secret-key"
  }'

# 从URL上传文件到MinIO
curl -X POST http://localhost:9000/tools/upload_url_to_minio \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/file.jpg",
    "bucket_name": "my-bucket",
    "endpoint": "minio.example.com:9000",
    "access_key": "my-access-key",
    "secret_key": "my-secret-key"
  }'
```

### MCP协议集成
```json
{
  "name": "convert_image_to_base64",
  "arguments": {
    "url": "https://example.com/image.jpg",
    "format": "jpeg"
  }
}

{
  "name": "draw_image_bbox",
  "arguments": {
    "bbox": [{"conf": 0.67, "class": "person", "coordinate": [1178, 535, 1245, 593]}],
    "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ..."
  }
}

{
  "name": "draw_image_bbox_url",
  "arguments": {
    "bbox": [{"conf": 0.67, "class": "person", "coordinate": [1178, 535, 1245, 593]}],
    "image_url": "https://example.com/image.jpg"
  }
}

{
  "name": "upload_file_to_minio",
  "arguments": {
    "file_path": "/path/to/file.jpg",
    "bucket_name": "my-bucket",
    "endpoint": "minio.example.com:9000",
    "access_key": "my-access-key",
    "secret_key": "my-secret-key"
  }
}

{
  "name": "upload_url_to_minio",
  "arguments": {
    "url": "https://example.com/file.jpg",
    "bucket_name": "my-bucket",
    "endpoint": "minio.example.com:9000",
    "access_key": "my-access-key",
    "secret_key": "my-secret-key"
  }
}
```

## 故障排除

### 常见问题

1. **Python依赖问题**
   ```bash
   # 安装Python3、pip和venv模块
   sudo apt-get install python3 python3-pip python3-venv  # Ubuntu/Debian
   sudo yum install python3 python3-pip python3-venv      # CentOS/RHEL
   
   # 使用虚拟环境安装依赖（推荐）
   ./start_linux.sh install
   
   # 或手动安装
   python3 -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt
   ```

2. **端口被占用**
   ```bash
   # 检查端口使用情况
   netstat -tlnp | grep :9000
   
   # 停止占用端口的服务
   sudo lsof -ti:9000 | xargs kill -9
   ```

3. **权限问题**
   ```bash
   # 给脚本执行权限
   chmod +x start_linux.sh
   ```

4. **多实例冲突问题**
   ```bash
   # 问题：启动一个实例会停止另一个实例
   # 原因：原脚本会停止所有 start_mcp.py 进程
   
   # 解决方案：使用新版本脚本，支持多实例
   # 实例1
   cd /path/to/instance1
   MCP_PORT=9000 ./start_linux.sh background
   
   # 实例2
   cd /path/to/instance2  
   MCP_PORT=9004 ./start_linux.sh background
   
   # 查看所有实例
   ./start_linux.sh all-status
   ```

### 调试命令
```bash
# 查看服务状态
./start_linux.sh status

# 查看服务日志
tail -f logs/mcp_service.log

# 查看进程状态
ps aux | grep start_mcp.py

# 测试健康检查
curl http://localhost:9000/health


```



## 开发指南

### 添加新工具
在 `utils/mcp_tools.py` 文件中添加新的工具方法：

```python
@mcp_instance.tool()
def new_tool_function(param1: str, param2: int) -> Dict[str, Any]:
    """
    新工具的描述
    
    参数:
        param1 (str): 参数1描述
        param2 (int): 参数2描述
    
    返回:
        Dict[str, Any]: 返回结果描述
    """
    try:
        # 工具实现逻辑
        result = process_something(param1, param2)
        
        return {
            "success": True,
            "message": "操作成功",
            "data": result
        }
    except Exception as e:
        return {
            "success": False,
            "message": f"操作失败: {str(e)}",
            "error": str(e)
        }
```

## 版本信息

- **FastMCP**: 2.11.0
- **Python**: 3.11+
- **协议版本**: MCP 2024-11-05

---

**总结**: 本项目提供了简洁的MCP AI工具服务解决方案，支持基本的启动和管理功能。