Skip to content

Conversation

@BaiyuScope3
Copy link
Collaborator

@BaiyuScope3 BaiyuScope3 commented Jan 8, 2026

Summary

This PR upgrades the adcp-client-python dependency to 2.18.0 and enhances the list_creative_formats tool to provide better human-readable output for LLM consumption.

Changes

1. Enhanced list_creative_formats Response

Added human-readable format details in the tool response content field
Each format now displays: name, ID, type, dimensions, description, required assets, optional assets, and supported macros
LLMs can now see full format specifications without needing structured data parsing

2. Upgraded to adcp-client-python 2.18.0

Updated dependency from adcp>=2.13.0 to adcp>=2.18.0
Migrated to new assets field (replaces deprecated assets_required)
Added create_asset() helper function returning the new Assets type
Backfill assets_required from assets for backward compatibility using get_required_assets() utility

3. Added Optional Impression Tracker Asset

Added create_impression_tracker_asset() helper for 3rd party tracking pixels
All formats (except VAST) now include an optional impression_tracker asset
VAST formats excluded as they have built-in tracking in the XML

4. Updated Server Utilities

_format_to_human_readable() now uses get_required_assets() and get_optional_assets() from adcp
Properly distinguishes between required and optional assets in output

5. Test Updates

Updated tests for PreviewRender which is now a RootModel (access via .root)
Updated tests for relaxed schema validation (additional fields now allowed)
Updated test_info_card_formats.py to verify new assets/assets_required structure

6. Bug Fix

Removed IMPRESSION_URL from COMMON_MACROS (not a universal macro)

Testing

All 256 tests pass ✅
Lint checks pass ✅

1. Test new assets discovery

image

2. Test improvement on LLM response

Before:
image
image

Now:
image

…esponse

LLMs only see the 'content' text field in MCP tool results, not the
'structured_content' field. This change includes human-readable format
details in the text content so Claude and other LLMs can see:

- Format name and ID
- Type and dimensions
- Supported macros (full list)
- Assets required
- Description

The structured_content still contains the full JSON for programmatic use.

Extracted _format_to_human_readable() helper function for reusability.
IMPRESSION_URL is not part of the universal macros specification.
@BaiyuScope3 BaiyuScope3 changed the title Fix/list formats include json in text feat: support 2.6.x adcp protocol, discover optional assets in the format Jan 8, 2026
- Upgrade adcp dependency to >=2.18.0
- Add new 'assets' field to all formats using create_asset() helper
- Add optional impression_tracker asset to all formats (except VAST)
- Backfill deprecated assets_required from assets using get_required_assets()
- Update server to use get_required_assets/get_optional_assets utilities
- Update tests for new schema (PreviewRender.root, relaxed field validation)
- Update test assertions for new assets/assets_required structure
@BaiyuScope3 BaiyuScope3 changed the title feat: support 2.6.x adcp protocol, discover optional assets in the format feat: Upgrade to adcp-client-python 2.18.0 and enhance list_creative_formats response Jan 9, 2026
@BaiyuScope3 BaiyuScope3 marked this pull request as ready for review January 9, 2026 18:31
Standard macros (included in `COMMON_MACROS`):
- Privacy: `GDPR`, `GDPR_CONSENT`, `US_PRIVACY`, `GPP_STRING`
- Tracking: `MEDIA_BUY_ID`, `CREATIVE_ID`, `IMPRESSION_URL`, `CLICK_URL`
- Tracking: `MEDIA_BUY_ID`, `CREATIVE_ID`, `CLICK_URL`
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMPRESSION_URL is not part of adcp universal macro

)


def _backfill_deprecated_assets_required() -> list[CreativeFormat]:
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

for backward compatibility, still populate assets_required fields extract from assets

"description": "Creative format specification with full details for detailed card",
},
),
create_impression_tracker_asset(),
Copy link
Collaborator Author

@BaiyuScope3 BaiyuScope3 Jan 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Impression Tracker Support by Format

Format ID Type Impression Tracker
display_generative display
display_300x250_generative display
display_728x90_generative display
display_320x50_generative display
display_160x600_generative display
display_336x280_generative display
display_300x600_generative display
display_970x250_generative display
display_image display
display_300x250_image display
display_728x90_image display
display_320x50_image display
display_160x600_image display
display_336x280_image display
display_300x600_image display
display_970x250_image display
display_html display
display_300x250_html display
display_728x90_html display
display_160x600_html display
display_336x280_html display
display_300x600_html display
display_970x250_html display
display_js display
video_standard video
video_dimensions video
video_standard_30s video
video_standard_15s video
video_1920x1080 video
video_1280x720 video
video_1080x1920 video
video_1080x1080 video
video_ctv_preroll_30s video
video_ctv_midroll_30s video
video_vast video
video_vast_30s video
native_standard native
native_content native
audio_standard_15s audio
audio_standard_30s audio
audio_standard_60s audio
dooh_billboard_1920x1080 dooh
dooh_billboard_landscape dooh
dooh_billboard_portrait dooh
dooh_transit_screen dooh
product_card_standard display
product_card_detailed display
format_card_standard display
format_card_detailed display

Summary:** 47/49 formats support optional impression_tracker. VAST formats excluded (built-in tracking).

- Replace manual assets_required iteration with get_format_assets() and get_required_assets()
- Utilities handle both new 'assets' and deprecated 'assets_required' fields automatically
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.

2 participants