@cyanheads/libofcongress-mcp-server 0.2.2 → 0.2.4

package/CLAUDE.md

@@ -1,7 +1,7 @@
 # Developer Protocol
 
 **Server:** libofcongress-mcp-server
-**Version:** 0.2.2
+**Version:** 0.2.4
 **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.9.9`
 **Engines:** Bun ≥1.3.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/sdk` ^1.29.0
@@ -113,7 +113,7 @@ import { z } from '@cyanheads/mcp-ts-core';
 import { parseEnvConfig } from '@cyanheads/mcp-ts-core/config';
 
 const ServerConfigSchema = z.object({
-  userAgent: z.string().default('libofcongress-mcp-server/0.2.2').describe('User-Agent header for LOC API requests.'),
+  userAgent: z.string().default('libofcongress-mcp-server/0.2.4').describe('User-Agent header for LOC API requests.'),
   requestDelayMs: z.coerce.number().default(3100).describe('Delay in ms between LOC API requests.'),
 });
 

package/Dockerfile

@@ -1,24 +1,24 @@
 # ==============================================================================
 # Build Stage
 #
-# Uses Node.js to compile TypeScript (tsx requires Node; Bun 1.3 intercepts tsx
-# and runs it natively, which breaks tsx's CJS compatibility shim on Linux).
+# This stage installs all dependencies (including dev), builds the TypeScript
+# source code into JavaScript, and prepares the production assets.
 # ==============================================================================
-FROM node:24-slim AS build
+FROM oven/bun:1.3 AS build
 
 WORKDIR /usr/src/app
 
-# Copy dependency manifests
+# Copy dependency manifests for optimized layer caching
 COPY package.json bun.lock ./
 
-# Install all dependencies using npm (bun.lock is readable by npm for lockfile-aware install)
-RUN npm install --include=dev
+# Install all dependencies (including dev dependencies for building)
+RUN bun install --frozen-lockfile
 
 # Copy the rest of the source code
 COPY . .
 
 # Build the application
-RUN npx tsx scripts/build.ts
+RUN bun run build
 
 
 # ==============================================================================
@@ -34,9 +34,10 @@ WORKDIR /usr/src/app
 ENV NODE_ENV=production
 
 # OCI image metadata (https://github.com/opencontainers/image-spec/blob/main/annotations.md)
-LABEL org.opencontainers.image.title="libofcongress-mcp-server"
-LABEL org.opencontainers.image.description=""
+LABEL org.opencontainers.image.title="@cyanheads/libofcongress-mcp-server"
+LABEL org.opencontainers.image.description="Search LOC digital collections, browse Chronicling America newspapers with full OCR text, and look up LC Subject Headings via MCP."
 LABEL org.opencontainers.image.licenses="Apache-2.0"
+LABEL org.opencontainers.image.source="https://github.com/cyanheads/libofcongress-mcp-server"
 
 # Copy dependency manifests
 COPY package.json bun.lock ./

package/README.md

