MongoDB MCP Server

Instructions

Implementation Reference

• src/index.ts:1045-1085 (handler)

  Main handler for the 'get_schema' tool. Samples up to 1000 documents from the specified collection, infers the schema using the inferSchema helper, and returns the schema as JSON.

  case 'get_schema': {
    const { database, collection, sampleSize = 100 } = request.params.arguments as {
      database?: string;
      collection: string;
      sampleSize?: number;
    };
    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 docs = await db
      .collection(collection)
      .find()
      .limit(sampleSize)
      .toArray();
    
    if (docs.length === 0) {
      return {
        content: [
          {
            type: 'text',
            text: 'No documents found in collection',
          },
        ],
      };
    }
  
    const schema = await this.inferSchema(docs);
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(schema, null, 2),
        },
      ],
    };
  }

• src/index.ts:336-369 (registration)

  Registration of the 'get_schema' tool in the ListTools response, including name, detailed description, and input schema definition.

            name: 'get_schema',
            description: `Infer schema from a collection by analyzing sample documents.
          
  Best Practice: Use this before querying to understand collection structure.
  
  Example:
  use_mcp_tool with
    server_name: "mongodb",
    tool_name: "get_schema",
    arguments: {
      "collection": "users",
      "sampleSize": 100
    }`,
            inputSchema: {
              type: 'object',
              properties: {
                database: {
                  type: 'string',
                  description: 'Database name (optional if default database is configured)',
                },
                collection: {
                  type: 'string',
                  description: 'Collection name',
                },
                sampleSize: {
                  type: 'number',
                  description: 'Number of documents to sample (default: 100)',
                  minimum: 1,
                  maximum: 1000,
                },
              },
              required: ['collection'],
            },
          },

• src/index.ts:349-368 (schema)

  Input schema definition for the 'get_schema' tool, specifying parameters: database (optional), collection (required), sampleSize (1-1000).

  inputSchema: {
    type: 'object',
    properties: {
      database: {
        type: 'string',
        description: 'Database name (optional if default database is configured)',
      },
      collection: {
        type: 'string',
        description: 'Collection name',
      },
      sampleSize: {
        type: 'number',
        description: 'Number of documents to sample (default: 100)',
        minimum: 1,
        maximum: 1000,
      },
    },
    required: ['collection'],
  },

• src/index.ts:113-153 (helper)

  Helper method inferSchema that recursively analyzes sample documents to infer the data schema, handling nested objects, arrays, primitives, and providing types, examples, and nullability.

  private async inferSchema(documents: any[], path = '', schema: any = {}) {
    for (const doc of documents) {
      Object.entries(doc).forEach(([key, value]) => {
        const fullPath = path ? `${path}.${key}` : key;
        
        if (Array.isArray(value)) {
          if (!schema[fullPath]) {
            schema[fullPath] = { type: 'array' };
          }
          
          // Handle empty arrays
          if (value.length === 0) {
            schema[fullPath].items = { type: 'unknown' };
          } 
          // Handle arrays of primitives
          else if (typeof value[0] !== 'object' || value[0] === null) {
            schema[fullPath].items = { type: typeof value[0] };
          }
          // Handle arrays of objects
          else {
            schema[fullPath].items = { type: 'object', properties: {} };
            this.inferSchema(value, `${fullPath}.items.properties`, schema);
          }
        } else if (value && typeof value === 'object') {
          if (!schema[fullPath]) {
            schema[fullPath] = { type: 'object', properties: {} };
          }
          this.inferSchema([value], `${fullPath}.properties`, schema);
        } else {
          if (!schema[fullPath]) {
            schema[fullPath] = { 
              type: typeof value,
              example: value, // Add example value for better understanding
              nullable: value === null
            };
          }
        }
      });
    }
    return schema;
  }