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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (30) hide show
  1. package/AGENTS.md +34 -18
  2. package/CLAUDE.md +34 -18
  3. package/Dockerfile +17 -8
  4. package/LICENSE +1 -1
  5. package/README.md +15 -12
  6. package/changelog/0.1.x/0.1.5.md +40 -0
  7. package/changelog/0.1.x/0.1.6.md +25 -0
  8. package/changelog/template.md +60 -19
  9. package/dist/index.js +1 -1
  10. package/dist/index.js.map +1 -1
  11. package/dist/mcp-server/tools/definitions/nonprofit-get-filings.tool.d.ts +4 -7
  12. package/dist/mcp-server/tools/definitions/nonprofit-get-filings.tool.d.ts.map +1 -1
  13. package/dist/mcp-server/tools/definitions/nonprofit-get-filings.tool.js +86 -114
  14. package/dist/mcp-server/tools/definitions/nonprofit-get-filings.tool.js.map +1 -1
  15. package/dist/mcp-server/tools/definitions/nonprofit-get-organization.tool.d.ts +4 -0
  16. package/dist/mcp-server/tools/definitions/nonprofit-get-organization.tool.d.ts.map +1 -1
  17. package/dist/mcp-server/tools/definitions/nonprofit-get-organization.tool.js +110 -44
  18. package/dist/mcp-server/tools/definitions/nonprofit-get-organization.tool.js.map +1 -1
  19. package/dist/mcp-server/tools/definitions/nonprofit-search.tool.d.ts +24 -14
  20. package/dist/mcp-server/tools/definitions/nonprofit-search.tool.d.ts.map +1 -1
  21. package/dist/mcp-server/tools/definitions/nonprofit-search.tool.js +114 -37
  22. package/dist/mcp-server/tools/definitions/nonprofit-search.tool.js.map +1 -1
  23. package/dist/services/nonprofit-explorer/nonprofit-explorer-service.d.ts +12 -0
  24. package/dist/services/nonprofit-explorer/nonprofit-explorer-service.d.ts.map +1 -1
  25. package/dist/services/nonprofit-explorer/nonprofit-explorer-service.js +83 -32
  26. package/dist/services/nonprofit-explorer/nonprofit-explorer-service.js.map +1 -1
  27. package/dist/services/nonprofit-explorer/types.d.ts +29 -2
  28. package/dist/services/nonprofit-explorer/types.d.ts.map +1 -1
  29. package/package.json +12 -11
  30. package/server.json +3 -3
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.6
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.6
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.6-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
 
@@ -35,19 +35,20 @@
35
35
  |:---|:---|
36
36
  | `nonprofit_search` | Search 1.8M+ IRS-recognized tax-exempt organizations by name, keyword, city, or phrase with optional state, NTEE sector, and 501(c) filters |
37
37
  | `nonprofit_get_organization` | Full profile for one org by EIN: legal identity, IRS classification, ruling date, and a financial snapshot from the most recent Form 990 |
38
- | `nonprofit_get_filings` | All Form 990 filings for an org by EIN: year-by-year financials, program-expense ratio, executive compensation, and source PDF/XML links |
38
+ | `nonprofit_get_filings` | All Form 990 filings for an org by EIN: year-by-year financials, revenue breakdown, executive compensation, and source PDF links |
39
39
 
40
40
  ### `nonprofit_search`
41
41
 
42
42
  Search for tax-exempt organizations across the IRS Nonprofit Explorer dataset.
43
43
 
44
- - Full-text search across org name, alternate name, and city with relevance ranking
44
+ - Full-text search across org name, the IRS Business Master File secondary name line, 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
- - 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
48
+ - Filter by 501(c) subsection code (e.g., `3` = charitable organization — both public charities and private foundations, `4` = social welfare)
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
  ---
@@ -58,6 +59,7 @@ Fetch the full profile for a single tax-exempt org by EIN.
58
59
 
59
60
  - Accepts EIN as integer (`530196605`) or string with or without hyphen (`"53-0196605"`)
60
61
  - Returns legal name, address, NTEE code, 501(c) type, and IRS ruling date
62
+ - IRS Business Master File standing: whether contributions are deductible (including the deductible-by-treaty case), exemption status, and public-charity vs. private-foundation classification — each decoded from its IRS code with the raw code retained
61
63
  - Financial snapshot from the most recent Form 990: revenue, expenses, assets, liabilities, net assets
62
64
  - Includes source 990 PDF link and IRS Business Master File summary figures
63
65
  - `filing_count` shows how many filings with extracted data are on record
@@ -72,9 +74,10 @@ Fetch the full filing history for an org by EIN.
72
74
 
73
75
  - All Form 990 filings with extracted financial data, sorted newest first
74
76
  - Per-filing: revenue, expenses, assets, liabilities, net assets, revenue breakdown (contributions, program service, investment income)
