feat(indexing): index-json-documents takes a typed documents array

[adityamparikh]

Summary

index-json-documents took its documents as a JSON string, so the model had to escape every quote and newline of the payload inside a JSON string argument. On the 61-show sample that escaping is about 12% of the output tokens the model generates for the call, and one mis-escaped quote fails the whole call after the payload has been produced.

The parameter is now List<Map<String, Object>> documents, advertised in the tool schema as an array of objects. The model emits native JSON, the MCP client parses it once, and on the SDK 2.0 line (#23) the shape is validated before dispatch.

before:  {"collection":"shows","json":"[{\"id\":\"netflix-001\",\"title\":\"Stranger Things\",...}]"}
after:   {"collection":"shows","documents":[{"id":"netflix-001","title":"Stranger Things",...}]}

Server-side indexing time is unchanged — 61 documents take 0.1 s either way — so the whole saving is in what the model has to emit.

What changed

• JsonDocumentCreator.create(List<Map<String,Object>>) converts the list with one valueToTree call and hands it to the same flatten(JsonNode) / toDocument(JsonNode) walk create(String) uses, so both entry points flatten identically by construction (nested objects to a_b, arrays to multi-valued fields, nulls skipped). JsonDocumentCreatorTest pins that they produce the same documents.
• IndexingService.indexJsonDocuments takes the typed list; the tool description tells the model to pass the array itself, not a string. Empty/null input is rejected by the creator, which already owns that policy for every format.
• IndexTool in the index-data prompt now carries the canonical format name separately from the payload parameter name — the two were the same string until the JSON parameter was renamed to documents, and the prompt's opening line needs the format ("markdown" even when the caller passes md), not the parameter.
• Tests keep their JSON text blocks and parse them through a new TestDocuments.json(...) helper; the MCP-level tests send the array.
• README tool table.

Input size limits removed

Behavior change worth a reviewer's attention: the 10 MB input cap is gone from all four formats, not just JSON.

The typed documents array has no string form to measure, so the JSON tool path was already uncapped; adding a second limit to match would have meant maintaining the cap in two shapes. All four formats carried the same copy-pasted 10 * 1024 * 1024 constant and the same getBytes() length check, which materialised a second full copy of the payload purely to measure it, immediately before the parser read the string again — in two different layers (JSON/CSV/markdown in the creators, XML in the orchestrator) with two different message formats.

Payload size is now bounded by the heap and by whatever limit the transport in front of the server imposes. Blank/null validation is unchanged on every path and still covered. The one test that exercised a limit — testCreateSchemalessDocumentsFromXmlWithLargeDocument, which built a 12 MB document to assert the XML check fired — is removed with it.

Not changed

CSV, XML and Markdown stay strings: those formats have few quotes and no repeated keys, so a string is already their cheapest wire form.

Independent of #203 and #205; the three merge in any order.

Tests

./gradlew build (Java 25) and ./gradlew nativeTest -Pnative (GraalVM CE 25.0.2) are green; the generic List<Map> parameter deserialises natively without extra hints.

🤖 Generated with Claude Code