@yuiseki/gyazocli 0.3.0 → 0.5.0

package/README.md

@@ -114,12 +114,33 @@ Configured in a client:
 }
 ```
 
+### Query syntax
+
+Bare words match the OCR text, title and description. These operators were
+checked against the live API, each with a value that should match, reading the
+results back from the detail endpoint to confirm the filter had applied:
+
+| Operator | Matches |
+| --- | --- |
+| `address:広島`, `address:Hiroshima`, `address:730-0041` | the reverse-geocoded address of a capture with GPS, in any language or case, postal codes included |
+| `app:"Gyazo Android"` | the application the capture came from |
+| `title:`, `url:`, `desc:` | the page it was captured from |
+| `ocr:` | the text in the image |
+| `type:png` | the file type |
+| `has:location` | only captures with coordinates |
+| `has:exif` | only captures with EXIF, which is not the same thing |
+| `since:2026-08-30 until:2026-08-31` | the upload date |
+| `-address:広島` | negation |
+
+There is no coordinate or radius search. `location:`, `geo:`, `near:`,
+`bbox:`, `city:`, `lat:` and the like all return nothing, exactly as an
+invented operator does, so search by place with `address:`.
+
 ### Tools
 
 - `gyazo_search`: full-text search over your captures. Arguments: `query`
   (required, up to 200 characters), `page` (default 1), `per` (default 20,
-  max 100). Search syntax is the same as Gyazo's: `cat`, `title:cat`,
-  `app:"Google Chrome"`, `url:google.com`, `cat since:2024-01-01 until:2024-12-31`.
+  max 100), `include_location`. See the query syntax below.
 - `gyazo_image`: metadata for one capture. Argument: `id_or_url` (required),
   which accepts a bare 32-character ID, a `https://gyazo.com/<id>` permalink or
   a direct image URL.
@@ -131,15 +152,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. A capture that carries coordinates gets a `location: {latitude,
-longitude}`, and OCR text is reported wherever the response carries it: 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.3.0');
+    .version('0.5.0');
 (0, config_1.registerConfigCommand)(program);
 (0, list_1.registerListCommand)(program);
 (0, get_1.registerGetCommand)(program);

package/dist/mcp.js

