pdf-debug-mcp
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@pdf-debug-mcpList indirect objects in report.pdf"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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]::OutputEncodingRelated 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/FlASCIIHexDecode/AHxASCII85Decode/A85RunLengthDecode/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 testSmoke test 会生成一个小 PDF,并验证:
构建后的模块可以列出 indirect objects;
可以读取 catalog 对象;
可以递归展开 page tree;
可以解码页面内容流并解析 operator;
可以读取页面资源;
MCP Server 可以通过 stdio 响应
initialize请求。
说明
该工具优先返回结构化 JSON,适合 AI 后续分析。对大型对象和大型 stream 使用 maxBytes、maxDepth、decodeStream 控制输出规模。
Available Tools
7 toolsget_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.
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | Path to a PDF file. Relative paths are resolved from the MCP server process cwd. | |
| maxBytes | No | Maximum bytes to include in raw/decoded stream or object previews. | |
| pageNumber | No | 1-based page number. Use this or objectNumber. | |
| decodeStream | No | Decode supported stream filters such as FlateDecode, ASCIIHexDecode, ASCII85Decode, and RunLengthDecode. | |
| objectNumber | No | Stream object number. Use this or pageNumber. | |
| parseOperators | No | Return a lightweight token/operator analysis for decoded PDF content streams. | |
| generationNumber | No | PDF indirect object generation number. |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | Path to a PDF file. Relative paths are resolved from the MCP server process cwd. | |
| maxDepth | No | Maximum recursion depth when expanding object references. |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | Path to a PDF file. Relative paths are resolved from the MCP server process cwd. | |
| maxBytes | No | Maximum bytes to include in raw/decoded stream or object previews. | |
| decodeStream | No | Decode supported stream filters such as FlateDecode, ASCIIHexDecode, ASCII85Decode, and RunLengthDecode. | |
| objectNumber | Yes | PDF indirect object number. | |
| generationNumber | No | PDF indirect object generation number. |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | Path to a PDF file. Relative paths are resolved from the MCP server process cwd. | |
| maxBytes | No | Maximum bytes to include in raw/decoded stream or object previews. | |
| maxDepth | No | Maximum recursion depth when expanding object references. | |
| decodeStream | No | Decode supported stream filters such as FlateDecode, ASCIIHexDecode, ASCII85Decode, and RunLengthDecode. | |
| objectNumber | Yes | PDF indirect object number. | |
| generationNumber | No | PDF indirect object generation number. |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | Path to a PDF file. Relative paths are resolved from the MCP server process cwd. | |
| maxDepth | No | Maximum recursion depth when expanding object references. | |
| pageNumber | Yes | 1-based page number. |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | Path to a PDF file. Relative paths are resolved from the MCP server process cwd. | |
| maxDepth | No | Maximum recursion depth when expanding object references. |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | Path to a PDF file. Relative paths are resolved from the MCP server process cwd. | |
| maxObjects | No | Maximum indirect object summaries to return. |
TDQS
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.
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.
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.
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.
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.
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
Each tool targets a distinct aspect of PDF structure (content stream, document info, objects, page tree, resources, etc.) with no overlapping purposes.
All tools follow a consistent verb_noun pattern in snake_case, using 'get_pdf_' or 'list_pdf_' prefixes.
Seven tools provide comprehensive coverage for PDF debugging without being excessive or insufficient.
The set covers essential PDF inspection operations; missing potential features like annotation extraction or object filtering are minor gaps.
Maintenance
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
MCP server for detecting and redacting PII (Personally Identifiable Information) in PDF documents.
MCP server for the PDFGate API. Generate PDFs, manage documents and handle e-signatures.
HTML-to-PDF MCP server — render pixel-faithful PDFs from HTML.
Privacy-first PDF tools over MCP: merge, split, rotate, delete, compress, protect, inspect.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA PDF processing server that extracts text via normal parsing or OCR, and retrieves images from PDF files through the MCP protocol with a built-in web debugger.36
- AlicenseAqualityNot gradedmaintenanceAn MCP server that enables users to read, search, and analyze PDF documents. It provides tools for extracting text, viewing metadata, searching content with context, and generating word statistics.5
- AlicenseNot gradedqualityDmaintenanceAn MCP server that provides tools for reading, writing, and manipulating PDF files, including text extraction, metadata retrieval, and merging or splitting documents. It also enables users to create PDFs from plain text and convert specific pages or entire documents into images.53ISC
- AlicenseAqualityAmaintenanceAn MCP (Model Context Protocol) server specialized in deciphering PDF internal structures.164842MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
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