Conversation
read_pdf_bytes put the base64 bytes only in structuredContent; its text block was a size summary like "256 bytes at 0/641720". Clients that only render content[] (e.g. terminal MCP clients) could not read the data. Mirror the structured result as serialized JSON in the text block, as the MCP spec recommends for tools that return structured content. The viewer keeps reading structuredContent, so its behavior is unchanged. Fixes modelcontextprotocol#762
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
read_pdf_bytesinexamples/pdf-servernow also returns its result as serialized JSON incontent[0].text, with the same data asstructuredContent. Before, the bytes were only instructuredContent.Fixes #762
Motivation and Context
Clients that only render
content[], such as terminal MCP clients, got a size summary like256 bytes at 0/641720and never saw the PDF bytes. The MCP spec says a tool that returns structured content SHOULD also return the serialized JSON in a TextContent block, and several other examples in this repo already do (wiki-explorer-server,system-monitor-server,customer-segmentation-server).The viewer (
src/mcp-app.ts) still readsstructuredContent, so its behavior is unchanged.How Has This Been Tested?
server.test.tsthat callsread_pdf_bytesthrough an in-memory client and checks thatcontent[0].textparses to the same object asstructuredContentand decodes to%PDF-1.4. It fails onmainwith a JSON parse error and passes with this change.node examples/pdf-server/dist/index.js --stdio <file>) with a client that reads onlycontent[0].text. It decoded the%PDF-1.7header oftests/helpers/assets/fw9.pdf, and the parsed text matchedstructuredContent.npm testpasses: all pdf-server tests, 195 passed and 1 skipped.npm run build:allandnpm run prettierpass.Breaking Changes
None.
structuredContentis unchanged. The text block changes from a size summary to JSON.Types of changes
Checklist
Additional context
Trade-off: each chunk (up to 512 KB) is now sent twice, once as base64 in
structuredContentand once inside the text. That also affects the viewer's range requests. If you'd rather keep the viewer path lean, I can include the text copy only when the client doesn't advertise the MCP Apps extension (getUiCapability(server.server.getClientCapabilities())).This PR doesn't cover the second part of #762, a text-extraction path for headless clients that can't mount the viewer. That seems better as a separate change.
AI disclosure: I used Claude Code to research the issue, write the change and the test, and run the verification. I reviewed the diff and the test results myself.