MCP CosmosDB

Instructions

Implementation Reference

• src/tools/dataOperations.ts:51-95 (handler)

  The handler function implementing mcp_get_documents tool logic. Retrieves documents from CosmosDB container using SQL query with optional filters, partition key, and limit.

  export const mcp_get_documents = async (args: { 
    container_id: string; 
    limit?: number;
    partition_key?: string;
    filter_conditions?: Record<string, any>;
  }): Promise<ToolResult<DocumentInfo[]>> => {
    const { container_id, limit = 100, partition_key, filter_conditions } = args;
    console.log('Executing mcp_get_documents with:', args);
  
    try {
      const container = getContainer(container_id);
  
      // Build query
      let query = `SELECT * FROM c`;
      const parameters: Array<{ name: string; value: any }> = [];
  
      // Add filter conditions
      if (filter_conditions && Object.keys(filter_conditions).length > 0) {
        const whereClauses = Object.entries(filter_conditions).map(([key, value], index) => {
          const paramName = `@param${index}`;
          parameters.push({ name: paramName, value });
          return `c.${key} = ${paramName}`;
        });
        query += ` WHERE ${whereClauses.join(' AND ')}`;
      }
  
      // Add limit
      query = `SELECT TOP ${limit} * FROM (${query})`;
  
      const querySpec = { query, parameters };
  
      // Query options
      const options: any = { maxItemCount: limit };
      if (partition_key) {
        options.partitionKey = partition_key;
      }
  
      const { resources: documents } = await container.items.query(querySpec, options).fetchAll();
  
      return { success: true, data: documents };
    } catch (error: any) {
      console.error(`Error in mcp_get_documents for container ${container_id}: ${error.message}`);
      return { success: false, error: error.message };
    }
  };

• src/tools.ts:106-132 (schema)

  Schema definition for mcp_get_documents tool, including input schema used in ListTools response.

  {
    name: "mcp_get_documents",
    description: "Get documents from a container with optional filters",
    inputSchema: {
      type: "object",
      properties: {
        container_id: {
          type: "string",
          description: "The ID of the container to query"
        },
        limit: {
          type: "number",
          description: "Maximum number of documents to return",
          default: 100
        },
        partition_key: {
          type: "string",
          description: "Optional partition key to filter by"
        },
        filter_conditions: {
          type: "object",
          description: "Optional filter conditions as key-value pairs"
        }
      },
      required: ["container_id"]
    }
  },

• src/tools/index.ts:12-17 (registration)

  Re-exports the mcp_get_documents handler from dataOperations.ts, enabling its import via tools/index.ts.

  export {
    mcp_execute_query,
    mcp_get_documents,
    mcp_get_document_by_id,
    mcp_analyze_schema
  } from './dataOperations.js';

• src/server.ts:106-108 (registration)

  Registers the handler dispatch for mcp_get_documents in the main server tool call switch statement.

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