@cyanheads/libofcongress-mcp-server 0.2.1

package/dist/mcp-server/tools/definitions/libofcongress-search.tool.js

@@ -0,0 +1,171 @@
+/**
+ * @fileoverview libofcongress_search tool — search Library of Congress digital collections.
+ * @module mcp-server/tools/definitions/libofcongress-search.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode, validationError } from '@cyanheads/mcp-ts-core/errors';
+import { getLocApiService } from '../../../services/loc-api/loc-api-service.js';
+export const locSearch = tool('libofcongress_search', {
+    title: 'Search LOC Collections',
+    description: 'Search the Library of Congress digital collections by keyword. Optionally filter by material format (photos, maps, newspapers, audio, etc.), date range, subject heading, or geographic location. Returns item summaries with titles, dates, descriptions, LOC IDs, and format tags. Use libofcongress_get_item to retrieve full metadata for a specific result. Use libofcongress_search_subjects first to find the exact LCSH heading spelling before applying a subject filter.',
+    annotations: { readOnlyHint: true, openWorldHint: true },
+    input: z.object({
+        query: z
+            .string()
+            .min(1)
+            .describe('Full-text search across metadata and available descriptive text.'),
+        format: z
+            .enum(['photo', 'map', 'newspaper', 'manuscript', 'audio', 'film', 'book', 'notated-music'])
+            .optional()
+            .describe('Material type filter. Options: photo, map, newspaper, manuscript, audio, film, book, notated-music. Omit to search all formats.'),
+        date_start: z
+            .number()
+            .int()
+            .optional()
+            .describe('Start year for date filter, inclusive (e.g., 1920). Omit for no lower bound.'),
+        date_end: z
+            .number()
+            .int()
+            .optional()
+            .describe('End year for date filter, inclusive (e.g., 1930). Omit for no upper bound.'),
+        subject: z
+            .string()
+            .optional()
+            .describe('Subject heading filter. Use the exact label from libofcongress_search_subjects results for best precision. Example: "World War, 1939-1945".'),
+        location: z
+            .string()
+            .optional()
+            .describe('Geographic location filter (e.g., "oklahoma", "washington d.c."). Lowercase, matches LOC location facets.'),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .default(25)
+            .describe('Results per page. Default 25, max 100.'),
+        page: z
+            .number()
+            .int()
+            .min(1)
+            .default(1)
+            .describe('1-indexed page number for paginating results.'),
+    }),
+    output: z.object({
+        items: z
+            .array(z
+            .object({
+            id: z
+                .string()
+                .describe('LOC item ID — pass to libofcongress_get_item for full metadata.'),
+            title: z.string().describe('Item title.'),
+            date: z.string().optional().describe('Publication or creation date.'),
+            description: z.string().optional().describe('Brief description or summary.'),
+            format: z
+                .string()
+                .optional()
+                .describe('Material format (e.g., photo, map, manuscript).'),
+            url: z.string().describe('LOC item URL.'),
+        })
+            .describe('A single LOC item summary.'))
+            .describe('Item summaries matching the search query and filters.'),
+        total: z.number().describe('Total number of matching items across all pages.'),
+        page: z.number().describe('Current 1-indexed page number.'),
+        pages: z.number().describe('Total number of pages available.'),
+        has_next: z.boolean().describe('True when more pages are available after this one.'),
+        message: z
+            .string()
+            .optional()
+            .describe('Recovery hint when results are empty — echoes the applied filters and suggests how to broaden. Absent on non-empty result pages.'),
+    }),
+    errors: [
+        {
+            reason: 'empty_results',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'No items matched the query and filters.',
+            recovery: 'Broaden the query, widen the date range, or use libofcongress_search_subjects to find the correct subject heading spelling.',
+        },
+        {
+            reason: 'rate_limit_exceeded',
+            code: JsonRpcErrorCode.ServiceUnavailable,
+            when: 'LOC API rate limit exceeded; requests are blocked for approximately 1 hour.',
+            recovery: 'Wait approximately 1 hour before retrying. Reduce request frequency to stay under 20 req/min.',
+        },
+    ],
+    async handler(input, ctx) {
+        ctx.log.info('libofcongress_search', {
+            query: input.query,
+            format: input.format,
+            page: input.page,
+        });
+        if (input.date_start !== undefined &&
+            input.date_end !== undefined &&
+            input.date_start > input.date_end) {
+            throw validationError(`date_start (${input.date_start}) must be ≤ date_end (${input.date_end}). Reverse the values to form a valid date range.`, { field: 'date_start', date_start: input.date_start, date_end: input.date_end });
+        }
+        const svc = getLocApiService();
+        const result = await svc.search({
+            query: input.query,
+            ...(input.format !== undefined && { format: input.format }),
+            ...(input.date_start !== undefined && { dateStart: input.date_start }),
+            ...(input.date_end !== undefined && { dateEnd: input.date_end }),
+            ...(input.subject?.trim() && { subject: input.subject.trim() }),
+            ...(input.location?.trim() && { location: input.location.trim() }),
+            limit: input.limit,
+            page: input.page,
+        }, ctx);
+        if (result.items.length === 0) {
+            return {
+                items: [],
+                total: 0,
+                page: input.page,
+                pages: 0,
+                has_next: false,
+                message: `No items matched "${input.query}"` +
+                    (input.format ? ` with format "${input.format}"` : '') +
+                    (input.date_start || input.date_end
+                        ? ` in dates ${input.date_start ?? ''}–${input.date_end ?? ''}`
+                        : '') +
+                    '. Try broadening the query, widening the date range, or running libofcongress_search_subjects to find the exact subject heading.',
+            };
+        }
+        const { total, page, pages, hasNext } = result.pagination;
+        // Detect contradictory pagination: LOC sometimes returns items on out-of-range pages.
+        // Surface a clear message rather than a confusing "Page 999 of 26" display.
+        if (pages > 0 && page > pages) {
+            return {
+                items: [],
+                total,
+                page,
+                pages,
+                has_next: false,
+                message: `No results on page ${page} — query has ${pages} page(s) total (${total} items). Use a page number between 1 and ${pages}.`,
+            };
+        }
+        return {
+            items: result.items,
+            total,
+            page,
+            pages,
+            has_next: hasNext,
+        };
+    },
+    format: (result) => {
+        const lines = [];
+        lines.push(`**Total:** ${result.total} | **Page:** ${result.page} of ${result.pages} | **has_next:** ${result.has_next}`);
+        if (result.message)
+            lines.push(`\n> ${result.message}`);
+        for (const item of result.items) {
+            lines.push(`\n## ${item.title}`);
+            lines.push(`**ID:** ${item.id}`);
+            if (item.date)
+                lines.push(`**Date:** ${item.date}`);
+            if (item.format)
+                lines.push(`**Format:** ${item.format}`);
+            if (item.description)
+                lines.push(item.description);
+            lines.push(`**URL:** ${item.url}`);
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=libofcongress-search.tool.js.map

package/dist/mcp-server/tools/definitions/libofcongress-search.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"libofcongress-search.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/libofcongress-search.tool.ts"],"names":[],"mappings":"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"}

package/dist/services/lc-linked-data/lc-linked-data-service.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @fileoverview LC Linked Data service — wraps id.loc.gov for LCSH subject heading lookups.
+ * @module services/lc-linked-data/lc-linked-data-service
+ */
+import type { Context } from '@cyanheads/mcp-ts-core';
+import type { AppConfig } from '@cyanheads/mcp-ts-core/config';
+import type { StorageService } from '@cyanheads/mcp-ts-core/storage';
+import type { LcSubjectHeading } from './types.js';
+export declare class LcLinkedDataService {
+    private readonly userAgent;
+    constructor(_config: AppConfig, _storage: StorageService);
+    /** Search LCSH subject headings via the suggest endpoint */
+    searchSubjects(query: string, limit: number, ctx: Context): Promise<LcSubjectHeading[]>;
+}
+export declare function initLcLinkedDataService(config: AppConfig, storage: StorageService): void;
+export declare function getLcLinkedDataService(): LcLinkedDataService;
+//# sourceMappingURL=lc-linked-data-service.d.ts.map

