# HTTP API 与 MCP 协议服务

> 通过 FastAPI 暴露 REST 接口，或通过 MCP 协议让 AI Agent 直接调用 ddddocr 能力。

- Repository: sml2h3/ddddocr
- GitHub: https://github.com/sml2h3/ddddocr
- Human wiki: https://grok-wiki.com/public/wiki/sml2h3-ddddocr-a34dd45d9f63
- Complete Markdown: https://grok-wiki.com/public/wiki/sml2h3-ddddocr-a34dd45d9f63/llms-full.txt

## Source Files

- `ddddocr/api/app.py`
- `ddddocr/api/routes.py`
- `ddddocr/api/mcp.py`
- `ddddocr/api/models.py`
- `ddddocr/api/server.py`
- `ddddocr/__main__.py`

---

<details>
<summary>相关源文件</summary>
以下文件用于生成此维基页面：
- [ddddocr/api/app.py](ddddocr/api/app.py)
- [ddddocr/api/routes.py](ddddocr/api/routes.py)
- [ddddocr/api/mcp.py](ddddocr/api/mcp.py)
- [ddddocr/api/models.py](ddddocr/api/models.py)
- [ddddocr/api/server.py](ddddocr/api/server.py)
- [ddddocr/api/__init__.py](ddddocr/api/__init__.py)
- [ddddocr/__main__.py](ddddocr/__main__.py)
</details>

# HTTP API 与 MCP 协议服务

ddddocr 提供两种方式让外部程序调用其验证码识别能力：一是通过 **FastAPI** 暴露的标准 REST API，二是通过 **MCP（Model Context Protocol）** 协议让 AI Agent 直接发现和调用工具。本页面介绍这两套服务的架构、接口和启动方式。

## 架构概览

项目中存在 **两套并行的 API 实现**，它们共享同一版本号（1.6.1），但设计思路不同：

| 实现 | 入口文件 | 特点 |
|------|----------|------|
| 直接模式 | `ddddocr/api/app.py` | 单文件内联所有路由，按配置键缓存多个 `DdddOcr` 实例，无需预初始化即可使用 |
| 服务模式 | `ddddocr/api/server.py` + `routes.py` + `mcp.py` | 分层架构：`DDDDDOCRService` 管理实例生命周期，路由工厂注册端点，`MCPHandler` 提供 MCP 协议支持 |

两种模式都通过 `ddddocr/api/__init__.py` 导出，最终由 `ddddocr/__main__.py` 的 `api` 子命令统一启动。

Sources: [ddddocr/api/__init__.py:1-14](), [ddddocr/__main__.py:52-69]()

## 启动方式

### 命令行启动

```bash
# 使用默认配置启动（0.0.0.0:8000）
python -m ddddocr api

# 自定义主机和端口
python -m ddddocr api --host 127.0.0.1 --port 9000

# 启用 GPU 加速和目标检测
python -m ddddocr api --use-gpu true --det true --device-id 0

# 使用旧版 OCR 模型
python -m ddddocr api --old true
```

CLI 会将所有参数写入环境变量（如 `DDDDOCR_HOST`、`DDDDOCR_PORT`），然后调用 `ddddocr.api.main()` 启动 uvicorn 服务器。

Sources: [ddddocr/__main__.py:18-69](), [ddddocr/api/app.py:743-754]()

### 环境变量配置

