Skip to main content
Glama
tycket033-tech

pdf-debug-mcp

pdf-debug-mcp

pdf-debug-mcp 是一个用于检查 PDF 底层结构的 MCP Server。它提供类似 PDF inspector/debugger 的能力:读取 indirect object、递归展开对象引用、查看内容流、列出页面树和页面资源。

实现使用 pdf-lib 解析 PDF 对象模型,并在项目内补充了 stream filter 解码和原始对象片段定位逻辑。选择 pdf-lib 的原因是它稳定、纯 JavaScript、维护成熟,且可以访问 indirect objects、catalog、page tree、page dictionaries 和 raw streams,适合作为 MCP 本地调试工具的基础。

编码要求

所有项目文件都使用 UTF-8 创建和编辑。在 Windows PowerShell 中读取文件前,建议先设置终端编码:

[Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false)
[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
$OutputEncoding = [Console]::OutputEncoding

Related MCP server: mcp-pdf-tools

安装与构建

cd C:\src\pdf-debug-mcp
npm install
npm run build

启动

npm start

该进程通过 stdio 提供 MCP 服务。

MCP 配置

Codex 配置

推荐先把项目链接成本地命令:

cd C:\src\pdf-debug-mcp
npm link

然后添加到 Codex:

codex mcp add pdf-debug -- pdf-debug-mcp

通用 MCP 客户端也可以直接执行构建后的入口文件:

{
  "mcpServers": {
    "pdf-debug": {
      "command": "node",
      "args": ["C:/src/pdf-debug-mcp/dist/index.js"]
    }
  }
}

工具

get_pdf_object

根据 object number 和 generation number 获取指定 PDF indirect object。

输入:

{
  "filePath": "C:/path/to/file.pdf",
  "objectNumber": 4,
  "generationNumber": 0,
  "maxBytes": 65536,
  "decodeStream": true
}

输出包含:

  • rawObject: 原始对象片段预览;

  • parsed: 解析后的结构化对象;

  • objectType: pdf-lib 对象类型;

  • hasStream: 是否包含 stream;

  • stream: stream 长度、filters、解码状态等 metadata。

get_pdf_object_structure

递归展开对象结构和 indirect references。

输入:

{
  "filePath": "C:/path/to/file.pdf",
  "objectNumber": 3,
  "generationNumber": 0,
  "maxDepth": 4,
  "maxBytes": 65536,
  "decodeStream": true
}

循环引用会标记为 [Circular Reference],达到深度限制会标记为 [Max depth N reached]

get_pdf_content_stream

根据页面或 stream object 获取内容流。

页面内容流:

{
  "filePath": "C:/path/to/file.pdf",
  "pageNumber": 1,
  "decodeStream": true,
  "parseOperators": true,
  "maxBytes": 65536
}

指定 stream object:

{
  "filePath": "C:/path/to/file.pdf",
  "objectNumber": 7,
  "generationNumber": 0,
  "decodeStream": true
}

输出会返回每个 stream 的来源对象、raw bytes 预览、decoded bytes/text 预览、filter 列表,以及可选 operator/token 分析。页面有多个内容流时会分别返回并提供 mergedDecoded

当前支持的 stream filters:

  • FlateDecode / Fl

  • ASCIIHexDecode / AHx

  • ASCII85Decode / A85

  • RunLengthDecode / RL

不支持的 filter 会保留当前 bytes 并在 decodeError 中说明。

list_pdf_objects

列出 PDF 中的 indirect objects。

{
  "filePath": "C:/path/to/file.pdf",
  "maxObjects": 1000
}

get_pdf_document_info

获取 PDF header、trailer、catalog、xref 摘要和对象数量。

{
  "filePath": "C:/path/to/file.pdf",
  "maxDepth": 3
}

get_pdf_page_tree

获取页面树结构。

{
  "filePath": "C:/path/to/file.pdf",
  "maxDepth": 8
}

get_pdf_page_resources

获取指定页面关联的 Resources、Fonts、XObjects、Annots 等引用。

{
  "filePath": "C:/path/to/file.pdf",
  "pageNumber": 1,
  "maxDepth": 3
}

验证

npm test

Smoke test 会生成一个小 PDF,并验证:

  • 构建后的模块可以列出 indirect objects;

  • 可以读取 catalog 对象;

  • 可以递归展开 page tree;

  • 可以解码页面内容流并解析 operator;

  • 可以读取页面资源;

  • MCP Server 可以通过 stdio 响应 initialize 请求。

说明

该工具优先返回结构化 JSON,适合 AI 后续分析。对大型对象和大型 stream 使用 maxBytesmaxDepthdecodeStream 控制输出规模。

Available Tools

7 tools
get_pdf_content_streamA

Return PDF content stream bytes and decoded text from either a 1-based page number or a stream object number, with optional operator parsing.

ParametersJSON Schema
NameRequiredDescriptionDefault
filePathYesPath to a PDF file. Relative paths are resolved from the MCP server process cwd.
maxBytesNoMaximum bytes to include in raw/decoded stream or object previews.
pageNumberNo1-based page number. Use this or objectNumber.
decodeStreamNoDecode supported stream filters such as FlateDecode, ASCIIHexDecode, ASCII85Decode, and RunLengthDecode.
objectNumberNoStream object number. Use this or pageNumber.
parseOperatorsNoReturn a lightweight token/operator analysis for decoded PDF content streams.
generationNumberNoPDF indirect object generation number.

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It explains the return type (bytes and decoded text) and optional operator parsing, but it omits behavioral traits such as read-only nature, error handling (e.g., invalid page number), or performance implications. It does not contradict any annotations since none exist.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence of 20 words without any redundancy. Every element earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description provides the high-level purpose but lacks details on parameter interactions (e.g., exclusivity of pageNumber and objectNumber), default values, or the format of return data. Since there is no output schema, agents may need more guidance on what to expect.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description clarifies the choice between pageNumber and objectNumber and mentions optional operator parsing, but this adds only marginal value beyond the already-described parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly and specifically states the tool's function: returning PDF content stream bytes and decoded text from either a page number or object number, with optional operator parsing. It distinguishes itself from sibling tools that deal with document info, objects, structure, page resources, page tree, or listing objects.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for retrieving content streams, but it does not explicitly guide when to choose this tool over siblings like get_pdf_object or get_pdf_object_structure. No exclusions or when-not-to-use guidance is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_pdf_document_infoA

Return PDF header, trailer, catalog, xref style summary, page count, and indirect object count.

ParametersJSON Schema
NameRequiredDescriptionDefault
filePathYesPath to a PDF file. Relative paths are resolved from the MCP server process cwd.
maxDepthNoMaximum recursion depth when expanding object references.

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description must carry the burden. It lists what is returned but does not explicitly state that the operation is read-only, has no side effects, or requires no authentication.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence of 15 words that efficiently communicates the tool's output. Every word adds value; no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Lists all major return values, which is sufficient for an agent to understand what information will be obtained. With no output schema, a note on output format would be helpful but not necessary given the clear enumeration.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The tool description does not add any meaning beyond what the schema already provides for filePath and maxDepth.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns specific PDF summary information (header, trailer, catalog, xref style summary, page count, indirect object count), distinguishing it from siblings that focus on individual objects or content streams.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives (e.g., get_pdf_object_structure or get_pdf_page_tree). Agents must infer from the sibling list.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_pdf_objectA

Return a PDF indirect object by object/generation number, including raw object preview, parsed structure, object type, and stream metadata.

ParametersJSON Schema
NameRequiredDescriptionDefault
filePathYesPath to a PDF file. Relative paths are resolved from the MCP server process cwd.
maxBytesNoMaximum bytes to include in raw/decoded stream or object previews.
decodeStreamNoDecode supported stream filters such as FlateDecode, ASCIIHexDecode, ASCII85Decode, and RunLengthDecode.
objectNumberYesPDF indirect object number.
generationNumberNoPDF indirect object generation number.

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description must bear full burden. It discloses the output content (preview, structure, type, metadata) but omits operational behaviors like side effects, error conditions, or performance implications. Adequate but not thorough.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence concisely states the tool's purpose and output. Every word adds value; no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given good schema coverage and no output schema, the description adequately explains what the tool returns. However, it lacks details on expected input validation or error scenarios, which would enhance completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for all parameters. The tool description adds context about the returned data but does not elaborate on parameter usage beyond the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns a PDF indirect object by number, listing included details (raw preview, parsed structure, type, stream metadata). It differentiates from siblings like get_pdf_object_structure by specifying what is returned.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives. The description does not mention prerequisites, when not to use it, or compare with sibling tools, leaving selection ambiguous.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_pdf_object_structureA

Recursively expand a PDF indirect object's structure and indirect references with maxDepth and circular-reference protection.

ParametersJSON Schema
NameRequiredDescriptionDefault
filePathYesPath to a PDF file. Relative paths are resolved from the MCP server process cwd.
maxBytesNoMaximum bytes to include in raw/decoded stream or object previews.
maxDepthNoMaximum recursion depth when expanding object references.
decodeStreamNoDecode supported stream filters such as FlateDecode, ASCIIHexDecode, ASCII85Decode, and RunLengthDecode.
objectNumberYesPDF indirect object number.
generationNumberNoPDF indirect object generation number.

TDQS

A3.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses recursion behavior, maxDepth parameter, and circular-reference protection, which are behavioral traits beyond the input schema. However, it does not mention side effects or safety aspects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that instantly conveys the tool's purpose and key features. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 6 parameters and no output schema, the description is succinct but does not explain the return value format (e.g., tree structure). This leaves ambiguity for the agent about what response to expect.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description does not add new parameter meaning beyond what the schema provides; it only mentions maxDepth in passing, which is already described in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool recursively expands a PDF indirect object's structure and indirect references, specifying key features like maxDepth and circular-reference protection. This distinctively separates it from siblings like get_pdf_object, which likely provides a flat view.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives. While the description implies use for recursive expansion, it does not provide when-not scenarios or mention sibling tools for different needs.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_pdf_page_resourcesA

Return a page's inherited Resources plus Fonts, XObjects, Annots, and related resource references.

ParametersJSON Schema
NameRequiredDescriptionDefault
filePathYesPath to a PDF file. Relative paths are resolved from the MCP server process cwd.
maxDepthNoMaximum recursion depth when expanding object references.
pageNumberYes1-based page number.

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses the return content but does not mention side effects (e.g., read-only), required permissions, error handling, or performance implications. The behavior is generally safe (read operation) but incomplete.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that front-loads the purpose. Every word adds value, and there is no extraneous information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 3 parameters and no output schema, the description covers the return value but lacks details on the format (e.g., JSON structure, reference types) and error conditions. It is adequate for basic understanding but insufficient for full autonomous use without schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description does not add meaning beyond the schema for the parameters; it focuses on the return value. The schema already explains filePath, pageNumber, and maxDepth adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Return') and the specific resource ('a page's inherited Resources plus Fonts, XObjects, Annots, and related resource references'). It distinguishes from sibling tools like get_pdf_page_tree or get_pdf_content_stream, which focus on different aspects of PDF pages.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implicitly indicates use when page resources are needed, but provides no explicit guidance on when to use this tool versus alternatives like get_pdf_object_structure or list_pdf_objects. No exclusion criteria or prerequisites are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_pdf_page_treeA

