@yuiseki/gyazocli 0.2.0 → 0.4.0

package/README.md

@@ -131,14 +131,31 @@ Configured in a client:
 - `gyazo_summary`: what a day or a range adds up to, with the same options as
   `gyazo summary`: `date`, `today`, `limit`, `max_pages`, `use_cache`. No
   arguments means the week up to yesterday.
+- `gyazo_recent`: what arrived since a moment or since a capture you have
+  already seen. Arguments: `minutes`, `since`, `after_image_id`, `limit`,
+  `max_pages`. No arguments means the last 30 minutes.
 - `gyazo_collection`: a collection and the captures in it. Arguments:
-  `id_or_url` (required) and `sort` (`added`, `created` or `captured`).
-
-All of them are read-only, and all of them return metadata rather than image
-bytes: URLs, timestamp, OCR text, title, source application and page, and
-location when the capture carries one. Use the URLs in a result to show the
-capture itself. Handing base64 image data to a model turned out not to work
-well in practice, and describing a capture does.
+  `id_or_url` (required), `sort` (`added`, `created` or `captured`), `page` and
+  `per`. Reports `total_image_count`, `returned_image_count` and `truncated`.
+- `gyazo_collections`: the collections, with their IDs, filtered by `query`
+  against their names.
+- `gyazo_image_content`: the pixels of one capture, as image content.
+  Arguments: `id_or_url` (required), `width` (default 1024), `format`
+  (`webp` or `jpeg`) and `max_bytes`.
+
+All of them are read-only. Everything except `gyazo_image_content` returns
+metadata rather than image bytes: URLs, timestamps, OCR text, title, source
+application and page, and location when the capture carries one. URLs, timestamp, OCR text, title, source application and page, and
+location when the capture carries one. A capture with a location gets a `location` holding
+`latitude`, `longitude`, `country_code` and an address in Japanese and
+English, each with its `locality` and `admin1`, plus `altitude_m` and
+`heading_deg` where the response carries the raw EXIF, which is the case for
+captures read through a collection. `captured_at` is when the shutter was
+pressed, as distinct from the upload time in `created_at`.
+
+For the pixels, `gyazo_image_content` returns a width-limited rendition, one
+capture at a time. Returning image bytes from the list and search tools is
+what made this awkward in practice, so those stay metadata-only.
 
 Tool names and arguments follow
 [nota/gyazo-mcp-server](https://github.com/nota/gyazo-mcp-server), so a client

package/dist/api.js

@@ -8,6 +8,10 @@ exports.getImageDetail = getImageDetail;
 exports.searchImages = searchImages;
 exports.getCurrentUser = getCurrentUser;
 exports.getCollection = getCollection;
+exports.listCollections = listCollections;
+exports.getCollectionDetail = getCollectionDetail;
+exports.listCollectionImages = listCollectionImages;
+exports.fetchImageRendition = fetchImageRendition;
 exports.uploadImage = uploadImage;
 const axios_1 = __importDefault(require("axios"));
 const form_data_1 = __importDefault(require("form-data"));
@@ -15,6 +19,7 @@ const config_1 = require("./config");
 const DEFAULT_API_ORIGIN = 'https://api.gyazo.com';
 const DEFAULT_UPLOAD_ORIGIN = 'https://upload.gyazo.com';
 const DEFAULT_WEB_ORIGIN = 'https://gyazo.com';
+const DEFAULT_IMAGE_ORIGIN = 'https://i.gyazo.com';
 function stripTrailingSlash(origin) {
     return origin.replace(/\/+$/, '');
 }
@@ -27,11 +32,17 @@ function uploadOrigin() {
 function webOrigin() {
     return stripTrailingSlash(config_1.config.GYAZO_WEB_ORIGIN || DEFAULT_WEB_ORIGIN);
 }
+function imageOrigin() {
+    return stripTrailingSlash(config_1.config.GYAZO_IMAGE_ORIGIN || DEFAULT_IMAGE_ORIGIN);
+}
 const apiBaseUrl = () => `${apiOrigin()}/api/images`;
 const apiSearchUrl = () => `${apiOrigin()}/api/search`;
 const apiUsersMeUrl = () => `${apiOrigin()}/api/users/me`;
 const apiUploadUrl = () => `${uploadOrigin()}/api/upload`;
 const webCollectionUrl = (id) => `${webOrigin()}/collections/${id}.json`;
+const apiCollectionsUrl = () => `${apiOrigin()}/api/v2/collections`;
+const apiCollectionUrl = (id) => `${apiCollectionsUrl()}/${id}`;
+const apiCollectionImagesUrl = (id) => `${apiCollectionUrl(id)}/images`;
 async function requestWithRetry(url, params = {}, headers) {
     const requestHeaders = headers ?? { Authorization: `Bearer ${config_1.config.GYAZO_ACCESS_TOKEN}` };
     try {
@@ -73,6 +84,54 @@ async function getCollection(collectionId, options = {}) {
     }
     return requestWithRetry(webCollectionUrl(collectionId), {}, headers);
 }
+/**
+ * The collections the token can see, newest activity first as the API orders
+ * them. Needed to turn a collection people call by name into an ID.
+ */
+async function listCollections() {
+    const data = await requestWithRetry(apiCollectionsUrl());
+    if (Array.isArray(data))
+        return data;
+    return Array.isArray(data?.collections) ? data.collections : [];
+}
+/** A collection's own fields, without its images. */
+async function getCollectionDetail(collectionId) {
+    return requestWithRetry(apiCollectionUrl(collectionId));
+}
+/**
+ * A page of a collection's images. Unlike the public web endpoint, which
+ * returns the first 100 and ignores every paging parameter, this one really
+ * pages, and its images carry the raw EXIF.
+ */
+async function listCollectionImages(collectionId, page = 1, per = 100) {
+    const data = await requestWithRetry(apiCollectionImagesUrl(collectionId), { page, per });
+    if (Array.isArray(data))
+        return data;
+    return Array.isArray(data?.images) ? data.images : [];
+}
+/**
+ * A width-limited rendition of a capture.
+ *
+ * The original can be several megabytes, which is no use to a model, and
+ * resizing locally would mean a native image library. Gyazo will do it: the
+ * rendition route takes a width and needs no credentials, so a capture can be
+ * handed over at a size that fits. 1024 wide lands around 130 KB as webp.
+ */
+async function fetchImageRendition(imageId, width, format = 'webp') {
+    const extension = format === 'jpeg' ? 'jpg' : 'webp';
+    const url = `${imageOrigin()}/thumb/${width}_w/${imageId}.${extension}`;
+    const response = await axios_1.default.get(url, { responseType: 'arraybuffer' });
+    const data = Buffer.from(response.data);
+    const contentType = String(response.headers['content-type'] || '').split(';')[0].trim();
+    return {
+        data,
+        mimeType: contentType || `image/${format}`,
+        bytes: data.length,
+        url,
+        width,
+        format,
+    };
+}
 async function uploadImage(options) {
     const form = new form_data_1.default();
     form.append('access_token', config_1.config.GYAZO_ACCESS_TOKEN || '');

package/dist/config.js

@@ -16,6 +16,7 @@ const configSchema = zod_1.z.object({
     GYAZO_API_ORIGIN: zod_1.z.string().optional(),
     GYAZO_UPLOAD_ORIGIN: zod_1.z.string().optional(),
     GYAZO_WEB_ORIGIN: zod_1.z.string().optional(),
+    GYAZO_IMAGE_ORIGIN: zod_1.z.string().optional(),
 });
 exports.config = configSchema.parse({
     GYAZO_ACCESS_TOKEN: process.env.GYAZO_ACCESS_TOKEN,
@@ -25,6 +26,7 @@ exports.config = configSchema.parse({
     GYAZO_API_ORIGIN: process.env.GYAZO_API_ORIGIN,
     GYAZO_UPLOAD_ORIGIN: process.env.GYAZO_UPLOAD_ORIGIN,
     GYAZO_WEB_ORIGIN: process.env.GYAZO_WEB_ORIGIN,
+    GYAZO_IMAGE_ORIGIN: process.env.GYAZO_IMAGE_ORIGIN,
 });
 function setAccessToken(token) {
     exports.config.GYAZO_ACCESS_TOKEN = token;

package/dist/format.js

@@ -13,6 +13,7 @@ exports.cleanTextForDomain = cleanTextForDomain;
 exports.stripInlineUrls = stripInlineUrls;
 exports.sanitizeSummaryText = sanitizeSummaryText;
 exports.getAddressEntry = getAddressEntry;
+exports.getAddressComponentCode = getAddressComponentCode;
 exports.getAddressComponent = getAddressComponent;
 exports.buildJaLocationLabel = buildJaLocationLabel;
 exports.buildEnLocationLabel = buildEnLocationLabel;
@@ -97,6 +98,28 @@ function getAddressEntry(exifAddress, locale) {
         return undefined;
     return entry;
 }
+/**
+ * The short form of a component, which is what a country code is: `JP` rather
+ * than `日本` or `Japan`, and the same in every language.
+ */
+function getAddressComponentCode(addressEntry, type) {
+    if (!addressEntry || typeof addressEntry !== 'object')
+        return undefined;
+    const components = Array.isArray(addressEntry.address_components)
+        ? addressEntry.address_components
+        : [];
+    for (const component of components) {
+        if (!component || typeof component !== 'object')
+            continue;
+        const types = Array.isArray(component.types) ? component.types : [];
+        if (!types.includes(type))
+            continue;
+        const value = normalizeText(component.short_name);
+        if (value)
+            return value;
+    }
+    return undefined;
+}
 function getAddressComponent(addressEntry, type) {
     if (!addressEntry || typeof addressEntry !== 'object')
         return undefined;

package/dist/index.js

@@ -26,7 +26,7 @@ program
     .name('gyazo')
     .description('Gyazo Memory CLI for AI Secretary')
     .option('--mcp-server', 'run as a Model Context Protocol server over stdio')
-    .version('0.2.0');
+    .version('0.4.0');
 (0, config_1.registerConfigCommand)(program);
 (0, list_1.registerListCommand)(program);
 (0, get_1.registerGetCommand)(program);

package/dist/mcp.js

@@ -20,6 +20,7 @@ const api_1 = require("./api");
 const credentials_1 = require("./credentials");
 const ids_1 = require("./ids");
 const dates_1 = require("./dates");
+const format_1 = require("./format");
 const memory_1 = require("./services/memory");
 const analytics_1 = require("./services/analytics");
 const collections_1 = require("./services/collections");
@@ -35,31 +36,132 @@ function serverVersion() {
     // level below it, so this holds both in the repository and once installed.
     return require('../package.json').version;
 }
+/** null and undefined both mean the capture does not carry the field. */
+function present(value) {
+    return value !== null && value !== undefined;
+}
+/**
+ * Both languages, always. A Japanese address reads poorly for a place abroad,
+ * and an English one reads poorly at home, and which of those applies is not
+ * something this server can decide for the model.
+ */
+const ADDRESS_LOCALES = ['ja', 'en'];
+function readNumber(value) {
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? value : undefined;
+    if (typeof value === 'string' && value.trim() !== '') {
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    return undefined;
+}
+function readAddresses(exifAddress) {
+    const addresses = {};
+    for (const locale of ADDRESS_LOCALES) {
+        const entry = (0, format_1.getAddressEntry)(exifAddress, locale);
+        const text = (0, format_1.normalizeText)(entry?.address);
+        if (!text)
+            continue;
+        const locality = (0, format_1.getAddressComponent)(entry, 'locality');
+        const admin1 = (0, format_1.getAddressComponent)(entry, 'administrative_area_level_1');
+        addresses[locale] = {
+            text,
+            ...(locality ? { locality } : {}),
+            ...(admin1 ? { admin1 } : {}),
+        };
+    }
+    return Object.keys(addresses).length > 0 ? addresses : undefined;
+}
 /**
- * The fields worth handing to a model: enough to cite a capture and to open it,
- * without the parts of the API response it cannot act on. Absent fields stay
- * absent rather than becoming null.
+ * Where a capture was taken, in the fields a model can reason about.
  *
- * Metadata only, on purpose. Handing image bytes to a model as base64 was the
- * ambitious part of the upstream design and it did not hold up in use, so a
- * capture is described here and its URLs are given for anything that wants the
- * pixels.
+ * The coordinates live under `metadata`; the top-level `exif_normalized` is
+ * null in every response this CLI reads, though it is still honoured in case
+ * an endpoint starts filling it. Altitude and heading only exist in the raw
+ * EXIF, which `/api/images/<id>` does not return, so they appear for captures
+ * read through a collection and are absent otherwise rather than guessed.
  */
+function readLocation(image) {
+    const source = image?.metadata?.exif_normalized ?? image?.exif_normalized;
+    const latitude = source?.latitude;
+    const longitude = source?.longitude;
+    if (typeof latitude !== 'number' || typeof longitude !== 'number') {
+        return undefined;
+    }
+    const exif = image?.metadata?.exif;
+    const altitude = readNumber(exif?.['Altitude']);
+    const heading = readNumber(exif?.['GPS Image Direction']);
+    const headingReferenceCode = (0, format_1.normalizeText)(exif?.['GPS Image Direction Reference']);
+    const headingReference = headingReferenceCode === 'M' ? 'magnetic' : headingReferenceCode === 'T' ? 'true' : undefined;
+    const exifAddress = image?.metadata?.exif_address;
+    const addresses = readAddresses(exifAddress);
+    const countryCode = ADDRESS_LOCALES.map((locale) => (0, format_1.getAddressComponentCode)((0, format_1.getAddressEntry)(exifAddress, locale), 'country')).find(present);
+    return {
+        latitude,
+        longitude,
+        ...(altitude !== undefined ? { altitude_m: altitude } : {}),
+        ...(heading !== undefined ? { heading_deg: heading } : {}),
+        ...(heading !== undefined && headingReference ? { heading_reference: headingReference } : {}),
+        ...(countryCode ? { country_code: countryCode } : {}),
+        ...(addresses ? { address: addresses } : {}),
+    };
+}
+/** When the shutter was pressed, as opposed to when the capture was uploaded. */
+function readCapturedAt(image) {
+    const capturedAt = image?.exif_captured_at ?? image?.metadata?.exif_normalized?.time ?? undefined;
+    return present(capturedAt) && typeof capturedAt === 'string' ? capturedAt : undefined;
+}
+/**
+ * The OCR text, from wherever this response carries it. Same mistake as the
+ * coordinates: the responses that have OCR keep it under `metadata`, and the
+ * top-level field comes back null.
+ */
+function readOcr(image) {
+    const ocr = present(image?.ocr) ? image.ocr : image?.metadata?.ocr;
+    return present(ocr) && present(ocr.description) ? ocr : undefined;
+}
 function toMetadata(image) {
+    const location = readLocation(image);
+    const capturedAt = readCapturedAt(image);
+    const ocr = readOcr(image);
     return {
         image_id: image.image_id,
         permalink_url: image.permalink_url,
         url: image.url,
-        ...(image.thumb_url !== undefined ? { thumb_url: image.thumb_url } : {}),
-        ...(image.type !== undefined ? { mimeType: `image/${image.type}` } : {}),
+        ...(present(image.thumb_url) ? { thumb_url: image.thumb_url } : {}),
+        ...(present(image.type) ? { mimeType: `image/${image.type}` } : {}),
         created_at: image.created_at,
-        ...(image.alt_text !== undefined ? { alt_text: image.alt_text } : {}),
-        ...(image.ocr !== undefined ? { ocr: image.ocr } : {}),
-        ...(image.metadata !== undefined ? { metadata: image.metadata } : {}),
-        ...(image.exif_normalized !== undefined ? { exif_normalized: image.exif_normalized } : {}),
+        ...(capturedAt !== undefined ? { captured_at: capturedAt } : {}),
+        ...(present(image.alt_text) && image.alt_text !== '' ? { alt_text: image.alt_text } : {}),
+        ...(ocr !== undefined ? { ocr } : {}),
+        ...(location !== undefined ? { location } : {}),
+        ...(present(image.metadata) ? { metadata: image.metadata } : {}),
     };
 }
 const NO_IMAGES = { content: [{ type: 'text', text: 'No images found' }] };
+/**
+ * Every call, with how long it took, on stderr. stdout belongs to the
+ * protocol, and the host that starts this server is where its stderr ends up,
+ * which is the only place an operator can see that one tool is slow.
+ */
+function logged(name, handler) {
+    return async (args) => {
+        const startedAt = Date.now();
+        const given = Object.entries((args || {}))
+            .filter(([, value]) => value !== undefined && value !== false)
+            .map(([key, value]) => `${key}=${JSON.stringify(value)}`)
+            .join(' ');
+        try {
+            const result = await handler(args);
+            console.error(`[gyazo-mcp] ${name} ok ${Date.now() - startedAt}ms ${given}`.trimEnd());
+            return result;
+        }
+        catch (error) {
+            console.error(`[gyazo-mcp] ${name} failed ${Date.now() - startedAt}ms ${given}`.trimEnd(), `- ${error?.message || error}`);
+            throw error;
+        }
+    };
+}
 function asJsonResult(payload) {
     return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
 }
@@ -108,7 +210,7 @@ function createMcpServer() {
                 .describe('Number of results per page (max: 100)'),
         },
         annotations: { readOnlyHint: true, openWorldHint: true },
-    }, async ({ query, page, per }) => {
+    }, logged('gyazo_search', async ({ query, page, per }) => {
         const images = await (0, api_1.searchImages)(query, page, per);
         if (!images || images.length === 0) {
             return NO_IMAGES;
@@ -121,7 +223,7 @@ function createMcpServer() {
                 },
             ],
         };
-    });
+    }));
     server.registerTool('gyazo_image', {
         title: 'Describe one Gyazo capture',
         description: 'Fetch the metadata of one capture on Gyazo: its URLs, timestamp, OCR text, ' +
@@ -135,7 +237,7 @@ function createMcpServer() {
                 'https://gyazo.com/<id> permalink, or a direct image URL all work.'),
         },
         annotations: { readOnlyHint: true, openWorldHint: true },
-    }, async ({ id_or_url }) => {
+    }, logged('gyazo_image', async ({ id_or_url }) => {
         const imageId = (0, ids_1.normalizeImageId)(id_or_url);
         if (!imageId) {
             throw new Error(`'${id_or_url}' is not a Gyazo image ID or URL. Pass a 32-character ID or a ` +
@@ -147,7 +249,7 @@ function createMcpServer() {
             return NO_IMAGES;
         }
         return asMetadataResult(image);
-    });
+    }));
     server.registerTool('gyazo_latest_image', {
         title: 'Describe the most recent Gyazo capture',
         description: 'Fetch the metadata of the capture the user uploaded most recently. Useful when ' +
@@ -157,14 +259,14 @@ function createMcpServer() {
         // are dropped rather than refused.
         inputSchema: {},
         annotations: { readOnlyHint: true, openWorldHint: true },
-    }, async () => {
+    }, logged('gyazo_latest_image', async () => {
         const images = await (0, api_1.listImages)(1, 1);
         const latest = images && images[0];
         if (!latest) {
             return NO_IMAGES;
         }
         return asMetadataResult(latest);
-    });
+    }));
     server.registerTool('gyazo_list', {
         title: 'List Gyazo captures',
         description: 'List the captures the user uploaded, newest first, taking the same options as ' +
@@ -209,7 +311,7 @@ function createMcpServer() {
                 .describe('Answer from the local cache where possible. Set false to force a fetch'),
         },
         annotations: { readOnlyHint: true, openWorldHint: true },
-    }, async (args) => {
+    }, logged('gyazo_list', async (args) => {
         const { page, limit, today, photos, uploaded, max_pages: maxPages, use_cache: useCache } = args;
         if (photos && uploaded) {
             throw new Error('photos and uploaded cannot be used together.');
@@ -236,7 +338,7 @@ function createMcpServer() {
             alias,
         });
         return asMetadataListResult(images);
-    });
+    }));
     server.registerTool('gyazo_summary', {
         title: 'Summarise a stretch of Gyazo captures',
         description: 'What a day or a range adds up to: how many captures each day, and which ' +
@@ -267,12 +369,12 @@ function createMcpServer() {
                 .describe('Answer from the local cache where possible. Set false to force a fetch'),
         },
         annotations: { readOnlyHint: true, openWorldHint: true },
-    }, async (args) => {
+    }, logged('gyazo_summary', async (args) => {
         const { today, limit, max_pages: maxPages, use_cache: useCache } = args;
         const targetDate = requireDate(args.date, today) || (0, dates_1.buildRecentWeekRangeUntilYesterday)();
         const dailySummaries = await (0, analytics_1.buildSummary)({ targetDate, maxPages, useCache });
         return asJsonResult((0, analytics_1.toSummaryJson)(targetDate.dateKey, dailySummaries, limit));
-    });
+    }));
     server.registerTool('gyazo_collection', {
         title: 'Read a Gyazo collection',
         description: 'The metadata of a collection and of the captures in it. A collection ID looks ' +
@@ -288,30 +390,223 @@ function createMcpServer() {
                 .default('added')
                 .describe('Image order: added (as the collection holds them), created (upload time) or ' +
                 'captured (when the photo was taken)'),
+            page: zod_1.z.number().int().min(1).default(1).describe('Page of images to read'),
+            per: zod_1.z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .default(100)
+                .describe('Images per page (max: 100)'),
         },
         annotations: { readOnlyHint: true, openWorldHint: true },
-    }, async ({ id_or_url, sort }) => {
+    }, logged('gyazo_collection', async ({ id_or_url, sort, page, per }) => {
         const collectionId = (0, ids_1.normalizeCollectionId)(id_or_url);
         if (!collectionId) {
             throw new Error(`'${id_or_url}' is not a Gyazo collection ID or URL. Pass a 32-character ID or a ` +
                 'https://gyazo.com/collections/<id> URL. A https://gyazo.com/<id> URL is a single ' +
                 'capture, which gyazo_image reads.');
         }
-        const { collection, images } = await (0, collections_1.readCollection)(collectionId, {
+        const result = await (0, collections_1.readCollection)(collectionId, {
             sort: sort,
+            paginated: true,
+            page,
+            per,
         });
+        const { collection, images } = result;
         return asJsonResult({
             id: collection?.id ?? collectionId,
-            ...(collection?.name !== undefined ? { name: collection.name } : {}),
+            ...(present(collection?.name) ? { name: collection.name } : {}),
             ...(collection?.description ? { description: collection.description } : {}),
-            ...(collection?.url !== undefined ? { url: collection.url } : {}),
-            ...(collection?.total_image_count !== undefined
-                ? { total_image_count: collection.total_image_count }
+            ...(present(collection?.url) ? { url: collection.url } : {}),
+            ...(result.totalImageCount !== undefined
+                ? { total_image_count: result.totalImageCount }
                 : {}),
-            ...(collection?.user !== undefined ? { user: collection.user } : {}),
+            returned_image_count: result.returnedImageCount,
+            page: result.page,
+            per: result.per,
+            // Said out loud, because a collection that stops without saying so
+            // reads as a complete answer. Ask for the next page to see the rest.
+            truncated: result.truncated,
+            ...(present(collection?.user) ? { user: collection.user } : {}),
             images: images.map(toMetadata),
         });
-    });
+    }));
+    server.registerTool('gyazo_recent', {
+        title: 'What the user captured recently',
+        description: 'The captures that arrived since a moment, or since a capture you have already ' +
+            'seen. Use this when the user says they just captured something, and pass ' +
+            'after_image_id with the newest capture you have already looked at so that you ' +
+            'get only what is new. With no arguments it covers the last 30 minutes.',
+        inputSchema: {
+            minutes: zod_1.z
+                .number()
+                .int()
+                .min(1)
+                .max(1440)
+                .optional()
+                .describe('How far back to look, in minutes. Defaults to 30 when nothing else is given'),
+            since: zod_1.z
+                .string()
+                .optional()
+                .describe('An ISO 8601 timestamp to look back to, instead of minutes'),
+            after_image_id: zod_1.z
+                .string()
+                .optional()
+                .describe('The newest capture you have already seen, as an ID or a Gyazo URL. Returns ' +
+                'only what came after it, and reports if it cannot be found'),
+            limit: zod_1.z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .default(20)
+                .describe('Most captures to return (max: 100)'),
+            max_pages: zod_1.z
+                .number()
+                .int()
+                .min(1)
+                .max(20)
+                .default(5)
+                .describe('How many pages of 100 to walk before giving up on the boundary'),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, logged('gyazo_recent', async (args) => {
+        const { limit, max_pages: maxPages } = args;
+        let afterImageId;
+        if (args.after_image_id) {
+            const normalized = (0, ids_1.normalizeImageId)(args.after_image_id);
+            if (!normalized) {
+                throw new Error(`'${args.after_image_id}' is not a Gyazo image ID or URL. Pass the ID of the ` +
+                    'newest capture you have already seen.');
+            }
+            afterImageId = normalized;
+        }
+        let since;
+        if (args.since) {
+            if (args.minutes !== undefined) {
+                throw new Error('since and minutes cannot be used together.');
+            }
+            const parsed = new Date(args.since);
+            if (Number.isNaN(parsed.getTime())) {
+                throw new Error(`'${args.since}' is not a timestamp this can read. Pass an ISO 8601 value such ` +
+                    'as 2026-09-08T11:42:00+09:00.');
+            }
+            since = parsed;
+        }
+        else if (args.minutes !== undefined) {
+            since = new Date(Date.now() - args.minutes * 60_000);
+        }
+        else if (!afterImageId) {
+            since = new Date(Date.now() - 30 * 60_000);
+        }
+        const result = await (0, memory_1.listCapturesSince)({ since, afterImageId, limit, maxPages });
+        if (result.watermarkMissing) {
+            throw new Error(`after_image_id ${afterImageId} was not found in the ${result.pagesWalked} most ` +
+                'recent pages of captures. It may be older than that, or belong to another ' +
+                'account. Ask for a window in minutes instead, or raise max_pages.');
+        }
+        return asMetadataListResult(result.images);
+    }));
+    server.registerTool('gyazo_collections', {
+        title: 'Find a Gyazo collection by name',
+        description: 'The collections the user has, with their IDs and how many captures each holds. ' +
+            'Use this to turn a collection the user names out loud into the ID that ' +
+            'gyazo_collection needs.',
+        inputSchema: {
+            query: zod_1.z
+                .string()
+                .optional()
+                .describe('Part of a collection name to match, case-insensitively. Omit for all of them'),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, logged('gyazo_collections', async ({ query }) => {
+        const collections = await (0, collections_1.findCollections)(query);
+        if (collections.length === 0) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: query
+                            ? `No collections match ${JSON.stringify(query)}.`
+                            : 'No collections found.',
+                    },
+                ],
+            };
+        }
+        return asJsonResult(collections.map((collection) => ({
+            id: collection.id,
+            ...(present(collection.name) ? { name: collection.name } : {}),
+            ...(collection.description ? { description: collection.description } : {}),
+            ...(present(collection.total_image_count)
+                ? { total_image_count: collection.total_image_count }
+                : {}),
+            ...(present(collection.url) ? { url: collection.url } : {}),
+            ...(present(collection.list_updated_at)
+                ? { list_updated_at: collection.list_updated_at }
+                : {}),
+        })));
+    }));
+    server.registerTool('gyazo_image_content', {
+        title: 'Look at a Gyazo capture',
+        description: 'The pixels of one capture, as image content you can actually look at. Use it ' +
+            'after gyazo_recent or gyazo_image when the metadata is not enough and you need ' +
+            'to see what the user is looking at: a sign, a menu, a building. Returns a ' +
+            'width-limited rendition rather than the original, which is usually several ' +
+            'megabytes. One capture at a time: for a set, read the metadata first and ask ' +
+            'for the ones that matter.',
+        inputSchema: {
+            id_or_url: zod_1.z
+                .string()
+                .min(1)
+                .describe('ID or URL of the capture on Gyazo'),
+            width: zod_1.z
+                .number()
+                .int()
+                .min(64)
+                .max(2000)
+                .default(1024)
+                .describe('Width in pixels. 1024 is legible for signs and menus; 512 is cheaper'),
+            format: zod_1.z
+                .enum(['webp', 'jpeg'])
+                .default('webp')
+                .describe('webp is about a third the size of jpeg for the same width'),
+            max_bytes: zod_1.z
+                .number()
+                .int()
+                .min(10_000)
+                .max(4_000_000)
+                .default(750_000)
+                .describe('Refuse rather than return anything larger than this'),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, logged('gyazo_image_content', async ({ id_or_url, width, format, max_bytes: maxBytes }) => {
+        const imageId = (0, ids_1.normalizeImageId)(id_or_url);
+        if (!imageId) {
+            throw new Error(`'${id_or_url}' is not a Gyazo image ID or URL. Pass a 32-character ID or a ` +
+                'https://gyazo.com/<id> URL.');
+        }
+        const rendition = await (0, api_1.fetchImageRendition)(imageId, width, format);
+        if (rendition.bytes > maxBytes) {
+            throw new Error(`The ${width}px ${format} rendition of ${imageId} is ${rendition.bytes} bytes, over ` +
+                `the max_bytes limit of ${maxBytes}. Ask for a smaller width, or raise max_bytes. ` +
+                `The rendition is at ${rendition.url}.`);
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `${imageId} at ${rendition.width}px wide, ${rendition.bytes} bytes as ` +
+                        `${rendition.mimeType}. This is a resized rendition, not the original.`,
+                },
+                {
+                    type: 'image',
+                    data: rendition.data.toString('base64'),
+                    mimeType: rendition.mimeType,
+                },
+            ],
+        };
+    }));
     return server;
 }
 async function runMcpServer() {

package/dist/services/collections.js

@@ -7,6 +7,7 @@ exports.collectionSortKey = collectionSortKey;
 exports.sortCollectionImages = sortCollectionImages;
 exports.printCollectionMarkdown = printCollectionMarkdown;
 exports.readCollection = readCollection;
+exports.findCollections = findCollections;
 /**
  * Collections. A collection ID is indistinguishable from an image ID, so the
  * only unambiguous way in is the URL form, which is why the check here is
@@ -14,6 +15,7 @@ exports.readCollection = readCollection;
  * edits collections.
  */
 const api_1 = require("../api");
+const credentials_1 = require("../credentials");
 const ids_1 = require("../ids");
 const format_1 = require("../format");
 const images_1 = require("./images");
@@ -84,14 +86,57 @@ function printCollectionMarkdown(collection, images) {
         (0, images_1.printListImages)(images);
     }
 }
