mcp_get_document_by_id

Instructions

Implementation Reference

• src/tools/dataOperations.ts:159-181 (handler)

  The main handler function that executes the mcp_get_document_by_id tool. It accepts container_id, document_id, partition_key, and optional connection_id. Uses CosmosDB's point read via container.item(id, partitionKey).read() to retrieve a single document by its ID and partition key.

  export const mcp_get_document_by_id = async (args: { 
    container_id: string; 
    document_id: string; 
    partition_key: PartitionKeyValue;
    connection_id?: string;
  }): Promise<ToolResult<DocumentInfo>> => {
    const { container_id, document_id, partition_key, connection_id } = args;
    log(`Executing mcp_get_document_by_id with: ${JSON.stringify(args)}`);
  
    try {
      const container = getContainer(container_id, connection_id);
      const { resource: document, statusCode } = await container.item(document_id, partition_key).read();
  
      if (!document) {
        return { success: false, error: `Document with id '${document_id}' not found` };
      }
  
      return { success: true, data: document };
    } catch (error: any) {
      log(`Error in mcp_get_document_by_id for document ${document_id}: ${error.message}`);
      return { success: false, error: error.message };
    }
  };

• src/tools.ts:187-214 (schema)

  The input schema and tool registration definition for mcp_get_document_by_id. Defines the tool name, description, and inputSchema with required parameters: container_id (string), document_id (string), and partition_key (string|number|boolean).

    // 7. Get Document by ID
    {
      name: "mcp_get_document_by_id",
      description: `Get a single document by its ID and partition key. This is the most efficient way to retrieve a specific document.
  
  IMPORTANT: Both document_id and partition_key are required for a point read in CosmosDB.
  The partition_key type must match your container's partition key type.
  
  Example: mcp_get_document_by_id({container_id: 'users', document_id: 'user-123', partition_key: 'user-123', connection_id: 'athlete'})`,
      inputSchema: {
        type: "object",
        properties: {
          container_id: {
            type: "string",
            description: "The ID/name of the container"
          },
          document_id: {
            type: "string",
            description: "The unique ID of the document (the 'id' field value)"
          },
          partition_key: {
            type: ["string", "number", "boolean"],
            description: "The partition key value for the document. Must match the container's partition key path value."
          },
          ...connectionIdProperty
        },
        required: ["container_id", "document_id", "partition_key"]
      }

• src/server.ts:141-142 (registration)

  The server-side dispatch that routes the 'mcp_get_document_by_id' tool call to the handler function via toolHandlers.mcp_get_document_by_id(input as any).

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

• src/tools/index.ts:12-22 (helper)

  The barrel export that re-exports mcp_get_document_by_id from dataOperations.ts so it's accessible via the tools module.

  export {
    mcp_list_connections,
    mcp_execute_query,
    mcp_get_documents,
    mcp_get_document_by_id,
    mcp_analyze_schema,
    mcp_create_document,
    mcp_update_document,
    mcp_delete_document,
    mcp_upsert_document
  } from './dataOperations.js';

• src/mcp-server.ts:1-3 (registration)

  The mcp-server.ts barrel file that re-exports all tools from ./tools/index.js, making them accessible to server.ts via import * as toolHandlers.

  // Import all tools from the modular structure
  export * from './tools/index.js';