@cyanheads/faa-aircraft-registry-mcp-server 0.1.12 → 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.
- package/AGENTS.md +29 -17
- package/CLAUDE.md +29 -17
- package/Dockerfile +5 -3
- package/README.md +64 -67
- package/changelog/0.2.x/0.2.0.md +45 -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 +74 -16
- package/dist/mcp-server/tools/definitions/get-registration-status.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/index.d.ts +126 -56
- 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 +21 -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 +18 -8
- package/dist/mcp-server/tools/definitions/search-registrations.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/search-registrations.tool.js +40 -63
- 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 +125 -69
- package/dist/services/registry/ingest.js.map +1 -1
- package/dist/services/registry/normalize.d.ts +26 -2
- package/dist/services/registry/normalize.d.ts.map +1 -1
- package/dist/services/registry/normalize.js +33 -30
- 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 +12 -0
- package/dist/services/registry/registry-search.d.ts.map +1 -0
- package/dist/services/registry/registry-search.js +110 -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 +143 -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 +43 -13
- package/dist/services/registry/schema.js.map +1 -1
- package/dist/services/registry/types.d.ts +24 -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 +10 -9
- package/server.json +17 -3
- package/skills/faa-aircraft-registry-guide/SKILL.md +40 -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.
|
|
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.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.
|
|
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,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 #
|
|
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)
|
|
@@ -275,10 +282,10 @@ 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} (
|
|
285
|
+
registration.resource.ts # faa://registration/{nNumber} (shares the lookup record schema)
|
|
279
286
|
cli/
|
|
280
287
|
faa-mirror-init.ts # mirror:init — full out-of-band build
|
|
281
|
-
faa-mirror-refresh.ts # mirror:refresh —
|
|
288
|
+
faa-mirror-refresh.ts # mirror:refresh — full rebuild
|
|
282
289
|
faa-mirror-verify.ts # mirror:verify — readiness + integrity check
|
|
283
290
|
_mirror-context.ts # shared mirror-instance shim for the three CLI scripts
|
|
284
291
|
```
|
|
@@ -298,7 +305,7 @@ src/
|
|
|
298
305
|
|
|
299
306
|
## Skills
|
|
300
307
|
|
|
301
|
-
|
|
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 |
|
|
@@ -366,7 +374,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
|
|
|
366
374
|
| `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
|
|
367
375
|
| `bun run test` | Run unit and integration tests (Vitest — use `bun run test`, not `bun test`) |
|
|
368
376
|
| `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
|
|
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. |
|
|
370
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. |
|
|
371
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. |
|
|
372
380
|
| `bun run start:stdio` | Production mode (stdio) |
|
|
@@ -381,7 +389,9 @@ When you complete a skill's checklist, check the boxes and add a completion time
|
|
|
381
389
|
|
|
382
390
|
## Bundling
|
|
383
391
|
|
|
384
|
-
`bun run bundle` produces a `.mcpb`
|
|
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.
|
|
385
395
|
|
|
386
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": ""`.
|
|
387
397
|
|
|
@@ -442,7 +452,7 @@ import { getRegistryService } from '@/services/registry/registry-service.js';
|
|
|
442
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`.
|
|
443
453
|
- [ ] JSDoc `@fileoverview` + `@module` on every file
|
|
444
454
|
- [ ] `ctx.log` for logging; data access goes through `registry-service` (the mirror), never persistence directly
|
|
445
|
-
- [ ] Owner-PII redaction holds
|
|
455
|
+
- [ ] Owner-PII redaction holds across output, matching, counts and ordering; owner-name search stays disabled when redacted
|
|
446
456
|
- [ ] Handlers throw on failure — error factories or plain `Error`, no try/catch
|
|
447
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
|
|
448
458
|
- [ ] If wrapping external API: raw/domain/output schemas reviewed against real upstream sparsity/nullability before finalizing required vs optional fields
|
|
@@ -450,6 +460,8 @@ import { getRegistryService } from '@/services/registry/registry-service.js';
|
|
|
450
460
|
- [ ] If wrapping external API: tests include at least one sparse payload case with omitted upstream fields
|
|
451
461
|
- [ ] Registered in `createApp()` arrays (directly or via barrel exports)
|
|
452
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
|
|
453
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
|
|
454
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
|
|
455
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.
|
|
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.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.
|
|
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,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 #
|
|
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)
|
|
@@ -275,10 +282,10 @@ 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} (
|
|
285
|
+
registration.resource.ts # faa://registration/{nNumber} (shares the lookup record schema)
|
|
279
286
|
cli/
|
|
280
287
|
faa-mirror-init.ts # mirror:init — full out-of-band build
|
|
281
|
-
faa-mirror-refresh.ts # mirror:refresh —
|
|
288
|
+
faa-mirror-refresh.ts # mirror:refresh — full rebuild
|
|
282
289
|
faa-mirror-verify.ts # mirror:verify — readiness + integrity check
|
|
283
290
|
_mirror-context.ts # shared mirror-instance shim for the three CLI scripts
|
|
284
291
|
```
|
|
@@ -298,7 +305,7 @@ src/
|
|
|
298
305
|
|
|
299
306
|
## Skills
|
|
300
307
|
|
|
301
|
-
|
|
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 |
|
|
@@ -366,7 +374,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
|
|
|
366
374
|
| `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
|
|
367
375
|
| `bun run test` | Run unit and integration tests (Vitest — use `bun run test`, not `bun test`) |
|
|
368
376
|
| `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
|
|
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. |
|
|
370
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. |
|
|
371
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. |
|
|
372
380
|
| `bun run start:stdio` | Production mode (stdio) |
|
|
@@ -381,7 +389,9 @@ When you complete a skill's checklist, check the boxes and add a completion time
|
|
|
381
389
|
|
|
382
390
|
## Bundling
|
|
383
391
|
|
|
384
|
-
`bun run bundle` produces a `.mcpb`
|
|
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.
|
|
385
395
|
|
|
386
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": ""`.
|
|
387
397
|
|
|
@@ -442,7 +452,7 @@ import { getRegistryService } from '@/services/registry/registry-service.js';
|
|
|
442
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`.
|
|
443
453
|
- [ ] JSDoc `@fileoverview` + `@module` on every file
|
|
444
454
|
- [ ] `ctx.log` for logging; data access goes through `registry-service` (the mirror), never persistence directly
|
|
445
|
-
- [ ] Owner-PII redaction holds
|
|
455
|
+
- [ ] Owner-PII redaction holds across output, matching, counts and ordering; owner-name search stays disabled when redacted
|
|
446
456
|
- [ ] Handlers throw on failure — error factories or plain `Error`, no try/catch
|
|
447
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
|
|
448
458
|
- [ ] If wrapping external API: raw/domain/output schemas reviewed against real upstream sparsity/nullability before finalizing required vs optional fields
|
|
@@ -450,6 +460,8 @@ import { getRegistryService } from '@/services/registry/registry-service.js';
|
|
|
450
460
|
- [ ] If wrapping external API: tests include at least one sparse payload case with omitted upstream fields
|
|
451
461
|
- [ ] Registered in `createApp()` arrays (directly or via barrel exports)
|
|
452
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
|
|
453
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
|
|
454
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
|
|
455
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,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.
|