STARWARCLOUD STARWAR.AI
返回市场
营养pdf-mcp服务器

营养pdf-mcp服务器

作者：PSPDFKit3 星标更新：2025-08-02
安装使用来源：spider==github.com

项目介绍

Nutrient PDF MCP 服务器

一款强大的用于LLM驱动的PDF文档分析和探索的模型上下文协议服务器

这是一个模型上下文协议(MCP)服务器，用于调查具有懒加载支持的PDF对象树。此工具允许LLM高效地探索PDF文档结构而不超出令牌限制。

特性

  • 懒加载：无需加载整个对象树即可探索PDF结构
  • 路径导航：使用点表示法（例如，Pages.Kids.0）在PDF对象之间导航
  • 选择性解析：按需解析特定的间接对象
  • 令牌效率：与全树转储相比，响应大小大幅减少
  • 类型安全：全面的类型提示和错误处理

安装

可选的 asdf 设置

你需要在你的机器上安装 python 和 nodejs。你可以选择使用 asdf。

最后，安装所需的工具：

git clone https://github.com/PSPDFKit/nutrient-pdf-mcp-server.git
cd nutrient-pdf-mcp-server
asdf install

# 安装 pipx 以支持 Python
python -m pip install --user pipx

之后继续进行剩余的安装步骤。

快速开始

git clone https://github.com/PSPDFKit/nutrient-pdf-mcp-server.git
cd nutrient-pdf-mcp-server
make install-dev  # 设置开发环境

对于 Claude Code CLI

推荐：构建并安装

pip install build
make build
pipx install dist/nutrient_pdf_mcp-1.0.0-py3-none-any.whl
claude mcp add nutrient-pdf-mcp nutrient-pdf-mcp

如果使用 asdf，你可能需要在运行之前用以下方式配置 pipx：

export PIPX_DEFAULT_PYTHON=$(asdf which python)
pipx install dist/nutrient_pdf_mcp-1.0.0-py3-none-any.whl

开发模式

make install-dev
claude mcp add nutrient-pdf-mcp "$(pwd)/venv/bin/python" -m pdf_mcp.server

手动配置

{
  "mcpServers": {
    "nutrient-pdf-mcp": {
      "command": "python",
      "args": ["-m", "pdf_mcp.server"]
    }
  }
}

可用工具

get_pdf_object_tree

Nutrient PDF MCP 服务器 - 获取具有懒加载支持的PDF对象树的JSON表示。

参数：

  • pdf_path（必需）：PDF文件的路径
  • object_id（可选）：要检索的具体对象ID（例如，'1 0'）
  • path（可选）：要导航的对象路径（例如，'Pages.Kids.0'）
  • mode（可选）：解析模式 - 'lazy'（默认）或 'full'

示例：

{
  "pdf_path": "document.pdf",
  "mode": "lazy"
}

{
  "pdf_path": "document.pdf",
  "path": "Pages.Kids.0",
  "mode": "lazy"
}

resolve_indirect_object

Nutrient PDF MCP 服务器 - 根据其对象和生成编号解析特定的间接对象。

参数：

  • pdf_path（必需）：PDF文件的路径
  • objnum（必需）：PDF对象编号（例如，3）
  • gennum（可选）：PDF生成编号（默认为0）
  • depth（可选）：解析深度 - 'shallow'（默认）或 'deep'

示例：

{
  "pdf_path": "document.pdf",
  "objnum": 3,
  "gennum":  0,
  "depth": "shallow"
}

命令行使用

# 运行服务器
make serve

# 或者启用调试日志运行
make serve-debug

架构

核心组件

  • parser.py：主要的PDF解析逻辑，支持懒加载
  • server.py：MCP服务器实现
  • types.py：PDF对象和响应的类型定义
  • exceptions.py：自定义异常类

响应类型

所有PDF对象都被序列化成一致的JSON格式：

{
  "type": "dict",
  "value": {
    "/Type": { "type": "name", "value": "/Pages" },
    "/Kids": {
      "type": "array",
      "value": [{ "type": "indirect_ref", "objnum": 2, "gennum": 0 }]
    }
  }
}

令牌效率

懒加载系统提供了巨大的令牌节省：

  • 懒加载模式：~5-50行（最小令牌）
  • 浅层解析：~50-100行（合理令牌）
  • 深层解析：500+行（谨慎使用）

示例

探索PDF结构

  1. 获取概览：get_pdf_object_tree(path="document.pdf", mode="lazy")
  2. 导航到页面：get_pdf_object_tree(path="document.pdf", path="Pages", mode="lazy")
  3. 解析特定页面：resolve_indirect_object(objnum=3, gennum=0, depth="shallow")
  4. 必要时深入：resolve_indirect_object(objnum=3, gennum=0, depth="deep")

路径导航示例

  • "Pages" - 导航到Pages对象
  • "Pages.Kids" - 获取Pages中的Kids数组
  • "Pages.Kids.0" - 获取第一页
  • "Pages.Kids.0.MediaBox.2" - 获取MediaBox数组中的宽度

开发

快速开始

# 设置开发环境
make install-dev

# 运行所有质量检查（格式化、lint、类型检查、测试）
make quality

# 或单独运行命令
make test          # 运行测试
make format        # 格式化代码
make lint          # 运行lint
make typecheck     # 类型检查

项目结构

nutrient-pdf-mcp-server/
├── pdf_mcp/
│   ├── __init__.py
│   ├── server.py          # MCP服务器
│   ├── parser.py          # PDF解析逻辑
│   ├── types.py           # 类型定义
│   └── exceptions.py      # 自定义异常
├── tests/                 # 测试套件
├── res/                   # 示例PDF
├── pyproject.toml         # 项目配置
└── README.md

发布到PyPI

# 构建包
make build

# 首先上传到test PyPI
twine upload --repository testpypi dist/*

# 上传到生产PyPI
twine upload dist/*

发布后，用户可以安装：

pipx install nutrient-pdf-mcp
# 或
pip install --user nutrient-pdf-mcp

贡献

  1. 分叉仓库
  2. 创建一个特性分支
  3. 编写带有测试的更改
  4. 确保代码质量检查通过
  5. 提交拉取请求

许可证

MIT 许可证 - 查看 LICENSE 文件了解详情。

相关项目