# MCP Hand Detection

一个基于 MediaPipe 的 Model Context Protocol (MCP) 服务器，提供手掌检测功能。

## 功能特性

- ✅ 基于 MediaPipe 的高精度手掌检测
- ✅ 符合 MCP 标准协议（JSON-RPC 2.0）
- ✅ 支持 stdio 和 HTTP 两种接口
- ✅ 易于集成到支持 MCP 的客户端（如 Cursor、Claude Desktop）
- ✅ 包含预训练模型，开箱即用

## 安装

```bash
pip install mcp-hand-detection
```

如果需要 HTTP API 功能：

```bash
pip install mcp-hand-detection[http]
```

## 快速开始

### 作为 MCP 服务器使用

在 MCP 客户端配置中添加：

```json
{
  "mcpServers": {
    "hand-detection": {
      "command": "mcp-hand-detection"
    }
  }
}
```

### 作为命令行工具使用

```bash
# 启动 MCP 服务器（通过 stdio）
mcp-hand-detection

# 启动 HTTP 服务器
mcp-hand-detection-http --port 8080
```

### 作为 Python 库使用

```python
from mcp_hand_detection import MCPServer

# 创建服务器实例
server = MCPServer()

# 检测手掌
result = server._detect_hand("/path/to/image.jpg")
print(result)
```

### HTTP API 使用示例

```python
from mcp_hand_detection import create_app

app = create_app()
app.run(host='0.0.0.0', port=8080)
```

或者使用命令行：

```bash
mcp-hand-detection-http --host 0.0.0.0 --port 8080
```

然后通过 HTTP 调用：

```bash
# 文件上传
curl -X POST http://localhost:8080/api/detect -F "image=@hand.jpg"

# Base64 编码
curl -X POST http://localhost:8080/api/detect \
  -H "Content-Type: application/json" \
  -d '{"image_base64": "...", "image_format": "jpg"}'
```

## API 文档

### MCP 工具

- **工具名称**: `detect_hand`
- **描述**: 检测图片中是否存在手掌
- **参数**:
  - `image_path` (string, 必需): 图片文件路径
- **返回**: JSON 格式的检测结果

### HTTP API

- `GET /health` - 健康检查
- `GET /api/tools` - 获取工具列表
- `POST /api/detect` - 检测手掌
  - 支持文件上传 (`multipart/form-data`)
  - 支持 Base64 编码 (`application/json`)

## 系统要求

- Python 3.9+
- OpenCV
- MediaPipe 0.10+
- NumPy

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！

## 链接

- [GitHub Repository](https://github.com/yourusername/mcp-hand-detection)
- [PyPI Package](https://pypi.org/project/mcp-hand-detection/)

