@yuiseki/gyazocli 0.0.2 → 0.2.0

package/dist/services/images.js

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UPLOAD_DESC_TAG = void 0;
+exports.requireImageId = requireImageId;
+exports.printGetMarkdown = printGetMarkdown;
+exports.summarizeImageForList = summarizeImageForList;
+exports.prepareImagesForDisplay = prepareImagesForDisplay;
+exports.enrichImagesForLocationDisplay = enrichImagesForLocationDisplay;
+exports.printListImages = printListImages;
+exports.ensureUploadDescTag = ensureUploadDescTag;
+exports.readStdinBuffer = readStdinBuffer;
+/**
+ * Showing captures to a person: one line each for a list, a markdown block for
+ * a single capture, and the enrichment that has to happen first. A search
+ * result carries less than an image detail does, so a location worth printing
+ * sometimes means fetching the detail before printing anything.
+ */
+const api_1 = require("../api");
+const storage_1 = require("../storage");
+const ids_1 = require("../ids");
+const format_1 = require("../format");
+const memory_1 = require("./memory");
+function requireImageId(input) {
+    const imageId = (0, ids_1.normalizeImageId)(input);
+    if (!imageId) {
+        console.error(`Error: '${input}' is not a Gyazo image ID or URL.`);
+        if ((0, ids_1.normalizeCollectionId)(input)) {
+            console.error(`Hint: that looks like a collection. Try \`gyazo collection ${input}\`.`);
+        }
+        else {
+            console.error('Hint: pass a 32-character image ID or a https://gyazo.com/<id> URL.');
+        }
+        process.exit(1);
+    }
+    return imageId;
+}
+function printGetMarkdown(image, ocrDescription, objects = []) {
+    const lines = [];
+    lines.push('## Gyazo Image');
+    lines.push('');
+    lines.push(`- URL: <${image.permalink_url}>`);
+    lines.push(`- Created at: ${(0, format_1.formatCreatedAt)(image.created_at)}`);
+    const title = (0, format_1.normalizeText)(image.metadata?.title);
+    if (title)
+        lines.push(`- Title: ${title}`);
+    const address = (0, format_1.extractImageAddressText)(image);
+    if (address)
+        lines.push(`- Address: ${address}`);
+    const altText = (0, format_1.normalizeText)(image.alt_text);
+    if (altText)
+        lines.push(`- Alt text: ${altText}`);
+    if (objects.length > 0) {
+        lines.push('');
+        lines.push('### Objects');
+        for (const object of objects) {
+            lines.push(`- ${(0, format_1.formatObjectAnnotationLine)(object)}`);
+        }
+    }
+    if (ocrDescription) {
+        const preview = (0, format_1.buildOcrPreview)(ocrDescription, 5);
+        lines.push('');
+        lines.push('### OCR');
+        lines.push('```text');
+        lines.push(preview.text);
+        lines.push('```');
+        if (preview.truncated) {
+            lines.push('');
+            lines.push(`> Truncated to first 5 lines. Use \`gyazo get --ocr ${image.image_id}\` for full text.`);
+        }
+    }
+    console.log(lines.join('\n'));
+}
+function summarizeImageForList(img) {
+    const domain = (0, format_1.extractDomain)((0, format_1.normalizeText)(img.metadata?.url));
+    const cleanedTitle = (0, format_1.sanitizeSummaryText)(img.metadata?.title, domain);
+    const cleanedDesc = (0, format_1.sanitizeSummaryText)(img.metadata?.desc ?? img.desc, domain);
+    const locationLabel = (0, format_1.sanitizeSummaryText)((0, format_1.extractImageLocationLabel)(img));
+    const cleanedAltText = (0, format_1.sanitizeSummaryText)(img.alt_text);
+    let main = '(no title/description)';
+    if (cleanedTitle && cleanedDesc) {
+        main = `${cleanedTitle} | ${cleanedDesc}`;
+    }
+    else if (cleanedTitle) {
+        main = cleanedTitle;
+    }
+    else if (cleanedDesc) {
+        main = cleanedDesc;
+    }
+    if (cleanedAltText) {
+        if (main === '(no title/description)') {
+            main = cleanedAltText;
+        }
+        else if (cleanedAltText !== main) {
+            main = `${main} | alt: ${cleanedAltText}`;
+        }
+    }
+    const prefixes = [];
+    if (domain)
+        prefixes.push(`[${domain}]`);
+    if (locationLabel)
+        prefixes.push(`[${locationLabel}]`);
+    if (main === '(no title/description)') {
+        if (prefixes.length > 0)
+            return prefixes.join(' ');
+        return main;
+    }
+    if (prefixes.length > 0) {
+        return `${prefixes.join(' ')} ${main}`;
+    }
+    return main;
+}
+async function prepareImagesForDisplay(images, options = {}) {
+    const useCache = options.useCache !== false;
+    if (options.cacheSearchResults) {
+        (0, memory_1.cacheSearchResultImages)(images);
+    }
+    let prepared = images;
+    if (options.enrichLocation) {
+        prepared = await enrichImagesForLocationDisplay(prepared, useCache);
+    }
+    prepared = (0, memory_1.supplementAltTextForDisplay)(prepared, useCache);
+    return prepared;
+}
+async function enrichImagesForLocationDisplay(images, useCache = true) {
+    const enriched = [];
+    for (const img of images) {
+        let current = img;
+        if (!(0, format_1.shouldEnrichForLocationDisplay)(current)) {
+            enriched.push(current);
+            continue;
+        }
+        if (useCache) {
+            const cached = (0, storage_1.loadImageCache)(img.image_id);
+            if (cached) {
+                current = (0, format_1.mergeImageForDisplay)(current, cached);
+            }
+        }
+        if (!(0, format_1.shouldEnrichForLocationDisplay)(current)) {
+            enriched.push(current);
+            continue;
+        }
+        try {
+            const detail = await (0, api_1.getImageDetail)(img.image_id);
+            (0, storage_1.saveImageCache)(img.image_id, detail);
+            current = (0, format_1.mergeImageForDisplay)(current, detail);
+        }
+        catch (_error) {
+            // Keep current data when detail fetch fails.
+        }
+        enriched.push(current);
+    }
+    return enriched;
+}
+function printListImages(images) {
+    images.forEach(img => {
+        const summary = (0, format_1.truncateText)(summarizeImageForList(img), 120);
+        const created = (0, format_1.formatCreatedAt)(img.created_at);
+        const shortId = (0, format_1.shortenImageId)(img.image_id);
+        const imageUrl = img.permalink_url || `https://gyazo.com/${img.image_id}`;
+        const linkedId = (0, format_1.formatTerminalLink)(shortId, imageUrl);
+        console.log(`- [${created}] ${summary} (id: ${linkedId})`);
+    });
+}
+exports.UPLOAD_DESC_TAG = '#gyazocli_uploads';
+function ensureUploadDescTag(desc) {
+    const normalized = (0, format_1.normalizeText)(desc);
+    if (!normalized)
+        return exports.UPLOAD_DESC_TAG;
+    const words = normalized
+        .split(' ')
+        .filter(word => word.toLowerCase() !== exports.UPLOAD_DESC_TAG.toLowerCase());
+    words.push(exports.UPLOAD_DESC_TAG);
+    return words.join(' ').trim();
+}
+async function readStdinBuffer() {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        process.stdin.on('data', (chunk) => {
+            chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        });
+        process.stdin.on('end', () => resolve(Buffer.concat(chunks)));
+        process.stdin.on('error', reject);
+    });
+}

