Skip to content

fix: preserve data-URL-looking JSON strings - #278

Open
bitbemol wants to merge 2 commits into
modelcontextprotocol:mainfrom
bitbemol:bugfix/preserve-data-url-json-strings
Open

fix: preserve data-URL-looking JSON strings#278
bitbemol wants to merge 2 commits into
modelcontextprotocol:mainfrom
bitbemol:bugfix/preserve-data-url-json-strings

Conversation

@bitbemol

@bitbemol bitbemol commented Aug 29, 2026

Copy link
Copy Markdown

Fixes #277.

Preserves JSON strings decoded through Value as .string, including strings that match data-URL syntax. Explicit Value.data encoding and the data-URL helper APIs remain available, and the public API documentation now clarifies that parsing is opt-in.

Motivation and Context

Value.init(from:) currently interprets any parseable data-URL-looking JSON string as .data. Because generic JSON contains no discriminator between an ordinary string and an encoded Value.data, this can silently change both the Value case and the string's spelling.

For example:

Original: data:text/plain,Hello%20World
Decoded and re-encoded: data:text/plain;base64,SGVsbG8gV29ybGQ=

This can also affect content explicitly tagged as MCP text when it passes through generic Value conversion.

The change makes the string branch of Value.init(from:) always produce .string. Applications that intentionally accept data URLs can continue to opt in through Data.parseDataURL(_:), while explicitly constructed Value.data values retain their existing encoding.

How Has This Been Tested?

Added regression coverage for:

  • Literal, base64-looking, empty, malformed, percent-encoded, non-ASCII, and application/octet-stream data-URL-looking strings
  • Strings nested inside arrays and objects
  • JSON string type and spelling preservation through round trips
  • Explicit Value.data encoding
  • The absence of an implicit .data discriminator on the generic JSON wire
  • Typed MCP text content passing through Value erasure
  • Typed image and audio content serialization

Verification performed:

  • swift test --filter ValueTests: 8/8 tests passed
  • Full Xcode test suite: 559/559 tests passed
  • git diff --check: clean

The regression tests were also run against the previous decoder implementation to confirm that they reproduce the reported behavior.

Breaking Changes

This intentionally changes observable behavior for callers that relied on generic Value decoding to automatically convert data-URL-looking JSON strings into .data.

Those callers will need to explicitly call Data.parseDataURL(_:) in fields where data URLs are expected. Encoding an explicitly constructed Value.data remains unchanged, as does typed image and audio content serialization.

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update

Checklist

  • I have read the MCP Documentation
  • My code follows the repository's style guidelines
  • New and existing tests pass locally
  • I have added appropriate error handling
  • I have added or updated documentation as needed

Additional context

This behavior was encountered in bitbemol/second-brain-mcp, which currently vendors the patched SDK pending an upstream resolution.

This is my first contribution to swift-sdk. I may be missing context behind the original implicit decoding behavior and am happy to adjust the approach based on maintainer feedback.

AI assistance disclosure: This bug was initially identified with LLM assistance, and Codex assisted with implementation analysis and regression-test development. I personally reviewed the relevant SDK behavior, reproduced the failure in Xcode with the previous decoder, and verified the fix with the complete test suite.

@ianegordon ianegordon mentioned this pull request Sep 10, 2026
Closed
ianegordon added a commit to ianegordon/swift-sdk that referenced this pull request Sep 11, 2026
@ianegordon @claude
FORK.md: decline modelcontextprotocol#227 rather than carry it
047d946 
The change is correct — Value.init(_:) only ever encodes its argument, so
the Codable constraint is over-tight — but it fixes no bug, and unlike
every other entry in the manifest its absence upstream is a compile error
rather than a runtime fault. Fork code passing an Encodable-only type
would not build against upstream unless modelcontextprotocol#227 lands there, turning the
return this fork exists to make easy into a build break. No downstream
needs the looser constraint today.

Moved from the candidate table to 'Not included, and why'. Remaining
candidates renumbered 7-10 to 6-9 so the intended order still continues
the manifest sequence. modelcontextprotocol#278's note no longer calls itself the second
Value.swift edit in the batch, since modelcontextprotocol#227 was the first.

