Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -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)?$")
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -14,13 +14,17 @@
* <p>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)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1 for explaining comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks.

* <p>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 {

Expand All @@ -31,7 +34,10 @@ public class CollectionCommandTools {
public Uni<ToolResponse> 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);
Expand All @@ -41,7 +47,7 @@ public Uni<ToolResponse> alterTable(
public Uni<ToolResponse> 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);
Expand All @@ -51,7 +57,7 @@ public Uni<ToolResponse> countDocuments(
public Uni<ToolResponse> 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(
Expand All @@ -74,7 +80,7 @@ public Uni<ToolResponse> createIndex(
public Uni<ToolResponse> 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(
Expand All @@ -95,7 +101,7 @@ public Uni<ToolResponse> createTextIndex(
public Uni<ToolResponse> 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(
Expand All @@ -117,11 +123,8 @@ public Uni<ToolResponse> createVectorIndex(
"Command that finds documents based on the filter and deletes them from a collection")
public Uni<ToolResponse> 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);
Expand All @@ -130,10 +133,9 @@ public Uni<ToolResponse> deleteMany(
@Tool(description = "Command that finds a single document and deletes it from a collection")
public Uni<ToolResponse> 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);
Expand All @@ -152,18 +154,14 @@ public Uni<ToolResponse> estimatedDocumentCount(
public Uni<ToolResponse> findAndRerank(
@ToolArg(description = "Name of the keyspace") String keyspace,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thinking out loud - something for next time we are working in this file.

IF we can rely on the description on the class for things like FilterDefinition SortDefinition. Perhaps we should create a class for the Keyspace, Collection, Table etc parameters that are just strings so we can put the description in one place.

Of we should update them to use a string constant.

e.g. "Name of the keyspace" is used in abut 30 places for tool defs .

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, let's do that next time we're in this file.

@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 =
"Fields to include or exclude in the returned documents, for example {\"title\": 1}",
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);
Expand All @@ -173,11 +171,16 @@ public Uni<ToolResponse> findAndRerank(
@Tool(description = "Command that finds JSON documents from a collection.")
public Uni<ToolResponse> 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);
Expand All @@ -188,10 +191,14 @@ public Uni<ToolResponse> find(
"Command that finds a single JSON document from a collection and deletes it. The deleted document is returned")
public Uni<ToolResponse> 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);
Expand All @@ -202,12 +209,16 @@ public Uni<ToolResponse> findOneAndDelete(
"Command that finds a single JSON document from a collection and replaces it with the replacement document.")
public Uni<ToolResponse> 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);
Expand All @@ -219,12 +230,17 @@ public Uni<ToolResponse> findOneAndReplace(
"Command that finds a single JSON document from a collection and updates the values provided in the update clause.")
public Uni<ToolResponse> 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);
Expand All @@ -233,11 +249,16 @@ public Uni<ToolResponse> findOneAndUpdate(
@Tool(description = "Command that finds a single JSON document from a collection.")
public Uni<ToolResponse> 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);
Expand All @@ -247,7 +268,7 @@ public Uni<ToolResponse> findOne(
public Uni<ToolResponse> 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);
Expand All @@ -257,9 +278,9 @@ public Uni<ToolResponse> listIndexes(
@Tool(description = "Command that inserts multiple JSON documents to a collection.")
public Uni<ToolResponse> 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<JsonNode> 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<JsonNode> documents,
@ToolArg(description = "Options for the command.", required = false)
InsertManyCommand.Options options) {

var command = new InsertManyCommand(documents, options);
Expand All @@ -269,8 +290,8 @@ public Uni<ToolResponse> insertMany(
@Tool(description = "Command that inserts a single JSON document to a collection.")
public Uni<ToolResponse> 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);
Expand All @@ -281,10 +302,11 @@ public Uni<ToolResponse> insertOne(
"Command that finds documents from a collection and updates it with the values provided in the update clause.")
public Uni<ToolResponse> 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);
Expand All @@ -295,11 +317,12 @@ public Uni<ToolResponse> updateMany(
"Command that finds a single JSON document from a table or collection and updates the values provided in the update clause.")
public Uni<ToolResponse> 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);
Expand Down
Loading