@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.
- package/AGENTS.md +34 -18
- package/CLAUDE.md +34 -18
- package/Dockerfile +17 -8
- package/LICENSE +1 -1
- package/README.md +15 -12
- package/changelog/0.1.x/0.1.5.md +40 -0
- package/changelog/0.1.x/0.1.6.md +25 -0
- package/changelog/template.md +60 -19
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/mcp-server/tools/definitions/nonprofit-get-filings.tool.d.ts +4 -7
- package/dist/mcp-server/tools/definitions/nonprofit-get-filings.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/nonprofit-get-filings.tool.js +86 -114
- package/dist/mcp-server/tools/definitions/nonprofit-get-filings.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/nonprofit-get-organization.tool.d.ts +4 -0
- package/dist/mcp-server/tools/definitions/nonprofit-get-organization.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/nonprofit-get-organization.tool.js +110 -44
- package/dist/mcp-server/tools/definitions/nonprofit-get-organization.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/nonprofit-search.tool.d.ts +24 -14
- package/dist/mcp-server/tools/definitions/nonprofit-search.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/nonprofit-search.tool.js +114 -37
- package/dist/mcp-server/tools/definitions/nonprofit-search.tool.js.map +1 -1
- package/dist/services/nonprofit-explorer/nonprofit-explorer-service.d.ts +12 -0
- package/dist/services/nonprofit-explorer/nonprofit-explorer-service.d.ts.map +1 -1
- package/dist/services/nonprofit-explorer/nonprofit-explorer-service.js +83 -32
- package/dist/services/nonprofit-explorer/nonprofit-explorer-service.js.map +1 -1
- package/dist/services/nonprofit-explorer/types.d.ts +29 -2
- package/dist/services/nonprofit-explorer/types.d.ts.map +1 -1
- package/package.json +12 -11
- 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.
|
|
5
|
-
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.
|
|
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.
|
|
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: '
|
|
53
|
-
code: JsonRpcErrorCode.
|
|
54
|
-
when: '
|
|
55
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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` |
|
|
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 (`
|
|
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
|
|
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.
|
|
5
|
-
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.
|
|
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.
|
|
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: '
|
|
53
|
-
code: JsonRpcErrorCode.
|
|
54
|
-
when: '
|
|
55
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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` |
|
|
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 (`
|
|
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
|
|
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
|
-
|
|
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="
|
|
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
|
-
|
|
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
|
|
59
|
-
|
|
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
|
|
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
|
-
[](./CHANGELOG.md) [](./LICENSE) [](https://github.com/users/cyanheads/packages/container/package/nonprofit-explorer-mcp-server) [](https://modelcontextprotocol.io/) [](https://www.npmjs.com/package/@cyanheads/nonprofit-explorer-mcp-server) [](https://www.typescriptlang.org/) [](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,
|
|
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,
|
|
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
|
|
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
|
|
49
|
-
- Paginated at 25 per page; use `page` (zero-indexed)
|
|
50
|
-
-
|
|
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
|
-
-
|
|
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
|
|
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
|
|
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
|
-
-
|
|
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.
|
|
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)
|