@yuiseki/gyazocli 0.4.0 → 0.5.1

package/README.md

@@ -114,12 +114,44 @@ 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 |
+| --- | --- |
+| `has:exif` | photographs rather than screenshots |
+| `has:location` | captures with coordinates |
+| `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 |
+| `since:2026-08-30 until:2026-08-31` | the upload date |
+| `-address:広島` | negation |
+| `OR` | alternation; terms are ANDed otherwise |
+
+To narrow to photographs, reach for `has:exif`. The application does not tell
+them apart: `app:"Gyazo Android"` includes screenshots and screen recordings
+from the same phone, and one page of `app:"Gyazo Android" -has:exif` came back
+as 68 gif and 30 png against 2 jpg.
+
+`has:exif` and `has:location` overlap without either containing the other. A
+photo taken indoors has EXIF and no coordinates; 86 captures here carry
+coordinates without the EXIF flag. `has:exif OR has:location` is the widest
+reading of "a photo".
+
+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.

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.4.0');
+    .version('0.5.1');
 (0, config_1.registerConfigCommand)(program);
 (0, list_1.registerListCommand)(program);
 (0, get_1.registerGetCommand)(program);

package/dist/mcp.js

@@ -24,12 +24,36 @@ 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. Terms are ANDed; OR in capitals is honoured, and a leading - negates.',
+    'To narrow to photographs rather than screenshots, use has:exif. The application is',
+    'not the distinction: app:"Gyazo Android" includes screenshots and screen recordings',
+    'from the same phone, and of one such page 68 were gif and 30 png against 2 jpg.',
+    'has:location narrows to captures with coordinates. It is not a subset of has:exif',
+    'and does not contain it either: a photo taken indoors has EXIF and no coordinates,',
+    'and some photos carry coordinates without the EXIF flag, so has:exif OR has:location',
+    'is the widest reading of "a photo".',
+    'address: matches the reverse-geocoded address of a capture with GPS, in any language',
+    'and case, and matches postal codes too, so address:広島 and address:Hiroshima and',
+    'address:730-0041 all find the same photos.',
+    'Also: app: the application it came from; title:, url: and desc: the page it was',
+    'captured from; ocr: the text in the image; type: the file type, as type:png; since:',
+    'and until: bound the upload date, as since:2026-08-30 until:2026-08-31. 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.',
+    'An operator Gyazo does not know returns nothing rather than matching as text, so an',
+    'invented operator looks exactly like "no such captures". If nothing suitable comes',
+    'back, rephrase the query rather than giving up on the first attempt.',
 ].join(' ');
 function serverVersion() {
     // The published tarball always contains package.json, and dist/ sits one
@@ -165,6 +189,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;
@@ -208,21 +241,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',
@@ -309,6 +336,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) => {
@@ -337,7 +365,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',
@@ -469,6 +497,7 @@ function createMcpServer() {
                 .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) => {
@@ -506,7 +535,7 @@ function createMcpServer() {
                 '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);
+        return asMetadataListResult(await withLocations(result.images, args.include_location));
     }));
     server.registerTool('gyazo_collections', {
         title: 'Find a Gyazo collection by name',

package/dist/services/memory.js

@@ -15,6 +15,7 @@ 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
@@ -415,3 +416,48 @@ async function listCapturesSince(options) {
     }
     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.4.0`
+- Version: `0.5.1`
 - Description: `Gyazo Memory CLI for AI Secretary`
 
 ### 2. Commands

package/package.json

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