Skip to content

fix: return object-shaped structuredContent from list tools #3574

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
gdut4140 wants to merge 4 commits into
base: main
Choose a base branch
from
+331 −242
Open

fix: return object-shaped structuredContent from list tools #3574

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
3a976ed
fix(structured-content): envelope array tool outputs in objects
gdut4140 Oct 24, 2026
b3108e4
test: expect object envelopes for array tool outputs
gdut4140 Oct 24, 2026
f3b0bac
test: regenerate list_commits snapshot for object envelope
gdut4140 Oct 24, 2026
0869a81
docs: describe object envelopes for list tool outputs
gdut4140 Oct 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -636,6 +636,8 @@ Structured repository results use compact DTOs rather than raw REST objects. Rel

For `get_repository_tree`, `list_gists`, `get_gist`, `create_gist`, and `update_gist`, gist results retain file names, contents, sizes, language/type information, timestamps, visibility, and compact owner profiles, while omitting API/node and Git transport URLs. Tree entries omit their derivable API URLs. Create/update gist results contain the gist ID and HTML URL. Modern JSON text and structured content serialize the same compact result. Older or unknown protocol versions retain byte-for-byte legacy text without an output schema or structured content.

List-returning tools `list_commits` and the `pull_request_read` methods `get_files`, `get_commits`, `get_reviews`, and `get_comments` expose their arrays inside a named object field (`commits`, `files`, `reviews`, `comments`) because MCP requires `structuredContent` to be a JSON object rather than a top-level array. Modern JSON text serializes the same object; older and unknown protocol versions keep the bare array text unchanged.

The issue metadata (`list_issue_types`, `list_issue_fields`), comment (`add_issue_comment`, `update_issue_comment`), dependency (`issue_dependency_read`, `issue_dependency_write`), and duplicate-detection (`find_duplicate`) tools provide typed `outputSchema` and `structuredContent` for negotiated supported protocol versions `2026-07-28` or newer. Older or unknown protocol versions retain the same text responses without these fields. Tool errors do not return structured content. Dependency and duplicate-detection tools retain their existing feature gates.

For negotiated supported protocol versions `2026-07-28` or newer, the consolidated Actions tools (`actions_list`, `actions_get`, `actions_run_trigger`) return structured objects with a `method` discriminant and a method-specific typed field; JSON text contains the same compact projection. Workflow, job, and artifact projections omit API/hypermedia URLs while retaining browser links and useful identifiers, states, timestamps, and usage durations. Run usage lists billable runner environments in deterministic name order. Older and unknown-protocol text responses remain unchanged; `get_job_logs` retains its typed content, URL, or failed-job collection variants.
Expand Down
5 changes: 5 additions & 0 deletions docs/typed-tool-schemas.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,11 @@ malformed versions also retain the legacy text result. Normal `Inventory.Registe
protocol era is already known before server construction, such as a stateless
request-scoped server.

The MCP schema for `structuredContent` is an object, so a typed output must not
be a top-level array. Wrap list results in a named field (for example
`ListCommitsOutput{Commits: [...]}`) and give the output schema the matching
object shape; the handler text may still be a bare array for legacy clients.

If a handler intentionally returns non-JSON text or content blocks, set
`PreserveHandlerContent` in `TypedSchemaOptions`, or call
`inventory.PreserveToolHandlerContent(ctx)` from the handler middleware for
Expand Down
Loading