Parsival MCP

帕西瓦尔

Parsival是一个基于MCP Python SDK的生产环境友好、基于工具的文件解析微服务。它旨在将常见的文档格式转换为丰富的结构化输出（Markdown、JSON、文本），并对流处理和代理集成进行性能调优和安全强化。

• 支持的输入格式：PDF、DOCX、DOC、PPTX、XLSX、CSV、HTML、MD、TXT
• 对大型文档的流式解析支持
• 缓存层：内存LRU+可选Redis
• 对损坏/加密文档的稳健处理、大小限制、子流程隔离
• 插件式解析器注册表和后处理管道

______________________________________________________________________

目录

1. 快速启动
2. 特性
3. 建筑
4. 存储库布局
5. 配置
6. 本地开发
8. API和工具
9. 解析器详细信息
10. 缓存行为
11. 测试和CI
12. 故障排除

______________________________________________________________________

快速启动

克隆存储库

git clone https://github.com/Aldrin-Joan/Parsival-mcp.git
cd Parsival-mcp

Python虚拟环境

Linux/macOS：

python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

Windows（PowerShell）：

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

运行服务器

推荐（本地stdio MCP）：

python -m src.mcp_entrypoint

这使用 MCP_TRANSPORT=stdio 默认情况下，在项目工具中，stdout专用于MCP协议流量。

验证支持的格式

from src.app import list_supported_formats
print(list_supported_formats())

______________________________________________________________________

特性

• 使用专用解析器插件进行多格式文件解析
• 以Markdown、JSON或原始文本输出
• 流解析器模式(stream=True)对于早期块
• Redis支持缓存，具有本地LRU回退功能
• 可配置的文件大小上限和解析器超时
• LibreOffice转换路径 .doc 支持
• 通过以下方式进行过程中和工人过程隔离 ProcessPoolExecutor
• 富有的 ParseResult 带有元数据、错误和可恢复性标志的模型
• 可插拔的后处理管道：元数据丰富、表规范化、图像提取

______________________________________________________________________

建筑

逻辑层

• src/app.py -工具定义和解析编排
• src/core -配置、缓存、路由、执行器、安全
• src/parsers -特定格式解析逻辑
• src/post_processors -结果富集管道
• src/serialisers -输出封送（Markdown、JSON、文本）
• src/tools -公共工具API包装器

堆芯流量

1. 客户端调用MCP工具（例如。， read_file).
2. src/tools/read_file.py 通过验证路径 validate_safe_path().
3. src.app.parse_file() 用途 FormatRouter 推断 FileFormat.
4. 解析器从以下位置获取 src.parsers.registry.
5. core.executor.run_parse_in_pool() 在进程池中执行解析器。
6. PostProcessingPipeline 使输出正常化。
7. 缓存密钥生成于 ContentHashStore 从文件哈希+选项。
8. 返回序列化响应。

格式检测（路由器）

• magic MIME嗅探（如果可用）
• 扩展图（例如。， .pdf, .docx, .pptx)
• CSV/HTML/Markdown的内容启发式

支持的工具

• read_file
• get_metadata
• extract_table
• extract_images
• convert_to_markdown
• search_file
• list_supported_formats

______________________________________________________________________

存储库布局

.
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml
├── requirements.txt
├── src/
│   ├── app.py
│   ├── config.py
│   ├── core/
│   ├── parsers/
│   ├── post_processors/
│   ├── serialisers/
│   ├── tools/
│   └── models/
└── tests/
    ├── unit/
    └── benchmarks/

• src/config.py -环境驱动设置对象
• src/core/cache.py -内存+Redis缓存层
• src/core/router.py -文件格式确定
• src/core/executor.py -具有线程限制的进程池执行
• src/parsers/* -按格式解析逻辑
• src/post_processors/* -丰富解析结果
• src/serialisers/* -Markdown/JSON/文本序列化器
• src/tools/* -MCP请求的工具包装器

______________________________________________________________________

配置

所需包

• python>=3.11
• 中列出的软件包 requirements.txt

可选服务

• Redis（用于共享缓存）
• LibreOffice（for .doc 转换；安装在Dockerfile中）

环境变量(MCP_ 前缀）

来自解析器的无前缀环境变量

______________________________________________________________________

本地开发

安装

pip install -r requirements.txt

运行单元测试

pytest -q

运行stdio烟雾测试

python scripts/tool_smoke_test_stdio.py

运行基准测试

pytest -q tests/benchmarks/test_benchmarks.py

静态检查

ruff check .
python -m mypy src tests

添加预提交

pip install pre-commit
pre-commit install
pre-commit run --all-files

______________________________________________________________________

在Docker中运行

构建

docker build -t parsival:latest .

跑

运行（stdio模式，不需要端口映射）：

docker run --rm -i -e PYTHONUNBUFFERED=1 -e MCP_TRANSPORT=stdio -e PYTHONPATH=/app parsival:latest

使用docker compose运行

运行stdio服务：

docker compose up parsival

作曲（单主机）

docker compose up --build

容器包括LibreOffice和 python-magic DOC/DOCX和格式嗅探所需的依赖关系。

______________________________________________________________________

API和工具

Parsival通过stdio公开MCP工具。使用您首选的MCP客户端按名称调用工具。

read_file

• path：str
• output_format：“markdown”|“json”|“text”（默认为“markdown”）
• page_range：\[开始，结束\]（1-索引）
• include_images：bool（默认为true）
• max_tokens_hint：int
• stream：bool（默认值为false）

退货 ReadFileResult （状态、格式、内容、元数据、错误、cachehit、request_id）。

get_metadata

• path：str
• 退货 DocumentMetadata 对象（文件格式、页面计数、表格计数等）

extract_table

• path：str
• table_index：int
• sheet_name：可选\[str\]
• 退货 TableResult

extract_images

• path：str
• page_range：可选\[tuple\[int，int\]\]
• max_dimension：可选\[int\]
• 退货列表\[ImageRef\]

convert_to_markdown

• path：str
• 返回标记字符串

search_file

• path：str
• query：str
• top_k：int
• 在章节文本上使用BM25排名（通过 rank-bm25)

list_supported_formats

• 无参数
• 退货可用 FileFormat 值和服务器版本

______________________________________________________________________

解析器详细信息

支持的文件格式

• PDF： src/parsers/pdf_parser.py （PyMuPDF+可选pdfplumber桌子）
• DOCX： src/parsers/docx_parser.py （python docx）
• 医生： src/parsers/doc_parser.py （LibreOffice转换+DOCX解析器）
• XLSX： src/parsers/xlsx_parser.py （波兰openpyxl）
• CSV： src/parsers/csv_parser.py （波兰，utf-8后撤）
• PPTX： src/parsers/pptx_parser.py （python pptx）
• HTML: src/parsers/html_parser.py （美汤+降价）
• TXT/MD： src/parsers/text_parser.py （纯文本启发式）

解析工作流

• parse_file 确定格式 FormatRouter.detect.
• 解析器返回 ParseResult，包括 sections, tables, images, metadata, errors.
• stream=True 分派解析器 stream_chunks，绕过缓存预取。
• max_tokens_hint 是解析后应用的软截断。

错误处理

• 损坏/加密的文档返回 ParseStatus.FAILED 和 ParseError 代码（例如。 encrypted, corrupt).
• 超大文件返回 ParseStatus.OVERSIZE （元数据中的源路径/大小）。
• 解析流防止在读取和结果刷新之间更改文件状态。

______________________________________________________________________

缓存行为

• 内置缓存密钥 src/core/cache.py 作为 SHA256(file) + ':' + SHA256(opts).
• 考虑的选项：output_format、page_range、include_images、max_tokens_hint、max_dision。
• 内存LRU缓存 cachetools.LRUCache 样本大小基于ParseResult的JSON大小。
• Redis后端如果 MCP_REDIS_ENABLED=true 和 MCP_REDIS_URL 已设置。
• 连接失败时，Redis会自动回退到内存中。
• 使用 MCP_REDIS_TTL （默认3600秒）。

______________________________________________________________________

测试和CI

本地试运行

pytest -q

覆盖

coverage run -m pytest -q
coverage report -m --fail-under=90

CI管道处于

• .github/workflows/ci.yml

- 针对Python 3.11/3.12/3.13的测试 - ruff check . - 覆盖+编解码器

______________________________________________________________________

故障排除

道路卫生

src/core/security.py 强制执行 MCP_WORKSPACE_ROOT 和 MCP_ALLOWED_DIRECTORIES如果你得到 SecurityError:

• 集 MCP_WORKSPACE_ROOT 到您的repo根目录
• 通过添加允许的目录 MCP_ALLOWED_DIRECTORIES

不支持的格式

如果解析失败，格式不受支持，请检查扩展名+文件魔术，并仅使用标准格式。

LibreOffice失败

• 确保 soffice 安装在PATH中（Dockerfile包括 libreoffice-* 包装）
• 增加：

- export LIBREOFFICE_TIMEOUT_SEC=60 - export MCP_MAX_LIBREOFFICE_WORKERS=4

Redis缓存

• 如果没有配置Redis，该服务将使用内存缓存。
• 集 MCP_REDIS_ENABLED=true 和 MCP_REDIS_URL=redis://localhost:6379/0.

______________________________________________________________________

维护人员注意事项

• 此README由以下代码和支持的配置生成 src/ 和 Docs/.
• 对于扩展，请在中添加解析器类 src/parsers 并注册 @register(FileFormat.X).
• 要公开新的MCP工具，请在中定义 src/tools 并在中添加装饰功能 src/app.py.