@cyanheads/faa-aircraft-registry-mcp-server 0.1.7 → 0.1.8

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 (43) hide show
  1. package/AGENTS.md +34 -28
  2. package/CLAUDE.md +34 -28
  3. package/Dockerfile +8 -6
  4. package/README.md +5 -3
  5. package/changelog/0.1.x/0.1.8.md +33 -0
  6. package/changelog/template.md +55 -16
  7. package/dist/index.d.ts +2 -1
  8. package/dist/index.d.ts.map +1 -1
  9. package/dist/index.js +2 -2
  10. package/dist/index.js.map +1 -1
  11. package/dist/mcp-server/resources/definitions/index.d.ts +2 -2
  12. package/dist/mcp-server/resources/definitions/registration.resource.d.ts +2 -2
  13. package/dist/mcp-server/resources/definitions/registration.resource.d.ts.map +1 -1
  14. package/dist/mcp-server/resources/definitions/registration.resource.js +4 -3
  15. package/dist/mcp-server/resources/definitions/registration.resource.js.map +1 -1
  16. package/dist/mcp-server/tools/definitions/_schemas.d.ts.map +1 -1
  17. package/dist/mcp-server/tools/definitions/_schemas.js +6 -18
  18. package/dist/mcp-server/tools/definitions/_schemas.js.map +1 -1
  19. package/dist/mcp-server/tools/definitions/get-aircraft-type.tool.d.ts +2 -2
  20. package/dist/mcp-server/tools/definitions/get-aircraft-type.tool.js +3 -3
  21. package/dist/mcp-server/tools/definitions/get-aircraft-type.tool.js.map +1 -1
  22. package/dist/mcp-server/tools/definitions/get-registration-status.tool.d.ts +3 -3
  23. package/dist/mcp-server/tools/definitions/get-registration-status.tool.d.ts.map +1 -1
  24. package/dist/mcp-server/tools/definitions/get-registration-status.tool.js +3 -3
  25. package/dist/mcp-server/tools/definitions/get-registration-status.tool.js.map +1 -1
  26. package/dist/mcp-server/tools/definitions/index.d.ts +74 -74
  27. package/dist/mcp-server/tools/definitions/lookup-registration.tool.d.ts +2 -2
  28. package/dist/mcp-server/tools/definitions/lookup-registration.tool.js +3 -3
  29. package/dist/mcp-server/tools/definitions/lookup-registration.tool.js.map +1 -1
  30. package/dist/mcp-server/tools/definitions/search-aircraft-types.tool.d.ts +1 -1
  31. package/dist/mcp-server/tools/definitions/search-aircraft-types.tool.js +2 -2
  32. package/dist/mcp-server/tools/definitions/search-aircraft-types.tool.js.map +1 -1
  33. package/dist/mcp-server/tools/definitions/search-registrations.tool.d.ts +2 -2
  34. package/dist/mcp-server/tools/definitions/search-registrations.tool.js +3 -3
  35. package/dist/mcp-server/tools/definitions/search-registrations.tool.js.map +1 -1
  36. package/dist/services/registry/decode.d.ts.map +1 -1
  37. package/dist/services/registry/registry-service.d.ts.map +1 -1
  38. package/dist/services/registry/registry-service.js +3 -3
  39. package/dist/services/registry/registry-service.js.map +1 -1
  40. package/dist/services/registry/schema.d.ts +3 -3
  41. package/dist/services/registry/schema.d.ts.map +1 -1
  42. package/package.json +12 -12
  43. package/server.json +3 -3
package/AGENTS.md CHANGED
@@ -1,10 +1,10 @@
1
1
  # Developer Protocol
2
2
 
3
3
  **Server:** faa-aircraft-registry-mcp-server
4
- **Version:** 0.1.7
5
- **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.10.14`
4
+ **Version:** 0.1.8
5
+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.12.3`
6
6
  **Engines:** Bun ≥1.3.0, Node ≥24.0.0
7
- **MCP SDK:** `@modelcontextprotocol/sdk` ^1.29.0
7
+ **MCP SDK:** `@modelcontextprotocol/server` ^2.0.0 (protocol revisions 2026-07-28 and 2025-*)
8
8
  **Zod:** ^4.4.3
9
9
 
10
10
  > **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.
@@ -26,7 +26,7 @@ An offline lookup server for the US civil aircraft registry. It indexes the FAA'
26
26
  - **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.
27
27
  - **Use `ctx.log`** for request-scoped logging. No `console` calls.
28
28
  - **Use `ctx.state`** for tenant-scoped storage. Never access persistence directly.
29
- - **Check `ctx.elicit`** for presence before calling.
29
+ - **Need input the caller didn't supply?** `return ctx.requestInput(...)` and read `ctx.inputs` when the handler is re-entered. Never await input mid-handler.
30
30
  - **Secrets in env vars only** — never hardcoded.
31
31
  - **Close the loop on issues.** When implementing work tracked by a GitHub issue, comment on the issue with what landed and close it. Do both — a comment without a close leaves stale issues open; a close without a comment leaves no record of what shipped. The comment is for future readers — state the concrete changes, not the conversation that produced them.
32
32
 