| 环境变量 | 默认值 | 说明 |
|----------|--------|------|
| `DDDDOCR_HOST` | `0.0.0.0` | 服务监听地址 |
| `DDDDOCR_PORT` | `8000` | 服务监听端口 |
| `DDDDOCR_WORKERS` | `1` | uvicorn 工作进程数 |
| `DDDDOCR_OCR` | `true` | 是否启用 OCR |
| `DDDDOCR_DET` | `false` | 是否启用目标检测 |
| `DDDDOCR_OLD` | `false` | 是否使用旧版模型 |
| `DDDDOCR_BETA` | `false` | 是否使用 Beta 模型 |
| `DDDDOCR_USE_GPU` | `false` | 是否使用 GPU |
| `DDDDOCR_DEVICE_ID` | `0` | GPU 设备 ID |
| `DDDDOCR_SHOW_AD` | `true` | 是否显示广告 |
| `DDDDOCR_IMPORT_ONNX_PATH` | `""` | 自定义 ONNX 模型路径 |
| `DDDDOCR_CHARSETS_PATH` | `""` | 自定义字符集路径 |

Sources: [ddddocr/api/app.py:319-328](), [ddddocr/__main__.py:54-65]()

## REST API 端点（直接模式）

直接模式（`app.py`）提供以下端点，启动后即可直接调用，无需预初始化：

### 健康检查与配置

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/health` | 健康检查，返回 `{"status": "ok"}` |
| `GET` | `/config` | 获取当前默认配置、活跃实例数和环境信息 |

### OCR 文字识别

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/ocr` | JSON 方式提交 Base64 图片进行 OCR |
| `POST` | `/ocr/file` | 文件上传方式进行 OCR |

请求体示例（JSON 方式）：

```json
{
  "image": "<base64编码的图片>",
  "probability": false,
  "colors": [],
  "custom_color_ranges": null
}
```

OCR 端点支持通过查询参数动态选择模型配置：

```
POST /ocr?ocr=true&det=false&old=false&beta=false&use_gpu=false&device_id=0&show_ad=true
```

系统会根据这些参数自动生成配置键（如 `ocr=true-det=false-old=false-beta=false-gpu=false-dev=0`），并缓存对应的 `DdddOcr` 实例以供复用。空闲超过 3600 秒的实例会被自动清理。

Sources: [ddddocr/api/app.py:335-404](), [ddddocr/api/app.py:239-298]()

### 目标检测

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/det` | JSON 方式提交图片进行目标检测 |
| `POST` | `/det/file` | 文件上传方式进行目标检测 |

返回检测到的边界框坐标列表。

Sources: [ddddocr/api/app.py:500-589]()

### 滑块验证码

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/slide_match` | 滑块匹配：根据滑块图和背景图计算偏移位置 |
| `POST` | `/slide_comparison` | 滑块比较：对比带坑位图片和完整背景图的差异 |

`slide_match` 请求体：

```json
{
  "target_image": "<base64>",
  "background_image": "<base64>",
  "simple_target": false,
  "flag": false
}
```

Sources: [ddddocr/api/app.py:592-676]()

### 字符集配置

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/set_charset_range` | 设置 OCR 识别的字符范围 |

Sources: [ddddocr/api/app.py:680-718]()

## REST API 端点（服务模式）

服务模式（`server.py` + `routes.py`）提供了更结构化的接口，需要先调用 `/initialize` 进行初始化：

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/` | 首页，包含 API 文档链接 |
| `POST` | `/initialize` | 初始化服务，选择加载的模型类型 |
| `POST` | `/switch-model` | 运行时切换模型（支持 `ocr`、`ocr_old`、`ocr_beta`、`det`） |
| `POST` | `/toggle-feature` | 开启/关闭特定功能（`ocr`、`detection`、`color_filter`） |
| `POST` | `/ocr` | 执行 OCR 识别 |
| `POST` | `/detect` | 执行目标检测 |
| `POST` | `/slide-match` | 滑块匹配 |
| `POST` | `/slide-comparison` | 滑块比较 |
| `GET` | `/status` | 获取服务状态（已加载模型、已启用功能、运行时间） |
| `GET` | `/health` | 健康检查 |

服务模式的核心是 `DDDDDOCRService` 类，它管理三个独立的实例（`ocr_instance`、`det_instance`、`slide_instance`），并通过 `enabled_features` 集合控制功能开关。

Sources: [ddddocr/api/server.py:22-153](), [ddddocr/api/routes.py:17-219]()