Return the PDF page tree rooted at the catalog /Pages object, including page/kids refs and content references.

ParametersJSON Schema
NameRequiredDescriptionDefault
filePathYesPath to a PDF file. Relative paths are resolved from the MCP server process cwd.
maxDepthNoMaximum recursion depth when expanding object references.

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It states a read operation but does not disclose any behavioral traits such as read-only nature, error conditions, or performance implications. Minimal transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence conveys the essential function without extraneous words. Every word contributes to understanding the tool's purpose and output.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the sibling tools and lack of output schema, the description sufficiently explains what the tool returns (page tree with refs and content references). It is adequately complete for a simple retrieval tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for both parameters. The tool description adds no additional meaning beyond what the schema already provides, so baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses specific verb 'Return' and resource 'PDF page tree' with detail about root location and included references. It clearly distinguishes from siblings by naming the exact object type and scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use for retrieving the page tree structure but provides no explicit guidance on when to use versus alternatives like get_pdf_object_structure or list_pdf_objects. No exclusions or prerequisites mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_pdf_objectsA

List indirect objects in a PDF with object number, generation number, object type, PDF /Type, and stream metadata.

ParametersJSON Schema
NameRequiredDescriptionDefault
filePathYesPath to a PDF file. Relative paths are resolved from the MCP server process cwd.
maxObjectsNoMaximum indirect object summaries to return.

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It describes output fields but does not disclose behavioral traits such as whether the operation is read-only, side effects, or performance implications.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence of 20 words, efficiently conveying the tool's purpose and output. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Adequately describes the output fields but lacks information on limitations (e.g., maxObjects default, that it only lists indirect objects), and does not leverage sibling names for differentiation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already describes both parameters. The description adds no additional meaning beyond what is in the schema, meeting the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (list), the resource (indirect objects in a PDF), and the specific fields returned (object number, generation number, object type, PDF /Type, stream metadata). It distinguishes from siblings like get_pdf_object, which retrieves a single object.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives. Sibling tools exist (e.g., get_pdf_object, get_pdf_page_tree) but the description provides no context for selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

TDQS

A4/5.0
Disambiguation5/5

Each tool targets a distinct aspect of PDF structure (content stream, document info, objects, page tree, resources, etc.) with no overlapping purposes.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern in snake_case, using 'get_pdf_' or 'list_pdf_' prefixes.

Tool Count5/5

Seven tools provide comprehensive coverage for PDF debugging without being excessive or insufficient.

Completeness4/5

The set covers essential PDF inspection operations; missing potential features like annotation extraction or object filtering are minor gaps.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/tycket033-tech/pdf-debug-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server