@cyanheads/nonprofit-explorer-mcp-server 0.1.4 → 0.1.5

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 CHANGED
@@ -1,10 +1,10 @@
1
1
  # Developer Protocol
2
2
 
3
3
  **Server:** nonprofit-explorer-mcp-server
4
- **Version:** 0.1.4
5
- **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.10.9`
4
+ **Version:** 0.1.5
5
+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.11.5`
6
6
  **Engines:** Bun ≥1.3.0, Node ≥24.0.0
7
- **MCP SDK:** `@modelcontextprotocol/sdk` ^1.29.0
7
+ **MCP SDK:** `@modelcontextprotocol/sdk` ^1.30.0
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.
@@ -47,19 +47,24 @@ export const nonprofitSearch = tool('nonprofit_search', {
47
47
  name: z.string().describe('Legal org name.'),
48
48
  })).describe('Matching organizations for the current page.'),
49
49
  }),
50
+ enrichment: {
51
+ notice: z.string().optional().describe('Present when the page carried no organizations.'),
52
+ },
50
53
  errors: [
51
54
  {
52
- reason: 'no_results',
53
- code: JsonRpcErrorCode.NotFound,
54
- when: 'No organizations match the given query and filters',
55
- recovery: 'Broaden the keyword query, remove one or more filters, or check spelling.',
55
+ reason: 'upstream_error',
56
+ code: JsonRpcErrorCode.ServiceUnavailable,
57
+ when: 'ProPublica returns a 5xx or the request fails at the network layer',
58
+ retryable: true,
59
+ recovery: 'Wait a moment and retry.',
56
60
  },
57
61
  ],
58
62
  async handler(input, ctx) {
59
63
  const svc = getNonprofitExplorerService();
60
64
  const raw = await svc.search(input, ctx);
61
65
  const orgs = raw.organizations ?? [];
62
- if (orgs.length === 0) throw ctx.fail('no_results', `No results for "${input.query}"`);
66
+ // A zero-hit search succeeded — return an empty list plus a notice, never an error.
67
+ if (orgs.length === 0) ctx.enrich.notice(`No organizations matched "${input.query}".`);
63
68
  return { total_results: raw.total_results ?? 0, organizations: orgs.map(o => ({ ein: o.ein, name: o.name ?? '' })) };
64
69
  },
65
70
  format: (result) => [{ type: 'text', text: result.organizations.map(o => `**${o.name}** (EIN: ${o.ein})`).join('\n') }],
@@ -79,10 +84,14 @@ Handlers receive a unified `ctx` object. Key properties:
79
84
  | Property | Description |
80
85
  |:---------|:------------|
81
86
  | `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. |
82
- | `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |
87
+ | `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |
88
+ | `ctx.elicit` | Ask user for structured input — form call `(message, schema)` or `.url(message, url)` for an external link. **Check for presence first:** `if (ctx.elicit) { ... }` |
89
+ | `ctx.enrich` | Success-path agent context (empty-result notices, query echo, pagination totals) — `ctx.enrich(...)` or `.notice()` / `.total()` / `.echo()` / `.truncated()`. Reaches `structuredContent` and `content[]`; lands only when the definition declares an `enrichment` block (no-op otherwise). |
90
+ | `ctx.content` | Non-text content blocks — `.image(data, mimeType)`, `.audio(data, mimeType)`, or `ctx.content(block)` for a raw block. Prepended to `content[]` after `format()`; never enters `structuredContent`. |
83
91
  | `ctx.signal` | `AbortSignal` for cancellation. |
92
+ | `ctx.progress` | Task progress (present when `task: true`) — `.setTotal(n)`, `.increment()`, `.update(message)`. |
84
93
  | `ctx.requestId` | Unique request ID. |
85
- | `ctx.tenantId` | Tenant ID from JWT or `'default'` for stdio. |
94
+ | `ctx.tenantId` | Tenant ID from JWT; `'default'` for stdio or HTTP with auth off. |
86
95
 
87
96
  ---
88
97
 
@@ -90,7 +99,7 @@ Handlers receive a unified `ctx` object. Key properties:
90
99
 
91
100
  Handlers throw — the framework catches, classifies, and formats.
92
101
 
93
- **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).
102
+ **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 (≥ 5 words, lint-validated) — the single source of truth for the agent's next move. Pass `ctx.recoveryFor('reason')` as the throw's data to put it on the wire (`data.recovery.hint`, mirrored into `content[]` text); override with an explicit `{ recovery: { hint: '...' } }` when dynamic runtime context matters. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring.
94
103
 
95
104
  ```ts
