@cyanheads/libofcongress-mcp-server 0.2.4 → 0.2.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/CLAUDE.md +14 -37
  2. package/README.md +1 -1
  3. package/dist/config/server-config.js +1 -1
  4. package/dist/index.js +4 -0
  5. package/dist/index.js.map +1 -1
  6. package/package.json +7 -7
  7. package/server.json +5 -5
  8. package/dist/libofcongress-mcp-server.mcpb +0 -0
package/CLAUDE.md CHANGED
@@ -1,8 +1,8 @@
1
1
  # Developer Protocol
2
2
 
3
3
  **Server:** libofcongress-mcp-server
4
- **Version:** 0.2.4
5
- **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.9.9`
4
+ **Version:** 0.2.5
5
+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.9.13`
6
6
  **Engines:** Bun ≥1.3.0, Node ≥24.0.0
7
7
  **MCP SDK:** `@modelcontextprotocol/sdk` ^1.29.0
8
8
  **Zod:** ^4.4.3
@@ -113,7 +113,7 @@ import { z } from '@cyanheads/mcp-ts-core';
113
113
  import { parseEnvConfig } from '@cyanheads/mcp-ts-core/config';
114
114
 
115
115
  const ServerConfigSchema = z.object({
116
- userAgent: z.string().default('libofcongress-mcp-server/0.2.4').describe('User-Agent header for LOC API requests.'),
116
+ userAgent: z.string().default('libofcongress-mcp-server/0.2.5').describe('User-Agent header for LOC API requests.'),
117
117
  requestDelayMs: z.coerce.number().default(3100).describe('Delay in ms between LOC API requests.'),
118
118
  });
119
119
 
@@ -155,6 +155,8 @@ Handlers throw — the framework catches, classifies, and formats.
155
155
  **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.
156
156
 
157
157
  ```ts
158
+ import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
159
+
158
160
  errors: [
159
161
  { reason: 'no_match', code: JsonRpcErrorCode.NotFound,
160
162
  when: 'No item matched the query',
@@ -248,9 +250,13 @@ Available skills:
248
250
  | `add-service` | Scaffold a new service integration |
249
251
  | `add-test` | Scaffold test file for a tool, resource, or service |
250
252
  | `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
253
+ | `tool-defs-analysis` | Read-only audit of MCP definition language across the surface — voice, leaks, defaults, recovery hints, output descriptions |
251
254
  | `security-pass` | Audit server for MCP-flavored security gaps: output injection, scope blast radius, input sinks, tenant isolation |
255
+ | `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase |
252
256
  | `devcheck` | Lint, format, typecheck, audit |
253
257
  | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
258
+ | `git-wrapup` | Land working-tree changes as a versioned commit + annotated tag — version bump, changelog, verify, tag. Local only. |
259
+ | `release-and-publish` | Push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
254
260
  | `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
255
261
  | `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
256
262
  | `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
@@ -259,6 +265,7 @@ Available skills:
259
265
  | `api-config` | AppConfig, parseConfig, env vars |
260
266
  | `api-context` | Context interface, logger, state, progress |
261
267
  | `api-errors` | McpError, JsonRpcErrorCode, error patterns |
268
+ | `api-linter` | Definition linter rule catalog — invoked by `bun run lint:mcp` and `devcheck` |
262
269
  | `api-services` | LLM, Speech, Graph services |
263
270
  | `api-testing` | createMockContext, test patterns |
264
271
  | `api-utils` | Formatting, parsing, security, pagination, scheduling, telemetry helpers |
@@ -297,40 +304,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
297
304
 
298
305
  **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.
299
306
 