@@ -94,6 +94,7 @@ export const registrationResource = resource('faa://registration/{nNumber}', {
94
94
  title: 'faa-aircraft-registry-mcp-server: registration record',
95
95
  description: 'Full registration record for one N-number — same payload as faa_lookup_registration.',
96
96
  mimeType: 'application/json',
97
+ cacheHint: { ttlMs: 3_600_000, cacheScope: 'private' },
97
98
  params: z.object({
98
99
  nNumber: z.string().min(1).describe('N-number. Accepts "N12345" or "12345".'),
99
100
  }),
@@ -164,7 +165,6 @@ For env booleans use `z.stringbool()`, never `z.coerce.boolean()` — `Boolean("
164
165
  await createApp({
165
166
  name: 'faa-aircraft-registry-mcp-server', // machine name on every surface — never Title Case
166
167
  title: 'faa-aircraft-registry-mcp-server', // display identity = the hyphenated repo name
167
- websiteUrl: 'https://github.com/cyanheads/faa-aircraft-registry-mcp-server',
168
168
  tools: allToolDefinitions,
169
169
  resources: allResourceDefinitions,
170
170
  instructions: 'Offline, keyless lookup of the US civil aircraft registry … The index must be built once via the mirror:init script before queries succeed.',
@@ -185,13 +185,14 @@ Handlers receive a unified `ctx` object. Key properties:
185
185
 
186
186
  | Property | Description |
187
187
  |:---------|:------------|
188
- | `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. |
188
+ | `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. Client-visible through `notifications/message`. |
189
189
  | `ctx.fail` / `ctx.recoveryFor` | Throw a typed contract error by `reason` (`ctx.fail`); pull the declared `recovery` metadata for the throw site (`ctx.recoveryFor`). Used by every tool/resource. |
190
- | `ctx.enrich` | Out-of-band response enrichment — `.truncated({ shown, cap })` when a search hits its limit, `.notice(msg)` when no rows match. Used by the search tools. |
190
+ | `ctx.enrich` | Success-path response enrichment — `.truncated({ shown, cap })`, `.notice(msg)`, and `.total(count)`. Reaches both `structuredContent` and `content[]`. |
191
+ | `ctx.content` | Non-text content blocks appended to `content[]`; unused by this text/JSON-only server. |
191
192
  | `ctx.signal` | `AbortSignal` for cancellation — threaded into the mirror sync run. |
192
193
  | `ctx.requestId` | Unique request ID. |
193
194
 
194
- This server is read-only over the local mirror: no `ctx.state` (the index is the store, accessed via `registry-service`), no `ctx.elicit` (no interactive input), no `ctx.progress` (no task-mode tools).
195
+ This server is read-only over the local mirror and explicitly stateless: no `ctx.state` (the index is the store, accessed via `registry-service`), no `ctx.requestInput`/`ctx.inputs` call sites, and no task surfaces.
195
196
 
196
197
  ---
197
198
 
@@ -218,6 +219,8 @@ async handler(input, ctx) {
218
219
 
219
220
  The cold-mirror case (a never-initialized index) is a service-layer `ServiceUnavailable` raised in `registry-service`, common to every tool — its recovery hint points to `mirror:init`. There is no live API fallback, so it surfaces loudly rather than returning an empty result.
220
221
 
222
+ `InvalidParams` is reserved for malformed JSON-RPC parameter shape rejected at the schema boundary. Post-Zod domain checks — malformed N-numbers, malformed manufacturer/model codes, missing search filters, and redaction-gated owner searches — use `ValidationError`.
223
+
221
224
  **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.
222
225
 
223
226
  **Fallback (no contract entry fits):** throw via factories or plain `Error`.
@@ -289,7 +292,7 @@ scripts/
289
292
 
290
293
  ## Skills
291
294
 
292
- 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.
295
+ 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. `bun run list-skills` prints the full registry.
293
296
 
294
297
  **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.
295
298
 
@@ -320,7 +323,7 @@ Available skills:
320
323
  | `api-auth` | Auth modes, scopes, JWT/OAuth |
321
324
  | `api-canvas` | DataCanvas: register tabular data, run SQL, export, plus the `spillover()` helper for big result sets — Tier 3 opt-in |
322
325
  | `api-config` | AppConfig, parseConfig, env vars |
323
- | `api-context` | Context interface, logger, state, progress |
326
+ | `api-context` | Context interface, RequestContext, logger, state, multi-round-trip input |
324
327
  | `api-errors` | McpError, JsonRpcErrorCode, error patterns |
325
328
  | `api-linter` | Definition linter rule catalog — invoked by `bun run lint:mcp` and `devcheck` |
326
329
  | `api-mirror` | MirrorService reference — the embedded SQLite + FTS5 mirror this server is built on (ingester, sync state, scheduling). Read before touching `registry-service` or the ingest path. |
@@ -342,29 +345,32 @@ When you complete a skill's checklist, check the boxes and add a completion time
342
345
 
343
346
  | Command | Purpose |
344
347
  |:--------|:--------|
345
- | `npm run build` | Compile TypeScript |
346
- | `npm run rebuild` | Clean + build |
347
- | `npm run clean` | Remove build artifacts |
348
- | `npm run devcheck` | Lint + format + typecheck + security + changelog sync |
348
+ | `bun run build` | Compile TypeScript |
349
+ | `bun run rebuild` | Clean + build |
350
+ | `bun run clean` | Remove build artifacts |
351
+ | `bun run devcheck` | Lint + format + typecheck + security + changelog sync |
349
352
  | `bun run audit:refresh` | Delete `bun.lock`, reinstall, and re-run `bun audit`. Use when `devcheck` flags a transitive advisory — Bun's `update` is sticky on transitive resolutions, so the advisory may be a stale-lockfile false positive. If it survives the refresh, it's real. |
350
- | `npm run tree` | Generate directory structure doc |
351
- | `npm run format` | Auto-fix formatting (safe fixes only) |
352
- | `npm run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
353
- | `npm test` | Run tests |
353
+ | `bun run lint:mcp` | Run the MCP definition linter standalone |
354
+ | `bun run lint:packaging` | Verify packaging-surface consistency |
355
+ | `bun run list-skills` | Print the skill registry |
356
+ | `bun run tree` | Generate directory structure doc |
357
+ | `bun run format` | Auto-fix formatting (safe fixes only) |
358
+ | `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
359
+ | `bun run test` | Run tests (Vitest — do not use `bun test`) |
354
360
  | `bun run mirror:init` | Build the SQLite registry index from the FAA ZIP — full out-of-band build. Run once before first use; idempotent and resumable. Never on server startup. |
355
361
  | `bun run mirror:refresh` | Rebuild the index from the latest FAA release. The HTTP server schedules this daily; stdio operators run it out-of-band. |
356
362
  | `bun run mirror:verify` | Report index health — readiness, sync status, record count, SQLite integrity check. Exits non-zero when not ready or integrity fails. |
357
- | `npm run start:stdio` | Production mode (stdio) |
358
- | `npm run start:http` | Production mode (HTTP) |
359
- | `npm run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
360
- | `npm run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
361
- | `npm run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install |
363
+ | `bun run start:stdio` | Production mode (stdio) |
364
+ | `bun run start:http` | Production mode (HTTP) |
365
+ | `bun run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
366
+ | `bun run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
367
+ | `bun run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install |
362
368
 
363
369
  ---
364
370
 
365
371
  ## Bundling
366
372
 
367
- `npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips dependency-shipped agent docs (`node_modules/**` `skills/`, `.claude/`, `.agents/`, `SKILL.md`) that root-anchored `.mcpbignore` patterns cannot reach. 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.
373
+ `bun run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The cleanup step prunes dev dependencies and strips dependency-shipped agent docs plus platform-specific native bindings that root-anchored `.mcpbignore` patterns cannot reach. MCPB is stdio-only — HTTP deployments are unaffected.
368
374
 
369
375
  **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.
370
376
 
@@ -374,7 +380,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
374
380
 
375
381
  ## Changelog
376
382
 
377
- 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.
383
+ 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 `bun 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 `bun run changelog:build` — devcheck hard-fails on drift; never hand-edit it.
378
384
 
379
385
  Each per-version file opens with YAML frontmatter:
380
386
 
@@ -382,14 +388,14 @@ Each per-version file opens with YAML frontmatter:
382
388
  ---
383
389
  summary: "One-line headline, ≤350 chars" # required — powers the rollup index
384
390
  breaking: false # optional — true flags breaking changes
385
- security: false # optional — true flags security fixes
391
+ security: false # optional — true only for a source-code security fix
386
392
  ---
387
393
 
388
394
  # 0.1.0 — YYYY-MM-DD
389
395
  ...
390
396
  ```
391
397
 
392
- `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`.
398
+ `breaking: true` renders a `· ⚠️ Breaking` badge — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames). `security: true` is only for a security fix in this server's own source, never a routine dependency advisory; dependency fixes belong under `## Dependencies`.
393
399
 
394
400
  `agent-notes` is an optional free-form field for maintenance agents processing the release downstream. Content here won't appear in the rendered CHANGELOG — it's consumed by agents running the `maintenance` skill. Use it for adoption instructions that don't fit the human-facing sections: new files to create, fields to populate, one-time migration steps. Omit entirely when there's nothing to say.
395
401
 
@@ -430,4 +436,4 @@ import { getRegistryService } from '@/services/registry/registry-service.js';
430
436
  - [ ] `.codex-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; `interface.displayName` = package name; `interface.shortDescription` from `package.json` description
431
437
  - [ ] `.codex-plugin/mcp.json` updated — server name key matches `package.json` name; env vars added for any required API keys
432
438
  - [ ] `.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
433
- - [ ] `npm run devcheck` passes
439
+ - [ ] `bun run devcheck` passes
package/CLAUDE.md CHANGED
@@ -1,10 +1,10 @@
1
1
  # Developer Protocol
2
2
 
3
3
  **Server:** faa-aircraft-registry-mcp-server
4
- **Version:** 0.1.7
5
- **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.10.14`
4
+ **Version:** 0.1.8
5
+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.12.3`
6
6
  **Engines:** Bun ≥1.3.0, Node ≥24.0.0
7
- **MCP SDK:** `@modelcontextprotocol/sdk` ^1.29.0
7
+ **MCP SDK:** `@modelcontextprotocol/server` ^2.0.0 (protocol revisions 2026-07-28 and 2025-*)
8
8
  **Zod:** ^4.4.3
9
9
 
10
10
  > **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.
@@ -26,7 +26,7 @@ An offline lookup server for the US civil aircraft registry. It indexes the FAA'
26
26
  - **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.
27
27
  - **Use `ctx.log`** for request-scoped logging. No `console` calls.
28
28
  - **Use `ctx.state`** for tenant-scoped storage. Never access persistence directly.
29
- - **Check `ctx.elicit`** for presence before calling.
29
+ - **Need input the caller didn't supply?** `return ctx.requestInput(...)` and read `ctx.inputs` when the handler is re-entered. Never await input mid-handler.
30
30
  - **Secrets in env vars only** — never hardcoded.
31
31
  - **Close the loop on issues.** When implementing work tracked by a GitHub issue, comment on the issue with what landed and close it. Do both — a comment without a close leaves stale issues open; a close without a comment leaves no record of what shipped. The comment is for future readers — state the concrete changes, not the conversation that produced them.
32
32
 
@@ -94,6 +94,7 @@ export const registrationResource = resource('faa://registration/{nNumber}', {
94
94
  title: 'faa-aircraft-registry-mcp-server: registration record',
95
95
  description: 'Full registration record for one N-number — same payload as faa_lookup_registration.',
96
96
  mimeType: 'application/json',
97
+ cacheHint: { ttlMs: 3_600_000, cacheScope: 'private' },
97
98
  params: z.object({
98
99
  nNumber: z.string().min(1).describe('N-number. Accepts "N12345" or "12345".'),
99
100
  }),
@@ -164,7 +165,6 @@ For env booleans use `z.stringbool()`, never `z.coerce.boolean()` — `Boolean("
164
165
  await createApp({
165
166
  name: 'faa-aircraft-registry-mcp-server', // machine name on every surface — never Title Case
166
167
  title: 'faa-aircraft-registry-mcp-server', // display identity = the hyphenated repo name
167
- websiteUrl: 'https://github.com/cyanheads/faa-aircraft-registry-mcp-server',
168
168
  tools: allToolDefinitions,
169
169
  resources: allResourceDefinitions,
170
170
  instructions: 'Offline, keyless lookup of the US civil aircraft registry … The index must be built once via the mirror:init script before queries succeed.',
@@ -185,13 +185,14 @@ Handlers receive a unified `ctx` object. Key properties:
185
185
 
186
186
  | Property | Description |
187
187
  |:---------|:------------|
188
- | `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. |
188
+ | `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. Client-visible through `notifications/message`. |
189
189
  | `ctx.fail` / `ctx.recoveryFor` | Throw a typed contract error by `reason` (`ctx.fail`); pull the declared `recovery` metadata for the throw site (`ctx.recoveryFor`). Used by every tool/resource. |
190
- | `ctx.enrich` | Out-of-band response enrichment — `.truncated({ shown, cap })` when a search hits its limit, `.notice(msg)` when no rows match. Used by the search tools. |
190
+ | `ctx.enrich` | Success-path response enrichment — `.truncated({ shown, cap })`, `.notice(msg)`, and `.total(count)`. Reaches both `structuredContent` and `content[]`. |
191
+ | `ctx.content` | Non-text content blocks appended to `content[]`; unused by this text/JSON-only server. |
191
192
  | `ctx.signal` | `AbortSignal` for cancellation — threaded into the mirror sync run. |
192
193
  | `ctx.requestId` | Unique request ID. |
193
194
 
194
- This server is read-only over the local mirror: no `ctx.state` (the index is the store, accessed via `registry-service`), no `ctx.elicit` (no interactive input), no `ctx.progress` (no task-mode tools).
195
+ This server is read-only over the local mirror and explicitly stateless: no `ctx.state` (the index is the store, accessed via `registry-service`), no `ctx.requestInput`/`ctx.inputs` call sites, and no task surfaces.
195
196
 
196
197
  ---
197
198
 
@@ -218,6 +219,8 @@ async handler(input, ctx) {
218
219
 
219
220
  The cold-mirror case (a never-initialized index) is a service-layer `ServiceUnavailable` raised in `registry-service`, common to every tool — its recovery hint points to `mirror:init`. There is no live API fallback, so it surfaces loudly rather than returning an empty result.
220
221
 
222
+ `InvalidParams` is reserved for malformed JSON-RPC parameter shape rejected at the schema boundary. Post-Zod domain checks — malformed N-numbers, malformed manufacturer/model codes, missing search filters, and redaction-gated owner searches — use `ValidationError`.
223
+
221
224
  **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.
222
225
 
223
226
  **Fallback (no contract entry fits):** throw via factories or plain `Error`.
@@ -289,7 +292,7 @@ scripts/
289
292
 
290
293
  ## Skills
291
294
 
292
- 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.
295
+ 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. `bun run list-skills` prints the full registry.
293
296
 
294
297
  **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.
295
298
 
@@ -320,7 +323,7 @@ Available skills:
320
323
  | `api-auth` | Auth modes, scopes, JWT/OAuth |
321
324
  | `api-canvas` | DataCanvas: register tabular data, run SQL, export, plus the `spillover()` helper for big result sets — Tier 3 opt-in |
322
325
  | `api-config` | AppConfig, parseConfig, env vars |
323
- | `api-context` | Context interface, logger, state, progress |
326
+ | `api-context` | Context interface, RequestContext, logger, state, multi-round-trip input |
324
327
  | `api-errors` | McpError, JsonRpcErrorCode, error patterns |
325
328
  | `api-linter` | Definition linter rule catalog — invoked by `bun run lint:mcp` and `devcheck` |
326
329
  | `api-mirror` | MirrorService reference — the embedded SQLite + FTS5 mirror this server is built on (ingester, sync state, scheduling). Read before touching `registry-service` or the ingest path. |
@@ -342,29 +345,32 @@ When you complete a skill's checklist, check the boxes and add a completion time
342
345
 
343
346
  | Command | Purpose |
344
347
  |:--------|:--------|
345
- | `npm run build` | Compile TypeScript |
346
- | `npm run rebuild` | Clean + build |
347
- | `npm run clean` | Remove build artifacts |
348
- | `npm run devcheck` | Lint + format + typecheck + security + changelog sync |
348
+ | `bun run build` | Compile TypeScript |
349
+ | `bun run rebuild` | Clean + build |
350
+ | `bun run clean` | Remove build artifacts |
351
+ | `bun run devcheck` | Lint + format + typecheck + security + changelog sync |
349
352
  | `bun run audit:refresh` | Delete `bun.lock`, reinstall, and re-run `bun audit`. Use when `devcheck` flags a transitive advisory — Bun's `update` is sticky on transitive resolutions, so the advisory may be a stale-lockfile false positive. If it survives the refresh, it's real. |
350
- | `npm run tree` | Generate directory structure doc |
351
- | `npm run format` | Auto-fix formatting (safe fixes only) |
352
- | `npm run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
353
- | `npm test` | Run tests |
353
+ | `bun run lint:mcp` | Run the MCP definition linter standalone |
354
+ | `bun run lint:packaging` | Verify packaging-surface consistency |
355
+ | `bun run list-skills` | Print the skill registry |
356
+ | `bun run tree` | Generate directory structure doc |
357
+ | `bun run format` | Auto-fix formatting (safe fixes only) |
358
+ | `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
359
+ | `bun run test` | Run tests (Vitest — do not use `bun test`) |
354
360
  | `bun run mirror:init` | Build the SQLite registry index from the FAA ZIP — full out-of-band build. Run once before first use; idempotent and resumable. Never on server startup. |
355
361
  | `bun run mirror:refresh` | Rebuild the index from the latest FAA release. The HTTP server schedules this daily; stdio operators run it out-of-band. |
356
362
  | `bun run mirror:verify` | Report index health — readiness, sync status, record count, SQLite integrity check. Exits non-zero when not ready or integrity fails. |
357
- | `npm run start:stdio` | Production mode (stdio) |
358
- | `npm run start:http` | Production mode (HTTP) |
359
- | `npm run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
360
- | `npm run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
361
- | `npm run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install |
363
+ | `bun run start:stdio` | Production mode (stdio) |
364
+ | `bun run start:http` | Production mode (HTTP) |
365
+ | `bun run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
366
+ | `bun run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
367
+ | `bun run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install |
362
368
 
363
369
  ---
364
370
 
365
371
  ## Bundling
366
372
 
367
- `npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips dependency-shipped agent docs (`node_modules/**` `skills/`, `.claude/`, `.agents/`, `SKILL.md`) that root-anchored `.mcpbignore` patterns cannot reach. 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.
373
+ `bun run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The cleanup step prunes dev dependencies and strips dependency-shipped agent docs plus platform-specific native bindings that root-anchored `.mcpbignore` patterns cannot reach. MCPB is stdio-only — HTTP deployments are unaffected.
368
374
 
369
375
  **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.
370
376
 
@@ -374,7 +380,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
374
380
 
375
381
  ## Changelog
376
382
 
377
- 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.
383
+ 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 `bun 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 `bun run changelog:build` — devcheck hard-fails on drift; never hand-edit it.
378
384
 
379
385
  Each per-version file opens with YAML frontmatter:
380
386
 
@@ -382,14 +388,14 @@ Each per-version file opens with YAML frontmatter:
382
388
  ---
383
389
  summary: "One-line headline, ≤350 chars" # required — powers the rollup index
384
390
  breaking: false # optional — true flags breaking changes
385
- security: false # optional — true flags security fixes
391
+ security: false # optional — true only for a source-code security fix
386
392
  ---
387
393
 
388
394
  # 0.1.0 — YYYY-MM-DD
389
395
  ...
390
396
  ```
391
397
 
392
- `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`.
398
+ `breaking: true` renders a `· ⚠️ Breaking` badge — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames). `security: true` is only for a security fix in this server's own source, never a routine dependency advisory; dependency fixes belong under `## Dependencies`.
393
399
 
394
400
  `agent-notes` is an optional free-form field for maintenance agents processing the release downstream. Content here won't appear in the rendered CHANGELOG — it's consumed by agents running the `maintenance` skill. Use it for adoption instructions that don't fit the human-facing sections: new files to create, fields to populate, one-time migration steps. Omit entirely when there's nothing to say.
395
401
 
@@ -430,4 +436,4 @@ import { getRegistryService } from '@/services/registry/registry-service.js';
430
436
  - [ ] `.codex-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; `interface.displayName` = package name; `interface.shortDescription` from `package.json` description
431
437
  - [ ] `.codex-plugin/mcp.json` updated — server name key matches `package.json` name; env vars added for any required API keys
432
438
  - [ ] `.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
433
- - [ ] `npm run devcheck` passes
439
+ - [ ] `bun run devcheck` passes
package/Dockerfile CHANGED
@@ -4,7 +4,7 @@
4
4
  # This stage installs all dependencies (including dev), builds the TypeScript
5
5
  # source code into JavaScript, and prepares the production assets.
6
6
  # ==============================================================================
7
- FROM oven/bun:1.3.14 AS build
7
+ FROM --platform=$BUILDPLATFORM oven/bun:1.4.0 AS build
8
8
 
9
9
  WORKDIR /usr/src/app
10
10
 
@@ -33,7 +33,7 @@ RUN bun run build
33
33
  # application. It uses a slim base image and only includes production
34
34
  # dependencies and build artifacts.
35
35
  # ==============================================================================
36
- FROM oven/bun:1.3.14-slim AS production
36
+ FROM oven/bun:1.4.0-slim AS production
37
37
 
38
38
  WORKDIR /usr/src/app
39
39
 
@@ -52,10 +52,12 @@ LABEL org.opencontainers.image.source="https://github.com/cyanheads/faa-aircraft
52
52
  # Copy dependency manifests
53
53
  COPY package.json bun.lock ./
54
54
 
55
- # Install only production dependencies, ignoring any lifecycle scripts (like 'prepare')
56
- # that are not needed in the final production image.
55
+ # Install only production dependencies, ignoring any lifecycle scripts (like
56
+ # 'prepare') that are not needed in the final production image. `--omit=peer`
57
+ # drops the framework's optional peer tiers; direct runtime dependencies remain.
58
+ # The OTEL step carries the same flag so it does not pull the omitted peers back.
57
59
  RUN --mount=type=cache,target=/root/.bun/install/cache \
58
- bun install --production --frozen-lockfile --ignore-scripts
60
+ bun install --production --omit=peer --frozen-lockfile --ignore-scripts
59
61
 
60
62
  # Conditionally install OpenTelemetry optional peer dependencies (Tier 3).
61
63
  # These are not bundled by default to keep the base image lean. Enable at build time
@@ -63,7 +65,7 @@ RUN --mount=type=cache,target=/root/.bun/install/cache \
63
65
  ARG OTEL_ENABLED=true
64
66
  RUN --mount=type=cache,target=/root/.bun/install/cache \
65
67
  if [ "$OTEL_ENABLED" = "true" ]; then \
66
- bun add @hono/otel \
68
+ bun add --omit=dev --omit=peer --ignore-scripts @hono/otel \
67
69
  @opentelemetry/instrumentation-http \
68
70
  @opentelemetry/exporter-metrics-otlp-http \
69
71
  @opentelemetry/exporter-trace-otlp-http \
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.1.7-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/faa-aircraft-registry-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%2Ffaa-aircraft-registry-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/faa-aircraft-registry-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.14-blueviolet.svg?style=flat-square)](https://bun.sh/)
10
+ [![Version](https://img.shields.io/badge/Version-0.1.8-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/faa-aircraft-registry-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/%40cyanheads%2Ffaa-aircraft-registry-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/faa-aircraft-registry-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.0-blueviolet.svg?style=flat-square)](https://bun.sh/)
11
11
 
12
12
  </div>
13
13
 
@@ -110,6 +110,7 @@ Built on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp
110
110
  - Swappable storage backends: `in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`
111
111
  - Structured logging with optional OpenTelemetry tracing
112
112
  - STDIO and Streamable HTTP transports
113
+ - MCP protocol revision 2026-07-28 alongside initialize-negotiated 2025-era clients
113
114
 
114
115
  FAA-registry-specific:
115
116
 
@@ -231,7 +232,7 @@ FAA_MIRROR_PATH=/path/to/faa-registry.db bun run mirror:refresh
231
232
  ```
232
233
 
233
234
  - **Keep the path stable.** Point `FAA_MIRROR_PATH` (and the same env var in your MCP client config) at a persistent location so the built index is reused across runs. Default: `.mirror/faa-registry.db`.
234
- - **Daily refresh.** Under HTTP transport the server schedules a daily `mirror:refresh` aligned to the FAA's nightly re-release (~11:30 PM Central); the index stays queryable throughout. Under stdio, run `mirror:refresh` out-of-band (e.g. a cron job).
235
+ - **Daily refresh.** Under HTTP transport the server schedules a daily `mirror:refresh` aligned to the FAA's nightly re-release (~11:30 PM Central). If an interrupted rebuild leaves the index empty, queries fail loudly with `ServiceUnavailable` until the rebuild succeeds. Under stdio, run `mirror:refresh` out-of-band (e.g. a cron job).
235
236
  - **Docker.** The image ships the mirror CLI and a writable `.mirror` data directory owned by the runtime user. Mount a volume there and run `mirror:init` once (e.g. `docker exec <container> bun run mirror:init`, or a one-shot init job against the shared volume) so the index persists across container restarts.
236
237
  - **Until the index exists,** every query fails with a `ServiceUnavailable` error whose recovery hint points to `mirror:init` — there is no live API to fall back to, so the cold state surfaces loudly rather than returning empty results.
237
238
 
@@ -239,7 +240,7 @@ The source URL is overridable via `FAA_DATABASE_URL` (for a private or cached mi
239
240
 
240
241
  ### Prerequisites
241
242
 
242
- - [Bun v1.3](https://bun.sh/) or higher (or Node.js v24+). `bun:sqlite` is built into Bun; a Node-only deployment adds `better-sqlite3` (already declared as an optional peer dependency).
243
+ - [Bun v1.4](https://bun.sh/) or higher (or Node.js v24+). `bun:sqlite` is built into Bun; a Node-only deployment adds `better-sqlite3` (already declared as an optional peer dependency).
243
244
  - Disk space for the built index (a few hundred MB) at `FAA_MIRROR_PATH`.
244
245
  - Network access at `mirror:init` / `mirror:refresh` time to download the FAA ZIP. Not needed at query time.
245
246
 
@@ -279,6 +280,7 @@ bun run mirror:init
279
280
  | `FAA_MIRROR_PATH` | Filesystem path to the SQLite index file. Point at a persistent path; mount a volume here in production. | `.mirror/faa-registry.db` |
280
281
  | `FAA_DATABASE_URL` | Source URL for the FAA Releasable Aircraft Database ZIP, used by `mirror:init` / `mirror:refresh` only. Overridable for a private/cached mirror; never read at request time. | FAA registry ZIP |
281
282
  | `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |
283
+ | `MCP_SESSION_MODE` | Session mode: `auto` (resolves to stateful), `stateful`, or `stateless`. The included `.env.example` and Docker image explicitly use stateless mode because this server has no multi-round-trip input. | `auto` → `stateful` |
282
284
  | `MCP_HTTP_PORT` | Port for the HTTP server. | `3010` |
283
285
  | `MCP_HTTP_ENDPOINT_PATH` | HTTP endpoint path where the MCP server is mounted. | `/mcp` |
284
286
  | `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |
@@ -0,0 +1,33 @@
1
+ ---
2
+ summary: "MCP 2026-07-28 support, strict tool inputs, valid error envelopes, and explicit stateless serving."
3
+ breaking: false
4
+ security: false
5
+ ---
6
+
7
+ # 0.1.8 — 2026-08-24
8
+
9
+ ## Added
10
+
11
+ - **MCP 2026-07-28 support** alongside initialize-negotiated 2025 clients.
12
+ - **Registration resource cache guidance** marking each response private and cacheable for one hour.
13
+
14
+ ## Changed
15
+
16
+ - **Tool contracts reject undeclared root inputs** and advertise SDK-valid structured error envelopes.
17
+ - **Domain validation failures** now use `ValidationError` for malformed N-numbers and codes, missing search filters, and disabled search fields; `InvalidParams` remains reserved for malformed request shape.
18
+ - **Session mode is explicitly stateless** across `.env.example`, the Docker image, and the README.
19
+ - **Tool, resource, mirror lifecycle, and packaging descriptions** are shorter and match the implemented behavior.
20
+ - **Build and release maintenance** adopts Bun 1.4, TypeScript 7, test typechecking, tool-contract integration coverage, leaner Docker installs, current packaging scripts and skills, and community health files.
21
+ - **Security reporting guidance** uses `security@caseyjhand.com` and asks reporters to redact credentials.
22
+
23
+ ## Dependencies
24
+
25
+ - `@cyanheads/mcp-ts-core` `^0.10.14` → `^0.12.3`
26
+ - `node-cron` `^4.4.1` → `^4.6.0`
27
+ - `better-sqlite3` peer `^12.0.0` → `^13.0.1`; development `^12.11.1` → `^13.0.3`
28
+ - `typescript` `^6.0.3` → `^7.0.2`
29
+ - `@biomejs/biome` `2.5.2` → `2.5.10`
30
+ - `@types/node` `26.1.1` → `26.2.0`
31
+ - `ignore` `^7.0.5` → `^7.0.6`
32
+ - `tsc-alias` `^1.9.1` → `^1.9.2`
33
+ - `vitest` `^4.1.9` → `^4.1.11`
@@ -4,10 +4,11 @@
4
4
  # to author a new release. Set that file's H1 to `# <version> — YYYY-MM-DD`
5
5
  # with a concrete date.
6
6
 
7
- # Required. One-line GitHub Release-style headline. 350 character cap.
8
- # Default short and scannable. Don't pad, don't stitch unrelated changes with
9
- # semicolons — pick the headline. Quotes required: unquoted YAML treats `: `
10
- # inside the value as a key separator and fails GitHub's strict parser.
7
+ # Required. One-line GitHub Release-style headline. 350 character cap — a
8
+ # ceiling, not a target. Default short and scannable. Don't pad, don't stitch
9
+ # unrelated changes with commas/semicolons into an inventory — pick the
10
+ # headline, like a tag's theme line. Quotes required: unquoted YAML treats
11
+ # `: ` inside the value as a key separator and fails GitHub's strict parser.
11
12
  summary: ""
12
13
 
13
14
  # Set `true` when consumers must change code to upgrade: API removals,
@@ -24,9 +25,10 @@ security: false
24
25
 
25
26
  # Optional free-form notes for maintenance agents processing this release.
26
27
  # Not rendered in CHANGELOG — consumed by agents running `maintenance` on
27
- # downstream servers. Use for adoption instructions that don't fit the
28
- # human-facing sections: new files to create, fields to populate, one-time
29
- # migration steps. Omit the field entirely when there's nothing to say.
28
+ # downstream servers. ADOPTION STEPS ONLY — new files to create, fields to
29
+ # populate, one-time migration steps. Never a second rendering of the body:
30
+ # if a body bullet already says it, name the bullet's symbol instead of
31
+ # re-explaining. Omit the field entirely when there's nothing to say.
30
32
  # agent-notes: |
31
33
  # <instructions for downstream maintenance agents>
32
34
  ---
@@ -41,17 +43,54 @@ security: false
41
43
  each bullet with the symbol or concept name in **bold** so they can skip
42
44
  what's irrelevant and zoom in on what's not.
43
45
 
44
- Tone: terse, fact-dense, not verbose. Default to one sentence per bullet —
45
- name the symbol, state what changed, stop. Use a second sentence only when
46
- it carries weight. If a bullet feels long, it is.
47
-
48
- Cut: mechanism walkthroughs (those belong in JSDoc, CLAUDE.md/AGENTS.md, or the
49
- relevant skill), ceremonial framings ("This release introduces…",
50
- backwards-compat paragraphs), file-by-file test enumerations, internal
51
- implementation notes. Prefer code/symbol names over English re-explanations.
46
+ Tone: terse, fact-dense, not verbose. Bullet shape: **symbol** + what
47
+ changed + at most one consumer-facing caveat. One sentence by default, two
48
+ when the second carries weight — a bullet past ~40 words or three sentences
49
+ is wrong. The depth lives one hop away: the linked issue carries the why,
50
+ the commit diff carries the how. The changelog names what changed and what
51
+ a consumer does about it; a reader who wants mechanism opens the link.
52
+
53
+ Model length on THIS guide, never on the previous entry — entries modeled
54
+ on entries compound.
55
+
56
+ Cut (each has shipped as a wall of text; these are the cruft):
57
+ - History/justification narration — how the bug worked, why the old
58
+ behavior was wrong. One short clause at most; the issue carries the story.
59
+ - Design-rationale defense — "chosen over Y because…", "guarding the
60
+ getter is not enough…". That is the author arguing with a reviewer;
61
+ reviewers read the PR, not the changelog.
62
+ - Defensive unchanged-clauses — "X is unchanged", "byte-identical to
63
+ <prev>". Keep one only where its absence would cause a real misread,
64
+ as a short parenthetical.
65
+ - Edge-case inventories — marker lists, not-flagged lists, escape tables.
66
+ Tests and the issue carry those.
67
+ - Mechanism walkthroughs (JSDoc, CLAUDE.md/AGENTS.md, or the relevant
68
+ skill own those), ceremonial framings ("This release introduces…"),
69
+ backwards-compat paragraphs, file-by-file test enumerations. Prefer
70
+ code/symbol names over English re-explanations.
71
+
72
+ Verified ≠ included: the every-claim-verified-from-the-diff rule bounds
73
+ the TRUTH of what you write, never the AMOUNT.
74
+
75
+ Example — same fact, right size:
76
+
77
+ TOO LONG: **`fetchWithTimeout`'s `timeoutMs` bounds the whole exchange**
78
+ (#341). `fetch` resolves once headers arrive and the deadline was
79
+ cleared as the helper returned, so a peer that answered promptly and
80
+ then stalled the stream held the request open indefinitely. A 2xx
81
+ carrying a body now comes back as a passthrough wrapper that disarms
82
+ the deadline when the body closes, errors, or is cancelled; …
83
+ [+90 more words of mechanism and edge cases]
84
+
85
+ RIGHT: **`fetchWithTimeout`'s `timeoutMs` now bounds the whole
86
+ exchange, not just the headers** (#341). A stalled body aborts with
87
+ the same `Timeout` error; the returned `Response` is a wrapper, so
88
+ identity assertions (`toBe(response)`) no longer hold.
52
89
 
53
90
  Narrative intro: skip by default. Add one short sentence only when the
54
- release theme genuinely needs framing the bullets can't carry.
91
+ release theme genuinely needs framing the bullets can't carry. When many
92
+ bullets share one upgrade consequence, state it ONCE — intro line or
93
+ agent-notes — never per bullet.
55
94
 
56
95
  Sections: Keep a Changelog order — Added, Changed, Deprecated, Removed,
57
96
  Fixed, Security. Include only sections with entries; delete the rest
package/dist/index.d.ts CHANGED
@@ -4,7 +4,8 @@
4
4
  * service (the on-disk FAA SQLite mirror) in setup(), registers the read-only
5
5
  * tools and the registration resource, and — under HTTP transport — schedules a
6
6
  * daily mirror refresh aligned to the FAA's nightly re-release. The index is
7
- * never built on startup; mirror:init runs out-of-band (Docker build / one-shot).
7
+ * never built on startup; mirror:init runs out-of-band (locally or in a one-shot
8
+ * container against the persistent mirror volume).
8
9
  * @module index
9
10
  */
10
11
  export {};
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;GAOG"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;GAQG"}
package/dist/index.js CHANGED
@@ -4,7 +4,8 @@
4
4
  * service (the on-disk FAA SQLite mirror) in setup(), registers the read-only
5
5
  * tools and the registration resource, and — under HTTP transport — schedules a
6
6
  * daily mirror refresh aligned to the FAA's nightly re-release. The index is
7
- * never built on startup; mirror:init runs out-of-band (Docker build / one-shot).
7
+ * never built on startup; mirror:init runs out-of-band (locally or in a one-shot
8
+ * container against the persistent mirror volume).
8
9
  * @module index
9
10
  */
10
11
  import { createApp } from '@cyanheads/mcp-ts-core';
@@ -24,7 +25,6 @@ const REFRESH_CRON = '0 6 * * *';
24
25
  await createApp({
25
26
  name: 'faa-aircraft-registry-mcp-server',
26
27
  title: 'faa-aircraft-registry-mcp-server',
27
- websiteUrl: 'https://github.com/cyanheads/faa-aircraft-registry-mcp-server',
28
28
  tools: allToolDefinitions,
29
29
  resources: allResourceDefinitions,
30
30
  instructions: 'Offline, keyless lookup of the US civil aircraft registry (the FAA Releasable Aircraft Database, indexed locally as SQLite + FTS5). Decode an N-number with faa_lookup_registration ("N12345" or "12345" both work); resolve active/deregistered/reserved status with faa_get_registration_status; search by owner/make-model/state/type/Mode S with faa_search_registrations; decode and discover manufacturer-model codes with faa_get_aircraft_type and faa_search_aircraft_types. Coded fields surface both the raw FAA code and the decoded label. Owner name and address are REDACTED by default (FAA_REDACT_OWNER_PII); when redacted, owner-name search is disabled and payloads carry ownerRedacted: true. The index must be built once via the mirror:init script before queries succeed.',
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;GAOG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACxE,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,sBAAsB,EAAE,MAAM,6CAA6C,CAAC;AACrF,OAAO,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAC;AAC7E,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,yCAAyC,CAAC;AAElG,MAAM,YAAY,GAAG,eAAe,EAAE,CAAC;AAEvC;;;;;GAKG;AACH,MAAM,YAAY,GAAG,WAAW,CAAC;AAEjC,MAAM,SAAS,CAAC;IACd,IAAI,EAAE,kCAAkC;IACxC,KAAK,EAAE,kCAAkC;IACzC,UAAU,EAAE,+DAA+D;IAC3E,KAAK,EAAE,kBAAkB;IACzB,SAAS,EAAE,sBAAsB;IACjC,YAAY,EACV,qwBAAqwB;IACvwB,OAAO,EAAE;QACP,WAAW,EAAE,KAAK;QAClB,OAAO,EACL,kIAAkI;QACpI,QAAQ,EAAE,+DAA+D;QACzE,KAAK,EAAE;YACL;gBACE,KAAK,EAAE,uBAAuB;gBAC9B,IAAI,EAAE,oFAAoF;gBAC1F,QAAQ,EAAE,IAAI;aACf;YACD;gBACE,KAAK,EAAE,8BAA8B;gBACrC,IAAI,EAAE,0DAA0D;gBAChE,QAAQ,EAAE,IAAI;aACf;SACF;KACF;IAED,KAAK,CAAC,IAAI;QACR,mBAAmB,CAAC;YAClB,cAAc,EAAE,YAAY,CAAC,cAAc;YAC3C,UAAU,EAAE,YAAY,CAAC,UAAU;YACnC,WAAW,EAAE,YAAY,CAAC,WAAW;SACtC,CAAC,CAAC;QAEH;;;;WAIG;QACH,IAAI,IAAI,CAAC,MAAM,CAAC,gBAAgB,KAAK,MAAM,EAAE,CAAC;YAC5C,KAAK,oBAAoB,EAAE,CAAC;QAC9B,CAAC;IACH,CAAC;CACF,CAAC,CAAC;AAEH,uDAAuD;AACvD,KAAK,UAAU,oBAAoB;IACjC,MAAM,gBAAgB,CAAC,QAAQ,CAC7B,sBAAsB,EACtB,YAAY,EACZ,KAAK,EAAE,MAAM,EAAE,EAAE;QACf,MAAM,CAAC,IAAI,CAAC,yCAAyC,EAAE,MAAM,CAAC,CAAC;QAC/D,MAAM,MAAM,GAAG,MAAM,kBAAkB,EAAE,CAAC,cAAc,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC;QACtF,MAAM,CAAC,IAAI,CAAC,4CAA4C,MAAM,CAAC,KAAK,UAAU,EAAE,MAAM,CAAC,CAAC;IAC1F,CAAC,EACD,gGAAgG,CACjG,CAAC;IACF,gBAAgB,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC;AACjD,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACxE,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,sBAAsB,EAAE,MAAM,6CAA6C,CAAC;AACrF,OAAO,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAC;AAC7E,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,yCAAyC,CAAC;AAElG,MAAM,YAAY,GAAG,eAAe,EAAE,CAAC;AAEvC;;;;;GAKG;AACH,MAAM,YAAY,GAAG,WAAW,CAAC;AAEjC,MAAM,SAAS,CAAC;IACd,IAAI,EAAE,kCAAkC;IACxC,KAAK,EAAE,kCAAkC;IACzC,KAAK,EAAE,kBAAkB;IACzB,SAAS,EAAE,sBAAsB;IACjC,YAAY,EACV,qwBAAqwB;IACvwB,OAAO,EAAE;QACP,WAAW,EAAE,KAAK;QAClB,OAAO,EACL,kIAAkI;QACpI,QAAQ,EAAE,+DAA+D;QACzE,KAAK,EAAE;YACL;gBACE,KAAK,EAAE,uBAAuB;gBAC9B,IAAI,EAAE,oFAAoF;gBAC1F,QAAQ,EAAE,IAAI;aACf;YACD;gBACE,KAAK,EAAE,8BAA8B;gBACrC,IAAI,EAAE,0DAA0D;gBAChE,QAAQ,EAAE,IAAI;aACf;SACF;KACF;IAED,KAAK,CAAC,IAAI;QACR,mBAAmB,CAAC;YAClB,cAAc,EAAE,YAAY,CAAC,cAAc;YAC3C,UAAU,EAAE,YAAY,CAAC,UAAU;YACnC,WAAW,EAAE,YAAY,CAAC,WAAW;SACtC,CAAC,CAAC;QAEH;;;;WAIG;QACH,IAAI,IAAI,CAAC,MAAM,CAAC,gBAAgB,KAAK,MAAM,EAAE,CAAC;YAC5C,KAAK,oBAAoB,EAAE,CAAC;QAC9B,CAAC;IACH,CAAC;CACF,CAAC,CAAC;AAEH,uDAAuD;AACvD,KAAK,UAAU,oBAAoB;IACjC,MAAM,gBAAgB,CAAC,QAAQ,CAC7B,sBAAsB,EACtB,YAAY,EACZ,KAAK,EAAE,MAAM,EAAE,EAAE;QACf,MAAM,CAAC,IAAI,CAAC,yCAAyC,EAAE,MAAM,CAAC,CAAC;QAC/D,MAAM,MAAM,GAAG,MAAM,kBAAkB,EAAE,CAAC,cAAc,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC;QACtF,MAAM,CAAC,IAAI,CAAC,4CAA4C,MAAM,CAAC,KAAK,UAAU,EAAE,MAAM,CAAC,CAAC;IAC1F,CAAC,EACD,gGAAgG,CACjG,CAAC;IACF,gBAAgB,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC;AACjD,CAAC"}