@cyanheads/faa-aircraft-registry-mcp-server 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (89) hide show
  1. package/AGENTS.md +433 -0
  2. package/CLAUDE.md +433 -0
  3. package/Dockerfile +121 -0
  4. package/LICENSE +201 -0
  5. package/README.md +349 -0
  6. package/changelog/0.1.x/0.1.0.md +23 -0
  7. package/changelog/template.md +127 -0
  8. package/dist/config/server-config.d.ts +23 -0
  9. package/dist/config/server-config.d.ts.map +1 -0
  10. package/dist/config/server-config.js +68 -0
  11. package/dist/config/server-config.js.map +1 -0
  12. package/dist/index.d.ts +11 -0
  13. package/dist/index.d.ts.map +1 -0
  14. package/dist/index.js +73 -0
  15. package/dist/index.js.map +1 -0
  16. package/dist/mcp-server/resources/definitions/index.d.ts +72 -0
  17. package/dist/mcp-server/resources/definitions/index.d.ts.map +1 -0
  18. package/dist/mcp-server/resources/definitions/index.js +8 -0
  19. package/dist/mcp-server/resources/definitions/index.js.map +1 -0
  20. package/dist/mcp-server/resources/definitions/registration.resource.d.ts +76 -0
  21. package/dist/mcp-server/resources/definitions/registration.resource.d.ts.map +1 -0
  22. package/dist/mcp-server/resources/definitions/registration.resource.js +39 -0
  23. package/dist/mcp-server/resources/definitions/registration.resource.js.map +1 -0
  24. package/dist/mcp-server/tools/definitions/_schemas.d.ts +108 -0
  25. package/dist/mcp-server/tools/definitions/_schemas.d.ts.map +1 -0
  26. package/dist/mcp-server/tools/definitions/_schemas.js +205 -0
  27. package/dist/mcp-server/tools/definitions/_schemas.js.map +1 -0
  28. package/dist/mcp-server/tools/definitions/get-aircraft-type.tool.d.ts +44 -0
  29. package/dist/mcp-server/tools/definitions/get-aircraft-type.tool.d.ts.map +1 -0
  30. package/dist/mcp-server/tools/definitions/get-aircraft-type.tool.js +100 -0
  31. package/dist/mcp-server/tools/definitions/get-aircraft-type.tool.js.map +1 -0
  32. package/dist/mcp-server/tools/definitions/get-registration-status.tool.d.ts +51 -0
  33. package/dist/mcp-server/tools/definitions/get-registration-status.tool.d.ts.map +1 -0
  34. package/dist/mcp-server/tools/definitions/get-registration-status.tool.js +142 -0
  35. package/dist/mcp-server/tools/definitions/get-registration-status.tool.js.map +1 -0
  36. package/dist/mcp-server/tools/definitions/index.d.ts +212 -0
  37. package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -0
  38. package/dist/mcp-server/tools/definitions/index.js +18 -0
  39. package/dist/mcp-server/tools/definitions/index.js.map +1 -0
  40. package/dist/mcp-server/tools/definitions/lookup-registration.tool.d.ts +78 -0
  41. package/dist/mcp-server/tools/definitions/lookup-registration.tool.d.ts.map +1 -0
  42. package/dist/mcp-server/tools/definitions/lookup-registration.tool.js +45 -0
  43. package/dist/mcp-server/tools/definitions/lookup-registration.tool.js.map +1 -0
  44. package/dist/mcp-server/tools/definitions/search-aircraft-types.tool.d.ts +42 -0
  45. package/dist/mcp-server/tools/definitions/search-aircraft-types.tool.d.ts.map +1 -0
  46. package/dist/mcp-server/tools/definitions/search-aircraft-types.tool.js +122 -0
  47. package/dist/mcp-server/tools/definitions/search-aircraft-types.tool.js.map +1 -0
  48. package/dist/mcp-server/tools/definitions/search-registrations.tool.d.ts +55 -0
  49. package/dist/mcp-server/tools/definitions/search-registrations.tool.d.ts.map +1 -0
  50. package/dist/mcp-server/tools/definitions/search-registrations.tool.js +154 -0
  51. package/dist/mcp-server/tools/definitions/search-registrations.tool.js.map +1 -0
  52. package/dist/services/registry/csv.d.ts +21 -0
  53. package/dist/services/registry/csv.d.ts.map +1 -0
  54. package/dist/services/registry/csv.js +110 -0
  55. package/dist/services/registry/csv.js.map +1 -0
  56. package/dist/services/registry/decode.d.ts +20 -0
  57. package/dist/services/registry/decode.d.ts.map +1 -0
  58. package/dist/services/registry/decode.js +169 -0
  59. package/dist/services/registry/decode.js.map +1 -0
  60. package/dist/services/registry/ingest.d.ts +25 -0
  61. package/dist/services/registry/ingest.d.ts.map +1 -0
  62. package/dist/services/registry/ingest.js +332 -0
  63. package/dist/services/registry/ingest.js.map +1 -0
  64. package/dist/services/registry/normalize.d.ts +36 -0
  65. package/dist/services/registry/normalize.d.ts.map +1 -0
  66. package/dist/services/registry/normalize.js +67 -0
  67. package/dist/services/registry/normalize.js.map +1 -0
  68. package/dist/services/registry/registry-service.d.ts +66 -0
  69. package/dist/services/registry/registry-service.d.ts.map +1 -0
  70. package/dist/services/registry/registry-service.js +351 -0
  71. package/dist/services/registry/registry-service.js.map +1 -0
  72. package/dist/services/registry/schema.d.ts +41 -0
  73. package/dist/services/registry/schema.d.ts.map +1 -0
  74. package/dist/services/registry/schema.js +181 -0
  75. package/dist/services/registry/schema.js.map +1 -0
  76. package/dist/services/registry/types.d.ts +181 -0
  77. package/dist/services/registry/types.d.ts.map +1 -0
  78. package/dist/services/registry/types.js +23 -0
  79. package/dist/services/registry/types.js.map +1 -0
  80. package/dist/services/registry/zip.d.ts +25 -0
  81. package/dist/services/registry/zip.d.ts.map +1 -0
  82. package/dist/services/registry/zip.js +79 -0
  83. package/dist/services/registry/zip.js.map +1 -0
  84. package/package.json +122 -0
  85. package/scripts/_mirror-context.ts +23 -0
  86. package/scripts/faa-mirror-init.ts +24 -0
  87. package/scripts/faa-mirror-refresh.ts +23 -0
  88. package/scripts/faa-mirror-verify.ts +36 -0
  89. package/server.json +141 -0