## MCP 协议服务

MCP（Model Context Protocol）是一种让 AI Agent 发现和调用外部工具的协议。ddddocr 的 MCP 实现位于 `ddddocr/api/mcp.py`，挂载在 `/mcp` 前缀下。

### 端点

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/mcp/` | 协议信息（版本、端点描述） |
| `GET` | `/mcp/capabilities` | 能力声明，返回可用工具列表及参数 schema |
| `POST` | `/mcp/call` | 调用指定工具 |

### 可用工具

AI Agent 通过 `/mcp/capabilities` 获取工具列表，然后通过 `/mcp/call` 调用：

| 工具名 | 功能 | 必需参数 |
|--------|------|----------|
| `ddddocr_initialize` | 初始化服务 | 无（可选 `ocr`、`det`、`old`、`beta`、`use_gpu`） |
| `ddddocr_ocr` | OCR 文字识别 | `image`（Base64） |
| `ddddocr_detection` | 目标检测 | `image`（Base64） |
| `ddddocr_slide_match` | 滑块匹配 | `target_image`、`background_image`（Base64） |
| `ddddocr_slide_comparison` | 滑块比较 | `target_image`、`background_image`（Base64） |
| `ddddocr_status` | 获取服务状态 | 无 |

### 调用示例

```json
// 请求：调用 OCR 工具
POST /mcp/call
{
  "method": "ddddocr_ocr",
  "params": {
    "image": "<base64编码的图片>",
    "probability": false
  },
  "id": "req-001"
}

// 响应
{
  "result": "识别结果文本",
  "error": null,
  "id": "req-001"
}
```

MCP 处理器内部会将 `method` 字段路由到对应的处理逻辑，复用 `DDDDDOCRService` 的实例管理能力。错误统一通过 `error` 字段返回，包含 `code`、`message` 和 `data`。

Sources: [ddddocr/api/mcp.py:17-227](), [ddddocr/api/models.py:97-117]()

## 数据模型

所有请求/响应模型均使用 Pydantic 定义，同时服务于 REST 和 MCP 两种协议：

| 模型 | 用途 |
|------|------|
| `InitializeRequest` | 服务初始化参数 |
| `SwitchModelRequest` | 模型切换参数 |
| `ToggleFeatureRequest` | 功能开关参数 |
| `OCRRequest` | OCR 识别请求 |
| `DetectionRequest` | 目标检测请求 |
| `SlideMatchRequest` | 滑块匹配请求 |
| `SlideComparisonRequest` | 滑块比较请求 |
| `APIResponse` | 统一 API 响应（`success` + `message` + `data`） |
| `StatusResponse` | 服务状态响应 |
| `MCPRequest` | MCP 工具调用请求（`method` + `params` + `id`） |
| `MCPResponse` | MCP 工具调用响应（`result` 或 `error`） |
| `MCPCapabilities` | MCP 能力声明（`tools` 列表） |

Sources: [ddddocr/api/models.py:1-117]()

## API 文档

FastAPI 自动生成交互式 API 文档，启动后可访问：

- **Swagger UI**：`http://<host>:<port>/docs`
- **ReDoc**：`http://<host>:<port>/redoc`

CORS 中间件默认允许所有来源的跨域请求（`allow_origins=["*"]`）。

Sources: [ddddocr/api/app.py:301-316](), [ddddocr/api/server.py:170-198]()

## 总结

ddddocr 的 HTTP API 与 MCP 服务设计了两条路径来暴露相同的底层能力：REST API 适合传统的 Web 应用和自动化脚本集成，MCP 协议则让 AI Agent 能够自主发现和调用 OCR、目标检测、滑块匹配等工具。两套 API 实现（直接模式和服务模式）共存于 `ddddocr/api` 模块中，通过 `__main__.py` 的 `api` 子命令统一启动，用户可根据需求选择适合的调用方式。