24 lines
3.8 KiB
Markdown
24 lines
3.8 KiB
Markdown
# 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 between project boards keeps the same card and comment records, so its files and progress-note files remain attached and accessible to destination project members. 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.
|