Skip to content

refactor: Mirror structuredContent as JSON text in storage and search tools - #1874

Open
daveomri wants to merge 5 commits into
masterfrom
refactor/storage-json-mirror
Open

daveomri wants to merge 5 commits into
masterfrom
refactor/storage-json-mirror

Conversation

@daveomri

Copy link
Copy Markdown
Collaborator

Why

Part of #744: the storage and small-payload parts of the plan (its PR 1 without the binary paths). The MCP spec recommends that a tool returning structuredContent also return it serialized in a text block for backwards compatibility. These tools didn't do that: their content[0] was prose or partial JSON.

Remaining #744 work, as follow-up PRs:

  1. Binary get-key-value-store-record paths, after fix: Stop get-key-value-store-record from reading whole records #1870 lands. It rewrites those paths, and fix: Return a normal result for a missing key-value store record #1778 / feat: Accept runId in storage retrieval tools #1782 edit the same file.
  2. Large-payload tools, with response sizes measured first.

What changed

Before:

  • Storage tools (8): content[0] was the JSON of the data without summary / nextStep.
  • send-server-actor-request: the same, also without errorMessage.
  • search-actors(-widget), search-apify-docs, fetch-actor-mcp-tool-list, report-problem: content[0] was prose.

Now: content[0] is JSON.stringify of exactly the returned structuredContent, and the existing narrative, links and caveats follow as separate blocks. Storage goes through buildStorageResponse; the other tools are edited at their call sites. A shared rule in respondOk would have duplicated the JSON for the ~25 callers that already mirror, and would have changed the large-payload tools ahead of their measurement.

The text content of 13 tools changes, so internal's contract tests may need updating if they assert on content[0].

Notes for reviewers (human-written)

Proof it works

Each changed response has a test asserting that JSON.parse(content[0].text) deep-equals structuredContent. That's 12 new cases: buildStorageResponse() with and without nextStep, plus every return site of the other 6 tools, including results and no-results paths. All failed on master and pass now. Tests that read the narrative from content[0] now read it from content[1].

co-written with Claude Code.

@daveomri
daveomri requested a review from jirispilka November 12, 2026 09:54
@daveomri daveomri linked an issue Nov 12, 2026 that may be closed by this pull request
4 tasks
@daveomri daveomri self-assigned this Nov 12, 2026
@daveomri daveomri changed the title Refactor/storage json mirror refactor: storage json mirror Nov 19, 2026
@daveomri daveomri changed the title refactor: storage json mirror refactor: Return large tool payloads once, as the JSON mirror Nov 19, 2026
@daveomri daveomri changed the title refactor: Return large tool payloads once, as the JSON mirror refactor: Mirror structuredContent as JSON text in storage and search tools Nov 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

refactor: Mirror structuredContent as JSON text in every tool result

1 participant