75
- - Program-expense ratio computed from 990 inputs with the full breakdown shown (officer comp, other salaries, fundraising); not available for 990-PF
77
+ - `program_expense_ratio` is always `null` — ProPublica returns no Form 990 Part IX program-service expense total, so the program/management/fundraising split is only in the source PDF
76
78
  - Executive compensation summary with field-name transparency and a note pointing to Schedule J for per-officer detail
77
- - Source 990 PDF and XML links per filing
79
+ - Source 990 PDF link per filing
80
+ - An EIN that resolves to a real org with no 990 on record returns an empty `filings` array plus a `notice` — a successful lookup, not an error
78
81
  - `filings_pdf_only` lists older filings with a PDF but no extracted data
79
82
  - Data lags 1–2 years; always cite `tax_prd_yr` (fiscal year) when presenting figures
80
83
 
@@ -94,14 +97,14 @@ ProPublica Nonprofit Explorer / IRS-specific:
94
97
  - Keyless access — ProPublica Nonprofit Explorer API requires no API key
95
98
  - Covers 1.8M+ IRS-recognized tax-exempt organizations
96
99
  - IRS Form 990 data: annual filings for public charities (990), small orgs (990-EZ), and private foundations (990-PF)
97
- - Source filing links (PDF and XML) on every filing record
100
+ - Source filing PDF link on every filing record, except where IRS PDF processing lags the extracted data and `pdf_url` is still null
98
101
  - Data sourced from ProPublica Nonprofit Explorer, derived from IRS Form 990 filings; data lags 1–2 years
99
102
 
100
103
  Agent-friendly output:
101
104
 
102
105
  - Provenance on every response — `data_source` attribution on all tool outputs, ProPublica URL for direct verification
103
106
  - Filing-year clarity — `tax_prd_yr` prominently labeled as fiscal year with explicit lag caveat in every financial response
104
- - Program-expense ratio with inputs — ratio is accompanied by the full expense breakdown so agents and users can verify the computation
107
+ - Null values are rendered, not dropped — the formatted text names why a value is absent (never recorded by the IRS, not extracted from the filing, not carried by that form type), and `structuredContent` keeps an explicit `null` rather than omitting the key
105
108
  - Field-name transparency on compensation — `field_name` and `form_type` exposed so agents know exactly which IRS field was read
106
109
 
107
110
  ## Getting started
@@ -184,7 +187,7 @@ MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
184
187
 
185
188
  ### Prerequisites
186
189
 
187
- - [Bun v1.3.11](https://bun.sh/) or higher (or Node.js v24+).
190
+ - [Bun v1.3.14](https://bun.sh/) or higher (or Node.js v24+).
188
191
  - No API key required — ProPublica Nonprofit Explorer is a keyless public API.
189
192
 
190
193
  ### 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`
@@ -0,0 +1,25 @@
1
+ ---
2
+ summary: "Removes nonprofit_get_filings' non-derivable program-expense ratio, adds IRS Business Master File classification fields to nonprofit_get_organization, and renders null values consistently across all three tools' output."
3
+ breaking: false
4
+ security: false
5
+ ---
6
+
7
+ # 0.1.6 — 2026-08-12
8
+
9
+ ## Added
10
+
11
+ - **IRS Business Master File classification** on `nonprofit_get_organization` — `deductible`, `exempt_status`, `foundation_type`, and `bmf_tax_period`, each decoded from its IRS code as `"<code> — <meaning>"` with the raw code retained. (#3)
12
+
13
+ ## Changed
14
+
15
+ - `sort_name`/`sub_name` relabeled across all three tools as the IRS Business Master File secondary name line — an internal sort key, not an alternate organization name.
16
+ - 501(c)(3) description corrected: it covers both public charities and private foundations, not "public charity" alone; `foundation_type` now distinguishes them.
17
+ - `docs/idea.md` marked as a superseded pre-build document; `docs/design.md` is the accurate reference.
18
+
19
+ ## Fixed
20
+
21
+ - **`nonprofit_get_filings` program-expense ratio** is now always `null` instead of an approximation computed from inputs that cannot produce it — ProPublica returns no Form 990 Part IX column (B) program-service total. (#4)
22
+ - **Null-valued fields** now render in `format()` across all three tools instead of being silently omitted, each labeled with why it's absent. A populated `revenue_amount` no longer disappears when `asset_amount` and `income_amount` are null. (#8)
23
+ - **`nonprofit_get_filings`** — an EIN resolving to a real organization with no 990 on record now returns a successful empty `filings` array with an enrichment notice instead of throwing `no_filings`; that error reason is dropped from the tool's contract. (#9)
24
+ - **`nonprofit_search`** — the 10,000-result cap caveat now reaches `structuredContent` via `ctx.enrich.notice`, not just the formatted text; also corrects "1 pages" pluralization and "0–0" range phrasing on a single-page past-the-end result. (#10)
25
+ - Tool descriptions and README no longer claim XML filing links — only the PDF link (`pdf_url`) is returned. (#7)