Metadata-Version: 2.4
Name: scnet-document-parser
Version: 0.1.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 塞进工具参数**。

## 特性

| 工具 | 说明 |
|------|------|
| `upload_file` | 传入本地路径 → presign + OSS multipart 上传 → 返回 `file_url` |
| `submit_parse` | 用 `file_url` / 外网直链提交 OCR，返回 `task_id` |
| `get_parse_task_status` | 单次查状态，不阻塞、不下载结果 |
| `get_parse_result` | 取结果；`max_wait_seconds=0` 非阻塞，正数显式轮询（上限 30s） |

推荐流程：

```
upload_file(path) → file_url
submit_parse(file_url) → task_id
轮询 get_parse_task_status 直到 result_ready
get_parse_result(task_id, format="markdown", max_wait_seconds=0)
```

## 环境要求

- 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
```

或用路径直接 `uvx`：

```bash
SCNET_API_KEY=sk-xxx uvx --from /Users/haojie/workspace/project/mcp-document-parsing-py scnet-document-parser
```

### 2）发布到 PyPI 之后

```bash
# 用户侧只需：
uvx scnet-document-parser
# 或固定版本
uvx scnet-document-parser==0.1.0
```

`uvx` 会从 PyPI 拉包、建临时环境、执行入口脚本 `scnet-document-parser`。

## MCP 客户端配置

### Claude Code / Claude Desktop

```json
{
  "mcpServers": {
    "scnet-document-parser": {
      "command": "uvx",
      "args": [
        "--from",
        "/Users/haojie/workspace/project/mcp-document-parsing-py",
        "scnet-document-parser"
      ],
      "env": {
        "SCNET_API_KEY": "sk-your-key"
      }
    }
  }
}
```

发布到 PyPI 后可简化为：

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

### Cursor

在 MCP 设置中同样使用 `command` + `args` + `env` 即可（stdio 模式，不是 URL）。

### 可选环境变量

| 变量 | 默认 | 说明 |
|------|------|------|
| `SCNET_API_KEY` | **必填** | SCNet Key（可带或不带 `Bearer ` 前缀） |
| `SCNET_BASE_URL` | `https://api.scnet.cn` | API 根地址 |
| `SCNET_POLL_INTERVAL_MS` | `3000` | 显式轮询间隔 |
| `SCNET_MAX_EXPLICIT_WAIT_SECONDS` | `30` | 正数 `max_wait_seconds` 上限 |
| `SCNET_RESULT_DOWNLOAD_TIMEOUT_MS` | `30000` | 结果 JSON 下载超时 |

## 与 Java SSE 版对比

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

业务链路一致：presign → OSS multipart → submit → query → 下载结果 → 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

# 上传（需 PyPI token）
uv publish

# 验证
uvx scnet-document-parser --help   # 入口会启动 stdio；无 key 时会报错退出
```

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

## 支持的文件类型

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

| 类别 | 扩展名 | 默认大小上限 |
|------|--------|--------------|
| PDF | `.pdf` | 100MB |
| Word | `.doc` `.docx` | 100MB |
| Excel | `.xls` `.xlsx` `.csv` `.xlsm` `.xlsb` | 50MB |
| PPT | `.ppt` `.pptx` | 100MB |
| 图片 | `.jpg` `.jpeg` `.png` `.bmp` `.tiff` `.tif` `.webp` | 10MB |

大小上限可通过环境变量覆盖：`SCNET_MAX_FILE_SIZE` / `SCNET_MAX_EXCEL_FILE_SIZE` / `SCNET_MAX_IMAGE_FILE_SIZE`。
