attach_url

Instructions

Implementation Reference

• src/tools/attach_url.ts:26-74 (handler)

  The main handler function `handleAttachUrl` that implements the attach_url tool logic: validates input (DART_TOKEN, input object, dart_id, url, filename), constructs a DartClient, calls client.attachUrl(), and returns the result with a task_url.

  export async function handleAttachUrl(input: AttachUrlInput): Promise<AttachUrlOutput> {
    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
      );
    }
  
    // Validate input
    if (!input || typeof input !== 'object') {
      throw new ValidationError('Input must be an object', 'input');
    }
  
    // Accept id, task_id, or taskId as aliases for dart_id
    input.dart_id = resolveDartId(input as unknown as Record<string, unknown>);
  
    if (!input.url || typeof input.url !== 'string' || input.url.trim() === '') {
      throw new ValidationError('url is required and must be a non-empty string', 'url');
    }
  
    if (!URL_PATTERN.test(input.url.trim())) {
      throw new ValidationError(
        'url must be a valid HTTP or HTTPS URL',
        'url'
      );
    }
  
    if (input.filename !== undefined && typeof input.filename !== 'string') {
      throw new ValidationError('filename must be a string if provided', 'filename');
    }
  
    const client = new DartClient({ token: DART_TOKEN });
  
    const result = await client.attachUrl({
      dart_id: input.dart_id.trim(),
      url: input.url.trim(),
      filename: input.filename,
    });
  
    return {
      attachment_id: result.attachment_id,
      dart_id: result.dart_id,
      url: result.url,
      filename: result.filename,
      task_url: `https://app.dartai.com/task/${input.dart_id.trim()}`,
    };
  }

• src/types/index.ts:870-874 (schema)

  AttachUrlInput interface defining the input schema: dart_id (string), url (string), and optional filename (string).

  export interface AttachUrlInput {
    dart_id: string;
    url: string;
    filename?: string;
  }

• src/types/index.ts:876-882 (schema)

  AttachUrlOutput interface defining the output schema: attachment_id, dart_id, url, filename, and task_url (all strings).

  export interface AttachUrlOutput {
    attachment_id: string;
    dart_id: string;
    url: string;
    filename: string;
    task_url: string;
  }

• src/index.ts:907-928 (registration)

  MCP tool registration for 'attach_url': defines name, description, inputSchema with dart_id, url, and optional filename properties.

  {
    name: 'attach_url',
    description: 'Attach a file from URL to a task. URL must be publicly accessible.',
    inputSchema: {
      type: 'object',
      properties: {
        dart_id: {
          type: 'string',
          description: 'Task dart_id (also accepts "id" or "task_id")',
        },
        url: {
          type: 'string',
          description: 'Public URL of file to attach',
        },
        filename: {
          type: 'string',
          description: 'Optional filename override',
        },
      },
      required: ['dart_id', 'url'],
    },
  },

• src/api/dartClient.ts:695-729 (helper)

  The API client method `attachUrl` that sends a POST request to `/tasks/{dart_id}/attachments/from-url` with the url (and optional filename), then maps the response to attachment_id, dart_id, url, and filename.

  async attachUrl(input: {
    dart_id: string;
    url: string;
    filename?: string;
  }): Promise<{
    attachment_id: string;
    dart_id: string;
    url: string;
    filename: string;
  }> {
    if (!input.dart_id || typeof input.dart_id !== 'string' || input.dart_id.trim() === '') {
      throw new DartAPIError('dart_id is required and must be a non-empty string', 400);
    }
    if (!input.url || typeof input.url !== 'string' || input.url.trim() === '') {
      throw new DartAPIError('url is required and must be a non-empty string', 400);
    }
  
    const apiInput: Record<string, unknown> = {
      url: input.url,
    };
    if (input.filename !== undefined) apiInput.filename = input.filename;
  
    const response = await this.request<{ item: any }>(
      'POST',
      `/tasks/${encodeURIComponent(input.dart_id.trim())}/attachments/from-url`,
      { item: apiInput }
    );
  
    return {
      attachment_id: response.item?.id || '',
      dart_id: input.dart_id,
      url: response.item?.url || input.url,
      filename: response.item?.filename || input.filename || '',
    };
  }