Hi! I've been using this MCP server and ran into a gap -- there's currently no way to see or retrieve attachments from conversation threads.
The Help Scout API already returns attachment metadata embedded in thread responses (_embedded.attachments on each thread from GET /conversations/{id}/threads), but the server's ThreadSchema doesn't model that field, so the data gets silently dropped.
Proposal:
-
Surface attachment metadata in getThreads responses -- Add an AttachmentSchema (id, filename, mimeType, size, etc.) and extend ThreadSchema to include the optional _embedded.attachments array. This requires no additional API calls since the data is already in the response.
-
Add a downloadAttachment tool -- A new tool that takes a conversationId and attachmentId, fetches the file content via the Help Scout attachment data endpoint (GET /v2/conversations/{conversationId}/attachments/{attachmentId}/data), writes it to a configurable directory on disk, and returns the file path. This avoids bloating the AI context window with file contents.
The download directory could default to a subdirectory under os.tmpdir() and then be overridden via an ATTACHMENT_DOWNLOAD_DIR environment variable, consistent with how other config options work in the project.
The typical workflow would be: call getThreads to discover attachments, then call downloadAttachment for any file you need.
Would you be open to a PR adding this? Happy to discuss the approach if you have different ideas about how it should work.
Hi! I've been using this MCP server and ran into a gap -- there's currently no way to see or retrieve attachments from conversation threads.
The Help Scout API already returns attachment metadata embedded in thread responses (
_embedded.attachmentson each thread fromGET /conversations/{id}/threads), but the server'sThreadSchemadoesn't model that field, so the data gets silently dropped.Proposal:
Surface attachment metadata in
getThreadsresponses -- Add anAttachmentSchema(id, filename, mimeType, size, etc.) and extendThreadSchemato include the optional_embedded.attachmentsarray. This requires no additional API calls since the data is already in the response.Add a
downloadAttachmenttool -- A new tool that takes aconversationIdandattachmentId, fetches the file content via the Help Scout attachment data endpoint (GET /v2/conversations/{conversationId}/attachments/{attachmentId}/data), writes it to a configurable directory on disk, and returns the file path. This avoids bloating the AI context window with file contents.The download directory could default to a subdirectory under
os.tmpdir()and then be overridden via anATTACHMENT_DOWNLOAD_DIRenvironment variable, consistent with how other config options work in the project.The typical workflow would be: call
getThreadsto discover attachments, then calldownloadAttachmentfor any file you need.Would you be open to a PR adding this? Happy to discuss the approach if you have different ideas about how it should work.