trello_create_card_attachment

Instructions

Implementation Reference

• src/tools/advanced.ts:1116-1173 (handler)

  Handler function that executes the tool logic. Extracts credentials, validates params via validateCreateCardAttachment, calls TrelloClient.createCardAttachment(), and returns the result.

  export async function handleTrelloCreateCardAttachment(args: unknown) {
    try {
      const { credentials, params } = extractCredentials(args);
      const { cardId, url, filePath, name, mimeType, setCover} = validateCreateCardAttachment(params);
      const client = new TrelloClient(credentials);
  
      const response = await client.createCardAttachment(cardId, {
        ...(url && { url }),
        ...(filePath && { filePath }),
        ...(name && { name }),
        ...(mimeType && { mimeType }),
        ...(setCover !== undefined && { setCover })
      });
      const attachment = response.data;
  
      const result = {
        summary: filePath
          ? `Uploaded file attachment to card ${cardId}`
          : `Attached URL to card ${cardId}`,
        cardId,
        attachment: {
          id: attachment.id,
          name: attachment.name,
          url: attachment.url,
          mimeType: attachment.mimeType,
          bytes: attachment.bytes,
          isUpload: attachment.isUpload,
          date: attachment.date
        },
        rateLimit: response.rateLimit
      };
  
      return {
        content: [
          {
            type: 'text' as const,
            text: JSON.stringify(result, null, 2)
          }
        ]
      };
    } catch (error) {
      const errorMessage = error instanceof z.ZodError
        ? formatValidationError(error)
        : error instanceof Error
          ? error.message
          : 'Unknown error occurred';
  
      return {
        content: [
          {
            type: 'text' as const,
            text: `Error creating attachment: ${errorMessage}`
          }
        ],
        isError: true
      };
    }
  }

• src/tools/advanced.ts:1073-1113 (schema)

  Tool definition with inputSchema. Defines the name 'trello_create_card_attachment', description, and schema properties (apiKey, token, cardId, url, filePath, name, mimeType, setCover), with cardId as required.

  export const trelloCreateCardAttachmentTool: Tool = {
    name: 'trello_create_card_attachment',
    description: 'Attach a URL or local file to a Trello card. Provide either a url (for link attachments) or filePath (for file uploads from the local filesystem).',
    inputSchema: {
      type: 'object',
      properties: {
        apiKey: {
          type: 'string',
          description: 'Trello API key (optional if TRELLO_API_KEY env var is set)'
        },
        token: {
          type: 'string',
          description: 'Trello API token (optional if TRELLO_TOKEN env var is set)'
        },
        cardId: {
          type: 'string',
          description: 'ID or URL of the card (e.g. "abc123" or "https://trello.com/c/abc123/1-title")'
        },
        url: {
          type: 'string',
          description: 'URL to attach as a link (e.g. "https://example.com/doc.pdf"). Cannot be used with filePath.'
        },
        filePath: {
          type: 'string',
          description: 'Absolute path to a local file to upload (e.g. "/home/user/report.pdf"). Cannot be used with url.'
        },
        name: {
          type: 'string',
          description: 'Optional display name for the attachment'
        },
        mimeType: {
          type: 'string',
          description: 'Optional MIME type (e.g. "application/pdf", "image/png"). Auto-detected for file uploads if omitted.'
        },
        setCover: {
          type: 'boolean',
          description: 'If true, set this attachment as the card cover image'
        }
      },
      required: ['cardId']
    }

• src/index.ts:98-99 (registration)

  Import of the tool definition and handler from src/tools/advanced.ts.

  trelloCreateCardAttachmentTool,
  handleTrelloCreateCardAttachment,

• src/index.ts:199-199 (registration)

  Tool is registered in the tool list (server.setRequestHandler for ListTools) as part of the advanced features array.

  trelloCreateCardAttachmentTool,

• src/index.ts:317-318 (registration)

  Case statement in the CallToolRequestHandler that routes the tool call to handleTrelloCreateCardAttachment.

  case 'trello_create_card_attachment':
    result = await handleTrelloCreateCardAttachment(args);

• src/tools/advanced.ts:58-72 (helper)

  Validation helper using Zod schema; validates cardId (Trello ID), optional url/filePath, name, mimeType, setCover. Requires either url or filePath via refine.

  const validateCreateCardAttachment = (args: unknown) => {
    const schema = z.object({
  
      cardId: trelloIdSchema,
      url: z.string().url().optional(),
      filePath: z.string().optional(),
      name: z.string().optional(),
      mimeType: z.string().optional(),
      setCover: z.boolean().optional()
    }).refine(data => data.url || data.filePath, {
      message: 'Either url or filePath must be provided'
    });
  
    return schema.parse(args);
  };

• src/trello/client.ts:605-649 (helper)

  TrelloClient.createCardAttachment method that handles both file upload (multipart/form-data) and URL attachment (JSON POST) to /cards/{cardId}/attachments.

  async createCardAttachment(cardId: string, data: {
    url?: string;
    filePath?: string;
    name?: string;
    mimeType?: string;
    setCover?: boolean;
  }): Promise<TrelloApiResponse<TrelloAttachment>> {
    if (data.filePath) {
      // File upload via multipart/form-data
      const fileBuffer = await readFile(data.filePath);
      const fileName = data.name || basename(data.filePath);
      const blob = new Blob([fileBuffer], { type: data.mimeType || 'application/octet-stream' });
  
      const formData = new FormData();
      formData.append('file', blob, fileName);
      if (data.name) formData.append('name', data.name);
      if (data.mimeType) formData.append('mimeType', data.mimeType);
      if (data.setCover !== undefined) formData.append('setCover', String(data.setCover));
  
      return this.makeRequest<TrelloAttachment>(
        `/cards/${cardId}/attachments`,
        {
          method: 'POST',
          body: formData as any
        },
        `Upload file attachment to card ${cardId}`
      );
    }
  
    // URL attachment via JSON body
    const body: Record<string, any> = {};
    if (data.url) body.url = data.url;
    if (data.name) body.name = data.name;
    if (data.mimeType) body.mimeType = data.mimeType;
    if (data.setCover !== undefined) body.setCover = data.setCover;
  
    return this.makeRequest<TrelloAttachment>(
      `/cards/${cardId}/attachments`,
      {
        method: 'POST',
        body: JSON.stringify(body)
      },
      `Create URL attachment on card ${cardId}`
    );
  }

• src/server.ts:119-120 (registration)

  Tool name listed in WRITE_TOOL_NAMES set, which controls write-allowed tool filtering in server creation.

    'trello_create_card_attachment', 'trello_delete_card_attachment'
  ]);