@cyanheads/faa-aircraft-registry-mcp-server 0.1.12 → 0.2.1

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 (117) hide show
  1. package/AGENTS.md +30 -17
  2. package/CLAUDE.md +30 -17
  3. package/Dockerfile +5 -3
  4. package/README.md +67 -67
  5. package/changelog/0.2.x/0.2.0.md +45 -0
  6. package/changelog/0.2.x/0.2.1.md +35 -0
  7. package/changelog/template.md +10 -3
  8. package/dist/cli/_mirror-context.d.ts +1 -1
  9. package/dist/cli/_mirror-context.d.ts.map +1 -1
  10. package/dist/cli/_mirror-context.js +3 -5
  11. package/dist/cli/_mirror-context.js.map +1 -1
  12. package/dist/cli/faa-mirror-init.d.ts +2 -2
  13. package/dist/cli/faa-mirror-init.js +2 -2
  14. package/dist/cli/faa-mirror-refresh.d.ts +3 -3
  15. package/dist/cli/faa-mirror-refresh.js +3 -3
  16. package/dist/cli/faa-mirror-verify.js +19 -10
  17. package/dist/cli/faa-mirror-verify.js.map +1 -1
  18. package/dist/config/server-config.d.ts +1 -0
  19. package/dist/config/server-config.d.ts.map +1 -1
  20. package/dist/config/server-config.js +3 -0
  21. package/dist/config/server-config.js.map +1 -1
  22. package/dist/index.js +4 -3
  23. package/dist/index.js.map +1 -1
  24. package/dist/lifecycle.d.ts +2 -3
  25. package/dist/lifecycle.d.ts.map +1 -1
  26. package/dist/lifecycle.js +15 -5
  27. package/dist/lifecycle.js.map +1 -1
  28. package/dist/mcp-server/_mirror-errors.d.ts +14 -0
  29. package/dist/mcp-server/_mirror-errors.d.ts.map +1 -0
  30. package/dist/mcp-server/_mirror-errors.js +14 -0
  31. package/dist/mcp-server/_mirror-errors.js.map +1 -0
  32. package/dist/mcp-server/resources/definitions/index.d.ts +13 -0
  33. package/dist/mcp-server/resources/definitions/index.d.ts.map +1 -1
  34. package/dist/mcp-server/resources/definitions/registration.resource.d.ts +13 -0
  35. package/dist/mcp-server/resources/definitions/registration.resource.d.ts.map +1 -1
  36. package/dist/mcp-server/resources/definitions/registration.resource.js +2 -0
  37. package/dist/mcp-server/resources/definitions/registration.resource.js.map +1 -1
  38. package/dist/mcp-server/tools/definitions/_response-metadata.d.ts +12 -0
  39. package/dist/mcp-server/tools/definitions/_response-metadata.d.ts.map +1 -0
  40. package/dist/mcp-server/tools/definitions/_response-metadata.js +30 -0
  41. package/dist/mcp-server/tools/definitions/_response-metadata.js.map +1 -0
  42. package/dist/mcp-server/tools/definitions/_schemas.d.ts +6 -0
  43. package/dist/mcp-server/tools/definitions/_schemas.d.ts.map +1 -1
  44. package/dist/mcp-server/tools/definitions/_schemas.js +41 -26
  45. package/dist/mcp-server/tools/definitions/_schemas.js.map +1 -1
  46. package/dist/mcp-server/tools/definitions/_search-page.d.ts +34 -0
  47. package/dist/mcp-server/tools/definitions/_search-page.d.ts.map +1 -0
  48. package/dist/mcp-server/tools/definitions/_search-page.js +64 -0
  49. package/dist/mcp-server/tools/definitions/_search-page.js.map +1 -0
  50. package/dist/mcp-server/tools/definitions/get-aircraft-type.tool.d.ts +11 -1
  51. package/dist/mcp-server/tools/definitions/get-aircraft-type.tool.d.ts.map +1 -1
  52. package/dist/mcp-server/tools/definitions/get-aircraft-type.tool.js +18 -7
  53. package/dist/mcp-server/tools/definitions/get-aircraft-type.tool.js.map +1 -1
  54. package/dist/mcp-server/tools/definitions/get-registration-status.tool.d.ts +28 -2
  55. package/dist/mcp-server/tools/definitions/get-registration-status.tool.d.ts.map +1 -1
  56. package/dist/mcp-server/tools/definitions/get-registration-status.tool.js +75 -17
  57. package/dist/mcp-server/tools/definitions/get-registration-status.tool.js.map +1 -1
  58. package/dist/mcp-server/tools/definitions/index.d.ts +149 -51
  59. package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -1
  60. package/dist/mcp-server/tools/definitions/lookup-registration.tool.d.ts +17 -1
  61. package/dist/mcp-server/tools/definitions/lookup-registration.tool.d.ts.map +1 -1
  62. package/dist/mcp-server/tools/definitions/lookup-registration.tool.js +9 -1
  63. package/dist/mcp-server/tools/definitions/lookup-registration.tool.js.map +1 -1
  64. package/dist/mcp-server/tools/definitions/search-aircraft-types.tool.d.ts +14 -6
  65. package/dist/mcp-server/tools/definitions/search-aircraft-types.tool.d.ts.map +1 -1
  66. package/dist/mcp-server/tools/definitions/search-aircraft-types.tool.js +22 -57
  67. package/dist/mcp-server/tools/definitions/search-aircraft-types.tool.js.map +1 -1
  68. package/dist/mcp-server/tools/definitions/search-registrations.tool.d.ts +43 -4
  69. package/dist/mcp-server/tools/definitions/search-registrations.tool.d.ts.map +1 -1
  70. package/dist/mcp-server/tools/definitions/search-registrations.tool.js +143 -60
  71. package/dist/mcp-server/tools/definitions/search-registrations.tool.js.map +1 -1
  72. package/dist/services/registry/decode.d.ts +3 -0
  73. package/dist/services/registry/decode.d.ts.map +1 -1
  74. package/dist/services/registry/decode.js +91 -0
  75. package/dist/services/registry/decode.js.map +1 -1
  76. package/dist/services/registry/ingest.d.ts +2 -2
  77. package/dist/services/registry/ingest.d.ts.map +1 -1
  78. package/dist/services/registry/ingest.js +181 -69
  79. package/dist/services/registry/ingest.js.map +1 -1
  80. package/dist/services/registry/mode-s.d.ts +25 -0
  81. package/dist/services/registry/mode-s.d.ts.map +1 -0
  82. package/dist/services/registry/mode-s.js +55 -0
  83. package/dist/services/registry/mode-s.js.map +1 -0
  84. package/dist/services/registry/normalize.d.ts +65 -8
  85. package/dist/services/registry/normalize.d.ts.map +1 -1
  86. package/dist/services/registry/normalize.js +139 -43
  87. package/dist/services/registry/normalize.js.map +1 -1
  88. package/dist/services/registry/registry-mirror.d.ts +11 -0
  89. package/dist/services/registry/registry-mirror.d.ts.map +1 -0
  90. package/dist/services/registry/registry-mirror.js +37 -0
  91. package/dist/services/registry/registry-mirror.js.map +1 -0
  92. package/dist/services/registry/registry-search.d.ts +16 -0
  93. package/dist/services/registry/registry-search.d.ts.map +1 -0
  94. package/dist/services/registry/registry-search.js +132 -0
  95. package/dist/services/registry/registry-search.js.map +1 -0
  96. package/dist/services/registry/registry-service.d.ts +15 -28
  97. package/dist/services/registry/registry-service.d.ts.map +1 -1
  98. package/dist/services/registry/registry-service.js +145 -222
  99. package/dist/services/registry/registry-service.js.map +1 -1
  100. package/dist/services/registry/registry-snapshot.d.ts +12 -0
  101. package/dist/services/registry/registry-snapshot.d.ts.map +1 -0
  102. package/dist/services/registry/registry-snapshot.js +30 -0
  103. package/dist/services/registry/registry-snapshot.js.map +1 -0
  104. package/dist/services/registry/schema.d.ts +3 -14
  105. package/dist/services/registry/schema.d.ts.map +1 -1
  106. package/dist/services/registry/schema.js +64 -13
  107. package/dist/services/registry/schema.js.map +1 -1
  108. package/dist/services/registry/types.d.ts +32 -7
  109. package/dist/services/registry/types.d.ts.map +1 -1
  110. package/dist/services/registry/types.js.map +1 -1
  111. package/dist/services/registry/zip.d.ts +2 -0
  112. package/dist/services/registry/zip.d.ts.map +1 -1
  113. package/dist/services/registry/zip.js +22 -2
  114. package/dist/services/registry/zip.js.map +1 -1
  115. package/package.json +11 -10
  116. package/server.json +19 -5
  117. package/skills/faa-aircraft-registry-guide/SKILL.md +41 -0
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.12
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.1
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,14 +260,18 @@ 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)
274
+ mode-s.ts # Mode S (ICAO 24-bit) → N-number decoder
267
275
  schema.ts # sqliteMirrorStore column + FTS5 + index spec