@@ -20,15 +20,34 @@ 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");
+/**
+ * The operators below were checked against the live API rather than taken from
+ * documentation: each one was run with a value that should match, and the
+ * results were read back from the detail endpoint to confirm the filter had
+ * actually applied. An operator Gyazo does not know returns nothing at all
+ * rather than falling back to a text search, so an untested guess costs the
+ * model a turn.
+ */
 const SEARCH_QUERY_DESCRIPTION = [
-    'Search keyword (max length: 200 characters).',
-    'Examples: cat | title:cat | app:"Google Chrome" | url:google.com |',
-    'cat since:2024-01-01 until:2024-12-31.',
-    'If nothing suitable comes back, rephrase the query to match what the user',
-    'meant and search again rather than giving up on the first attempt.',
+    'Search keyword, up to 200 characters. Bare words match the OCR text, title and',
+    'description.',
+    'Operators, all confirmed to work: address: matches the reverse-geocoded address of',
+    'a capture with GPS, in any language and case, and also matches postal codes, so',
+    'address:広島 and address:Hiroshima and address:730-0041 all find the same photos;',
+    'app: the application it came from, as app:"Gyazo Android"; title:, url: and desc:',
+    'the page it was captured from; ocr: the text in the image; type: the file type, as',
+    'type:png; has:location only captures with coordinates; has:exif only captures with',
+    'EXIF, which is not the same thing; since: and until: bound the upload date, as',
+    'since:2026-08-30 until:2026-08-31. A leading - negates, as -address:広島. Quote a',
+    'value that contains spaces.',
+    'There is no coordinate or radius search: location:, geo:, near:, bbox:, city: and',
+    'the like all return nothing. To search by place, use address: with a place name.',
+    'If nothing suitable comes back, rephrase the query to match what the user meant and',
+    'search again rather than giving up on the first attempt.',
 ].join(' ');
 function serverVersion() {
     // The published tarball always contains package.json, and dist/ sits one
@@ -40,10 +59,45 @@ function present(value) {
     return value !== null && value !== undefined;
 }
 /**
- * Where a capture was taken. This lives under `metadata`, and the top-level
- * `exif_normalized` is null in every response this CLI reads, which is why
- * coordinates were missing from all of the tool output until now. The
- * top-level shape is still read, in case an endpoint starts filling it.
+ * 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;
+}
+/**
+ * Where a capture was taken, in the fields a model can reason about.
+ *
+ * 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;
@@ -52,7 +106,28 @@ function readLocation(image) {
     if (typeof latitude !== 'number' || typeof longitude !== 'number') {
         return undefined;
     }
-    return { latitude, longitude };
+    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
@@ -65,6 +140,7 @@ function readOcr(image) {
 }
 function toMetadata(image) {
     const location = readLocation(image);
+    const capturedAt = readCapturedAt(image);
     const ocr = readOcr(image);
     return {
         image_id: image.image_id,
@@ -73,6 +149,7 @@ function toMetadata(image) {
         ...(present(image.thumb_url) ? { thumb_url: image.thumb_url } : {}),
         ...(present(image.type) ? { mimeType: `image/${image.type}` } : {}),
         created_at: image.created_at,
+        ...(capturedAt !== undefined ? { captured_at: capturedAt } : {}),
         ...(present(image.alt_text) && image.alt_text !== '' ? { alt_text: image.alt_text } : {}),
         ...(ocr !== undefined ? { ocr } : {}),
         ...(location !== undefined ? { location } : {}),
@@ -106,6 +183,15 @@ function logged(name, handler) {
 function asJsonResult(payload) {
     return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
 }
+const INCLUDE_LOCATION = zod_1.z
+    .boolean()
+    .default(true)
+    .describe('Fill in the location, which the listing and search endpoints leave out. Costs one ' +
+    'extra lookup per capture the local cache does not already hold. Set false when the ' +
+    'coordinates do not matter');
+async function withLocations(images, includeLocation) {
+    return includeLocation ? (0, memory_1.enrichImageLocations)(images) : images;
+}
 function asMetadataListResult(images) {
     if (!images || images.length === 0) {
         return NO_IMAGES;
@@ -149,21 +235,15 @@ function createMcpServer() {
                 .max(100)
                 .default(20)
                 .describe('Number of results per page (max: 100)'),
+            include_location: INCLUDE_LOCATION,
         },
         annotations: { readOnlyHint: true, openWorldHint: true },
-    }, logged('gyazo_search', async ({ query, page, per }) => {
+    }, logged('gyazo_search', async ({ query, page, per, include_location: includeLocation }) => {
         const images = await (0, api_1.searchImages)(query, page, per);
         if (!images || images.length === 0) {
             return NO_IMAGES;
         }
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: JSON.stringify(images.map(toMetadata), null, 2),
-                },
-            ],
-        };
+        return asMetadataListResult(await withLocations(images, includeLocation));
     }));
     server.registerTool('gyazo_image', {
         title: 'Describe one Gyazo capture',
@@ -250,6 +330,7 @@ function createMcpServer() {
                 .boolean()
                 .default(true)
                 .describe('Answer from the local cache where possible. Set false to force a fetch'),
+            include_location: INCLUDE_LOCATION,
         },
         annotations: { readOnlyHint: true, openWorldHint: true },
     }, logged('gyazo_list', async (args) => {
@@ -278,7 +359,7 @@ function createMcpServer() {
             hour: hour || undefined,
             alias,
         });
-        return asMetadataListResult(images);
+        return asMetadataListResult(await withLocations(images, args.include_location));
     }));
     server.registerTool('gyazo_summary', {
         title: 'Summarise a stretch of Gyazo captures',
@@ -331,30 +412,224 @@ 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 },
-    }, logged('gyazo_collection', 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'),
+            include_location: INCLUDE_LOCATION,
+        },
+        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(await withLocations(result.images, args.include_location));
+    }));
+    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,8 @@ exports.cacheSearchResultImages = cacheSearchResultImages;
 exports.supplementAltTextFromSearchCache = supplementAltTextFromSearchCache;
 exports.supplementAltTextForDisplay = supplementAltTextForDisplay;
 exports.listCaptures = listCaptures;
+exports.listCapturesSince = listCapturesSince;
+exports.enrichImageLocations = enrichImageLocations;
 /**
  * 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 +373,91 @@ 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 };
+}
+/**
+ * Fill in what the lean endpoints leave out.
+ *
+ * The listing and the search endpoints return an image without its
+ * coordinates or its address, whatever the capture actually carries; only the
+ * detail endpoint has them. So a caller that needs a location has to ask again
+ * per image, which is what this does: the cache first, the API for the rest,
+ * a few at a time, writing what it fetches back to the cache so the next look
+ * is free.
+ */
+async function enrichImageLocations(images, options = {}) {
+    const useCache = options.useCache !== false;
+    const limit = options.limit ?? 40;
+    const concurrency = Math.max(1, options.concurrency ?? 5);
+    const enriched = [...images];
+    const pending = [];
+    for (let index = 0; index < enriched.length && pending.length < limit; index++) {
+        const image = enriched[index];
+        if (image?.metadata?.exif_normalized || image?.metadata?.exif_address)
+            continue;
+        if (useCache) {
+            const cached = (0, storage_1.loadImageCache)(image?.image_id);
+            if (cached) {
+                enriched[index] = (0, format_1.mergeImageForDisplay)(image, cached);
+                continue;
+            }
+        }
+        pending.push(index);
+    }
+    for (let start = 0; start < pending.length; start += concurrency) {
+        const batch = pending.slice(start, start + concurrency);
+        await Promise.all(batch.map(async (index) => {
+            const image = enriched[index];
+            try {
+                const detail = await (0, api_1.getImageDetail)(image.image_id);
+                (0, storage_1.saveImageCache)(image.image_id, detail);
+                enriched[index] = (0, format_1.mergeImageForDisplay)(image, detail);
+            }
+            catch (_error) {
+                // A capture that cannot be fetched keeps what the listing said.
+            }
+        }));
+    }
+    return enriched;
+}

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.3.0`
+- Version: `0.5.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

package/package.json

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