package/dist/services/memory.js

@@ -0,0 +1,373 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadImageIdsFromDateRangeCache = loadImageIdsFromDateRangeCache;
+exports.normalizeHourlyMetadataEntries = normalizeHourlyMetadataEntries;
+exports.warmDateCacheForApps = warmDateCacheForApps;
+exports.warmDateCacheForDomains = warmDateCacheForDomains;
+exports.warmDateCacheForTags = warmDateCacheForTags;
+exports.warmDateCacheForLocations = warmDateCacheForLocations;
+exports.warmDateCacheForList = warmDateCacheForList;
+exports.warmDateCacheForRanking = warmDateCacheForRanking;
+exports.buildHourlyMetadataEntriesFromImageCache = buildHourlyMetadataEntriesFromImageCache;
+exports.loadOrBuildHourlyMetadataEntries = loadOrBuildHourlyMetadataEntries;
+exports.cacheSearchResultImages = cacheSearchResultImages;
+exports.supplementAltTextFromSearchCache = supplementAltTextFromSearchCache;
+exports.supplementAltTextForDisplay = supplementAltTextForDisplay;
+exports.listCaptures = listCaptures;
+/**
+ * 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
+ * layer answers from the cache when it can, fetching and writing through when
+ * it cannot.
+ *
+ * Two shapes are cached. Whole images, keyed by ID, and hourly buckets holding
+ * the IDs captured in that hour plus the metadata the rankings count, so a
+ * ranking does not have to open every image to answer.
+ */
+const api_1 = require("../api");
+const storage_1 = require("../storage");
+const dates_1 = require("../dates");
+const format_1 = require("../format");
+function loadImageIdsFromDateRangeCache(targetDate) {
+    const imageIds = new Set();
+    const dates = (0, dates_1.getDatePartsInRange)(targetDate.start, targetDate.end);
+    const hours = (0, dates_1.getDateHourStrings)();
+    for (const date of dates) {
+        for (const hour of hours) {
+            const ids = (0, storage_1.loadHourlyCache)(date.year, date.month, date.day, hour) || [];
+            for (const id of ids)
+                imageIds.add(id);
+        }
+    }
+    return Array.from(imageIds);
+}
+function normalizeHourlyMetadataEntries(valuesByImageId) {
+    if (!valuesByImageId || typeof valuesByImageId !== 'object')
+        return {};
+    const normalized = {};
+    for (const [imageId, rawValues] of Object.entries(valuesByImageId)) {
+        const values = Array.isArray(rawValues)
+            ? rawValues.map(value => String(value))
+            : [];
+        normalized[imageId] = (0, format_1.normalizeRankingValues)(values);
+    }
+    return normalized;
+}
+async function warmDateCacheForApps(targetDate, maxPages, useCache) {
+    return warmDateCacheForRanking(targetDate, maxPages, useCache, 'apps', format_1.extractImageApps);
+}
+async function warmDateCacheForDomains(targetDate, maxPages, useCache) {
+    return warmDateCacheForRanking(targetDate, maxPages, useCache, 'domains', format_1.extractImageDomains);
+}
+async function warmDateCacheForTags(targetDate, maxPages, useCache) {
+    return warmDateCacheForRanking(targetDate, maxPages, useCache, 'tags', format_1.extractImageTags);
+}
+async function warmDateCacheForLocations(targetDate, maxPages, useCache) {
+    return warmDateCacheForRanking(targetDate, maxPages, useCache, 'locations', format_1.extractImageLocations);
+}
+async function warmDateCacheForList(targetDate, maxPages, useCache) {
+    const hourlyIndices = new Map();
+    const imageIds = new Set();
+    for (let page = 1; page <= maxPages; page++) {
+        const images = await (0, api_1.listImages)(page, 100);
+        if (images.length === 0)
+            break;
+        let reachedLimit = false;
+        for (const img of images) {
+            const createdAt = new Date(img.created_at);
+            if (Number.isNaN(createdAt.getTime()))
+                continue;
+            if (createdAt > targetDate.end)
+                continue;
+            if (createdAt < targetDate.start) {
+                reachedLimit = true;
+                break;
+            }
+            const dateParts = (0, dates_1.toDateParts)(createdAt);
+            const bucketKey = (0, dates_1.buildHourlyBucketKey)(dateParts.year, dateParts.month, dateParts.day, dateParts.hour);
+            if (!hourlyIndices.has(bucketKey)) {
+                hourlyIndices.set(bucketKey, new Set());
+            }
+            hourlyIndices.get(bucketKey)?.add(img.image_id);
+            imageIds.add(img.image_id);
+            let merged = img;
+            const cached = useCache ? (0, storage_1.loadImageCache)(img.image_id) : null;
+            if (cached) {
+                merged = (0, format_1.mergeImageForDisplay)(img, cached);
+            }
+            (0, storage_1.saveImageCache)(img.image_id, merged);
+        }
+        if (reachedLimit)
+            break;
+    }
+    for (const [bucketKey, current] of hourlyIndices.entries()) {
+        const { year, month, day, hour } = (0, dates_1.splitHourlyBucketKey)(bucketKey);
+        if (useCache) {
+            const existing = (0, storage_1.loadHourlyCache)(year, month, day, hour) || [];
+            for (const id of existing)
+                current.add(id);
+        }
+        (0, storage_1.saveHourlyCache)(year, month, day, hour, Array.from(current));
+        for (const id of current)
+            imageIds.add(id);
+    }
+    if (useCache) {
+        for (const id of loadImageIdsFromDateRangeCache(targetDate)) {
+            imageIds.add(id);
+        }
+    }
+    return Array.from(imageIds);
+}
+async function warmDateCacheForRanking(targetDate, maxPages, useCache, metadataKind, extractValues) {
+    const hourlyIndices = new Map();
+    const hourlyMetadataEntries = new Map();
+    const existingHourlyMetadataEntries = new Map();
+    const imageIds = new Set();
+    for (let page = 1; page <= maxPages; page++) {
+        const images = await (0, api_1.listImages)(page, 100);
+        if (images.length === 0)
+            break;
+        let reachedLimit = false;
+        for (const img of images) {
+            const createdAt = new Date(img.created_at);
+            if (Number.isNaN(createdAt.getTime()))
+                continue;
+            if (createdAt > targetDate.end)
+                continue;
+            if (createdAt < targetDate.start) {
+                reachedLimit = true;
+                break;
+            }
+            const dateParts = (0, dates_1.toDateParts)(createdAt);
+            const bucketKey = (0, dates_1.buildHourlyBucketKey)(dateParts.year, dateParts.month, dateParts.day, dateParts.hour);
+            if (!hourlyIndices.has(bucketKey)) {
+                hourlyIndices.set(bucketKey, new Set());
+            }
+            if (!hourlyMetadataEntries.has(bucketKey)) {
+                hourlyMetadataEntries.set(bucketKey, new Map());
+            }
+            hourlyIndices.get(bucketKey)?.add(img.image_id);
+            imageIds.add(img.image_id);
+            let merged = img;
+            const cached = useCache ? (0, storage_1.loadImageCache)(img.image_id) : null;
+            if (cached) {
+                merged = (0, format_1.mergeImageForDisplay)(img, cached);
+            }
+            let values;
+            let hasExistingMetadataEntry = false;
+            if (useCache) {
+                let existingForBucket = existingHourlyMetadataEntries.get(bucketKey);
+                if (!existingForBucket) {
+                    existingForBucket = normalizeHourlyMetadataEntries((0, storage_1.loadHourlyMetadataCache)(metadataKind, dateParts.year, dateParts.month, dateParts.day, dateParts.hour));
+                    existingHourlyMetadataEntries.set(bucketKey, existingForBucket);
+                }
+                if (Object.prototype.hasOwnProperty.call(existingForBucket, img.image_id)) {
+                    values = existingForBucket[img.image_id];
+                    hasExistingMetadataEntry = true;
+                }
+            }
+            if (!values) {
+                values = (0, format_1.normalizeRankingValues)(extractValues(merged));
+            }
+            if (values.length === 0 && !hasExistingMetadataEntry) {
+                try {
+                    const detail = await (0, api_1.getImageDetail)(img.image_id);
+                    merged = (0, format_1.mergeImageForDisplay)(merged, detail);
+                    values = (0, format_1.normalizeRankingValues)(extractValues(merged));
+                }
+                catch (_error) {
+                    // Keep best effort result when detail fetch fails.
+                }
+            }
+            (0, storage_1.saveImageCache)(img.image_id, merged);
+            hourlyMetadataEntries.get(bucketKey)?.set(img.image_id, values);
+        }
+        if (reachedLimit)
+            break;
+    }
+    for (const [bucketKey, current] of hourlyIndices.entries()) {
+        const { year, month, day, hour } = (0, dates_1.splitHourlyBucketKey)(bucketKey);
+        if (useCache) {
+            const existing = (0, storage_1.loadHourlyCache)(year, month, day, hour) || [];
+            for (const id of existing)
+                current.add(id);
+        }
+        (0, storage_1.saveHourlyCache)(year, month, day, hour, Array.from(current));
+        for (const id of current)
+            imageIds.add(id);
+        const mergedMetadataEntries = useCache
+            ? normalizeHourlyMetadataEntries((0, storage_1.loadHourlyMetadataCache)(metadataKind, year, month, day, hour))
+            : {};
+        const currentMetadataEntries = hourlyMetadataEntries.get(bucketKey) || new Map();
+        for (const [imageId, values] of currentMetadataEntries.entries()) {
+            mergedMetadataEntries[imageId] = values;
+        }
+        (0, storage_1.saveHourlyMetadataCache)(metadataKind, year, month, day, hour, mergedMetadataEntries);
+    }
+    if (useCache) {
+        const dates = (0, dates_1.getDatePartsInRange)(targetDate.start, targetDate.end);
+        const hours = (0, dates_1.getDateHourStrings)();
+        for (const date of dates) {
+            for (const hour of hours) {
+                const existing = (0, storage_1.loadHourlyCache)(date.year, date.month, date.day, hour) || [];
+                for (const id of existing)
+                    imageIds.add(id);
+            }
+        }
+    }
+    return Array.from(imageIds);
+}
+function buildHourlyMetadataEntriesFromImageCache(year, month, day, hour, extractValues) {
+    const imageIds = (0, storage_1.loadHourlyCache)(year, month, day, hour) || [];
+    const valuesByImageId = {};
+    for (const imageId of imageIds) {
+        const image = (0, storage_1.loadImageCache)(imageId);
+        if (!image)
+            continue;
+        valuesByImageId[imageId] = (0, format_1.normalizeRankingValues)(extractValues(image));
+    }
+    return valuesByImageId;
+}
+function loadOrBuildHourlyMetadataEntries(metadataKind, year, month, day, hour, extractValues) {
+    const rawCached = (0, storage_1.loadHourlyMetadataCache)(metadataKind, year, month, day, hour);
+    if (rawCached !== null) {
+        return normalizeHourlyMetadataEntries(rawCached);
+    }
+    const built = buildHourlyMetadataEntriesFromImageCache(year, month, day, hour, extractValues);
+    const hasHourlyIndex = Boolean((0, storage_1.loadHourlyCache)(year, month, day, hour));
+    if (hasHourlyIndex || Object.keys(built).length > 0) {
+        (0, storage_1.saveHourlyMetadataCache)(metadataKind, year, month, day, hour, built);
+    }
+    return built;
+}
+function cacheSearchResultImages(images) {
+    for (const img of images) {
+        if (!img?.image_id)
+            continue;
+        (0, storage_1.saveSearchImageCache)(img.image_id, img);
+    }
+}
+function supplementAltTextFromSearchCache(image, useCache = true) {
+    const hasAltText = Boolean((0, format_1.normalizeText)(image.alt_text));
+    if (hasAltText)
+        return { image, supplemented: false };
+    if (!useCache)
+        return { image, supplemented: false };
+    const cached = (0, storage_1.loadSearchImageCache)(image.image_id);
+    const cachedAltText = (0, format_1.normalizeText)(cached?.alt_text);
+    const cachedHasAltText = Boolean(cachedAltText);
+    if (!cachedHasAltText)
+        return { image, supplemented: false };
+    return {
+        image: {
+            ...image,
+            alt_text: cachedAltText,
+        },
+        supplemented: true,
+    };
+}
+function supplementAltTextForDisplay(images, useCache = true) {
+    return images.map(img => supplementAltTextFromSearchCache(img, useCache).image);
+}
+const ALIAS_QUERIES = {
+    photos: 'has:location',
+    uploaded: 'gyazocli_uploads',
+};
+function byNewestFirst(a, b) {
+    return new Date(b.created_at).getTime() - new Date(a.created_at).getTime();
+}
+function page(images, pageNumber, limit) {
+    const start = (pageNumber - 1) * limit;
+    return images.slice(start, start + limit);
+}
+/**
+ * The captures a `list` request asks for. Four ways in, in the order the
+ * options decide between them: a saved search alias, a date range, one hour of
+ * the cache, or simply the most recent page.
+ *
+ * Validation is the caller's: this takes options that already agree with each
+ * other, because how to refuse differs between the CLI and the MCP server.
+ */
+async function listCaptures(options) {
+    const { page: pageNumber, limit, maxPages, useCache } = options;
+    if (options.alias) {
+        const query = ALIAS_QUERIES[options.alias];
+        if (!options.date) {
+            return { images: await (0, api_1.searchImages)(query, pageNumber, limit) };
+        }
+        const collected = [];
+        for (let searchPage = 1; searchPage <= maxPages; searchPage++) {
+            const pageImages = await (0, api_1.searchImages)(query, searchPage, 100);
+            if (pageImages.length === 0)
+                break;
+            let reachedLimit = false;
+            for (const img of pageImages) {
+                const createdAt = new Date(img.created_at);
+                if (Number.isNaN(createdAt.getTime()))
+                    continue;
+                if (createdAt > options.date.end)
+                    continue;
+                if (createdAt < options.date.start) {
+                    reachedLimit = true;
+                    break;
+                }
+                collected.push(img);
+            }
+            if (reachedLimit)
+                break;
+        }
+        collected.sort(byNewestFirst);
+        return { images: page(collected, pageNumber, limit) };
+    }
+    if (options.date) {
+        const targetDate = options.date;
+        let imageIds = [];
+        if (useCache) {
+            imageIds = loadImageIdsFromDateRangeCache(targetDate);
+            if (imageIds.length === 0) {
+                await warmDateCacheForList(targetDate, maxPages, true);
+                imageIds = loadImageIdsFromDateRangeCache(targetDate);
+            }
+        }
+        else {
+            imageIds = await warmDateCacheForList(targetDate, maxPages, false);
+        }
+        if (imageIds.length === 0) {
+            return { images: [], empty: 'date' };
+        }
+        const images = imageIds
+            .map((id) => (0, storage_1.loadImageCache)(id))
+            .filter((img) => img !== null)
+            .filter((img) => {
+            const createdAt = new Date(img.created_at);
+            if (Number.isNaN(createdAt.getTime()))
+                return false;
+            return createdAt >= targetDate.start && createdAt <= targetDate.end;
+        });
+        images.sort(byNewestFirst);
+        return { images: page(images, pageNumber, limit) };
+    }
+    if (options.hour) {
+        const { year, month, day, hour } = options.hour;
+        const imageIds = (0, storage_1.loadHourlyCache)(year, month, day, hour);
+        if (!imageIds) {
+            return { images: [], empty: 'hour' };
+        }
+        if (useCache) {
+            return { images: imageIds.map((id) => (0, storage_1.loadImageCache)(id)).filter((img) => img !== null) };
+        }
+        const images = [];
+        for (const imageId of imageIds) {
+            try {
+                const detail = await (0, api_1.getImageDetail)(imageId);
+                (0, storage_1.saveImageCache)(imageId, detail);
+                images.push(detail);
+            }
+            catch (_error) {
+                // Skip failed items and continue with the rest.
+            }
+        }
+        return { images };
+    }
+    return { images: await (0, api_1.listImages)(pageNumber, limit) };
+}

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

@@ -6,12 +6,14 @@ Accepted
 ## Context
 The current `gyazocli` implementation uses flat top-level commands (not nested under `images`). Documentation should reflect the command tree implemented in `src/index.ts`.
 
+The commands are defined in `src/index.ts`; what they call lives in the modules described in [ADR 005](005-module-layout.md).
+
 ## Decision
 Adopt and document the existing top-level command structure.
 
 ### 1. Program Metadata
 - Binary name: `gyazo`
-- Version: `0.0.2`
+- Version: `0.2.0`
 - Description: `Gyazo Memory CLI for AI Secretary`
 
 ### 2. Commands

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

@@ -0,0 +1,88 @@
+# 004. Serve MCP from the CLI
+
+## 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.
+
+## Context
+
+nota/gyazo-mcp-server is the official MCP server for Gyazo, and it works: a
+client reached it through a tunnel and searched captures. It is published from
+the nota organization, though, which we cannot publish to, so following it
+means keeping a fork in step with it.
+
+The CLI already holds everything such a server needs: the access token, the
+API client, the cache, and the search that `gyazo search` uses.
+
+## Decision
+
+Serve MCP from this CLI, started with `gyazo --mcp-server` (also `--mcp`,
+`mcp-server`, `mcp`), rather than shipping a second executable.
+
+- Dispatched before commander parses. The server owns stdout for the whole
+  process, which does not fit inside a command action that shares stdout with
+  the usual human-readable output.
+- The MCP SDK is required lazily, so every other command keeps its startup
+  time.
+- Tool names and argument shapes follow nota/gyazo-mcp-server, so a client
+  configured against it keeps working when it is pointed here.
+- The token is resolved the same way as for every other command, and the
+  server exits with a message on stderr when there is none, rather than
+  starting and failing every call.
+
+## Metadata, not image bytes
+
+Upstream returns image content as base64, compressing it with sharp to fit.
+Trying that from a real client showed the ambition does not pay off: the bytes
+are awkward to move through MCP and the model gets little from them that the
+metadata does not already say. Gyazo captures carry OCR text, a title, the
+application and page they came from, and sometimes a location, which is the
+part a model can actually reason about.
+
+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.
+
+## Read-only by construction
+
+`gyazo_upload` is not implemented and no other tool writes. There is no need
+for it yet, and a server that cannot write cannot be talked into writing. Every
+tool carries `readOnlyHint`, and a test asserts that the tool list contains
+nothing else.
+
+## The same answers as the CLI
+
+`gyazo_list` and `gyazo_summary` take the options their commands take, down to
+the defaults, because a client that knows `gyazo list --date 2026-02-20
+--photos` should not have to learn a second vocabulary. The names are
+snake_case, which is what tool arguments look like: `max_pages`, `use_cache`.
+
+The query behind each one moved into the services, so the command and the tool
+call the same function. `listCaptures`, `buildSummary` and `readCollection`
+answer the question; the command prints the answer and the tool serialises it.
+Copying a query into a second caller is how two callers start disagreeing.
+
+Validation stayed with each caller. Which options contradict each other is the
+same question in both places, but the answers differ in kind: the CLI reports
+and exits, and a server must not exit over one bad argument. `parseDateOption`
+and `parseHourOption` grew non-exiting variants for that reason, and the
+exiting ones are now thin wrappers over them.
+
+## Consequences
+
+- 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.
+- 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`
+  property on it. Unknown properties are dropped, so a client configured
+  against upstream still works.
+- The id handling moved to `src/ids.ts`, so the server can turn a URL into an
+  ID without loading commander and every command with it.
+- The tests speak JSON-RPC to the built CLI over a pipe against a stub API, so
+  they cover the framing as well as the tool. CI additionally runs a handshake
+  against a production install with hoisting turned off, because `--mcp-server`
+  is the only path that loads the SDK.