96
105
  import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
@@ -107,6 +116,8 @@ async handler(input, ctx) {
107
116
  }
108
117
  ```
109
118
 
119
+ **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.
120
+
110
121
  **Fallback (no contract entry fits):** throw via factories or plain `Error`.
111
122
 
112
123
  ```ts
@@ -150,7 +161,7 @@ src/
150
161
 
151
162
  ## Skills
152
163
 
153
- 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.
164
+ 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.
154
165
 
155
166
  **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.
156
167
 
@@ -170,7 +181,6 @@ Available skills:
170
181
  | `tool-defs-analysis` | Read-only audit of MCP definition language across the surface — voice, leaks, defaults, recovery hints, output descriptions |
171
182
  | `security-pass` | Audit server for MCP-flavored security gaps: output injection, scope blast radius, input sinks, tenant isolation |
172
183
  | `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase |
173
- | `devcheck` | Lint, format, typecheck, audit |
174
184
  | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
175
185
  | `git-wrapup` | Land working-tree changes as a versioned commit + annotated tag — version bump, changelog, verify, tag. Local only. |
176
186
  | `release-and-publish` | Push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
@@ -178,19 +188,22 @@ Available skills:
178
188
  | `orchestrations` | Chain task skills into a gated multi-phase pipeline — build-out, QA-fix, update-ship — when you can spawn sub-agents |
179
189
  | `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
180
190
  | `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
181
- | `techniques` | Reusable response/data-shaping patterns (outline-on-overflow, capped-list disclosure) |
191
+ | `techniques` | Catalog of response/data-shaping techniques — overflow handling, payload shaping, retrieval patterns |
182
192
  | `api-auth` | Auth modes, scopes, JWT/OAuth |
183
193
  | `api-canvas` | DataCanvas: register tabular data, run SQL, export, plus the `spillover()` helper for big result sets — Tier 3 opt-in |
184
194
  | `api-config` | AppConfig, parseConfig, env vars |
185
195
  | `api-context` | Context interface, logger, state, progress |
186
196
  | `api-errors` | McpError, JsonRpcErrorCode, error patterns |
187
197
  | `api-linter` | Definition linter rule catalog — invoked by `bun run lint:mcp` and `devcheck` |
198
+ | `api-mirror` | MirrorService: persistent self-refreshing local mirror (embedded SQLite + FTS5) of a bulk upstream dataset — Tier 3 opt-in |
188
199
  | `api-services` | LLM, Speech, Graph services |
189
200
  | `api-testing` | createMockContext, test patterns |
190
201
  | `api-utils` | Formatting, parsing, security, pagination, scheduling, telemetry helpers |
191
202
  | `api-telemetry` | OTel catalog: spans, metrics, completion logs, env config, cardinality rules |
192
203
  | `api-workers` | Cloudflare Workers runtime |
193
204
 
205
+ **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.
206
+
194
207
  When you complete a skill's checklist, check the boxes and add a completion timestamp at the end (e.g., `Completed: 2026-06-01`).
195
208
 
196
209
  ---
@@ -206,10 +219,13 @@ When you complete a skill's checklist, check the boxes and add a completion time
206
219
  | `bun run clean` | Remove build artifacts |
207
220
  | `bun run devcheck` | Lint + format + typecheck + security + changelog sync |
208
221
  | `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. |
222
+ | `bun run lint:mcp` | Run the MCP definition linter standalone (rule catalog: `api-linter` skill) |
223
+ | `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity (run by devcheck) |
224
+ | `bun run list-skills` | Print the skill registry |
209
225
  | `bun run tree` | Generate directory structure doc |
210
226
  | `bun run format` | Auto-fix formatting (safe fixes only) |
211
227
  | `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
212
- | `bun run test` | Run tests |
228
+ | `bun run test` | Run tests (Vitest — use `bun run test`, not `bun test`) |
213
229
  | `bun run start:stdio` | Production mode (stdio) |
214
230
  | `bun run start:http` | Production mode (HTTP) |
215
231
  | `bun run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
@@ -220,7 +236,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
220
236
 
221
237
  ## Bundling
222
238
 
223
- `bun 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.
239
+ `bun 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 two classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`skills/`, `.claude/`, `.agents/`, `SKILL.md`) and platform-specific native bindings, which would otherwise lock the bundle to the platform it was packed on. 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.
224
240
 
225
241
  **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.
226
242
 
@@ -238,14 +254,14 @@ Each per-version file opens with YAML frontmatter:
238
254
  ---
239
255
  summary: "One-line headline, ≤350 chars" # required — powers the rollup index
240
256
  breaking: false # optional — true flags breaking changes
241
- security: false # optional — true flags security fixes
257
+ security: false # optional — true ONLY for a source-code security fix, never a dependency CVE bump
242
258
  ---
243
259
 
244
260
  # 0.1.0 — YYYY-MM-DD
245
261
  ...
246
262
  ```
247
263
 
248
- `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`.
264
+ `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 — set it only for a security fix in this server's *own source code*, never for a routine dependency or transitive CVE bump (record those under `## Dependencies`). When both are set, badges render `· ⚠️ Breaking · 🛡️ Security`.
249
265
 
250
266
  `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.
251
267
 
package/CLAUDE.md CHANGED
@@ -1,10 +1,10 @@
1
1
  # Developer Protocol
2
2
 
3
3
  **Server:** nonprofit-explorer-mcp-server
4
- **Version:** 0.1.4
5
- **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.10.9`
4
+ **Version:** 0.1.5
5
+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.11.5`
6
6
  **Engines:** Bun ≥1.3.0, Node ≥24.0.0
7
- **MCP SDK:** `@modelcontextprotocol/sdk` ^1.29.0
7
+ **MCP SDK:** `@modelcontextprotocol/sdk` ^1.30.0
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.
@@ -47,19 +47,24 @@ export const nonprofitSearch = tool('nonprofit_search', {
47
47
  name: z.string().describe('Legal org name.'),
48
48
  })).describe('Matching organizations for the current page.'),
49
49
  }),
50
+ enrichment: {
51
+ notice: z.string().optional().describe('Present when the page carried no organizations.'),
52
+ },
50
53
  errors: [
51
54
  {
52
- reason: 'no_results',
53
- code: JsonRpcErrorCode.NotFound,
54
- when: 'No organizations match the given query and filters',
55
- recovery: 'Broaden the keyword query, remove one or more filters, or check spelling.',
55
+ reason: 'upstream_error',
56
+ code: JsonRpcErrorCode.ServiceUnavailable,
57
+ when: 'ProPublica returns a 5xx or the request fails at the network layer',
58
+ retryable: true,
59
+ recovery: 'Wait a moment and retry.',
56
60
  },
57
61
  ],
58
62
  async handler(input, ctx) {
59
63
  const svc = getNonprofitExplorerService();
60
64
  const raw = await svc.search(input, ctx);
61
65
  const orgs = raw.organizations ?? [];
62
- if (orgs.length === 0) throw ctx.fail('no_results', `No results for "${input.query}"`);
66
+ // A zero-hit search succeeded — return an empty list plus a notice, never an error.
67
+ if (orgs.length === 0) ctx.enrich.notice(`No organizations matched "${input.query}".`);
63
68
  return { total_results: raw.total_results ?? 0, organizations: orgs.map(o => ({ ein: o.ein, name: o.name ?? '' })) };
64
69
  },
65
70
  format: (result) => [{ type: 'text', text: result.organizations.map(o => `**${o.name}** (EIN: ${o.ein})`).join('\n') }],
@@ -79,10 +84,14 @@ Handlers receive a unified `ctx` object. Key properties:
79
84
  | Property | Description |
80
85
  |:---------|:------------|
81
86
  | `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. |
82
- | `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |
87
+ | `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |
88
+ | `ctx.elicit` | Ask user for structured input — form call `(message, schema)` or `.url(message, url)` for an external link. **Check for presence first:** `if (ctx.elicit) { ... }` |
89
+ | `ctx.enrich` | Success-path agent context (empty-result notices, query echo, pagination totals) — `ctx.enrich(...)` or `.notice()` / `.total()` / `.echo()` / `.truncated()`. Reaches `structuredContent` and `content[]`; lands only when the definition declares an `enrichment` block (no-op otherwise). |
90
+ | `ctx.content` | Non-text content blocks — `.image(data, mimeType)`, `.audio(data, mimeType)`, or `ctx.content(block)` for a raw block. Prepended to `content[]` after `format()`; never enters `structuredContent`. |
83
91
  | `ctx.signal` | `AbortSignal` for cancellation. |
92
+ | `ctx.progress` | Task progress (present when `task: true`) — `.setTotal(n)`, `.increment()`, `.update(message)`. |
84
93
  | `ctx.requestId` | Unique request ID. |
85
- | `ctx.tenantId` | Tenant ID from JWT or `'default'` for stdio. |
94
+ | `ctx.tenantId` | Tenant ID from JWT; `'default'` for stdio or HTTP with auth off. |
86
95
 
87
96
  ---
88
97
 
@@ -90,7 +99,7 @@ Handlers receive a unified `ctx` object. Key properties:
90
99
 
91
100
  Handlers throw — the framework catches, classifies, and formats.
92
101
 
93
- **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).
102
+ **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 (≥ 5 words, lint-validated) — the single source of truth for the agent's next move. Pass `ctx.recoveryFor('reason')` as the throw's data to put it on the wire (`data.recovery.hint`, mirrored into `content[]` text); override with an explicit `{ recovery: { hint: '...' } }` when dynamic runtime context matters. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring.
94
103
 
95
104
  ```ts
96
105
  import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
@@ -107,6 +116,8 @@ async handler(input, ctx) {
107
116
  }
108
117
  ```
109
118
 
119
+ **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.
120
+
110
121
  **Fallback (no contract entry fits):** throw via factories or plain `Error`.
111
122
 
112
123
  ```ts
@@ -150,7 +161,7 @@ src/
150
161
 
151
162
  ## Skills
152
163
 
153
- 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.
164
+ 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.
154
165
 
155
166
  **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.
156
167
 
@@ -170,7 +181,6 @@ Available skills:
170
181
  | `tool-defs-analysis` | Read-only audit of MCP definition language across the surface — voice, leaks, defaults, recovery hints, output descriptions |
171
182
  | `security-pass` | Audit server for MCP-flavored security gaps: output injection, scope blast radius, input sinks, tenant isolation |
172
183
  | `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase |
173
- | `devcheck` | Lint, format, typecheck, audit |
174
184
  | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
175
185
  | `git-wrapup` | Land working-tree changes as a versioned commit + annotated tag — version bump, changelog, verify, tag. Local only. |
176
186
  | `release-and-publish` | Push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
@@ -178,19 +188,22 @@ Available skills:
178
188
  | `orchestrations` | Chain task skills into a gated multi-phase pipeline — build-out, QA-fix, update-ship — when you can spawn sub-agents |
179
189
  | `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
180
190
  | `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
181
- | `techniques` | Reusable response/data-shaping patterns (outline-on-overflow, capped-list disclosure) |
191
+ | `techniques` | Catalog of response/data-shaping techniques — overflow handling, payload shaping, retrieval patterns |
182
192
  | `api-auth` | Auth modes, scopes, JWT/OAuth |
183
193
  | `api-canvas` | DataCanvas: register tabular data, run SQL, export, plus the `spillover()` helper for big result sets — Tier 3 opt-in |
184
194
  | `api-config` | AppConfig, parseConfig, env vars |
185
195
  | `api-context` | Context interface, logger, state, progress |
186
196
  | `api-errors` | McpError, JsonRpcErrorCode, error patterns |
187
197
  | `api-linter` | Definition linter rule catalog — invoked by `bun run lint:mcp` and `devcheck` |
198
+ | `api-mirror` | MirrorService: persistent self-refreshing local mirror (embedded SQLite + FTS5) of a bulk upstream dataset — Tier 3 opt-in |
188
199
  | `api-services` | LLM, Speech, Graph services |
189
200
  | `api-testing` | createMockContext, test patterns |
190
201
  | `api-utils` | Formatting, parsing, security, pagination, scheduling, telemetry helpers |
191
202
  | `api-telemetry` | OTel catalog: spans, metrics, completion logs, env config, cardinality rules |
192
203
  | `api-workers` | Cloudflare Workers runtime |
193
204
 
205
+ **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.
206
+
194
207
  When you complete a skill's checklist, check the boxes and add a completion timestamp at the end (e.g., `Completed: 2026-06-01`).
195
208
 
196
209
  ---
@@ -206,10 +219,13 @@ When you complete a skill's checklist, check the boxes and add a completion time
206
219
  | `bun run clean` | Remove build artifacts |
207
220
  | `bun run devcheck` | Lint + format + typecheck + security + changelog sync |
208
221
  | `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. |
222
+ | `bun run lint:mcp` | Run the MCP definition linter standalone (rule catalog: `api-linter` skill) |
223
+ | `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity (run by devcheck) |
224
+ | `bun run list-skills` | Print the skill registry |
209
225
  | `bun run tree` | Generate directory structure doc |
210
226
  | `bun run format` | Auto-fix formatting (safe fixes only) |
211
227
  | `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
212
- | `bun run test` | Run tests |
228
+ | `bun run test` | Run tests (Vitest — use `bun run test`, not `bun test`) |
213
229
  | `bun run start:stdio` | Production mode (stdio) |
214
230
  | `bun run start:http` | Production mode (HTTP) |
215
231
  | `bun run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
@@ -220,7 +236,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
220
236
 
221
237
  ## Bundling
222
238
 
223
- `bun 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.
239
+ `bun 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 two classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`skills/`, `.claude/`, `.agents/`, `SKILL.md`) and platform-specific native bindings, which would otherwise lock the bundle to the platform it was packed on. 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.
224
240
 
225
241
  **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.
226
242
 
@@ -238,14 +254,14 @@ Each per-version file opens with YAML frontmatter:
238
254
  ---
239
255
  summary: "One-line headline, ≤350 chars" # required — powers the rollup index
240
256
  breaking: false # optional — true flags breaking changes
241
- security: false # optional — true flags security fixes
257
+ security: false # optional — true ONLY for a source-code security fix, never a dependency CVE bump
242
258
  ---
243
259
 
244
260
  # 0.1.0 — YYYY-MM-DD
245
261
  ...
246
262
  ```
247
263
 
248
- `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`.
264
+ `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 — set it only for a security fix in this server's *own source code*, never for a routine dependency or transitive CVE bump (record those under `## Dependencies`). When both are set, badges render `· ⚠️ Breaking · 🛡️ Security`.
249
265
 