package/dist/services/lc-linked-data/lc-linked-data-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lc-linked-data-service.d.ts","sourceRoot":"","sources":["../../../src/services/lc-linked-data/lc-linked-data-service.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAE/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAErE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAWnD,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,cAAc;IAKxD,4DAA4D;IACtD,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;CA8C9F;AAMD,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAExF;AAED,wBAAgB,sBAAsB,IAAI,mBAAmB,CAO5D"}

package/dist/services/lc-linked-data/lc-linked-data-service.js

@@ -0,0 +1,71 @@
+/**
+ * @fileoverview LC Linked Data service — wraps id.loc.gov for LCSH subject heading lookups.
+ * @module services/lc-linked-data/lc-linked-data-service
+ */
+import { serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
+import { getServerConfig } from '../../config/server-config.js';
+const LC_LINKED_DATA_BASE = 'https://id.loc.gov';
+const SUBJECTS_SCHEME = 'http://id.loc.gov/authorities/subjects';
+export class LcLinkedDataService {
+    userAgent;
+    constructor(_config, _storage) {
+        const serverConfig = getServerConfig();
+        this.userAgent = serverConfig.userAgent;
+    }
+    /** Search LCSH subject headings via the suggest endpoint */
+    async searchSubjects(query, limit, ctx) {
+        const qs = new URLSearchParams({
+            q: query,
+            memberOf: SUBJECTS_SCHEME,
+            count: String(Math.min(limit, 50)),
+        });
+        const url = `${LC_LINKED_DATA_BASE}/suggest/?${qs}`;
+        ctx.log.debug('LC Linked Data subject suggest', { url });
+        const response = await fetch(url, {
+            headers: { 'User-Agent': this.userAgent, Accept: 'application/json' },
+            signal: ctx.signal,
+        });
+        if (!response.ok) {
+            throw serviceUnavailable(`LC Linked Data returned HTTP ${response.status}`, {
+                url,
+                status: response.status,
+            });
+        }
+        const text = await response.text();
+        if (/^\s*<(!DOCTYPE\s+html|html[\s>])/i.test(text)) {
+            throw serviceUnavailable('LC Linked Data returned HTML — temporarily unavailable.', { url });
+        }
+        const data = JSON.parse(text);
+        if (!Array.isArray(data) || data.length < 4) {
+            return [];
+        }
+        const [, labels, counts, uris] = data;
+        const results = [];
+        for (let i = 0; i < labels.length; i++) {
+            const label = labels[i];
+            const uri = uris[i];
+            if (!label || !uri)
+                continue;
+            const countStr = counts[i];
+            const count = countStr ? parseInt(countStr, 10) : undefined;
+            results.push({
+                label,
+                uri,
+                ...(count !== undefined && !Number.isNaN(count) && { count }),
+            });
+        }
+        return results;
+    }
+}
+// --- Init/accessor pattern ---
+let _service;
+export function initLcLinkedDataService(config, storage) {
+    _service = new LcLinkedDataService(config, storage);
+}
+export function getLcLinkedDataService() {
+    if (!_service) {
+        throw new Error('LcLinkedDataService not initialized — call initLcLinkedDataService() in setup()');
+    }
+    return _service;
+}
+//# sourceMappingURL=lc-linked-data-service.js.map

package/dist/services/lc-linked-data/lc-linked-data-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lc-linked-data-service.js","sourceRoot":"","sources":["../../../src/services/lc-linked-data/lc-linked-data-service.ts"],"names":[],"mappings":"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"}

package/dist/services/lc-linked-data/types.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @fileoverview Domain types for the LC Linked Data service (id.loc.gov).
+ * @module services/lc-linked-data/types
+ */
+/** Normalized LCSH subject heading record */
+export type LcSubjectHeading = {
+    label: string;
+    uri: string;
+    count?: number;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/services/lc-linked-data/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/services/lc-linked-data/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,6CAA6C;AAC7C,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC"}

package/dist/services/lc-linked-data/types.js

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Domain types for the LC Linked Data service (id.loc.gov).
+ * @module services/lc-linked-data/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/services/lc-linked-data/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/services/lc-linked-data/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/services/loc-api/loc-api-service.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @fileoverview LOC JSON API service — wraps www.loc.gov with rate limiting, retry, and response normalization.
+ * @module services/loc-api/loc-api-service
+ */
+import type { Context } from '@cyanheads/mcp-ts-core';
+import type { AppConfig } from '@cyanheads/mcp-ts-core/config';
+import type { StorageService } from '@cyanheads/mcp-ts-core/storage';
+import type { LocCollection, LocItemDetail, LocItemSummary, LocNewspaperPage, LocNewspaperPageDetail, LocPagination } from './types.js';
+export declare class LocApiService {
+    private readonly userAgent;
+    private readonly requestDelayMs;
+    constructor(_config: AppConfig, _storage: StorageService);
+    private checkRateLimit;
+    private fetch;
+    private fetchJson;
+    /**
+     * Fetch a LOC search endpoint, treating HTTP 400 and 520 as out-of-range page responses
+     * (LOC returns these for page numbers beyond the result set).
+     * Returns null when the page is out of range.
+     */
+    private fetchSearchJson;
+    /** Search LOC digital collections */
+    search(params: {
+        query: string;
+        format?: string;
+        dateStart?: number;
+        dateEnd?: number;
+        subject?: string;
+        location?: string;
+        limit?: number;
+        page?: number;
+    }, ctx: Context): Promise<{
+        items: LocItemSummary[];
+        pagination: LocPagination;
+    }>;
+    /** Get full metadata for a single LOC item */
+    getItem(itemId: string, ctx: Context): Promise<LocItemDetail>;
+    /** Search historical newspaper pages via the /newspapers/ endpoint */
+    searchNewspapers(params: {
+        query: string;
+        dateStart?: number;
+        dateEnd?: number;
+        state?: string;
+        newspaperTitle?: string;
+        limit?: number;
+        page?: number;
+    }, ctx: Context): Promise<{
+        items: LocNewspaperPage[];
+        pagination: LocPagination;
+    }>;
+    /** Retrieve full OCR text for a specific newspaper page via its resource URL */
+    getNewspaperPage(pageUrl: string, ctx: Context): Promise<LocNewspaperPageDetail>;
+    /** Browse LOC curated digital collections */
+    browseCollections(params: {
+        query?: string;
+        limit?: number;
+        page?: number;
+    }, ctx: Context): Promise<{
+        items: LocCollection[];
+        pagination: LocPagination;
+    }>;
+}
+export declare function initLocApiService(config: AppConfig, storage: StorageService): void;
+export declare function getLocApiService(): LocApiService;
+//# sourceMappingURL=loc-api-service.d.ts.map

package/dist/services/loc-api/loc-api-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loc-api-service.d.ts","sourceRoot":"","sources":["../../../src/services/loc-api/loc-api-service.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAE/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAErE,OAAO,KAAK,EACV,aAAa,EACb,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,sBAAsB,EACtB,aAAa,EAKd,MAAM,YAAY,CAAC;AAsFpB,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;gBAE5B,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,cAAc;IAMxD,OAAO,CAAC,cAAc;YAgBR,KAAK;YAwCL,SAAS;IAevB;;;;OAIG;YACW,eAAe;IAoB7B,qCAAqC;IAC/B,MAAM,CACV,MAAM,EAAE;QACN,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,EACD,GAAG,EAAE,OAAO,GACX,OAAO,CAAC;QAAE,KAAK,EAAE,cAAc,EAAE,CAAC;QAAC,UAAU,EAAE,aAAa,CAAA;KAAE,CAAC;IA+BlE,8CAA8C;IACxC,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC;IAgDnE,sEAAsE;IAChE,gBAAgB,CACpB,MAAM,EAAE;QACN,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,EACD,GAAG,EAAE,OAAO,GACX,OAAO,CAAC;QAAE,KAAK,EAAE,gBAAgB,EAAE,CAAC;QAAC,UAAU,EAAE,aAAa,CAAA;KAAE,CAAC;IAmDpE,gFAAgF;IAC1E,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,sBAAsB,CAAC;IA2FtF,6CAA6C;IACvC,iBAAiB,CACrB,MAAM,EAAE;QACN,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,EACD,GAAG,EAAE,OAAO,GACX,OAAO,CAAC;QAAE,KAAK,EAAE,aAAa,EAAE,CAAC;QAAC,UAAU,EAAE,aAAa,CAAA;KAAE,CAAC;CAiClE;AAMD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAElF;AAED,wBAAgB,gBAAgB,IAAI,aAAa,CAKhD"}