Skip to content

Server: add configurable unknown-field policy before tool argument coercion #858

Closed

Description

@bokelley

Problem

Server-side tool calls can currently pass through permissive SDK/FastMCP request models before adopter-specific strict models see the raw arguments. That can allow unknown top-level tool fields to be accepted or silently dropped, especially on MCP.

In salesagent this caused a regression where dev/CI no longer failed loudly for payloads such as:

{
  "brief": "test ads",
  "nonsense_field": "bar"
}

The local workaround in salesagent PR #603 adds pre-validation hooks that:

  • normalize legacy fields first
  • reject unknown top-level fields in non-production/dev mode
  • strip unsupported unknown fields in production/forward-compatible mode
  • cover advertised write tools such as create_media_buy, not only read tools

Why this belongs in the SDK

This is a generic transport-boundary concern, not a seller-specific business rule. The SDK already owns:

  • MCP/A2A dispatch
  • request validation hooks
  • generated tool schemas
  • canonical error envelopes

If the SDK handles this centrally, every adopter gets consistent behavior before permissive Pydantic models can swallow extras.

Suggested API

One possible shape:

from adcp.validation import UnknownFieldPolicy, ValidationHookConfig

serve(
    handler,
    validation=ValidationHookConfig(
        unknown_fields=UnknownFieldPolicy.REJECT,  # or STRIP / IGNORE
    ),
)

or a simpler top-level option:

serve(handler, unknown_fields="reject")  # "strip" / "ignore"

The key is that this should run before tool argument validation/coercion on both MCP and A2A.

Expected behavior

  • reject: fail loudly with canonical INVALID_REQUEST, including the unknown field path/name.
  • strip: remove unsupported unknown top-level fields before validation, for forward-compatible production deployments.
  • ignore: preserve current permissive behavior when adopters explicitly want it.
  • Behavior should be transport-consistent for MCP and A2A.
  • Regression tests should include mutating tools such as create_media_buy, because accepting unknown fields on write operations is the highest-risk path.

Reference

Salesagent fixed this locally in PR #603: bokelley/salesagent#603

Activity

  1. added
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on May 25, 2026
  2. bokelley commented on May 25, 2026

    @bokelley
    ContributorAuthor

    Triage

    Classification: Feature request
    Bucket(s): validation, handlers (no matching repo labels found)
    Status: ready-to-implement

    What the experts said:

    • code-reviewer: Extend ValidationHookConfig with unknown_fields: Literal["reject","strip","ignore"] | None = None; implement as a dedicated gate in create_tool_caller after the pre-validation hook stage — not via pre_validation_hook (which would silently collide with adopter-supplied hooks); regression tests for mutating tools (create_media_buy) are a hard requirement before merge.
    • dx-expert: Option B (extend ValidationHookConfig) is architecturally correct and consistent with the existing string-literal mode pattern across all 6+ factory entry points; document the distinction from ADCP_STRICT_VALIDATION (Pydantic model-level) vs. this new dispatcher gate, and record the SERVER_DEFAULT_VALIDATION default decision explicitly in the PR.

    My take: Both experts converge — non-breaking with unknown_fields defaulting to "ignore". MCP and A2A consistency is free since both dispatch through create_tool_caller.

    • src/adcp/validation/client_hooks.py — add UnknownFieldPolicy = Literal["reject", "strip", "ignore"] type alias and unknown_fields: UnknownFieldPolicy | None = None to ValidationHookConfig; export from validation/__init__.py. Leave SERVER_DEFAULT_VALIDATION unchanged.
    • src/adcp/server/mcp_tools.py — in create_tool_caller, insert a gate after pre_validation_hook and before schema validation: key-check params against the tool's inputSchema.properties; on reject raise ADCPTaskError(INVALID_REQUEST, "<tool>: unknown field 'X'. Known fields: …"); on strip delete in place. Do not thread via pre_validation_hook.
    • tests/ — reject and strip coverage for a mutating tool (create_media_buy) and a read tool; follow the _MinimalHandler fixture pattern in test_pre_validation_hooks.py.
    • Non-breaking: unknown_fields defaults to None/"ignore", matching current behavior; no existing ValidationHookConfig construction call requires updating.

    Triaged by Claude Code. Session: https://claude.ai/code/cse_017ePtG3abZUMNyA2c6cQLqT


    Generated by Claude Code

  3. added
    enhancementNew feature or request
    and removed
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on May 25, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions