@cyanheads/faa-aircraft-registry-mcp-server 0.1.11 → 0.2.0

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 (120) hide show
  1. package/AGENTS.md +36 -23
  2. package/CLAUDE.md +36 -23
  3. package/Dockerfile +10 -20
  4. package/README.md +74 -75
  5. package/changelog/0.1.x/0.1.12.md +17 -0
  6. package/changelog/0.2.x/0.2.0.md +45 -0
  7. package/changelog/template.md +10 -3
  8. package/{scripts/_mirror-context.ts → dist/cli/_mirror-context.d.ts} +7 -22
  9. package/dist/cli/_mirror-context.d.ts.map +1 -0
  10. package/dist/cli/_mirror-context.js +32 -0
  11. package/dist/cli/_mirror-context.js.map +1 -0
  12. package/dist/cli/faa-mirror-init.d.ts +11 -0
  13. package/dist/cli/faa-mirror-init.d.ts.map +1 -0
  14. package/{scripts/faa-mirror-init.ts → dist/cli/faa-mirror-init.js} +6 -11
  15. package/dist/cli/faa-mirror-init.js.map +1 -0
  16. package/dist/cli/faa-mirror-refresh.d.ts +11 -0
  17. package/dist/cli/faa-mirror-refresh.d.ts.map +1 -0
  18. package/{scripts/faa-mirror-refresh.ts → dist/cli/faa-mirror-refresh.js} +7 -12
  19. package/dist/cli/faa-mirror-refresh.js.map +1 -0
  20. package/dist/cli/faa-mirror-verify.d.ts +10 -0
  21. package/dist/cli/faa-mirror-verify.d.ts.map +1 -0
  22. package/dist/cli/faa-mirror-verify.js +51 -0
  23. package/dist/cli/faa-mirror-verify.js.map +1 -0
  24. package/dist/config/server-config.d.ts +1 -0
  25. package/dist/config/server-config.d.ts.map +1 -1
  26. package/dist/config/server-config.js +3 -0
  27. package/dist/config/server-config.js.map +1 -1
  28. package/dist/index.js +4 -3
  29. package/dist/index.js.map +1 -1
  30. package/dist/lifecycle.d.ts +2 -3
  31. package/dist/lifecycle.d.ts.map +1 -1
  32. package/dist/lifecycle.js +15 -5
  33. package/dist/lifecycle.js.map +1 -1
  34. package/dist/mcp-server/_mirror-errors.d.ts +14 -0
  35. package/dist/mcp-server/_mirror-errors.d.ts.map +1 -0
  36. package/dist/mcp-server/_mirror-errors.js +14 -0
  37. package/dist/mcp-server/_mirror-errors.js.map +1 -0
  38. package/dist/mcp-server/resources/definitions/index.d.ts +13 -0
  39. package/dist/mcp-server/resources/definitions/index.d.ts.map +1 -1
  40. package/dist/mcp-server/resources/definitions/registration.resource.d.ts +13 -0
  41. package/dist/mcp-server/resources/definitions/registration.resource.d.ts.map +1 -1
  42. package/dist/mcp-server/resources/definitions/registration.resource.js +2 -0
  43. package/dist/mcp-server/resources/definitions/registration.resource.js.map +1 -1
  44. package/dist/mcp-server/tools/definitions/_response-metadata.d.ts +12 -0
  45. package/dist/mcp-server/tools/definitions/_response-metadata.d.ts.map +1 -0
  46. package/dist/mcp-server/tools/definitions/_response-metadata.js +30 -0
  47. package/dist/mcp-server/tools/definitions/_response-metadata.js.map +1 -0
  48. package/dist/mcp-server/tools/definitions/_schemas.d.ts +6 -0
  49. package/dist/mcp-server/tools/definitions/_schemas.d.ts.map +1 -1
  50. package/dist/mcp-server/tools/definitions/_schemas.js +41 -26
  51. package/dist/mcp-server/tools/definitions/_schemas.js.map +1 -1
  52. package/dist/mcp-server/tools/definitions/_search-page.d.ts +34 -0
  53. package/dist/mcp-server/tools/definitions/_search-page.d.ts.map +1 -0
  54. package/dist/mcp-server/tools/definitions/_search-page.js +64 -0
  55. package/dist/mcp-server/tools/definitions/_search-page.js.map +1 -0
  56. package/dist/mcp-server/tools/definitions/get-aircraft-type.tool.d.ts +11 -1
  57. package/dist/mcp-server/tools/definitions/get-aircraft-type.tool.d.ts.map +1 -1
  58. package/dist/mcp-server/tools/definitions/get-aircraft-type.tool.js +18 -7
  59. package/dist/mcp-server/tools/definitions/get-aircraft-type.tool.js.map +1 -1
  60. package/dist/mcp-server/tools/definitions/get-registration-status.tool.d.ts +28 -2
  61. package/dist/mcp-server/tools/definitions/get-registration-status.tool.d.ts.map +1 -1
  62. package/dist/mcp-server/tools/definitions/get-registration-status.tool.js +74 -16
  63. package/dist/mcp-server/tools/definitions/get-registration-status.tool.js.map +1 -1
  64. package/dist/mcp-server/tools/definitions/index.d.ts +126 -56
  65. package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -1
  66. package/dist/mcp-server/tools/definitions/lookup-registration.tool.d.ts +17 -1
  67. package/dist/mcp-server/tools/definitions/lookup-registration.tool.d.ts.map +1 -1
  68. package/dist/mcp-server/tools/definitions/lookup-registration.tool.js +9 -1
  69. package/dist/mcp-server/tools/definitions/lookup-registration.tool.js.map +1 -1
  70. package/dist/mcp-server/tools/definitions/search-aircraft-types.tool.d.ts +14 -6
  71. package/dist/mcp-server/tools/definitions/search-aircraft-types.tool.d.ts.map +1 -1
  72. package/dist/mcp-server/tools/definitions/search-aircraft-types.tool.js +21 -57
  73. package/dist/mcp-server/tools/definitions/search-aircraft-types.tool.js.map +1 -1
  74. package/dist/mcp-server/tools/definitions/search-registrations.tool.d.ts +18 -8
  75. package/dist/mcp-server/tools/definitions/search-registrations.tool.d.ts.map +1 -1
  76. package/dist/mcp-server/tools/definitions/search-registrations.tool.js +40 -63
  77. package/dist/mcp-server/tools/definitions/search-registrations.tool.js.map +1 -1
  78. package/dist/services/registry/decode.d.ts +3 -0
  79. package/dist/services/registry/decode.d.ts.map +1 -1
  80. package/dist/services/registry/decode.js +91 -0
  81. package/dist/services/registry/decode.js.map +1 -1
  82. package/dist/services/registry/ingest.d.ts +2 -2
  83. package/dist/services/registry/ingest.d.ts.map +1 -1
  84. package/dist/services/registry/ingest.js +125 -69
  85. package/dist/services/registry/ingest.js.map +1 -1
  86. package/dist/services/registry/normalize.d.ts +26 -2
  87. package/dist/services/registry/normalize.d.ts.map +1 -1
  88. package/dist/services/registry/normalize.js +33 -30
  89. package/dist/services/registry/normalize.js.map +1 -1
  90. package/dist/services/registry/registry-mirror.d.ts +11 -0
  91. package/dist/services/registry/registry-mirror.d.ts.map +1 -0
  92. package/dist/services/registry/registry-mirror.js +37 -0
  93. package/dist/services/registry/registry-mirror.js.map +1 -0
  94. package/dist/services/registry/registry-search.d.ts +12 -0
  95. package/dist/services/registry/registry-search.d.ts.map +1 -0
  96. package/dist/services/registry/registry-search.js +110 -0
  97. package/dist/services/registry/registry-search.js.map +1 -0
  98. package/dist/services/registry/registry-service.d.ts +15 -28
  99. package/dist/services/registry/registry-service.d.ts.map +1 -1
  100. package/dist/services/registry/registry-service.js +143 -222
  101. package/dist/services/registry/registry-service.js.map +1 -1
  102. package/dist/services/registry/registry-snapshot.d.ts +12 -0
  103. package/dist/services/registry/registry-snapshot.d.ts.map +1 -0
  104. package/dist/services/registry/registry-snapshot.js +30 -0
  105. package/dist/services/registry/registry-snapshot.js.map +1 -0
  106. package/dist/services/registry/schema.d.ts +3 -14
  107. package/dist/services/registry/schema.d.ts.map +1 -1
  108. package/dist/services/registry/schema.js +43 -13
  109. package/dist/services/registry/schema.js.map +1 -1
  110. package/dist/services/registry/types.d.ts +24 -7
  111. package/dist/services/registry/types.d.ts.map +1 -1
  112. package/dist/services/registry/types.js.map +1 -1
  113. package/dist/services/registry/zip.d.ts +2 -0
  114. package/dist/services/registry/zip.d.ts.map +1 -1
  115. package/dist/services/registry/zip.js +22 -2
  116. package/dist/services/registry/zip.js.map +1 -1
  117. package/package.json +16 -26
  118. package/server.json +17 -3
  119. package/skills/faa-aircraft-registry-guide/SKILL.md +40 -0
  120. package/scripts/faa-mirror-verify.ts +0 -50
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.11
5
- **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.15`
6
- **Engines:** Bun ≥1.4.0, Node ≥24.0.0
7
- **MCP SDK:** `@modelcontextprotocol/server` ^2.3.1 (protocol revisions 2026-07-28 and 2025-*)
4
+ **Version:** 0.2.0
5
+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.22`
6
+ **Engines:** Bun ≥1.4.4, Node ≥24.0.0
7
+ **MCP SDK:** `@modelcontextprotocol/server` ^2.4.0 (protocol revisions 2026-07-28 and 2025-*)
8
8
  **Zod:** ^4.6.7
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.
@@ -17,7 +17,9 @@ An offline lookup server for the US civil aircraft registry. It indexes the FAA'
17
17
 
