3.6 KiB
Card and progress-note attachments
Attachments are stored as private files with metadata in CardAttachment. A file belongs to one card, and optionally one CardComment progress note on that card. Moving a card keeps its files. Deleting a note or card cascades to its attachment records and removes stored files. Explicit deletion also removes the bytes. Files are snapshots; source_path and source_commit record provenance but do not cause automatic refresh.
Configuration
Set PROJECTS_PRIVATE_MEDIA_ROOT to a persistent directory outside any web server static or public media alias. The default is private_media/ under the repository for local development. Back up this directory alongside the database. The application account needs read/write access. No MEDIA_URL or public media route is configured.
Limits default to 10 MiB per file, 50 files and 100 MiB per card. Override with PROJECTS_ATTACHMENT_MAX_BYTES, PROJECTS_ATTACHMENT_MAX_FILES and PROJECTS_ATTACHMENT_MAX_CARD_BYTES. MCP base64 upload/fetch has a stricter 2 MiB limit to bound tool payloads. The accepted extensions are UTF-8 text/code (txt, md, py, js, ts, tsx, jsx, json, css, html, xml, csv, yaml, yml, sh, diff, patch) and PNG, JPEG, WebP, PDF. HTML is always served as plain text. SVG and archives are rejected. Files are not extracted or executed. Download responses use Content-Disposition: attachment, nosniff, and no-store.
Web use
On a card page, upload multiple files in Card files or beneath a specific progress note. The form works without JavaScript; JavaScript adds drag and drop, progress and inline error feedback. The card and note sections share a simple list. Safe images up to 1 MiB have a thumbnail and preview link; UTF-8 text up to 1 MiB has a text preview. Other files download. Rename changes only the display title. Deleting requires confirmation.
All reads require project access. Upload, rename and delete require editor or owner access. Django session forms use CSRF. An attachment ID alone does not grant access.
MCP transfer
attachments_list(card_id, comment_id?, limit?, offset?) returns metadata for card and note files. attachments_get(attachment_id) returns metadata. attachments_fetch(attachment_id) returns exact content_base64, SHA-256, and decoded text for UTF-8 files. attachments_upload(card_id, filename, content_base64, comment_id?, title?, description?, source_path?, source_commit?) transfers bytes to the server. attachments_update changes display metadata; attachments_delete removes bytes and metadata. Read tools require projects:read; writes require projects:write. Each tool checks card access. A remote server never reads a caller's filesystem path.
For a local repository snapshot, read the file locally, calculate its SHA-256, base64 encode the bytes, then call attachments_upload with the target card and progress-note IDs. Include a repository-relative source_path and a Git commit SHA when available. Compare the returned SHA-256; attachments_fetch lets another client verify exact bytes. If a working-tree file differs from the recorded commit, describe that in the progress note; source_commit alone cannot establish the working-tree state.
The tool output uses standard base64 in structured JSON so clients can reconstruct binary files. Client support for passing generated image bytes into a tool, exposing large tool payloads, and rendering fetched images must be checked against a deployed MCP connection. The local tests exercise the actual MCP tool call path for text bytes and permission denial; they cannot establish compatibility with a remote ChatGPT client before deployment.