@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.
- package/AGENTS.md +30 -17
- package/CLAUDE.md +30 -17
- package/Dockerfile +5 -3
- package/README.md +67 -67
- package/changelog/0.2.x/0.2.0.md +45 -0
- package/changelog/0.2.x/0.2.1.md +35 -0
- package/changelog/template.md +10 -3
- package/dist/cli/_mirror-context.d.ts +1 -1
- package/dist/cli/_mirror-context.d.ts.map +1 -1
- package/dist/cli/_mirror-context.js +3 -5
- package/dist/cli/_mirror-context.js.map +1 -1
- package/dist/cli/faa-mirror-init.d.ts +2 -2
- package/dist/cli/faa-mirror-init.js +2 -2
- package/dist/cli/faa-mirror-refresh.d.ts +3 -3
- package/dist/cli/faa-mirror-refresh.js +3 -3
- package/dist/cli/faa-mirror-verify.js +19 -10
- package/dist/cli/faa-mirror-verify.js.map +1 -1
- package/dist/config/server-config.d.ts +1 -0
- package/dist/config/server-config.d.ts.map +1 -1
- package/dist/config/server-config.js +3 -0
- package/dist/config/server-config.js.map +1 -1
- package/dist/index.js +4 -3
- package/dist/index.js.map +1 -1
- package/dist/lifecycle.d.ts +2 -3
- package/dist/lifecycle.d.ts.map +1 -1
- package/dist/lifecycle.js +15 -5
- package/dist/lifecycle.js.map +1 -1
- package/dist/mcp-server/_mirror-errors.d.ts +14 -0
- package/dist/mcp-server/_mirror-errors.d.ts.map +1 -0
- package/dist/mcp-server/_mirror-errors.js +14 -0
- package/dist/mcp-server/_mirror-errors.js.map +1 -0
- package/dist/mcp-server/resources/definitions/index.d.ts +13 -0
- package/dist/mcp-server/resources/definitions/index.d.ts.map +1 -1
- package/dist/mcp-server/resources/definitions/registration.resource.d.ts +13 -0
- package/dist/mcp-server/resources/definitions/registration.resource.d.ts.map +1 -1
- package/dist/mcp-server/resources/definitions/registration.resource.js +2 -0
- package/dist/mcp-server/resources/definitions/registration.resource.js.map +1 -1
- package/dist/mcp-server/tools/definitions/_response-metadata.d.ts +12 -0
- package/dist/mcp-server/tools/definitions/_response-metadata.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/_response-metadata.js +30 -0
- package/dist/mcp-server/tools/definitions/_response-metadata.js.map +1 -0
- package/dist/mcp-server/tools/definitions/_schemas.d.ts +6 -0
- package/dist/mcp-server/tools/definitions/_schemas.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/_schemas.js +41 -26
- package/dist/mcp-server/tools/definitions/_schemas.js.map +1 -1
- package/dist/mcp-server/tools/definitions/_search-page.d.ts +34 -0
- package/dist/mcp-server/tools/definitions/_search-page.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/_search-page.js +64 -0
- package/dist/mcp-server/tools/definitions/_search-page.js.map +1 -0
- package/dist/mcp-server/tools/definitions/get-aircraft-type.tool.d.ts +11 -1
- package/dist/mcp-server/tools/definitions/get-aircraft-type.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-aircraft-type.tool.js +18 -7
- package/dist/mcp-server/tools/definitions/get-aircraft-type.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-registration-status.tool.d.ts +28 -2
- package/dist/mcp-server/tools/definitions/get-registration-status.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-registration-status.tool.js +75 -17
- package/dist/mcp-server/tools/definitions/get-registration-status.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/index.d.ts +149 -51
- package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/lookup-registration.tool.d.ts +17 -1
- package/dist/mcp-server/tools/definitions/lookup-registration.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/lookup-registration.tool.js +9 -1
- package/dist/mcp-server/tools/definitions/lookup-registration.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/search-aircraft-types.tool.d.ts +14 -6
- package/dist/mcp-server/tools/definitions/search-aircraft-types.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/search-aircraft-types.tool.js +22 -57
- package/dist/mcp-server/tools/definitions/search-aircraft-types.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/search-registrations.tool.d.ts +43 -4
- package/dist/mcp-server/tools/definitions/search-registrations.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/search-registrations.tool.js +143 -60
- package/dist/mcp-server/tools/definitions/search-registrations.tool.js.map +1 -1
- package/dist/services/registry/decode.d.ts +3 -0
- package/dist/services/registry/decode.d.ts.map +1 -1
- package/dist/services/registry/decode.js +91 -0
- package/dist/services/registry/decode.js.map +1 -1
- package/dist/services/registry/ingest.d.ts +2 -2
- package/dist/services/registry/ingest.d.ts.map +1 -1
- package/dist/services/registry/ingest.js +181 -69
- package/dist/services/registry/ingest.js.map +1 -1
- package/dist/services/registry/mode-s.d.ts +25 -0
- package/dist/services/registry/mode-s.d.ts.map +1 -0
- package/dist/services/registry/mode-s.js +55 -0
- package/dist/services/registry/mode-s.js.map +1 -0
- package/dist/services/registry/normalize.d.ts +65 -8
- package/dist/services/registry/normalize.d.ts.map +1 -1
- package/dist/services/registry/normalize.js +139 -43
- package/dist/services/registry/normalize.js.map +1 -1
- package/dist/services/registry/registry-mirror.d.ts +11 -0
- package/dist/services/registry/registry-mirror.d.ts.map +1 -0
- package/dist/services/registry/registry-mirror.js +37 -0
- package/dist/services/registry/registry-mirror.js.map +1 -0
- package/dist/services/registry/registry-search.d.ts +16 -0
- package/dist/services/registry/registry-search.d.ts.map +1 -0
- package/dist/services/registry/registry-search.js +132 -0
- package/dist/services/registry/registry-search.js.map +1 -0
- package/dist/services/registry/registry-service.d.ts +15 -28
- package/dist/services/registry/registry-service.d.ts.map +1 -1
- package/dist/services/registry/registry-service.js +145 -222
- package/dist/services/registry/registry-service.js.map +1 -1
- package/dist/services/registry/registry-snapshot.d.ts +12 -0
- package/dist/services/registry/registry-snapshot.d.ts.map +1 -0
- package/dist/services/registry/registry-snapshot.js +30 -0
- package/dist/services/registry/registry-snapshot.js.map +1 -0
- package/dist/services/registry/schema.d.ts +3 -14
- package/dist/services/registry/schema.d.ts.map +1 -1
- package/dist/services/registry/schema.js +64 -13
- package/dist/services/registry/schema.js.map +1 -1
- package/dist/services/registry/types.d.ts +32 -7
- package/dist/services/registry/types.d.ts.map +1 -1
- package/dist/services/registry/types.js.map +1 -1
- package/dist/services/registry/zip.d.ts +2 -0
- package/dist/services/registry/zip.d.ts.map +1 -1
- package/dist/services/registry/zip.js +22 -2
- package/dist/services/registry/zip.js.map +1 -1
- package/package.json +11 -10
- package/server.json +19 -5
- 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
|
|
5
|
-
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.
|
|
6
|
-
**Engines:** Bun ≥1.4.
|
|
7
|
-
**MCP SDK:** `@modelcontextprotocol/server` ^2.
|
|
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.
|
|
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')
|
|
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
|
-
|
|
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 #
|
|
263
|
+
server-config.ts # redaction, limit clamping, mirror path and source URL (Zod schema)
|
|
260
264
|
services/
|
|
261
265
|
registry/
|
|
262
|
-
registry-service.ts #
|
|
263
|
-
|
|
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} (
|
|
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 —
|
|
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
|
-
|
|
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
|
|
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`
|
|
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
|
|
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
|
|
5
|
-
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.
|
|
6
|
-
**Engines:** Bun ≥1.4.
|
|
7
|
-
**MCP SDK:** `@modelcontextprotocol/server` ^2.
|
|
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.
|
|
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')
|
|
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
|
-
|
|
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 #
|
|
263
|
+
server-config.ts # redaction, limit clamping, mirror path and source URL (Zod schema)
|
|
260
264
|
services/
|
|
261
265
|
registry/
|
|
262
|
-
registry-service.ts #
|
|
263
|
-
|
|
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} (
|
|
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 —
|
|
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
|
-
|
|
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
|
|
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`
|
|
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
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|