feat(nitro): add explicit tool result helper

[alesanGreat]

Linked issue

Closes #315

Description

Add an explicit toolResult() escape hatch for tools that intentionally return protocol fields while also declaring an outputSchema.

Today, outputSchema correctly takes precedence over protocol-looking object keys so domain schemas such as { content: string[] } remain valid. The missing case is an intentional CallToolResult: without an explicit signal, structuredContent + isError are interpreted as the domain object itself.

This change:

• adds toolResult() as an explicit, non-wire marker for intentional protocol results;
• preserves the existing behavior for all unmarked domain objects;
• allows content to be omitted when structuredContent is available, using Nitro's existing text fallback;
• documents structured in-band failures without changing the ordinary throw path;
• adds regression coverage and updates the public export snapshot;
• includes a minor changeset for nitro-mcp-toolkit.

Validation

Validated on the repository-pinned Node 24.18.0 with pnpm 11.17.0:

• git diff --check
• focused oxfmt --check on all changed package files: pass
• focused oxlint on changed TypeScript files: 0 errors (the existing triple-slash warning in src/runtime/index.ts remains)
• pnpm --filter nitro-mcp-toolkit run typecheck: pass
• pnpm --filter nitro-mcp-toolkit run build: pass
• focused tool + public-surface tests: 16/16 pass
• full coverage suite with a 60s hook timeout on this Windows machine: 22/22 test files, 122/122 tests; 96.55% statements, 92.99% branches. The default 10s run hit only the existing Nitro app build hook timeout; with a realistic local build allowance it passes unchanged.

I also captured the real MCP 2026-07-28 HTTP wire, before client decoding, for a structured success/failure pair. The SDK stamped resultType: "complete" on both responses and preserved explicit isError values. As an independent interoperability check, that pair conforms to QZX Result Contract v1 in its structural_core mode. This is validation only: the change adds no QZX dependency or runtime coupling.

Checklist

• I have linked an issue or discussion.
• I have added tests that prove the behavior.
• I have updated the documentation accordingly.
• I have added a changeset for the public API addition.

[vercel]

@alesanGreat is attempting to deploy a commit to the Nuxt Team on Vercel.

A member of the Team first needs to authorize it.

[github-actions]

Thank you for following the naming conventions! 🙏

[pkg-pr-new]

npm i https://pkg.pr.new/nitro-mcp-toolkit@318

npm i https://pkg.pr.new/@nuxtjs/mcp-toolkit@318

commit: 1f500a3