Repository navigation
fix: describe every MCP tool argument and the JSON it takes #2658
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
e1c9f67
0cc5d9c
03bf04d
d63d03a
94f0951
e4e193a
b3f049f
bf25f5a
9485dc0
9735669
2a1d843
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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. | ||
| * | ||
| * <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 { | ||
|
|
||
|
|
@@ -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); | ||
|
|
@@ -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); | ||
|
|
@@ -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( | ||
|
|
@@ -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( | ||
|
|
@@ -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( | ||
|
|
@@ -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); | ||
|
|
@@ -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); | ||
|
|
@@ -152,18 +154,14 @@ public Uni<ToolResponse> estimatedDocumentCount( | |
| public Uni<ToolResponse> findAndRerank( | ||
| @ToolArg(description = "Name of the keyspace") String keyspace, | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 .
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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); | ||
|
|
@@ -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); | ||
|
|
@@ -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); | ||
|
|
@@ -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); | ||
|
|
@@ -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); | ||
|
|
@@ -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); | ||
|
|
@@ -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); | ||
|
|
@@ -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); | ||
|
|
@@ -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); | ||
|
|
@@ -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); | ||
|
|
@@ -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); | ||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
+1 for explaining comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks.