MongoDB MCP Server

Instructions

Implementation Reference

• src/index.ts:1306-1357 (handler)

  The main handler for the 'sample_data' tool. It performs a random sampling of documents from the specified collection using MongoDB's $sample aggregation stage, caps the sample size at 1000 for safety, supports both JSON and CSV output formats, and appends visualization hints for the sampled data.

  case 'sample_data': {
    const { 
      database, 
      collection, 
      size = 10,
      outputFormat = 'json',
      formatOptions = {}
    } = request.params.arguments as {
      database?: string;
      collection: string;
      size?: number;
      outputFormat?: 'json' | 'csv';
      formatOptions?: any;
    };
    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);
    const sampleSize = Math.min(size, 1000); // Cap sample size for safety
    
    const results = await db.collection(collection).aggregate([
      { $sample: { size: sampleSize } }
    ]).toArray();
    
    // Handle different output formats
    if (outputFormat.toLowerCase() === 'csv') {
      return {
        content: [
          {
            type: 'text',
            text: this.documentsToCsv(results, formatOptions),
          },
        ],
      };
    } else {
      // Default JSON format
      const vizHint = this.generateVisualizationHint(results);
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(results, null, 2) + (vizHint ? `\n\nVisualization Hint:\n${vizHint}` : ''),
          },
        ],
      };
    }
  }

• src/index.ts:681-755 (registration)

  Registration of the 'sample_data' tool in the list_tools response, including detailed description and complete input schema definition with parameters for database, collection, sample size, output format, and CSV options.

            name: 'sample_data',
            description: `Get a random sample of documents from a collection.
    
  Supports both JSON and CSV output formats:
  - Use outputFormat="json" for standard JSON (default)
  - Use outputFormat="csv" for comma-separated values export
  
  Useful for:
  - Exploratory data analysis
  - Testing with representative data
  - Understanding data distribution
  - Performance testing with realistic data subsets
  
  Example - JSON Sample:
  use_mcp_tool with
    server_name: "mongodb",
    tool_name: "sample_data",
    arguments: {
      "collection": "users",
      "size": 50
    }
  
  Example - CSV Export:
  use_mcp_tool with
    server_name: "mongodb",
    tool_name: "sample_data",
    arguments: {
      "collection": "users",
      "size": 100,
      "outputFormat": "csv",
      "formatOptions": {
        "includeHeaders": true,
        "delimiter": ","
      }
    }`,
            inputSchema: {
              type: 'object',
              properties: {
                database: {
                  type: 'string',
                  description: 'Database name (optional if default database is configured)',
                },
                collection: {
                  type: 'string',
                  description: 'Collection name',
                },
                size: {
                  type: 'number',
                  description: 'Number of random documents to sample (default: 10)',
                  minimum: 1,
                  maximum: 1000,
                },
                outputFormat: {
                  type: 'string',
                  description: 'Output format for results (json or csv)',
                  enum: ['json', 'csv'],
                },
                formatOptions: {
                  type: 'object',
                  description: 'Format-specific options',
                  properties: {
                    delimiter: {
                      type: 'string',
                      description: 'CSV delimiter character (default: comma)',
                    },
                    includeHeaders: {
                      type: 'boolean',
                      description: 'Whether to include header row in CSV (default: true)',
                    },
                  },
                },
              },
              required: ['collection'],
            },
          },

• src/index.ts:716-754 (schema)

  Input schema definition for the 'sample_data' tool, specifying parameters, types, descriptions, constraints, and required fields.

  inputSchema: {
    type: 'object',
    properties: {
      database: {
        type: 'string',
        description: 'Database name (optional if default database is configured)',
      },
      collection: {
        type: 'string',
        description: 'Collection name',
      },
      size: {
        type: 'number',
        description: 'Number of random documents to sample (default: 10)',
        minimum: 1,
        maximum: 1000,
      },
      outputFormat: {
        type: 'string',
        description: 'Output format for results (json or csv)',
        enum: ['json', 'csv'],
      },
      formatOptions: {
        type: 'object',
        description: 'Format-specific options',
        properties: {
          delimiter: {
            type: 'string',
            description: 'CSV delimiter character (default: comma)',
          },
          includeHeaders: {
            type: 'boolean',
            description: 'Whether to include header row in CSV (default: true)',
          },
        },
      },
    },
    required: ['collection'],
  },

• src/index.ts:254-289 (helper)

  Helper function to convert MongoDB documents to CSV format, handling varying schemas, proper escaping, and configurable options. Used by sample_data for CSV output.

  private documentsToCsv(docs: any[], options: {
    includeHeaders?: boolean;
    delimiter?: string;
  } = {}): string {
    if (!Array.isArray(docs) || docs.length === 0) return '';
    
    const delimiter = options.delimiter || ',';
    const includeHeaders = options.includeHeaders !== false;
    
    // Extract all possible field names from all documents (handles varying schemas)
    const fieldsSet = new Set<string>();
    docs.forEach(doc => {
      Object.keys(doc).forEach(key => fieldsSet.add(key));
    });
    
    const fields = Array.from(fieldsSet);
    let result = '';
    
    // Add headers
    if (includeHeaders) {
      result += fields.map(field => this.escapeCsvField(field, delimiter)).join(delimiter) + '\n';
    }
    
    // Add data rows
    docs.forEach(doc => {
      const row = fields.map(field => {
        const value = doc[field];
        if (value === undefined || value === null) return '';
        if (typeof value === 'object') return this.escapeCsvField(JSON.stringify(value), delimiter);
        return this.escapeCsvField(String(value), delimiter);
      });
      result += row.join(delimiter) + '\n';
    });
    
    return result;
  }

• src/index.ts:194-246 (helper)

  Helper function that analyzes sampled data and generates visualization recommendations based on data types (time series, numeric, categorical, geospatial), used by sample_data to append hints to JSON output.

  private generateVisualizationHint(data: any[]): string {
    if (!Array.isArray(data) || data.length === 0) return '';
  
    // Check if the data looks like time series
    const hasDateFields = Object.keys(data[0]).some(key => 
      data[0][key] instanceof Date || 
      (typeof data[0][key] === 'string' && !isNaN(Date.parse(data[0][key])))
    );
  
    // Check if the data has numeric fields
    const numericFields = Object.keys(data[0]).filter(key => 
      typeof data[0][key] === 'number'
    );
  
    // Check if the data has categorical fields
    const categoricalFields = Object.keys(data[0]).filter(key => 
      typeof data[0][key] === 'string' && 
      data.every(item => typeof item[key] === 'string')
    );
  
    // Check if the data has geospatial fields
    const hasGeoData = Object.keys(data[0]).some(key => {
      const value = data[0][key];
      return value && typeof value === 'object' && 
        (('type' in value && value.type === 'Point' && 'coordinates' in value) ||
         (Array.isArray(value) && value.length === 2 && 
          typeof value[0] === 'number' && typeof value[1] === 'number'));
    });
  
    let hints = [];
  
    if (hasDateFields && numericFields.length > 0) {
      hints.push('Time Series Visualization:\n- Consider line charts for temporal trends\n- Time-based heat maps for density patterns\n- Area charts for cumulative values over time');
    }
  
    if (categoricalFields.length > 0 && numericFields.length > 0) {
      hints.push('Categorical Analysis:\n- Bar charts for comparing categories\n- Box plots for distribution analysis\n- Heat maps for category correlations\n- Treemaps for hierarchical data');
    }
  
    if (numericFields.length >= 2) {
      hints.push('Numerical Analysis:\n- Scatter plots for correlation analysis\n- Bubble charts if three numeric dimensions\n- Correlation matrices for multiple variables\n- Histograms for distribution analysis');
    }
  
    if (hasGeoData) {
      hints.push('Geospatial Visualization:\n- Map overlays for location data\n- Choropleth maps for regional analysis\n- Heat maps for density visualization\n- Cluster maps for point concentration');
    }
  
    if (data.length > 1000) {
      hints.push('Large Dataset Considerations:\n- Consider sampling for initial visualization\n- Use aggregation for summary views\n- Implement pagination or infinite scroll\n- Consider server-side rendering');
    }
  
    return hints.join('\n\n');
  }