Tracking: fork issue #13, relabelled decline.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Eb9yGSXH1TVkg5Afsu9phk
ianegordon added a commit to ianegordon/swift-sdk that referenced this pull request Sep 11, 2026
@ianegordon @claude
FORK.md: record modelcontextprotocol#276 as entry 7 and pr/276-compat…
9395644 
… as entry 7a

Client.Capabilities.experimental was [String: String] where the 2025-11-25
schema defines a map of arbitrary objects, so a ChatGPT-shaped initialize
carrying {"openai/visibility": {"enabled": true}} failed to decode and the
server answered -32603 to a valid request. Reproduced on the wire before the
merge and confirmed fixed after.

The entry records what the PR description understates: the type change is
source-breaking for a typed [String: String] variable and for reading a value
back as String, and the extensions field it adds is a draft-schema capability
absent from 2025-11-25 — an unmodeled key already decoded fine, so that half
is a feature rather than a fix.

7a restores the typed-variable call site behind a deprecation warning. The
read direction cannot be shimmed by an initializer and still needs updating
downstream.

Remaining candidate modelcontextprotocol#278 renumbered 7 to 6.

Tracking: fork issue #11.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Eb9yGSXH1TVkg5Afsu9phk
ianegordon added a commit to ianegordon/swift-sdk that referenced this pull request Sep 11, 2026
@ianegordon @claude
Merge pr/278: preserve data-URL-looking JSON strings (upstream modelc…
4539b00 
…ontextprotocol#278, bitbemol)

Manifest entry 8. Upstream refs/pull/278/head at af48e3f, unmodified.

Value.init(from:) treated any parseable data-URL-looking JSON string as
Value.data, silently changing both the case and the string's spelling.
Content explicitly tagged as MCP text was corrupted on round trip:
data:text/plain,Hello%20World came back as
data:text/plain;base64,SGVsbG8gV29ybGQ=. Generic JSON carries no
discriminator, and the spec tags content explicitly (TextContent.type is
const "text"), so the decoder had no business guessing.

The string branch now always produces .string. Data.isDataURL(string:) and
Data.parseDataURL(_:) remain public for callers that want to opt in, and
explicit Value.data encoding is unchanged.

Verified by running the PR's own tests against the unpatched tree first:
six of eight fail there, including typed text content corruption, and all
eight pass after the merge.

Behavior change, not a source break: no API signature moves, so fork code
calling parseDataURL explicitly still compiles and behaves identically
against upstream. Note Value.data is now round-trip-asymmetric — it encodes
as a data URL but decodes back as .string, which the PR pins with a test.

The unrelated NetworkTransport capture-list hunk (Task { @mainactor [self] in)
is behaviorally inert and emits no warning on this toolchain; left as authored,
review feedback for upstream.

Fixes modelcontextprotocol#277.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Eb9yGSXH1TVkg5Afsu9phk
ianegordon added a commit to ianegordon/swift-sdk that referenced this pull request Sep 11, 2026
@ianegordon @claude
FORK.md: record modelcontextprotocol#278 as manifest entry 8, pin exa…
6e25ae0 
…mple to 0.12.2-ianegordon.8

Value.init(from:) treated any parseable data-URL-looking JSON string as
Value.data, silently changing both the case and the string's spelling.
Content explicitly tagged as MCP text was corrupted on round trip.

The entry records the measured before/after (the PR's own tests fail six of
eight against the unpatched tree, all eight pass after), that this is a
behavior change rather than a source break with no return trap, and two
caveats: Value.data is now round-trip-asymmetric, and the unrelated
NetworkTransport capture-list hunk is inert and left as authored.

The candidate table is now empty. Its section and header are kept, with a
note that the next candidates come from the twelve upstream PRs triaged
Investigate under the investigate label.

Tracking: fork issue #12.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Eb9yGSXH1TVkg5Afsu9phk
@ianegordon ianegordon mentioned this pull request Sep 12, 2026
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Value decoding changes data-URL-looking JSON strings into Value.data

1 participant

@bitbemol