feat(core): SEP-2356 TransferModes field + Phase 3 upload-mode plan

[panyam]

Summary

• Code: add core.FileInputTransferMode typed enum (constants Inline + Upload) and an optional TransferModes []FileInputTransferMode field on core.FileInputDescriptor, aligning the descriptor with SEP-2631's 2026-05-07 harmonize commit (modelcontextprotocol/specification PR 2631 commit 41517ea). Forward-compat plumbing only — the validator still only validates inline data URIs, and a descriptor restricting to transferModes: [\"upload\"] is well-formed but unsatisfiable by an mcpkit client today.
• Tests: extend the marshal round-trip case + add TestExtractFileInputDescriptorTransferModesShapes covering the three input shapes ([]any, []string, []FileInputTransferMode). Phase 1 suite continues to pass.
• Plan doc: add Phase 3 — upload-mode transfer to docs/SEP_2356_FILE_INPUTS_PLAN.md with the implementation layer breakdown and 10 open design questions for the WG (covering FileValue scope, transfer-mode selection, capability layering, file URI scheme, storage lifetime, upload auth, streaming, error reasons, cap gating).
• Capabilities surface: CAPABILITIES.md mcp-file-inputs-experimental row updated to list the new field.

Why now

SEP-2631 is OPEN and still iterating. The descriptor-shape changes from the harmonize commit are stable enough to track today (the field name lock — transferModes, the enum values — inline / upload, and the omit-when-unset semantics). The protocol-side parts (files/prepareUpload, storage abstraction, HTTPS upload endpoint) are precisely what the SEP says least about and stays deferred — the Phase 3 section captures the layer breakdown so the work can pick up cleanly when 2631 lands.

The Phase 3 design-questions section is structured to seed WG-facing engagement: each question records mcpkit's recommendation grounded in the existing surface, so the conversation has concrete starting points rather than blank slates.

Test plan

• go test ./core/ -count=1 — green.
• Marshal round-trip with TransferModes: [\"inline\",\"upload\"] produces the expected JSON.
• Empty descriptor still serializes to {}.
• omitempty on transferModes confirmed via descriptor without the field.
• descriptorFromMap accepts []any (json.Unmarshal default), []string, and []FileInputTransferMode.
• All pre-existing Phase 1 tests (validator, schema-helper, capability gating, strip-keyword, JSON round-trip) still pass.

Out of scope

• Validator enforcement of TransferModes (rejecting inline values when descriptor restricts to ["upload"], etc.). Lands as part of Phase 3 when upload mode is implemented end-to-end.
• ClientCapabilities.Files.{Upload,Download} cap fields, files/prepareUpload / files/getDownload RPC methods, FileStore abstraction, HTTP upload endpoint, browser-side bridge upload. All deferred to Phase 3.
• Updating mcpconformance with upload-mode scenarios. Inline scenarios on the pending branch stay as-is; upload scenarios get added when the wire shape stops moving.

References

• modelcontextprotocol/specification PR 2356 (SEP-2356, in-review)
• modelcontextprotocol/specification PR 2631 (SEP-2631, OPEN, in-flux)
• mcpkit issue 313 (SEP-2356 umbrella)