delete_doc

Instructions

Implementation Reference

• src/tools/delete_doc.ts:27-91 (handler)

  Main handler function for the delete_doc tool. Validates input (DART_TOKEN, doc_id), calls DartClient.deleteDoc(), and returns DeleteDocOutput with recoverability information.

  export async function handleDeleteDoc(input: DeleteDocInput): Promise<DeleteDocOutput> {
    const DART_TOKEN = process.env.DART_TOKEN;
  
    if (!DART_TOKEN) {
      throw new DartAPIError(
        'DART_TOKEN environment variable is required. Get your token from: https://app.dartai.com/?settings=account',
        401
      );
    }
  
    // ============================================================================
    // Step 1: Validate input and doc_id
    // ============================================================================
    if (!input || typeof input !== 'object') {
      throw new DartAPIError(
        'input is required and must be an object',
        400
      );
    }
  
    if (!input.doc_id || typeof input.doc_id !== 'string' || input.doc_id.trim() === '') {
      throw new DartAPIError(
        'doc_id is required and must be a non-empty string',
        400
      );
    }
  
    // ============================================================================
    // Step 2: Call DartClient.deleteDoc()
    // ============================================================================
    const client = new DartClient({ token: DART_TOKEN });
  
    let result: { success: boolean; doc_id: string };
    try {
      result = await client.deleteDoc(input.doc_id);
    } catch (error) {
      // Handle 404 errors specifically
      if (error instanceof DartAPIError && error.statusCode === 404) {
        throw new DartAPIError(
          `Document not found: No document with doc_id "${input.doc_id}" exists in workspace`,
          404,
          error.response
        );
      }
      // Re-throw other errors with enhanced context
      if (error instanceof DartAPIError) {
        throw new DartAPIError(
          `Failed to delete document: ${error.message}`,
          error.statusCode,
          error.response
        );
      }
      throw error;
    }
  
    // ============================================================================
    // Step 3: Return output with recoverability information
    // ============================================================================
    return {
      doc_id: result.doc_id,
      deleted: result.success,
      recoverable: true, // Documents move to trash (recoverable via web UI)
      message: `Document "${result.doc_id}" moved to trash. Recoverable via Dart web UI: https://app.dartai.com/trash`,
    };
  }

• src/types/index.ts:581-583 (schema)

  DeleteDocInput interface – defines the input schema with a required doc_id string field.

  export interface DeleteDocInput {
    doc_id: string;
  }

• src/types/index.ts:585-590 (schema)

  DeleteDocOutput interface – defines the output shape with doc_id, deleted, recoverable, and message fields.

  export interface DeleteDocOutput {
    doc_id: string;
    deleted: boolean;
    recoverable: boolean;
    message: string;
  }

• src/index.ts:762-774 (registration)

  Tool registration in the MCP server tool list – defines the name 'delete_doc', description, and inputSchema (object with required doc_id string).

    name: 'delete_doc',
    description: 'Delete a document (moves to trash - recoverable via Dart web UI)',
    inputSchema: {
      type: 'object',
      properties: {
        doc_id: {
          type: 'string',
          description: 'Document doc_id to delete',
        },
      },
      required: ['doc_id'],
    },
  },

• src/index.ts:1160-1170 (registration)

  Tool dispatch handler in the main switch statement – calls handleDeleteDoc and returns JSON-formatted result.

  case 'delete_doc': {
    const result = await handleDeleteDoc((args || {}) as any);
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(result, null, 2),
        },
      ],
    };
  }