text_search

Instructions

Implementation Reference

• src/index.ts:1591-1649 (handler)

  Handler function for executing the text_search tool. Performs full-text search using MongoDB's $text operator, supports additional filters, scoring, sorting by score, and limits. Includes error handling for missing text indexes.

  case 'text_search': {
    const { database, collection, searchText, filter, limit, includeScore } = request.params
      .arguments as {
      database?: string;
      collection: string;
      searchText: string;
      filter?: object;
      limit?: number;
      includeScore?: boolean;
    };
    const dbName = database || this.defaultDatabase;
    if (!dbName) {
      throw new McpError(
        ErrorCode.InvalidRequest,
        'Database name is required when no default database is configured'
      );
    }
  
    const db = client.db(dbName);
    
    try {
      const searchQuery = {
        $text: { $search: searchText },
        ...(filter || {}),
      };
  
      const projection = includeScore ? { score: { $meta: 'textScore' } } : undefined;
      let query = db.collection(collection).find(searchQuery);
  
      if (projection) {
        query = query.project(projection);
      }
      if (includeScore) {
        query = query.sort({ score: { $meta: 'textScore' } });
      }
      if (limit) {
        query = query.limit(limit);
      }
  
      const results = await query.toArray();
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(results, null, 2),
          },
        ],
      };
    } catch (error) {
      // Check if error is due to missing text index
      if (error instanceof Error && error.message.includes('text index')) {
        throw new McpError(
          ErrorCode.InvalidRequest,
          'No text index found on this collection. Create a text index first using db.collection.createIndex({ "field": "text" })'
        );
      }
      throw error;
    }
  }

• src/index.ts:970-1001 (schema)

  Input schema definition for the text_search tool, specifying parameters like searchText, collection, optional filter, limit, and includeScore.

  inputSchema: {
    type: 'object',
    properties: {
      database: {
        type: 'string',
        description: 'Database name (optional if default database is configured)',
      },
      collection: {
        type: 'string',
        description: 'Collection name',
      },
      searchText: {
        type: 'string',
        description: 'Text to search for',
      },
      filter: {
        type: 'object',
        description: 'Additional MongoDB query filter (optional)',
      },
      limit: {
        type: 'number',
        description: 'Maximum number of results to return (optional)',
        minimum: 1,
        maximum: 1000,
      },
      includeScore: {
        type: 'boolean',
        description: 'Include text search score in results (optional)',
      },
    },
    required: ['collection', 'searchText'],
  },

• src/index.ts:946-1002 (registration)

  Registration of the text_search tool in the ListTools response, including name, description, and input schema.

            name: 'text_search',
            description: `Perform a full-text search on a collection.
  
  Requirements:
  - Collection must have a text index
  - Only one text index per collection is allowed
  
  Features:
  - Supports phrases and keywords
  - Word stemming
  - Stop words removal
  - Text score ranking
  
  Example:
  use_mcp_tool with
    server_name: "mongodb",
    tool_name: "text_search",
    arguments: {
      "collection": "articles",
      "searchText": "mongodb database",
      "filter": { "published": true },
      "limit": 10,
      "includeScore": true
    }`,
            inputSchema: {
              type: 'object',
              properties: {
                database: {
                  type: 'string',
                  description: 'Database name (optional if default database is configured)',
                },
                collection: {
                  type: 'string',
                  description: 'Collection name',
                },
                searchText: {
                  type: 'string',
                  description: 'Text to search for',
                },
                filter: {
                  type: 'object',
                  description: 'Additional MongoDB query filter (optional)',
                },
                limit: {
                  type: 'number',
                  description: 'Maximum number of results to return (optional)',
                  minimum: 1,
                  maximum: 1000,
                },
                includeScore: {
                  type: 'boolean',
                  description: 'Include text search score in results (optional)',
                },
              },
              required: ['collection', 'searchText'],
            },
          },