mcp_create_document

Instructions

Implementation Reference

• src/tools/dataOperations.ts:186-228 (handler)

  The main handler function that creates a document in a CosmosDB container. Validates document has an 'id', creates the item via container.items.create(), and returns the created document's id, etag, timestamp, and request charge.

  export const mcp_create_document = async (args: CreateDocumentArgs & { connection_id?: string }): Promise<ToolResult<DocumentOperationResult>> => {
    const { container_id, document, partition_key, connection_id } = args;
    log(`Executing mcp_create_document with: ${JSON.stringify({ container_id, document_id: document.id, partition_key, connection_id })}`);
  
    try {
      // Validate modifications are allowed
      validateModificationAllowed('create_document', connection_id);
      
      // Validate document has an id
      if (!document.id) {
        return { success: false, error: "Document must have an 'id' field" };
      }
  
      const container = getContainer(container_id, connection_id);
      
      const { resource: createdDocument, requestCharge } = await container.items.create(
        document
      );
  
      if (!createdDocument) {
        return { success: false, error: "Failed to create document - no response from CosmosDB" };
      }
  
      return { 
        success: true, 
        data: {
          id: createdDocument.id,
          _etag: createdDocument._etag,
          _ts: createdDocument._ts,
          requestCharge: requestCharge || 0
        }
      };
    } catch (error: any) {
      log(`Error in mcp_create_document for container ${container_id}: ${error.message}`);
      
      // Provide more helpful error messages
      if (error.code === 409) {
        return { success: false, error: `Document with id '${document.id}' already exists in this partition` };
      }
      
      return { success: false, error: error.message };
    }
  };

• src/tools.ts:239-273 (schema)

  Tool registration and input schema definition for 'mcp_create_document'. Defines the name, description, inputSchema (container_id, document, partition_key, optional connection_id), and required fields.

    // 9. Create Document
    {
      name: "mcp_create_document",
      description: `Create a new document in a CosmosDB container.
  
  REQUIREMENTS:
  - The document MUST have an 'id' field (string)
  - The document MUST have the partition key field with a value
  - The 'id' must be unique within the partition
  
  Example: mcp_create_document({
    container_id: 'users',
    document: {id: 'user-456', email: 'test@example.com', status: 'active'},
    partition_key: 'user-456',
    connection_id: 'athlete'
  })`,
      inputSchema: {
        type: "object",
        properties: {
          container_id: {
            type: "string",
            description: "The ID/name of the container"
          },
          document: {
            type: "object",
            description: "The document to create. Must include 'id' field and the partition key field."
          },
          partition_key: {
            type: ["string", "number", "boolean"],
            description: "The partition key value for the document"
          },
          ...connectionIdProperty
        },
        required: ["container_id", "document", "partition_key"]
      }

• src/server.ts:149-151 (registration)

  Server-side registration where the tool name 'mcp_create_document' is matched and dispatched to the handler function.

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

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

  Re-export of mcp_create_document from dataOperations.ts, making it available to consumers of the tools module.

    mcp_create_document,
    mcp_update_document,
    mcp_delete_document,
    mcp_upsert_document
  } from './dataOperations.js';