feat: add Data Extraction tools (parse_document, extract_fields)

[jdrhyne]

Why

Agents need structured document data — typed elements with coordinates, tables,
key/value regions, confidence — not a wall of text. This exposes the Nutrient DWS
Data Extraction API as MCP tools, shaped so a large extraction never has to
land in the conversation.

What's added

Two tools, mapping 1:1 onto the two Data Extraction endpoints:

• parse_document (POST /extraction/parse) — parse a whole document by
  mode (text / structure / understand / agentic). Spatial output (typed
  elements with bounding boxes, confidence, reading order) is written to
  outputPath and summarized inline; markdown is returned inline, or to a file.
  Ask for both formats in one call — the second is billed at no extra cost.
• extract_fields (POST /extraction/extract) — hand it a JSON schema, get
  back just those values, each with a per-field citation. A grounding summary
  flags fields that came back not_found, so a confident extraction is
  distinguishable from a guess.

Authentication (the main thing to review)

Data Extraction is a separate product/tenant with its own credit balance, which
drives the credential model. A single DwsApiClient resolves the right credential
per request — keyed by the endpoint's product — behind a CredentialProvider:

• OAuth (recommended, nothing extra to configure): one product:all token
  covers both products.
• Static keys: a Processor key is tenant-bound and can't authenticate
  extraction, so extraction needs its own NUTRIENT_DWS_EXTRACTION_API_KEY.
  Setting only that key runs the server in extraction-only mode (Processor
  tools return a clear error). Any static key ⇒ static mode — the server never
  silently falls back to the OAuth browser flow.
• A rejected static key fails fast (it can't be refreshed); a 401 under OAuth
  refreshes the token once and retries.

Design notes worth a look

• Context safety: large spatial output and citations go to a file; inline
  summaries are content-free (counts, confidence, page geometry — no document
  text). Markdown honors outputPath for the same reason.
• Billing-safe by construction: everything cheap is checked before the
  billable call (sandbox resolution; a same-path guard so the source is never
  overwritten; format/mode compatibility). Nothing is written on a non-extraction
  2xx, and a filesystem failure after a billed call is reported as "billed" —
  not as a retryable error.
• Version-pinned: requests send x-nutrient-api-version, so results don't
  drift with the age of the API key.
• Costs surfaced: each result reports credits used + remaining (named as the
  Data Extraction balance, distinct from the Processor credits check_credits
  reports), plus the parse/extract split.
• Uploads survive a token refresh: multipart bodies are buffered so the
  401-retry replays the file rather than a consumed stream (affects every upload
  tool).

Out of scope

• Run-history / share endpoints (GET/DELETE /extraction/runs) — a follow-up.
• storeRun is intentionally not exposed: there's no tool to retrieve a stored
  run by runId, so offering it would advertise a capability that isn't there.

[jdrhyne]

U0 — live /extraction/parse verification (do before merge)

The handlers are built against Nutrient's published Data Extraction schema, but no live call has run yet (no key was available during development). One real request confirms the response shape and gives us a recorded fixture. Costs ~2–3 credits total.

Steps

# 1. Set the Data Extraction key (SEPARATE from NUTRIENT_DWS_API_KEY; starts with pdf_live_)
export NUTRIENT_EXTRACTION_API_KEY=pdf_live_...   # or add to .env (gitignored)

# 2a. Spatial (structure mode, ~1.5 credits) — confirms the element schema
curl -sS -X POST https://api.nutrient.io/extraction/parse \
  -H "Authorization: Bearer $NUTRIENT_EXTRACTION_API_KEY" \
  -F "file=@tests/assets/example.pdf" \
  -F 'instructions={"mode":"structure","output":{"format":"spatial"}}' \
  | tee tests/fixtures/extraction-spatial-sample.json | jq '.output.elements[0], .metrics'

# 2b. Markdown (text mode, ~1 credit)
curl -sS -X POST https://api.nutrient.io/extraction/parse \
  -H "Authorization: Bearer $NUTRIENT_EXTRACTION_API_KEY" \
  -F "file=@tests/assets/example.pdf" \
  -F 'instructions={"mode":"text","output":{"format":"markdown"}}' \
  | jq '.output | keys'

Acceptance criteria — the code reads exactly these paths (src/dws/extract.ts)

• Spatial: output.elements is an array; each element has type, confidence, bounds.{x,y,width,height}, page.pageIndex. metrics.pagesProcessed is present.
  • summarizeSpatial uses element.type / element.confidence / element.page.pageIndex / metrics.pagesProcessed
  • query_extraction filters on element.bounds / confidence / page.pageIndex / type
• Markdown: response has output.markdown (string).

If the field names match → no code change needed; just drop the captured response into tests/fixtures/ and (optionally) swap the inline fixture in tests/extract.test.ts for it, then this is release-ready.

If anything differs → adjust the SpatialElement / ExtractionResponse types and the filter/summary field access in src/dws/extract.ts (and the instructions shape if options.language / output.includeWords placement differs from the docs).

Tracked as U0 in docs/plans/2026-06-07-001-feat-dws-data-extraction-workflow-plan.md.

[HungKNguyen]

Approving. The per-request credential routing is the right design and it's well-tested (product-keyed 401 re-resolution, static-key fail-fast, extraction-only/processor-only gating). A few non-blocking follow-ups — none need to hold the merge:

1. product:all scope invalidates every existing cached OAuth credential (credential-provider.ts, nutrient-oauth.ts)
OAuth now requests ['mcp:invoke','product:all','offline_access'], and coversRequestedScopes nulls any cache lacking product:all — i.e. every currently-cached user. Next request forces a full browser re-auth, which is a silent break on headless/CI OAuth deployments until someone re-consents. Please add a release/upgrade note. (Secondary: exchangeCodeForToken records the requested scopes, not the server-granted ones — if the authz server ever narrows product:all, the cache would claim a scope it doesn't hold.)

2. formats not deduped/normalized (parse.ts)
["spatial","spatial"] is forwarded verbatim and only rejected by the API after local checks pass (wasted round trip). [...new Set(formats)] + a length check catches it locally.

3. Malformed-2xx messaging (low likelihood) (parse.ts)
When a "both" request returns 2xx with elements but no markdown, the handler returns a bare Error: … Nothing was written. I checked the DWS backend: "both" is one Maestro pass returning both artifacts, so this only happens on a partial/malformed 2xx — not reachable via valid input. But since the extraction was billed there and the client already models billed-write failures, consider routing missing-expected-field-on-2xx through that same billed messaging rather than a bare (retry-inviting) error.

Nit: writeToResolvedPath does fs.access then fs.mkdir(recursive) — the probe is redundant since mkdir is recursive; drop it.