@@ -7,7 +7,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.2.2-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/libofcongress-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/%40cyanheads%2Flibofcongress-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/libofcongress-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^5.9.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.11-blueviolet.svg?style=flat-square)](https://bun.sh/)
+[![Version](https://img.shields.io/badge/Version-0.2.4-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/libofcongress-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/%40cyanheads%2Flibofcongress-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/libofcongress-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^5.9.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.11-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 
@@ -19,6 +19,12 @@
 
 </div>
 
+<div align="center">
+
+**Public Hosted Server:** [https://libofcongress.caseyjhand.com/mcp](https://libofcongress.caseyjhand.com/mcp)
+
+</div>
+
 ---
 
 ## Tools

package/dist/config/server-config.js

@@ -7,7 +7,7 @@ import { parseEnvConfig } from '@cyanheads/mcp-ts-core/config';
 const ServerConfigSchema = z.object({
     userAgent: z
         .string()
-        .default('libofcongress-mcp-server/0.2.2')
+        .default('libofcongress-mcp-server/0.2.3')
         .describe('User-Agent header sent with LOC API requests. LOC recommends a descriptive value for polite access.'),
     requestDelayMs: z.coerce
         .number()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/libofcongress-mcp-server",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "mcpName": "io.github.cyanheads/libofcongress-mcp-server",
   "description": "Search LOC digital collections, browse Chronicling America newspapers with full OCR text, and look up LC Subject Headings via MCP. STDIO or Streamable HTTP.",
   "type": "module",
@@ -9,35 +9,25 @@
   "bin": {
     "libofcongress-mcp-server": "dist/index.js"
   },
-  "files": [
-    "changelog/",
-    "dist/",
-    "README.md",
-    "LICENSE",
-    "CLAUDE.md",
-    "AGENTS.md",
-    "Dockerfile",
-    "server.json"
-  ],
+  "files": ["dist/", "README.md", "LICENSE", "CLAUDE.md", "Dockerfile", "server.json"],
   "scripts": {
-    "build": "tsx scripts/build.ts",
-    "rebuild": "tsx scripts/clean.ts && tsx scripts/build.ts",
-    "clean": "tsx scripts/clean.ts",
-    "devcheck": "tsx scripts/devcheck.ts",
+    "build": "bun run scripts/build.ts",
+    "rebuild": "bun run scripts/clean.ts && bun run build",
+    "clean": "bun run scripts/clean.ts",
+    "devcheck": "bun run scripts/devcheck.ts",
     "audit:refresh": "rm -f bun.lock && bun install && bun audit",
-    "tree": "tsx scripts/tree.ts",
-    "list-skills": "tsx scripts/list-skills.ts",
+    "tree": "bun run scripts/tree.ts",
+    "list-skills": "bun run scripts/list-skills.ts",
     "format": "biome check --write --unsafe .",
-    "lint:mcp": "tsx scripts/lint-mcp.ts",
-    "lint:packaging": "tsx scripts/lint-packaging.ts",
+    "lint:mcp": "bun run scripts/lint-mcp.ts",
+    "lint:packaging": "bun run scripts/lint-packaging.ts",
     "publish-mcp": "mcp-publisher login github -token \"$(security find-generic-password -a \"$USER\" -s mcp-publisher-github-pat -w)\" && mcp-publisher publish",
     "bundle": "bun run build && npx -y @anthropic-ai/mcpb pack . dist/libofcongress-mcp-server.mcpb",
-    "changelog:build": "tsx scripts/build-changelog.ts",
-    "changelog:check": "tsx scripts/build-changelog.ts --check",
-    "test": "vitest run",
-    "start": "node dist/index.js",
-    "start:stdio": "MCP_TRANSPORT_TYPE=stdio node dist/index.js",
-    "start:http": "MCP_TRANSPORT_TYPE=http node dist/index.js"
+    "changelog:build": "bun run scripts/build-changelog.ts",
+    "changelog:check": "bun run scripts/build-changelog.ts --check",
+    "test": "bunx vitest run",
+    "start:stdio": "MCP_TRANSPORT_TYPE=stdio bun ./dist/index.js",
+    "start:http": "MCP_TRANSPORT_TYPE=http bun ./dist/index.js"
   },
   "keywords": [
     "mcp",
@@ -65,6 +55,16 @@
     "type": "git",
     "url": "git+https://github.com/cyanheads/libofcongress-mcp-server.git"
   },
+  "funding": [
+    {
+      "type": "github",
+      "url": "https://github.com/sponsors/cyanheads"
+    },
+    {
+      "type": "buy_me_a_coffee",
+      "url": "https://www.buymeacoffee.com/cyanheads"
+    }
+  ],
   "license": "Apache-2.0",
   "packageManager": "bun@1.3.11",
   "engines": {
@@ -85,7 +85,6 @@
     "depcheck": "^1.4.7",
     "ignore": "^7.0.5",
     "tsc-alias": "^1.8.16",
-    "tsx": "^4.19.0",
     "typescript": "^5.9.3",
     "vitest": "^4.1.0"
   }

package/server.json

@@ -6,14 +6,14 @@
     "url": "https://github.com/cyanheads/libofcongress-mcp-server",
     "source": "github"
   },
-  "version": "0.2.2",
+  "version": "0.2.4",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@cyanheads/libofcongress-mcp-server",
       "runtimeHint": "bun",
-      "version": "0.2.2",
+      "version": "0.2.4",
       "packageArguments": [
         {
           "type": "positional",
@@ -30,7 +30,7 @@
           "description": "User-Agent header sent with LOC API requests. LOC recommends a descriptive value for polite access.",
           "format": "string",
           "isRequired": false,
-          "default": "libofcongress-mcp-server/0.2.2"
+          "default": "libofcongress-mcp-server/0.2.4"
         },
         {
           "name": "LOC_REQUEST_DELAY_MS",
@@ -56,7 +56,7 @@
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@cyanheads/libofcongress-mcp-server",
       "runtimeHint": "bun",
-      "version": "0.2.2",
+      "version": "0.2.4",
       "packageArguments": [
         {
           "type": "positional",
@@ -73,7 +73,7 @@
           "description": "User-Agent header sent with LOC API requests. LOC recommends a descriptive value for polite access.",
           "format": "string",
           "isRequired": false,
-          "default": "libofcongress-mcp-server/0.2.2"
+          "default": "libofcongress-mcp-server/0.2.4"
         },
         {
           "name": "LOC_REQUEST_DELAY_MS",

package/AGENTS.md

@@ -1,388 +0,0 @@
-# Developer Protocol
-
-**Server:** libofcongress-mcp-server
-**Version:** 0.2.2
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.9.9`
-**Engines:** Bun ≥1.3.0, Node ≥24.0.0
-**MCP SDK:** `@modelcontextprotocol/sdk` ^1.29.0
-**Zod:** ^4.4.3
-
-> **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
-
----
-
-## What's Next?
-
-When the user asks what's next or needs direction, suggest options based on the current project state. Common next steps:
-
-1. **Re-run the `setup` skill** — ensures CLAUDE.md, skills, structure, and metadata are populated and up to date with the current codebase
-2. **Run the `design-mcp-server` skill** — if the tool/resource surface hasn't been mapped yet, work through domain design
-3. **Add tools/resources/prompts** — scaffold new definitions using the `add-tool`, `add-app-tool`, `add-resource`, `add-prompt` skills
-4. **Add services** — scaffold domain service integrations using the `add-service` skill
-5. **Add tests** — scaffold tests for existing definitions using the `add-test` skill
-6. **Field-test definitions** — exercise tools/resources/prompts with real inputs using the `field-test` skill, get a report of issues and pain points
-7. **Run `devcheck`** — lint, format, typecheck, and security audit
-8. **Run the `security-pass` skill** — audit handlers for MCP-specific security gaps: output injection, scope blast radius, input sinks, tenant isolation
-9. **Run the `polish-docs-meta` skill** — finalize README, CHANGELOG, metadata, and agent protocol for shipping
-10. **Run the `maintenance` skill** — investigate changelogs, adopt upstream changes, and sync skills after `bun update --latest`
-
-Tailor suggestions to what's actually missing or stale — don't recite the full list every time.
-
----
-
-## Core Rules
-
-- **Logic throws, framework catches.** Tool/resource handlers are pure — throw on failure, no `try/catch`. Plain `Error` is fine; the framework catches, classifies, and formats. Use error factories (`notFound()`, `validationError()`, etc.) when the error code matters.
-- **Use `ctx.log`** for request-scoped logging. No `console` calls.
-- **Use `ctx.state`** for tenant-scoped storage. Never access persistence directly.
-- **Check `ctx.elicit` / `ctx.sample`** for presence before calling.
-- **Secrets in env vars only** — never hardcoded.
-- **Close the loop on issues.** When implementing work tracked by a GitHub issue, comment on the issue with what landed before moving on. The comment is for future readers — state the concrete changes, not the conversation that produced them.
-
----
-
-## Patterns
-
-### Tool
-
-```ts
-import { tool, z } from '@cyanheads/mcp-ts-core';
-import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
-import { getLocApiService } from '@/services/loc-api/loc-api-service.js';
-
-export const locSearch = tool('libofcongress_search', {
-  description: 'Search the Library of Congress digital collections by keyword with format, date range, subject heading, and geographic location filters.',
-  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.'),
-    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.'),
-  }),
-  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.'),
-      url: z.string().describe('LOC item URL.'),
-    })).describe('Item summaries matching the search query and filters.'),
-    total: z.number().describe('Total number of matching items across all pages.'),
-    has_next: z.boolean().describe('True when more pages are available after this one.'),
-  }),
-  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.' },
-  ],
-  async handler(input, ctx) {
-    ctx.log.info('libofcongress_search', { query: input.query, page: input.page });
-    const svc = getLocApiService();
-    const result = await svc.search({ query: input.query, limit: input.limit, page: input.page }, ctx);
-    return { items: result.items, total: result.pagination.total, has_next: result.pagination.hasNext };
-  },
-  format: (result) => [{
-    type: 'text',
-    text: result.items.map(i => `**${i.title}** (${i.id})\n${i.url}`).join('\n\n'),
-  }],
-});
-```
-
-### Resource
-
-```ts
-import { resource, z } from '@cyanheads/mcp-ts-core';
-import { getLocApiService } from '@/services/loc-api/loc-api-service.js';
-
-export const locItemResource = resource('libofcongress://item/{item_id}', {
-  name: 'loc-item',
-  description: 'LOC digital item metadata by ID. Stable URI for injecting item context into agent conversations.',
-  mimeType: 'application/json',
-  params: z.object({ item_id: z.string().describe('LOC item ID (e.g., "loc.pnp.ppmsc.02404").') }),
-  handler(params, ctx) {
-    ctx.log.debug('libofcongress://item resource', { item_id: params.item_id });
-    const svc = getLocApiService();
-    return svc.getItem(params.item_id, ctx);
-  },
-});
-```
-
-### Server config
-
-```ts
-// src/config/server-config.ts
-import { z } from '@cyanheads/mcp-ts-core';
-import { parseEnvConfig } from '@cyanheads/mcp-ts-core/config';
-
-const ServerConfigSchema = z.object({
-  userAgent: z.string().default('libofcongress-mcp-server/0.2.2').describe('User-Agent header for LOC API requests.'),
-  requestDelayMs: z.coerce.number().default(3100).describe('Delay in ms between LOC API requests.'),
-});
-
-let _config: z.infer<typeof ServerConfigSchema> | undefined;
-export function getServerConfig() {
-  _config ??= parseEnvConfig(ServerConfigSchema, {
-    userAgent: 'LOC_USER_AGENT',
-    requestDelayMs: 'LOC_REQUEST_DELAY_MS',
-  });
-  return _config;
-}
-```
-
-`parseEnvConfig` maps Zod schema paths → env var names so errors name the variable (`LOC_USER_AGENT`) not the path (`userAgent`). Throws `ConfigurationError`, which the framework prints as a clean startup banner.
-
----
-
-## Context
-
-Handlers receive a unified `ctx` object. Key properties:
-
-| Property | Description |
-|:---------|:------------|
-| `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. |
-| `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |
-| `ctx.elicit` | Ask user for structured input. **Check for presence first:** `if (ctx.elicit) { ... }` |
-| `ctx.sample` | Request LLM completion from the client. **Check for presence first:** `if (ctx.sample) { ... }` |
-| `ctx.signal` | `AbortSignal` for cancellation. |
-| `ctx.progress` | Task progress (present when `task: true`) — `.setTotal(n)`, `.increment()`, `.update(message)`. |
-| `ctx.requestId` | Unique request ID. |
-| `ctx.tenantId` | Tenant ID from JWT or `'default'` for stdio. |
-
----
-
-## Errors
-
-Handlers throw — the framework catches, classifies, and formats.
-
-**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required descriptive metadata for the agent's next move (≥ 5 words, lint-validated); for the wire `data.recovery.hint` (mirrored into `content[]` text), pass explicitly at the throw site when dynamic context matters: `ctx.fail('reason', msg, { recovery: { hint: '...' } })`. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring.
-
-```ts
-errors: [
-  { reason: 'no_match', code: JsonRpcErrorCode.NotFound,
-    when: 'No item matched the query',
-    recovery: 'Broaden the query or check the spelling and try again.' },
-],
-async handler(input, ctx) {
-  const item = await db.find(input.id);
-  if (!item) throw ctx.fail('no_match', `No item ${input.id}`);
-  return item;
-}
-```
-
-**Declare contracts inline on each tool.** The contract is part of the tool's public surface — one file should give the full picture. Don't extract a shared `errors[]` constant; per-tool repetition is the intended cost of locality.
-
-**Fallback (no contract entry fits):** throw via factories or plain `Error`.
-
-```ts
-// Error factories — explicit code
-import { notFound, serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
-throw notFound('Item not found', { itemId });
-throw serviceUnavailable('API unavailable', { url }, { cause: err });
-
-// Plain Error — framework auto-classifies from message patterns
-throw new Error('Item not found');           // → NotFound
-throw new Error('Invalid query format');     // → ValidationError
-
-// McpError — when no factory exists for the code
-import { McpError, JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
-throw new McpError(JsonRpcErrorCode.DatabaseError, 'Connection failed', { pool: 'primary' });
-```
-
-See framework CLAUDE.md and the `api-errors` skill for the full auto-classification table, all available factories, and the contract reference.
-
----
-
-## Structure
-
-```text
-src/
-  index.ts                              # createApp() entry point — registers tools, resource, and initializes services
-  config/
-    server-config.ts                    # LOC_USER_AGENT and LOC_REQUEST_DELAY_MS (Zod schema)
-  services/
-    loc-api/
-      loc-api-service.ts               # LOC JSON API client — rate pacing, search, item fetch, newspaper page
-      types.ts                          # Raw and normalized LOC API types
-    lc-linked-data/
-      lc-linked-data-service.ts        # id.loc.gov LCSH subject suggest client
-      types.ts                          # Subject heading types
-  mcp-server/
-    tools/definitions/
-      libofcongress-search.tool.ts               # libofcongress_search — general LOC collection search
-      libofcongress-get-item.tool.ts             # libofcongress_get_item — full item metadata
-      libofcongress-search-newspapers.tool.ts    # libofcongress_search_newspapers — Chronicling America search
-      libofcongress-get-newspaper-page.tool.ts   # libofcongress_get_newspaper_page — full OCR text
-      libofcongress-search-subjects.tool.ts      # libofcongress_search_subjects — LCSH subject heading lookup
-      libofcongress-browse-collections.tool.ts   # libofcongress_browse_collections — curated collection browser
-    resources/definitions/
-      libofcongress-item.resource.ts             # libofcongress://item/{item_id} — stable item URI
-```
-
----
-
-## Naming
-
-| What | Convention | Example |
-|:-----|:-----------|:--------|
-| Files | kebab-case with suffix | `search-docs.tool.ts` |
-| Tool/resource/prompt names | snake_case | `search_docs` |
-| Directories | kebab-case | `src/services/doc-search/` |
-| Descriptions | Single string or template literal, no `+` concatenation | `'Search items by query and filter.'` |
-
----
-
-## Skills
-
-Skills are modular instructions in `skills/` at the project root. Read them directly when a task matches — e.g., `skills/add-tool/SKILL.md` when adding a tool.
-
-**Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
-
-Available skills:
-
-| Skill | Purpose |
-|:------|:--------|
-| `setup` | Post-init project orientation |
-| `design-mcp-server` | Design tool surface, resources, and services for a new server |
-| `add-tool` | Scaffold a new tool definition |
-| `add-app-tool` | Scaffold an MCP App tool + paired UI resource |
-| `add-resource` | Scaffold a new resource definition |
-| `add-prompt` | Scaffold a new prompt definition |
-| `add-service` | Scaffold a new service integration |
-| `add-test` | Scaffold test file for a tool, resource, or service |
-| `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
-| `security-pass` | Audit server for MCP-flavored security gaps: output injection, scope blast radius, input sinks, tenant isolation |
-| `devcheck` | Lint, format, typecheck, audit |
-| `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
-| `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
-| `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
-| `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
-| `api-auth` | Auth modes, scopes, JWT/OAuth |
-| `api-canvas` | DataCanvas: register tabular data, run SQL, export, plus the `spillover()` helper for big result sets — Tier 3 opt-in |
-| `api-config` | AppConfig, parseConfig, env vars |
-| `api-context` | Context interface, logger, state, progress |
-| `api-errors` | McpError, JsonRpcErrorCode, error patterns |
-| `api-services` | LLM, Speech, Graph services |
-| `api-testing` | createMockContext, test patterns |
-| `api-utils` | Formatting, parsing, security, pagination, scheduling, telemetry helpers |
-| `api-telemetry` | OTel catalog: spans, metrics, completion logs, env config, cardinality rules |
-| `api-workers` | Cloudflare Workers runtime |
-
-When you complete a skill's checklist, check the boxes and add a completion timestamp at the end (e.g., `Completed: 2026-03-11`).
-
----
-
-## Commands
-
-**Runtime:** Scripts use `tsx` — both `npm run <cmd>` and `bun run <cmd>` work. `bun` is slightly faster for script invocation but not required.
-
-| Command | Purpose |
-|:--------|:--------|
-| `npm run build` | Compile TypeScript |
-| `npm run rebuild` | Clean + build |
-| `npm run clean` | Remove build artifacts |
-| `npm run devcheck` | Lint + format + typecheck + security + changelog sync |
-| `bun run audit:refresh` | Delete `bun.lock`, reinstall, re-audit. Use when `devcheck` flags a transitive advisory — stale lockfile can mask already-patched deps. If advisory survives, it's real. |
-| `npm run tree` | Generate directory structure doc |
-| `npm run format` | Auto-fix formatting |
-| `npm test` | Run tests |
-| `npm run start:stdio` | Production mode (stdio) |
-| `npm run start:http` | Production mode (HTTP) |
-| `npm run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
-| `npm run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
-| `npm run bundle` | Build and pack as `.mcpb` for one-click Claude Desktop install |
-
----
-
-## Bundling
-
-`npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
-
-**Adding an env var requires both files:** `server.json` (registry discovery, `environmentVariables[]`) and `manifest.json` (bundle install UX, `mcp_config.env` + `user_config`). `lint:packaging` (run by `devcheck`) verifies the env var names match.
-
-**README install badges.** Drop these into the project README to give users one-click install paths. Fill in `<OWNER>` / `<REPO>` / `<PACKAGE_NAME>` and encode the per-server config. Cursor + VS Code badges assume the server is published to npm; Claude Desktop downloads the `.mcpb` directly so npm publishing isn't required.
-
-| Client | Mechanism |
-|:-------|:----------|
-| Claude Desktop | Browser downloads the `.mcpb` from the latest GitHub Release; OS file handler routes it to Claude Desktop, which opens the install dialog. No deep-link URL scheme yet — this is the canonical path. |
-| Cursor | Official `https://cursor.com/en/install-mcp` endpoint with base64 JSON config. |
-| VS Code / Insiders | Official `vscode:mcp/install?...` deep link, wrapped in `https://vscode.dev/redirect?url=` so GitHub-rendered markdown doesn't strip the non-HTTP scheme. |
-| Claude Code / Codex | CLI only (`claude mcp add` / `codex mcp add`); no URL scheme. |
-
-```markdown
-[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/<OWNER>/<REPO>/releases/latest/download/<PACKAGE_NAME>.mcpb)
-[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=<PACKAGE_NAME>&config=<BASE64_CONFIG>)
-[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?<URLENCODED_JSON>)
-```
-
-Both install links route through HTTPS endpoints (`cursor.com/en/install-mcp` and `vscode.dev/redirect`) — GitHub-rendered markdown strips non-HTTP URL schemes from anchors, so a raw `cursor://` or `vscode:` link won't click through from github.com.
-
-Generate the encoded configs (replace `<PACKAGE_NAME>` and add env vars for any required API keys):
-
-```bash
-# Cursor: base64-encoded JSON. Split command/args, add env when keys are needed.
-echo -n '{"command":"npx","args":["-y","<PACKAGE_NAME>"],"env":{"API_KEY":"your-api-key"}}' | base64
-# Without env (no required keys):
-echo -n '{"command":"npx","args":["-y","<PACKAGE_NAME>"]}' | base64
-
-# VS Code: URL-encoded JSON. Same shape plus a `name` field.
-node -p 'encodeURIComponent(JSON.stringify({name:"<SHORT_NAME>",command:"npx",args:["-y","<PACKAGE_NAME>"],env:{API_KEY:"your-api-key"}}))'
-# Without env:
-node -p 'encodeURIComponent(JSON.stringify({name:"<SHORT_NAME>",command:"npx",args:["-y","<PACKAGE_NAME>"]}))'
-```
-
-Both clients use the same `{command, args, env}` shape (matching `mcp.json` schema). VS Code adds a top-level `name` field. Omit `env` entirely when no API keys are needed — don't include empty objects or framework-only vars like `MCP_TRANSPORT_TYPE`.
-
-The Claude Desktop badge requires the bundle to ship with a stable filename — `bun run bundle` outputs `dist/<PACKAGE_NAME>.mcpb`, and `release-and-publish` attaches that file to the GitHub Release. `releases/latest/download/<PACKAGE_NAME>.mcpb` then redirects to the most recent release.
-
----
-
-## Changelog
-
-Directory-based, grouped by minor series via the `.x` semver-wildcard convention. Source of truth: `changelog/<major.minor>.x/<version>.md` (e.g. `changelog/0.1.x/0.1.0.md`) — one file per release, shipped in the npm package. At release, author the per-version file with a concrete version and date, then run `npm run changelog:build` to regenerate the rollup. `changelog/template.md` is a **pristine format reference** — never edited or moved; read it for the frontmatter + section layout when scaffolding. `CHANGELOG.md` is a **navigation index** (header + link + summary per version), regenerated by `npm run changelog:build` — devcheck hard-fails on drift; never hand-edit it.
-
-Each per-version file opens with YAML frontmatter:
-
-```markdown
----
-summary: "One-line headline, ≤350 chars"  # required — powers the rollup index
-breaking: false                            # optional — true flags breaking changes
-security: false                            # optional — true flags security fixes
----
-
-# 0.1.0 — YYYY-MM-DD
-...
-```
-
-`breaking: true` renders a `· ⚠️ Breaking` badge — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames). `security: true` renders a `· 🛡️ Security` badge and pairs with a `## Security` body section. When both are set, badges render `· ⚠️ Breaking · 🛡️ Security`.
-
-**Section order** (Keep a Changelog): Added, Changed, Deprecated, Removed, Fixed, Security. Include only sections with entries — don't ship empty headers.
-
-**Tag annotations** render as GitHub Release bodies via `--notes-from-tag`. They must be structured markdown — never a flat comma-separated string. Subject omits the version number (GitHub prepends it). See `changelog/template.md` for the full format reference.
-
----
-
-## Imports
-
-```ts
-// Framework — z is re-exported, no separate zod import needed
-import { tool, z } from '@cyanheads/mcp-ts-core';
-import { McpError, JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
-
-// Server's own code — via path alias
-import { getMyService } from '@/services/my-domain/my-service.js';
-```
-
----
-
-## Checklist
-
-- [ ] Zod schemas: all fields have `.describe()`, only JSON-Schema-serializable types (no `z.custom()`, `z.date()`, `z.transform()`, `z.bigint()`, `z.symbol()`, `z.void()`, `z.map()`, `z.set()`, `z.function()`, `z.nan()`)
-- [ ] Optional nested objects: handler guards for empty inner values from form-based clients (`if (input.obj?.field && ...)`, not just `if (input.obj)`). When regex/length constraints matter, use `z.union([z.literal(''), z.string().regex(...).describe(...)])` — literal variants are exempt from `describe-on-fields`.
-- [ ] JSDoc `@fileoverview` + `@module` on every file
-- [ ] `ctx.log` for logging, `ctx.state` for storage
-- [ ] Handlers throw on failure — error factories or plain `Error`, no try/catch
-- [ ] `format()` renders all data the LLM needs — different clients forward different surfaces (Claude Code → `structuredContent`, Claude Desktop → `content[]`); both must carry the same data
-- [ ] If wrapping external API: raw/domain/output schemas reviewed against real upstream sparsity/nullability before finalizing required vs optional fields
-- [ ] If wrapping external API: normalization and `format()` preserve uncertainty; do not fabricate facts from missing upstream data
-- [ ] If wrapping external API: tests include at least one sparse payload case with omitted upstream fields
-- [ ] Registered in `createApp()` arrays (directly or via barrel exports)
-- [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
-- [ ] `npm run devcheck` passes

package/changelog/0.1.x/0.1.0.md

@@ -1,22 +0,0 @@
----
-summary: "Initial release — LOC digital collections, Chronicling America newspaper search with full OCR, LCSH subject heading lookup, and collection browsing via MCP."
-breaking: false
----
-
-# 0.1.0 — 2026-05-24
-
-Initial release.
-
-## Added
-
-- `loc_search` — full-text search across LOC digital collections with format, date range, subject heading, and geographic location filters
-- `loc_get_item` — full metadata for a specific LOC item: contributors, subjects, rights, physical description, resource links, related items
-- `loc_search_newspapers` — historical newspaper page search (Chronicling America corpus) with OCR excerpts, date range, state, and publication title filters
-- `loc_get_newspaper_page` — full OCR text for a specific newspaper page; ALTO XML parsing with graceful `ocr_available: false` for image-only batches
-- `loc_search_subjects` — Library of Congress Subject Headings (LCSH) search via `id.loc.gov` suggest endpoint; returns standardized labels and URIs for use as `loc_search` subject filters
-- `loc_browse_collections` — lists and filters LOC curated digital collections; returns slugs usable as `partof` facet values in `loc_search`
-- `loc://item/{item_id}` resource — stable URI for injecting item metadata into agent context
-- `LocApiService` — LOC JSON API client with module-level rate-limit enforcement (20 req/min, 1-hour block on 429), configurable pacing delay, HTML-response detection, and out-of-range page handling (HTTP 400/520)
-- `LcLinkedDataService` — `id.loc.gov` subject suggest client
-- Server-level agent instructions: recommended tool-call order, two-hop newspaper workflow, rate-limit reminder
-- 81 tests (7 test files) covering all tools and the item resource

package/changelog/0.1.x/0.1.1.md

@@ -1,29 +0,0 @@
----
-summary: "Initial npm publish — 6 tools, 1 resource, 81 tests, field-test fixes, and pre-launch polish"
-breaking: false
----
-
-# 0.1.1 — 2026-05-24
-
-First published release. Implements the full server surface, applies field-test fixes, and ships pre-launch polish over the initial scaffold tagged as 0.1.0.
-
-## Added
-
-- `loc_search` — full-text search across LOC digital collections with format, date range, subject heading, and geographic location filters
-- `loc_get_item` — full metadata for a specific LOC item: contributors, subjects, rights, physical description, resource links, related items
-- `loc_search_newspapers` — historical newspaper page search (Chronicling America corpus) with OCR excerpts, date range, state, and publication title filters
-- `loc_get_newspaper_page` — full OCR text for a specific newspaper page; ALTO XML parsing with graceful `ocr_available: false` for image-only batches
-- `loc_search_subjects` — LCSH subject heading lookup via `id.loc.gov` suggest endpoint; returns standardized labels and URIs
-- `loc_browse_collections` — curated LOC digital collections browser; returns slugs usable as `partof` facet values in `loc_search`
-- `loc://item/{item_id}` resource — stable URI for injecting item metadata into agent context
-- `LocApiService` — LOC JSON API client with module-level rate-limit enforcement (20 req/min, 1-hour block on 429), configurable pacing delay, HTML-response detection, and out-of-range page handling
-- `LcLinkedDataService` — `id.loc.gov` subject suggest client
-- Server-level agent instructions in `AGENTS.md`: recommended tool-call order, two-hop newspaper workflow, rate-limit reminder
-- 81 tests across 7 files covering all tools and the item resource
-
-## Fixed
-
-- `loc_search` and `loc_search_newspapers` — improved date range validation, field mapping corrections (`newspaper_title` from `partof_title` not `subject`), and sparse result handling
-- `loc_get_newspaper_page` — hardened ALTO XML parsing; added rate-limit detection and configurable retry guidance
-- `loc_get_item` — null-safety improvements for sparse upstream payloads
-- `LocApiService` — corrected field extraction, added structured handling for HTTP 429/400/520 responses

package/changelog/0.2.x/0.2.0.md

@@ -1,13 +0,0 @@
----
-summary: "Tool prefix renamed loc_* → libofcongress_*; resource URI renamed loc:// → libofcongress://"
-breaking: true
----
-
-# 0.2.0 — 2026-05-24
-
-## Changed
-
-- All six tools renamed: `loc_search` → `libofcongress_search`, `loc_get_item` → `libofcongress_get_item`, `loc_search_newspapers` → `libofcongress_search_newspapers`, `loc_get_newspaper_page` → `libofcongress_get_newspaper_page`, `loc_search_subjects` → `libofcongress_search_subjects`, `loc_browse_collections` → `libofcongress_browse_collections` ([#12](https://github.com/cyanheads/libofcongress-mcp-server/issues/12))
-- Resource URI renamed: `loc://item/{item_id}` → `libofcongress://item/{item_id}`
-- Tool and resource definition files renamed to match: `loc-*.tool.ts` → `libofcongress-*.tool.ts`, `loc-item.resource.ts` → `libofcongress-item.resource.ts`
-- Test files renamed to mirror the new filenames

package/changelog/0.2.x/0.2.1.md

@@ -1,14 +0,0 @@
----
-summary: "npm package scoped to @cyanheads/libofcongress-mcp-server"
-breaking: false
----
-
-# 0.2.1 — 2026-05-24
-
-## Fixed
-
-- **package name** corrected from bare `libofcongress-mcp-server` to `@cyanheads/libofcongress-mcp-server` — install via `npx -y @cyanheads/libofcongress-mcp-server`
-- **`server.json` identifiers** updated to `@cyanheads/libofcongress-mcp-server` in both stdio and HTTP package entries
-- **Cursor and VS Code install badges** recomputed with the scoped package name
-- **`bundle` script** switched from `npm run build` to `bun run build` for consistency with the rest of the scripts
-- **`author` field** aligned to the cyanheads convention (`cyanheads <casey@caseyjhand.com>`)

package/changelog/0.2.x/0.2.2.md

@@ -1,26 +0,0 @@
----
-summary: "Field-test fixes: rights crash, OCR extraction, out-of-range pagination, URL normalization, and tool-definition improvements"
-breaking: false
-security: false
----
-
-# 0.2.2 — 2026-05-24
-
-## Fixed
-
-- **`rights` crash** ([#13](https://github.com/cyanheads/libofcongress-mcp-server/issues/13)) — `rights` and `rights_information` typed as `string | string[]`; joined to a single string before return, preventing a type crash when LOC returns an array.
-- **OCR text extraction** ([#14](https://github.com/cyanheads/libofcongress-mcp-server/issues/14)) — `tile.loc.gov` returns JSON (`{ "<key>": { full_text: "..." } }`), not ALTO XML; extraction rewritten to parse the JSON shape. OCR test suite updated to match.
-- **Out-of-range pagination** ([#15](https://github.com/cyanheads/libofcongress-mcp-server/issues/15)) — `libofcongress_search`, `libofcongress_search_newspapers`, and `libofcongress_browse_collections` now return a clear `message` when `page` exceeds the available range, using `pages === 0` as the LOC 400 sentinel.
-- **Protocol-relative URL normalization** ([#16](https://github.com/cyanheads/libofcongress-mcp-server/issues/16)) — LOC sometimes returns `//lccn.loc.gov/...` URLs; normalized to `https:` before surfacing.
-- **`libofcongress_get_newspaper_page` error contract** ([#17](https://github.com/cyanheads/libofcongress-mcp-server/issues/17)) — handler now `async`; `NotFound` errors from the service are re-thrown as typed `page_not_found` failures via `ctx.fail`. Redundant URL-parse validation removed (prefix check is sufficient).
-- **`libofcongress_get_item` error contract** ([#18](https://github.com/cyanheads/libofcongress-mcp-server/issues/18)) — handler converted to `async`; `NotFound` errors re-thrown as typed `item_not_found` failures via `ctx.fail`.
-- **`libofcongress_search` and `libofcongress_search_newspapers` query input** ([#19](https://github.com/cyanheads/libofcongress-mcp-server/issues/19)) — `query` field gains `.trim()` to strip accidental leading/trailing whitespace before hitting the LOC API.
-
-## Changed
-
-- **`libofcongress_browse_collections` description** — removed incorrect claim that the `slug` value can be passed as a `partof` facet to `libofcongress_search` (that routing does not work); replaced with accurate description of the returned URL.
-- **`slug` output field description** — simplified to reflect actual semantics (identifies the collection in loc.gov URLs).
-- **`libofcongress://item` resource description** — removed redundant "Stable URI for injecting item context into agent conversations" sentence.
-- **`libofcongress_get_newspaper_page` `page_url` description** — replaced vague format description with a concrete example URL.
-- **`HTML_RESPONSE_RE` regex** — extracted to a module-level constant to avoid recompilation on every request.
-- **`normalizePagination` stub replaced** — `fetchSearchJson` returning `null` (LOC 400) now returns an explicit `{ pages: 0 }` sentinel object instead of calling the normalization helper with `undefined`.

package/changelog/template.md

@@ -1,119 +0,0 @@
----
-# FORMAT REFERENCE — do not edit. Copy this file to
-# `changelog/<major.minor>.x/<version>.md` (e.g. `changelog/0.8.x/0.8.6.md`)
-# to author a new release. Set that file's H1 to `# <version> — YYYY-MM-DD`
-# with a concrete date.
-
-# Required. One-line GitHub Release-style headline. 350 character cap.
-# Default short and scannable. Don't pad, don't stitch unrelated changes with
-# semicolons — pick the headline. Quotes required: unquoted YAML treats `: `
-# inside the value as a key separator and fails GitHub's strict parser.
-summary: ""
-
-# Set `true` when consumers must change code to upgrade: API removals,
-# signature changes, config renames, behavior changes that break existing
-# usage. Flagged as `Breaking` in the rollup.
-breaking: false
-
-# Set `true` if this release contains any security fix. Pairs with the
-# `## Security` section below. Flagged as `Security` in the rollup so
-# users can triage upgrade urgency at a glance.
-security: false
----
-
-# <version> — YYYY-MM-DD
-
-<!--
-  AUTHORING GUIDE — applies to the new per-version file you create from this
-  template.
-
-  Audience: someone scanning release notes to decide what affects them. Lead
-  each bullet with the symbol or concept name in **bold** so they can skip
-  what's irrelevant and zoom in on what's not.
-
-  Tone: terse, fact-dense, not verbose. Default to one sentence per bullet —
-  name the symbol, state what changed, stop. Use a second sentence only when
-  it carries weight. If a bullet feels long, it is.
-
-  Cut: mechanism walkthroughs (those belong in JSDoc, AGENTS.md, or the
-  relevant skill), ceremonial framings ("This release introduces…",
-  backwards-compat paragraphs), file-by-file test enumerations, internal
-  implementation notes. Prefer code/symbol names over English re-explanations.
-
-  Narrative intro: skip by default. Add one short sentence only when the
-  release theme genuinely needs framing the bullets can't carry.
-
-  Sections: Keep a Changelog order — Added, Changed, Deprecated, Removed,
-  Fixed, Security. Include only sections with entries; delete the rest
-  (including the commented-out scaffolding below). Don't ship empty headers.
-
-  Include: every distinct fact a reader needs to adopt or audit the release —
-  new exports, signatures, lint rule IDs, env vars, breaking changes, version
-  bumps on shipped skills. Nothing more.
-
-  Links: link issues, PRs, docs, or skills where they help a reader jump to
-  context. Once per item per entry — don't re-link the same issue in summary,
-  narrative, and bullet. Skip links for inline symbol names; code spans speak
-  for themselves.
-
-  Issue/PR URLs: use full URLs. GitHub's bare `#NN` auto-link only resolves
-  inside its own UI, not in npm reads or local editors.
-
-      [#38](https://github.com/cyanheads/mcp-ts-core/issues/38)   ← issue
-      [#42](https://github.com/cyanheads/mcp-ts-core/pull/42)     ← PR
-
-  Verify numbers exist before linking (`gh issue view NN`, `gh pr view NN`).
-  Never speculate on a future number — `#42` for an upcoming PR silently
-  resolves to whatever real item already owns 42, and timeline previews pull
-  in that unrelated item's metadata.
-
-  TAG ANNOTATIONS — the annotated tag body renders as the GitHub Release body
-  via `gh release create --notes-from-tag`. The tag is a derivative of this
-  changelog entry — a condensed, scannable version, not a copy. Format:
-
-    <theme — omit version number, GitHub prepends it>
-                                                          ← blank line
-    <1-2 sentence context: what this release does>
-                                                          ← blank line
-    Dependency bumps:                                     ← section header
-                                                          ← blank line
-    - `@cyanheads/mcp-ts-core` ^0.9.1 → ^0.9.6          ← bullet
-                                                          ← blank line
-    Changed:                                              ← only sections with entries
-                                                          ← blank line
-    - `format()` output includes `query` in text mode
-                                                          ← blank line
-    Added:
-                                                          ← blank line
-    - `manifest.json` scaffolded for MCPB bundle support
-    - Install badges (Claude Desktop, Cursor, VS Code)
-                                                          ← blank line
-    <N> tests pass; `bun run devcheck` clean.             ← footer
-
-  Never a flat comma-separated string. Always structured markdown with
-  sections. The tag must scan well as a rendered GitHub Release page.
--->
-
-## Added
-
--
-
-## Changed
-
--
-
-<!-- ## Deprecated
-
-- -->
-
-<!-- ## Removed
-
-- -->
-
-## Fixed
-
--
-
-<!-- ## Security
-
-- -->