-/**
- * A collection and its images in the requested order. The API returns the
- * images in the order they were added, which is the default here too.
- */
 async function readCollection(collectionId, options = {}) {
+    const sort = options.sort || 'added';
+    const page = options.page && options.page > 0 ? options.page : 1;
+    const per = options.per && options.per > 0 ? Math.min(options.per, 100) : 100;
+    const useApi = Boolean(options.paginated) && !options.anonymous && Boolean((0, credentials_1.resolveAccessToken)());
+    if (useApi) {
+        const [collection, images] = await Promise.all([
+            (0, api_1.getCollectionDetail)(collectionId),
+            (0, api_1.listCollectionImages)(collectionId, page, per),
+        ]);
+        const total = collection?.total_image_count;
+        const sorted = sortCollectionImages(images, sort);
+        return {
+            collection,
+            images: sorted,
+            page,
+            per,
+            returnedImageCount: sorted.length,
+            totalImageCount: typeof total === 'number' ? total : undefined,
+            truncated: typeof total === 'number' ? page * per < total : false,
+            source: 'api',
+        };
+    }
+    // Only --anonymous drops the token here: a private collection of your own
+    // reads fine through the web endpoint with it.
     const collection = await (0, api_1.getCollection)(collectionId, {
         anonymous: Boolean(options.anonymous),
     });
-    const images = sortCollectionImages(Array.isArray(collection?.images) ? collection.images : [], options.sort || 'added');
-    return { collection, images };
+    const images = sortCollectionImages(Array.isArray(collection?.images) ? collection.images : [], sort);
+    const total = collection?.total_image_count;
+    return {
+        collection,
+        images,
+        page: 1,
+        per: images.length,
+        returnedImageCount: images.length,
+        totalImageCount: typeof total === 'number' ? total : undefined,
+        truncated: typeof total === 'number' ? images.length < total : false,
+        source: 'web',
+    };
+}
+/**
+ * Collections whose name contains the query, or all of them when there is no
+ * query. Matching is case-insensitive and ignores surrounding whitespace,
+ * because a name people say out loud rarely matches one stored with emoji and
+ * padding.
+ */
+async function findCollections(query) {
+    const collections = await (0, api_1.listCollections)();
+    const needle = (0, format_1.normalizeText)(query)?.toLowerCase();
+    if (!needle)
+        return collections;
+    return collections.filter((collection) => (collection.name || '').toLowerCase().includes(needle));
 }