300
- **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.
301
-
302
- | Client | Mechanism |
303
- |:-------|:----------|
304
- | 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. |
305
- | Cursor | Official `https://cursor.com/en/install-mcp` endpoint with base64 JSON config. |
306
- | 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. |
307
- | Claude Code / Codex | CLI only (`claude mcp add` / `codex mcp add`); no URL scheme. |
308
-
309
- ```markdown
310
- [![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)
311
- [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=<PACKAGE_NAME>&config=<BASE64_CONFIG>)
312
- [![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>)
313
- ```
314
-
315
- 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.
316
-
317
- Generate the encoded configs (replace `<PACKAGE_NAME>` and add env vars for any required API keys):
318
-
319
- ```bash
320
- # Cursor: base64-encoded JSON. Split command/args, add env when keys are needed.
321
- echo -n '{"command":"npx","args":["-y","<PACKAGE_NAME>"],"env":{"API_KEY":"your-api-key"}}' | base64
322
- # Without env (no required keys):
323
- echo -n '{"command":"npx","args":["-y","<PACKAGE_NAME>"]}' | base64
324
-
325
- # VS Code: URL-encoded JSON. Same shape plus a `name` field.
326
- node -p 'encodeURIComponent(JSON.stringify({name:"<SHORT_NAME>",command:"npx",args:["-y","<PACKAGE_NAME>"],env:{API_KEY:"your-api-key"}}))'
327
- # Without env:
328
- node -p 'encodeURIComponent(JSON.stringify({name:"<SHORT_NAME>",command:"npx",args:["-y","<PACKAGE_NAME>"]}))'
329
- ```
330
-
331
- 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`.
332
-
333
- 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.
307
+ **README install badges** (Claude Desktop `.mcpb`, Cursor, VS Code) and the `base64` / `encodeURIComponent` config-generation commands are ship-time concerns — run the `polish-docs-meta` skill, which carries the badge format, layout, and generation snippets in `skills/polish-docs-meta/references/readme.md`.
334
308
 
335
309
  ---
336
310
 
@@ -385,4 +359,7 @@ import { getMyService } from '@/services/my-domain/my-service.js';
385
359
  - [ ] If wrapping external API: tests include at least one sparse payload case with omitted upstream fields
386
360
  - [ ] Registered in `createApp()` arrays (directly or via barrel exports)
387
361
  - [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
362
+ - [ ] `.codex-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; `interface.displayName` = package name; `interface.shortDescription` from `package.json` description
363
+ - [ ] `.codex-plugin/mcp.json` updated — server name key matches `package.json` name; env vars added for any required API keys
364
+ - [ ] `.claude-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; inline `mcpServers` entry with server name key, env vars for any required API keys
388
365
  - [ ] `npm run devcheck` passes
package/README.md CHANGED
@@ -7,7 +7,7 @@
7
7
 
8
8
  <div align="center">
9
9
 
10
- [![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/)
10
+ [![Version](https://img.shields.io/badge/Version-0.2.5-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-^6.0.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/)
11
11
 
12
12
  </div>
13
13
 
package/dist/config/server-config.js CHANGED
@@ -7,7 +7,7 @@ import { parseEnvConfig } from '@cyanheads/mcp-ts-core/config';
7
7
  const ServerConfigSchema = z.object({
8
8
  userAgent: z
9
9
  .string()
10
- .default('libofcongress-mcp-server/0.2.3')
10
+ .default('libofcongress-mcp-server/0.2.5')
11
11
  .describe('User-Agent header sent with LOC API requests. LOC recommends a descriptive value for polite access.'),
12
12
  requestDelayMs: z.coerce
13
13
  .number()
package/dist/index.js CHANGED
@@ -27,6 +27,10 @@ await createApp({
27
27
  instructions: 'Library of Congress digital collections server. Use libofcongress_search_subjects to find exact LCSH terms before subject-filtering libofcongress_search. ' +
28
28
  'Newspaper research: libofcongress_search_newspapers → libofcongress_get_newspaper_page (two hops). ' +
29
29
  'Rate limit: 20 req/min; violations block for 1 hour.',
30
+ landing: {
31
+ // Public hosted catalog — serve full inventory without auth requirement.
32
+ requireAuth: false,
33
+ },
30
34
  setup(core) {
31
35
  initLocApiService(core.config, core.storage);
32
36
  initLcLinkedDataService(core.config, core.storage);
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,mEAAmE,CAAC;AACpG,OAAO,EAAE,oBAAoB,EAAE,MAAM,yEAAyE,CAAC;AAC/G,OAAO,EAAE,UAAU,EAAE,MAAM,+DAA+D,CAAC;AAC3F,OAAO,EAAE,mBAAmB,EAAE,MAAM,yEAAyE,CAAC;AAC9G,OAAO,EAAE,SAAS,EAAE,MAAM,6DAA6D,CAAC;AACxF,OAAO,EAAE,mBAAmB,EAAE,MAAM,wEAAwE,CAAC;AAC7G,OAAO,EAAE,iBAAiB,EAAE,MAAM,sEAAsE,CAAC;AACzG,OAAO,EAAE,uBAAuB,EAAE,MAAM,qDAAqD,CAAC;AAC9F,OAAO,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAE1E,MAAM,SAAS,CAAC;IACd,KAAK,EAAE;QACL,SAAS;QACT,UAAU;QACV,mBAAmB;QACnB,mBAAmB;QACnB,iBAAiB;QACjB,oBAAoB;KACrB;IACD,SAAS,EAAE,CAAC,eAAe,CAAC;IAC5B,OAAO,EAAE,EAAE;IACX,YAAY,EACV,4JAA4J;QAC5J,qGAAqG;QACrG,sDAAsD;IACxD,KAAK,CAAC,IAAI;QACR,iBAAiB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAC7C,uBAAuB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IACrD,CAAC;CACF,CAAC,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,mEAAmE,CAAC;AACpG,OAAO,EAAE,oBAAoB,EAAE,MAAM,yEAAyE,CAAC;AAC/G,OAAO,EAAE,UAAU,EAAE,MAAM,+DAA+D,CAAC;AAC3F,OAAO,EAAE,mBAAmB,EAAE,MAAM,yEAAyE,CAAC;AAC9G,OAAO,EAAE,SAAS,EAAE,MAAM,6DAA6D,CAAC;AACxF,OAAO,EAAE,mBAAmB,EAAE,MAAM,wEAAwE,CAAC;AAC7G,OAAO,EAAE,iBAAiB,EAAE,MAAM,sEAAsE,CAAC;AACzG,OAAO,EAAE,uBAAuB,EAAE,MAAM,qDAAqD,CAAC;AAC9F,OAAO,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAE1E,MAAM,SAAS,CAAC;IACd,KAAK,EAAE;QACL,SAAS;QACT,UAAU;QACV,mBAAmB;QACnB,mBAAmB;QACnB,iBAAiB;QACjB,oBAAoB;KACrB;IACD,SAAS,EAAE,CAAC,eAAe,CAAC;IAC5B,OAAO,EAAE,EAAE;IACX,YAAY,EACV,4JAA4J;QAC5J,qGAAqG;QACrG,sDAAsD;IACxD,OAAO,EAAE;QACP,yEAAyE;QACzE,WAAW,EAAE,KAAK;KACnB;IACD,KAAK,CAAC,IAAI;QACR,iBAAiB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAC7C,uBAAuB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IACrD,CAAC;CACF,CAAC,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cyanheads/libofcongress-mcp-server",
3
- "version": "0.2.4",
3
+ "version": "0.2.5",
4
4
  "mcpName": "io.github.cyanheads/libofcongress-mcp-server",
5
5
  "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.",
6
6
  "type": "module",
@@ -75,17 +75,17 @@
75
75
  "access": "public"
76
76
  },
77
77
  "dependencies": {
78
- "@cyanheads/mcp-ts-core": "^0.9.9",
78
+ "@cyanheads/mcp-ts-core": "^0.9.13",
79
79
  "pino-pretty": "^13.1.3",
80
80
  "zod": "^4.4.3"
81
81
  },
82
82
  "devDependencies": {
83
- "@biomejs/biome": "^2.4.7",
84
- "@types/node": "^25.6.0",
83
+ "@biomejs/biome": "^2.4.16",
84
+ "@types/node": "^25.9.1",
85
85
  "depcheck": "^1.4.7",
86
86
  "ignore": "^7.0.5",
87
- "tsc-alias": "^1.8.16",
88
- "typescript": "^5.9.3",
89
- "vitest": "^4.1.0"
87
+ "tsc-alias": "^1.8.17",
88
+ "typescript": "^6.0.3",
89
+ "vitest": "^4.1.7"
90
90
  }
91
91
  }
package/server.json CHANGED
@@ -6,14 +6,14 @@
6
6
  "url": "https://github.com/cyanheads/libofcongress-mcp-server",
7
7
  "source": "github"
8
8
  },
9
- "version": "0.2.4",
9
+ "version": "0.2.5",
10
10
  "packages": [
11
11
  {
12
12
  "registryType": "npm",
13
13
  "registryBaseUrl": "https://registry.npmjs.org",
14
14
  "identifier": "@cyanheads/libofcongress-mcp-server",
15
15
  "runtimeHint": "bun",
16
- "version": "0.2.4",
16
+ "version": "0.2.5",
17
17
  "packageArguments": [
18
18
  {
19
19
  "type": "positional",
@@ -30,7 +30,7 @@
30
30
  "description": "User-Agent header sent with LOC API requests. LOC recommends a descriptive value for polite access.",
31
31
  "format": "string",
32
32
  "isRequired": false,
33
- "default": "libofcongress-mcp-server/0.2.4"
33
+ "default": "libofcongress-mcp-server/0.2.5"
34
34
  },
35
35
  {
36
36
  "name": "LOC_REQUEST_DELAY_MS",
@@ -56,7 +56,7 @@
56
56
  "registryBaseUrl": "https://registry.npmjs.org",
57
57
  "identifier": "@cyanheads/libofcongress-mcp-server",
58
58
  "runtimeHint": "bun",
59
- "version": "0.2.4",
59
+ "version": "0.2.5",
60
60
  "packageArguments": [
61
61
  {
62
62
  "type": "positional",
@@ -73,7 +73,7 @@
73
73
  "description": "User-Agent header sent with LOC API requests. LOC recommends a descriptive value for polite access.",
74
74
  "format": "string",
75
75
  "isRequired": false,
76
- "default": "libofcongress-mcp-server/0.2.4"
76
+ "default": "libofcongress-mcp-server/0.2.5"
77
77
  },
78
78
  {
79
79
  "name": "LOC_REQUEST_DELAY_MS",
package/dist/libofcongress-mcp-server.mcpb DELETED
Binary file