package/CLAUDE.md ADDED
@@ -0,0 +1,433 @@
1
+ # Developer Protocol
2
+
3
+ **Server:** faa-aircraft-registry-mcp-server
4
+ **Version:** 0.1.0
5
+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.10.6`
6
+ **Engines:** Bun ≥1.3.0, Node ≥24.0.0
7
+ **MCP SDK:** `@modelcontextprotocol/sdk` ^1.29.0
8
+ **Zod:** ^4.4.3
9
+
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.
11
+
12
+ ---
13
+
14
+ ## What This Server Is
15
+
16
+ An offline lookup server for the US civil aircraft registry. It indexes the FAA's public-domain [Releasable Aircraft Database](https://registry.faa.gov/database/ReleasableAircraft.zip) into an embedded SQLite + FTS5 mirror (built via the framework `MirrorService`), pre-joining `MASTER` → `ACFTREF` → `ENGINE` and decoding coded fields at query time. Keyless, no runtime network — every query hits the local index.
17
+
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
+
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.
21
+
22
+ ---
23
+
24
+ ## Core Rules
25
+
26
+ - **Logic throws, framework catches.** Tool/resource handlers are pure — throw on failure, no `try/catch`. Plain `Error` is fine; the framework catches, classifies, and formats. Use error factories (`notFound()`, `validationError()`, etc.) when the error code matters.
27
+ - **Use `ctx.log`** for request-scoped logging. No `console` calls.
28
+ - **Use `ctx.state`** for tenant-scoped storage. Never access persistence directly.
29
+ - **Check `ctx.elicit`** for presence before calling.
30
+ - **Secrets in env vars only** — never hardcoded.
31
+ - **Close the loop on issues.** When implementing work tracked by a GitHub issue, comment on the issue with what landed and close it. Do both — a comment without a close leaves stale issues open; a close without a comment leaves no record of what shipped. The comment is for future readers — state the concrete changes, not the conversation that produced them.
32
+
33
+ ---
34
+
35
+ ## Patterns
36
+
37
+ All five tools are read-only, `openWorldHint: false` (no live network), and declare typed error contracts. Definitions live in `src/mcp-server/tools/definitions/`; the shared registration record schema + `format()` live in `_schemas.ts` (reused by the lookup tool and the resource).
38
+
39
+ ### Tool
40
+
41
+ ```ts
42
+ import { tool, z } from '@cyanheads/mcp-ts-core';
43
+ import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
44
+ import { getRegistryService } from '@/services/registry/registry-service.js';
45
+ import { formatRegistrationRecord, registrationRecordSchema } from './_schemas.js';
46
+
47
+ export const lookupRegistrationTool = tool('faa_lookup_registration', {
48
+ title: 'faa-aircraft-registry-mcp-server: lookup registration',
49
+ description: 'Decode one US civil aircraft N-number to its full registration record …',
50
+ annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
51
+
52
+ input: z.object({
53
+ nNumber: z.string().min(1).describe('N-number to decode. Accepts "N12345" or "12345".'),
54
+ }),
55
+ output: registrationRecordSchema,
56
+
57
+ errors: [
58
+ {
59
+ reason: 'not_found',
60
+ code: JsonRpcErrorCode.NotFound,
61
+ when: 'The N-number is well-formed but has no active registration in the MASTER file.',
62
+ recovery: 'Call faa_get_registration_status to check deregistered/reserved, or faa_search_registrations.',
63
+ },
64
+ ],
65
+
66
+ async handler(input, ctx) {
67
+ const record = await getRegistryService().lookupRegistration(input.nNumber, ctx);
68
+ if (!record) {
69
+ throw ctx.fail('not_found', `No active registration for N-number "${input.nNumber}".`, {
70
+ ...ctx.recoveryFor('not_found'),
71
+ });
72
+ }
73
+ return record;
74
+ },
75
+
76
+ // format() populates content[] — the markdown twin of structuredContent.
77
+ // Both surfaces must carry the same data; the linter enforces format-parity.
78
+ format: (result) => [{ type: 'text', text: formatRegistrationRecord(result) }],
79
+ });
80
+ ```
81
+
82
+ Coded fields surface BOTH the raw FAA code and the decoded label (`{ code, label? }` via `codedValueSchema`); permissible fields the FAA leaves blank are optional and rendered as absent, never fabricated.
83
+
84
+ ### Resource
85
+
86
+ ```ts
87
+ import { resource, z } from '@cyanheads/mcp-ts-core';
88
+ import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
89
+ import { registrationRecordSchema } from '@/mcp-server/tools/definitions/_schemas.js';
90
+ import { getRegistryService } from '@/services/registry/registry-service.js';
91
+
92
+ export const registrationResource = resource('faa://registration/{nNumber}', {
93
+ name: 'faa-registration',
94
+ title: 'faa-aircraft-registry-mcp-server: registration record',
95
+ description: 'Full registration record for one N-number — same payload as faa_lookup_registration.',
96
+ mimeType: 'application/json',
97
+ params: z.object({
98
+ nNumber: z.string().min(1).describe('N-number. Accepts "N12345" or "12345".'),
99
+ }),
100
+ output: registrationRecordSchema,
101
+
102
+ errors: [
103
+ {
104
+ reason: 'not_found',
105
+ code: JsonRpcErrorCode.NotFound,
106
+ when: 'The N-number is well-formed but has no active registration.',
107
+ recovery: 'Use faa_get_registration_status for deregistered/reserved, or faa_search_registrations.',
108
+ },
109
+ ],
110
+
111
+ async handler(params, ctx) {
112
+ const record = await getRegistryService().lookupRegistration(params.nNumber, ctx);
113
+ if (!record) {
114
+ throw ctx.fail('not_found', `No active registration for N-number "${params.nNumber}".`, {
115
+ ...ctx.recoveryFor('not_found'),
116
+ });
117
+ }
118
+ return record;
119
+ },
120
+ });
121
+ ```
122
+
123
+ This server has no prompts — it is a pure lookup/search/decode surface with no recurring multi-step interaction worth templating.
124
+
125
+ ### Server config
126
+
127
+ ```ts
128
+ // src/config/server-config.ts — lazy-parsed, separate from framework config
129
+ import { z } from '@cyanheads/mcp-ts-core';
130
+ import { parseEnvConfig } from '@cyanheads/mcp-ts-core/config';
131
+
132
+ const ServerConfigSchema = z.object({
133
+ // Fail-safe: unset/empty/malformed coerces to 'true' (redacted) before stringbool sees it,
134
+ // so only an explicit, well-formed false/0/no/off turns redaction off.
135
+ redactOwnerPii: z
136
+ .preprocess(redactToSafeDefault, z.stringbool())
137
+ .describe('Fail-safe owner-PII redaction. Redacted unless explicitly set to a falsy value.'),
138
+ mirrorPath: z.string().min(1).default('.mirror/faa-registry.db')
139
+ .describe('Filesystem path to the SQLite registry index.'),
140
+ databaseUrl: z.string().url().default('https://registry.faa.gov/database/ReleasableAircraft.zip')
141
+ .describe('Source URL for the FAA ZIP (ingest-time only).'),
142
+ });
143
+
144
+ let _config: z.infer<typeof ServerConfigSchema> | undefined;
145
+ export function getServerConfig() {
146
+ _config ??= parseEnvConfig(ServerConfigSchema, {
147
+ redactOwnerPii: 'FAA_REDACT_OWNER_PII',
148
+ mirrorPath: 'FAA_MIRROR_PATH',
149
+ databaseUrl: 'FAA_DATABASE_URL',
150
+ });
151
+ return _config;
152
+ }
153
+ ```
154
+
155
+ `parseEnvConfig` maps Zod schema paths → env var names so errors name the variable (`FAA_REDACT_OWNER_PII`) not the path (`redactOwnerPii`). Throws `ConfigurationError`, which the framework prints as a clean startup banner. The redaction flag is a privacy control: it must fail safe (default redacted) rather than throw or expose on a malformed value — hence the `preprocess` shim instead of a bare `.default()`.
156
+
157
+ For env booleans use `z.stringbool()`, never `z.coerce.boolean()` — `Boolean("false")` is `true`, so a coerced flag can't be disabled through the environment. `z.stringbool()` parses `true/false/1/0/yes/no/on/off` and rejects anything else, so `=false` actually disables.
158
+
159
+ ### Server identity and instructions
160
+
161
+ `createApp()` accepts optional identity fields forwarded to the SDK's `initialize` response and the server manifest (`/.well-known/mcp.json`):
162
+
163
+ ```ts
164
+ await createApp({
165
+ name: 'faa-aircraft-registry-mcp-server', // machine name on every surface — never Title Case
166
+ title: 'faa-aircraft-registry-mcp-server', // display identity = the hyphenated repo name
167
+ websiteUrl: 'https://github.com/cyanheads/faa-aircraft-registry-mcp-server',
168
+ tools: allToolDefinitions,
169
+ resources: allResourceDefinitions,
170
+ instructions: 'Offline, keyless lookup of the US civil aircraft registry … The index must be built once via the mirror:init script before queries succeed.',
171
+ setup(core) {
172
+ initRegistryService({ /* redactOwnerPii, mirrorPath, databaseUrl */ });
173
+ if (core.config.mcpTransportType === 'http') void scheduleDailyRefresh(); // daily mirror:refresh
174
+ },
175
+ });
176
+ ```
177
+
178
+ `name` and `title` are both the hyphenated machine name on every surface — never a Title Case display name; `description` is NOT passed here (it derives from `package.json`, the canonical source). `instructions` is session-level orientation sent on every `initialize` — here it notes the offline/keyless nature, the redaction default, and the `mirror:init` precondition. Daily refresh is scheduled only under HTTP transport (a long-lived process owns the cron); stdio operators run `mirror:refresh` out-of-band.
179
+
180
+ ---
181
+
182
+ ## Context
183
+
184
+ Handlers receive a unified `ctx` object. Key properties:
185
+
186
+ | Property | Description |
187
+ |:---------|:------------|
188
+ | `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. |
189
+ | `ctx.fail` / `ctx.recoveryFor` | Throw a typed contract error by `reason` (`ctx.fail`); pull the declared `recovery` metadata for the throw site (`ctx.recoveryFor`). Used by every tool/resource. |
190
+ | `ctx.enrich` | Out-of-band response enrichment — `.truncated({ shown, cap })` when a search hits its limit, `.notice(msg)` when no rows match. Used by the search tools. |
191
+ | `ctx.signal` | `AbortSignal` for cancellation — threaded into the mirror sync run. |
192
+ | `ctx.requestId` | Unique request ID. |
193
+
194
+ This server is read-only over the local mirror: no `ctx.state` (the index is the store, accessed via `registry-service`), no `ctx.elicit` (no interactive input), no `ctx.progress` (no task-mode tools).
195
+
196
+ ---
197
+
198
+ ## Errors
199
+
200
+ Handlers throw — the framework catches, classifies, and formats.
201
+
202
+ **Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required descriptive metadata for the agent's next move (≥ 5 words, lint-validated); for the wire `data.recovery.hint` (mirrored into `content[]` text), pass explicitly at the throw site when dynamic context matters: `ctx.fail('reason', msg, { recovery: { hint: '...' } })`. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring.
203
+
204
+ ```ts
205
+ import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
206
+
207
+ errors: [
208
+ { reason: 'not_found', code: JsonRpcErrorCode.NotFound,
209
+ when: 'The N-number is well-formed but has no active registration in the MASTER file.',
210
+ recovery: 'Call faa_get_registration_status to check deregistered/reserved, or faa_search_registrations.' },
211
+ ],
212
+ async handler(input, ctx) {
213
+ const record = await getRegistryService().lookupRegistration(input.nNumber, ctx);
214
+ if (!record) throw ctx.fail('not_found', `No active registration for "${input.nNumber}".`, { ...ctx.recoveryFor('not_found') });
215
+ return record;
216
+ }
217
+ ```
218
+
219
+ The cold-mirror case (a never-initialized index) is a service-layer `ServiceUnavailable` raised in `registry-service`, common to every tool — its recovery hint points to `mirror:init`. There is no live API fallback, so it surfaces loudly rather than returning an empty result.
220
+
221
+ **Declare contracts inline on each tool.** The contract is part of the tool's public surface — one file should give the full picture. Don't extract a shared `errors[]` constant; per-tool repetition is the intended cost of locality.
222
+
223
+ **Fallback (no contract entry fits):** throw via factories or plain `Error`.
224
+
225
+ ```ts
226
+ // Error factories — explicit code
227
+ import { notFound, serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
228
+ throw notFound('Item not found', { itemId });
229
+ throw serviceUnavailable('API unavailable', { url }, { cause: err });
230
+
231
+ // Plain Error — framework auto-classifies from message patterns
232
+ throw new Error('Item not found'); // → NotFound
233
+ throw new Error('Invalid query format'); // → ValidationError
234
+
235
+ // McpError — when no factory exists for the code
236
+ import { McpError, JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
237
+ throw new McpError(JsonRpcErrorCode.DatabaseError, 'Connection failed', { pool: 'primary' });
238
+ ```
239
+
240
+ See framework CLAUDE.md and the `api-errors` skill for the full auto-classification table, all available factories, and the contract reference.
241
+
242
+ ---
243
+
244
+ ## Structure
245
+
246
+ ```text
247
+ src/
248
+ index.ts # createApp() entry; inits registry service, schedules daily refresh (HTTP)
249
+ config/
250
+ server-config.ts # FAA_REDACT_OWNER_PII / FAA_MIRROR_PATH / FAA_DATABASE_URL (Zod schema)
251
+ services/
252
+ registry/
253
+ registry-service.ts # MirrorService instance; query/join/decode + the PII redaction gate
254
+ ingest.ts # sync ingester: download ZIP → parse MASTER-1..9 + ACFTREF/ENGINE/DEREG/RESERVED → pre-join
255
+ zip.ts csv.ts # ZIP extraction + comma-delimited parsing
256
+ decode.ts # static decode maps (status, type, region, category, …) applied at query time
257
+ normalize.ts # N-number normalizer (strip leading N, uppercase)
258
+ schema.ts # sqliteMirrorStore column + FTS5 + index spec
259
+ types.ts # domain types
260
+ mcp-server/
261
+ tools/definitions/
262
+ _schemas.ts # shared registration-record schema + format() (lookup tool + resource)
263
+ lookup-registration.tool.ts # the 80% tool
264
+ get-registration-status.tool.ts # cross-file status resolver (active/deregistered/reserved/unknown)
265
+ search-registrations.tool.ts # FTS5 search of active registrations
266
+ search-aircraft-types.tool.ts # FTS5 search of the aircraft reference table
267
+ get-aircraft-type.tool.ts # decode a 7-char mfr/model/series code
268
+ resources/definitions/
269
+ registration.resource.ts # faa://registration/{nNumber} (reuses the lookup handler)
270
+ scripts/
271
+ faa-mirror-init.ts # mirror:init — full out-of-band build
272
+ faa-mirror-refresh.ts # mirror:refresh — incremental/full rebuild
273
+ faa-mirror-verify.ts # mirror:verify — readiness + integrity check
274
+ _mirror-context.ts # shared mirror-instance shim for the three CLI scripts
275
+ ```
276
+
277
+ ---
278
+
279
+ ## Naming
280
+
281
+ | What | Convention | Example |
282
+ |:-----|:-----------|:--------|
283
+ | Files | kebab-case with suffix | `search-docs.tool.ts` |
284
+ | Tool/resource/prompt names | snake_case | `search_docs` |
285
+ | Directories | kebab-case | `src/services/doc-search/` |
286
+ | Descriptions | Single string or template literal, no `+` concatenation | `'Search items by query and filter.'` |
287
+
288
+ ---
289
+
290
+ ## Skills
291
+
292
+ Skills are modular instructions in `skills/` at the project root. Read them directly when a task matches — e.g., `skills/add-tool/SKILL.md` when adding a tool.
293
+
294
+ **Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
295
+
296
+ Available skills:
297
+
298
+ | Skill | Purpose |
299
+ |:------|:--------|
300
+ | `setup` | Post-init project orientation |
301
+ | `design-mcp-server` | Design tool surface, resources, and services for a new server |
302
+ | `add-tool` | Scaffold a new tool definition |
303
+ | `add-app-tool` | Scaffold an MCP App tool + paired UI resource |
304
+ | `add-resource` | Scaffold a new resource definition |
305
+ | `add-prompt` | Scaffold a new prompt definition |
306
+ | `add-service` | Scaffold a new service integration |
307
+ | `add-test` | Scaffold test file for a tool, resource, or service |
308
+ | `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
309
+ | `tool-defs-analysis` | Read-only audit of MCP definition language across the surface — voice, leaks, defaults, recovery hints, output descriptions |
310
+ | `security-pass` | Audit server for MCP-flavored security gaps: output injection, scope blast radius, input sinks, tenant isolation |
311
+ | `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase |
312
+ | `devcheck` | Lint, format, typecheck, audit |
313
+ | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
314
+ | `git-wrapup` | Land working-tree changes as a versioned commit + annotated tag — version bump, changelog, verify, tag. Local only. |
315
+ | `release-and-publish` | Push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
316
+ | `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
317
+ | `orchestrations` | Chain task skills into a gated multi-phase pipeline — build-out, QA-fix, update-ship — when you can spawn sub-agents |
318
+ | `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
319
+ | `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
320
+ | `api-auth` | Auth modes, scopes, JWT/OAuth |
321
+ | `api-canvas` | DataCanvas: register tabular data, run SQL, export, plus the `spillover()` helper for big result sets — Tier 3 opt-in |
322
+ | `api-config` | AppConfig, parseConfig, env vars |
323
+ | `api-context` | Context interface, logger, state, progress |
324
+ | `api-errors` | McpError, JsonRpcErrorCode, error patterns |
325
+ | `api-linter` | Definition linter rule catalog — invoked by `bun run lint:mcp` and `devcheck` |
326
+ | `api-mirror` | MirrorService reference — the embedded SQLite + FTS5 mirror this server is built on (ingester, sync state, scheduling). Read before touching `registry-service` or the ingest path. |
327
+ | `api-services` | LLM, Speech, Graph services |
328
+ | `api-testing` | createMockContext, test patterns |
329
+ | `api-utils` | Formatting, parsing, security, pagination, scheduling, telemetry helpers |
330
+ | `api-telemetry` | OTel catalog: spans, metrics, completion logs, env config, cardinality rules |
331
+ | `api-workers` | Cloudflare Workers runtime |
332
+
333
+ **Chaining skills into pipelines.** When the user wants a multi-phase effort — build this server out, QA-and-fix the surface, update-and-ship — *and you can spawn sub-agents*, `skills/orchestrations/SKILL.md` sequences the task skills above into a gated pipeline with verification at each step. Read it to drive the run. Optional: skip it if you can't orchestrate sub-agents, and ignore it entirely if you were *spawned* as one — you've already been scoped to a single phase.
334
+
335
+ When you complete a skill's checklist, check the boxes and add a completion timestamp at the end (e.g., `Completed: 2026-03-11`).
336
+
337
+ ---
338
+
339
+ ## Commands
340
+
341
+ **Runtime:** Scripts use Bun's native TypeScript execution — `bun run <cmd>` is the standard invocation. `npm run <cmd>` also works (npm delegates to bun).
342
+
343
+ | Command | Purpose |
344
+ |:--------|:--------|
345
+ | `npm run build` | Compile TypeScript |
346
+ | `npm run rebuild` | Clean + build |
347
+ | `npm run clean` | Remove build artifacts |
348
+ | `npm run devcheck` | Lint + format + typecheck + security + changelog sync |
349
+ | `bun run audit:refresh` | Delete `bun.lock`, reinstall, and re-run `bun audit`. Use when `devcheck` flags a transitive advisory — Bun's `update` is sticky on transitive resolutions, so the advisory may be a stale-lockfile false positive. If it survives the refresh, it's real. |
350
+ | `npm run tree` | Generate directory structure doc |
351
+ | `npm run format` | Auto-fix formatting (safe fixes only) |
352
+ | `npm run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
353
+ | `npm test` | Run tests |
354
+ | `bun run mirror:init` | Build the SQLite registry index from the FAA ZIP — full out-of-band build. Run once before first use; idempotent and resumable. Never on server startup. |
355
+ | `bun run mirror:refresh` | Rebuild the index from the latest FAA release. The HTTP server schedules this daily; stdio operators run it out-of-band. |
356
+ | `bun run mirror:verify` | Report index health — readiness, sync status, record count, SQLite integrity check. Exits non-zero when not ready or integrity fails. |
357
+ | `npm run start:stdio` | Production mode (stdio) |
358
+ | `npm run start:http` | Production mode (HTTP) |
359
+ | `npm run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
360
+ | `npm run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
361
+ | `npm run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install |
362
+
363
+ ---
364
+
365
+ ## Bundling
366
+
367
+ `npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips dependency-shipped agent docs (`node_modules/**` `skills/`, `.claude/`, `.agents/`, `SKILL.md`) that root-anchored `.mcpbignore` patterns cannot reach. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
368
+
369
+ **Adding an env var requires both files:** `server.json` (registry discovery, `environmentVariables[]`) and `manifest.json` (bundle install UX, `mcp_config.env` + `user_config`). `lint:packaging` (run by `devcheck`) verifies the env var names match.
370
+
371
+ **README install badges** (Claude Desktop `.mcpb`, Cursor, VS Code) and the `base64` / `encodeURIComponent` config-generation commands are ship-time concerns — run the `polish-docs-meta` skill, which carries the badge format, layout, and generation snippets in `skills/polish-docs-meta/references/readme.md`.
372
+
373
+ ---
374
+
375
+ ## Changelog
376
+
377
+ Directory-based, grouped by minor series via the `.x` semver-wildcard convention. Source of truth: `changelog/<major.minor>.x/<version>.md` (e.g. `changelog/0.1.x/0.1.0.md`) — one file per release, shipped in the npm package. At release, author the per-version file with a concrete version and date, then run `npm run changelog:build` to regenerate the rollup. `changelog/template.md` is a **pristine format reference** — never edited or moved; read it for the frontmatter + section layout when scaffolding. `CHANGELOG.md` is a **navigation index** (header + link + summary per version), regenerated by `npm run changelog:build` — devcheck hard-fails on drift; never hand-edit it.
378
+
379
+ Each per-version file opens with YAML frontmatter:
380
+
381
+ ```markdown
382
+ ---
383
+ summary: "One-line headline, ≤350 chars" # required — powers the rollup index
384
+ breaking: false # optional — true flags breaking changes
385
+ security: false # optional — true flags security fixes
386
+ ---
387
+
388
+ # 0.1.0 — YYYY-MM-DD
389
+ ...
390
+ ```
391
+
392
+ `breaking: true` renders a `· ⚠️ Breaking` badge — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames). `security: true` renders a `· 🛡️ Security` badge and pairs with a `## Security` body section. When both are set, badges render `· ⚠️ Breaking · 🛡️ Security`.
393
+
394
+ `agent-notes` is an optional free-form field for maintenance agents processing the release downstream. Content here won't appear in the rendered CHANGELOG — it's consumed by agents running the `maintenance` skill. Use it for adoption instructions that don't fit the human-facing sections: new files to create, fields to populate, one-time migration steps. Omit entirely when there's nothing to say.
395
+
396
+ **Section order** (Keep a Changelog): Added, Changed, Deprecated, Removed, Fixed, Security. Include only sections with entries — don't ship empty headers.
397
+
398
+ **Tag annotations** render as GitHub Release bodies via `--notes-from-tag`. They must be structured markdown — never a flat comma-separated string. Subject omits the version number (GitHub prepends it). See `changelog/template.md` for the full format reference.
399
+
400
+ ---
401
+
402
+ ## Imports
403
+
404
+ ```ts
405
+ // Framework — z is re-exported, no separate zod import needed
406
+ import { tool, z } from '@cyanheads/mcp-ts-core';
407
+ import { McpError, JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
408
+ import { defineMirror, sqliteMirrorStore } from '@cyanheads/mcp-ts-core/mirror';
409
+
410
+ // Server's own code — via path alias
411
+ import { getRegistryService } from '@/services/registry/registry-service.js';
412
+ ```
413
+
414
+ ---
415
+
416
+ ## Checklist
417
+
418
+ - [ ] Zod schemas: all fields have `.describe()`, only JSON-Schema-serializable types (no `z.custom()`, `z.date()`, `z.transform()`, `z.bigint()`, `z.symbol()`, `z.void()`, `z.map()`, `z.set()`, `z.function()`, `z.nan()`)
419
+ - [ ] 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`.
420
+ - [ ] JSDoc `@fileoverview` + `@module` on every file
421
+ - [ ] `ctx.log` for logging; data access goes through `registry-service` (the mirror), never persistence directly
422
+ - [ ] Owner-PII redaction holds: PII fields dropped AND owner-name search disabled when redacted; the gate is the single chokepoint in `registry-service`
423
+ - [ ] Handlers throw on failure — error factories or plain `Error`, no try/catch
424
+ - [ ] `format()` renders all data the LLM needs — different clients forward different surfaces (Claude Code → `structuredContent`, Claude Desktop → `content[]`); both must carry the same data
425
+ - [ ] If wrapping external API: raw/domain/output schemas reviewed against real upstream sparsity/nullability before finalizing required vs optional fields
426
+ - [ ] If wrapping external API: normalization and `format()` preserve uncertainty; do not fabricate facts from missing upstream data
427
+ - [ ] If wrapping external API: tests include at least one sparse payload case with omitted upstream fields
428
+ - [ ] Registered in `createApp()` arrays (directly or via barrel exports)
429
+ - [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
430
+ - [ ] `.codex-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; `interface.displayName` = package name; `interface.shortDescription` from `package.json` description
431
+ - [ ] `.codex-plugin/mcp.json` updated — server name key matches `package.json` name; env vars added for any required API keys
432
+ - [ ] `.claude-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; inline `mcpServers` entry with server name key, env vars for any required API keys
433
+ - [ ] `npm run devcheck` passes
package/Dockerfile ADDED
@@ -0,0 +1,121 @@
1
+ # ==============================================================================
2
+ # Build Stage
3
+ #
4
+ # This stage installs all dependencies (including dev), builds the TypeScript
5
+ # source code into JavaScript, and prepares the production assets.
6
+ # ==============================================================================
7
+ FROM oven/bun:1.3 AS build
8
+
9
+ WORKDIR /usr/src/app
10
+
11
+ # Copy dependency manifests for optimized layer caching
12
+ COPY package.json bun.lock ./
13
+
14
+ # Install all dependencies (including dev dependencies for building)
15
+ RUN bun install --frozen-lockfile
16
+
17
+ # Copy the rest of the source code
18
+ COPY . .
19
+
20
+ # Build the application
21
+ RUN bun run build
22
+
23
+
24
+ # ==============================================================================
25
+ # Production Stage
26
+ #
27
+ # This stage creates a minimal, optimized, and secure image for running the
28
+ # application. It uses a slim base image and only includes production
29
+ # dependencies and build artifacts.
30
+ # ==============================================================================
31
+ FROM oven/bun:1.3-slim AS production
32
+
33
+ WORKDIR /usr/src/app
34
+
35
+ # Set the environment to production for performance and to ensure only
36
+ # production dependencies are installed.
37
+ ENV NODE_ENV=production
38
+
39
+ # OCI image metadata (https://github.com/opencontainers/image-spec/blob/main/annotations.md)
40
+ ARG APP_VERSION
41
+ LABEL org.opencontainers.image.title="faa-aircraft-registry-mcp-server"
42
+ LABEL org.opencontainers.image.description="Offline, keyless MCP server for the US civil aircraft registry (FAA Releasable Aircraft Database) — decode an N-number to aircraft, engine, status, and owner; search by owner, type, or state."
43
+ LABEL org.opencontainers.image.licenses="Apache-2.0"
44
+ LABEL org.opencontainers.image.version="${APP_VERSION}"
45
+ LABEL org.opencontainers.image.source="https://github.com/cyanheads/faa-aircraft-registry-mcp-server"
46
+
47
+ # Copy dependency manifests
48
+ COPY package.json bun.lock ./
49
+
50
+ # Install only production dependencies, ignoring any lifecycle scripts (like 'prepare')
51
+ # that are not needed in the final production image.
52
+ RUN bun install --production --frozen-lockfile --ignore-scripts
53
+
54
+ # Conditionally install OpenTelemetry optional peer dependencies (Tier 3).
55
+ # These are not bundled by default to keep the base image lean. Enable at build time
56
+ # with: docker build --build-arg OTEL_ENABLED=true
57
+ ARG OTEL_ENABLED=true
58
+ RUN if [ "$OTEL_ENABLED" = "true" ]; then \
59
+ bun add @hono/otel \
60
+ @opentelemetry/instrumentation-http \
61
+ @opentelemetry/exporter-metrics-otlp-http \
62
+ @opentelemetry/exporter-trace-otlp-http \
63
+ @opentelemetry/instrumentation-pino \
64
+ @opentelemetry/resources \
65
+ @opentelemetry/sdk-metrics \
66
+ @opentelemetry/sdk-node \
67
+ @opentelemetry/sdk-trace-node \
68
+ @opentelemetry/semantic-conventions; \
69
+ fi
70
+
71
+ # Copy the compiled application code from the build stage
72
+ COPY --from=build /usr/src/app/dist ./dist
73
+
74
+ # Mirror CLI (MirrorService — Tier 3). Copy the lifecycle scripts and the shared
75
+ # context shim they import, then emit a runtime tsconfig so Bun resolves the @/
76
+ # path alias against ./dist/ rather than the source ./src/ (which never reaches
77
+ # the runtime image). Same `bun run mirror:*` commands work in dev and the image.
78
+ # See the api-mirror skill for the full recipe.
79
+ COPY --from=build /usr/src/app/scripts/faa-mirror-init.ts \
80
+ /usr/src/app/scripts/faa-mirror-refresh.ts \
81
+ /usr/src/app/scripts/faa-mirror-verify.ts \
82
+ /usr/src/app/scripts/_mirror-context.ts \
83
+ ./scripts/
84
+ RUN echo '{"compilerOptions":{"baseUrl":".","paths":{"@/*":["./dist/*"]}}}' > tsconfig.json
85
+
86
+ # The 'oven/bun' image already provides a non-root user named 'bun'.
87
+ # We will use this existing user for enhanced security.
88
+
89
+ # Create and set permissions for the log directory, assigning ownership to the 'bun' user.
90
+ RUN mkdir -p /var/log/faa-aircraft-registry-mcp-server && chown -R bun:bun /var/log/faa-aircraft-registry-mcp-server
91
+
92
+ # Writable data dir for the on-disk SQLite registry index (FAA mirror), owned by
93
+ # the runtime user. Mount a volume over .mirror in production to persist the index.
94
+ RUN mkdir -p /usr/src/app/.cache /usr/src/app/.mirror \
95
+ && chown -R bun:bun /usr/src/app/.cache /usr/src/app/.mirror
96
+
97
+ # Switch to the non-root user
98
+ USER bun
99
+
100
+ # Define an argument for the port, allowing it to be overridden at build time.
101
+ # The `PORT` variable is often injected by cloud environments at runtime.
102
+ ARG PORT
103
+
104
+ # Set runtime environment variables
105
+ # Note: PORT is an automatic variable in many cloud environments (e.g., Cloud Run)
106
+ ENV MCP_HTTP_PORT=${PORT:-3010}
107
+ ENV MCP_HTTP_HOST="0.0.0.0"
108
+ ENV MCP_TRANSPORT_TYPE="http"
109
+ ENV MCP_SESSION_MODE="stateless"
110
+ ENV MCP_LOG_LEVEL="info"
111
+ ENV LOGS_DIR="/var/log/faa-aircraft-registry-mcp-server"
112
+ ENV MCP_FORCE_CONSOLE_LOGGING="true"
113
+
114
+ # Expose the port the server listens on
115
+ EXPOSE ${MCP_HTTP_PORT}
116
+
117
+ # Health check using a bun-native fetch (slim image ships no curl/wget)
118
+ HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 CMD bun -e "fetch('http://localhost:'+(process.env.MCP_HTTP_PORT??'3010')+'/healthz').then((r)=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
119
+
120
+ # The command to start the server
121
+ CMD ["bun", "run", "dist/index.js"]