# MCP 协议集成

> MCP（Model Context Protocol）端点、能力声明与工具调用机制，使 AI Agent 能直接调用 ddddocr 识别服务

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

## Source Files

- `ddddocr/api/mcp.py`
- `ddddocr/api/models.py`
- `ddddocr/api/server.py`

---

<details>
<summary>相关源文件</summary>
以下文件用于生成此维基页面：
- [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/routes.py](ddddocr/api/routes.py)
- [ddddocr/api/__init__.py](ddddocr/api/__init__.py)
</details>

# MCP 协议集成

本文档说明 ddddocr 如何通过 MCP（Model Context Protocol）端点暴露其 OCR、目标检测和滑块匹配能力，使外部 AI Agent 能以标准化工具调用方式直接使用 ddddocr 服务，无需自行管理模型生命周期。

## 协议概览

ddddocr 的 MCP 集成基于 FastAPI 实现，采用自定义的 JSON-RPC 风格协议，而非官方 MCP SDK。协议通过三个 HTTP 端点运作：能力声明、工具调用和协议信息查询。所有 MCP 端点挂载在 `/mcp` 路径前缀下，与 RESTful API 共存于同一 FastAPI 应用。

Sources: [ddddocr/api/mcp.py:1-228](), [ddddocr/api/server.py:193-195]()

## 端点说明

### `GET /mcp` — 协议信息

返回 MCP 协议的元信息，包括协议名称、版本和可用端点路径。

```json
{
  "protocol": "MCP",
  "version": "1.6.1",
  "description": "DDDDOCR MCP协议支持",
  "endpoints": {
    "capabilities": "/mcp/capabilities",
    "call": "/mcp/call"
  }
}
```

Sources: [ddddocr/api/mcp.py:216-227]()

### `GET /mcp/capabilities` — 能力声明

返回 `MCPCapabilities` 对象，声明该服务暴露的全部工具。每个工具包含 `name`、`description` 和 `inputSchema`（JSON Schema 格式），AI Agent 可据此了解可调用的功能及其参数。

当前声明的工具共 6 个：

| 工具名 | 说明 | 必填参数 |
|--------|------|----------|
| `ddddocr_initialize` | 初始化服务，选择加载的模型类型 | 无（全部可选） |
| `ddddocr_ocr` | 执行 OCR 文字识别 | `image`（base64） |
| `ddddocr_detection` | 执行目标检测 | `image`（base64） |
| `ddddocr_slide_match` | 滑块边缘匹配算法 | `target_image`, `background_image` |
| `ddddocr_slide_comparison` | 滑块图像差异比较 | `target_image`, `background_image` |
| `ddddocr_status` | 获取服务状态 | 无 |

Sources: [ddddocr/api/mcp.py:28-118]()

### `POST /mcp/call` — 工具调用

接收 `MCPRequest`（含 `method`、`params`、`id`），根据 `method` 字段分发到对应处理逻辑，返回 `MCPResponse`。

## 请求与响应模型

MCP 协议使用三个 Pydantic 模型：

```python
class MCPRequest(BaseModel):
    method: str          # 工具名，如 "ddddocr_ocr"
    params: Dict[str, Any]  # 工具参数
    id: Optional[Union[str, int]]  # 请求关联 ID

class MCPResponse(BaseModel):
    result: Optional[Any]          # 成功时的结果
    error: Optional[Dict[str, Any]]  # 失败时的错误 {code, message, data}
    id: Optional[Union[str, int]]  # 与请求对应的 ID

class MCPCapabilities(BaseModel):
    tools: List[Dict[str, Any]]       # 工具声明列表
    resources: List[Dict[str, Any]]   # 资源列表（当前为空）
    prompts: List[Dict[str, Any]]     # 提示列表（当前为空）
```

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

## 调用流程

以下序列图展示 AI Agent 通过 MCP 协议调用 OCR 识别的典型流程：

```mermaid
sequenceDiagram
    participant Agent as AI Agent
    participant MCP as MCPHandler
    participant Service as DDDDOCRService
    participant Core as ddddocr.DdddOcr

    Agent->>MCP: GET /mcp/capabilities
    MCP-->>Agent: 返回工具声明列表

    Agent->>MCP: POST /mcp/call {method: "ddddocr_initialize", params: {ocr: true}}
    MCP->>Service: service.initialize(config)
    Service->>Core: DdddOcr(ocr=True, ...)
    Core-->>Service: 实例就绪
    Service-->>MCP: {loaded_models: ["ocr", "slide"], message: "..."}
    MCP-->>Agent: MCPResponse {result: ...}

    Agent->>MCP: POST /mcp/call {method: "ddddocr_ocr", params: {image: "<base64>"}}
    MCP->>MCP: base64.b64decode(image)
    MCP->>Core: ocr_instance.classification(image_data)
    Core-->>MCP: "识别文本"
    MCP-->>Agent: MCPResponse {result: "识别文本"}
```