268
276
  types.ts # domain types
269
277
  mcp-server/
@@ -275,10 +283,10 @@ src/
275
283
  search-aircraft-types.tool.ts # FTS5 search of the aircraft reference table
276
284
  get-aircraft-type.tool.ts # decode a 6–7-character mfr/model/series code
277
285
  resources/definitions/
278
- registration.resource.ts # faa://registration/{nNumber} (reuses the lookup handler)
286
+ registration.resource.ts # faa://registration/{nNumber} (shares the lookup record schema)
279
287
  cli/
280
288
  faa-mirror-init.ts # mirror:init — full out-of-band build
281
- faa-mirror-refresh.ts # mirror:refresh — incremental/full rebuild
289
+ faa-mirror-refresh.ts # mirror:refresh — full rebuild
282
290
  faa-mirror-verify.ts # mirror:verify — readiness + integrity check
283
291
  _mirror-context.ts # shared mirror-instance shim for the three CLI scripts
284
292
  ```
@@ -298,7 +306,7 @@ src/
298
306
 
299
307
  ## Skills
300
308
 
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.
309
+ 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
310
 
303
311
  **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
312
 
@@ -313,6 +321,7 @@ Available skills:
313
321
  | `add-resource` | Scaffold a new resource definition |
314
322
  | `add-prompt` | Scaffold a new prompt definition |
315
323
  | `add-service` | Scaffold a new service integration |
324
+ | `add-skill` | Author and verify a published skill in root `skills/` |
316
325
  | `add-test` | Scaffold test file for a tool, resource, or service |
317
326
  | `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
