create_doc

Instructions

Implementation Reference

• src/tools/create_doc.ts:35-146 (handler)

  Main handler function that validates inputs (title, text, optional folder), resolves folder reference, calls DartClient.createDoc(), and returns the created document with a deep link URL.

  export async function handleCreateDoc(input: CreateDocInput): Promise<CreateDocOutput> {
    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 required fields
    // ============================================================================
    if (!input.title || typeof input.title !== 'string' || input.title.trim() === '') {
      throw new ValidationError(
        'title is required and must be a non-empty string',
        'title'
      );
    }
  
    if (!input.text || typeof input.text !== 'string') {
      throw new ValidationError(
        'text is required and must be a string (markdown supported)',
        'text'
      );
    }
  
    // ============================================================================
    // Step 2: Validate folder reference (if provided)
    // ============================================================================
    let resolvedFolder: string | undefined;
  
    if (input.folder) {
      // Get config to validate folder reference
      let config: DartConfig;
      try {
        config = await handleGetConfig({ cache_bust: false });
      } catch (error) {
        if (error instanceof DartAPIError) {
          throw new DartAPIError(
            `Failed to retrieve workspace config for folder validation: ${error.message}`,
            error.statusCode,
            error.response
          );
        }
        throw error;
      }
  
      // Check if folder exists
      if (!config.folders || config.folders.length === 0) {
        throw new ValidationError(
          'No folders found in workspace configuration. Create a folder first in Dart AI.',
          'folder'
        );
      }
  
      const folder = findFolder(config.folders, input.folder);
  
      if (!folder) {
        const folderNames = getFolderNames(config.folders);
        const availableFolders = folderNames.join(', ');
        throw new ValidationError(
          `Invalid folder: "${input.folder}" not found in workspace. Available folders: ${availableFolders}`,
          'folder',
          folderNames
        );
      }
  
      resolvedFolder = folder.dart_id;
    }
  
    // ============================================================================
    // Step 3: Call DartClient.createDoc()
    // ============================================================================
    const client = new DartClient({ token: DART_TOKEN });
  
    const docInput: { title: string; text: string; folder?: string } = {
      title: input.title,
      text: input.text,
    };
  
    if (resolvedFolder) {
      docInput.folder = resolvedFolder;
    }
  
    let createdDoc;
    try {
      createdDoc = await client.createDoc(docInput);
    } catch (error) {
      if (error instanceof DartAPIError) {
        throw new DartAPIError(
          `Failed to create document: ${error.message}`,
          error.statusCode,
          error.response
        );
      }
      throw error;
    }
  
    // ============================================================================
    // Step 4: Generate deep link URL and return output
    // ============================================================================
    const deepLinkUrl = `https://app.dartai.com/doc/${createdDoc.doc_id}`;
  
    return {
      doc_id: createdDoc.doc_id,
      title: createdDoc.title,
      url: deepLinkUrl,
      created_at: createdDoc.created_at,
      all_fields: createdDoc,
    };
  }

• src/types/index.ts:542-546 (schema)

  CreateDocInput interface defining the input schema: title (string), text (string), folder (optional string).

  export interface CreateDocInput {
    title: string;
    text: string;
    folder?: string;
  }

• src/types/index.ts:548-554 (schema)

  CreateDocOutput interface defining the return shape: doc_id, title, url, created_at, all_fields (DartDoc).

  export interface CreateDocOutput {
    doc_id: string;
    title: string;
    url: string;
    created_at: string;
    all_fields: DartDoc;
  }

• src/index.ts:693-714 (registration)

  Tool registration with name 'create_doc', description, inputSchema (title, text required, folder optional).

  {
    name: 'create_doc',
    description: 'Create a new document with title, text (markdown supported), and optional folder',
    inputSchema: {
      type: 'object',
      properties: {
        title: {
          type: 'string',
          description: 'Document title',
        },
        text: {
          type: 'string',
          description: 'Document text content (markdown supported)',
        },
        folder: {
          type: 'string',
          description: 'Folder dart_id or name (optional)',
        },
      },
      required: ['title', 'text'],
    },
  },

• src/index.ts:1124-1130 (registration)

  Tool dispatch case 'create_doc' that calls handleCreateDoc and returns JSON-stringified result.

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