diff --git a/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/impl/FindEmbeddingProvidersCommand.java b/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/impl/FindEmbeddingProvidersCommand.java index 974574e154..d7df3ba304 100644 --- a/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/impl/FindEmbeddingProvidersCommand.java +++ b/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/impl/FindEmbeddingProvidersCommand.java @@ -20,7 +20,7 @@ public record Options( @Nullable @Schema( description = - "Optional filter to select models by required support status. If omitted, only SUPPORTED models are returned (ones which can be used when creating a new Collection or Table). Available values are SUPPORTED, DEPRECATED, and END_OF_LIFE (case-insensitive).", + "Optional filter to select models by required support status. If omitted, only SUPPORTED models are returned (ones which can be used when creating a new Collection or Table). Available values are SUPPORTED, DEPRECATED, and END_OF_LIFE (case-insensitive). Set to null or an empty string to return all models.", type = SchemaType.STRING, implementation = String.class) @Pattern(regexp = "(?i)^(SUPPORTED|DEPRECATED|END_OF_LIFE)?$") diff --git a/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/table/definition/TableDefinitionDesc.java b/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/table/definition/TableDefinitionDesc.java index deda07338f..b484e90b51 100644 --- a/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/table/definition/TableDefinitionDesc.java +++ b/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/table/definition/TableDefinitionDesc.java @@ -14,13 +14,17 @@ *

Has the columns and the primary key definition, not the name of the table. */ public record TableDefinitionDesc( - @Schema(description = "API table columns definitions", type = SchemaType.OBJECT) + @Schema( + description = + "Columns of the table, mapping each column name to its type, for example {\"id\": \"text\", \"title\": \"text\"}", + type = SchemaType.OBJECT) @JsonInclude(JsonInclude.Include.NON_NULL) @JsonProperty(TableDescConstants.TableDefinitionDesc.COLUMNS) ColumnsDescContainer columns, @Valid @Schema( - description = "Primary key definition for the table", + description = + "Primary key of the table, either the name of one column or an object with partitionBy and partitionSort", anyOf = {String.class, PrimaryKeyDesc.class}) @JsonInclude(JsonInclude.Include.NON_NULL) @JsonProperty(TableDescConstants.TableDefinitionDesc.PRIMARY_KEY) diff --git a/src/main/java/io/stargate/sgv2/jsonapi/api/v1/mcp/CollectionCommandTools.java b/src/main/java/io/stargate/sgv2/jsonapi/api/v1/mcp/CollectionCommandTools.java index efb89bf227..fa374343c7 100644 --- a/src/main/java/io/stargate/sgv2/jsonapi/api/v1/mcp/CollectionCommandTools.java +++ b/src/main/java/io/stargate/sgv2/jsonapi/api/v1/mcp/CollectionCommandTools.java @@ -22,6 +22,9 @@ * MCP tool provider for collection-level (and table-level) commands {@link * io.stargate.sgv2.jsonapi.api.model.command.CollectionCommand}. These correspond to the {@link * io.stargate.sgv2.jsonapi.api.v1.CollectionResource} REST endpoint. + * + *

The filter and sort arguments have no description here. A {@code @ToolArg} description would + * replace the one on their classes, which Swagger also uses. */ public class CollectionCommandTools { @@ -31,7 +34,10 @@ public class CollectionCommandTools { public Uni alterTable( @ToolArg(description = "Name of the keyspace") String keyspace, @ToolArg(description = "Name of the table") String table, - @ToolArg(description = "The alter table operation") AlterTableOperation operation) { + @ToolArg( + description = + "Alters the schema of a Table, to add or drop columns or configure vectorization, for example {\"add\": {\"columns\": {\"rating\": \"int\"}}}") + AlterTableOperation operation) { var command = new AlterTableCommand(operation); return mcpResource.processCollectionCommand(keyspace, table, command); @@ -41,7 +47,7 @@ public Uni alterTable( public Uni countDocuments( @ToolArg(description = "Name of the keyspace") String keyspace, @ToolArg(description = "Name of the collection") String collection, - @ToolArg(description = "filter", required = false) FilterDefinition filter) { + @ToolArg(required = false) FilterDefinition filter) { var command = new CountDocumentsCommand(filter); return mcpResource.processCollectionCommand(keyspace, collection, command); @@ -51,7 +57,7 @@ public Uni countDocuments( public Uni createIndex( @ToolArg(description = "Name of the keyspace") String keyspace, @ToolArg(description = "Name of the table") String table, - @ToolArg(description = "Name of the new Index") String indexName, + @ToolArg(description = "Name of the new index") String indexName, @ToolArg(description = "Definition of the index to create") RegularIndexDefinitionDesc definition, @ToolArg( @@ -74,7 +80,7 @@ public Uni createIndex( public Uni createTextIndex( @ToolArg(description = "Name of the keyspace") String keyspace, @ToolArg(description = "Name of the table") String table, - @ToolArg(description = "Name of the new Index") String indexName, + @ToolArg(description = "Name of the new index") String indexName, @ToolArg(description = "Definition of the index to create") TextIndexDefinitionDesc definition, @ToolArg( @@ -95,7 +101,7 @@ public Uni createTextIndex( public Uni createVectorIndex( @ToolArg(description = "Name of the keyspace") String keyspace, @ToolArg(description = "Name of the table") String table, - @ToolArg(description = "Name of the new Index") String indexName, + @ToolArg(description = "Name of the new index") String indexName, @ToolArg(description = "Definition of the index to create") VectorIndexDefinitionDesc definition, @ToolArg( @@ -117,11 +123,8 @@ public Uni createVectorIndex( "Command that finds documents based on the filter and deletes them from a collection") public Uni deleteMany( @ToolArg(description = "Name of the keyspace") String keyspace, - @ToolArg(description = "Name of the collection/table") String collection, - @ToolArg( - description = "Filter clause based on which documents are identified", - required = false) - FilterDefinition filter) { + @ToolArg(description = "Name of the collection or table") String collection, + @ToolArg(required = false) FilterDefinition filter) { var command = new DeleteManyCommand(filter); return mcpResource.processCollectionCommand(keyspace, collection, command); @@ -130,10 +133,9 @@ public Uni deleteMany( @Tool(description = "Command that finds a single document and deletes it from a collection") public Uni deleteOne( @ToolArg(description = "Name of the keyspace") String keyspace, - @ToolArg(description = "Name of the collection/table") String collection, - @ToolArg(description = "Filter clause based on which documents are identified") - FilterDefinition filter, - @ToolArg(description = "Sort clause", required = false) SortDefinition sort) { + @ToolArg(description = "Name of the collection or table") String collection, + @ToolArg FilterDefinition filter, + @ToolArg(required = false) SortDefinition sort) { var command = new DeleteOneCommand(filter, sort); return mcpResource.processCollectionCommand(keyspace, collection, command); @@ -152,8 +154,6 @@ public Uni estimatedDocumentCount( public Uni findAndRerank( @ToolArg(description = "Name of the keyspace") String keyspace, @ToolArg(description = "Name of the collection") String collection, - // filter and sort have no description here because it would replace the one on their - // classes, which Swagger also uses. @ToolArg(required = false) FilterDefinition filter, @ToolArg( description = @@ -161,9 +161,7 @@ public Uni findAndRerank( required = false) JsonNode projection, @ToolArg(required = false) FindAndRerankSort sort, - @ToolArg( - description = "Options for result limits, reranking, and what the response includes", - required = false) + @ToolArg(description = "Options for the command.", required = false) FindAndRerankCommand.Options options) { var command = new FindAndRerankCommand(filter, projection, sort, options); @@ -173,11 +171,16 @@ public Uni findAndRerank( @Tool(description = "Command that finds JSON documents from a collection.") public Uni find( @ToolArg(description = "Name of the keyspace") String keyspace, - @ToolArg(description = "Name of the collection/table") String collection, - @ToolArg(description = "filter", required = false) FilterDefinition filter, - @ToolArg(description = "projection", required = false) JsonNode projection, - @ToolArg(description = "sort", required = false) SortDefinition sort, - @ToolArg(description = "options", required = false) FindCommand.Options options) { + @ToolArg(description = "Name of the collection or table") String collection, + @ToolArg(required = false) FilterDefinition filter, + @ToolArg( + description = + "Fields to include or exclude in the returned documents, for example {\"title\": 1}", + required = false) + JsonNode projection, + @ToolArg(required = false) SortDefinition sort, + @ToolArg(description = "Options for the command.", required = false) + FindCommand.Options options) { var command = new FindCommand(filter, projection, sort, options); return mcpResource.processCollectionCommand(keyspace, collection, command); @@ -188,10 +191,14 @@ public Uni find( "Command that finds a single JSON document from a collection and deletes it. The deleted document is returned") public Uni findOneAndDelete( @ToolArg(description = "Name of the keyspace") String keyspace, - @ToolArg(description = "Name of the collection/table") String collection, - @ToolArg(description = "filter", required = false) FilterDefinition filter, - @ToolArg(description = "sort", required = false) SortDefinition sort, - @ToolArg(description = "projection", required = false) JsonNode projection) { + @ToolArg(description = "Name of the collection") String collection, + @ToolArg(required = false) FilterDefinition filter, + @ToolArg(required = false) SortDefinition sort, + @ToolArg( + description = + "Fields to include or exclude in the returned document, for example {\"title\": 1}", + required = false) + JsonNode projection) { var command = new FindOneAndDeleteCommand(filter, sort, projection); return mcpResource.processCollectionCommand(keyspace, collection, command); @@ -202,12 +209,16 @@ public Uni findOneAndDelete( "Command that finds a single JSON document from a collection and replaces it with the replacement document.") public Uni findOneAndReplace( @ToolArg(description = "Name of the keyspace") String keyspace, - @ToolArg(description = "Name of the collection/table") String collection, - @ToolArg(description = "filter", required = false) FilterDefinition filter, - @ToolArg(description = "sort", required = false) SortDefinition sort, - @ToolArg(description = "projection", required = false) JsonNode projection, - @ToolArg(description = "replacement") ObjectNode replacement, - @ToolArg(description = "options", required = false) + @ToolArg(description = "Name of the collection") String collection, + @ToolArg(required = false) FilterDefinition filter, + @ToolArg(required = false) SortDefinition sort, + @ToolArg( + description = + "Fields to include or exclude in the returned document, for example {\"title\": 1}", + required = false) + JsonNode projection, + @ToolArg(description = "Document that replaces the matching document") ObjectNode replacement, + @ToolArg(description = "Options for the command.", required = false) FindOneAndReplaceCommand.Options options) { var command = new FindOneAndReplaceCommand(filter, sort, projection, replacement, options); @@ -219,12 +230,17 @@ public Uni findOneAndReplace( "Command that finds a single JSON document from a collection and updates the values provided in the update clause.") public Uni findOneAndUpdate( @ToolArg(description = "Name of the keyspace") String keyspace, - @ToolArg(description = "Name of the collection/table") String collection, - @ToolArg(description = "filter", required = false) FilterDefinition filter, - @ToolArg(description = "projection", required = false) JsonNode projection, - @ToolArg(description = "sort", required = false) SortDefinition sort, - @ToolArg(description = "update") UpdateClause update, - @ToolArg(description = "options", required = false) FindOneAndUpdateCommand.Options options) { + @ToolArg(description = "Name of the collection") String collection, + @ToolArg(required = false) FilterDefinition filter, + @ToolArg( + description = + "Fields to include or exclude in the returned document, for example {\"title\": 1}", + required = false) + JsonNode projection, + @ToolArg(required = false) SortDefinition sort, + @ToolArg UpdateClause update, + @ToolArg(description = "Options for the command.", required = false) + FindOneAndUpdateCommand.Options options) { var command = new FindOneAndUpdateCommand(filter, projection, sort, update, options); return mcpResource.processCollectionCommand(keyspace, collection, command); @@ -233,11 +249,16 @@ public Uni findOneAndUpdate( @Tool(description = "Command that finds a single JSON document from a collection.") public Uni findOne( @ToolArg(description = "Name of the keyspace") String keyspace, - @ToolArg(description = "Name of the collection/table") String collection, - @ToolArg(description = "filter", required = false) FilterDefinition filter, - @ToolArg(description = "projection", required = false) JsonNode projection, - @ToolArg(description = "sort", required = false) SortDefinition sort, - @ToolArg(description = "options", required = false) FindOneCommand.Options options) { + @ToolArg(description = "Name of the collection or table") String collection, + @ToolArg(required = false) FilterDefinition filter, + @ToolArg( + description = + "Fields to include or exclude in the returned document, for example {\"title\": 1}", + required = false) + JsonNode projection, + @ToolArg(required = false) SortDefinition sort, + @ToolArg(description = "Options for the command.", required = false) + FindOneCommand.Options options) { var command = new FindOneCommand(filter, projection, sort, options); return mcpResource.processCollectionCommand(keyspace, collection, command); @@ -247,7 +268,7 @@ public Uni findOne( public Uni listIndexes( @ToolArg(description = "Name of the keyspace") String keyspace, @ToolArg(description = "Name of the table") String table, - @ToolArg(description = "Options for the `listIndexes` command.", required = false) + @ToolArg(description = "Options for the command.", required = false) ListIndexesCommand.Options options) { var command = new ListIndexesCommand(options); @@ -257,9 +278,9 @@ public Uni listIndexes( @Tool(description = "Command that inserts multiple JSON documents to a collection.") public Uni insertMany( @ToolArg(description = "Name of the keyspace") String keyspace, - @ToolArg(description = "Name of the collection/table") String collection, - @ToolArg(description = "JSON documents to insert") List documents, - @ToolArg(description = "Options for inserting many documents", required = false) + @ToolArg(description = "Name of the collection or table") String collection, + @ToolArg(description = "Documents or rows to insert") List documents, + @ToolArg(description = "Options for the command.", required = false) InsertManyCommand.Options options) { var command = new InsertManyCommand(documents, options); @@ -269,8 +290,8 @@ public Uni insertMany( @Tool(description = "Command that inserts a single JSON document to a collection.") public Uni insertOne( @ToolArg(description = "Name of the keyspace") String keyspace, - @ToolArg(description = "Name of the collection/table") String collection, - @ToolArg(description = "JSON document to insert") JsonNode document) { + @ToolArg(description = "Name of the collection or table") String collection, + @ToolArg(description = "Document or row to insert") JsonNode document) { var command = new InsertOneCommand(document); return mcpResource.processCollectionCommand(keyspace, collection, command); @@ -281,10 +302,11 @@ public Uni insertOne( "Command that finds documents from a collection and updates it with the values provided in the update clause.") public Uni updateMany( @ToolArg(description = "Name of the keyspace") String keyspace, - @ToolArg(description = "Name of the collection/table") String collection, - @ToolArg(description = "filter", required = false) FilterDefinition filter, - @ToolArg(description = "update") UpdateClause update, - @ToolArg(description = "options", required = false) UpdateManyCommand.Options options) { + @ToolArg(description = "Name of the collection") String collection, + @ToolArg(required = false) FilterDefinition filter, + @ToolArg UpdateClause update, + @ToolArg(description = "Options for the command.", required = false) + UpdateManyCommand.Options options) { var command = new UpdateManyCommand(filter, update, options); return mcpResource.processCollectionCommand(keyspace, collection, command); @@ -295,11 +317,12 @@ public Uni updateMany( "Command that finds a single JSON document from a table or collection and updates the values provided in the update clause.") public Uni updateOne( @ToolArg(description = "Name of the keyspace") String keyspace, - @ToolArg(description = "Name of the collection/table") String collection, - @ToolArg(description = "filter", required = false) FilterDefinition filter, - @ToolArg(description = "update") UpdateClause update, - @ToolArg(description = "sort", required = false) SortDefinition sort, - @ToolArg(description = "options", required = false) UpdateOneCommand.Options options) { + @ToolArg(description = "Name of the collection or table") String collection, + @ToolArg(required = false) FilterDefinition filter, + @ToolArg UpdateClause update, + @ToolArg(required = false) SortDefinition sort, + @ToolArg(description = "Options for the command.", required = false) + UpdateOneCommand.Options options) { var command = new UpdateOneCommand(filter, update, sort, options); return mcpResource.processCollectionCommand(keyspace, collection, command); diff --git a/src/main/java/io/stargate/sgv2/jsonapi/api/v1/mcp/GeneralCommandTools.java b/src/main/java/io/stargate/sgv2/jsonapi/api/v1/mcp/GeneralCommandTools.java index aaf01203ea..316545e8d0 100644 --- a/src/main/java/io/stargate/sgv2/jsonapi/api/v1/mcp/GeneralCommandTools.java +++ b/src/main/java/io/stargate/sgv2/jsonapi/api/v1/mcp/GeneralCommandTools.java @@ -22,8 +22,8 @@ public class GeneralCommandTools { @Tool(description = "Command that creates a keyspace.") public Uni createKeyspace( - @ToolArg(description = "Required name of the new Keyspace") String name, - @ToolArg(description = "Options for creating a new keyspace.", required = false) + @ToolArg(description = "Name of the new keyspace") String name, + @ToolArg(description = "Options for the command.", required = false) CreateKeyspaceCommand.Options options) { var command = new CreateKeyspaceCommand(name, options); @@ -32,7 +32,7 @@ public Uni createKeyspace( @Tool(description = "Command that deletes a Keyspace.") public Uni dropKeyspace( - @ToolArg(description = "Required name of the Keyspace to remove") @NotEmpty String name) { + @ToolArg(description = "Name of the keyspace to drop") @NotEmpty String name) { var command = new DropKeyspaceCommand(name); return mcpResource.processCommand(mcpResource.buildDatabaseContext(command), command); @@ -47,10 +47,7 @@ public Uni findKeyspaces() { @Tool(description = "Lists the available Embedding Providers for this database.") public Uni findEmbeddingProviders( - @ToolArg( - description = - "Optional model status filter: SUPPORTED, DEPRECATED, or END_OF_LIFE. If omitted, only SUPPORTED models are returned.", - required = false) + @ToolArg(description = "Options for the command.", required = false) FindEmbeddingProvidersCommand.Options options) { var command = new FindEmbeddingProvidersCommand(options); @@ -59,10 +56,7 @@ public Uni findEmbeddingProviders( @Tool(description = "Lists the available Reranking Providers for this database.") public Uni findRerankingProviders( - @ToolArg( - description = - "Optional model status filter: SUPPORTED, DEPRECATED, or END_OF_LIFE. If omitted, only SUPPORTED models are returned.", - required = false) + @ToolArg(description = "Options for the command.", required = false) FindRerankingProvidersCommand.Options options) { var command = new FindRerankingProvidersCommand(options); diff --git a/src/main/java/io/stargate/sgv2/jsonapi/api/v1/mcp/KeyspaceCommandTools.java b/src/main/java/io/stargate/sgv2/jsonapi/api/v1/mcp/KeyspaceCommandTools.java index faec415caa..2e2e5d6dcd 100644 --- a/src/main/java/io/stargate/sgv2/jsonapi/api/v1/mcp/KeyspaceCommandTools.java +++ b/src/main/java/io/stargate/sgv2/jsonapi/api/v1/mcp/KeyspaceCommandTools.java @@ -24,9 +24,9 @@ public class KeyspaceCommandTools { */ @Tool(description = "Command that creates a collection.") public Uni createCollection( - @ToolArg(description = "Name of the existing keyspace") String keyspace, + @ToolArg(description = "Name of the keyspace") String keyspace, @ToolArg(description = "Name of the new collection") String collection, - @ToolArg(description = "Configuration options for the collection", required = false) + @ToolArg(description = "Options for the command.", required = false) CreateCollectionCommand.Options options) { var command = new CreateCollectionCommand(collection, options); @@ -35,8 +35,8 @@ public Uni createCollection( @Tool(description = "Command that deletes a collection if one exists.") public Uni deleteCollection( - @ToolArg(description = "Name of the existing Keyspace") String keyspace, - @ToolArg(description = "Name of the existing Collection") String collection) { + @ToolArg(description = "Name of the keyspace") String keyspace, + @ToolArg(description = "Name of the collection to delete") String collection) { var command = new DeleteCollectionCommand(collection); return mcpResource.processCommand(mcpResource.buildKeyspaceContext(keyspace, command), command); @@ -44,8 +44,8 @@ public Uni deleteCollection( @Tool(description = "Command that lists all available collections in a keyspace.") public Uni findCollections( - @ToolArg(description = "Name of the existing Keyspace") String keyspace, - @ToolArg(description = "include collection properties.", required = false) + @ToolArg(description = "Name of the keyspace") String keyspace, + @ToolArg(description = "Options for the command.", required = false) FindCollectionsCommand.Options options) { var command = new FindCollectionsCommand(options); @@ -57,11 +57,11 @@ public Uni findCollections( */ @Tool(description = "Command that alters a user defined type.") public Uni alterType( - @ToolArg(description = "Keyspace of the type to alter") String keyspace, + @ToolArg(description = "Name of the keyspace") String keyspace, @ToolArg(description = "Name of the type to alter") String name, - @ToolArg(description = "Operation to rename fields", required = false) - RenameTypeFieldsDesc rename, - @ToolArg(description = "Operation to add fields", required = false) TypeDefinitionDesc add) { + @ToolArg(description = "Fields to rename", required = false) RenameTypeFieldsDesc rename, + @ToolArg(description = "Fields to add to the type", required = false) + TypeDefinitionDesc add) { var command = new AlterTypeCommand(name, rename, add); return mcpResource.processCommand(mcpResource.buildKeyspaceContext(keyspace, command), command); @@ -69,10 +69,10 @@ public Uni alterType( @Tool(description = "Command that creates an API Table.") public Uni createTable( - @ToolArg(description = "Name of the existing keyspace") String keyspace, - @ToolArg(description = "Name of the new Table") String table, - @ToolArg(description = "Table definition") TableDefinitionDesc definition, - @ToolArg(description = "Configuration options for the table", required = false) + @ToolArg(description = "Name of the keyspace") String keyspace, + @ToolArg(description = "Name of the new table") String table, + @ToolArg(description = "Definition of the new table") TableDefinitionDesc definition, + @ToolArg(description = "Options for the command.", required = false) CreateTableCommand.Options options) { var command = new CreateTableCommand(table, definition, options); @@ -81,10 +81,10 @@ public Uni createTable( @Tool(description = "Command that creates a user defined type.") public Uni createType( - @ToolArg(description = "Name of the existing keyspace") String keyspace, - @ToolArg(description = "Name of the type to create") String name, - @ToolArg(description = "Type definition") TypeDefinitionDesc definition, - @ToolArg(description = "Configuration options for the command", required = false) + @ToolArg(description = "Name of the keyspace") String keyspace, + @ToolArg(description = "Name of the new type") String name, + @ToolArg(description = "Fields of the new type") TypeDefinitionDesc definition, + @ToolArg(description = "Options for the command.", required = false) CreateTypeCommand.Options options) { var command = new CreateTypeCommand(name, definition, options); @@ -93,9 +93,9 @@ public Uni createType( @Tool(description = "Command that drops an index for a column.") public Uni dropIndex( - @ToolArg(description = "Name of the existing keyspace") String keyspace, - @ToolArg(description = "Name of the Index to remove") String name, - @ToolArg(description = "Dropping index command option.", required = false) + @ToolArg(description = "Name of the keyspace") String keyspace, + @ToolArg(description = "Name of the index to drop") String name, + @ToolArg(description = "Options for the command.", required = false) DropIndexCommand.Options options) { var command = new DropIndexCommand(name, options); @@ -104,9 +104,9 @@ public Uni dropIndex( @Tool(description = "Command that drops a table if one exists.") public Uni dropTable( - @ToolArg(description = "Name of the existing keyspace") String keyspace, - @ToolArg(description = "Name of the Table to remove") String table, - @ToolArg(description = "Optional options for drop command", required = false) + @ToolArg(description = "Name of the keyspace") String keyspace, + @ToolArg(description = "Name of the table to drop") String table, + @ToolArg(description = "Options for the command.", required = false) DropTableCommand.Options options) { var command = new DropTableCommand(table, options); @@ -115,9 +115,9 @@ public Uni dropTable( @Tool(description = "Command that drops a user defined type if one exists.") public Uni dropType( - @ToolArg(description = "Name of the existing keyspace") String keyspace, - @ToolArg(description = "Name of the Type to remove") String name, - @ToolArg(description = "Options for drop command", required = false) + @ToolArg(description = "Name of the keyspace") String keyspace, + @ToolArg(description = "Name of the type to drop") String name, + @ToolArg(description = "Options for the command.", required = false) DropTypeCommand.Options options) { var command = new DropTypeCommand(name, options); @@ -126,8 +126,8 @@ public Uni dropType( @Tool(description = "Command that lists all available tables in a keyspace") public Uni listTables( - @ToolArg(description = "Name of the existing keyspace") String keyspace, - @ToolArg(description = "Options for the `listTables` command.", required = false) + @ToolArg(description = "Name of the keyspace") String keyspace, + @ToolArg(description = "Options for the command.", required = false) ListTablesCommand.Options options) { var command = new ListTablesCommand(options); @@ -136,8 +136,8 @@ public Uni listTables( @Tool(description = "Command that lists all available types in a keyspace") public Uni listTypes( - @ToolArg(description = "Name of the existing keyspace") String keyspace, - @ToolArg(description = "Options for the `listTypes` command.", required = false) + @ToolArg(description = "Name of the keyspace") String keyspace, + @ToolArg(description = "Options for the command.", required = false) ListTypesCommand.Options options) { var command = new ListTypesCommand(options); 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 d317e8f7d6..1c66a58440 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,6 +3,7 @@ import static io.restassured.RestAssured.given; import static org.junit.jupiter.api.Assertions.*; +import com.fasterxml.jackson.databind.DeserializationFeature; import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.node.MissingNode; @@ -278,6 +279,44 @@ void toolSchemasHideJavaFieldNames() throws Exception { } } + /** MCP clients choose argument values from these descriptions, so a bare name is not enough. */ + @Test + void everyToolDescribesEveryArgument() throws Exception { + for (var tool : toolManager) { + var document = inputSchema(tool.name()); + for (var argument : document.path("properties").properties()) { + var label = tool.name() + "." + argument.getKey(); + var description = schemaMetadata(document, argument.getValue(), "description").asText(); + assertFalse(description.isBlank(), label); + assertNotEquals(argument.getKey(), description.toLowerCase(), label); + } + } + } + + /** An example at the end of an argument description must parse as that argument. */ + @Test + void argumentDescriptionExamplesDeserialize() throws Exception { + var marker = "for example "; + // Trailing text after the example would mean the example is not the whole JSON value. + var reader = objectMapper.reader().with(DeserializationFeature.FAIL_ON_TRAILING_TOKENS); + var checked = 0; + for (var tool : toolManager) { + for (var argument : tool.arguments()) { + var start = argument.description().indexOf(marker); + if (start < 0) { + continue; + } + var label = tool.name() + "." + argument.name(); + var example = reader.readTree(argument.description().substring(start + marker.length())); + var type = objectMapper.constructType(argument.type()); + assertNotNull( + assertDoesNotThrow(() -> objectMapper.treeToValue(example, type), label), label); + checked++; + } + } + assertTrue(checked > 0, "No argument description has an example"); + } + /** * 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.