@cyanheads/faa-aircraft-registry-mcp-server 0.1.7 → 0.1.8
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 +34 -28
- package/CLAUDE.md +34 -28
- package/Dockerfile +8 -6
- package/README.md +5 -3
- package/changelog/0.1.x/0.1.8.md +33 -0
- package/changelog/template.md +55 -16
- package/dist/index.d.ts +2 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2 -2
- package/dist/index.js.map +1 -1
- package/dist/mcp-server/resources/definitions/index.d.ts +2 -2
- package/dist/mcp-server/resources/definitions/registration.resource.d.ts +2 -2
- package/dist/mcp-server/resources/definitions/registration.resource.d.ts.map +1 -1
- package/dist/mcp-server/resources/definitions/registration.resource.js +4 -3
- package/dist/mcp-server/resources/definitions/registration.resource.js.map +1 -1
- package/dist/mcp-server/tools/definitions/_schemas.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/_schemas.js +6 -18
- package/dist/mcp-server/tools/definitions/_schemas.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-aircraft-type.tool.d.ts +2 -2
- package/dist/mcp-server/tools/definitions/get-aircraft-type.tool.js +3 -3
- 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 +3 -3
- 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 +3 -3
- package/dist/mcp-server/tools/definitions/get-registration-status.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/index.d.ts +74 -74
- package/dist/mcp-server/tools/definitions/lookup-registration.tool.d.ts +2 -2
- package/dist/mcp-server/tools/definitions/lookup-registration.tool.js +3 -3
- 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 +1 -1
- package/dist/mcp-server/tools/definitions/search-aircraft-types.tool.js +2 -2
- 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 +2 -2
- package/dist/mcp-server/tools/definitions/search-registrations.tool.js +3 -3
- package/dist/mcp-server/tools/definitions/search-registrations.tool.js.map +1 -1
- package/dist/services/registry/decode.d.ts.map +1 -1
- package/dist/services/registry/registry-service.d.ts.map +1 -1
- package/dist/services/registry/registry-service.js +3 -3
- package/dist/services/registry/registry-service.js.map +1 -1
- package/dist/services/registry/schema.d.ts +3 -3
- package/dist/services/registry/schema.d.ts.map +1 -1
- package/package.json +12 -12
- package/server.json +3 -3
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.
|
|
4
|
+
**Version:** 0.1.8
|
|
5
|
+
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.12.3`
|
|
6
6
|
**Engines:** Bun ≥1.3.0, Node ≥24.0.0
|
|
7
|
-
**MCP SDK:** `@modelcontextprotocol/
|
|
7
|
+
**MCP SDK:** `@modelcontextprotocol/server` ^2.0.0 (protocol revisions 2026-07-28 and 2025-*)
|
|
8
8
|
**Zod:** ^4.4.3
|
|
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.
|
|
@@ -26,7 +26,7 @@ An offline lookup server for the US civil aircraft registry. It indexes the FAA'
|
|
|
26
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
27
|
- **Use `ctx.log`** for request-scoped logging. No `console` calls.
|
|
28
28
|
- **Use `ctx.state`** for tenant-scoped storage. Never access persistence directly.
|
|
29
|
-
- **
|
|
29
|
+
- **Need input the caller didn't supply?** `return ctx.requestInput(...)` and read `ctx.inputs` when the handler is re-entered. Never await input mid-handler.
|
|
30
30
|
- **Secrets in env vars only** — never hardcoded.
|
|
31
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
32
|
|
|
@@ -94,6 +94,7 @@ export const registrationResource = resource('faa://registration/{nNumber}', {
|
|
|
94
94
|
title: 'faa-aircraft-registry-mcp-server: registration record',
|
|
95
95
|
description: 'Full registration record for one N-number — same payload as faa_lookup_registration.',
|
|
96
96
|
mimeType: 'application/json',
|
|
97
|
+
cacheHint: { ttlMs: 3_600_000, cacheScope: 'private' },
|
|
97
98
|
params: z.object({
|
|
98
99
|
nNumber: z.string().min(1).describe('N-number. Accepts "N12345" or "12345".'),
|
|
99
100
|
}),
|
|
@@ -164,7 +165,6 @@ For env booleans use `z.stringbool()`, never `z.coerce.boolean()` — `Boolean("
|
|
|
164
165
|
await createApp({
|
|
165
166
|
name: 'faa-aircraft-registry-mcp-server', // machine name on every surface — never Title Case
|
|
166
167
|
title: 'faa-aircraft-registry-mcp-server', // display identity = the hyphenated repo name
|
|
167
|
-
websiteUrl: 'https://github.com/cyanheads/faa-aircraft-registry-mcp-server',
|
|
168
168
|
tools: allToolDefinitions,
|
|
169
169
|
resources: allResourceDefinitions,
|
|
170
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.',
|
|
@@ -185,13 +185,14 @@ Handlers receive a unified `ctx` object. Key properties:
|
|
|
185
185
|
|
|
186
186
|
| Property | Description |
|
|
187
187
|
|:---------|:------------|
|
|
188
|
-
| `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. |
|
|
188
|
+
| `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. Client-visible through `notifications/message`. |
|
|
189
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` |
|
|
190
|
+
| `ctx.enrich` | Success-path response enrichment — `.truncated({ shown, cap })`, `.notice(msg)`, and `.total(count)`. Reaches both `structuredContent` and `content[]`. |
|
|
191
|
+
| `ctx.content` | Non-text content blocks appended to `content[]`; unused by this text/JSON-only server. |
|
|
191
192
|
| `ctx.signal` | `AbortSignal` for cancellation — threaded into the mirror sync run. |
|
|
192
193
|
| `ctx.requestId` | Unique request ID. |
|
|
193
194
|
|
|
194
|
-
This server is read-only over the local mirror: no `ctx.state` (the index is the store, accessed via `registry-service`), no `ctx.
|
|
195
|
+
This server is read-only over the local mirror and explicitly stateless: no `ctx.state` (the index is the store, accessed via `registry-service`), no `ctx.requestInput`/`ctx.inputs` call sites, and no task surfaces.
|
|
195
196
|
|
|
196
197
|
---
|
|
197
198
|
|
|
@@ -218,6 +219,8 @@ async handler(input, ctx) {
|
|
|
218
219
|
|
|
219
220
|
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
|
|
|
222
|
+
`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`.
|
|
223
|
+
|
|
221
224
|
**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
225
|
|
|
223
226
|
**Fallback (no contract entry fits):** throw via factories or plain `Error`.
|
|
@@ -289,7 +292,7 @@ scripts/
|
|
|
289
292
|
|
|
290
293
|
## Skills
|
|
291
294
|
|
|
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.
|
|
295
|
+
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. `bun run list-skills` prints the full registry.
|
|
293
296
|
|
|
294
297
|
**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
298
|
|
|
@@ -320,7 +323,7 @@ Available skills:
|
|
|
320
323
|
| `api-auth` | Auth modes, scopes, JWT/OAuth |
|
|
321
324
|
| `api-canvas` | DataCanvas: register tabular data, run SQL, export, plus the `spillover()` helper for big result sets — Tier 3 opt-in |
|
|
322
325
|
| `api-config` | AppConfig, parseConfig, env vars |
|
|
323
|
-
| `api-context` | Context interface, logger, state,
|
|
326
|
+
| `api-context` | Context interface, RequestContext, logger, state, multi-round-trip input |
|
|
324
327
|
| `api-errors` | McpError, JsonRpcErrorCode, error patterns |
|
|
325
328
|
| `api-linter` | Definition linter rule catalog — invoked by `bun run lint:mcp` and `devcheck` |
|
|
326
329
|
| `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. |
|
|
@@ -342,29 +345,32 @@ When you complete a skill's checklist, check the boxes and add a completion time
|
|
|
342
345
|
|
|
343
346
|
| Command | Purpose |
|
|
344
347
|
|:--------|:--------|
|
|
345
|
-
| `
|
|
346
|
-
| `
|
|
347
|
-
| `
|
|
348
|
-
| `
|
|
348
|
+
| `bun run build` | Compile TypeScript |
|
|
349
|
+
| `bun run rebuild` | Clean + build |
|
|
350
|
+
| `bun run clean` | Remove build artifacts |
|
|
351
|
+
| `bun run devcheck` | Lint + format + typecheck + security + changelog sync |
|
|
349
352
|
| `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
|
-
| `
|
|
351
|
-
| `
|
|
352
|
-
| `
|
|
353
|
-
| `
|
|
353
|
+
| `bun run lint:mcp` | Run the MCP definition linter standalone |
|
|
354
|
+
| `bun run lint:packaging` | Verify packaging-surface consistency |
|
|
355
|
+
| `bun run list-skills` | Print the skill registry |
|
|
356
|
+
| `bun run tree` | Generate directory structure doc |
|
|
357
|
+
| `bun run format` | Auto-fix formatting (safe fixes only) |
|
|
358
|
+
| `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
|
|
359
|
+
| `bun run test` | Run tests (Vitest — do not use `bun test`) |
|
|
354
360
|
| `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
361
|
| `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
362
|
| `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
|
-
| `
|
|
358
|
-
| `
|
|
359
|
-
| `
|
|
360
|
-
| `
|
|
361
|
-
| `
|
|
363
|
+
| `bun run start:stdio` | Production mode (stdio) |
|
|
364
|
+
| `bun run start:http` | Production mode (HTTP) |
|
|
365
|
+
| `bun run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
|
|
366
|
+
| `bun run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
|
|
367
|
+
| `bun run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install |
|
|
362
368
|
|
|
363
369
|
---
|
|
364
370
|
|
|
365
371
|
## Bundling
|
|
366
372
|
|
|
367
|
-
`
|
|
373
|
+
`bun run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The cleanup step prunes dev dependencies and strips dependency-shipped agent docs plus platform-specific native bindings that root-anchored `.mcpbignore` patterns cannot reach. MCPB is stdio-only — HTTP deployments are unaffected.
|
|
368
374
|
|
|
369
375
|
**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
376
|
|
|
@@ -374,7 +380,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
|
|
|
374
380
|
|
|
375
381
|
## Changelog
|
|
376
382
|
|
|
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 `
|
|
383
|
+
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 `bun 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 `bun run changelog:build` — devcheck hard-fails on drift; never hand-edit it.
|
|
378
384
|
|
|
379
385
|
Each per-version file opens with YAML frontmatter:
|
|
380
386
|
|
|
@@ -382,14 +388,14 @@ Each per-version file opens with YAML frontmatter:
|
|
|
382
388
|
---
|
|
383
389
|
summary: "One-line headline, ≤350 chars" # required — powers the rollup index
|
|
384
390
|
breaking: false # optional — true flags breaking changes
|
|
385
|
-
security: false # optional — true
|
|
391
|
+
security: false # optional — true only for a source-code security fix
|
|
386
392
|
---
|
|
387
393
|
|
|
388
394
|
# 0.1.0 — YYYY-MM-DD
|
|
389
395
|
...
|
|
390
396
|
```
|
|
391
397
|
|
|
392
|
-
`breaking: true` renders a `· ⚠️ Breaking` badge — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames). `security: true`
|
|
398
|
+
`breaking: true` renders a `· ⚠️ Breaking` badge — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames). `security: true` is only for a security fix in this server's own source, never a routine dependency advisory; dependency fixes belong under `## Dependencies`.
|
|
393
399
|
|
|
394
400
|
`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
401
|
|
|
@@ -430,4 +436,4 @@ import { getRegistryService } from '@/services/registry/registry-service.js';
|
|
|
430
436
|
- [ ] `.codex-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; `interface.displayName` = package name; `interface.shortDescription` from `package.json` description
|
|
431
437
|
- [ ] `.codex-plugin/mcp.json` updated — server name key matches `package.json` name; env vars added for any required API keys
|
|
432
438
|
- [ ] `.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
|
-
- [ ] `
|
|
439
|
+
- [ ] `bun run devcheck` passes
|
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.
|
|
4
|
+
**Version:** 0.1.8
|
|
5
|
+
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.12.3`
|
|
6
6
|
**Engines:** Bun ≥1.3.0, Node ≥24.0.0
|
|
7
|
-
**MCP SDK:** `@modelcontextprotocol/
|
|
7
|
+
**MCP SDK:** `@modelcontextprotocol/server` ^2.0.0 (protocol revisions 2026-07-28 and 2025-*)
|
|
8
8
|
**Zod:** ^4.4.3
|
|
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.
|
|
@@ -26,7 +26,7 @@ An offline lookup server for the US civil aircraft registry. It indexes the FAA'
|
|
|
26
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
27
|
- **Use `ctx.log`** for request-scoped logging. No `console` calls.
|
|
28
28
|
- **Use `ctx.state`** for tenant-scoped storage. Never access persistence directly.
|
|
29
|
-
- **
|
|
29
|
+
- **Need input the caller didn't supply?** `return ctx.requestInput(...)` and read `ctx.inputs` when the handler is re-entered. Never await input mid-handler.
|
|
30
30
|
- **Secrets in env vars only** — never hardcoded.
|
|
31
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
32
|
|
|
@@ -94,6 +94,7 @@ export const registrationResource = resource('faa://registration/{nNumber}', {
|
|
|
94
94
|
title: 'faa-aircraft-registry-mcp-server: registration record',
|
|
95
95
|
description: 'Full registration record for one N-number — same payload as faa_lookup_registration.',
|
|
96
96
|
mimeType: 'application/json',
|
|
97
|
+
cacheHint: { ttlMs: 3_600_000, cacheScope: 'private' },
|
|
97
98
|
params: z.object({
|
|
98
99
|
nNumber: z.string().min(1).describe('N-number. Accepts "N12345" or "12345".'),
|
|
99
100
|
}),
|
|
@@ -164,7 +165,6 @@ For env booleans use `z.stringbool()`, never `z.coerce.boolean()` — `Boolean("
|
|
|
164
165
|
await createApp({
|
|
165
166
|
name: 'faa-aircraft-registry-mcp-server', // machine name on every surface — never Title Case
|
|
166
167
|
title: 'faa-aircraft-registry-mcp-server', // display identity = the hyphenated repo name
|
|
167
|
-
websiteUrl: 'https://github.com/cyanheads/faa-aircraft-registry-mcp-server',
|
|
168
168
|
tools: allToolDefinitions,
|
|
169
169
|
resources: allResourceDefinitions,
|
|
170
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.',
|
|
@@ -185,13 +185,14 @@ Handlers receive a unified `ctx` object. Key properties:
|
|
|
185
185
|
|
|
186
186
|
| Property | Description |
|
|
187
187
|
|:---------|:------------|
|
|
188
|
-
| `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. |
|
|
188
|
+
| `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. Client-visible through `notifications/message`. |
|
|
189
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` |
|
|
190
|
+
| `ctx.enrich` | Success-path response enrichment — `.truncated({ shown, cap })`, `.notice(msg)`, and `.total(count)`. Reaches both `structuredContent` and `content[]`. |
|
|
191
|
+
| `ctx.content` | Non-text content blocks appended to `content[]`; unused by this text/JSON-only server. |
|
|
191
192
|
| `ctx.signal` | `AbortSignal` for cancellation — threaded into the mirror sync run. |
|
|
192
193
|
| `ctx.requestId` | Unique request ID. |
|
|
193
194
|
|
|
194
|
-
This server is read-only over the local mirror: no `ctx.state` (the index is the store, accessed via `registry-service`), no `ctx.
|
|
195
|
+
This server is read-only over the local mirror and explicitly stateless: no `ctx.state` (the index is the store, accessed via `registry-service`), no `ctx.requestInput`/`ctx.inputs` call sites, and no task surfaces.
|
|
195
196
|
|
|
196
197
|
---
|
|
197
198
|
|
|
@@ -218,6 +219,8 @@ async handler(input, ctx) {
|
|
|
218
219
|
|
|
219
220
|
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
|
|
|
222
|
+
`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`.
|
|
223
|
+
|
|
221
224
|
**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
225
|
|
|
223
226
|
**Fallback (no contract entry fits):** throw via factories or plain `Error`.
|
|
@@ -289,7 +292,7 @@ scripts/
|
|
|
289
292
|
|
|
290
293
|
## Skills
|
|
291
294
|
|
|
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.
|
|
295
|
+
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. `bun run list-skills` prints the full registry.
|
|
293
296
|
|
|
294
297
|
**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
298
|
|
|
@@ -320,7 +323,7 @@ Available skills:
|
|
|
320
323
|
| `api-auth` | Auth modes, scopes, JWT/OAuth |
|
|
321
324
|
| `api-canvas` | DataCanvas: register tabular data, run SQL, export, plus the `spillover()` helper for big result sets — Tier 3 opt-in |
|
|
322
325
|
| `api-config` | AppConfig, parseConfig, env vars |
|
|
323
|
-
| `api-context` | Context interface, logger, state,
|
|
326
|
+
| `api-context` | Context interface, RequestContext, logger, state, multi-round-trip input |
|
|
324
327
|
| `api-errors` | McpError, JsonRpcErrorCode, error patterns |
|
|
325
328
|
| `api-linter` | Definition linter rule catalog — invoked by `bun run lint:mcp` and `devcheck` |
|
|
326
329
|
| `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. |
|
|
@@ -342,29 +345,32 @@ When you complete a skill's checklist, check the boxes and add a completion time
|
|
|
342
345
|
|
|
343
346
|
| Command | Purpose |
|
|
344
347
|
|:--------|:--------|
|
|
345
|
-
| `
|
|
346
|
-
| `
|
|
347
|
-
| `
|
|
348
|
-
| `
|
|
348
|
+
| `bun run build` | Compile TypeScript |
|
|
349
|
+
| `bun run rebuild` | Clean + build |
|
|
350
|
+
| `bun run clean` | Remove build artifacts |
|
|
351
|
+
| `bun run devcheck` | Lint + format + typecheck + security + changelog sync |
|
|
349
352
|
| `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
|
-
| `
|
|
351
|
-
| `
|
|
352
|
-
| `
|
|
353
|
-
| `
|
|
353
|
+
| `bun run lint:mcp` | Run the MCP definition linter standalone |
|
|
354
|
+
| `bun run lint:packaging` | Verify packaging-surface consistency |
|
|
355
|
+
| `bun run list-skills` | Print the skill registry |
|
|
356
|
+
| `bun run tree` | Generate directory structure doc |
|
|
357
|
+
| `bun run format` | Auto-fix formatting (safe fixes only) |
|
|
358
|
+
| `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
|
|
359
|
+
| `bun run test` | Run tests (Vitest — do not use `bun test`) |
|
|
354
360
|
| `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
361
|
| `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
362
|
| `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
|
-
| `
|
|
358
|
-
| `
|
|
359
|
-
| `
|
|
360
|
-
| `
|
|
361
|
-
| `
|
|
363
|
+
| `bun run start:stdio` | Production mode (stdio) |
|
|
364
|
+
| `bun run start:http` | Production mode (HTTP) |
|
|
365
|
+
| `bun run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
|
|
366
|
+
| `bun run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
|
|
367
|
+
| `bun run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install |
|
|
362
368
|
|
|
363
369
|
---
|
|
364
370
|
|
|
365
371
|
## Bundling
|
|
366
372
|
|
|
367
|
-
`
|
|
373
|
+
`bun run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The cleanup step prunes dev dependencies and strips dependency-shipped agent docs plus platform-specific native bindings that root-anchored `.mcpbignore` patterns cannot reach. MCPB is stdio-only — HTTP deployments are unaffected.
|
|
368
374
|
|
|
369
375
|
**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
376
|
|
|
@@ -374,7 +380,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
|
|
|
374
380
|
|
|
375
381
|
## Changelog
|
|
376
382
|
|
|
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 `
|
|
383
|
+
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 `bun 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 `bun run changelog:build` — devcheck hard-fails on drift; never hand-edit it.
|
|
378
384
|
|
|
379
385
|
Each per-version file opens with YAML frontmatter:
|
|
380
386
|
|
|
@@ -382,14 +388,14 @@ Each per-version file opens with YAML frontmatter:
|
|
|
382
388
|
---
|
|
383
389
|
summary: "One-line headline, ≤350 chars" # required — powers the rollup index
|
|
384
390
|
breaking: false # optional — true flags breaking changes
|
|
385
|
-
security: false # optional — true
|
|
391
|
+
security: false # optional — true only for a source-code security fix
|
|
386
392
|
---
|
|
387
393
|
|
|
388
394
|
# 0.1.0 — YYYY-MM-DD
|
|
389
395
|
...
|
|
390
396
|
```
|
|
391
397
|
|
|
392
|
-
`breaking: true` renders a `· ⚠️ Breaking` badge — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames). `security: true`
|
|
398
|
+
`breaking: true` renders a `· ⚠️ Breaking` badge — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames). `security: true` is only for a security fix in this server's own source, never a routine dependency advisory; dependency fixes belong under `## Dependencies`.
|
|
393
399
|
|
|
394
400
|
`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
401
|
|
|
@@ -430,4 +436,4 @@ import { getRegistryService } from '@/services/registry/registry-service.js';
|
|
|
430
436
|
- [ ] `.codex-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; `interface.displayName` = package name; `interface.shortDescription` from `package.json` description
|
|
431
437
|
- [ ] `.codex-plugin/mcp.json` updated — server name key matches `package.json` name; env vars added for any required API keys
|
|
432
438
|
- [ ] `.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
|
-
- [ ] `
|
|
439
|
+
- [ ] `bun run devcheck` passes
|
package/Dockerfile
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
# This stage installs all dependencies (including dev), builds the TypeScript
|
|
5
5
|
# source code into JavaScript, and prepares the production assets.
|
|
6
6
|
# ==============================================================================
|
|
7
|
-
FROM oven/bun:1.
|
|
7
|
+
FROM --platform=$BUILDPLATFORM oven/bun:1.4.0 AS build
|
|
8
8
|
|
|
9
9
|
WORKDIR /usr/src/app
|
|
10
10
|
|
|
@@ -33,7 +33,7 @@ RUN bun run build
|
|
|
33
33
|
# application. It uses a slim base image and only includes production
|
|
34
34
|
# dependencies and build artifacts.
|
|
35
35
|
# ==============================================================================
|
|
36
|
-
FROM oven/bun:1.
|
|
36
|
+
FROM oven/bun:1.4.0-slim AS production
|
|
37
37
|
|
|
38
38
|
WORKDIR /usr/src/app
|
|
39
39
|
|
|
@@ -52,10 +52,12 @@ LABEL org.opencontainers.image.source="https://github.com/cyanheads/faa-aircraft
|
|
|
52
52
|
# Copy dependency manifests
|
|
53
53
|
COPY package.json bun.lock ./
|
|
54
54
|
|
|
55
|
-
# Install only production dependencies, ignoring any lifecycle scripts (like
|
|
56
|
-
# that are not needed in the final production image.
|
|
55
|
+
# Install only production dependencies, ignoring any lifecycle scripts (like
|
|
56
|
+
# 'prepare') that are not needed in the final production image. `--omit=peer`
|
|
57
|
+
# drops the framework's optional peer tiers; direct runtime dependencies remain.
|
|
58
|
+
# The OTEL step carries the same flag so it does not pull the omitted peers back.
|
|
57
59
|
RUN --mount=type=cache,target=/root/.bun/install/cache \
|
|
58
|
-
bun install --production --frozen-lockfile --ignore-scripts
|
|
60
|
+
bun install --production --omit=peer --frozen-lockfile --ignore-scripts
|
|
59
61
|
|
|
60
62
|
# Conditionally install OpenTelemetry optional peer dependencies (Tier 3).
|
|
61
63
|
# These are not bundled by default to keep the base image lean. Enable at build time
|
|
@@ -63,7 +65,7 @@ RUN --mount=type=cache,target=/root/.bun/install/cache \
|
|
|
63
65
|
ARG OTEL_ENABLED=true
|
|
64
66
|
RUN --mount=type=cache,target=/root/.bun/install/cache \
|
|
65
67
|
if [ "$OTEL_ENABLED" = "true" ]; then \
|
|
66
|
-
bun add @hono/otel \
|
|
68
|
+
bun add --omit=dev --omit=peer --ignore-scripts @hono/otel \
|
|
67
69
|
@opentelemetry/instrumentation-http \
|
|
68
70
|
@opentelemetry/exporter-metrics-otlp-http \
|
|
69
71
|
@opentelemetry/exporter-trace-otlp-http \
|
package/README.md
CHANGED
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
|
|
8
8
|
<div align="center">
|
|
9
9
|
|
|
10
|
-
[](./CHANGELOG.md) [](./LICENSE) [](https://github.com/users/cyanheads/packages/container/package/faa-aircraft-registry-mcp-server) [](https://modelcontextprotocol.io/) [](https://www.npmjs.com/package/@cyanheads/faa-aircraft-registry-mcp-server) [](https://www.typescriptlang.org/) [](https://bun.sh/)
|
|
11
11
|
|
|
12
12
|
</div>
|
|
13
13
|
|
|
@@ -110,6 +110,7 @@ Built on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp
|
|
|
110
110
|
- Swappable storage backends: `in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`
|
|
111
111
|
- Structured logging with optional OpenTelemetry tracing
|
|
112
112
|
- STDIO and Streamable HTTP transports
|
|
113
|
+
- MCP protocol revision 2026-07-28 alongside initialize-negotiated 2025-era clients
|
|
113
114
|
|
|
114
115
|
FAA-registry-specific:
|
|
115
116
|
|
|
@@ -231,7 +232,7 @@ FAA_MIRROR_PATH=/path/to/faa-registry.db bun run mirror:refresh
|
|
|
231
232
|
```
|
|
232
233
|
|
|
233
234
|
- **Keep the path stable.** Point `FAA_MIRROR_PATH` (and the same env var in your MCP client config) at a persistent location so the built index is reused across runs. Default: `.mirror/faa-registry.db`.
|
|
234
|
-
- **Daily refresh.** Under HTTP transport the server schedules a daily `mirror:refresh` aligned to the FAA's nightly re-release (~11:30 PM Central)
|
|
235
|
+
- **Daily refresh.** Under HTTP transport the server schedules a daily `mirror:refresh` aligned to the FAA's nightly re-release (~11:30 PM Central). If an interrupted rebuild leaves the index empty, queries fail loudly with `ServiceUnavailable` until the rebuild succeeds. Under stdio, run `mirror:refresh` out-of-band (e.g. a cron job).
|
|
235
236
|
- **Docker.** The image ships the mirror CLI and a writable `.mirror` data directory owned by the runtime user. Mount a volume there and run `mirror:init` once (e.g. `docker exec <container> bun run mirror:init`, or a one-shot init job against the shared volume) so the index persists across container restarts.
|
|
236
237
|
- **Until the index exists,** every query fails with a `ServiceUnavailable` error whose recovery hint points to `mirror:init` — there is no live API to fall back to, so the cold state surfaces loudly rather than returning empty results.
|
|
237
238
|
|
|
@@ -239,7 +240,7 @@ The source URL is overridable via `FAA_DATABASE_URL` (for a private or cached mi
|
|
|
239
240
|
|
|
240
241
|
### Prerequisites
|
|
241
242
|
|
|
242
|
-
- [Bun v1.
|
|
243
|
+
- [Bun v1.4](https://bun.sh/) or higher (or Node.js v24+). `bun:sqlite` is built into Bun; a Node-only deployment adds `better-sqlite3` (already declared as an optional peer dependency).
|
|
243
244
|
- Disk space for the built index (a few hundred MB) at `FAA_MIRROR_PATH`.
|
|
244
245
|
- Network access at `mirror:init` / `mirror:refresh` time to download the FAA ZIP. Not needed at query time.
|
|
245
246
|
|
|
@@ -279,6 +280,7 @@ bun run mirror:init
|
|
|
279
280
|
| `FAA_MIRROR_PATH` | Filesystem path to the SQLite index file. Point at a persistent path; mount a volume here in production. | `.mirror/faa-registry.db` |
|
|
280
281
|
| `FAA_DATABASE_URL` | Source URL for the FAA Releasable Aircraft Database ZIP, used by `mirror:init` / `mirror:refresh` only. Overridable for a private/cached mirror; never read at request time. | FAA registry ZIP |
|
|
281
282
|
| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |
|
|
283
|
+
| `MCP_SESSION_MODE` | Session mode: `auto` (resolves to stateful), `stateful`, or `stateless`. The included `.env.example` and Docker image explicitly use stateless mode because this server has no multi-round-trip input. | `auto` → `stateful` |
|
|
282
284
|
| `MCP_HTTP_PORT` | Port for the HTTP server. | `3010` |
|
|
283
285
|
| `MCP_HTTP_ENDPOINT_PATH` | HTTP endpoint path where the MCP server is mounted. | `/mcp` |
|
|
284
286
|
| `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
---
|
|
2
|
+
summary: "MCP 2026-07-28 support, strict tool inputs, valid error envelopes, and explicit stateless serving."
|
|
3
|
+
breaking: false
|
|
4
|
+
security: false
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# 0.1.8 — 2026-08-24
|
|
8
|
+
|
|
9
|
+
## Added
|
|
10
|
+
|
|
11
|
+
- **MCP 2026-07-28 support** alongside initialize-negotiated 2025 clients.
|
|
12
|
+
- **Registration resource cache guidance** marking each response private and cacheable for one hour.
|
|
13
|
+
|
|
14
|
+
## Changed
|
|
15
|
+
|
|
16
|
+
- **Tool contracts reject undeclared root inputs** and advertise SDK-valid structured error envelopes.
|
|
17
|
+
- **Domain validation failures** now use `ValidationError` for malformed N-numbers and codes, missing search filters, and disabled search fields; `InvalidParams` remains reserved for malformed request shape.
|
|
18
|
+
- **Session mode is explicitly stateless** across `.env.example`, the Docker image, and the README.
|
|
19
|
+
- **Tool, resource, mirror lifecycle, and packaging descriptions** are shorter and match the implemented behavior.
|
|
20
|
+
- **Build and release maintenance** adopts Bun 1.4, TypeScript 7, test typechecking, tool-contract integration coverage, leaner Docker installs, current packaging scripts and skills, and community health files.
|
|
21
|
+
- **Security reporting guidance** uses `security@caseyjhand.com` and asks reporters to redact credentials.
|
|
22
|
+
|
|
23
|
+
## Dependencies
|
|
24
|
+
|
|
25
|
+
- `@cyanheads/mcp-ts-core` `^0.10.14` → `^0.12.3`
|
|
26
|
+
- `node-cron` `^4.4.1` → `^4.6.0`
|
|
27
|
+
- `better-sqlite3` peer `^12.0.0` → `^13.0.1`; development `^12.11.1` → `^13.0.3`
|
|
28
|
+
- `typescript` `^6.0.3` → `^7.0.2`
|
|
29
|
+
- `@biomejs/biome` `2.5.2` → `2.5.10`
|
|
30
|
+
- `@types/node` `26.1.1` → `26.2.0`
|
|
31
|
+
- `ignore` `^7.0.5` → `^7.0.6`
|
|
32
|
+
- `tsc-alias` `^1.9.1` → `^1.9.2`
|
|
33
|
+
- `vitest` `^4.1.9` → `^4.1.11`
|
package/changelog/template.md
CHANGED
|
@@ -4,10 +4,11 @@
|
|
|
4
4
|
# to author a new release. Set that file's H1 to `# <version> — YYYY-MM-DD`
|
|
5
5
|
# with a concrete date.
|
|
6
6
|
|
|
7
|
-
# Required. One-line GitHub Release-style headline. 350 character cap
|
|
8
|
-
# Default short and scannable. Don't pad, don't stitch
|
|
9
|
-
#
|
|
10
|
-
#
|
|
7
|
+
# Required. One-line GitHub Release-style headline. 350 character cap — a
|
|
8
|
+
# ceiling, not a target. Default short and scannable. Don't pad, don't stitch
|
|
9
|
+
# unrelated changes with commas/semicolons into an inventory — pick the
|
|
10
|
+
# headline, like a tag's theme line. Quotes required: unquoted YAML treats
|
|
11
|
+
# `: ` inside the value as a key separator and fails GitHub's strict parser.
|
|
11
12
|
summary: ""
|
|
12
13
|
|
|
13
14
|
# Set `true` when consumers must change code to upgrade: API removals,
|
|
@@ -24,9 +25,10 @@ security: false
|
|
|
24
25
|
|
|
25
26
|
# Optional free-form notes for maintenance agents processing this release.
|
|
26
27
|
# Not rendered in CHANGELOG — consumed by agents running `maintenance` on
|
|
27
|
-
# downstream servers.
|
|
28
|
-
#
|
|
29
|
-
#
|
|
28
|
+
# downstream servers. ADOPTION STEPS ONLY — new files to create, fields to
|
|
29
|
+
# populate, one-time migration steps. Never a second rendering of the body:
|
|
30
|
+
# if a body bullet already says it, name the bullet's symbol instead of
|
|
31
|
+
# re-explaining. Omit the field entirely when there's nothing to say.
|
|
30
32
|
# agent-notes: |
|
|
31
33
|
# <instructions for downstream maintenance agents>
|
|
32
34
|
---
|
|
@@ -41,17 +43,54 @@ security: false
|
|
|
41
43
|
each bullet with the symbol or concept name in **bold** so they can skip
|
|
42
44
|
what's irrelevant and zoom in on what's not.
|
|
43
45
|
|
|
44
|
-
Tone: terse, fact-dense, not verbose.
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
46
|
+
Tone: terse, fact-dense, not verbose. Bullet shape: **symbol** + what
|
|
47
|
+
changed + at most one consumer-facing caveat. One sentence by default, two
|
|
48
|
+
when the second carries weight — a bullet past ~40 words or three sentences
|
|
49
|
+
is wrong. The depth lives one hop away: the linked issue carries the why,
|
|
50
|
+
the commit diff carries the how. The changelog names what changed and what
|
|
51
|
+
a consumer does about it; a reader who wants mechanism opens the link.
|
|
52
|
+
|
|
53
|
+
Model length on THIS guide, never on the previous entry — entries modeled
|
|
54
|
+
on entries compound.
|
|
55
|
+
|
|
56
|
+
Cut (each has shipped as a wall of text; these are the cruft):
|
|
57
|
+
- History/justification narration — how the bug worked, why the old
|
|
58
|
+
behavior was wrong. One short clause at most; the issue carries the story.
|
|
59
|
+
- Design-rationale defense — "chosen over Y because…", "guarding the
|
|
60
|
+
getter is not enough…". That is the author arguing with a reviewer;
|
|
61
|
+
reviewers read the PR, not the changelog.
|
|
62
|
+
- Defensive unchanged-clauses — "X is unchanged", "byte-identical to
|
|
63
|
+
<prev>". Keep one only where its absence would cause a real misread,
|
|
64
|
+
as a short parenthetical.
|
|
65
|
+
- Edge-case inventories — marker lists, not-flagged lists, escape tables.
|
|
66
|
+
Tests and the issue carry those.
|
|
67
|
+
- Mechanism walkthroughs (JSDoc, CLAUDE.md/AGENTS.md, or the relevant
|
|
68
|
+
skill own those), ceremonial framings ("This release introduces…"),
|
|
69
|
+
backwards-compat paragraphs, file-by-file test enumerations. Prefer
|
|
70
|
+
code/symbol names over English re-explanations.
|
|
71
|
+
|
|
72
|
+
Verified ≠ included: the every-claim-verified-from-the-diff rule bounds
|
|
73
|
+
the TRUTH of what you write, never the AMOUNT.
|
|
74
|
+
|
|
75
|
+
Example — same fact, right size:
|
|
76
|
+
|
|
77
|
+
TOO LONG: **`fetchWithTimeout`'s `timeoutMs` bounds the whole exchange**
|
|
78
|
+
(#341). `fetch` resolves once headers arrive and the deadline was
|
|
79
|
+
cleared as the helper returned, so a peer that answered promptly and
|
|
80
|
+
then stalled the stream held the request open indefinitely. A 2xx
|
|
81
|
+
carrying a body now comes back as a passthrough wrapper that disarms
|
|
82
|
+
the deadline when the body closes, errors, or is cancelled; …
|
|
83
|
+
[+90 more words of mechanism and edge cases]
|
|
84
|
+
|
|
85
|
+
RIGHT: **`fetchWithTimeout`'s `timeoutMs` now bounds the whole
|
|
86
|
+
exchange, not just the headers** (#341). A stalled body aborts with
|
|
87
|
+
the same `Timeout` error; the returned `Response` is a wrapper, so
|
|
88
|
+
identity assertions (`toBe(response)`) no longer hold.
|
|
52
89
|
|
|
53
90
|
Narrative intro: skip by default. Add one short sentence only when the
|
|
54
|
-
release theme genuinely needs framing the bullets can't carry.
|
|
91
|
+
release theme genuinely needs framing the bullets can't carry. When many
|
|
92
|
+
bullets share one upgrade consequence, state it ONCE — intro line or
|
|
93
|
+
agent-notes — never per bullet.
|
|
55
94
|
|
|
56
95
|
Sections: Keep a Changelog order — Added, Changed, Deprecated, Removed,
|
|
57
96
|
Fixed, Security. Include only sections with entries; delete the rest
|
package/dist/index.d.ts
CHANGED
|
@@ -4,7 +4,8 @@
|
|
|
4
4
|
* service (the on-disk FAA SQLite mirror) in setup(), registers the read-only
|
|
5
5
|
* tools and the registration resource, and — under HTTP transport — schedules a
|
|
6
6
|
* daily mirror refresh aligned to the FAA's nightly re-release. The index is
|
|
7
|
-
* never built on startup; mirror:init runs out-of-band (
|
|
7
|
+
* never built on startup; mirror:init runs out-of-band (locally or in a one-shot
|
|
8
|
+
* container against the persistent mirror volume).
|
|
8
9
|
* @module index
|
|
9
10
|
*/
|
|
10
11
|
export {};
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;GAQG"}
|
package/dist/index.js
CHANGED
|
@@ -4,7 +4,8 @@
|
|
|
4
4
|
* service (the on-disk FAA SQLite mirror) in setup(), registers the read-only
|
|
5
5
|
* tools and the registration resource, and — under HTTP transport — schedules a
|
|
6
6
|
* daily mirror refresh aligned to the FAA's nightly re-release. The index is
|
|
7
|
-
* never built on startup; mirror:init runs out-of-band (
|
|
7
|
+
* never built on startup; mirror:init runs out-of-band (locally or in a one-shot
|
|
8
|
+
* container against the persistent mirror volume).
|
|
8
9
|
* @module index
|
|
9
10
|
*/
|
|
10
11
|
import { createApp } from '@cyanheads/mcp-ts-core';
|
|
@@ -24,7 +25,6 @@ const REFRESH_CRON = '0 6 * * *';
|
|
|
24
25
|
await createApp({
|
|
25
26
|
name: 'faa-aircraft-registry-mcp-server',
|
|
26
27
|
title: 'faa-aircraft-registry-mcp-server',
|
|
27
|
-
websiteUrl: 'https://github.com/cyanheads/faa-aircraft-registry-mcp-server',
|
|
28
28
|
tools: allToolDefinitions,
|
|
29
29
|
resources: allResourceDefinitions,
|
|
30
30
|
instructions: 'Offline, keyless lookup of the US civil aircraft registry (the FAA Releasable Aircraft Database, indexed locally as SQLite + FTS5). Decode an N-number with faa_lookup_registration ("N12345" or "12345" both work); resolve active/deregistered/reserved status with faa_get_registration_status; search by owner/make-model/state/type/Mode S with faa_search_registrations; decode and discover manufacturer-model codes with faa_get_aircraft_type and faa_search_aircraft_types. Coded fields surface both the raw FAA code and the decoded label. Owner name and address are REDACTED by default (FAA_REDACT_OWNER_PII); when redacted, owner-name search is disabled and payloads carry ownerRedacted: true. The index must be built once via the mirror:init script before queries succeed.',
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACxE,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,sBAAsB,EAAE,MAAM,6CAA6C,CAAC;AACrF,OAAO,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAC;AAC7E,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,yCAAyC,CAAC;AAElG,MAAM,YAAY,GAAG,eAAe,EAAE,CAAC;AAEvC;;;;;GAKG;AACH,MAAM,YAAY,GAAG,WAAW,CAAC;AAEjC,MAAM,SAAS,CAAC;IACd,IAAI,EAAE,kCAAkC;IACxC,KAAK,EAAE,kCAAkC;IACzC,KAAK,EAAE,kBAAkB;IACzB,SAAS,EAAE,sBAAsB;IACjC,YAAY,EACV,qwBAAqwB;IACvwB,OAAO,EAAE;QACP,WAAW,EAAE,KAAK;QAClB,OAAO,EACL,kIAAkI;QACpI,QAAQ,EAAE,+DAA+D;QACzE,KAAK,EAAE;YACL;gBACE,KAAK,EAAE,uBAAuB;gBAC9B,IAAI,EAAE,oFAAoF;gBAC1F,QAAQ,EAAE,IAAI;aACf;YACD;gBACE,KAAK,EAAE,8BAA8B;gBACrC,IAAI,EAAE,0DAA0D;gBAChE,QAAQ,EAAE,IAAI;aACf;SACF;KACF;IAED,KAAK,CAAC,IAAI;QACR,mBAAmB,CAAC;YAClB,cAAc,EAAE,YAAY,CAAC,cAAc;YAC3C,UAAU,EAAE,YAAY,CAAC,UAAU;YACnC,WAAW,EAAE,YAAY,CAAC,WAAW;SACtC,CAAC,CAAC;QAEH;;;;WAIG;QACH,IAAI,IAAI,CAAC,MAAM,CAAC,gBAAgB,KAAK,MAAM,EAAE,CAAC;YAC5C,KAAK,oBAAoB,EAAE,CAAC;QAC9B,CAAC;IACH,CAAC;CACF,CAAC,CAAC;AAEH,uDAAuD;AACvD,KAAK,UAAU,oBAAoB;IACjC,MAAM,gBAAgB,CAAC,QAAQ,CAC7B,sBAAsB,EACtB,YAAY,EACZ,KAAK,EAAE,MAAM,EAAE,EAAE;QACf,MAAM,CAAC,IAAI,CAAC,yCAAyC,EAAE,MAAM,CAAC,CAAC;QAC/D,MAAM,MAAM,GAAG,MAAM,kBAAkB,EAAE,CAAC,cAAc,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC;QACtF,MAAM,CAAC,IAAI,CAAC,4CAA4C,MAAM,CAAC,KAAK,UAAU,EAAE,MAAM,CAAC,CAAC;IAC1F,CAAC,EACD,gGAAgG,CACjG,CAAC;IACF,gBAAgB,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC;AACjD,CAAC"}
|