feat(mcp): bound tool responses with queryable artifacts

[LevSky22]

Summary

• bound serialized MCP tool results before they enter model context
• keep small JSON results inline and store oversized JSON as opaque, expiring artifacts
• expose only query_response_artifact for model-facing artifact access; no raw payload reader is registered
• return bounded structuredContent under an explicit outputSchema
• provide optional protocol-native artifact descriptor links whose resource reads return bounded metadata, never the stored payload
• enforce one camelCase v3 contract across tool schemas, documentation, result metadata, cursors, and errors
• normalize response-root-relative paths with exact-first fallback
• infer one unambiguous collection and recover redundant collection prefixes in projected fields
• return structured, caller-correctable artifact query errors
• clarify that nested projected fields require a leading / and suggest the exact corrected pointer when it resolves
• refresh the branch onto upstream n8n-mcp v2.77.0 without rewriting PR history

Artifact query contract v3

query_response_artifact accepts an RFC 6901 responsePath, optional predicates, projected fields, pageSize, an opaque cursor, bounded textSearch, and describe.

Inputs are strictly camelCase. Snake_case aliases are rejected by the tool schema, giving clients immediate validation feedback instead of allowing two competing input conventions.

Paths resolve exactly first and then, when applicable, relative to a previously selected response root. This keeps RFC 6901 behavior deterministic while supporting a path such as /teams whether the stored artifact contains the full response envelope or the already-selected collection.

Projected root fields may use shorthand such as id. Nested paths must be RFC 6901 pointers beginning with /; for example, /parameters/jsCode. A value such as parameters/jsCode remains a literal root-key shorthand so keys containing / stay addressable. When that literal key is absent but the leading-slash pointer resolves, the error now suggests the exact correction rather than silently changing semantics.

When the selected object contains exactly one array, projection can infer that collection. If every requested field redundantly includes the same collection prefix, the query interprets those pointers relative to each item only after exact projection fails, preserves the requested output labels, and reports the inferred path and normalization warning. Mixed or ambiguous prefixes still fail closed.

For keyed objects such as n8n connections, objectMode: "entries" exposes { key, value } rows. Incorrect array-style queries return OBJECT_MODE_REQUIRED with a bounded suggested request. describe is pageable, and textSearch returns bounded match contexts.

Success and error results share the same structured envelope. responseMeta reports completeness, pagination, applied filters, field resolution, and artifact metadata. Recoverable failures include stable codes and bounded details so callers can correct paths, cursors, object modes, or expired handles without guessing.

Context safety

Large payloads remain behind the query-only boundary. Tool calls return selected structure, matches, fields, or pages rather than raw artifact bytes. Optional MCP resource reads return only a bounded descriptor capped at 8 KiB, so enabling resource-link support does not reintroduce the stored provider response into model context.

Cursors are authenticated and bound to the artifact, caller scope, and exact query view. Existing compact tool results remain backward compatible; only oversized artifact access uses the v3 query contract.

Verification

• npm run typecheck
• npm run build
• focused artifact-query and documentation suites: 130 passed
• complete unit suite on Node 22: 6,254 passed, 35 skipped, 0 failed
• coverage: 84.92% statements/lines, 86.36% branches, 84.71% functions
• live n8n integration suites were not run locally; they require a configured test instance

Conceived by Romuald Członkowski - www.aiadvisors.pl/en

[codecov]

Codecov Report

❌ Patch coverage is 93.68359% with 107 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/services/mcp-response-bounding.ts	93.40%	83 Missing and 9 partials ⚠️
src/mcp/server.ts	91.27%	14 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!