mcp_update_document

Instructions

Implementation Reference

• src/tools/dataOperations.ts:233-278 (handler)

  The main handler function for mcp_update_document. Updates (replaces) an existing document in a CosmosDB container. Takes UpdateDocumentArgs plus optional connection_id, validates modifications are allowed, ensures document ID consistency, performs the replace operation via CosmosDB SDK, and returns DocumentOperationResult with id, _etag, _ts, and requestCharge.

  export const mcp_update_document = async (args: UpdateDocumentArgs & { connection_id?: string }): Promise<ToolResult<DocumentOperationResult>> => {
    const { container_id, document_id, document, partition_key, connection_id } = args;
    log(`Executing mcp_update_document with: ${JSON.stringify({ container_id, document_id, partition_key, connection_id })}`);
  
    try {
      // Validate modifications are allowed
      validateModificationAllowed('update_document', connection_id);
      
      // Ensure document has the correct id
      if (document.id && document.id !== document_id) {
        return { success: false, error: "Document 'id' field must match 'document_id' parameter" };
      }
      
      // Ensure id is set
      const documentToUpdate = { ...document, id: document_id };
  
      const container = getContainer(container_id, connection_id);
      
      const { resource: updatedDocument, requestCharge } = await container
        .item(document_id, partition_key)
        .replace(documentToUpdate);
  
      if (!updatedDocument) {
        return { success: false, error: "Failed to update document - no response from CosmosDB" };
      }
  
      return { 
        success: true, 
        data: {
          id: updatedDocument.id,
          _etag: updatedDocument._etag,
          _ts: updatedDocument._ts,
          requestCharge: requestCharge || 0
        }
      };
    } catch (error: any) {
      log(`Error in mcp_update_document for document ${document_id}: ${error.message}`);
      
      // Provide more helpful error messages
      if (error.code === 404) {
        return { success: false, error: `Document with id '${document_id}' not found` };
      }
      
      return { success: false, error: error.message };
    }
  };

• src/tools/types.ts:82-87 (schema)

  The UpdateDocumentArgs interface defining the input schema for mcp_update_document: container_id, document_id, document (Record<string, any>), and partition_key (string | number | boolean).

  export interface UpdateDocumentArgs {
    container_id: string;
    document_id: string;
    document: Record<string, any>;
    partition_key: PartitionKeyValue;
  }

• src/tools.ts:276-314 (registration)

  Tool registration/definition for mcp_update_document in the MCP_COSMOSDB_TOOLS array. Defines the tool name, description (with full replacement note and example), and inputSchema with required fields: container_id, document_id, document, partition_key, and optional connection_id.

    // 10. Update/Replace Document
    {
      name: "mcp_update_document",
      description: `Update (replace) an existing document in a CosmosDB container.
  
  NOTE: This performs a full document replacement. Include ALL fields you want to keep.
  For partial updates, first get the document with mcp_get_document_by_id, modify it, then update.
  
  Example: mcp_update_document({
    container_id: 'users',
    document_id: 'user-456',
    document: {id: 'user-456', email: 'new@example.com', status: 'inactive'},
    partition_key: 'user-456',
    connection_id: 'athlete'
  })`,
      inputSchema: {
        type: "object",
        properties: {
          container_id: {
            type: "string",
            description: "The ID/name of the container"
          },
          document_id: {
            type: "string",
            description: "The ID of the document to update"
          },
          document: {
            type: "object",
            description: "The complete document with updated values. Must include 'id' field."
          },
          partition_key: {
            type: ["string", "number", "boolean"],
            description: "The partition key value for the document"
          },
          ...connectionIdProperty
        },
        required: ["container_id", "document_id", "document", "partition_key"]
      }
    },

• src/server.ts:148-154 (registration)

  Server-side routing: the CallTool handler switch case for 'mcp_update_document' that dispatches to toolHandlers.mcp_update_document (imported from './mcp-server.js' which re-exports from './tools/index.js').

  // CRUD operations
  case 'mcp_create_document':
      result = await toolHandlers.mcp_create_document(input as any);
      break;
  case 'mcp_update_document':
      result = await toolHandlers.mcp_update_document(input as any);
      break;

• src/db.ts:366-379 (helper)

  The validateModificationAllowed helper function called by mcp_update_document. Checks if modifications are allowed for the given connection and throws an error if not, preventing unauthorized writes.

  /**
   * Validate that modifications are allowed before performing write operations
   */
  export const validateModificationAllowed = (operation: string, connectionId?: string): void => {
    const id = resolveConnectionId(connectionId);
    
    if (!isModificationAllowed(connectionId)) {
      throw new Error(
        `Database modifications are disabled for connection '${id}'. ` +
        `Operation '${operation}' was blocked. ` +
        `Set allowModifications=true in the connection config to enable write operations.`
      );
    }
  };