Skip to content

fix(mcp): advertise precise object-rooted output schemas - #68

Merged
birdmanmandbir merged 6 commits into
mainfrom
fix/mcp-note-get-output-schema
Aug 12, 2026
Merged

fix(mcp): advertise precise object-rooted output schemas#68
birdmanmandbir merged 6 commits into
mainfrom
fix/mcp-note-get-output-schema

Conversation

@orga-agent

@orga-agent orga-agent Bot commented Aug 12, 2026

Copy link
Copy Markdown
Contributor

Problem

mcporter rejects the flicknote MCP server's tools/list because derived output schemas contain terms strict clients cannot parse:

  • note_get's metadata field (Option<serde_json::Value>) derives a boolean schema term "metadata": true.
  • note_source's SourceResult enum derives a oneOf union without an explicit object root.

Earlier coarse fixes (e2fd1b5, #67; and the first commit here) replaced these with {"type":"object"}, which satisfies strict clients but discards the useful output contract: clients could no longer discover fields, required values, collection shapes, or source-view variants.

Fix

Compatibility is fixed at the narrow incompatible parts instead of erasing each schema:

  • note_get: keep the full generated schema; metadata uses an object-form JSON Schema term that keeps arbitrary JSON (and null from Option) representable.
  • note_source: new MCP boundary DTO McpSourceResult (transparent over SourceResult, serialization unchanged) advertises an object-rooted tagged union with rendered/raw/info variants, each variant's discriminator and required fields, and an object-form term for the arbitrary raw value.
  • List tools: unchanged object wrappers with notes/projects array item schemas.
  • Removed the generic minimal-object output_schema override; schemas now follow MCP boundary DTOs.

Tests

  • mcp_tool_output_schemas_are_strict_client_compatible: every tool's outputSchema has an explicit object root and no boolean schema terms; list tools advertise wrapper + item schemas.
  • mcp_note_get_output_schema_advertises_detail_structure: content/metadata/extractions/sections present and required; metadata is object-form and represents arbitrary JSON incl. null.
  • mcp_note_source_output_schema_advertises_all_views: all three views with discriminators and variant-specific fields.
  • Existing tool-call tests (note detail, source views, projects) verify structuredContent still matches.

Verification

  • cargo test --bin flicknote — 51 tests pass.
  • cargo clippy --workspace --all-targets --all-features -- -D warnings clean.
  • cargo fmt --all --check clean.
  • End-to-end stdio probe of built flicknote mcp: 25 tools, note_get.metadata object-form, note_source object-rooted with views rendered/raw/info, zero strict-client violations.

@orga-agent orga-agent Bot changed the title fix(mcp): emit spec-compliant outputSchema for note_get fix(mcp): advertise precise object-rooted output schemas Aug 12, 2026
@birdmanmandbir
birdmanmandbir merged commit ab31ed2 into main Aug 12, 2026
9 checks passed
@orga-agent
orga-agent Bot deleted the fix/mcp-note-get-output-schema branch August 12, 2026 08:39
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.

1 participant