Skip to main content
Glama
Sign In
artsonia-mcp

artsonia-mcp

by chrischall
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Download a student's artwork images

artsonia_download_artwork
Destructive

Download full-resolution student artwork images to a local folder, optionally filtering by class, grade, or recent count, and saving comments or EXIF metadata.

Instructions

Download full-resolution images of a student's artwork to a local folder, named from the artwork title/project/grade and time-stamped to the image's source date. Optionally filter by class/project (substring), grade, and/or keep only the most-recent N (the portfolio is reliably newest-first). Re-runs are idempotent (skip_existing). Runs immediately, with no confirmation step; writes only inside the allowed download folders. write_metadata:true also saves each artwork's comments + teacher feedback as a .json sidecar next to its image. embed_metadata:true embeds title/project/grade/date into each JPEG's EXIF/IPTC. path_template (e.g. "{grade}/{project}" or "{school_year}") organizes downloads into subfolders for multi-year archives. Note: descriptive filenames need each artwork's detail page (slower) — use filename_template "{artwork_id}" for the fast id-only path.

Input Schema

NameRequiredDescriptionDefault
destYesLocal destination folder (a leading ~ is expanded). Created if missing. Must be inside the allowed download folders: ARTSONIA_OUTPUT_DIR when set, otherwise ~/Downloads or ~/Pictures (on a hosted server, $MCP_DATA_DIR/downloads); anything else is refused before any download.
gradeNoOnly artworks created in this grade, e.g. "6" or "Grade 6".
limitNoKeep only the N most recent matching artworks (portfolio is newest-first).
projectNoOnly artworks whose school-project/class name contains this (case-insensitive).
artist_idYesStudent artist_id (from artsonia_list_students).
resolutionNoImage resolution. "full" is the original (~0.7 MB each).full
write_indexNoAfter downloading, write an index.json manifest into the destination folder listing the downloaded items (artwork_id, title, file, grade, project, date). Off by default.
path_templateNoOptional subfolder pattern under dest, composed with filename_template — e.g. "{grade}/{project}" or "{school_year}" for multi-year archives. Same tokens as filename_template; segments are slugified like filenames and empty tokens collapse (no empty folders). Paths are deterministic, so skip_existing re-runs stay idempotent. {school_year} (July–June, e.g. "2021-2022") derives from the image's Last-Modified.
skip_existingNoSkip artworks whose target file already exists (idempotent re-runs). Set false to overwrite.
embed_metadataNoEmbed each image's title/project/grade and source date (its Last-Modified, same as date_source) into the JPEG's EXIF (ImageDescription, DateTimeOriginal) and IPTC (title, keywords, date) so the metadata survives renames/moves and is searchable in Spotlight/Apple Photos. Needs each artwork's detail page (slower); applies to freshly downloaded files only (skipped files are left untouched). Off by default.
write_metadataNoAfter downloading, write a per-artwork <image-name>.json sidecar next to each image with the artwork's comments and teacher feedback (plus title/project/grade). Fetches each artwork's detail page + the student's feedback page. Off by default.
include_privateNoInclude artworks marked private in the portfolio. Set false to exclude them (excluded count is reported as private_excluded_count).
filename_templateNoFilename pattern. Tokens: {title} {project} {grade} {date} {school_year} {artwork_id}. The artwork_id is auto-appended for uniqueness if absent. Use "{artwork_id}" for the fast id-only path (no detail fetch).{grade} - {project} - {title}
set_mtime_from_sourceNoSet each file's modified time from the image's Last-Modified header (its Artsonia upload date) instead of the download moment.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.3.1
    • removedInput schema / properties / confirmToken
      Removed value: -{
-  "description": "ONLY for the two-step confirmation fallback (a client without MCP elicitation). The confirmToken from this same tool's phase-1 \"confirmation-required\" response, passed back ONLY after the user has seen that preview and explicitly approved it in chat — never on the first call, never invented, never reused. Call again with the same arguments. Ignored when the client supports elicitation.",
-  "type": "string"
-}
  2. Changed1 schema field changedv1.2.3
    • changedInput schema / properties / dest / description
      Previous value: -"Local destination folder (a leading ~ is expanded). Created if missing."New value: +"Local destination folder (a leading ~ is expanded). Created if missing. Must be inside the allowed download folders: ARTSONIA_OUTPUT_DIR when set, otherwise ~/Downloads or ~/Pictures (on a hosted server, $MCP_DATA_DIR/downloads); anything else is refused before any download."
  3. First observedv1.2.1

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations: no confirmation step, writes confined to allowed download folders, idempotent re-runs via skip_existing, sidecar JSON and EXIF/IPTC embedding behavior, deterministic path templates, and that portfolio order is reliably newest-first. This is rich disclosure that heavily complements destructiveHint/openWorldHint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded and each sentence carries operational information, but the dense single paragraph packs a lot of qualifiers, making it slightly heavy to scan. No wasted sentences, but tighter grouping into sub-points would help.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 14-parameter mutation tool with no output schema, the description covers write scope, idempotency, metadata options, and pathing well. It doesn't describe reported return values (e.g. counts, private_excluded_count) which are left to the schema, a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% (baseline 3), but the description adds cross-parameter meaning: the speed trade-off between descriptive filename tokens and the id-only path, the path_template subfolder semantics, and the newest-first ordering that motivates limit. It reinforces rather than merely repeats the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (download full-resolution images of a student's artwork to a local folder) and distinguishes itself from the read-only siblings like artsonia_get_artwork/artsonia_get_portfolio by emphasizing it writes files locally.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Clear context for when to reach for it (bulk local archiving, with filters for class/project/grade/recency), and it explicitly routes between the descriptive-filename slow path and the '{artwork_id}' fast path. It does not name a sibling alternative or state when NOT to use it, so it stops short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools