From e1c9f67c1f23a3bce10492e86a6998da0fd8c786 Mon Sep 17 00:00:00 2001 From: Eric Hare Date: Thu, 5 Nov 2026 10:46:57 -0800 Subject: [PATCH 1/4] fix: describe accepted MCP update syntax in tool schemas --- .../command/clause/update/UpdateClause.java | 89 ++++++- .../command/clause/update/UpdateOperator.java | 42 +++- .../v1/mcp/McpOpenApiSchemaAdapterTest.java | 23 ++ .../api/v1/mcp/McpSchemaIntegrationTest.java | 49 ++++ .../v1/mcp/McpUpdateSchemaContractTest.java | 234 ++++++++++++++++++ 5 files changed, 419 insertions(+), 18 deletions(-) create mode 100644 src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpUpdateSchemaContractTest.java diff --git a/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/clause/update/UpdateClause.java b/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/clause/update/UpdateClause.java index aa8c314757..f3d9bcabdf 100644 --- a/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/clause/update/UpdateClause.java +++ b/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/clause/update/UpdateClause.java @@ -9,6 +9,7 @@ import java.util.stream.Collectors; import org.eclipse.microprofile.openapi.annotations.enums.SchemaType; import org.eclipse.microprofile.openapi.annotations.media.Schema; +import org.eclipse.microprofile.openapi.annotations.media.SchemaProperty; /** * Value type read from incoming JSON and used for resolving into actual {@link UpdateOperation}s @@ -16,16 +17,94 @@ */ @JsonDeserialize(using = UpdateClauseDeserializer.class) @Schema( + name = "UpdateClause", type = SchemaType.OBJECT, implementation = Object.class, - examples = - """ + additionalProperties = Schema.False.class, + description = + "A Data API update object mapping operators such as $set and $unset to objects of document paths and values. Operators may be combined on distinct paths. Tables support only $set, $unset, $push, and $pullAll; collections support every operator except $pullAll.", + properties = { + @SchemaProperty( + name = UpdateOperator.Names.SET, + type = SchemaType.OBJECT, + description = + "Sets paths to JSON values, including null, arrays, objects, and extended JSON."), + @SchemaProperty( + name = UpdateOperator.Names.SET_ON_INSERT, + type = SchemaType.OBJECT, + description = "Sets paths only when an upsert inserts a document."), + @SchemaProperty( + name = UpdateOperator.Names.UNSET, + type = SchemaType.OBJECT, + description = "Removes paths. The values supplied for them are ignored."), + @SchemaProperty( + name = UpdateOperator.Names.INC, + type = SchemaType.OBJECT, + description = "Maps paths to numeric increments, including fractions."), + @SchemaProperty( + name = UpdateOperator.Names.MUL, + type = SchemaType.OBJECT, + description = "Maps paths to numeric multipliers, including fractions."), + @SchemaProperty( + name = UpdateOperator.Names.MIN, + type = SchemaType.OBJECT, + description = "Updates paths when the supplied values are smaller."), + @SchemaProperty( + name = UpdateOperator.Names.MAX, + type = SchemaType.OBJECT, + description = "Updates paths when the supplied values are larger."), + @SchemaProperty( + name = UpdateOperator.Names.RENAME, + type = SchemaType.OBJECT, + description = "Maps existing paths to new path strings."), + @SchemaProperty( + name = UpdateOperator.Names.CURRENT_DATE, + type = SchemaType.OBJECT, + description = "Sets paths to the current date using true or {\"$type\": \"date\"}."), + @SchemaProperty( + name = UpdateOperator.Names.POP, + type = SchemaType.OBJECT, + description = "Removes the first (-1) or last (1) element of arrays."), + @SchemaProperty( + name = UpdateOperator.Names.PUSH, + type = SchemaType.OBJECT, + description = + "Appends values to arrays, or to list, set, and map columns. Use $each for multiple values; only collections accept $position."), + @SchemaProperty( + name = UpdateOperator.Names.ADD_TO_SET, + type = SchemaType.OBJECT, + description = "Adds unique array values. Use {\"$each\": [...]} for multiple values."), + @SchemaProperty( + name = UpdateOperator.Names.PULL_ALL, + type = SchemaType.OBJECT, + description = + "Tables only. Removes the listed values from list and set columns, and the listed keys from map columns.") + }, + examples = { + """ { "$set" : {"location": "New York"}, - "$unset" : {"new_data": 1} + "$unset" : {"obsolete": 1} } - """) -public record UpdateClause(EnumMap updateOperationDefs) { + """, + """ + {"$inc": {"score": 0.25}, "$mul": {"price": 1.5}, + "$min": {"lowest": 2.5}, "$max": {"highest": 9.5}} + """, + """ + {"$push": {"items": {"$each": [1, 2], "$position": 0}}, + "$addToSet": {"tags": {"$each": ["a", "b"]}}, + "$pop": {"history": -1}, "$rename": {"oldName": "newName"}} + """, + """ + {"$currentDate": {"updated": true}, + "$setOnInsert": {"created": {"$date": 123456}}, "$set": {"optional": null}} + """, + "{}" + }) +// Hide parsed operations from schemas without changing Jackson serialization. +public record UpdateClause( + @Schema(hidden = true) EnumMap updateOperationDefs) { /** * Method that will validate update operation definitions of the clause and construct an ordered * set of {@link UpdateOperation}s. diff --git a/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/clause/update/UpdateOperator.java b/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/clause/update/UpdateOperator.java index f9920aab0e..a05cefbef8 100644 --- a/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/clause/update/UpdateOperator.java +++ b/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/clause/update/UpdateOperator.java @@ -7,83 +7,83 @@ /** List of update operator that's supported in update. */ public enum UpdateOperator { - ADD_TO_SET("$addToSet") { + ADD_TO_SET(Names.ADD_TO_SET) { @Override public UpdateOperation resolveOperation(ObjectNode arguments) { return AddToSetOperation.construct(arguments); } }, - CURRENT_DATE("$currentDate") { + CURRENT_DATE(Names.CURRENT_DATE) { @Override public UpdateOperation resolveOperation(ObjectNode arguments) { return CurrentDateOperation.construct(arguments); } }, - INC("$inc") { + INC(Names.INC) { @Override public UpdateOperation resolveOperation(ObjectNode arguments) { return IncOperation.construct(arguments); } }, - MAX("$max") { + MAX(Names.MAX) { @Override public UpdateOperation resolveOperation(ObjectNode arguments) { return MinMaxOperation.constructMax(arguments); } }, - MIN("$min") { + MIN(Names.MIN) { @Override public UpdateOperation resolveOperation(ObjectNode arguments) { return MinMaxOperation.constructMin(arguments); } }, - MUL("$mul") { + MUL(Names.MUL) { @Override public UpdateOperation resolveOperation(ObjectNode arguments) { return MulOperation.construct(arguments); } }, - POP("$pop") { + POP(Names.POP) { @Override public UpdateOperation resolveOperation(ObjectNode arguments) { return PopOperation.construct(arguments); } }, - PUSH("$push") { + PUSH(Names.PUSH) { @Override public UpdateOperation resolveOperation(ObjectNode arguments) { return PushOperation.construct(arguments); } }, - RENAME("$rename") { + RENAME(Names.RENAME) { @Override public UpdateOperation resolveOperation(ObjectNode arguments) { return RenameOperation.construct(arguments); } }, - SET("$set") { + SET(Names.SET) { @Override public UpdateOperation resolveOperation(ObjectNode arguments) { return SetOperation.constructSet(arguments); } }, - SET_ON_INSERT("$setOnInsert") { + SET_ON_INSERT(Names.SET_ON_INSERT) { @Override public UpdateOperation resolveOperation(ObjectNode arguments) { return SetOperation.constructSetOnInsert(arguments); } }, - UNSET("$unset") { + UNSET(Names.UNSET) { @Override public UpdateOperation resolveOperation(ObjectNode arguments) { return UnsetOperation.construct(arguments); @@ -92,7 +92,23 @@ public UpdateOperation resolveOperation(ObjectNode arguments) { // Then operators that we recognize but do not (yet) support - PULL_ALL("$pullAll"); + PULL_ALL(Names.PULL_ALL); + + public interface Names { + String ADD_TO_SET = "$addToSet"; + String CURRENT_DATE = "$currentDate"; + String INC = "$inc"; + String MAX = "$max"; + String MIN = "$min"; + String MUL = "$mul"; + String POP = "$pop"; + String PUSH = "$push"; + String RENAME = "$rename"; + String SET = "$set"; + String SET_ON_INSERT = "$setOnInsert"; + String UNSET = "$unset"; + String PULL_ALL = "$pullAll"; + } private String apiName; diff --git a/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpOpenApiSchemaAdapterTest.java b/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpOpenApiSchemaAdapterTest.java index b093b66e99..d29fd2df1a 100644 --- a/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpOpenApiSchemaAdapterTest.java +++ b/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpOpenApiSchemaAdapterTest.java @@ -297,6 +297,29 @@ void shouldEscapeComponentNamesInReferences() { assertEquals("#/components/schemas/A~1B~0C", McpOpenApiSchemaAdapter.componentRef("A/B~C")); } + @Test + void shouldPreserveFractionalSchemaBoundsAndDefault() throws Exception { + var document = fixtureDocument(); + ((ObjectNode) document.path("components").path("schemas")) + .putObject("Fractional") + .put("type", "number") + .put("minimum", 0.25) + .put("maximum", 1.75) + .put("default", 0.5); + var schema = + bundle(MAPPER.readTree("{\"$ref\":\"#/components/schemas/Fractional\"}"), document); + var component = schema.at(schema.path("$ref").asText().substring(1)); + + assertEquals(0.25, component.path("minimum").doubleValue()); + assertEquals(1.75, component.path("maximum").doubleValue()); + assertEquals(0.5, component.path("default").doubleValue()); + assertAccepts(schema, "0.25"); + assertAccepts(schema, "1.75"); + assertAccepts(schema, component.path("default").toString()); + assertRejects(schema, "0.125"); + assertRejects(schema, "1.875"); + } + /** Bundles a copy of {@code input}, so tests can compare the result with the input. */ private static ObjectNode bundle(JsonNode input, JsonNode document) { ObjectNode schema = input.deepCopy(); diff --git a/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpSchemaIntegrationTest.java b/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpSchemaIntegrationTest.java index 6ad33411b8..b6c2c243f5 100644 --- a/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpSchemaIntegrationTest.java +++ b/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpSchemaIntegrationTest.java @@ -12,7 +12,10 @@ import io.quarkus.test.junit.TestProfile; import io.stargate.sgv2.jsonapi.testresource.NoGlobalResourcesTestProfile; import io.vertx.core.json.JsonObject; +import java.util.HashSet; import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.ValueSource; /** Checks the schemas clients receive from the packaged application's tools/list endpoint. */ @QuarkusIntegrationTest @@ -149,6 +152,52 @@ void findAndRerankPreservesNestedConstraints() { .thenAssertResults(); } + @ParameterizedTest + @ValueSource(strings = {"updateOne", "updateMany", "findOneAndUpdate"}) + void updateToolsAdvertiseAcceptedOperatorSyntax(String tool) { + mcpClient + .when() + .toolsList( + page -> { + var schema = schemaFor(page, tool); + var document = json(page.findByName(tool).inputSchema()); + var update = document.path("properties").path("update"); + var visited = new HashSet(); + while (update.has("$ref")) { + var reference = update.path("$ref").asText(); + assertTrue(reference.startsWith("#/"), reference); + assertTrue(visited.add(reference), "Circular update schema reference"); + update = document.at(reference.substring(1)); + assertFalse(update.isMissingNode(), reference); + } + var examples = update.path("examples"); + assertFalse(examples.isEmpty(), "Update tools must advertise usable examples"); + var arguments = + new JsonObject() + .put("keyspace", "default_keyspace") + .put("collection", "schema_test"); + for (var example : examples) { + arguments.put("update", new JsonObject(example.toString())); + assertAccepts(schema, arguments); + assertAccepts(schema, arguments.copy().putNull("filter")); + } + for (var malformed : + new String[] { + "{\"updateOperationDefs\":{}}", + "{\"$unknown\":{}}", + "{\"$set\":null}", + "{\"$set\":5}", + "{\"$set\":[]}" + }) { + assertRejects(schema, arguments.copy().put("update", new JsonObject(malformed))); + } + arguments.remove("update"); + assertRejects(schema, arguments); + assertRejects(schema, arguments.copy().putNull("update")); + }) + .thenAssertResults(); + } + private static JsonSchema schemaFor(ToolsPage page, String name) { var tool = page.findByName(name); assertNotNull(tool, name); diff --git a/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpUpdateSchemaContractTest.java b/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpUpdateSchemaContractTest.java new file mode 100644 index 0000000000..3735e8a286 --- /dev/null +++ b/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpUpdateSchemaContractTest.java @@ -0,0 +1,234 @@ +package io.stargate.sgv2.jsonapi.api.v1.mcp; + +import static io.restassured.RestAssured.given; +import static org.junit.jupiter.api.Assertions.*; + +import com.fasterxml.jackson.databind.JsonNode; +import com.fasterxml.jackson.databind.ObjectMapper; +import com.fasterxml.jackson.databind.node.ObjectNode; +import com.networknt.schema.JsonSchemaFactory; +import com.networknt.schema.SpecVersion; +import io.quarkiverse.mcp.server.GlobalInputSchemaGenerator; +import io.quarkiverse.mcp.server.ToolManager; +import io.quarkus.test.junit.QuarkusTest; +import io.quarkus.test.junit.TestProfile; +import io.stargate.sgv2.jsonapi.api.model.command.Command; +import io.stargate.sgv2.jsonapi.api.model.command.Updatable; +import io.stargate.sgv2.jsonapi.api.model.command.clause.update.UpdateClause; +import io.stargate.sgv2.jsonapi.api.model.command.clause.update.UpdateOperator; +import io.stargate.sgv2.jsonapi.exception.UpdateException; +import io.stargate.sgv2.jsonapi.testresource.NoGlobalResourcesTestProfile; +import jakarta.inject.Inject; +import jakarta.validation.Validator; +import java.util.HashSet; +import java.util.List; +import java.util.Set; +import java.util.stream.Stream; +import java.util.stream.StreamSupport; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.Arguments; +import org.junit.jupiter.params.provider.EnumSource; +import org.junit.jupiter.params.provider.MethodSource; +import org.junit.jupiter.params.provider.ValueSource; + +/** Checks update arguments advertised by the registered tools against the real command parser. */ +@QuarkusTest +@TestProfile(NoGlobalResourcesTestProfile.Impl.class) +class McpUpdateSchemaContractTest { + private static final List TOOLS = List.of("updateOne", "updateMany", "findOneAndUpdate"); + + @Inject ObjectMapper objectMapper; + @Inject GlobalInputSchemaGenerator schemaGenerator; + @Inject ToolManager toolManager; + @Inject Validator validator; + + @ParameterizedTest + @ValueSource(strings = {"updateOne", "updateMany", "findOneAndUpdate"}) + void advertisedExamplesValidateAndBuild(String tool) throws Exception { + var schema = inputSchema(tool); + var examples = updateSchema(schema).path("examples"); + assertFalse(examples.isEmpty(), "Update arguments must advertise usable examples"); + for (var update : examples) { + var payload = toolInput(update); + assertSchemaAccepts(schema, payload); + assertNotNull(parseCommand(tool, payload).updateClause().buildOperations()); + } + } + + @ParameterizedTest + @MethodSource("supportedUpdates") + void toolSchemasAcceptSupportedUpdates(String tool, String json) throws Exception { + var payload = toolInput(objectMapper.readTree(json)); + assertSchemaAccepts(inputSchema(tool), payload); + assertNotNull(parseCommand(tool, payload).updateClause().buildOperations()); + } + + static Stream supportedUpdates() { + // Nonempty arguments exercise each operation's parser, including supported array modifiers. + var updates = + List.of( + "{}", + "{\"$set\": {}}", + "{\"$set\": {\"profile.name\": \"Ada\", \"optional\": null}}", + "{\"$unset\": {\"obsolete\": null}}", + "{\"$setOnInsert\": {\"created\": true}}", + "{\"$inc\": {\"score\": 0.25}}", + "{\"$mul\": {\"score\": 1.5}}", + "{\"$min\": {\"score\": 2.5}}", + "{\"$max\": {\"score\": 9.5}}", + "{\"$rename\": {\"oldName\": \"newName\"}}", + "{\"$currentDate\": {\"updated\": true, \"reviewed\": {\"$type\": \"date\"}}}", + "{\"$pop\": {\"first\": -1, \"last\": 1}}", + "{\"$push\": {\"items\": {\"$each\": [1, 2], \"$position\": 0}}}", + "{\"$addToSet\": {\"tags\": {\"$each\": [\"a\", \"b\"]}}}", + """ + {"$set": {"created": {"$date": 123456}, + "owner": {"$uuid": "550e8400-e29b-41d4-a716-446655440000"}, + "nested": {"values": [null, true, 1.25, {"name": "Ada"}]}}, + "$unset": {"obsolete": 1}} + """); + return TOOLS.stream().flatMap(tool -> updates.stream().map(json -> Arguments.of(tool, json))); + } + + @ParameterizedTest + @MethodSource("invalidUpdates") + void toolSchemasRejectMalformedUpdates(String tool, String json) throws Exception { + var update = objectMapper.readTree(json); + assertSchemaRejects(inputSchema(tool), toolInput(update)); + assertThrows(UpdateException.class, () -> objectMapper.treeToValue(update, UpdateClause.class)); + } + + static Stream invalidUpdates() { + var updates = + List.of( + "[]", + "5", + "\"update\"", + "{\"name\": \"Ada\"}", + "{\"updateOperationDefs\": {}}", + "{\"$unknown\": {}}", + "{\"$set\": null}", + "{\"$set\": 5}", + "{\"$set\": []}", + "{\"$set\": \"value\"}"); + return TOOLS.stream().flatMap(tool -> updates.stream().map(json -> Arguments.of(tool, json))); + } + + // updateOne is the only update tool that also serves tables. + @Test + void updateOneAcceptsTableOnlyPullAll() throws Exception { + var payload = toolInput(objectMapper.readTree("{\"$pullAll\": {\"listColumn\": [1]}}")); + assertSchemaAccepts(inputSchema("updateOne"), payload); + assertEquals( + Set.of(UpdateOperator.PULL_ALL), + parseCommand("updateOne", payload).updateClause().updateOperationDefs().keySet()); + } + + @ParameterizedTest + @ValueSource(strings = {"updateOne", "updateMany", "findOneAndUpdate"}) + void updateIsRequiredAndFilterMayBeOmittedOrNull(String tool) throws Exception { + var schema = inputSchema(tool); + var payload = toolInput(objectMapper.readTree("{}")); + assertSchemaAccepts(schema, payload); + assertNotNull(parseCommand(tool, payload).updateClause().buildOperations()); + payload.putNull("filter"); + assertSchemaAccepts(schema, payload); + assertNotNull(parseCommand(tool, payload).updateClause().buildOperations()); + + payload.remove("update"); + assertSchemaRejects(schema, payload); + assertFalse(validator.validate(command(tool, payload)).isEmpty()); + payload.putNull("update"); + assertSchemaRejects(schema, payload); + assertFalse(validator.validate(command(tool, payload)).isEmpty()); + } + + @ParameterizedTest + @ValueSource(strings = {"updateOne", "updateMany", "findOneAndUpdate"}) + void openApiCommandsAcceptAdvertisedUpdateExamples(String tool) throws Exception { + var document = + objectMapper.readTree( + given() + .queryParam("format", "json") + .get("/api/json/openapi") + .then() + .statusCode(200) + .extract() + .asString()); + var name = Character.toUpperCase(tool.charAt(0)) + tool.substring(1) + "Command"; + var schema = objectMapper.createObjectNode().put("$ref", "#/components/schemas/" + name); + schema.set("components", document.path("components")); + var examples = updateSchema(inputSchema(tool)).path("examples"); + assertFalse(examples.isEmpty(), "OpenAPI checks must exercise the advertised update examples"); + for (var update : examples) { + var payload = objectMapper.createObjectNode().set("update", update); + assertSchemaAccepts(schema, payload); + } + } + + // $pullAll is table-only, and every advertised example must also build for collections. + @ParameterizedTest + @EnumSource(value = UpdateOperator.class, names = "PULL_ALL", mode = EnumSource.Mode.EXCLUDE) + void everySupportedOperatorHasAnAdvertisedExample(UpdateOperator operator) throws Exception { + var examples = updateSchema(inputSchema("updateOne")).path("examples"); + assertTrue( + StreamSupport.stream(examples.spliterator(), false) + .anyMatch(example -> example.has(operator.apiName())), + () -> "Missing example for " + operator.apiName()); + } + + private Updatable parseCommand(String tool, ObjectNode payload) throws Exception { + var command = command(tool, payload); + assertTrue(validator.validate(command).isEmpty()); + return (Updatable) command; + } + + private Command command(String tool, ObjectNode payload) throws Exception { + var arguments = payload.deepCopy(); + arguments.remove(List.of("keyspace", "collection")); + return objectMapper.treeToValue( + objectMapper.createObjectNode().set(tool, arguments), Command.class); + } + + private ObjectNode toolInput(JsonNode update) { + var payload = objectMapper.createObjectNode(); + payload.put("keyspace", "default_keyspace").put("collection", "documents"); + payload.set("update", update); + return payload; + } + + private JsonNode inputSchema(String tool) throws Exception { + return objectMapper.readTree(schemaGenerator.generate(toolManager.getTool(tool)).asJson()); + } + + private static JsonNode updateSchema(JsonNode document) { + var schema = document.path("properties").path("update"); + var visited = new HashSet(); + while (schema.has("$ref")) { + var reference = schema.path("$ref").asText(); + assertTrue(reference.startsWith("#/"), reference); + assertTrue(visited.add(reference), "Circular update schema reference"); + schema = document.at(reference.substring(1)); + assertFalse(schema.isMissingNode(), "Unresolved update schema " + reference); + } + return schema; + } + + private void assertSchemaAccepts(JsonNode schema, JsonNode payload) { + var errors = + JsonSchemaFactory.getInstance(SpecVersion.VersionFlag.V202012) + .getSchema(schema) + .validate(payload); + assertTrue(errors.isEmpty(), () -> "Schema validation for " + payload + " returned " + errors); + } + + private void assertSchemaRejects(JsonNode schema, JsonNode payload) { + assertFalse( + JsonSchemaFactory.getInstance(SpecVersion.VersionFlag.V202012) + .getSchema(schema) + .validate(payload) + .isEmpty(), + () -> "Schema accepted malformed update " + payload); + } +} From 03bf04d5ce848409fc822e9bd3d695f44803fb0e Mon Sep 17 00:00:00 2001 From: Eric Hare Date: Mon, 16 Nov 2026 15:44:29 -0800 Subject: [PATCH 2/4] fix: reword update operator schemas and merge MCP update tests --- .../command/clause/update/UpdateClause.java | 72 ++++-- .../command/clause/update/UpdateOperator.java | 26 +- .../v1/mcp/McpClauseSchemaContractTest.java | 193 ++++++++++++++- .../v1/mcp/McpOpenApiSchemaAdapterTest.java | 18 +- .../api/v1/mcp/McpSchemaIntegrationTest.java | 49 ---- .../v1/mcp/McpUpdateSchemaContractTest.java | 234 ------------------ 6 files changed, 267 insertions(+), 325 deletions(-) delete mode 100644 src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpUpdateSchemaContractTest.java diff --git a/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/clause/update/UpdateClause.java b/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/clause/update/UpdateClause.java index f3d9bcabdf..4d83be51d0 100644 --- a/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/clause/update/UpdateClause.java +++ b/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/clause/update/UpdateClause.java @@ -22,83 +22,107 @@ implementation = Object.class, additionalProperties = Schema.False.class, description = - "A Data API update object mapping operators such as $set and $unset to objects of document paths and values. Operators may be combined on distinct paths. Tables support only $set, $unset, $push, and $pullAll; collections support every operator except $pullAll.", + "The Update Clause to use when updating Documents in a Collection or Rows in a Table.", properties = { @SchemaProperty( name = UpdateOperator.Names.SET, type = SchemaType.OBJECT, - description = - "Sets paths to JSON values, including null, arrays, objects, and extended JSON."), + description = "Sets fields to the provided JSON value."), @SchemaProperty( name = UpdateOperator.Names.SET_ON_INSERT, type = SchemaType.OBJECT, - description = "Sets paths only when an upsert inserts a document."), + description = + "Sets fields to the provided JSON value, only when an upsert inserts the document."), @SchemaProperty( name = UpdateOperator.Names.UNSET, type = SchemaType.OBJECT, - description = "Removes paths. The values supplied for them are ignored."), + description = "Removes fields from the Document, or sets Table columns to null."), @SchemaProperty( name = UpdateOperator.Names.INC, type = SchemaType.OBJECT, - description = "Maps paths to numeric increments, including fractions."), + description = + "Updates numeric fields by incrementing them by the provided value (use negative values to decrement)."), @SchemaProperty( name = UpdateOperator.Names.MUL, type = SchemaType.OBJECT, - description = "Maps paths to numeric multipliers, including fractions."), + description = "Updates numeric fields by multiplying them by the provided value."), @SchemaProperty( name = UpdateOperator.Names.MIN, type = SchemaType.OBJECT, - description = "Updates paths when the supplied values are smaller."), + description = + "Updates fields to the smaller of the current value or the provided value."), @SchemaProperty( name = UpdateOperator.Names.MAX, type = SchemaType.OBJECT, - description = "Updates paths when the supplied values are larger."), + description = "Updates fields to the larger of the current value or the provided value."), @SchemaProperty( name = UpdateOperator.Names.RENAME, type = SchemaType.OBJECT, - description = "Maps existing paths to new path strings."), + description = "Renames fields to the provided names."), @SchemaProperty( name = UpdateOperator.Names.CURRENT_DATE, type = SchemaType.OBJECT, - description = "Sets paths to the current date using true or {\"$type\": \"date\"}."), + description = + "Sets fields to the current date. The value must be true or {\"$type\": \"date\"}."), @SchemaProperty( name = UpdateOperator.Names.POP, type = SchemaType.OBJECT, - description = "Removes the first (-1) or last (1) element of arrays."), + description = + "Updates array fields to remove the first (-1) or the last (1) element of the array."), @SchemaProperty( name = UpdateOperator.Names.PUSH, type = SchemaType.OBJECT, description = - "Appends values to arrays, or to list, set, and map columns. Use $each for multiple values; only collections accept $position."), + "Updates array fields in a Document, or list, set, and map columns in a Table, by appending values. Use $each for multiple values. Only collections accept $position."), @SchemaProperty( name = UpdateOperator.Names.ADD_TO_SET, type = SchemaType.OBJECT, - description = "Adds unique array values. Use {\"$each\": [...]} for multiple values."), + description = + "Updates array fields in a Document by appending values that are not already present. Use $each for multiple values."), @SchemaProperty( name = UpdateOperator.Names.PULL_ALL, type = SchemaType.OBJECT, description = - "Tables only. Removes the listed values from list and set columns, and the listed keys from map columns.") + "Updates list and set columns in a Table by removing the provided values, and map columns by removing the provided keys.") }, examples = { """ { - "$set" : {"location": "New York"}, - "$unset" : {"obsolete": 1} + "$set": {"location": "New York"}, + "$unset": {"obsolete": 1} } """, """ - {"$inc": {"score": 0.25}, "$mul": {"price": 1.5}, - "$min": {"lowest": 2.5}, "$max": {"highest": 9.5}} + { + "$inc": {"score": 0.25}, + "$mul": {"price": 1.5}, + "$min": {"lowest": 2.5}, + "$max": {"highest": 9.5} + } """, """ - {"$push": {"items": {"$each": [1, 2], "$position": 0}}, - "$addToSet": {"tags": {"$each": ["a", "b"]}}, - "$pop": {"history": -1}, "$rename": {"oldName": "newName"}} + { + "$push": { + "items": {"$each": [1, 2], "$position": 0} + }, + "$addToSet": { + "tags": {"$each": ["a", "b"]} + }, + "$pop": {"history": -1}, + "$rename": {"oldName": "newName"} + } + """, + """ + { + "$currentDate": {"updated": true}, + "$setOnInsert": {"created": {"$date": 123456}}, + "$set": {"optional": null} + } """, """ - {"$currentDate": {"updated": true}, - "$setOnInsert": {"created": {"$date": 123456}}, "$set": {"optional": null}} + { + "$pullAll": {"tags": ["a", "b"]} + } """, "{}" }) diff --git a/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/clause/update/UpdateOperator.java b/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/clause/update/UpdateOperator.java index a05cefbef8..2968bfece7 100644 --- a/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/clause/update/UpdateOperator.java +++ b/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/clause/update/UpdateOperator.java @@ -9,83 +9,83 @@ public enum UpdateOperator { ADD_TO_SET(Names.ADD_TO_SET) { @Override - public UpdateOperation resolveOperation(ObjectNode arguments) { + public UpdateOperation resolveOperation(ObjectNode arguments) { return AddToSetOperation.construct(arguments); } }, CURRENT_DATE(Names.CURRENT_DATE) { @Override - public UpdateOperation resolveOperation(ObjectNode arguments) { + public UpdateOperation resolveOperation(ObjectNode arguments) { return CurrentDateOperation.construct(arguments); } }, INC(Names.INC) { @Override - public UpdateOperation resolveOperation(ObjectNode arguments) { + public UpdateOperation resolveOperation(ObjectNode arguments) { return IncOperation.construct(arguments); } }, MAX(Names.MAX) { @Override - public UpdateOperation resolveOperation(ObjectNode arguments) { + public UpdateOperation resolveOperation(ObjectNode arguments) { return MinMaxOperation.constructMax(arguments); } }, MIN(Names.MIN) { @Override - public UpdateOperation resolveOperation(ObjectNode arguments) { + public UpdateOperation resolveOperation(ObjectNode arguments) { return MinMaxOperation.constructMin(arguments); } }, MUL(Names.MUL) { @Override - public UpdateOperation resolveOperation(ObjectNode arguments) { + public UpdateOperation resolveOperation(ObjectNode arguments) { return MulOperation.construct(arguments); } }, POP(Names.POP) { @Override - public UpdateOperation resolveOperation(ObjectNode arguments) { + public UpdateOperation resolveOperation(ObjectNode arguments) { return PopOperation.construct(arguments); } }, PUSH(Names.PUSH) { @Override - public UpdateOperation resolveOperation(ObjectNode arguments) { + public UpdateOperation resolveOperation(ObjectNode arguments) { return PushOperation.construct(arguments); } }, RENAME(Names.RENAME) { @Override - public UpdateOperation resolveOperation(ObjectNode arguments) { + public UpdateOperation resolveOperation(ObjectNode arguments) { return RenameOperation.construct(arguments); } }, SET(Names.SET) { @Override - public UpdateOperation resolveOperation(ObjectNode arguments) { + public UpdateOperation resolveOperation(ObjectNode arguments) { return SetOperation.constructSet(arguments); } }, SET_ON_INSERT(Names.SET_ON_INSERT) { @Override - public UpdateOperation resolveOperation(ObjectNode arguments) { + public UpdateOperation resolveOperation(ObjectNode arguments) { return SetOperation.constructSetOnInsert(arguments); } }, UNSET(Names.UNSET) { @Override - public UpdateOperation resolveOperation(ObjectNode arguments) { + public UpdateOperation resolveOperation(ObjectNode arguments) { return UnsetOperation.construct(arguments); } }, @@ -120,7 +120,7 @@ public String apiName() { return apiName; } - public UpdateOperation resolveOperation(ObjectNode arguments) { + public UpdateOperation resolveOperation(ObjectNode arguments) { throw UpdateException.Code.UNSUPPORTED_UPDATE_OPERATION.get( Map.of("errorMessage", "Unsupported update operator '%s'".formatted(apiName))); } diff --git a/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpClauseSchemaContractTest.java b/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpClauseSchemaContractTest.java index 99f5e33de0..4abe8c2079 100644 --- a/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpClauseSchemaContractTest.java +++ b/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpClauseSchemaContractTest.java @@ -18,6 +18,14 @@ import io.quarkus.test.junit.QuarkusTest; import io.quarkus.test.junit.TestProfile; import io.stargate.sgv2.jsonapi.TestConstants; +import io.stargate.sgv2.jsonapi.api.model.command.Command; +import io.stargate.sgv2.jsonapi.api.model.command.Updatable; +import io.stargate.sgv2.jsonapi.api.model.command.clause.update.UpdateClause; +import io.stargate.sgv2.jsonapi.api.model.command.clause.update.UpdateOperator; +import io.stargate.sgv2.jsonapi.exception.UpdateException; +import jakarta.validation.Validator; +import java.util.Set; +import java.util.stream.StreamSupport; import io.stargate.sgv2.jsonapi.api.model.command.JsonDefinition; import io.stargate.sgv2.jsonapi.api.model.command.clause.filter.FilterDefinition; import io.stargate.sgv2.jsonapi.api.model.command.clause.filter.SortDefinition; @@ -67,9 +75,13 @@ @QuarkusTest @TestProfile(NoGlobalResourcesTestProfile.Impl.class) class McpClauseSchemaContractTest { + private static final List UPDATE_TOOLS = + List.of("updateOne", "updateMany", "findOneAndUpdate"); + @Inject ObjectMapper objectMapper; @Inject GlobalInputSchemaGenerator schemaGenerator; @Inject ToolManager toolManager; + @Inject Validator validator; record WireNames( @JsonProperty("wireName") String internalName, @JsonIgnore CommandFeatures commandFeatures) {} @@ -142,11 +154,15 @@ void everyAdvertisedClauseExampleDeserializes(Class clauseType) throws Except assertSchemaAccepts(schema, example); var clause = objectMapper.treeToValue(example, clauseType); assertNotNull(clause); - // These two clauses defer parsing until build, so deserialization alone cannot validate them. + // These clauses defer parsing until build, so deserialization alone cannot validate them. if (clause instanceof FilterDefinition filter) { assertNotNull(filter.build(new TestConstants().collectionContext())); } else if (clause instanceof SortDefinition sort) { assertNotNull(sort.build(new TestConstants().collectionContext())); + } else if (clause instanceof UpdateClause update + && !example.has(UpdateOperator.PULL_ALL.apiName())) { + // $pullAll is table only, so the collection operations cannot build it. + assertNotNull(update.buildOperations()); } } } @@ -623,6 +639,181 @@ static Stream invalidWireShapes() { FindAndRerankCommand.HybridLimits.class, "{\"$vector\": 50, \"$lexical\": \"10\"}")); } + @ParameterizedTest + @EnumSource(UpdateOperator.class) + void everyUpdateOperatorHasAnAdvertisedExample(UpdateOperator operator) { + var schema = schemaFor(UpdateClause.class); + var examples = schemaMetadata(schema, schema, "examples"); + assertTrue( + StreamSupport.stream(examples.spliterator(), false) + .anyMatch(example -> example.has(operator.apiName())), + () -> "Missing example for " + operator.apiName()); + } + + @ParameterizedTest + @MethodSource("supportedUpdates") + void updateToolsAcceptSupportedUpdates(String tool, String json) throws Exception { + var payload = updateToolInput(objectMapper.readTree(json)); + assertSchemaAccepts(inputSchema(tool), payload); + assertNotNull(parseUpdateCommand(tool, payload).updateClause().buildOperations()); + } + + static Stream supportedUpdates() { + // Nonempty arguments exercise each operation's parser, including supported array modifiers. + var updates = + List.of( + "{}", + """ + {"$set": {}} + """, + """ + {"$set": {"profile.name": "Ada", "optional": null}} + """, + """ + {"$unset": {"obsolete": null}} + """, + """ + {"$setOnInsert": {"created": true}} + """, + """ + {"$inc": {"score": 0.25}} + """, + """ + {"$mul": {"score": 1.5}} + """, + """ + {"$min": {"score": 2.5}} + """, + """ + {"$max": {"score": 9.5}} + """, + """ + {"$rename": {"oldName": "newName"}} + """, + """ + {"$currentDate": {"updated": true, "reviewed": {"$type": "date"}}} + """, + """ + {"$pop": {"first": -1, "last": 1}} + """, + """ + {"$push": {"items": {"$each": [1, 2], "$position": 0}}} + """, + """ + {"$addToSet": {"tags": {"$each": ["a", "b"]}}} + """, + """ + {"$set": {"created": {"$date": 123456}, + "owner": {"$uuid": "550e8400-e29b-41d4-a716-446655440000"}, + "nested": {"values": [null, true, 1.25, {"name": "Ada"}]}}, + "$unset": {"obsolete": 1}} + """); + return UPDATE_TOOLS.stream() + .flatMap(tool -> updates.stream().map(json -> Arguments.of(tool, json))); + } + + @ParameterizedTest + @MethodSource("malformedUpdates") + void updateToolsRejectMalformedUpdates(String tool, String json) throws Exception { + var update = objectMapper.readTree(json); + assertSchemaRejects(inputSchema(tool), updateToolInput(update)); + assertThrows(UpdateException.class, () -> objectMapper.treeToValue(update, UpdateClause.class)); + } + + static Stream malformedUpdates() { + var updates = + List.of( + "[]", + "5", + """ + "update" + """, + """ + {"name": "Ada"} + """, + """ + {"updateOperationDefs": {}} + """, + """ + {"$unknown": {}} + """, + """ + {"$set": null} + """, + """ + {"$set": 5} + """, + """ + {"$set": []} + """, + """ + {"$set": "value"} + """); + return UPDATE_TOOLS.stream() + .flatMap(tool -> updates.stream().map(json -> Arguments.of(tool, json))); + } + + // updateOne is the only update tool that also serves tables. + @Test + void updateOneAcceptsTableOnlyPullAll() throws Exception { + var payload = + updateToolInput( + objectMapper.readTree( + """ + {"$pullAll": {"listColumn": [1]}} + """)); + assertSchemaAccepts(inputSchema("updateOne"), payload); + assertEquals( + Set.of(UpdateOperator.PULL_ALL), + parseUpdateCommand("updateOne", payload).updateClause().updateOperationDefs().keySet()); + } + + @ParameterizedTest + @ValueSource(strings = {"updateOne", "updateMany", "findOneAndUpdate"}) + void updateIsRequiredAndFilterMayBeOmittedOrNull(String tool) throws Exception { + var schema = inputSchema(tool); + var payload = updateToolInput(objectMapper.readTree("{}")); + assertSchemaAccepts(schema, payload); + assertNotNull(parseUpdateCommand(tool, payload).updateClause().buildOperations()); + payload.putNull("filter"); + assertSchemaAccepts(schema, payload); + assertNotNull(parseUpdateCommand(tool, payload).updateClause().buildOperations()); + + payload.remove("update"); + assertSchemaRejects(schema, payload); + assertFalse(validator.validate(command(tool, payload)).isEmpty()); + payload.putNull("update"); + assertSchemaRejects(schema, payload); + assertFalse(validator.validate(command(tool, payload)).isEmpty()); + } + + private ObjectNode updateToolInput(JsonNode update) throws Exception { + return toolInput("{}").set("update", update); + } + + private Updatable parseUpdateCommand(String tool, ObjectNode payload) throws Exception { + var command = command(tool, payload); + assertTrue(validator.validate(command).isEmpty()); + return (Updatable) command; + } + + /** Builds the command a tool call runs, without the MCP routing arguments. */ + private Command command(String tool, ObjectNode payload) throws Exception { + var arguments = payload.deepCopy(); + arguments.remove(List.of("keyspace", "collection")); + return objectMapper.treeToValue( + objectMapper.createObjectNode().set(tool, arguments), Command.class); + } + + private void assertSchemaRejects(JsonNode schema, JsonNode payload) { + assertFalse( + JsonSchemaFactory.getInstance(SpecVersion.VersionFlag.V202012) + .getSchema(schema) + .validate(payload) + .isEmpty(), + () -> "Schema accepted malformed payload " + payload); + } + private void assertSchemaAccepts(JsonNode schema, JsonNode example) { var validator = JsonSchemaFactory.getInstance(SpecVersion.VersionFlag.V202012).getSchema(schema); diff --git a/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpOpenApiSchemaAdapterTest.java b/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpOpenApiSchemaAdapterTest.java index d29fd2df1a..c29506f691 100644 --- a/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpOpenApiSchemaAdapterTest.java +++ b/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpOpenApiSchemaAdapterTest.java @@ -297,17 +297,27 @@ void shouldEscapeComponentNamesInReferences() { assertEquals("#/components/schemas/A~1B~0C", McpOpenApiSchemaAdapter.componentRef("A/B~C")); } + /** + * Checks that copying an OpenAPI component into {@code $defs} keeps decimal numbers exact. The + * test adds this component to the fixture document and bundles a reference to it. + * + *
+   * "Decimal": {"type": "number", "minimum": 0.25, "maximum": 1.75, "default": 0.5}
+   * 
+ * + *