250
266
  `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.
251
267
 
package/Dockerfile CHANGED
@@ -4,15 +4,17 @@
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.3 AS build
7
+ FROM oven/bun:1.3.14 AS build
8
8
 
9
9
  WORKDIR /usr/src/app
10
10
 
11
11
  # Copy dependency manifests for optimized layer caching
12
12
  COPY package.json bun.lock ./
13
13
 
14
- # Install all dependencies (including dev dependencies for building)
15
- RUN bun install --frozen-lockfile
14
+ # Install all dependencies (including dev dependencies for building).
15
+ # The BuildKit cache mount persists Bun's global package cache across builds.
16
+ RUN --mount=type=cache,target=/root/.bun/install/cache \
17
+ bun install --frozen-lockfile --ignore-scripts
16
18
 
17
19
  # Copy the rest of the source code
18
20
  COPY . .
@@ -28,7 +30,7 @@ RUN bun run build
28
30
  # application. It uses a slim base image and only includes production
29
31
  # dependencies and build artifacts.
30
32
  # ==============================================================================
31
- FROM oven/bun:1.3-slim AS production
33
+ FROM oven/bun:1.3.14-slim AS production
32
34
 
33
35
  WORKDIR /usr/src/app
34
36
 
@@ -39,7 +41,7 @@ ENV NODE_ENV=production
39
41
  # OCI image metadata (https://github.com/opencontainers/image-spec/blob/main/annotations.md)
40
42
  ARG APP_VERSION=dev
41
43
  LABEL org.opencontainers.image.title="nonprofit-explorer-mcp-server"
42
- LABEL org.opencontainers.image.description="MCP server for US nonprofit financials via ProPublica — IRS Form 990 data for 1.8M+ tax-exempt organizations."
44
+ LABEL org.opencontainers.image.description="Search and explore 1.8M+ US nonprofits, fetch Form 990 financials, and access IRS filing history via MCP. STDIO or Streamable HTTP."
43
45
  LABEL org.opencontainers.image.licenses="Apache-2.0"
44
46
  LABEL org.opencontainers.image.source="https://github.com/cyanheads/nonprofit-explorer-mcp-server"
45
47
  LABEL org.opencontainers.image.version="${APP_VERSION}"
@@ -49,14 +51,21 @@ COPY package.json bun.lock ./
49
51
 
50
52
  # Install only production dependencies, ignoring any lifecycle scripts (like 'prepare')
51
53
  # that are not needed in the final production image.
52
- RUN bun install --production --frozen-lockfile --ignore-scripts
54
+ # `--omit=peer` drops the framework's optional peer tiers (test runner, service
55
+ # SDKs, parsers) that Bun would otherwise auto-install. Anything this server
56
+ # actually imports belongs in its own `dependencies`, so nothing needed at
57
+ # runtime is lost. The OTEL step below carries the same flag — without it, that
58
+ # install re-resolves the graph and pulls every optional peer back in.
59
+ RUN --mount=type=cache,target=/root/.bun/install/cache \
60
+ bun install --production --omit=peer --frozen-lockfile --ignore-scripts
53
61
 
54
62
  # Conditionally install OpenTelemetry optional peer dependencies (Tier 3).
55
63
  # These are not bundled by default to keep the base image lean. Enable at build time
56
64
  # with: docker build --build-arg OTEL_ENABLED=true
57
65
  ARG OTEL_ENABLED=true
58
- RUN if [ "$OTEL_ENABLED" = "true" ]; then \
59
- bun add @hono/otel \
66
+ RUN --mount=type=cache,target=/root/.bun/install/cache \
67
+ if [ "$OTEL_ENABLED" = "true" ]; then \
68
+ bun add --omit=dev --omit=peer --ignore-scripts @hono/otel \
60
69
  @opentelemetry/instrumentation-http \
61
70
  @opentelemetry/exporter-metrics-otlp-http \
62
71
  @opentelemetry/exporter-trace-otlp-http \
package/LICENSE CHANGED
@@ -186,7 +186,7 @@ Apache License
186
186
  same "printed page" as the copyright notice for easier
187
187
  identification within third-party archives.
188
188
 
189
- Copyright 2025 Casey Hand @cyanheads
189
+ Copyright 2026 Casey Hand @cyanheads
190
190
 
191
191
  Licensed under the Apache License, Version 2.0 (the "License");
192
192
  you may not use this file except in compliance with the License.
package/README.md CHANGED
@@ -7,7 +7,7 @@
7
7
 
8
8
  <div align="center">
9
9
 
10
- [![Version](https://img.shields.io/badge/Version-0.1.4-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/nonprofit-explorer-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/nonprofit-explorer-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/nonprofit-explorer-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.11-blueviolet.svg?style=flat-square)](https://bun.sh/)
10
+ [![Version](https://img.shields.io/badge/Version-0.1.5-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/nonprofit-explorer-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.30.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/nonprofit-explorer-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/nonprofit-explorer-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.14-blueviolet.svg?style=flat-square)](https://bun.sh/)
11
11
 
12
12
  </div>
13
13
 
@@ -43,11 +43,12 @@ Search for tax-exempt organizations across the IRS Nonprofit Explorer dataset.
43
43
 
44
44
  - Full-text search across org name, alternate name, and city with relevance ranking
45
45
  - Supports quoted phrases (`"Red Cross"`), required terms (`+evanston`), excluded terms (`-dental`)
46
- - Filter by US state (two-letter abbreviation; `ZZ` for foreign entities)
46
+ - Filter by US state, territory, or military postal code (`ZZ` for foreign entities); case-insensitive, and a code outside that set is rejected rather than silently returning national results
47
47
  - Filter by NTEE major sector (Arts, Education, Health, Human Services, etc., 1–10)
48
48
  - Filter by 501(c) subsection code (e.g., `3` = public charity, `4` = social welfare)
49
- - Paginated at 25 per page; use `page` (zero-indexed) and `num_pages` to walk large result sets
50
- - API caps total results at 10,000; `total_results === 10000` means the actual count may be higher
49
+ - Paginated at 25 per page; use `page` (zero-indexed) with `num_pages`, `per_page`, and `page_offset` to walk large result sets
50
+ - Zero matches and a page past the last one are both successful searches with an empty `organizations` array and a `notice` explaining which case it is
51
+ - API caps total results at 10,000; `total_results === 10000` means the actual count may be higher, and a `page` whose offset reaches 10,000 is refused with the `pagination_ceiling` error
51
52
  - Returns EINs — pass to `nonprofit_get_organization` or `nonprofit_get_filings` for details
52
53
 
53
54
  ---
@@ -184,7 +185,7 @@ MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
184
185
 
185
186
  ### Prerequisites
186
187
 
187
- - [Bun v1.3.11](https://bun.sh/) or higher (or Node.js v24+).
188
+ - [Bun v1.3.14](https://bun.sh/) or higher (or Node.js v24+).
188
189
  - No API key required — ProPublica Nonprofit Explorer is a keyless public API.
189
190
 
190
191
  ### Installation
@@ -0,0 +1,40 @@
1
+ ---
2
+ summary: "Fixes nonprofit_search state-filter case handling and pagination-boundary misclassification, wires recovery hints into service-originated errors, and adopts mcp-ts-core ^0.11.5."
3
+ breaking: false
4
+ security: false
5
+ ---
6
+
7
+ # 0.1.5 — 2026-08-13
8
+
9
+ ## Added
10
+
11
+ - **`per_page` / `page_offset`** on `nonprofit_search` output, mirroring ProPublica's pagination metadata when present.
12
+ - **Bun install-security scanner** (`bunfig.toml`) — `@socketsecurity/bun-security-scanner` scans every install; `minimumReleaseAge` blocks packages published in the last 3 days, with `@cyanheads/mcp-ts-core` exempted for same-day framework adoption.
13
+ - **`.mcpb` native-binding strip** — `scripts/clean-mcpb.ts` and `lint:packaging` now also strip and verify `@duckdb/node-bindings-*` platform-specific entries, alongside the existing agent-doc strip.
14
+ - **GitHub community health files** — `CODE_OF_CONDUCT.md`, `CONTRIBUTING.md`, `SECURITY.md`, `FUNDING.yml` under `.github/`, and `.gitattributes` for line-ending normalization and generated-file marking.
15
+
16
+ ## Changed
17
+
18
+ - **`tsconfig.json` split** — typechecks `src/` and `tests/` with `noEmit: true`; `tsconfig.build.json` narrows to `src/` for the actual compile.
19
+ - Vendored skills resynced to mcp-ts-core `^0.11.5` conventions.
20
+ - Dockerfile adopts BuildKit cache mounts for `bun install` layers and pins the exact Bun patch (`1.3.14`) over a floating minor tag.
21
+ - devcheck's outdated-dependency check now tolerates versions held back by `minimumReleaseAge` and skips peer-range rows.
22
+
23
+ ## Fixed
24
+
25
+ - **`nonprofit_search` state filter** — `state` is uppercased before the ProPublica request and validated against US states, DC, territories, and military codes (plus `ZZ`); an unrecognized value is now rejected as `invalid_state` instead of silently returning unfiltered national results. (#2)
26
+ - **`nonprofit_search` empty-page handling** — a zero-match query and a page past the end of the result set are now both successes (empty `organizations`, plus a `notice` distinguishing which) instead of sharing the same `no_results` error. (#5)
27
+ - **`nonprofit_search` pagination ceiling** — a page at or beyond ProPublica's 10,000-result offset ceiling is now a non-retryable `pagination_ceiling` error instead of the generic `upstream_error`. (#5)
28
+ - **Service-layer error recovery hints** — `nonprofit_get_organization`, `nonprofit_get_filings`, and `nonprofit_search` now attach each tool's own declared `recovery` hint to service-originated `not_found`/`upstream_error`/`pagination_ceiling` throws, not just handler-level ones. (#6)
29
+
30
+ ## Dependencies
31
+
32
+ - `@cyanheads/mcp-ts-core` ^0.10.9 → ^0.11.5
33
+ - `typescript` ^6.0.3 → ^7.0.2
34
+ - `@biomejs/biome` ^2.5.0 → ^2.5.7
35
+ - `@types/node` ^26.0.0 → ^26.2.0
36
+ - `tsc-alias` ^1.8.17 → ^1.9.1
37
+ - `vitest` ^4.1.9 → ^4.1.10
38
+ - `ignore` ^7.0.5 → ^7.0.6
39
+ - `@socketsecurity/bun-security-scanner` added ^1.1.2
40
+ - Bun `1.3.11` → `1.3.14`; MCP SDK (peer, via framework) `^1.29.0` → `^1.30.0`
@@ -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 unrelated changes with
9
- # semicolons — pick the headline. Quotes required: unquoted YAML treats `: `
10
- # inside the value as a key separator and fails GitHub's strict parser.
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,
@@ -15,16 +16,19 @@ summary: ""
15
16
  # usage. Flagged as `Breaking` in the rollup.
16
17
  breaking: false
17
18
 
18
- # Set `true` if this release contains any security fix. Pairs with the
19
- # `## Security` section below. Flagged as `Security` in the rollup so
20
- # users can triage upgrade urgency at a glance.
19
+ # Set `true` ONLY for a security fix in THIS project's own source code — a
20
+ # vulnerability or hardening in code you ship. A dependency or transitive CVE
21
+ # bump is routine maintenance, NOT a security release: record it under
22
+ # `## Dependencies` (with the advisory ID) and leave this `false`. When true,
23
+ # pairs with the `## Security` section below and flags `Security` in the rollup.
21
24
  security: false
