mcp_get_documents

Instructions

Implementation Reference

• src/tools/dataOperations.ts:96-154 (handler)

  The actual handler function for mcp_get_documents. It queries a CosmosDB container with optional filters (equality), ordering, partition key, and limit. Builds a SQL query dynamically, executes it via the container's items.query, and returns the documents.

  export const mcp_get_documents = async (args: { 
    container_id: string; 
    limit?: number;
    partition_key?: PartitionKeyValue;
    filter_conditions?: Record<string, any>;
    order_by?: string;
    order_direction?: 'ASC' | 'DESC';
    connection_id?: string;
  }): Promise<ToolResult<DocumentInfo[]>> => {
    const { container_id, limit = 100, partition_key, filter_conditions, order_by, order_direction = 'ASC', connection_id } = args;
    log(`Executing mcp_get_documents with: ${JSON.stringify(args)}`);
  
    try {
      const container = getContainer(container_id, connection_id);
  
      // Build query with proper TOP clause (not subquery)
      const whereClauses: string[] = [];
      const parameters: Array<{ name: string; value: any }> = [];
  
      // Add filter conditions
      if (filter_conditions && Object.keys(filter_conditions).length > 0) {
        Object.entries(filter_conditions).forEach(([key, value], index) => {
          const paramName = `@param${index}`;
          parameters.push({ name: paramName, value });
          whereClauses.push(`c.${key} = ${paramName}`);
        });
      }
  
      // Build final query
      let query = `SELECT * FROM c`;
      if (whereClauses.length > 0) {
        query += ` WHERE ${whereClauses.join(' AND ')}`;
      }
      
      // Add ORDER BY clause if specified
      if (order_by) {
        const direction = order_direction === 'DESC' ? 'DESC' : 'ASC';
        query += ` ORDER BY c.${order_by} ${direction}`;
      }
  
      const querySpec = { query, parameters };
  
      // Query options
      const options: any = { maxItemCount: limit };
      if (partition_key !== undefined) {
        options.partitionKey = partition_key;
      }
  
      const { resources: documents } = await container.items.query(querySpec, options).fetchAll();
      
      // Apply limit after query (since ORDER BY with TOP can be problematic in CosmosDB)
      const limitedDocuments = documents.slice(0, limit);
  
      return { success: true, data: limitedDocuments };
    } catch (error: any) {
      log(`Error in mcp_get_documents for container ${container_id}: ${error.message}`);
      return { success: false, error: error.message };
    }
  };

• src/tools/dataOperations.ts:96-104 (schema)

  The input parameter schema for the handler function - accepts container_id (required), limit, partition_key, filter_conditions, order_by, order_direction, and connection_id.

  export const mcp_get_documents = async (args: { 
    container_id: string; 
    limit?: number;
    partition_key?: PartitionKeyValue;
    filter_conditions?: Record<string, any>;
    order_by?: string;
    order_direction?: 'ASC' | 'DESC';
    connection_id?: string;
  }): Promise<ToolResult<DocumentInfo[]>> => {

• src/tools.ts:137-185 (schema)

  The MCP tool registration schema for mcp_get_documents, defining the inputSchema with container_id, limit, partition_key, filter_conditions, order_by, order_direction, and connection_id properties.

    // 6. Get Documents - Simple filtering without SQL
    {
      name: "mcp_get_documents",
      description: `Get documents from a container with simple filters and ordering. Use this for basic queries without complex SQL syntax.
  
  FOR COMPLEX QUERIES: Use mcp_cosmos_query instead.
  THIS TOOL IS BEST FOR:
  - Getting all documents (with limit)
  - Simple equality filters on fields
  - Filtering by partition key for performance
  - Getting the most recent or oldest documents using order_by
  
  Example: mcp_get_documents({container_id: 'users', limit: 10, order_by: '_ts', order_direction: 'DESC', connection_id: 'athlete'})
  Example: mcp_get_documents({container_id: 'users', limit: 50, filter_conditions: {status: 'active'}})`,
      inputSchema: {
        type: "object",
        properties: {
          container_id: {
            type: "string",
            description: "The ID/name of the container to query"
          },
          limit: {
            type: "number",
            description: "Maximum number of documents to return (default: 100)",
            default: 100
          },
          partition_key: {
            type: ["string", "number", "boolean"],
            description: "Optional partition key value to filter by. Improves performance significantly."
          },
          filter_conditions: {
            type: "object",
            description: "Simple equality filters as key-value pairs. Example: {status: 'active', type: 'premium'}"
          },
          order_by: {
            type: "string",
            description: "Field name to order results by. Use '_ts' for timestamp ordering (most recent/oldest). Example: '_ts', 'creationDate', 'name'"
          },
          order_direction: {
            type: "string",
            enum: ["ASC", "DESC"],
            description: "Sort direction: 'ASC' for ascending (oldest first), 'DESC' for descending (newest first). Default: 'ASC'",
            default: "ASC"
          },
          ...connectionIdProperty
        },
        required: ["container_id"]
      }
    },

• src/tools.ts:139-185 (registration)

  The tool is registered in the MCP_COSMOSDB_TOOLS array with name 'mcp_get_documents' and its description/input schema.

      name: "mcp_get_documents",
      description: `Get documents from a container with simple filters and ordering. Use this for basic queries without complex SQL syntax.
  
  FOR COMPLEX QUERIES: Use mcp_cosmos_query instead.
  THIS TOOL IS BEST FOR:
  - Getting all documents (with limit)
  - Simple equality filters on fields
  - Filtering by partition key for performance
  - Getting the most recent or oldest documents using order_by
  
  Example: mcp_get_documents({container_id: 'users', limit: 10, order_by: '_ts', order_direction: 'DESC', connection_id: 'athlete'})
  Example: mcp_get_documents({container_id: 'users', limit: 50, filter_conditions: {status: 'active'}})`,
      inputSchema: {
        type: "object",
        properties: {
          container_id: {
            type: "string",
            description: "The ID/name of the container to query"
          },
          limit: {
            type: "number",
            description: "Maximum number of documents to return (default: 100)",
            default: 100
          },
          partition_key: {
            type: ["string", "number", "boolean"],
            description: "Optional partition key value to filter by. Improves performance significantly."
          },
          filter_conditions: {
            type: "object",
            description: "Simple equality filters as key-value pairs. Example: {status: 'active', type: 'premium'}"
          },
          order_by: {
            type: "string",
            description: "Field name to order results by. Use '_ts' for timestamp ordering (most recent/oldest). Example: '_ts', 'creationDate', 'name'"
          },
          order_direction: {
            type: "string",
            enum: ["ASC", "DESC"],
            description: "Sort direction: 'ASC' for ascending (oldest first), 'DESC' for descending (newest first). Default: 'ASC'",
            default: "ASC"
          },
          ...connectionIdProperty
        },
        required: ["container_id"]
      }
    },

• src/server.ts:138-139 (registration)

  The CallTool handler routes the 'mcp_get_documents' case to toolHandlers.mcp_get_documents (imported from './mcp-server.js' which re-exports from tools/index.ts which re-exports from tools/dataOperations.ts).

  case 'mcp_get_documents':
      result = await toolHandlers.mcp_get_documents(input as any);