18
18
  **Server-as-source.** The mirror is the source of truth at runtime; there is no upstream API to retry. The index is built out-of-band by `mirror:init` (never on startup) and refreshed daily; a cold (never-initialized) index is a hard `ServiceUnavailable`, not a silent empty result. See the `api-mirror` skill for the MirrorService model.
19
19
 
20
- **Owner-PII redaction is a first-class, fail-safe feature.** `FAA_REDACT_OWNER_PII` defaults to redacted; unset/empty/malformed resolves to redacted. When redacted, owner name/address are dropped from output AND owner-name search is disabled. The redaction gate (a single chokepoint in `registry-service`) and the baked `.mirror/` data are load-bearing — do not weaken either.
20
+ **Owner-PII redaction is a first-class, fail-safe feature.** `FAA_REDACT_OWNER_PII` defaults to redacted; unset/empty/malformed resolves to redacted. Owner name/address are dropped from output AND owner-name search is disabled. Ingest classifies manufacturer names against registrant identities; `registry-search` excludes hidden manufacturers from matching, counts, and ordering, and `registry-service` withholds them and repeated kit-manufacturer aliases from output. Legacy unclassified non-type-certificated manufacturers fail closed until refresh. Preserve both the matching and output gates.
21
+
22
+ **Reads and rebuilds share a generation contract.** `registry-snapshot` checks readiness, source date, and query data in one SQLite read transaction. `registry-mirror` carries the framework sync lease into raw ingest writes; the generation stays loading from the table wipe until the fenced terminal sync commit. Stop older writers before upgrading a shared mirror. Never serve partial rebuilds or replace the FAA archive date with local completion time.
21
23
 
22
24
  ---
23
25
 
@@ -133,6 +135,7 @@ const ServerConfigSchema = z.object({
133
135
  redactOwnerPii: z
134
136
  .preprocess(redactToSafeDefault, z.stringbool())
135
137
  .describe('Fail-safe owner-PII redaction. Redacted unless explicitly set to a falsy value.'),
138
+ clampLimits: z.stringbool().default(true),
136
139
  mirrorPath: z.string().min(1).default('.mirror/faa-registry.db')
137
140
  .describe('Filesystem path to the SQLite registry index.'),
138
141
  databaseUrl: z.string().url().default('https://registry.faa.gov/database/ReleasableAircraft.zip')
@@ -143,6 +146,7 @@ let _config: z.infer<typeof ServerConfigSchema> | undefined;
143
146
  export function getServerConfig() {
144
147
  _config ??= parseEnvConfig(ServerConfigSchema, {
145
148
  redactOwnerPii: 'FAA_REDACT_OWNER_PII',
149
+ clampLimits: 'FAA_CLAMP_LIMITS',
146
150
  mirrorPath: 'FAA_MIRROR_PATH',
147
151
  databaseUrl: 'FAA_DATABASE_URL',
148
152
  });
@@ -166,9 +170,9 @@ await createApp({
166
170
  resources: allResourceDefinitions,
167
171
  instructions: 'Offline, keyless lookup of the US civil aircraft registry … The index must be built once via the mirror:init script before queries succeed.',
168
172
  sessionMode: 'stateless',
169
- setup(core) {
173
+ async setup(core) {
170
174
  initRegistryService({ /* redactOwnerPii, mirrorPath, databaseUrl */ });
171
- if (core.config.mcpTransportType === 'http') void scheduleDailyRefresh(); // daily mirror:refresh
175
+ if (core.config.mcpTransportType === 'http') await scheduleDailyRefresh(); // daily mirror:refresh
172
176
  },
173
177
  teardown: teardownServer, // src/lifecycle.ts
174
178
  });
@@ -222,7 +226,7 @@ async handler(input, ctx) {
222
226
  }
223
227
  ```
224
228
 
225
- 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.
229
+ Every tool and the registration resource can return service-layer `ServiceUnavailable` reasons `mirror_not_ready`, `mirror_empty`, and `mirror_loading`. The loading reason also has an explicit retryable error contract. `registry-snapshot` raises these inside the read transaction; an interrupted rebuild requires a successful refresh. There is no live API fallback.
226
230
 
227
231
  `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`.
228
232
 
@@ -256,11 +260,14 @@ src/
256
260
  index.ts # createApp() entry; identity, sessionMode, setup/teardown wiring
257
261
  lifecycle.ts # daily refresh cron (HTTP) + teardown: remove job, close mirror handle
258
262
  config/
259
- server-config.ts # FAA_REDACT_OWNER_PII / FAA_MIRROR_PATH / FAA_DATABASE_URL (Zod schema)
263
+ server-config.ts # redaction, limit clamping, mirror path and source URL (Zod schema)
260
264
  services/
261
265
  registry/
262
- registry-service.ts # MirrorService instance; query/join/decode + the PII redaction gate
263
- ingest.ts # sync ingester: download ZIP → parse MASTER-1..9 + ACFTREF/ENGINE/DEREG/RESERVED → pre-join
266
+ registry-service.ts # lookup/status queries and domain mapping with output redaction
267
+ registry-search.ts # SQL/FTS search, exact serial filter and manufacturer matching gate
268
+ registry-mirror.ts # mirror construction and raw-writer lease binding
269
+ registry-snapshot.ts # transactional readiness, source date and query snapshot
270
+ ingest.ts # sync ingester: download ZIP → parse MASTER (single or MASTER-1..9) + ACFTREF/ENGINE/DEREG/RESERVED → pre-join
264
271
  zip.ts csv.ts # ZIP extraction + comma-delimited parsing
265
272
  decode.ts # static decode maps (status, type, region, category, …) applied at query time
266
273
  normalize.ts # N-number normalizer (strip leading N, uppercase)
@@ -275,12 +282,12 @@ src/
275
282
  search-aircraft-types.tool.ts # FTS5 search of the aircraft reference table
276
283
  get-aircraft-type.tool.ts # decode a 6–7-character mfr/model/series code
277
284
  resources/definitions/
278
- registration.resource.ts # faa://registration/{nNumber} (reuses the lookup handler)
279
- scripts/
280
- faa-mirror-init.ts # mirror:init — full out-of-band build
281
- faa-mirror-refresh.ts # mirror:refresh — incremental/full rebuild
282
- faa-mirror-verify.ts # mirror:verify — readiness + integrity check
283
- _mirror-context.ts # shared mirror-instance shim for the three CLI scripts
285
+ registration.resource.ts # faa://registration/{nNumber} (shares the lookup record schema)
286
+ cli/
287
+ faa-mirror-init.ts # mirror:init — full out-of-band build
288
+ faa-mirror-refresh.ts # mirror:refresh — full rebuild
289
+ faa-mirror-verify.ts # mirror:verify — readiness + integrity check
290
+ _mirror-context.ts # shared mirror-instance shim for the three CLI scripts
284
291
  ```
285
292
 
286
293
  ---
@@ -298,7 +305,7 @@ scripts/
298
305
 
299
306
  ## Skills
300
307
 
301
- Skills are modular instructions in `framework-skills/` at the project root. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. The directory is `framework-skills/`, not `skills/`, because Claude Code and Codex auto-load a plugin's root `skills/` — these are development-time skills for building the server, not skills for the agents that install it.
308
+ Read development skills in `framework-skills/` when a task matches. Run `bun run list-skills` for the full registry. Root `skills/` is reserved for published skills that help agents use the server. Plugin hosts load that tree directly, npm, Docker, and MCPB carry it, and `createApp({ skills: 'skills' })` serves it over MCP.
302
309
 
303
310
  **Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `framework-skills/` paths. The agent mirrors keep the name `skills/` — plugin hosts do not scan them. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
304
311
 
@@ -313,6 +320,7 @@ Available skills:
313
320
  | `add-resource` | Scaffold a new resource definition |
314
321
  | `add-prompt` | Scaffold a new prompt definition |
315
322
  | `add-service` | Scaffold a new service integration |
323
+ | `add-skill` | Author and verify a published skill in root `skills/` |
316
324
  | `add-test` | Scaffold test file for a tool, resource, or service |
317
325
  | `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
318
326
  | `tool-defs-analysis` | Read-only audit of MCP definition language across the surface — voice, leaks, defaults, recovery hints, output descriptions |
@@ -348,7 +356,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
348
356
 
349
357
  ## Commands
350
358
 
351
- **Runtime:** Scripts use Bun's native TypeScript execution — `bun run <cmd>` is the standard invocation. `npm run <cmd>` also works (npm delegates to bun).
359
+ **Runtime:** Build and development scripts use Bun's native TypeScript execution. Mirror lifecycle commands run compiled `dist/cli/*.js`; build first in a checkout. `bun run mirror:*` uses Bun, while `npm run mirror:*` uses Node. Both share the same compiled registry modules.
352
360
 
353
361
  | Command | Purpose |
354
362
  |:--------|:--------|
@@ -364,8 +372,9 @@ When you complete a skill's checklist, check the boxes and add a completion time
364
372
  | `bun run tree` | Generate directory structure doc |
365
373
  | `bun run format` | Auto-fix formatting (safe fixes only) |
366
374
  | `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
367
- | `bun run test` | Run tests (Vitest — use `bun run test`, not `bun test`) |
368
- | `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. |
375
+ | `bun run test` | Run unit and integration tests (Vitest — use `bun run test`, not `bun test`) |
376
+ | `bun run test:package` | Build and exercise the npm tarball and cleaned MCPB with real Node and Bun processes |
377
+ | `bun run mirror:init` | Build the SQLite registry index from the FAA ZIP before first use, never on server startup. Rerunning after an interruption starts a full rebuild. |
369
378
  | `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. |
370
379
  | `bun run mirror:verify` | Report index health — readiness, sync status, record count, SQLite integrity check. Exits non-zero when not ready or integrity fails. |
371
380
  | `bun run start:stdio` | Production mode (stdio) |
@@ -380,7 +389,9 @@ When you complete a skill's checklist, check the boxes and add a completion time
380
389
 
381
390
  ## Bundling
382
391
 
383
- `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.
392
+ `bun run bundle` produces a stdio-only `.mcpb` for Claude Desktop. Use root-anchored entries in `.mcpbignore` for source, tests, docs, plugin manifests, and other repository-local paths. Root `skills/` and the compiled mirror CLI in `dist/cli/` ship in the bundle. Cleanup removes dev dependencies, dependency agent docs, DuckDB platform bindings, node-gyp intermediate files, and build-only package files. The required `better-sqlite3` dependency retains all eight N-API prebuilts (macOS, Windows, Linux glibc/musl × x64/arm64).
393
+
394
+ Root `plugin.json` and `mcp.json` are the Agent Plugins 1.0.0 metadata and stdio launcher. Keep user-supplied variables in the host overlays and retain the `.codex-plugin/plugin.json` pointer to `./.codex-plugin/mcp.json` so Codex can forward them.
384
395
 
385
396
  **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, that every `user_config` option is wired into `mcp_config.env` as `"X": "${user_config.X}"` (the host substitutes nothing else — `"${X}"` reaches the server as that literal string), and that an optional string option carries `"default": ""`.
386
397
 
@@ -441,7 +452,7 @@ import { getRegistryService } from '@/services/registry/registry-service.js';
441
452
  - [ ] 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`.
442
453
  - [ ] JSDoc `@fileoverview` + `@module` on every file
443
454
  - [ ] `ctx.log` for logging; data access goes through `registry-service` (the mirror), never persistence directly
444
- - [ ] Owner-PII redaction holds: PII fields dropped AND owner-name search disabled when redacted; the gate is the single chokepoint in `registry-service`
455
+ - [ ] Owner-PII redaction holds across output, matching, counts and ordering; owner-name search stays disabled when redacted
445
456
  - [ ] Handlers throw on failure — error factories or plain `Error`, no try/catch
446
457
  - [ ] `format()` renders all data the LLM needs — different clients forward different surfaces (Claude Code → `structuredContent`, Claude Desktop → `content[]`); both must carry the same data
447
458
  - [ ] If wrapping external API: raw/domain/output schemas reviewed against real upstream sparsity/nullability before finalizing required vs optional fields
@@ -449,6 +460,8 @@ import { getRegistryService } from '@/services/registry/registry-service.js';
449
460
  - [ ] If wrapping external API: tests include at least one sparse payload case with omitted upstream fields
450
461
  - [ ] Registered in `createApp()` arrays (directly or via barrel exports)
451
462
  - [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
463
+ - [ ] Root plugin metadata matches `package.json` and the root launcher carries only fixed environment values
464
+ - [ ] Any published skill passes `lint:packaging`, with its gates and identifiers verified in a field test
452
465
  - [ ] `.codex-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; `interface.displayName` = the unscoped repo name (never the npm scope — `lint:packaging` enforces this); `interface.shortDescription` from `package.json` description
453
466
  - [ ] `.codex-plugin/mcp.json` updated — server name key is the unscoped repo name; every user-supplied variable (API key, contact email, instance URL) is listed in `env_vars` so Codex forwards it from the user's environment. Never write `"KEY": ""` into `env` — an empty value replaces the user's exported key and is read as unset
454
467
  - [ ] `.claude-plugin/plugin.json` populated — `name`, `version`, `description`, `author`, `repository`, `license`, `keywords` from `package.json`; inline `mcpServers` entry keyed by the unscoped repo name. Every user-supplied variable is declared under `userConfig` (`type`, `title`, `description`; `sensitive: true` for keys and tokens; `required: true` or `default: ""`) and referenced from `env` as `"KEY": "${user_config.<option>}"` — mirror the `user_config` block in `manifest.json`. Never write `"KEY": ""` into `env`
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.11
5
- **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.15`
6
- **Engines:** Bun ≥1.4.0, Node ≥24.0.0
7
- **MCP SDK:** `@modelcontextprotocol/server` ^2.3.1 (protocol revisions 2026-07-28 and 2025-*)
4
+ **Version:** 0.2.0
5
+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.22`
6
+ **Engines:** Bun ≥1.4.4, Node ≥24.0.0
7
+ **MCP SDK:** `@modelcontextprotocol/server` ^2.4.0 (protocol revisions 2026-07-28 and 2025-*)
8
8
  **Zod:** ^4.6.7
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.
@@ -17,7 +17,9 @@ An offline lookup server for the US civil aircraft registry. It indexes the FAA'
17
17
 
18
18
  **Server-as-source.** The mirror is the source of truth at runtime; there is no upstream API to retry. The index is built out-of-band by `mirror:init` (never on startup) and refreshed daily; a cold (never-initialized) index is a hard `ServiceUnavailable`, not a silent empty result. See the `api-mirror` skill for the MirrorService model.
19
19
 
20
- **Owner-PII redaction is a first-class, fail-safe feature.** `FAA_REDACT_OWNER_PII` defaults to redacted; unset/empty/malformed resolves to redacted. When redacted, owner name/address are dropped from output AND owner-name search is disabled. The redaction gate (a single chokepoint in `registry-service`) and the baked `.mirror/` data are load-bearing — do not weaken either.
20
+ **Owner-PII redaction is a first-class, fail-safe feature.** `FAA_REDACT_OWNER_PII` defaults to redacted; unset/empty/malformed resolves to redacted. Owner name/address are dropped from output AND owner-name search is disabled. Ingest classifies manufacturer names against registrant identities; `registry-search` excludes hidden manufacturers from matching, counts, and ordering, and `registry-service` withholds them and repeated kit-manufacturer aliases from output. Legacy unclassified non-type-certificated manufacturers fail closed until refresh. Preserve both the matching and output gates.
21
+
22
+ **Reads and rebuilds share a generation contract.** `registry-snapshot` checks readiness, source date, and query data in one SQLite read transaction. `registry-mirror` carries the framework sync lease into raw ingest writes; the generation stays loading from the table wipe until the fenced terminal sync commit. Stop older writers before upgrading a shared mirror. Never serve partial rebuilds or replace the FAA archive date with local completion time.
21
23
 
22
24
  ---
23
25
 
@@ -133,6 +135,7 @@ const ServerConfigSchema = z.object({
133
135
  redactOwnerPii: z
134
136
  .preprocess(redactToSafeDefault, z.stringbool())
135
137
  .describe('Fail-safe owner-PII redaction. Redacted unless explicitly set to a falsy value.'),
138
+ clampLimits: z.stringbool().default(true),
136
139
  mirrorPath: z.string().min(1).default('.mirror/faa-registry.db')
137
140
  .describe('Filesystem path to the SQLite registry index.'),
138
141
  databaseUrl: z.string().url().default('https://registry.faa.gov/database/ReleasableAircraft.zip')
@@ -143,6 +146,7 @@ let _config: z.infer<typeof ServerConfigSchema> | undefined;
143
146
  export function getServerConfig() {
144
147
  _config ??= parseEnvConfig(ServerConfigSchema, {
145
148
  redactOwnerPii: 'FAA_REDACT_OWNER_PII',
149
+ clampLimits: 'FAA_CLAMP_LIMITS',
146
150
  mirrorPath: 'FAA_MIRROR_PATH',
147
151
  databaseUrl: 'FAA_DATABASE_URL',
148
152
  });
@@ -166,9 +170,9 @@ await createApp({
166
170
  resources: allResourceDefinitions,
167
171
  instructions: 'Offline, keyless lookup of the US civil aircraft registry … The index must be built once via the mirror:init script before queries succeed.',
168
172
  sessionMode: 'stateless',
169
- setup(core) {
173
+ async setup(core) {
170
174
  initRegistryService({ /* redactOwnerPii, mirrorPath, databaseUrl */ });
171
- if (core.config.mcpTransportType === 'http') void scheduleDailyRefresh(); // daily mirror:refresh
175
+ if (core.config.mcpTransportType === 'http') await scheduleDailyRefresh(); // daily mirror:refresh
172
176
  },
173
177
  teardown: teardownServer, // src/lifecycle.ts
174
178
  });
@@ -222,7 +226,7 @@ async handler(input, ctx) {
222
226
  }
223
227
  ```
224
228
 
225
- 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.
229
+ Every tool and the registration resource can return service-layer `ServiceUnavailable` reasons `mirror_not_ready`, `mirror_empty`, and `mirror_loading`. The loading reason also has an explicit retryable error contract. `registry-snapshot` raises these inside the read transaction; an interrupted rebuild requires a successful refresh. There is no live API fallback.
226
230
 
227
231
  `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`.
228
232
 
@@ -256,11 +260,14 @@ src/
256
260
  index.ts # createApp() entry; identity, sessionMode, setup/teardown wiring
257
261
  lifecycle.ts # daily refresh cron (HTTP) + teardown: remove job, close mirror handle
258
262
  config/
259
- server-config.ts # FAA_REDACT_OWNER_PII / FAA_MIRROR_PATH / FAA_DATABASE_URL (Zod schema)
263
+ server-config.ts # redaction, limit clamping, mirror path and source URL (Zod schema)
260
264
  services/
261
265
  registry/
262
- registry-service.ts # MirrorService instance; query/join/decode + the PII redaction gate
263
- ingest.ts # sync ingester: download ZIP → parse MASTER-1..9 + ACFTREF/ENGINE/DEREG/RESERVED → pre-join
266
+ registry-service.ts # lookup/status queries and domain mapping with output redaction
267
+ registry-search.ts # SQL/FTS search, exact serial filter and manufacturer matching gate
268
+ registry-mirror.ts # mirror construction and raw-writer lease binding
269
+ registry-snapshot.ts # transactional readiness, source date and query snapshot
270
+ ingest.ts # sync ingester: download ZIP → parse MASTER (single or MASTER-1..9) + ACFTREF/ENGINE/DEREG/RESERVED → pre-join
264
271
  zip.ts csv.ts # ZIP extraction + comma-delimited parsing
265
272
  decode.ts # static decode maps (status, type, region, category, …) applied at query time
266
273
  normalize.ts # N-number normalizer (strip leading N, uppercase)
@@ -275,12 +282,12 @@ src/
275
282
  search-aircraft-types.tool.ts # FTS5 search of the aircraft reference table
276
283
  get-aircraft-type.tool.ts # decode a 6–7-character mfr/model/series code
277
284
  resources/definitions/
278
- registration.resource.ts # faa://registration/{nNumber} (reuses the lookup handler)
279
- scripts/
280
- faa-mirror-init.ts # mirror:init — full out-of-band build
281
- faa-mirror-refresh.ts # mirror:refresh — incremental/full rebuild
282
- faa-mirror-verify.ts # mirror:verify — readiness + integrity check
283
- _mirror-context.ts # shared mirror-instance shim for the three CLI scripts
285
+ registration.resource.ts # faa://registration/{nNumber} (shares the lookup record schema)
286
+ cli/
287
+ faa-mirror-init.ts # mirror:init — full out-of-band build
288
+ faa-mirror-refresh.ts # mirror:refresh — full rebuild
289
+ faa-mirror-verify.ts # mirror:verify — readiness + integrity check
290
+ _mirror-context.ts # shared mirror-instance shim for the three CLI scripts
284
291
  ```
285
292
 
286
293
  ---
@@ -298,7 +305,7 @@ scripts/
298
305
 
299
306
  ## Skills
300
307
 
301
- Skills are modular instructions in `framework-skills/` at the project root. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. The directory is `framework-skills/`, not `skills/`, because Claude Code and Codex auto-load a plugin's root `skills/` — these are development-time skills for building the server, not skills for the agents that install it.
308
+ Read development skills in `framework-skills/` when a task matches. Run `bun run list-skills` for the full registry. Root `skills/` is reserved for published skills that help agents use the server. Plugin hosts load that tree directly, npm, Docker, and MCPB carry it, and `createApp({ skills: 'skills' })` serves it over MCP.
302
309
 
303
310
  **Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `framework-skills/` paths. The agent mirrors keep the name `skills/` — plugin hosts do not scan them. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
304
311
 
@@ -313,6 +320,7 @@ Available skills:
313
320
  | `add-resource` | Scaffold a new resource definition |
314
321
  | `add-prompt` | Scaffold a new prompt definition |
315
322
  | `add-service` | Scaffold a new service integration |
323
+ | `add-skill` | Author and verify a published skill in root `skills/` |
316
324
  | `add-test` | Scaffold test file for a tool, resource, or service |
317
325
  | `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
318
326
  | `tool-defs-analysis` | Read-only audit of MCP definition language across the surface — voice, leaks, defaults, recovery hints, output descriptions |
@@ -348,7 +356,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
348
356
 
349
357
  ## Commands
350
358
 
351
- **Runtime:** Scripts use Bun's native TypeScript execution — `bun run <cmd>` is the standard invocation. `npm run <cmd>` also works (npm delegates to bun).
359
+ **Runtime:** Build and development scripts use Bun's native TypeScript execution. Mirror lifecycle commands run compiled `dist/cli/*.js`; build first in a checkout. `bun run mirror:*` uses Bun, while `npm run mirror:*` uses Node. Both share the same compiled registry modules.
352
360
 
353
361
  | Command | Purpose |
354
362
  |:--------|:--------|
@@ -364,8 +372,9 @@ When you complete a skill's checklist, check the boxes and add a completion time
364
372
  | `bun run tree` | Generate directory structure doc |
365
373
  | `bun run format` | Auto-fix formatting (safe fixes only) |
366
374
  | `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
367
- | `bun run test` | Run tests (Vitest — use `bun run test`, not `bun test`) |
368
- | `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. |
375
+ | `bun run test` | Run unit and integration tests (Vitest — use `bun run test`, not `bun test`) |
376
+ | `bun run test:package` | Build and exercise the npm tarball and cleaned MCPB with real Node and Bun processes |
377
+ | `bun run mirror:init` | Build the SQLite registry index from the FAA ZIP before first use, never on server startup. Rerunning after an interruption starts a full rebuild. |
369
378
  | `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. |
370
379
  | `bun run mirror:verify` | Report index health — readiness, sync status, record count, SQLite integrity check. Exits non-zero when not ready or integrity fails. |
371
380
  | `bun run start:stdio` | Production mode (stdio) |
@@ -380,7 +389,9 @@ When you complete a skill's checklist, check the boxes and add a completion time
380
389
 
381
390
  ## Bundling
382
391
 
383
- `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.
392
+ `bun run bundle` produces a stdio-only `.mcpb` for Claude Desktop. Use root-anchored entries in `.mcpbignore` for source, tests, docs, plugin manifests, and other repository-local paths. Root `skills/` and the compiled mirror CLI in `dist/cli/` ship in the bundle. Cleanup removes dev dependencies, dependency agent docs, DuckDB platform bindings, node-gyp intermediate files, and build-only package files. The required `better-sqlite3` dependency retains all eight N-API prebuilts (macOS, Windows, Linux glibc/musl × x64/arm64).
393
+
394
+ Root `plugin.json` and `mcp.json` are the Agent Plugins 1.0.0 metadata and stdio launcher. Keep user-supplied variables in the host overlays and retain the `.codex-plugin/plugin.json` pointer to `./.codex-plugin/mcp.json` so Codex can forward them.
384
395
 
385
396
  **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, that every `user_config` option is wired into `mcp_config.env` as `"X": "${user_config.X}"` (the host substitutes nothing else — `"${X}"` reaches the server as that literal string), and that an optional string option carries `"default": ""`.
386
397
 
@@ -441,7 +452,7 @@ import { getRegistryService } from '@/services/registry/registry-service.js';
441
452
  - [ ] 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`.
442
453
  - [ ] JSDoc `@fileoverview` + `@module` on every file
443
454
  - [ ] `ctx.log` for logging; data access goes through `registry-service` (the mirror), never persistence directly
444
- - [ ] Owner-PII redaction holds: PII fields dropped AND owner-name search disabled when redacted; the gate is the single chokepoint in `registry-service`
455
+ - [ ] Owner-PII redaction holds across output, matching, counts and ordering; owner-name search stays disabled when redacted
445
456
  - [ ] Handlers throw on failure — error factories or plain `Error`, no try/catch
446
457
  - [ ] `format()` renders all data the LLM needs — different clients forward different surfaces (Claude Code → `structuredContent`, Claude Desktop → `content[]`); both must carry the same data
447
458
  - [ ] If wrapping external API: raw/domain/output schemas reviewed against real upstream sparsity/nullability before finalizing required vs optional fields
@@ -449,6 +460,8 @@ import { getRegistryService } from '@/services/registry/registry-service.js';
449
460
  - [ ] If wrapping external API: tests include at least one sparse payload case with omitted upstream fields
450
461
  - [ ] Registered in `createApp()` arrays (directly or via barrel exports)
451
462
  - [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
463
+ - [ ] Root plugin metadata matches `package.json` and the root launcher carries only fixed environment values
464
+ - [ ] Any published skill passes `lint:packaging`, with its gates and identifiers verified in a field test
452
465
  - [ ] `.codex-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; `interface.displayName` = the unscoped repo name (never the npm scope — `lint:packaging` enforces this); `interface.shortDescription` from `package.json` description
453
466
  - [ ] `.codex-plugin/mcp.json` updated — server name key is the unscoped repo name; every user-supplied variable (API key, contact email, instance URL) is listed in `env_vars` so Codex forwards it from the user's environment. Never write `"KEY": ""` into `env` — an empty value replaces the user's exported key and is read as unset
454
467
  - [ ] `.claude-plugin/plugin.json` populated — `name`, `version`, `description`, `author`, `repository`, `license`, `keywords` from `package.json`; inline `mcpServers` entry keyed by the unscoped repo name. Every user-supplied variable is declared under `userConfig` (`type`, `title`, `description`; `sensitive: true` for keys and tokens; `required: true` or `default: ""`) and referenced from `env` as `"KEY": "${user_config.<option>}"` — mirror the `user_config` block in `manifest.json`. Never write `"KEY": ""` into `env`
package/Dockerfile CHANGED
@@ -14,23 +14,22 @@
14
14
  # output. A stage that compiles a native addon needs the target-arch toolchain
15
15
  # and cannot cross-compile this way — drop the flag there.
16
16
  # ==============================================================================
17
- FROM --platform=$BUILDPLATFORM oven/bun:1.4.3 AS build
17
+ FROM --platform=$BUILDPLATFORM oven/bun:1.4.4 AS build
18
18
 
19
19
  WORKDIR /usr/src/app
20
20
 
21
21
  # Copy dependency manifests for optimized layer caching
22
22
  COPY package.json bun.lock ./
23
23
 
24
- # Install all dependencies (including dev dependencies for building). Skip
25
- # lifecycle scripts so the optional `better-sqlite3` native addon isn't compiled
26
- # (node-gyp toolchain is absent on the bun base image) — the runtime uses Bun's
27
- # built-in `bun:sqlite`, so the addon is never loaded in this image.
24
+ # Install all dependencies (including dev dependencies for building). The runtime
25
+ # uses Bun's built-in `bun:sqlite`; better-sqlite3 ships prebuilts for Node users.
28
26
  # The BuildKit cache mount persists Bun's global package cache across builds.
29
27
  RUN --mount=type=cache,target=/root/.bun/install/cache \
30
28
  bun install --frozen-lockfile --ignore-scripts
31
29
 
32
30
  # Copy the rest of the source code
33
31
  COPY . .
32
+ RUN mkdir -p skills
34
33
 
35
34
  # Build the application
36
35
  RUN bun run build
@@ -49,7 +48,7 @@ RUN bun run build
49
48
  # A clean image rather than `FROM build`: the build stage's node_modules holds
50
49
  # devDependencies.
51
50
  # ==============================================================================
52
- FROM --platform=$BUILDPLATFORM oven/bun:1.4.3 AS deps
51
+ FROM --platform=$BUILDPLATFORM oven/bun:1.4.4 AS deps
53
52
 
54
53
  WORKDIR /usr/src/app
55
54
 
@@ -77,8 +76,7 @@ RUN case "$TARGETARCH" in \
77
76
  # Install only production dependencies, ignoring any lifecycle scripts (like 'prepare')
78
77
  # that are not needed in the final production image.
79
78
  # `--omit=peer` drops the framework's optional peer tiers (test runner, service
80
- # SDKs, parsers) that Bun would otherwise auto-install, and this server's own
81
- # optional `better-sqlite3` peer (the image runs on `bun:sqlite`). Anything this
79
+ # SDKs, parsers) that Bun would otherwise auto-install. Anything this
82
80
  # server actually imports belongs in its own `dependencies`, so nothing needed at
83
81
  # runtime is lost.
84
82
  RUN --mount=type=cache,target=/root/.bun/install/cache \
@@ -118,7 +116,7 @@ RUN rm -rf node_modules/@socketsecurity/bun-security-scanner
118
116
  # dependencies and build artifacts. Its only Bun invocations are HEALTHCHECK
119
117
  # and CMD, which run on the real target at container start.
120
118
  # ==============================================================================
121
- FROM oven/bun:1.4.3-slim AS production
119
+ FROM oven/bun:1.4.4-slim AS production
122
120
 
123
121
  WORKDIR /usr/src/app
124
122
 
@@ -140,18 +138,10 @@ COPY --from=deps /usr/src/app/node_modules ./node_modules
140
138
 
141
139
  # Copy the compiled application code from the build stage
142
140
  COPY --from=build /usr/src/app/dist ./dist
141
+ COPY --from=build /usr/src/app/skills ./skills
143
142
 
144
- # Mirror CLI (MirrorService — Tier 3). Copy the lifecycle scripts and the shared
145
- # context shim they import, then emit a runtime tsconfig so Bun resolves the @/
146
- # path alias against ./dist/ rather than the source ./src/ (which never reaches
147
- # the runtime image). Same `bun run mirror:*` commands work in dev and the image.
148
- # See the api-mirror skill for the full recipe.
149
- COPY --from=build /usr/src/app/scripts/faa-mirror-init.ts \
150
- /usr/src/app/scripts/faa-mirror-refresh.ts \
151
- /usr/src/app/scripts/faa-mirror-verify.ts \
152
- /usr/src/app/scripts/_mirror-context.ts \
153
- ./scripts/
154
- RUN echo '{"compilerOptions":{"baseUrl":".","paths":{"@/*":["./dist/*"]}}}' > tsconfig.json
143
+ # dist/cli contains the compiled mirror lifecycle commands. Their relative
144
+ # imports share the server's compiled modules; no source or runtime tsconfig.
155
145
 
156
146
  # The 'oven/bun' image already provides a non-root user named 'bun'.
157
147
  # We will use this existing user for enhanced security.