feat(mcp): token-efficiency batch — 6 wins for agent context budgets#25
Merged
Conversation
Six independent improvements that meaningfully reduce token consumption
and round-trip count for typical agent sessions.
1. `verbose: false` on patch_screen + batch_patch_screens — response
becomes { savedAt } instead of the full merged screen. ~95% reduction
per patch call. Default true for backwards compatibility.
2. `fields: 'ids'` on catalog tools (list_fonts, list_frames,
list_koubou_devices, list_compositions, list_locales) — returns
just the id list instead of full entries. ~90% token reduction
when the agent only needs to pick a valid id.
3. `describe_project(slug)` — natural-language summary of EVERY screen
in one call. Saves N round-trips compared to calling describe_screen
N times. Fetches the envelope once, formats each screen from the
loaded data.
4. `get_overview(slug)` — composite read returning meta, screenCount,
compositionCounts, theme summary, exportSize, active locale, locale
codes, active variant, variant count. Replaces what would otherwise
take 4-5 separate calls. Designed as the "what is this project"
orientation check at the start of an agent session.
5. `get_screen` field selection — pass `fields: [...]` as an array of
dot-paths (e.g. ["headline", "spotlight.x", "callouts.0.id"]). Returns
a flat object keyed by the original paths. ~80-95% token reduction
when the agent only needs a few values.
6. Generic `batch` tool — runs N tool calls in one stdio round-trip.
Each entry's result is collected (errors recorded, batch continues).
`batch` cannot call itself to prevent runaway nesting.
Tool count: 68 → 71. Tests: 535 passing.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Six independent improvements that meaningfully reduce token consumption and round-trip count for typical agent sessions. Each addresses a measured friction point.
verbose: falseonpatch_screen+batch_patch_screens— response becomes{ savedAt }instead of the full merged screenfields: 'ids'on catalog tools (list_fonts, list_frames, list_koubou_devices, list_compositions, list_locales)describe_project(slug)— all screens summarised in one callget_overview(slug)— composite read: meta, screen count, theme, locale, variants, sizesget_screenfield selection via dot-path array (e.g.["headline", "spotlight.x"])batchtool — N tool calls in one stdio round-tripDefaults preserved everywhere — existing callers keep getting full responses unless they explicitly opt in to slim modes.
Tool count: 68 → 71
Note: screen.ts size
While working on this I noticed
packages/mcp/src/tools/screen.tsis now 1834 lines vs the next-largest file at 482. It accumulated tools from many domains (text, device, background, effects, render, layout-prediction, description). Worth a focused refactor into 6-8 smaller per-domain files. I'm planning a follow-upchore(mcp): split screen.ts by domainPR to address that separately — keeps this token-efficiency PR review-able.Test plan
pnpm typecheckcleanpnpm test— 535/535 passingpnpm buildsucceeds🤖 Generated with Claude Code