22
25
 
23
26
  # Optional free-form notes for maintenance agents processing this release.
24
27
  # Not rendered in CHANGELOG — consumed by agents running `maintenance` on
25
- # downstream servers. Use for adoption instructions that don't fit the
26
- # human-facing sections: new files to create, fields to populate, one-time
27
- # migration steps. Omit the field entirely when there's nothing to say.
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.
28
32
  # agent-notes: |
29
33
  # <instructions for downstream maintenance agents>
30
34
  ---
@@ -39,17 +43,54 @@ security: false
39
43
  each bullet with the symbol or concept name in **bold** so they can skip
40
44
  what's irrelevant and zoom in on what's not.
41
45
 
42
- Tone: terse, fact-dense, not verbose. Default to one sentence per bullet —
43
- name the symbol, state what changed, stop. Use a second sentence only when
44
- it carries weight. If a bullet feels long, it is.
45
-
46
- Cut: mechanism walkthroughs (those belong in JSDoc, CLAUDE.md/AGENTS.md, or the
47
- relevant skill), ceremonial framings ("This release introduces…",
48
- backwards-compat paragraphs), file-by-file test enumerations, internal
49
- implementation notes. Prefer code/symbol names over English re-explanations.
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.
50
89
 
51
90
  Narrative intro: skip by default. Add one short sentence only when the
52
- 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.
53
94
 
54
95
  Sections: Keep a Changelog order — Added, Changed, Deprecated, Removed,
55
96
  Fixed, Security. Include only sections with entries; delete the rest