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(推荐,用于
uvx一键运行) - SCNet API Key
用 uvx 运行(推荐)
1)本地开发(未发布到 PyPI 时)
cd /Users/haojie/workspace/project/mcp-document-parsing-py
uv sync
SCNET_API_KEY=sk-xxx uv run scnet-document-parser
2)发布到 PyPI 之后
uvx scnet-document-parser
# 或固定版本
uvx scnet-document-parser==0.4.0
MCP 客户端配置
Claude Code / Claude Desktop
{
"mcpServers": {
"scnet-document-parser": {
"command": "uvx",
"args": ["scnet-document-parser"],
"env": {
"SCNET_API_KEY": "sk-your-key"
}
}
}
}
本地未发布时可将 args 改为:
"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 |
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。
开发
cd /Users/haojie/workspace/project/mcp-document-parsing-py
uv sync --group dev
uv run pytest
发布到 PyPI(供他人 uvx)
uv build
uv publish
包名:scnet-document-parser
控制台入口:scnet-document-parser → scnet_document_parser.server:main
Metadata
Release files for scnet-document-parser 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| scnet_document_parser-0.4.0.tar.gz | 15.6 kB | Without provenance | Details for scnet_document_parser-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| scnet_document_parser-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for scnet_document_parser-0.4.0-py3-none-any.whl |
Total release size: 35.6 kB
Release files / scnet_document_parser-0.4.0.tar.gz
| Download URL | scnet_document_parser-0.4.0.tar.gz |
|---|---|
| Size | 15.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
731bf6dc41c4ff2ac3cd1ab69abd430f0e862c8ca9a5ecc255502d381d7a5690
|
|
BLAKE2b-256 checksum How to use checksums |
2b2b0e9656a5ae45d9bb9f74ce7c85bf08109a4b79d6d941877079f63a6c2af3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.26 {"installer":{"name":"uv","version":"0.11.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / scnet_document_parser-0.4.0-py3-none-any.whl
| Download URL | scnet_document_parser-0.4.0-py3-none-any.whl |
|---|---|
| Size | 20.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a82017251750444221447bee70146d7df749cf86907b54dd9a39db6842f7034e
|
|
BLAKE2b-256 checksum How to use checksums |
ce61eb300596907f86f334547ce55049e45f583f2d67fb171910da1a0abaa491
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.26 {"installer":{"name":"uv","version":"0.11.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for scnet-document-parser 0.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.