The bundled copy must keep those three values, accept the bounds, and reject values just + * outside them. + */ @Test - void shouldPreserveFractionalSchemaBoundsAndDefault() throws Exception { + void shouldPreserveDecimalSchemaBoundsAndDefault() throws Exception { var document = fixtureDocument(); ((ObjectNode) document.path("components").path("schemas")) - .putObject("Fractional") + .putObject("Decimal") .put("type", "number") .put("minimum", 0.25) .put("maximum", 1.75) .put("default", 0.5); - var schema = - bundle(MAPPER.readTree("{\"$ref\":\"#/components/schemas/Fractional\"}"), document); + var schema = bundle(MAPPER.readTree("{\"$ref\":\"#/components/schemas/Decimal\"}"), document); var component = schema.at(schema.path("$ref").asText().substring(1)); assertEquals(0.25, component.path("minimum").doubleValue()); diff --git a/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpSchemaIntegrationTest.java b/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpSchemaIntegrationTest.java index b6c2c243f5..6ad33411b8 100644 --- a/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpSchemaIntegrationTest.java +++ b/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpSchemaIntegrationTest.java @@ -12,10 +12,7 @@ import io.quarkus.test.junit.TestProfile; import io.stargate.sgv2.jsonapi.testresource.NoGlobalResourcesTestProfile; import io.vertx.core.json.JsonObject; -import java.util.HashSet; import org.junit.jupiter.api.Test; -import org.junit.jupiter.params.ParameterizedTest; -import org.junit.jupiter.params.provider.ValueSource; /** Checks the schemas clients receive from the packaged application's tools/list endpoint. */ @QuarkusIntegrationTest @@ -152,52 +149,6 @@ void findAndRerankPreservesNestedConstraints() { .thenAssertResults(); } - @ParameterizedTest - @ValueSource(strings = {"updateOne", "updateMany", "findOneAndUpdate"}) - void updateToolsAdvertiseAcceptedOperatorSyntax(String tool) { - mcpClient - .when() - .toolsList( - page -> { - var schema = schemaFor(page, tool); - var document = json(page.findByName(tool).inputSchema()); - var update = document.path("properties").path("update"); - var visited = new HashSet(); - while (update.has("$ref")) { - var reference = update.path("$ref").asText(); - assertTrue(reference.startsWith("#/"), reference); - assertTrue(visited.add(reference), "Circular update schema reference"); - update = document.at(reference.substring(1)); - assertFalse(update.isMissingNode(), reference); - } - var examples = update.path("examples"); - assertFalse(examples.isEmpty(), "Update tools must advertise usable examples"); - var arguments = - new JsonObject() - .put("keyspace", "default_keyspace") - .put("collection", "schema_test"); - for (var example : examples) { - arguments.put("update", new JsonObject(example.toString())); - assertAccepts(schema, arguments); - assertAccepts(schema, arguments.copy().putNull("filter")); - } - for (var malformed : - new String[] { - "{\"updateOperationDefs\":{}}", - "{\"$unknown\":{}}", - "{\"$set\":null}", - "{\"$set\":5}", - "{\"$set\":[]}" - }) { - assertRejects(schema, arguments.copy().put("update", new JsonObject(malformed))); - } - arguments.remove("update"); - assertRejects(schema, arguments); - assertRejects(schema, arguments.copy().putNull("update")); - }) - .thenAssertResults(); - } - private static JsonSchema schemaFor(ToolsPage page, String name) { var tool = page.findByName(name); assertNotNull(tool, name); diff --git a/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpUpdateSchemaContractTest.java b/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpUpdateSchemaContractTest.java deleted file mode 100644 index 3735e8a286..0000000000 --- a/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpUpdateSchemaContractTest.java +++ /dev/null @@ -1,234 +0,0 @@ -package io.stargate.sgv2.jsonapi.api.v1.mcp; - -import static io.restassured.RestAssured.given; -import static org.junit.jupiter.api.Assertions.*; - -import com.fasterxml.jackson.databind.JsonNode; -import com.fasterxml.jackson.databind.ObjectMapper; -import com.fasterxml.jackson.databind.node.ObjectNode; -import com.networknt.schema.JsonSchemaFactory; -import com.networknt.schema.SpecVersion; -import io.quarkiverse.mcp.server.GlobalInputSchemaGenerator; -import io.quarkiverse.mcp.server.ToolManager; -import io.quarkus.test.junit.QuarkusTest; -import io.quarkus.test.junit.TestProfile; -import io.stargate.sgv2.jsonapi.api.model.command.Command; -import io.stargate.sgv2.jsonapi.api.model.command.Updatable; -import io.stargate.sgv2.jsonapi.api.model.command.clause.update.UpdateClause; -import io.stargate.sgv2.jsonapi.api.model.command.clause.update.UpdateOperator; -import io.stargate.sgv2.jsonapi.exception.UpdateException; -import io.stargate.sgv2.jsonapi.testresource.NoGlobalResourcesTestProfile; -import jakarta.inject.Inject; -import jakarta.validation.Validator; -import java.util.HashSet; -import java.util.List; -import java.util.Set; -import java.util.stream.Stream; -import java.util.stream.StreamSupport; -import org.junit.jupiter.api.Test; -import org.junit.jupiter.params.ParameterizedTest; -import org.junit.jupiter.params.provider.Arguments; -import org.junit.jupiter.params.provider.EnumSource; -import org.junit.jupiter.params.provider.MethodSource; -import org.junit.jupiter.params.provider.ValueSource; - -/** Checks update arguments advertised by the registered tools against the real command parser. */ -@QuarkusTest -@TestProfile(NoGlobalResourcesTestProfile.Impl.class) -class McpUpdateSchemaContractTest { - private static final List TOOLS = List.of("updateOne", "updateMany", "findOneAndUpdate"); - - @Inject ObjectMapper objectMapper; - @Inject GlobalInputSchemaGenerator schemaGenerator; - @Inject ToolManager toolManager; - @Inject Validator validator; - - @ParameterizedTest - @ValueSource(strings = {"updateOne", "updateMany", "findOneAndUpdate"}) - void advertisedExamplesValidateAndBuild(String tool) throws Exception { - var schema = inputSchema(tool); - var examples = updateSchema(schema).path("examples"); - assertFalse(examples.isEmpty(), "Update arguments must advertise usable examples"); - for (var update : examples) { - var payload = toolInput(update); - assertSchemaAccepts(schema, payload); - assertNotNull(parseCommand(tool, payload).updateClause().buildOperations()); - } - } - - @ParameterizedTest - @MethodSource("supportedUpdates") - void toolSchemasAcceptSupportedUpdates(String tool, String json) throws Exception { - var payload = toolInput(objectMapper.readTree(json)); - assertSchemaAccepts(inputSchema(tool), payload); - assertNotNull(parseCommand(tool, payload).updateClause().buildOperations()); - } - - static Stream supportedUpdates() { - // Nonempty arguments exercise each operation's parser, including supported array modifiers. - var updates = - List.of( - "{}", - "{\"$set\": {}}", - "{\"$set\": {\"profile.name\": \"Ada\", \"optional\": null}}", - "{\"$unset\": {\"obsolete\": null}}", - "{\"$setOnInsert\": {\"created\": true}}", - "{\"$inc\": {\"score\": 0.25}}", - "{\"$mul\": {\"score\": 1.5}}", - "{\"$min\": {\"score\": 2.5}}", - "{\"$max\": {\"score\": 9.5}}", - "{\"$rename\": {\"oldName\": \"newName\"}}", - "{\"$currentDate\": {\"updated\": true, \"reviewed\": {\"$type\": \"date\"}}}", - "{\"$pop\": {\"first\": -1, \"last\": 1}}", - "{\"$push\": {\"items\": {\"$each\": [1, 2], \"$position\": 0}}}", - "{\"$addToSet\": {\"tags\": {\"$each\": [\"a\", \"b\"]}}}", - """ - {"$set": {"created": {"$date": 123456}, - "owner": {"$uuid": "550e8400-e29b-41d4-a716-446655440000"}, - "nested": {"values": [null, true, 1.25, {"name": "Ada"}]}}, - "$unset": {"obsolete": 1}} - """); - return TOOLS.stream().flatMap(tool -> updates.stream().map(json -> Arguments.of(tool, json))); - } - - @ParameterizedTest - @MethodSource("invalidUpdates") - void toolSchemasRejectMalformedUpdates(String tool, String json) throws Exception { - var update = objectMapper.readTree(json); - assertSchemaRejects(inputSchema(tool), toolInput(update)); - assertThrows(UpdateException.class, () -> objectMapper.treeToValue(update, UpdateClause.class)); - } - - static Stream invalidUpdates() { - var updates = - List.of( - "[]", - "5", - "\"update\"", - "{\"name\": \"Ada\"}", - "{\"updateOperationDefs\": {}}", - "{\"$unknown\": {}}", - "{\"$set\": null}", - "{\"$set\": 5}", - "{\"$set\": []}", - "{\"$set\": \"value\"}"); - return TOOLS.stream().flatMap(tool -> updates.stream().map(json -> Arguments.of(tool, json))); - } - - // updateOne is the only update tool that also serves tables. - @Test - void updateOneAcceptsTableOnlyPullAll() throws Exception { - var payload = toolInput(objectMapper.readTree("{\"$pullAll\": {\"listColumn\": [1]}}")); - assertSchemaAccepts(inputSchema("updateOne"), payload); - assertEquals( - Set.of(UpdateOperator.PULL_ALL), - parseCommand("updateOne", payload).updateClause().updateOperationDefs().keySet()); - } - - @ParameterizedTest - @ValueSource(strings = {"updateOne", "updateMany", "findOneAndUpdate"}) - void updateIsRequiredAndFilterMayBeOmittedOrNull(String tool) throws Exception { - var schema = inputSchema(tool); - var payload = toolInput(objectMapper.readTree("{}")); - assertSchemaAccepts(schema, payload); - assertNotNull(parseCommand(tool, payload).updateClause().buildOperations()); - payload.putNull("filter"); - assertSchemaAccepts(schema, payload); - assertNotNull(parseCommand(tool, payload).updateClause().buildOperations()); - - payload.remove("update"); - assertSchemaRejects(schema, payload); - assertFalse(validator.validate(command(tool, payload)).isEmpty()); - payload.putNull("update"); - assertSchemaRejects(schema, payload); - assertFalse(validator.validate(command(tool, payload)).isEmpty()); - } - - @ParameterizedTest - @ValueSource(strings = {"updateOne", "updateMany", "findOneAndUpdate"}) - void openApiCommandsAcceptAdvertisedUpdateExamples(String tool) throws Exception { - var document = - objectMapper.readTree( - given() - .queryParam("format", "json") - .get("/api/json/openapi") - .then() - .statusCode(200) - .extract() - .asString()); - var name = Character.toUpperCase(tool.charAt(0)) + tool.substring(1) + "Command"; - var schema = objectMapper.createObjectNode().put("$ref", "#/components/schemas/" + name); - schema.set("components", document.path("components")); - var examples = updateSchema(inputSchema(tool)).path("examples"); - assertFalse(examples.isEmpty(), "OpenAPI checks must exercise the advertised update examples"); - for (var update : examples) { - var payload = objectMapper.createObjectNode().set("update", update); - assertSchemaAccepts(schema, payload); - } - } - - // $pullAll is table-only, and every advertised example must also build for collections. - @ParameterizedTest - @EnumSource(value = UpdateOperator.class, names = "PULL_ALL", mode = EnumSource.Mode.EXCLUDE) - void everySupportedOperatorHasAnAdvertisedExample(UpdateOperator operator) throws Exception { - var examples = updateSchema(inputSchema("updateOne")).path("examples"); - assertTrue( - StreamSupport.stream(examples.spliterator(), false) - .anyMatch(example -> example.has(operator.apiName())), - () -> "Missing example for " + operator.apiName()); - } - - private Updatable parseCommand(String tool, ObjectNode payload) throws Exception { - var command = command(tool, payload); - assertTrue(validator.validate(command).isEmpty()); - return (Updatable) command; - } - - private Command command(String tool, ObjectNode payload) throws Exception { - var arguments = payload.deepCopy(); - arguments.remove(List.of("keyspace", "collection")); - return objectMapper.treeToValue( - objectMapper.createObjectNode().set(tool, arguments), Command.class); - } - - private ObjectNode toolInput(JsonNode update) { - var payload = objectMapper.createObjectNode(); - payload.put("keyspace", "default_keyspace").put("collection", "documents"); - payload.set("update", update); - return payload; - } - - private JsonNode inputSchema(String tool) throws Exception { - return objectMapper.readTree(schemaGenerator.generate(toolManager.getTool(tool)).asJson()); - } - - private static JsonNode updateSchema(JsonNode document) { - var schema = document.path("properties").path("update"); - var visited = new HashSet(); - while (schema.has("$ref")) { - var reference = schema.path("$ref").asText(); - assertTrue(reference.startsWith("#/"), reference); - assertTrue(visited.add(reference), "Circular update schema reference"); - schema = document.at(reference.substring(1)); - assertFalse(schema.isMissingNode(), "Unresolved update schema " + reference); - } - return schema; - } - - private void assertSchemaAccepts(JsonNode schema, JsonNode payload) { - var errors = - JsonSchemaFactory.getInstance(SpecVersion.VersionFlag.V202012) - .getSchema(schema) - .validate(payload); - assertTrue(errors.isEmpty(), () -> "Schema validation for " + payload + " returned " + errors); - } - - private void assertSchemaRejects(JsonNode schema, JsonNode payload) { - assertFalse( - JsonSchemaFactory.getInstance(SpecVersion.VersionFlag.V202012) - .getSchema(schema) - .validate(payload) - .isEmpty(), - () -> "Schema accepted malformed update " + payload); - } -} From d63d03a95e5d02b4b195ddce52cd2f348a4e936c Mon Sep 17 00:00:00 2001 From: Eric Hare Date: Mon, 16 Nov 2026 15:49:48 -0800 Subject: [PATCH 3/4] style: sort imports and simplify wrapping in MCP clause contract test --- .../v1/mcp/McpClauseSchemaContractTest.java | 43 ++++++++++--------- 1 file changed, 23 insertions(+), 20 deletions(-) diff --git a/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpClauseSchemaContractTest.java b/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpClauseSchemaContractTest.java index 4abe8c2079..6503d54f1f 100644 --- a/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpClauseSchemaContractTest.java +++ b/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpClauseSchemaContractTest.java @@ -19,20 +19,17 @@ import io.quarkus.test.junit.TestProfile; import io.stargate.sgv2.jsonapi.TestConstants; import io.stargate.sgv2.jsonapi.api.model.command.Command; -import io.stargate.sgv2.jsonapi.api.model.command.Updatable; -import io.stargate.sgv2.jsonapi.api.model.command.clause.update.UpdateClause; -import io.stargate.sgv2.jsonapi.api.model.command.clause.update.UpdateOperator; -import io.stargate.sgv2.jsonapi.exception.UpdateException; -import jakarta.validation.Validator; -import java.util.Set; -import java.util.stream.StreamSupport; import io.stargate.sgv2.jsonapi.api.model.command.JsonDefinition; +import io.stargate.sgv2.jsonapi.api.model.command.Updatable; import io.stargate.sgv2.jsonapi.api.model.command.clause.filter.FilterDefinition; import io.stargate.sgv2.jsonapi.api.model.command.clause.filter.SortDefinition; import io.stargate.sgv2.jsonapi.api.model.command.clause.sort.FindAndRerankSort; +import io.stargate.sgv2.jsonapi.api.model.command.clause.update.UpdateClause; +import io.stargate.sgv2.jsonapi.api.model.command.clause.update.UpdateOperator; import io.stargate.sgv2.jsonapi.api.model.command.impl.CreateCollectionCommand; import io.stargate.sgv2.jsonapi.api.model.command.impl.FindAndRerankCommand; import io.stargate.sgv2.jsonapi.exception.RequestException; +import io.stargate.sgv2.jsonapi.exception.UpdateException; import io.stargate.sgv2.jsonapi.metrics.CommandFeatures; import io.stargate.sgv2.jsonapi.service.provider.ApiModelSupport; import io.stargate.sgv2.jsonapi.service.reranking.configuration.RerankingProvidersConfig; @@ -45,13 +42,16 @@ import io.stargate.sgv2.jsonapi.service.schema.collections.CollectionRerankDef; import io.stargate.sgv2.jsonapi.testresource.NoGlobalResourcesTestProfile; import jakarta.inject.Inject; +import jakarta.validation.Validator; import java.util.ArrayList; import java.util.Comparator; import java.util.HashSet; import java.util.List; import java.util.Map; import java.util.Optional; +import java.util.Set; import java.util.stream.Stream; +import java.util.stream.StreamSupport; import org.eclipse.microprofile.openapi.annotations.media.Schema; import org.jboss.jandex.AnnotationTarget; import org.jboss.jandex.IndexReader; @@ -159,10 +159,11 @@ void everyAdvertisedClauseExampleDeserializes(Class clauseType) throws Except assertNotNull(filter.build(new TestConstants().collectionContext())); } else if (clause instanceof SortDefinition sort) { assertNotNull(sort.build(new TestConstants().collectionContext())); - } else if (clause instanceof UpdateClause update - && !example.has(UpdateOperator.PULL_ALL.apiName())) { + } else if (clause instanceof UpdateClause update) { // $pullAll is table only, so the collection operations cannot build it. - assertNotNull(update.buildOperations()); + if (!example.has(UpdateOperator.PULL_ALL.apiName())) { + assertNotNull(update.buildOperations()); + } } } } @@ -708,8 +709,7 @@ static Stream supportedUpdates() { "nested": {"values": [null, true, 1.25, {"name": "Ada"}]}}, "$unset": {"obsolete": 1}} """); - return UPDATE_TOOLS.stream() - .flatMap(tool -> updates.stream().map(json -> Arguments.of(tool, json))); + return forUpdateTools(updates); } @ParameterizedTest @@ -749,19 +749,18 @@ static Stream malformedUpdates() { """ {"$set": "value"} """); - return UPDATE_TOOLS.stream() - .flatMap(tool -> updates.stream().map(json -> Arguments.of(tool, json))); + return forUpdateTools(updates); } // updateOne is the only update tool that also serves tables. @Test void updateOneAcceptsTableOnlyPullAll() throws Exception { - var payload = - updateToolInput( - objectMapper.readTree( - """ - {"$pullAll": {"listColumn": [1]}} - """)); + var update = + objectMapper.readTree( + """ + {"$pullAll": {"listColumn": [1]}} + """); + var payload = updateToolInput(update); assertSchemaAccepts(inputSchema("updateOne"), payload); assertEquals( Set.of(UpdateOperator.PULL_ALL), @@ -787,6 +786,10 @@ void updateIsRequiredAndFilterMayBeOmittedOrNull(String tool) throws Exception { assertFalse(validator.validate(command(tool, payload)).isEmpty()); } + private static Stream forUpdateTools(List updates) { + return UPDATE_TOOLS.stream().flatMap(t -> updates.stream().map(u -> Arguments.of(t, u))); + } + private ObjectNode updateToolInput(JsonNode update) throws Exception { return toolInput("{}").set("update", update); } From e4e193a4aa3a2c55a0c6688fff2f51102982d36c Mon Sep 17 00:00:00 2001 From: Eric Hare Date: Mon, 16 Nov 2026 18:13:28 -0800 Subject: [PATCH 4/4] test: move customizer checks to McpSchemaCustomizerTest and trim MCP contract test McpSchemaCustomizerTest now covers each rule the customizer adds in four tests: JSON property names, ignored and hidden fields, descriptions, and component references. It reaches every line and branch of the customizer. McpClauseSchemaContractTest keeps the checks that published clause schemas agree with the server's parsers. Tool payload cases that repeat McpSchemaIntegrationTest are removed, the update cases run once against the update clause schema instead of once per tool, and the rerank credentials case is a row in the override table. --- .../v1/mcp/McpClauseSchemaContractTest.java | 1035 ++++++----------- .../api/v1/mcp/McpSchemaCustomizerTest.java | 213 ++-- 2 files changed, 425 insertions(+), 823 deletions(-) diff --git a/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpClauseSchemaContractTest.java b/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpClauseSchemaContractTest.java index 6503d54f1f..d317e8f7d6 100644 --- a/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpClauseSchemaContractTest.java +++ b/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpClauseSchemaContractTest.java @@ -3,23 +3,20 @@ import static io.restassured.RestAssured.given; import static org.junit.jupiter.api.Assertions.*; -import com.fasterxml.jackson.annotation.JsonIgnore; -import com.fasterxml.jackson.annotation.JsonProperty; import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.ObjectMapper; -import com.fasterxml.jackson.databind.annotation.JsonDeserialize; import com.fasterxml.jackson.databind.node.MissingNode; import com.fasterxml.jackson.databind.node.ObjectNode; import com.github.victools.jsonschema.generator.*; import com.networknt.schema.JsonSchemaFactory; import com.networknt.schema.SpecVersion; +import com.networknt.schema.ValidationMessage; import io.quarkiverse.mcp.server.GlobalInputSchemaGenerator; import io.quarkiverse.mcp.server.ToolManager; import io.quarkus.test.junit.QuarkusTest; import io.quarkus.test.junit.TestProfile; import io.stargate.sgv2.jsonapi.TestConstants; import io.stargate.sgv2.jsonapi.api.model.command.Command; -import io.stargate.sgv2.jsonapi.api.model.command.JsonDefinition; import io.stargate.sgv2.jsonapi.api.model.command.Updatable; import io.stargate.sgv2.jsonapi.api.model.command.clause.filter.FilterDefinition; import io.stargate.sgv2.jsonapi.api.model.command.clause.filter.SortDefinition; @@ -30,7 +27,6 @@ import io.stargate.sgv2.jsonapi.api.model.command.impl.FindAndRerankCommand; import io.stargate.sgv2.jsonapi.exception.RequestException; import io.stargate.sgv2.jsonapi.exception.UpdateException; -import io.stargate.sgv2.jsonapi.metrics.CommandFeatures; import io.stargate.sgv2.jsonapi.service.provider.ApiModelSupport; import io.stargate.sgv2.jsonapi.service.reranking.configuration.RerankingProvidersConfig; import io.stargate.sgv2.jsonapi.service.reranking.configuration.RerankingProvidersConfig.RerankingProviderConfig.AuthenticationType; @@ -43,8 +39,6 @@ import io.stargate.sgv2.jsonapi.testresource.NoGlobalResourcesTestProfile; import jakarta.inject.Inject; import jakarta.validation.Validator; -import java.util.ArrayList; -import java.util.Comparator; import java.util.HashSet; import java.util.List; import java.util.Map; @@ -53,95 +47,46 @@ import java.util.stream.Stream; import java.util.stream.StreamSupport; import org.eclipse.microprofile.openapi.annotations.media.Schema; -import org.jboss.jandex.AnnotationTarget; -import org.jboss.jandex.IndexReader; import org.junit.jupiter.api.Test; import org.junit.jupiter.api.function.Executable; import org.junit.jupiter.params.ParameterizedTest; -import org.junit.jupiter.params.provider.Arguments; +import org.junit.jupiter.params.provider.CsvSource; import org.junit.jupiter.params.provider.EnumSource; import org.junit.jupiter.params.provider.MethodSource; import org.junit.jupiter.params.provider.ValueSource; /** - * Checks that MCP and OpenAPI advertise the JSON accepted by Data API clause deserializers. - * Reflection alone exposes internal Java fields for clauses with custom deserializers, so those - * clauses need schema overrides. + * Checks the JSON schemas the Data API publishes for command clauses such as filter, sort, and + * update. Clients build requests from the MCP tool input schemas and the OpenAPI document, so both + * must accept the JSON the server accepts and reject the JSON it rejects. * - *

Schema validation checks the advertised JSON shape. Deserialization and clause building check - * that the server accepts the examples. Generated tool schemas and the OpenAPI document also verify - * that the overrides reach clients. These checks do not execute commands or require a database. + *

The clause classes use custom deserializers, so each schema is a hand-written {@code @Schema} + * annotation rather than one generated from the Java fields. These tests compare each schema with + * the server's parser so the two stay in step. No commands run and no database is needed. + * + *

Test cases are tables with one JSON value per line, separated from other columns by {@code |}. */ @QuarkusTest @TestProfile(NoGlobalResourcesTestProfile.Impl.class) class McpClauseSchemaContractTest { - private static final List UPDATE_TOOLS = - List.of("updateOne", "updateMany", "findOneAndUpdate"); - @Inject ObjectMapper objectMapper; @Inject GlobalInputSchemaGenerator schemaGenerator; @Inject ToolManager toolManager; @Inject Validator validator; - record WireNames( - @JsonProperty("wireName") String internalName, @JsonIgnore CommandFeatures commandFeatures) {} - - record PropertyNameDefaults( - @JsonProperty("") String defaultName, @JsonProperty(" ") String whitespaceName) {} - - record IgnoredFields( - @JsonIgnore String internal, - @JsonIgnore(false) String visible, - CommandFeatures unannotatedFeatures) {} - - static class GetterIgnoredField { - public String internal; - - @JsonIgnore - public String getInternal() { - return internal; - } - } - - @Test - void jsonIgnoreControlsFieldVisibility() { - var properties = schemaFor(IgnoredFields.class).path("properties"); - assertFalse(properties.has("internal")); - assertTrue(properties.has("visible")); - assertTrue(properties.has("unannotatedFeatures")); - } + // ---- Clause schemas, one clause type at a time ---- - @Test - void jsonIgnoreOnGetterHidesField() { - assertFalse(schemaFor(GetterIgnoredField.class).path("properties").has("internal")); - } - - @Test - void fieldsUseJsonPropertyNamesAndHideCommandFeatures() { - var properties = schemaFor(WireNames.class).path("properties"); - assertTrue(properties.has("wireName")); - assertFalse(properties.has("internalName")); - assertFalse(properties.has("commandFeatures")); - } - - @Test - void emptyAndWhitespacePropertyNamesMatchJackson() throws Exception { - var payload = - objectMapper.readTree( - """ - {"defaultName": "default", " ": "explicit"} - """); - var schema = schemaFor(PropertyNameDefaults.class); - var properties = schema.path("properties"); - assertEquals(payload.size(), properties.size()); - payload.fieldNames().forEachRemaining(name -> assertTrue(properties.has(name))); - assertSchemaAccepts(schema, payload); - assertEquals( - new PropertyNameDefaults("default", "explicit"), - objectMapper.treeToValue(payload, PropertyNameDefaults.class)); + /** The clause types whose schemas come from {@code @Schema} rather than their Java fields. */ + static Stream> clauseTypes() { + return Stream.of( + FilterDefinition.class, + SortDefinition.class, + UpdateClause.class, + FindAndRerankSort.class, + FindAndRerankCommand.HybridLimits.class); } - /** An example must satisfy both its advertised schema and the server's clause parser. */ + /** Clients copy these examples, so each must pass its own schema and the server's parser. */ @ParameterizedTest @MethodSource("clauseTypes") void everyAdvertisedClauseExampleDeserializes(Class clauseType) throws Exception { @@ -168,32 +113,10 @@ void everyAdvertisedClauseExampleDeserializes(Class clauseType) throws Except } } - static Stream> clauseTypes() throws Exception { - var loader = FilterDefinition.class.getClassLoader(); - // Use the build's class index so new annotated clauses join these tests automatically. - try (var indexStream = loader.getResourceAsStream("META-INF/jandex.idx")) { - assertNotNull(indexStream, "The application class index must be available"); - var index = new IndexReader(indexStream).read(); - var clauseTypes = new ArrayList>(); - for (var annotation : index.getAnnotations(Schema.class)) { - if (annotation.target().kind() != AnnotationTarget.Kind.CLASS) { - continue; - } - var type = Class.forName(annotation.target().asClass().name().toString(), false, loader); - var schema = type.getAnnotation(Schema.class); - // Select parsed clause types, excluding helper classes for nested JSON shapes. - if (!schema.name().isBlank() - && (JsonDefinition.class.isAssignableFrom(type) - || type.isAnnotationPresent(JsonDeserialize.class))) { - clauseTypes.add(type); - } - } - assertFalse(clauseTypes.isEmpty(), "The application index must contain clause schemas"); - return clauseTypes.stream().sorted(Comparator.comparing(Class::getName)); - } - } - - /** Both entry points accept the same clause JSON and must expose the same schema definition. */ + /** + * MCP builds clause schemas from the OpenAPI document generated at build time. This checks they + * match the document the server serves, so Swagger and MCP clients see the same clause JSON. + */ @ParameterizedTest @MethodSource("clauseTypes") void openApiAndMcpShareClauseSchemas(Class clauseType) throws Exception { @@ -210,198 +133,212 @@ void openApiAndMcpShareClauseSchemas(Class clauseType) throws Exception { assertEquals(expected.path("$defs"), actual.path("$defs")); } - @Test - void filterSchemaAcceptsDocumentObjectsAndNull() throws Exception { - var annotation = FilterDefinition.class.getAnnotation(Schema.class); - var schema = schemaFor(FilterDefinition.class); - var component = referencedSchema(schema, schema); - - assertEquals(annotation.description(), schemaMetadata(schema, schema, "description").asText()); - assertEquals(annotation.examples().length, component.path("examples").size()); - for (var i = 0; i < annotation.examples().length; i++) { - assertEquals( - objectMapper.readTree(annotation.examples()[i]), component.path("examples").get(i)); + /** Accepting the examples proves nothing alone, since an empty schema accepts every value. */ + @ParameterizedTest + @CsvSource( + delimiter = '|', + textBlock = + """ + FilterDefinition | [] + FindAndRerankSort | {"vectorizeSort": "query"} + FindAndRerankSort | {"$hybrid": {"$lexical": 1}} + FindAndRerankSort | {"$hybrid": {"$vector": "query"}} + FindAndRerankSort | {"$hybrid": {"$vector": null, "$vectorize": null}} + HybridLimits | {"vectorLimit": 50, "lexicalLimit": 10} + HybridLimits | {"$vector": 50} + HybridLimits | {"$vector": 50, "$lexical": "10"} + """) + void clauseSchemasRejectInvalidJson(String clauseName, String json) throws Exception { + var clauseType = + clauseTypes().filter(type -> type.getSimpleName().equals(clauseName)).findFirst(); + assertTrue(clauseType.isPresent(), () -> "Not a clause type: " + clauseName); + assertSchemaRejects(schemaFor(clauseType.get()), objectMapper.readTree(json)); + } + + /** The findAndRerank sort parser accepts null and empty legs, so the schema must as well. */ + @ParameterizedTest + @CsvSource( + delimiter = '|', + textBlock = + """ + {"$hybrid": {"$vector": null, "$lexical": "query"}} + {"$hybrid": {"$vectorize": null, "$lexical": "query"}} + {"$hybrid": {"$vectorize": "query", "$lexical": null}} + {"$hybrid": {"$vector": [1, 2, 3], "$lexical": null}} + {"$hybrid": {"$vector": null}} + {"$hybrid": {"$vectorize": null}} + {"$hybrid": {"$lexical": null}} + {"$hybrid": {}} + {} + null + """) + void rerankSortAcceptsNullableAndEmptyJson(String json) throws Exception { + var sort = objectMapper.readTree(json); + assertSchemaAccepts(schemaFor(FindAndRerankSort.class), sort); + var clause = assertDoesNotThrow(() -> objectMapper.treeToValue(sort, FindAndRerankSort.class)); + if (!sort.isNull()) { + assertNotNull(clause); } - assertSchemaAccepts(schema, objectMapper.readTree("null")); - assertSchemaAccepts(schema, objectMapper.readTree("{\"some.path\": {\"$gt\": 40}}")); - assertFalse( - JsonSchemaFactory.getInstance(SpecVersion.VersionFlag.V202012) - .getSchema(schema) - .validate(objectMapper.readTree("[]")) - .isEmpty()); + assertSchemaAccepts(inputSchema("findAndRerank"), toolInput("{}").set("sort", sort)); } - /** A correct reusable schema has no effect unless command fields actually reference it. */ - @Test - void openApiCommandsReferenceSharedSchemas() throws Exception { - var document = openApi(); - var schemas = document.path("components").path("schemas"); - var find = schemas.path("FindCommand").path("properties"); - assertEquals(schemas.path("FilterDefinition"), referencedSchema(document, find.path("filter"))); - assertEquals(schemas.path("SortDefinition"), referencedSchema(document, find.path("sort"))); - var rerank = schemas.path("FindAndRerankCommand").path("properties"); - assertEquals( - schemas.path("FindAndRerankSort"), referencedSchema(document, rerank.path("sort"))); - var options = referencedSchema(document, rerank.path("options")).path("properties"); - assertEquals( - schemas.path("HybridLimits"), referencedSchema(document, options.path("hybridLimits"))); - var openApiOverride = - (ObjectNode) referencedSchema(document, options.path("rerank")).deepCopy(); - // The field description belongs to the command options, not the reusable schema component. - openApiOverride.remove("description"); - assertEquals(schemas.path("RerankServiceOverride"), openApiOverride); - var mcpDocument = inputSchema("findAndRerank"); - var mcpOverride = - (ObjectNode) - referencedSchema(mcpDocument, propertySchema(mcpDocument, "options", "rerank")) - .deepCopy(); - ((ObjectNode) mcpOverride).remove("description"); - var expected = - objectMapper.createObjectNode().put("$ref", FindAndRerankCommand.RerankOverrideSchema.REF); - McpOpenApiSchemaAdapter.bundleOpenApiSchemas(expected, document); - assertEquals(referencedSchema(expected, expected), mcpOverride); - } - - /** Check the complete command schema because inferred parent types can restrict valid clauses. */ + /** The update clause examples are the only place a client sees how each operator is written. */ @ParameterizedTest - @ValueSource(strings = {"50", "{\"$vector\": 50, \"$lexical\": 10}", "null"}) - void openApiAcceptsHybridLimitsWireForms(String limits) throws Exception { - var document = openApi(); - var schema = - objectMapper.createObjectNode().put("$ref", "#/components/schemas/FindAndRerankCommand"); - schema.set("components", document.path("components")); - var command = objectMapper.createObjectNode(); - command.putObject("sort").put("$hybrid", "search text"); - command.putObject("options").set("hybridLimits", objectMapper.readTree(limits)); - assertSchemaAccepts(schema, command); + @EnumSource(UpdateOperator.class) + void everyUpdateOperatorHasAnAdvertisedExample(UpdateOperator operator) { + var schema = schemaFor(UpdateClause.class); + var examples = schemaMetadata(schema, schema, "examples"); + assertTrue( + StreamSupport.stream(examples.spliterator(), false) + .anyMatch(example -> example.has(operator.apiName())), + () -> "Missing example for " + operator.apiName()); } - @Test - void openApiAcceptsNullOptionalClauses() throws Exception { - var schema = - objectMapper.createObjectNode().put("$ref", "#/components/schemas/FindAndRerankCommand"); - schema.set("components", openApi().path("components")); - assertSchemaAccepts( - schema, - objectMapper.readTree( - """ - {"filter": null, "sort": null, "options": {"rerank": null}} - """)); + /** Nonempty arguments exercise each operation's parser, including supported array modifiers. */ + @ParameterizedTest + @CsvSource( + delimiter = '|', + textBlock = + """ + {} + {"$set": {}} + {"$set": {"profile.name": "Ada", "optional": null}} + {"$set": {"created": {"$date": 123456}, "owner": {"$uuid": "550e8400-e29b-41d4-a716-446655440000"}}} + {"$set": {"nested": [null, true, 1.25, {"name": "Ada"}]}, "$unset": {"obsolete": 1}} + {"$unset": {"obsolete": null}} + {"$setOnInsert": {"created": true}} + {"$inc": {"score": 0.25}} + {"$mul": {"score": 1.5}} + {"$min": {"score": 2.5}} + {"$max": {"score": 9.5}} + {"$rename": {"oldName": "newName"}} + {"$currentDate": {"updated": true, "reviewed": {"$type": "date"}}} + {"$pop": {"first": -1, "last": 1}} + {"$push": {"items": {"$each": [1, 2], "$position": 0}}} + {"$addToSet": {"tags": {"$each": ["a", "b"]}}} + """) + void updateClauseAcceptsSupportedUpdates(String json) throws Exception { + var update = objectMapper.readTree(json); + assertSchemaAccepts(schemaFor(UpdateClause.class), update); + assertNotNull(objectMapper.treeToValue(update, UpdateClause.class).buildOperations()); } - private JsonNode referencedSchema(JsonNode document, JsonNode schema) { - var visited = new HashSet(); - while (schema.has("$ref")) { - var reference = schema.path("$ref").asText(); - assertTrue(reference.startsWith("#/"), "Expected a local schema reference"); - assertTrue(visited.add(reference), "Circular schema reference"); - schema = document.at(reference.substring(1)); - assertFalse(schema.isMissingNode(), "Unresolved schema reference " + reference); - } - return schema; + /** The update parser rejects these, so the schema must reject them too. */ + @ParameterizedTest + @CsvSource( + delimiter = '|', + textBlock = + """ + [] + 5 + "update" + {"name": "Ada"} + {"updateOperationDefs": {}} + {"$unknown": {}} + {"$set": null} + {"$set": 5} + {"$set": []} + {"$set": "value"} + """) + void updateClauseRejectsMalformedUpdates(String json) throws Exception { + var update = objectMapper.readTree(json); + assertSchemaRejects(schemaFor(UpdateClause.class), update); + assertThrows(UpdateException.class, () -> objectMapper.treeToValue(update, UpdateClause.class)); } - private JsonNode propertySchema(JsonNode document, String... names) { - var schema = document; - for (var name : names) { - schema = referencedSchema(document, schema).path("properties").path(name); - assertFalse(schema.isMissingNode(), "Missing property " + name); - } - return schema; - } + // ---- MCP tool input schemas, as the MCP server publishes them ---- - private JsonNode schemaMetadata(JsonNode document, JsonNode schema, String keyword) { - if (schema.has(keyword)) { - return schema.get(keyword); - } - if (schema.has("$ref")) { - return schemaMetadata(document, referencedSchema(document, schema), keyword); - } - for (var branch : schema.path("allOf")) { - var metadata = schemaMetadata(document, branch, keyword); - if (!metadata.isMissingNode()) { - return metadata; + /** + * Tool schemas describe the JSON clients send, so they must show JSON names and leave out fields + * the server keeps for itself. Each name below is a Java field on a class a tool argument uses. + */ + @Test + void toolSchemasHideJavaFieldNames() throws Exception { + var javaFieldNames = + List.of( + // @JsonIgnore fields on FilterDefinition, SortDefinition, and FindAndRerankSort. + "filterClause", + "sortClause", + "commandFeatures", + "rerankLegMode", + "hybridSort", + "vectorizeSort", + "lexicalSort", + "vectorSort", + // Fields the JSON names differently, on UpdateClause, HybridLimits, and Options. + "updateOperationDefs", + "vectorLimit", + "lexicalLimit", + "rerankServiceOverride"); + for (var tool : toolManager) { + var document = inputSchema(tool.name()); + for (var name : javaFieldNames) { + assertNull(document.findParent(name), () -> tool.name() + " schema shows " + name); } } - return MissingNode.getInstance(); } - private JsonNode openApi() throws Exception { - var json = - given() - .queryParam("format", "json") - .get("/api/json/openapi") - .then() - .statusCode(200) - .extract() - .asString(); - return objectMapper.readTree(json); - } - - @Test - void rerankToolUsesSortClassDescription() throws Exception { - var description = FindAndRerankSort.class.getAnnotation(Schema.class).description(); - assertFalse(description.isBlank()); - var document = inputSchema("findAndRerank"); - assertEquals( - description, - schemaMetadata(document, propertySchema(document, "sort"), "description").asText()); - } - - @Test - void rerankToolUsesFilterClassDescription() throws Exception { - var description = FilterDefinition.class.getAnnotation(Schema.class).description(); - assertFalse(description.isBlank()); - var document = inputSchema("findAndRerank"); - assertEquals( - description, - schemaMetadata(document, propertySchema(document, "filter"), "description").asText()); - } + /** + * Each update tool must use the update clause schema and require an update, as the command's + * validation does. The filter may be left out or null. + */ + @ParameterizedTest + @ValueSource(strings = {"updateOne", "updateMany", "findOneAndUpdate"}) + void updateToolsRequireAnUpdateClause(String tool) throws Exception { + var schema = inputSchema(tool); + var payload = toolInput("{}"); + payload.putObject("update"); + assertSchemaAccepts(schema, payload); + assertNotNull(parseUpdateCommand(tool, payload).updateClause().buildOperations()); + payload.putNull("filter"); + assertSchemaAccepts(schema, payload); + assertNotNull(parseUpdateCommand(tool, payload).updateClause().buildOperations()); - /** A description that only repeats the argument name tells a client nothing. */ - @Test - void rerankToolDescribesEveryArgument() throws Exception { - var document = inputSchema("findAndRerank"); - for (var argument : document.path("properties").properties()) { - var name = argument.getKey(); - var description = schemaMetadata(document, argument.getValue(), "description").asText(); - assertFalse(description.isBlank(), name); - assertNotEquals(name, description.toLowerCase(), name); - } + // Any object schema accepts this. Only the update clause schema rejects it. + payload.putObject("update").put("name", "Ada"); + assertSchemaRejects(schema, payload); + payload.remove("update"); + assertSchemaRejects(schema, payload); + assertFalse(validator.validate(command(tool, payload)).isEmpty()); + payload.putNull("update"); + assertSchemaRejects(schema, payload); + assertFalse(validator.validate(command(tool, payload)).isEmpty()); } - @Test - void rerankToolUsesOverrideFieldDescription() throws Exception { - var description = - FindAndRerankCommand.Options.class - .getDeclaredField("rerankServiceOverride") - .getAnnotation(Schema.class) - .description(); - assertFalse(description.isBlank()); - var document = inputSchema("findAndRerank"); - assertEquals( - description, - schemaMetadata(document, propertySchema(document, "options", "rerank"), "description") - .asText()); - } + // The findAndRerank rerank override has its own schema, written to match CollectionRerankDef. - /** Schema acceptance must agree with service validation of the override fields. */ + /** + * Schema acceptance must agree with service validation of the override fields. Whether + * credentials are allowed depends on the provider's configuration, which the schema cannot see, + * so the test provider here accepts a shared secret. + */ @ParameterizedTest - @MethodSource("rerankOverrides") + @CsvSource( + delimiter = '|', + textBlock = + """ + {"provider": "nvidia", "modelName": "nvidia/rerank-v1"} | true + {"provider": "nvidia", "modelName": "nvidia/rerank-v1", "authentication": {}, "parameters": {}} | true + {"provider": "nvidia", "modelName": "nvidia/rerank-v1", "authentication": null, "parameters": null} | true + {"provider": "nvidia", "modelName": "nvidia/rerank-v1", "authentication": {"providerKey": "credential-reference"}} | true + {"provider": "nvidia", "modelName": "nvidia/rerank-v1", "parameters": {"truncate": "END"}} | false + {} | false + {"provider": "nvidia"} | false + {"modelName": "nvidia/rerank-v1"} | false + {"provider": null, "modelName": "nvidia/rerank-v1"} | false + {"provider": "nvidia", "modelName": null} | false + {"provider": null, "modelName": null} | false + """) void rerankOverrideSchemaMatchesServiceValidation(String json, boolean accepted) throws Exception { - var schema = inputSchema("findAndRerank"); var payload = objectMapper.readTree(json); var command = toolInput("{}"); command.putObject("options").set("rerank", payload); - var errors = - JsonSchemaFactory.getInstance(SpecVersion.VersionFlag.V202012) - .getSchema(schema) - .validate(command); + var errors = schemaErrors(inputSchema("findAndRerank"), command); assertEquals( accepted, errors.isEmpty(), () -> "Schema validation for " + json + " returned " + errors); - Executable validate = () -> validateRerankOverride(payload, AuthenticationType.NONE); + Executable validate = () -> validateRerankOverride(payload); if (accepted) { assertDoesNotThrow(validate); } else { @@ -410,160 +347,6 @@ void rerankOverrideSchemaMatchesServiceValidation(String json, boolean accepted) } } - static Stream rerankOverrides() { - return Stream.of( - Arguments.of( - """ - {"provider": "nvidia", "modelName": "nvidia/rerank-v1"} - """, - true), - Arguments.of( - """ - {"provider": "nvidia", "modelName": "nvidia/rerank-v1", - "authentication": {}, "parameters": {}} - """, - true), - Arguments.of( - """ - {"provider": "nvidia", "modelName": "nvidia/rerank-v1", - "authentication": null, "parameters": null} - """, - true), - Arguments.of( - """ - {"provider": "nvidia", "modelName": "nvidia/rerank-v1", - "parameters": {"truncate": "END"}} - """, - false), - Arguments.of("{}", false), - Arguments.of( - """ - {"provider": "nvidia"} - """, - false), - Arguments.of( - """ - {"modelName": "nvidia/rerank-v1"} - """, - false), - Arguments.of( - """ - {"provider": null, "modelName": "nvidia/rerank-v1"} - """, - false), - Arguments.of( - """ - {"provider": "nvidia", "modelName": null} - """, - false), - Arguments.of( - """ - {"provider": null, "modelName": null} - """, - false)); - } - - /** The schema allows credentials because the provider configuration determines support. */ - @ParameterizedTest - @EnumSource(AuthenticationType.class) - void rerankAuthenticationValidationDependsOnProvider(AuthenticationType authenticationType) - throws Exception { - var payload = - objectMapper.readTree( - """ - {"provider": "nvidia", "modelName": "nvidia/rerank-v1", - "authentication": {"providerKey": "credential-reference"}} - """); - var command = toolInput("{}"); - command.putObject("options").set("rerank", payload); - assertSchemaAccepts(inputSchema("findAndRerank"), command); - - Executable validate = () -> validateRerankOverride(payload, authenticationType); - if (authenticationType == AuthenticationType.SHARED_SECRET) { - assertDoesNotThrow(validate); - } else { - var error = assertThrows(RequestException.class, validate); - assertEquals(RequestException.Code.INVALID_RERANK_OVERRIDE.name(), error.code); - } - } - - private CollectionRerankDef.RerankServiceDef validateRerankOverride( - JsonNode payload, AuthenticationType authenticationType) throws Exception { - var override = - objectMapper.treeToValue(payload, CreateCollectionCommand.Options.RerankServiceDesc.class); - return CollectionRerankDef.validateServiceDesc( - supportedRerankingProvider(authenticationType), - override.provider(), - override.modelName(), - override.authentication(), - override.parameters(), - RequestException.Code.INVALID_RERANK_OVERRIDE); - } - - private static RerankingProvidersConfig supportedRerankingProvider( - AuthenticationType authenticationType) { - var model = - new ModelConfigImpl( - "nvidia/rerank-v1", - new ApiModelSupport.ApiModelSupportImpl( - ApiModelSupport.SupportStatus.SUPPORTED, Optional.empty()), - false, - "https://example.com/rerank", - new RequestPropertiesImpl(3, 10, 100, 100, 0.5, 10)); - return new RerankingProvidersConfigImpl( - Map.of( - "nvidia", - new RerankingProviderConfigImpl( - false, - "nvidia", - true, - Map.of(authenticationType, new AuthenticationConfigImpl(true, List.of())), - List.of(model)))); - } - - @ParameterizedTest - @ValueSource(strings = {"50", "{\"$vector\": 50, \"$lexical\": 10}"}) - void rerankToolAcceptsWirePayloads(String limits) throws Exception { - var payload = - toolInput( - """ - { - "filter": {"age": {"$gt": 40}}, - "sort": {"$hybrid": "search text"}, - "options": {"rerank": {"provider": "nvidia", "modelName": "nvidia/rerank-v1"}} - } - """); - ((ObjectNode) payload.path("options")).set("hybridLimits", objectMapper.readTree(limits)); - assertSchemaAccepts(inputSchema("findAndRerank"), payload); - } - - @ParameterizedTest - @ValueSource( - strings = { - "{\"$hybrid\":{\"$vector\":null,\"$lexical\":\"query\"}}", - "{\"$hybrid\":{\"$vectorize\":null,\"$lexical\":\"query\"}}", - "{\"$hybrid\":{\"$vectorize\":\"query\",\"$lexical\":null}}", - "{\"$hybrid\":{\"$vector\":[1,2,3],\"$lexical\":null}}", - "{\"$hybrid\":{\"$vector\":null}}", - "{\"$hybrid\":{\"$vectorize\":null}}", - "{\"$hybrid\":{\"$lexical\":null}}", - "{\"$hybrid\":{}}", - "{}", - "null" - }) - void sortSchemaAcceptsNullableAndEmptyWireForms(String json) throws Exception { - var sort = objectMapper.readTree(json); - assertSchemaAccepts(schemaFor(FindAndRerankSort.class), sort); - var clause = assertDoesNotThrow(() -> objectMapper.treeToValue(sort, FindAndRerankSort.class)); - if (!sort.isNull()) { - assertNotNull(clause); - } - - var payload = toolInput("{}"); - payload.set("sort", sort); - assertSchemaAccepts(inputSchema("findAndRerank"), payload); - } - @Test void rerankOverrideExamplesDeserialize() throws Exception { var document = inputSchema("findAndRerank"); @@ -581,217 +364,95 @@ void rerankOverrideExamplesDeserialize() throws Exception { } } - @Test - void findToolAcceptsWirePayloads() throws Exception { - var payload = - toolInput( - """ - {"filter": {"age": {"$gt": 40}}, "sort": {"user.age": -1, "user.name": 1}} - """); - assertSchemaAccepts(inputSchema("find"), payload); - } - - @ParameterizedTest - @MethodSource("invalidToolPayloads") - void toolSchemasRejectInvalidPayloads(String tool, String json) throws Exception { - var schema = - JsonSchemaFactory.getInstance(SpecVersion.VersionFlag.V202012).getSchema(inputSchema(tool)); - assertFalse(schema.validate(toolInput(json)).isEmpty()); - } - - static Stream invalidToolPayloads() { - return Stream.of( - Arguments.of("find", "{\"filter\": 5}"), - Arguments.of("find", "{\"sort\": []}"), - Arguments.of("findAndRerank", "{\"sort\": {\"vectorizeSort\": \"query\"}}"), - Arguments.of("findAndRerank", "{\"sort\": {\"$hybrid\": {\"$vector\": \"query\"}}}"), - Arguments.of("findAndRerank", "{\"options\": {\"hybridLimits\": {\"$vector\": 50}}}"), - Arguments.of("findAndRerank", "{\"options\": {\"rerank\": {\"provider\": \"nvidia\"}}}")); - } - - private ObjectNode toolInput(String json) throws Exception { - // Routing arguments are required by MCP but are not part of the command clauses. - return ((ObjectNode) objectMapper.readTree(json)) - .put("keyspace", "default_keyspace") - .put("collection", "documents"); - } - - /** Positive examples alone would also pass against a schema that accepts every JSON value. */ - @ParameterizedTest - @MethodSource("invalidWireShapes") - void schemaRejectsInvalidWireShapes(Class clauseType, String json) throws Exception { - var schema = - JsonSchemaFactory.getInstance(SpecVersion.VersionFlag.V202012) - .getSchema(schemaFor(clauseType)); - assertFalse(schema.validate(objectMapper.readTree(json)).isEmpty()); - } - - static Stream invalidWireShapes() { - return Stream.of( - Arguments.of(FindAndRerankSort.class, "{\"vectorizeSort\": \"query\"}"), - Arguments.of(FindAndRerankSort.class, "{\"$hybrid\": {\"$lexical\": 1}}"), - Arguments.of(FindAndRerankSort.class, "{\"$hybrid\": {\"$vector\": \"query\"}}"), - Arguments.of( - FindAndRerankSort.class, "{\"$hybrid\": {\"$vector\": null, \"$vectorize\": null}}"), - Arguments.of( - FindAndRerankCommand.HybridLimits.class, "{\"vectorLimit\": 50, \"lexicalLimit\": 10}"), - Arguments.of(FindAndRerankCommand.HybridLimits.class, "{\"$vector\": 50}"), - Arguments.of( - FindAndRerankCommand.HybridLimits.class, "{\"$vector\": 50, \"$lexical\": \"10\"}")); - } + // ---- OpenAPI command schemas, as the server publishes them for Swagger ---- + /** The HTTP API accepts this JSON, so the OpenAPI command schemas must accept it too. */ @ParameterizedTest - @EnumSource(UpdateOperator.class) - void everyUpdateOperatorHasAnAdvertisedExample(UpdateOperator operator) { - var schema = schemaFor(UpdateClause.class); - var examples = schemaMetadata(schema, schema, "examples"); - assertTrue( - StreamSupport.stream(examples.spliterator(), false) - .anyMatch(example -> example.has(operator.apiName())), - () -> "Missing example for " + operator.apiName()); - } - - @ParameterizedTest - @MethodSource("supportedUpdates") - void updateToolsAcceptSupportedUpdates(String tool, String json) throws Exception { - var payload = updateToolInput(objectMapper.readTree(json)); - assertSchemaAccepts(inputSchema(tool), payload); - assertNotNull(parseUpdateCommand(tool, payload).updateClause().buildOperations()); - } - - static Stream supportedUpdates() { - // Nonempty arguments exercise each operation's parser, including supported array modifiers. - var updates = - List.of( - "{}", - """ - {"$set": {}} - """, - """ - {"$set": {"profile.name": "Ada", "optional": null}} - """, - """ - {"$unset": {"obsolete": null}} - """, - """ - {"$setOnInsert": {"created": true}} - """, - """ - {"$inc": {"score": 0.25}} - """, - """ - {"$mul": {"score": 1.5}} - """, - """ - {"$min": {"score": 2.5}} - """, - """ - {"$max": {"score": 9.5}} - """, - """ - {"$rename": {"oldName": "newName"}} - """, - """ - {"$currentDate": {"updated": true, "reviewed": {"$type": "date"}}} - """, - """ - {"$pop": {"first": -1, "last": 1}} - """, - """ - {"$push": {"items": {"$each": [1, 2], "$position": 0}}} - """, - """ - {"$addToSet": {"tags": {"$each": ["a", "b"]}}} - """, - """ - {"$set": {"created": {"$date": 123456}, - "owner": {"$uuid": "550e8400-e29b-41d4-a716-446655440000"}, - "nested": {"values": [null, true, 1.25, {"name": "Ada"}]}}, - "$unset": {"obsolete": 1}} - """); - return forUpdateTools(updates); - } - + @CsvSource( + delimiter = '|', + textBlock = + """ + FindCommand | {"filter": {"age": {"$gt": 40}}, "sort": {"user.age": -1}} + FindAndRerankCommand | {"sort": {"$hybrid": "search text"}, "options": {"hybridLimits": 50}} + FindAndRerankCommand | {"sort": {"$hybrid": "search text"}, "options": {"hybridLimits": {"$vector": 50, "$lexical": 10}}} + FindAndRerankCommand | {"sort": {"$hybrid": "search text"}, "options": {"hybridLimits": null}} + FindAndRerankCommand | {"filter": null, "sort": null, "options": {"rerank": null}} + UpdateOneCommand | {"filter": {"_id": "doc1"}, "update": {"$set": {"name": "Ada"}}} + """) + void openApiCommandsAcceptValidPayloads(String command, String json) throws Exception { + assertSchemaAccepts(openApiCommandSchema(command), objectMapper.readTree(json)); + } + + /** + * A command schema that accepts everything passes the test above, so check it rejects too. Each + * payload is an accepted one with a single clause broken. + */ @ParameterizedTest - @MethodSource("malformedUpdates") - void updateToolsRejectMalformedUpdates(String tool, String json) throws Exception { - var update = objectMapper.readTree(json); - assertSchemaRejects(inputSchema(tool), updateToolInput(update)); - assertThrows(UpdateException.class, () -> objectMapper.treeToValue(update, UpdateClause.class)); - } - - static Stream malformedUpdates() { - var updates = - List.of( - "[]", - "5", - """ - "update" - """, - """ - {"name": "Ada"} - """, - """ - {"updateOperationDefs": {}} - """, - """ - {"$unknown": {}} - """, - """ - {"$set": null} - """, - """ - {"$set": 5} - """, - """ - {"$set": []} - """, - """ - {"$set": "value"} - """); - return forUpdateTools(updates); + @CsvSource( + delimiter = '|', + textBlock = + """ + FindCommand | {"filter": 5, "sort": {"user.age": -1}} + FindCommand | {"filter": {"age": {"$gt": 40}}, "sort": []} + FindAndRerankCommand | {"sort": {"vectorizeSort": "query"}} + FindAndRerankCommand | {"sort": {"$hybrid": "search text"}, "options": {"hybridLimits": {"$vector": 50}}} + FindAndRerankCommand | {"sort": {"$hybrid": "search text"}, "options": {"rerank": {"provider": "nvidia"}}} + UpdateOneCommand | {"filter": {"_id": "doc1"}, "update": {"$unknown": {}}} + """) + void openApiCommandsRejectInvalidPayloads(String command, String json) throws Exception { + assertSchemaRejects(openApiCommandSchema(command), objectMapper.readTree(json)); + } + + // ---- Helpers ---- + + /** Generates a schema for one type the way the MCP server does for a tool argument. */ + private JsonNode schemaFor(Class type) { + var builder = + new SchemaGeneratorConfigBuilder( + objectMapper, SchemaVersion.DRAFT_2020_12, OptionPreset.PLAIN_JSON) + .without(Option.SCHEMA_VERSION_INDICATOR); + new McpSchemaCustomizer().customize(builder); + var schema = new SchemaGenerator(builder.build()).generateSchema(type); + McpOpenApiSchemaAdapter.bundleOpenApiSchemas( + schema, McpOpenApiSchemaAdapter.readGeneratedOpenApiDocument()); + return schema; } - // updateOne is the only update tool that also serves tables. - @Test - void updateOneAcceptsTableOnlyPullAll() throws Exception { - var update = - objectMapper.readTree( - """ - {"$pullAll": {"listColumn": [1]}} - """); - var payload = updateToolInput(update); - assertSchemaAccepts(inputSchema("updateOne"), payload); - assertEquals( - Set.of(UpdateOperator.PULL_ALL), - parseUpdateCommand("updateOne", payload).updateClause().updateOperationDefs().keySet()); + /** The input schema the MCP server publishes for a registered tool. */ + private JsonNode inputSchema(String name) throws Exception { + var tool = toolManager.getTool(name); + assertNotNull(tool); + return objectMapper.readTree(schemaGenerator.generate(tool).asJson()); } - @ParameterizedTest - @ValueSource(strings = {"updateOne", "updateMany", "findOneAndUpdate"}) - void updateIsRequiredAndFilterMayBeOmittedOrNull(String tool) throws Exception { - var schema = inputSchema(tool); - var payload = updateToolInput(objectMapper.readTree("{}")); - assertSchemaAccepts(schema, payload); - assertNotNull(parseUpdateCommand(tool, payload).updateClause().buildOperations()); - payload.putNull("filter"); - assertSchemaAccepts(schema, payload); - assertNotNull(parseUpdateCommand(tool, payload).updateClause().buildOperations()); - - payload.remove("update"); - assertSchemaRejects(schema, payload); - assertFalse(validator.validate(command(tool, payload)).isEmpty()); - payload.putNull("update"); - assertSchemaRejects(schema, payload); - assertFalse(validator.validate(command(tool, payload)).isEmpty()); + /** A self-contained schema for one command component of the served OpenAPI document. */ + private JsonNode openApiCommandSchema(String command) throws Exception { + var components = openApi().path("components"); + assertFalse( + components.path("schemas").path(command).isMissingNode(), + "Missing OpenAPI component " + command); + var schema = objectMapper.createObjectNode().put("$ref", "#/components/schemas/" + command); + schema.set("components", components); + return schema; } - private static Stream forUpdateTools(List updates) { - return UPDATE_TOOLS.stream().flatMap(t -> updates.stream().map(u -> Arguments.of(t, u))); + private JsonNode openApi() throws Exception { + var json = + given() + .queryParam("format", "json") + .get("/api/json/openapi") + .then() + .statusCode(200) + .extract() + .asString(); + return objectMapper.readTree(json); } - private ObjectNode updateToolInput(JsonNode update) throws Exception { - return toolInput("{}").set("update", update); + private ObjectNode toolInput(String json) throws Exception { + // Routing arguments are required by MCP but are not part of the command clauses. + return ((ObjectNode) objectMapper.readTree(json)) + .put("keyspace", "default_keyspace") + .put("collection", "documents"); } private Updatable parseUpdateCommand(String tool, ObjectNode payload) throws Exception { @@ -808,73 +469,95 @@ private Command command(String tool, ObjectNode payload) throws Exception { objectMapper.createObjectNode().set(tool, arguments), Command.class); } - private void assertSchemaRejects(JsonNode schema, JsonNode payload) { - assertFalse( - JsonSchemaFactory.getInstance(SpecVersion.VersionFlag.V202012) - .getSchema(schema) - .validate(payload) - .isEmpty(), - () -> "Schema accepted malformed payload " + payload); + private CollectionRerankDef.RerankServiceDef validateRerankOverride(JsonNode payload) + throws Exception { + var override = + objectMapper.treeToValue(payload, CreateCollectionCommand.Options.RerankServiceDesc.class); + return CollectionRerankDef.validateServiceDesc( + sharedSecretRerankingProvider(), + override.provider(), + override.modelName(), + override.authentication(), + override.parameters(), + RequestException.Code.INVALID_RERANK_OVERRIDE); } - private void assertSchemaAccepts(JsonNode schema, JsonNode example) { - var validator = - JsonSchemaFactory.getInstance(SpecVersion.VersionFlag.V202012).getSchema(schema); - assertTrue(validator.validate(example).isEmpty(), () -> validator.validate(example).toString()); + /** One enabled nvidia provider and model that accepts a shared secret. */ + private static RerankingProvidersConfig sharedSecretRerankingProvider() { + var model = + new ModelConfigImpl( + "nvidia/rerank-v1", + new ApiModelSupport.ApiModelSupportImpl( + ApiModelSupport.SupportStatus.SUPPORTED, Optional.empty()), + false, + "https://example.com/rerank", + new RequestPropertiesImpl(3, 10, 100, 100, 0.5, 10)); + return new RerankingProvidersConfigImpl( + Map.of( + "nvidia", + new RerankingProviderConfigImpl( + false, + "nvidia", + true, + Map.of( + AuthenticationType.SHARED_SECRET, + new AuthenticationConfigImpl(true, List.of())), + List.of(model)))); } - @Test - void collectionCreationAcceptsRerankAuthenticationAndParameters() throws Exception { - var payload = - objectMapper.readTree( - """ - { - "provider": "nvidia", "modelName": "nvidia/rerank-v1", - "authentication": {"providerKey": "credential-reference"}, - "parameters": {"truncate": "END"} - } - """); - assertSchemaAccepts( - schemaFor(CreateCollectionCommand.Options.RerankServiceDesc.class), payload); - assertEquals( - new CreateCollectionCommand.Options.RerankServiceDesc( - "nvidia", - "nvidia/rerank-v1", - Map.of("providerKey", "credential-reference"), - Map.of("truncate", "END")), - objectMapper.treeToValue(payload, CreateCollectionCommand.Options.RerankServiceDesc.class)); + /** Follows local {@code $ref} links until it reaches the schema they point to. */ + private JsonNode referencedSchema(JsonNode document, JsonNode schema) { + var visited = new HashSet(); + while (schema.has("$ref")) { + var reference = schema.path("$ref").asText(); + assertTrue(reference.startsWith("#/"), "Expected a local schema reference"); + assertTrue(visited.add(reference), "Circular schema reference"); + schema = document.at(reference.substring(1)); + assertFalse(schema.isMissingNode(), "Unresolved schema reference " + reference); + } + return schema; } - @Test - void allRegisteredToolsGenerateInputSchemas() { - var count = 0; - // Exercise named OpenAPI lookups for every tool, including ordinary options records. - for (var tool : toolManager) { - var schema = - assertDoesNotThrow( - () -> objectMapper.readTree(schemaGenerator.generate(tool).asJson()), tool.name()); - assertTrue(schema.path("properties").isObject(), tool.name()); - count++; + /** The schema of a nested property, such as {@code options} then {@code rerank}. */ + private JsonNode propertySchema(JsonNode document, String... names) { + var schema = document; + for (var name : names) { + schema = referencedSchema(document, schema).path("properties").path(name); + assertFalse(schema.isMissingNode(), "Missing property " + name); } - assertTrue(count > 0, "The MCP server must register tools"); + return schema; } - private JsonNode inputSchema(String name) throws Exception { - // The registered tool includes nested command fields and the application's customizer wiring. - var tool = toolManager.getTool(name); - assertNotNull(tool); - return objectMapper.readTree(schemaGenerator.generate(tool).asJson()); + /** A keyword such as {@code examples}, found on the schema or through its refs and allOf. */ + private JsonNode schemaMetadata(JsonNode document, JsonNode schema, String keyword) { + if (schema.has(keyword)) { + return schema.get(keyword); + } + if (schema.has("$ref")) { + return schemaMetadata(document, referencedSchema(document, schema), keyword); + } + for (var branch : schema.path("allOf")) { + var metadata = schemaMetadata(document, branch, keyword); + if (!metadata.isMissingNode()) { + return metadata; + } + } + return MissingNode.getInstance(); } - private JsonNode schemaFor(Class type) { - var builder = - new SchemaGeneratorConfigBuilder( - objectMapper, SchemaVersion.DRAFT_2020_12, OptionPreset.PLAIN_JSON) - .without(Option.SCHEMA_VERSION_INDICATOR); - new McpSchemaCustomizer().customize(builder); - var schema = new SchemaGenerator(builder.build()).generateSchema(type); - McpOpenApiSchemaAdapter.bundleOpenApiSchemas( - schema, McpOpenApiSchemaAdapter.readGeneratedOpenApiDocument()); - return schema; + private Set schemaErrors(JsonNode schema, JsonNode payload) { + return JsonSchemaFactory.getInstance(SpecVersion.VersionFlag.V202012) + .getSchema(schema) + .validate(payload); + } + + private void assertSchemaAccepts(JsonNode schema, JsonNode payload) { + var errors = schemaErrors(schema, payload); + assertTrue(errors.isEmpty(), () -> "Schema rejected " + payload + ": " + errors); + } + + private void assertSchemaRejects(JsonNode schema, JsonNode payload) { + assertFalse( + schemaErrors(schema, payload).isEmpty(), () -> "Schema accepted invalid " + payload); } } diff --git a/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpSchemaCustomizerTest.java b/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpSchemaCustomizerTest.java index 9ec348f1f1..999771aa98 100644 --- a/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpSchemaCustomizerTest.java +++ b/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpSchemaCustomizerTest.java @@ -2,193 +2,112 @@ import static org.junit.jupiter.api.Assertions.*; +import com.fasterxml.jackson.annotation.JsonIgnore; +import com.fasterxml.jackson.annotation.JsonProperty; import com.fasterxml.jackson.databind.JsonNode; import com.github.victools.jsonschema.generator.Option; import com.github.victools.jsonschema.generator.OptionPreset; import com.github.victools.jsonschema.generator.SchemaGenerator; import com.github.victools.jsonschema.generator.SchemaGeneratorConfigBuilder; import com.github.victools.jsonschema.generator.SchemaVersion; +import java.util.List; +import java.util.Set; +import java.util.TreeSet; import org.eclipse.microprofile.openapi.annotations.media.Schema; import org.junit.jupiter.api.Test; /** - * Checks OpenAPI references and annotation descriptions supplied by {@link McpSchemaCustomizer}. + * Unit tests for {@link McpSchemaCustomizer}. Each test covers one rule the customizer adds to the + * MCP schema generator, using records that apply the rule next to fields that do not. */ class McpSchemaCustomizerTest { + private static final String COMPONENT_REF = "#/components/schemas/CustomizerTestSchema"; - /** - * Test record that mimics nested command structures such as {@link - * io.stargate.sgv2.jsonapi.api.model.command.impl.CreateTableCommand}. CreateTableCommand → - * TableDefinitionDesc → PrimaryKeyDesc - */ - record TestPrimaryKey( - @Schema(description = "Partition key columns") String[] keys, - @Schema(description = "Clustering key ordering") String ordering) {} + record PropertyNames( + @JsonProperty("wireName") String javaName, + // Jackson treats an empty name as "use the Java name". + @JsonProperty("") String emptyName, + String plain) {} - record TestDefinition( - @Schema(description = "Column definitions for the table") String columns, - @Schema(description = "Primary key definition") TestPrimaryKey primaryKey) {} + record IgnoredFields( + @JsonIgnore String ignored, + @JsonIgnore(false) String notIgnored, + @Schema(hidden = true) String hidden, + @Schema(description = "Not hidden") String visible) {} - record TestOptions( - @Schema(description = "Flag to ignore if already exists") Boolean ifNotExists) {} + @Schema(description = "Type description") + record DescribedType(String value) {} - record TestCreateTable( - @Schema(description = "Table definition") TestDefinition definition, - @Schema(description = "Configuration options") TestOptions options, - Boolean noAnnotation) {} - - @Schema(description = "Reusable value description") - record TestDescribedType(String value) {} - - record TestTypeDescription(TestDescribedType value) {} - - record TestHiddenFields(@Schema(hidden = true) String internal, String visible) {} - - record TestNamedField(@Schema(name = "aPropertyName") String value) {} + record Descriptions( + @Schema(description = "Field description") String described, + @Schema(description = " ") String blank, + String plain, + DescribedType typed) {} @Schema(name = "CustomizerTestSchema") - record TestSharedType(String internalValue) {} + record NamedType(String javaField) {} - @Schema(ref = "#/components/schemas/CustomizerTestSchema") - record TestReferencedType(String internalValue) {} + @Schema(ref = COMPONENT_REF) + record ReferencedType(String javaField) {} - record TestFieldValue(String internalValue) {} + record FieldValue(String javaField) {} - record TestSharedFields( - @Schema(ref = "#/components/schemas/CustomizerTestSchema", description = "First field") - TestFieldValue first, - @Schema(ref = "#/components/schemas/CustomizerTestSchema", description = "Second field") - TestFieldValue second) {} + record References( + NamedType namedType, + ReferencedType referencedType, + @Schema(ref = COMPONENT_REF, description = "Field description") FieldValue referencedField, + // A field's @Schema name only names the property, so the field keeps its own type. + @Schema(name = "notAComponent") String namedField, + // A type @Schema without a name or ref keeps the Java fields. + DescribedType describedType) {} @Test - void shouldReferenceNamedComponentInsteadOfInternalJavaFields() { - var schema = schemaFor(TestSharedType.class); - - assertEquals("#/components/schemas/CustomizerTestSchema", schema.path("$ref").asText()); - assertFalse(schema.path("properties").has("internalValue")); + void propertiesUseJsonPropertyNames() { + assertEquals(Set.of("wireName", "emptyName", "plain"), propertyNames(PropertyNames.class)); } @Test - void shouldKeepExplicitComponentReference() { - assertEquals(schemaFor(TestSharedType.class), schemaFor(TestReferencedType.class)); + void ignoredAndHiddenFieldsAreLeftOut() { + assertEquals(Set.of("notIgnored", "visible"), propertyNames(IgnoredFields.class)); } @Test - void shouldKeepFieldReferencesAndDescriptions() { - var properties = schemaFor(TestSharedFields.class).path("properties"); + void descriptionsComeFromSchemaAnnotations() { + var properties = schemaFor(Descriptions.class).path("properties"); - for (var name : new String[] {"first", "second"}) { - assertEquals( - "#/components/schemas/CustomizerTestSchema", properties.path(name).path("$ref").asText()); - assertFalse(properties.path(name).path("properties").has("internalValue")); - } - assertEquals("First field", properties.path("first").path("description").asText()); - assertEquals("Second field", properties.path("second").path("description").asText()); - assertFalse(schemaFor(TestSharedType.class).has("description")); + assertEquals("Field description", properties.path("described").path("description").asText()); + assertEquals("Type description", properties.path("typed").path("description").asText()); + assertFalse(properties.path("blank").has("description")); + assertFalse(properties.path("plain").has("description")); } @Test - void shouldOmitFieldsHiddenBySchemaAnnotation() { - var properties = schemaFor(TestHiddenFields.class).path("properties"); + void namedSchemasBecomeComponentReferences() { + var properties = schemaFor(References.class).path("properties"); - assertFalse(properties.has("internal")); - assertTrue(properties.has("visible")); + for (var name : List.of("namedType", "referencedType", "referencedField")) { + assertEquals(COMPONENT_REF, properties.path(name).path("$ref").asText(), name); + assertFalse(properties.path(name).has("properties"), name); + } + assertEquals( + "Field description", properties.path("referencedField").path("description").asText()); + assertEquals("string", properties.path("namedField").path("type").asText()); + assertFalse(properties.path("describedType").has("$ref")); + assertTrue(properties.path("describedType").path("properties").has("value")); } - @Test - void shouldNotTreatFieldSchemaNameAsComponentName() { - var schema = assertDoesNotThrow(() -> schemaFor(TestNamedField.class)); - - assertEquals("string", schema.path("properties").path("value").path("type").asText()); + private static Set propertyNames(Class type) { + var names = new TreeSet(); + schemaFor(type).path("properties").fieldNames().forEachRemaining(names::add); + return names; } + /** Generates a schema the way Quarkus MCP Server's {@code DefaultSchemaGenerator} does. */ private static JsonNode schemaFor(Class type) { - var builder = baseConfigBuilder(); + var builder = + new SchemaGeneratorConfigBuilder(SchemaVersion.DRAFT_2020_12, OptionPreset.PLAIN_JSON) + .without(Option.SCHEMA_VERSION_INDICATOR); new McpSchemaCustomizer().customize(builder); return new SchemaGenerator(builder.build()).generateSchema(type); } - - @Test - void shouldIncludeRootTypeDescription() { - var configBuilder = baseConfigBuilder(); - new McpSchemaCustomizer().customize(configBuilder); - - var schema = new SchemaGenerator(configBuilder.build()).generateSchema(TestDescribedType.class); - - assertEquals("Reusable value description", schema.path("description").asText()); - } - - @Test - void shouldIncludeNestedTypeDescriptionWithoutFieldDescription() { - var configBuilder = baseConfigBuilder(); - new McpSchemaCustomizer().customize(configBuilder); - - var schema = - new SchemaGenerator(configBuilder.build()).generateSchema(TestTypeDescription.class); - - assertEquals( - "Reusable value description", - schema.path("properties").path("value").path("description").asText()); - } - - @Test - void shouldIncludeSchemaDescriptionWithCustomizer() { - var configBuilder = baseConfigBuilder(); - new McpSchemaCustomizer().customize(configBuilder); - - var schema = new SchemaGenerator(configBuilder.build()).generateSchema(TestCreateTable.class); - var props = schema.path("properties"); - - // Level 1: top-level fields - assertEquals("Table definition", props.path("definition").path("description").asText()); - assertEquals("Configuration options", props.path("options").path("description").asText()); - assertTrue( - props.path("noAnnotation").path("description").isMissingNode(), - "Fields without @Schema should have no description"); - - // Level 2: nested inside TestDefinition - var defProps = props.path("definition").path("properties"); - assertEquals( - "Column definitions for the table", defProps.path("columns").path("description").asText()); - assertEquals( - "Primary key definition", defProps.path("primaryKey").path("description").asText()); - - // Level 2: nested inside TestOptions - var optProps = props.path("options").path("properties"); - assertEquals( - "Flag to ignore if already exists", - optProps.path("ifNotExists").path("description").asText()); - - // Level 3: nested inside TestPrimaryKey - var pkProps = defProps.path("primaryKey").path("properties"); - assertEquals("Partition key columns", pkProps.path("keys").path("description").asText()); - assertEquals("Clustering key ordering", pkProps.path("ordering").path("description").asText()); - } - - @Test - void shouldNotIncludeDescriptionWithoutCustomizer() { - var schema = - new SchemaGenerator(baseConfigBuilder().build()).generateSchema(TestCreateTable.class); - - // Spot-check: a deeply nested field should have no description - var pkProps = - schema - .get("properties") - .get("definition") - .get("properties") - .get("primaryKey") - .get("properties"); - assertNull( - pkProps.get("keys").get("description"), - "Without customizer, PLAIN_JSON preset should not resolve @Schema descriptions"); - } - - /** - * Creates a {@link SchemaGeneratorConfigBuilder} matching the configuration used by Quarkus MCP - * Server's {@code DefaultSchemaGenerator}. - */ - private static SchemaGeneratorConfigBuilder baseConfigBuilder() { - return new SchemaGeneratorConfigBuilder(SchemaVersion.DRAFT_2020_12, OptionPreset.PLAIN_JSON) - .without(Option.SCHEMA_VERSION_INDICATOR); - } }