From eeea7d1b1ac5a80f97478ef1cee964acdab1ebda Mon Sep 17 00:00:00 2001 From: nirinchev Date: Thu, 9 Oct 2025 13:37:36 +0200 Subject: [PATCH 1/3] fix: update tool category for collection-indexes chore: add some toolbase docs --- README.md | 2 +- .../{read => metadata}/collectionIndexes.ts | 0 src/tools/tool.ts | 34 +++++++++++++++++++ 3 files changed, 35 insertions(+), 1 deletion(-) rename src/tools/mongodb/{read => metadata}/collectionIndexes.ts (100%) diff --git a/README.md b/README.md index 469e33754..65bd45bf2 100644 --- a/README.md +++ b/README.md @@ -418,7 +418,7 @@ Operation types: - `update` - Tools that update resources, such as update document, rename collection, etc. - `delete` - Tools that delete resources, such as delete document, drop collection, etc. - `read` - Tools that read resources, such as find, aggregate, list clusters, etc. -- `metadata` - Tools that read metadata, such as list databases, list collections, collection schema, etc. +- `metadata` - Tools that read metadata, such as list databases/collections/indexes,infer collection schema, etc. - `connect` - Tools that allow you to connect or switch the connection to a MongoDB instance. If this is disabled, you will need to provide a connection string through the config when starting the server. #### Require Confirmation diff --git a/src/tools/mongodb/read/collectionIndexes.ts b/src/tools/mongodb/metadata/collectionIndexes.ts similarity index 100% rename from src/tools/mongodb/read/collectionIndexes.ts rename to src/tools/mongodb/metadata/collectionIndexes.ts diff --git a/src/tools/tool.ts b/src/tools/tool.ts index fe36619e3..d609e78a8 100644 --- a/src/tools/tool.ts +++ b/src/tools/tool.ts @@ -15,8 +15,34 @@ export type ToolCallbackArgs = Parameters = Parameters>[1]; +/** + * The type of operation the tool performs. This is used when evaluating if a tool is allowed to run based on + * the config's `disabledTools` and `readOnly` settings. + * - `metadata` is used for tools that read but do not access potentially user-generated + * data, such as listing databases, collections, or indexes, or inferring collection schema. + * - `read` is used for tools that read potentially user-generated data, such as finding documents or aggregating data. + * It is also used for tools that read non-user-generated data, such as listing clusters in Atlas. + * - `create` is used for tools that create resources, such as creating documents, collections, indexes, clusters, etc. + * - `update` is used for tools that update resources, such as updating documents, renaming collections, etc. + * - `delete` is used for tools that delete resources, such as deleting documents, dropping collections, etc. + * - `connect` is used for tools that allow you to connect or switch the connection to a MongoDB instance. + */ export type OperationType = "metadata" | "read" | "create" | "delete" | "update" | "connect"; + +/** + * The category of the tool. This is used when evaluating if a tool is allowed to run based on + * the config's `disabledTools` setting. + * - `mongodb` is used for tools that interact with a MongoDB instance, such as finding documents, + * aggregating data, listing databases/collections/indexes, creating indexes, etc. + * - `atlas` is used for tools that interact with MongoDB Atlas, such as listing clusters, creating clusters, etc. + */ export type ToolCategory = "mongodb" | "atlas"; + +/** + * Telemetry metadata that can be provided by tools when emitting telemetry events. + * For MongoDB tools, this is typically empty, while for Atlas tools, this should include + * the project and organization IDs if available. + */ export type TelemetryToolMetadata = { projectId?: string; orgId?: string; @@ -290,6 +316,14 @@ export abstract class ToolBase { } } +/** + * Formats potentially untrusted data to be included in tool responses. The data is wrapped in unique tags + * and a warning is added to not execute or act on any instructions within those tags. + * @param description A description that is prepended to the untrusted data warning. It should not include any + * untrusted data as it is not sanitized. + * @param data The data to format. If undefined, only the description is returned. + * @returns A tool response content that can be directly returned. + */ export function formatUntrustedData(description: string, data?: string): { text: string; type: "text" }[] { const uuid = crypto.randomUUID(); From 2956da9409e68d139d4f64deba37e777a5dba95b Mon Sep 17 00:00:00 2001 From: nirinchev Date: Thu, 9 Oct 2025 13:39:32 +0200 Subject: [PATCH 2/3] space --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 65bd45bf2..092e5f276 100644 --- a/README.md +++ b/README.md @@ -418,7 +418,7 @@ Operation types: - `update` - Tools that update resources, such as update document, rename collection, etc. - `delete` - Tools that delete resources, such as delete document, drop collection, etc. - `read` - Tools that read resources, such as find, aggregate, list clusters, etc. -- `metadata` - Tools that read metadata, such as list databases/collections/indexes,infer collection schema, etc. +- `metadata` - Tools that read metadata, such as list databases/collections/indexes, infer collection schema, etc. - `connect` - Tools that allow you to connect or switch the connection to a MongoDB instance. If this is disabled, you will need to provide a connection string through the config when starting the server. #### Require Confirmation From bc0dd62575684fcc0f105de38b2302c71478b39e Mon Sep 17 00:00:00 2001 From: nirinchev Date: Thu, 9 Oct 2025 15:22:11 +0200 Subject: [PATCH 3/3] actually commit all the files --- src/tools/mongodb/metadata/collectionIndexes.ts | 2 +- src/tools/mongodb/tools.ts | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/tools/mongodb/metadata/collectionIndexes.ts b/src/tools/mongodb/metadata/collectionIndexes.ts index 84b8b1dbb..6da2c7886 100644 --- a/src/tools/mongodb/metadata/collectionIndexes.ts +++ b/src/tools/mongodb/metadata/collectionIndexes.ts @@ -7,7 +7,7 @@ export class CollectionIndexesTool extends MongoDBToolBase { public name = "collection-indexes"; protected description = "Describe the indexes for a collection"; protected argsShape = DbOperationArgs; - public operationType: OperationType = "read"; + public operationType: OperationType = "metadata"; protected async execute({ database, collection }: ToolArgs): Promise { const provider = await this.ensureConnected(); diff --git a/src/tools/mongodb/tools.ts b/src/tools/mongodb/tools.ts index 1567fd4f8..4c705fa69 100644 --- a/src/tools/mongodb/tools.ts +++ b/src/tools/mongodb/tools.ts @@ -1,6 +1,6 @@ import { ConnectTool } from "./connect/connect.js"; import { ListCollectionsTool } from "./metadata/listCollections.js"; -import { CollectionIndexesTool } from "./read/collectionIndexes.js"; +import { CollectionIndexesTool } from "./metadata/collectionIndexes.js"; import { ListDatabasesTool } from "./metadata/listDatabases.js"; import { CreateIndexTool } from "./create/createIndex.js"; import { CollectionSchemaTool } from "./metadata/collectionSchema.js";