318
327
  | `tool-defs-analysis` | Read-only audit of MCP definition language across the surface — voice, leaks, defaults, recovery hints, output descriptions |
@@ -366,7 +375,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
366
375
  | `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
367
376
  | `bun run test` | Run unit and integration tests (Vitest — use `bun run test`, not `bun test`) |
368
377
  | `bun run test:package` | Build and exercise the npm tarball and cleaned MCPB with real Node and Bun processes |
369
- | `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. |
378
+ | `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. |
370
379
  | `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. |
371
380
  | `bun run mirror:verify` | Report index health — readiness, sync status, record count, SQLite integrity check. Exits non-zero when not ready or integrity fails. |
372
381
  | `bun run start:stdio` | Production mode (stdio) |
@@ -381,7 +390,9 @@ When you complete a skill's checklist, check the boxes and add a completion time
381
390
 
382
391
  ## Bundling
383
392
 
384
- `bun run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. Cleanup prunes dev dependencies, dependency-shipped agent docs, and optional DuckDB platform bindings. The required `better-sqlite3` production dependency retains all eight bundled N-API prebuilts (macOS, Windows, Linux glibc/musl × x64/arm64). Source and development scripts are excluded; the mirror CLI ships as `dist/cli/*.js`. MCPB is stdio-only.
393
+ `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).
394
+
395
+ 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.
385
396
 
386
397
  **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": ""`.
387
398
 
@@ -442,7 +453,7 @@ import { getRegistryService } from '@/services/registry/registry-service.js';
442
453
  - [ ] 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`.
443
454
  - [ ] JSDoc `@fileoverview` + `@module` on every file
444
455
  - [ ] `ctx.log` for logging; data access goes through `registry-service` (the mirror), never persistence directly
445
- - [ ] Owner-PII redaction holds: PII fields dropped AND owner-name search disabled when redacted; the gate is the single chokepoint in `registry-service`
456
+ - [ ] Owner-PII redaction holds across output, matching, counts and ordering; owner-name search stays disabled when redacted
446
457
  - [ ] Handlers throw on failure — error factories or plain `Error`, no try/catch
447
458
  - [ ] `format()` renders all data the LLM needs — different clients forward different surfaces (Claude Code → `structuredContent`, Claude Desktop → `content[]`); both must carry the same data
448
459
  - [ ] If wrapping external API: raw/domain/output schemas reviewed against real upstream sparsity/nullability before finalizing required vs optional fields
@@ -450,6 +461,8 @@ import { getRegistryService } from '@/services/registry/registry-service.js';
450
461
  - [ ] If wrapping external API: tests include at least one sparse payload case with omitted upstream fields
451
462
  - [ ] Registered in `createApp()` arrays (directly or via barrel exports)
452
463
  - [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
464
+ - [ ] Root plugin metadata matches `package.json` and the root launcher carries only fixed environment values
465
+ - [ ] Any published skill passes `lint:packaging`, with its gates and identifiers verified in a field test
453
466
  - [ ] `.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
454
467
  - [ ] `.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
455
468
  - [ ] `.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.12
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.1
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,14 +260,18 @@ 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)
274
+ mode-s.ts # Mode S (ICAO 24-bit) → N-number decoder
267
275
  schema.ts # sqliteMirrorStore column + FTS5 + index spec
268
276
  types.ts # domain types
269
277
  mcp-server/
@@ -275,10 +283,10 @@ src/
275
283
  search-aircraft-types.tool.ts # FTS5 search of the aircraft reference table
276
284
  get-aircraft-type.tool.ts # decode a 6–7-character mfr/model/series code
277
285
  resources/definitions/
278
- registration.resource.ts # faa://registration/{nNumber} (reuses the lookup handler)
286
+ registration.resource.ts # faa://registration/{nNumber} (shares the lookup record schema)
279
287
  cli/
280
288
  faa-mirror-init.ts # mirror:init — full out-of-band build
281
- faa-mirror-refresh.ts # mirror:refresh — incremental/full rebuild
289
+ faa-mirror-refresh.ts # mirror:refresh — full rebuild
282
290
  faa-mirror-verify.ts # mirror:verify — readiness + integrity check
283
291
  _mirror-context.ts # shared mirror-instance shim for the three CLI scripts
284
292
  ```
@@ -298,7 +306,7 @@ src/
298
306
 
299
307
  ## Skills
300
308
 
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.
309
+ 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
310
 
303
311
  **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
312
 
@@ -313,6 +321,7 @@ Available skills:
313
321
  | `add-resource` | Scaffold a new resource definition |
314
322
  | `add-prompt` | Scaffold a new prompt definition |
315
323
  | `add-service` | Scaffold a new service integration |
324
+ | `add-skill` | Author and verify a published skill in root `skills/` |
316
325
  | `add-test` | Scaffold test file for a tool, resource, or service |
317
326
  | `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
318
327
  | `tool-defs-analysis` | Read-only audit of MCP definition language across the surface — voice, leaks, defaults, recovery hints, output descriptions |
@@ -366,7 +375,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
366
375
  | `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
367
376
  | `bun run test` | Run unit and integration tests (Vitest — use `bun run test`, not `bun test`) |
368
377
  | `bun run test:package` | Build and exercise the npm tarball and cleaned MCPB with real Node and Bun processes |
369
- | `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. |
378
+ | `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. |
370
379
  | `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. |
371
380
  | `bun run mirror:verify` | Report index health — readiness, sync status, record count, SQLite integrity check. Exits non-zero when not ready or integrity fails. |
372
381
  | `bun run start:stdio` | Production mode (stdio) |
@@ -381,7 +390,9 @@ When you complete a skill's checklist, check the boxes and add a completion time
381
390
 
382
391
  ## Bundling
383
392
 
384
- `bun run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. Cleanup prunes dev dependencies, dependency-shipped agent docs, and optional DuckDB platform bindings. The required `better-sqlite3` production dependency retains all eight bundled N-API prebuilts (macOS, Windows, Linux glibc/musl × x64/arm64). Source and development scripts are excluded; the mirror CLI ships as `dist/cli/*.js`. MCPB is stdio-only.
393
+ `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).
394
+
395
+ 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.
385
396
 
386
397
  **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": ""`.
387
398
 
@@ -442,7 +453,7 @@ import { getRegistryService } from '@/services/registry/registry-service.js';
442
453
  - [ ] 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`.
443
454
  - [ ] JSDoc `@fileoverview` + `@module` on every file
444
455
  - [ ] `ctx.log` for logging; data access goes through `registry-service` (the mirror), never persistence directly
445
- - [ ] Owner-PII redaction holds: PII fields dropped AND owner-name search disabled when redacted; the gate is the single chokepoint in `registry-service`
456
+ - [ ] Owner-PII redaction holds across output, matching, counts and ordering; owner-name search stays disabled when redacted
446
457
  - [ ] Handlers throw on failure — error factories or plain `Error`, no try/catch
447
458
  - [ ] `format()` renders all data the LLM needs — different clients forward different surfaces (Claude Code → `structuredContent`, Claude Desktop → `content[]`); both must carry the same data
448
459
  - [ ] If wrapping external API: raw/domain/output schemas reviewed against real upstream sparsity/nullability before finalizing required vs optional fields
@@ -450,6 +461,8 @@ import { getRegistryService } from '@/services/registry/registry-service.js';
450
461
  - [ ] If wrapping external API: tests include at least one sparse payload case with omitted upstream fields
451
462
  - [ ] Registered in `createApp()` arrays (directly or via barrel exports)
452
463
  - [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
464
+ - [ ] Root plugin metadata matches `package.json` and the root launcher carries only fixed environment values
465
+ - [ ] Any published skill passes `lint:packaging`, with its gates and identifiers verified in a field test
453
466
  - [ ] `.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
454
467
  - [ ] `.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
455
468
  - [ ] `.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,7 +14,7 @@
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
 
@@ -29,6 +29,7 @@ RUN --mount=type=cache,target=/root/.bun/install/cache \
29
29
 
30
30
  # Copy the rest of the source code
31
31
  COPY . .
32
+ RUN mkdir -p skills
32
33
 
33
34
  # Build the application
34
35
  RUN bun run build
@@ -47,7 +48,7 @@ RUN bun run build
47
48
  # A clean image rather than `FROM build`: the build stage's node_modules holds
48
49
  # devDependencies.
49
50
  # ==============================================================================
50
- FROM --platform=$BUILDPLATFORM oven/bun:1.4.3 AS deps
51
+ FROM --platform=$BUILDPLATFORM oven/bun:1.4.4 AS deps
51
52
 
52
53
  WORKDIR /usr/src/app
53
54
 
@@ -115,7 +116,7 @@ RUN rm -rf node_modules/@socketsecurity/bun-security-scanner
115
116
  # dependencies and build artifacts. Its only Bun invocations are HEALTHCHECK
116
117
  # and CMD, which run on the real target at container start.
117
118
  # ==============================================================================
118
- FROM oven/bun:1.4.3-slim AS production
119
+ FROM oven/bun:1.4.4-slim AS production
119
120
 
120
121
  WORKDIR /usr/src/app
121
122
 
@@ -137,6 +138,7 @@ COPY --from=deps /usr/src/app/node_modules ./node_modules
137
138
 
138
139
  # Copy the compiled application code from the build stage
139
140
  COPY --from=build /usr/src/app/dist ./dist
141
+ COPY --from=build /usr/src/app/skills ./skills
140
142
 
141
143
  # dist/cli contains the compiled mirror lifecycle commands. Their relative
142
144
  # imports share the server's compiled modules; no source or runtime tsconfig.