package/dist/services/memory.js

@@ -14,6 +14,7 @@ exports.cacheSearchResultImages = cacheSearchResultImages;
 exports.supplementAltTextFromSearchCache = supplementAltTextFromSearchCache;
 exports.supplementAltTextForDisplay = supplementAltTextForDisplay;
 exports.listCaptures = listCaptures;
+exports.listCapturesSince = listCapturesSince;
 /**
  * The memory this CLI keeps: the local cache of captures, and the walks over
  * the Gyazo API that fill it. A command asks for a day or a range, and this
@@ -371,3 +372,46 @@ async function listCaptures(options) {
     }
     return { images: await (0, api_1.listImages)(pageNumber, limit) };
 }
+/**
+ * What arrived since a moment, or since a capture. The listing comes back
+ * newest first, so the walk stops at the first capture that is older than the
+ * boundary rather than reading to the end.
+ *
+ * A watermark that never turns up is reported, not papered over: returning
+ * everything walked would read as "all of this is new", which is the wrong
+ * answer told confidently.
+ */
+async function listCapturesSince(options) {
+    const { since, afterImageId, limit, maxPages } = options;
+    const collected = [];
+    let pagesWalked = 0;
+    let reachedBoundary = false;
+    for (let page = 1; page <= maxPages && !reachedBoundary; page++) {
+        const images = await (0, api_1.listImages)(page, 100);
+        pagesWalked = page;
+        if (images.length === 0)
+            break;
+        for (const image of images) {
+            if (afterImageId && image.image_id === afterImageId) {
+                reachedBoundary = true;
+                break;
+            }
+            if (since) {
+                const createdAt = new Date(image.created_at);
+                if (Number.isNaN(createdAt.getTime()))
+                    continue;
+                if (createdAt < since) {
+                    reachedBoundary = true;
+                    break;
+                }
+            }
+            collected.push(image);
+        }
+        if (images.length < 100)
+            break;
+    }
+    if (afterImageId && !reachedBoundary) {
+        return { images: [], pagesWalked, watermarkMissing: true };
+    }
+    return { images: collected.slice(0, limit), pagesWalked };
+}

