MCP/client: bulk add sources — ADD_SOURCE accepts many specs in one call

Author: teng-linCreated Jul 18, 2026Updated Aug 12, 2026
LabelsP2

Live-verified on scratch notebooks (teng-lin-9414, torn down): ADD_SOURCE is genuinely batch-capable and unexposed. Companion to #1995 (bulk source delete).

Verified wire shape

Single (_source/add.py:475) puts one spec in params[0]; the backend accepts a list of specs:

python
specs = [[None, None, [url], None, None, None, None, None, None, None, 1] for url in urls]
params = [specs, notebook_id, build_template_block()]

✅ 3 URLs added in a single ADD_SOURCE call, all landed as sources.

Proposal

  • Client: sources.add_urls(nb_id, urls: list[str]) → one RPC. (Mixed spec types — url/text/youtube/drive — can batch later; start with URLs.)
  • MCP: plural mode on source_add (mirror source_wait/source_delete shape), returning a structured aggregate.
  • Highest-value bulk op — collapses the common "dump a reading list into a notebook" flow from N round-trips to one.

Notes

  • not_found/validation semantics differ from delete (these are creates) — return per-url created ids + any per-spec errors the batch reports.
  • New _idempotency_policy.py client-token slot (mirrors batch DELETE_LABEL).
  • ADR-0025 schema-char budget on the MCP side — trim docstrings, don't raise it.