Sources: [ddddocr/api/mcp.py:120-214](), [ddddocr/api/server.py:22-80]()

## 服务架构

```text
FastAPI 应用 (create_app)
├── RESTful 路由 (routes.py)
│   ├── POST /initialize
│   ├── POST /ocr
│   ├── POST /detect
│   ├── POST /slide-match
│   └── GET  /status
│
└── MCP 路由 (/mcp 前缀, mcp.py)
    ├── GET  /mcp           → 协议信息
    ├── GET  /mcp/capabilities → 工具声明
    └── POST /mcp/call      → 工具分发
```

`MCPHandler` 在 `server.py:194` 中被实例化并注入同一个 `DDDDDOCRService` 服务实例。RESTful API 和 MCP 协议共享同一个 OCR/检测/滑块实例池，因此通过 MCP 初始化后，RESTful 端点也能使用已加载的模型，反之亦然。

Sources: [ddddocr/api/server.py:170-197](), [ddddocr/api/server.py:22-30]()

## 错误处理

MCP 工具调用采用统一的错误响应格式。当 `method` 对应的服务实例未初始化时，返回 HTTP 400；当遇到未知方法名时，同样返回 400。所有其他异常被捕获并封装为：

```json
{
  "error": {
    "code": -1,
    "message": "错误描述",
    "data": null
  }
}
```

与 RESTful API 不同，MCP 端点的错误不抛出 HTTP 异常，而是通过 `MCPResponse.error` 字段返回，保持了 JSON-RPC 风格的一致性。

Sources: [ddddocr/api/mcp.py:206-214]()

## 图像数据传输

所有涉及图像的工具（OCR、检测、滑块）均使用 **base64 编码** 传输图像数据。`image`、`target_image`、`background_image` 参数均为 base64 字符串，MCPHandler 在分发前调用 `base64.b64decode()` 解码为原始字节再传递给 ddddocr 核心。

Sources: [ddddocr/api/mcp.py:140-141](), [ddddocr/api/mcp.py:163-164](), [ddddocr/api/mcp.py:176-177]()

## 与 RESTful API 的对比

| 特性 | RESTful API (`/ocr`, `/det` 等) | MCP 协议 (`/mcp/call`) |
|------|----------------------------------|------------------------|
| 协议风格 | REST + JSON | JSON-RPC 风格 |
| 能力发现 | 无（需阅读文档） | `GET /mcp/capabilities` 自动声明 |
| 错误格式 | HTTP 状态码 + `APIResponse` | `MCPResponse.error` 字段 |
| 文件上传 | 支持（`/ocr/file`） | 不支持（仅 base64） |
| Agent 友好度 | 需手写调用代码 | 标准化工具声明，适合 Agent 自动发现和调用 |
| 实例管理 | 按需创建、自动清理 | 通过 `ddddocr_initialize` 显式初始化 |

Sources: [ddddocr/api/routes.py:52-68](), [ddddocr/api/mcp.py:120-214](), [ddddocr/api/app.py:239-281]()

## 使用示例

AI Agent 典型调用序列：

```bash
# 1. 查询可用工具
curl http://localhost:8000/mcp/capabilities

# 2. 初始化 OCR 服务
curl -X POST http://localhost:8000/mcp/call \
  -H "Content-Type: application/json" \
  -d '{"method": "ddddocr_initialize", "params": {"ocr": true}, "id": 1}'

# 3. 执行 OCR 识别
curl -X POST http://localhost:8000/mcp/call \
  -H "Content-Type: application/json" \
  -d '{"method": "ddddocr_ocr", "params": {"image": "<base64_encoded_image>"}, "id": 2}'

# 4. 查询服务状态
curl -X POST http://localhost:8000/mcp/call \
  -H "Content-Type: application/json" \
  -d '{"method": "ddddocr_status", "params": {}, "id": 3}'
```

## 服务启动

通过 `python -m ddddocr.api` 或直接调用 `run_server()` 启动时，MCP 端点随 FastAPI 应用自动挂载：

```
DDDDOCR API服务启动在 http://0.0.0.0:8000
MCP协议地址: http://0.0.0.0:8000/mcp
```

Sources: [ddddocr/api/server.py:200-206](), [ddddocr/api/__main__.py:1-10]()

## 总结

ddddocr 的 MCP 集成提供了一条标准化路径，使 AI Agent 无需了解 ddddocr 的 Python API 细节，即可通过 JSON-RPC 风格的 HTTP 调用完成 OCR 识别、目标检测和滑块匹配。协议实现简洁——一个 `MCPHandler` 类承载了能力声明、请求分发和错误处理的全部逻辑，通过 FastAPI Router 挂载到主应用，与 RESTful API 共享同一服务实例池。