package/docs/ADR/003-cli-structure.md

@@ -13,7 +13,7 @@ Adopt and document the existing top-level command structure.
 
 ### 1. Program Metadata
 - Binary name: `gyazo`
-- Version: `0.2.0`
+- Version: `0.4.0`
 - Description: `Gyazo Memory CLI for AI Secretary`
 
 ### 2. Commands

package/docs/ADR/004-mcp-server.md

@@ -2,9 +2,10 @@
 
 ## Status
 
-Accepted. `gyazo_search`, `gyazo_image`, `gyazo_latest_image`, `gyazo_list`,
-`gyazo_summary` and `gyazo_collection` implemented, all read-only and all
-metadata only. `gyazo_upload` deliberately not.
+Accepted. Nine tools, all read-only: `gyazo_search`, `gyazo_image`,
+`gyazo_image_content`, `gyazo_latest_image`, `gyazo_list`, `gyazo_recent`,
+`gyazo_summary`, `gyazo_collection`, `gyazo_collections`. `gyazo_upload`
+deliberately not.
 
 ## Context
 
@@ -45,6 +46,28 @@ So every tool here returns metadata and URLs, and none returns pixels. A
 client that wants to show a capture opens the URL in the result. This also
 drops sharp from the dependency list entirely.
 
+## Pixels, after all, for one capture at a time
+
+Metadata-only held for lists and searches and turned out to be too strict for
+a single capture. The use case that matters is a person walking somewhere
+unfamiliar saying "look at this": GPS and OCR give the place and the letters,
+not what they are looking at.
+
+`gyazo_image_content` is a separate tool rather than a flag on `gyazo_image`,
+so a call that only wants metadata cannot come back with a megabyte. It
+returns a width-limited rendition from Gyazo's own resize route, which needs
+no credentials, so there is still no image library here. 1024px is about 130 KB
+as webp. Over `max_bytes` it refuses and says what to change, rather than
+sending something the host will drop.
+
+## Differential retrieval
+
+Four captures in a row, then "look at what I just captured", is not a question
+`gyazo_latest_image` can answer. `gyazo_recent` takes a window in minutes, an
+explicit `since`, or `after_image_id` as a watermark, and returns what came
+after. A watermark that cannot be found is reported: returning everything
+walked would read as "all of this is new".
+
 ## Read-only by construction
 
 `gyazo_upload` is not implemented and no other tool writes. There is no need
@@ -74,7 +97,13 @@ exiting ones are now thin wrappers over them.
 
 - The result payload is the fields a model can act on: `image_id`,
   `permalink_url`, `url`, `thumb_url`, `mimeType`, `created_at`, `alt_text`,
-  `ocr`, `metadata`, `exif_normalized`. Absent fields stay absent.
+  `ocr`, `location`, `metadata`. Absent fields stay absent, and a null field
+  counts as absent.
+- `location` and `ocr` are read from under `metadata`, which is where Gyazo
+  puts them. The top-level `exif_normalized` and `ocr` are null in every
+  response this CLI receives, and reading those was why coordinates never
+  appeared in any payload. Fixtures written from the shape the code expected
+  hid it; they now come from real responses.
 - No `uri` field, unlike upstream: it points at an MCP resource, and this
   server does not serve resources yet.
 - `gyazo_latest_image` takes no arguments, while upstream declared a `name`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yuiseki/gyazocli",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Gyazo Memory CLI for AI Secretary",
   "repository": {
     "type": "git",