Metadata-Version: 2.4
Name: scnet-document-parser
Version: 0.4.0
Summary: Local stdio MCP server for SCNet document OCR parsing (path-based upload)
Project-URL: Homepage, https://github.com/sugon/mcp-document-parsing-py
Project-URL: Repository, https://github.com/sugon/mcp-document-parsing-py
Author: Sugon
License: MIT
Keywords: document-parser,mcp,ocr,scnet,stdio
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=2.0.0
Description-Content-Type: text/markdown

# SCNet Document Parser (Python / stdio MCP)

本地 **stdio** MCP 服务，封装 SCNet 文档 OCR 能力。  
相对 Java SSE 版的关键差异：`upload_file` 接收**本机文件路径**，由进程直接读盘上传，**不再把文件 base64 塞进工具参数**。

定位：**个人 Agent 的小文档高精度解析**（公式 / 印章 / 表格等）。大文件请走 SCNet 或长文档 HTTP API。

## 特性

| 工具 | 说明 |
|------|------|
| `upload_file` | 传入本地路径 → 体量校验 → presign + OSS multipart → 返回 `file_url` |
| `submit_parse` | 用 `file_url` / 外网直链提交 OCR，返回 `task_id`；固定 `ocrType/source/channelTag`，可选页码与表格/方向/印章/行内公式开关 |
| `get_parse_task_status` | 单次查状态，不阻塞、不下载结果（推荐轮询） |
| `get_parse_result` | 取结果；**默认 `format=agent`**；`max_wait_seconds=0` 非阻塞 |

推荐流程（多步轮询，避免长时间阻塞）：

```
upload_file(path) → file_url
submit_parse(file_url, page_index?, is_table_cls?, ...) → task_id
轮询 get_parse_task_status 直到 result_ready
get_parse_result(task_id)                 # 默认 agent：markdown + capabilities + highlights
# 可选：format=markdown | blocks | full
```

`submit_parse` 请求体会固定带上 `ocrType=DOC_PARING`、`source=mcp`、`channelTag=mcp`（与 `file_url` 同级）。可选：

| 参数 | 类型 | 说明 |
|------|------|------|
| `page_index` | string | `'2'` 表示 0–2；`'0-2'` / `'1-3'` 指定区间 |
| `is_table_cls` | bool | 表格细分（有线/无线） |
| `is_doc_ori` | bool | 文档方向矫正 |
| `enforce_seal` | bool | 强制二次印章检测（请求字段 `enfoceSeal`） |
| `is_inline_formula` | bool | 行内公式检测 |

### `format` 说明

| format | 含义 |
|--------|------|
| **`agent`（默认）** | 聚合 markdown + 能力计数（公式/印章/表格/图片/图表）+ highlights |
| `markdown` | 仅 markdown 聚合（可截断） |
| `blocks` | 简化块列表（type/text/bbox） |
| `full` | 原始 documents/datas，**体积可能很大**，仅二次处理时显式使用 |

## 环境要求

- Python 3.10+
- [uv](https://docs.astral.sh/uv/)（推荐，用于 `uvx` 一键运行）
- SCNet API Key

## 用 uvx 运行（推荐）

### 1）本地开发（未发布到 PyPI 时）

```bash
cd /Users/haojie/workspace/project/mcp-document-parsing-py
uv sync
SCNET_API_KEY=sk-xxx uv run scnet-document-parser
```

### 2）发布到 PyPI 之后

```bash
uvx scnet-document-parser
# 或固定版本
uvx scnet-document-parser==0.4.0
```

## MCP 客户端配置

### Claude Code / Claude Desktop

```json
{
  "mcpServers": {
    "scnet-document-parser": {
      "command": "uvx",
      "args": ["scnet-document-parser"],
      "env": {
        "SCNET_API_KEY": "sk-your-key"
      }
    }
  }
}
```

本地未发布时可将 `args` 改为：

```json
"args": ["--from", "/path/to/mcp-document-parsing-py", "scnet-document-parser"]
```

### 可选环境变量

| 变量 | 默认 / 硬顶 | 说明 |
|------|-------------|------|
| `SCNET_API_KEY` | **必填** | SCNet Key（可带或不带 `Bearer ` 前缀） |
| `SCNET_BASE_URL` | `https://api.scnet.cn` | API 根地址（presign / 查状态 / 下载等） |
| `SCNET_SUBMIT_OCR_URL` | 未设置 → `{base_url}/api/llm/v1/ocrdoc/submit` | **仅**覆盖 `submit_parse` 的请求地址；可写绝对 URL 或相对 path |
| `SCNET_POLL_INTERVAL_MS` | `3000` | 显式轮询间隔 |
| `SCNET_MAX_EXPLICIT_WAIT_SECONDS` | `30` | 正数 `max_wait_seconds` 上限 |
| `SCNET_RESULT_DOWNLOAD_TIMEOUT_MS` | `30000` | 结果 JSON 下载超时 |
| `SCNET_MAX_PDF_FILE_SIZE` | 硬顶 15 MiB | 可调低，不可突破硬顶 |
| `SCNET_MAX_WORD_FILE_SIZE` | 硬顶 10 MiB | 同上 |
| `SCNET_MAX_PPT_FILE_SIZE` | 硬顶 10 MiB | 同上 |
| `SCNET_MAX_EXCEL_FILE_SIZE` | 硬顶 5 MiB | 同上 |
| `SCNET_MAX_IMAGE_FILE_SIZE` | 硬顶 10 MiB | 同上 |
| `SCNET_MAX_MARKDOWN_CHARS` | `100000` | agent/markdown 截断 |
| `SCNET_HIGHLIGHT_PER_TYPE` | `5` | 每类 highlight 上限 |
| `SCNET_HIGHLIGHT_MAX` | `20` | highlight 总上限 |

> 环境变量大于硬顶时会被 **clamp 到硬顶** 并打 warning。

## 支持的文件类型

与 `ai-sugon-long-document-parsing` 的 `FileType` / `TaskController.submit` 对齐：

| 类别 | 扩展名 | MCP 硬顶 |
|------|--------|----------|
| PDF | `.pdf` | **15 MiB** |
| Word | `.doc` `.docx` | **10 MiB** |
| PPT | `.ppt` `.pptx` | **10 MiB** |
| Excel | `.xls` `.xlsx` `.csv` `.xlsm` `.xlsb` | **5 MiB** |
| 图片 | `.jpg` `.jpeg` `.png` `.bmp` `.tiff` `.tif` `.webp` | **10 MiB** |

超限会拒绝上传并提示走 HTTP API。

## 与 Java SSE 版对比

| | Java `mcp-document-parsing` | 本项目 (Python stdio) |
|--|------------------------------|------------------------|
| 传输 | HTTP/SSE 远程服务 | stdio 本地子进程 |
| 安装 | 起 Spring Boot 服务 | `uvx` / `uv run` |
| 鉴权 | 每个 HTTP 请求 `Authorization` | 环境变量 `SCNET_API_KEY` |
| 上传 | `byte[]`（客户端常 base64） | **本地路径直接读文件** |
| 默认结果 | full 结构 | **agent 视图** |
| 适用 | 团队共享中台 | 个人 Agent 读本机**小**文档 |

业务链路一致：presign → OSS multipart → submit → query → 下载结果 → agent/full/markdown/blocks。

## 开发

```bash
cd /Users/haojie/workspace/project/mcp-document-parsing-py
uv sync --group dev
uv run pytest
```

## 发布到 PyPI（供他人 uvx）

```bash
uv build
uv publish
```

包名：`scnet-document-parser`  
控制台入口：`scnet-document-parser` → `scnet_document_parser.server:main`
