Skip to main content
Glama
Sign In
Scormave

Gramps Web MCP

by Scormave
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Hybrid

Read Media

read_media
Read-only

Download media bytes to view Gramps Web photos, scans, or audio; default thumbnail renders a JPEG preview, while file mode returns the original.

Instructions

Download a media file's bytes so you can see it. Default mode thumbnail renders a JPEG preview (PNG when transparent) from an image original as MCP image content, 1568 pixels on the long edge unless size is given; EXIF and other metadata are stripped. Prefer it for reading photos and document scans; region shows one part of an image, as a media link with that region does. Use mode file only when the original is needed: returns image, audio, or embedded blob resource content according to MIME type. Requires GRAMPS_MEDIA_RESOURCES_ENABLED=true and respects size and private-record safeguards. For the media record itself (path, description, links) use get_object; to change it use update_media.

Input Schema

NameRequiredDescriptionDefault
modeNoDownload mode: thumbnail | file. Default thumbnail. Use file only when a preview is insufficient.thumbnail
sizeNoThumbnail long edge in pixels, 1 to 4096; default 1568, which keeps handwriting and small print legible. Use 512 or less for a quick look at photos. Images are never upscaled. Only valid for mode thumbnail; omit for mode file.
handleYesThe media object to show. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects.
regionNoShow only this part of the image, at up to size pixels on its long edge: [left, top, right, bottom] in percent of the image width and height, 0 to 100, from the top-left corner, as stored on a media link. Use it to check a region before saving it in mediaHandles or attachTo, or to read one record on a page scan. Only valid for mode thumbnail.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv2.5.1
    • addedInput schema / properties / region
      Added value: +{
+  "default": null,
+  "description": "Show only this part of the image, at up to size pixels on its long edge: [left, top, right, bottom] in percent of the image width and height, 0 to 100, from the top-left corner, as stored on a media link. Use it to check a region before saving it in mediaHandles or attachTo, or to read one record on a page scan. Only valid for mode thumbnail.",
+  "items": {
+    "type": "number"
+  },
+  "type": [
+    "array",
+    "null"
+  ]
+}
  2. Added

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare a safe read (readOnlyHint=true, destructiveHint=false), and the description adds real context beyond them: the GRAMPS_MEDIA_RESOURCES_ENABLED=true prerequisite, EXIF/metadata stripping, no upscaling, and respect for size and private-record safeguards. It also discloses the differing return shapes per mode (MCP image content vs media link vs blob resource by MIME).

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?

Front-loaded with the core action and default mode, and every clause carries information (mode selection, output type, prerequisites, siblings). It is dense with semicolons and a few clauses restate schema details, which slightly blurs the structure.

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

Completeness5/5

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

For a read-only media fetch with no output schema, the description covers the key unknowns: what content type is returned per mode and MIME, the environment flag required, metadata stripping, and where to go for the record itself or for modification. An agent has everything needed to call it correctly.

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% and the schema already carries most semantics, but the description adds decision-level rationale: region is for verifying a crop before saving it, and the default 1568 size is chosen to keep handwriting and small print legible. Some of this overlaps the schema text (e.g., 1568px long edge, 512 for a quick look), so the added value is moderate rather than decisive.

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?

Opens with a concrete verb+resource ('Download a media file's bytes') and immediately states the default behavior (JPEG thumbnail preview, PNG when transparent, 1568px long edge). It explicitly distinguishes itself from get_object (media record metadata) and update_media (changing it), so an agent can route correctly without opening sibling schemas.

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

Usage Guidelines5/5

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

Gives explicit when-to-use guidance: prefer thumbnail for reading photos and document scans, use region to check a part of an image before persisting it in mediaHandles or attachTo, and use mode file only when the original is needed. It also names the alternatives for adjacent needs (get_object, update_media) and the search/list_objects route to find a handle.

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