@cyanheads/nonprofit-explorer-mcp-server 0.1.10 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. package/.claude-plugin/plugin.json +33 -0
  2. package/.codex-plugin/mcp.json +9 -0
  3. package/.codex-plugin/plugin.json +25 -0
  4. package/AGENTS.md +14 -11
  5. package/CLAUDE.md +14 -11
  6. package/Dockerfile +5 -3
  7. package/README.md +22 -13
  8. package/changelog/0.2.x/0.2.0.md +31 -0
  9. package/changelog/0.3.x/0.3.0.md +35 -0
  10. package/dist/index.js +4 -7
  11. package/dist/index.js.map +1 -1
  12. package/dist/mcp-server/tools/definitions/nonprofit-get-filings.tool.d.ts +39 -3
  13. package/dist/mcp-server/tools/definitions/nonprofit-get-filings.tool.d.ts.map +1 -1
  14. package/dist/mcp-server/tools/definitions/nonprofit-get-filings.tool.js +243 -60
  15. package/dist/mcp-server/tools/definitions/nonprofit-get-filings.tool.js.map +1 -1
  16. package/dist/mcp-server/tools/definitions/nonprofit-get-organization.tool.d.ts +29 -2
  17. package/dist/mcp-server/tools/definitions/nonprofit-get-organization.tool.d.ts.map +1 -1
  18. package/dist/mcp-server/tools/definitions/nonprofit-get-organization.tool.js +129 -29
  19. package/dist/mcp-server/tools/definitions/nonprofit-get-organization.tool.js.map +1 -1
  20. package/dist/mcp-server/tools/definitions/{nonprofit-search.tool.d.ts → nonprofit-search-organizations.tool.d.ts} +20 -15
  21. package/dist/mcp-server/tools/definitions/nonprofit-search-organizations.tool.d.ts.map +1 -0
  22. package/dist/mcp-server/tools/definitions/{nonprofit-search.tool.js → nonprofit-search-organizations.tool.js} +62 -25
  23. package/dist/mcp-server/tools/definitions/nonprofit-search-organizations.tool.js.map +1 -0
  24. package/dist/services/nonprofit-explorer/filing-history.d.ts +10 -0
  25. package/dist/services/nonprofit-explorer/filing-history.d.ts.map +1 -0
  26. package/dist/services/nonprofit-explorer/filing-history.js +27 -0
  27. package/dist/services/nonprofit-explorer/filing-history.js.map +1 -0
  28. package/dist/services/nonprofit-explorer/filing-requirements.d.ts +15 -0
  29. package/dist/services/nonprofit-explorer/filing-requirements.d.ts.map +1 -0
  30. package/dist/services/nonprofit-explorer/filing-requirements.js +49 -0
  31. package/dist/services/nonprofit-explorer/filing-requirements.js.map +1 -0
  32. package/dist/services/nonprofit-explorer/nonprofit-explorer-service.d.ts +4 -4
  33. package/dist/services/nonprofit-explorer/nonprofit-explorer-service.d.ts.map +1 -1
  34. package/dist/services/nonprofit-explorer/nonprofit-explorer-service.js +109 -36
  35. package/dist/services/nonprofit-explorer/nonprofit-explorer-service.js.map +1 -1
  36. package/dist/services/nonprofit-explorer/types.d.ts +22 -0
  37. package/dist/services/nonprofit-explorer/types.d.ts.map +1 -1
  38. package/mcp.json +11 -0
  39. package/package.json +14 -9
  40. package/plugin.json +30 -0
  41. package/server.json +3 -3
  42. package/skills/nonprofit-explorer-guide/SKILL.md +45 -0
  43. package/dist/mcp-server/tools/definitions/nonprofit-search.tool.d.ts.map +0 -1
  44. package/dist/mcp-server/tools/definitions/nonprofit-search.tool.js.map +0 -1
@@ -0,0 +1,33 @@
1
+ {
2
+ "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
3
+ "name": "nonprofit-explorer-mcp-server",
4
+ "version": "0.3.0",
5
+ "description": "Search and explore 1.8M+ US nonprofits, fetch Form 990 financials, and access IRS filing history via MCP. STDIO or Streamable HTTP.",
6
+ "author": {
7
+ "name": "cyanheads",
8
+ "email": "casey@caseyjhand.com",
9
+ "url": "https://github.com/cyanheads"
10
+ },
11
+ "homepage": "https://github.com/cyanheads/nonprofit-explorer-mcp-server#readme",
12
+ "repository": "https://github.com/cyanheads/nonprofit-explorer-mcp-server",
13
+ "license": "Apache-2.0",
14
+ "keywords": [
15
+ "mcp",
16
+ "mcp-server",
17
+ "model-context-protocol",
18
+ "nonprofit",
19
+ "propublica",
20
+ "irs",
21
+ "form-990",
22
+ "tax-exempt"
23
+ ],
24
+ "mcpServers": {
25
+ "nonprofit-explorer-mcp-server": {
26
+ "command": "npx",
27
+ "args": ["-y", "@cyanheads/nonprofit-explorer-mcp-server"],
28
+ "env": {
29
+ "MCP_TRANSPORT_TYPE": "stdio"
30
+ }
31
+ }
32
+ }
33
+ }
@@ -0,0 +1,9 @@
1
+ {
2
+ "nonprofit-explorer-mcp-server": {
3
+ "command": "npx",
4
+ "args": ["-y", "@cyanheads/nonprofit-explorer-mcp-server"],
5
+ "env": {
6
+ "MCP_TRANSPORT_TYPE": "stdio"
7
+ }
8
+ }
9
+ }
@@ -0,0 +1,25 @@
1
+ {
2
+ "name": "nonprofit-explorer-mcp-server",
3
+ "version": "0.3.0",
4
+ "description": "Search and explore 1.8M+ US nonprofits, fetch Form 990 financials, and access IRS filing history via MCP. STDIO or Streamable HTTP.",
5
+ "author": {
6
+ "name": "cyanheads",
7
+ "email": "casey@caseyjhand.com",
8
+ "url": "https://github.com/cyanheads"
9
+ },
10
+ "homepage": "https://github.com/cyanheads/nonprofit-explorer-mcp-server#readme",
11
+ "repository": "https://github.com/cyanheads/nonprofit-explorer-mcp-server",
12
+ "license": "Apache-2.0",
13
+ "keywords": ["mcp", "mcp-server", "model-context-protocol", "nonprofit", "propublica", "irs", "form-990", "tax-exempt"],
14
+ "mcpServers": "./.codex-plugin/mcp.json",
15
+ "interface": {
16
+ "displayName": "nonprofit-explorer-mcp-server",
17
+ "shortDescription": "Search and explore 1.8M+ US nonprofits, fetch Form 990 financials, and access IRS filing history via MCP. STDIO or Streamable HTTP.",
18
+ "longDescription": "Search and explore 1.8M+ US nonprofits, fetch Form 990 financials, and access IRS filing history via MCP. STDIO or Streamable HTTP.",
19
+ "developerName": "cyanheads",
20
+ "category": "data",
21
+ "capabilities": ["Read"],
22
+ "websiteURL": "https://github.com/cyanheads/nonprofit-explorer-mcp-server",
23
+ "defaultPrompt": []
24
+ }
25
+ }
package/AGENTS.md CHANGED
@@ -1,11 +1,11 @@
1
1
  # Developer Protocol
2
2
 
3
3
  **Server:** nonprofit-explorer-mcp-server
4
- **Version:** 0.1.10
5
- **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.14`
4
+ **Version:** 0.3.0
5
+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.18`
6
6
  **Engines:** Bun ≥1.4.0, Node ≥24.0.0
7
- **MCP SDK:** `@modelcontextprotocol/server` ^2.2.0
8
- **Zod:** ^4.6.5
7
+ **MCP SDK:** `@modelcontextprotocol/server` ^2.4.0
8
+ **Zod:** ^4.6.7
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.
11
11
 
@@ -32,7 +32,7 @@ import { tool, z } from '@cyanheads/mcp-ts-core';
32
32
  import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
33
33
  import { getNonprofitExplorerService } from '@/services/nonprofit-explorer/nonprofit-explorer-service.js';
34
34
 
35
- export const nonprofitSearch = tool('nonprofit_search', {
35
+ export const nonprofitSearchOrganizations = tool('nonprofit_search_organizations', {
36
36
  title: 'Search Nonprofits',
37
37
  description: 'Search 1.8M+ IRS-recognized tax-exempt organizations by name, keyword, city, or phrase.',
38
38
  annotations: { readOnlyHint: true },
@@ -125,7 +125,7 @@ import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
125
125
  errors: [
126
126
  { reason: 'not_found', code: JsonRpcErrorCode.NotFound,
127
127
  when: 'EIN does not correspond to a known org',
128
- recovery: 'Verify the EIN with nonprofit_search. Use the integer EIN value.' },
128
+ recovery: 'Verify the EIN with nonprofit_search_organizations. Use the integer EIN value.' },
129
129
  ],
130
130
  async handler(input, ctx) {
131
131
  const org = await svc.getOrganization(normalizeEin(input.ein), ctx);
@@ -141,7 +141,7 @@ async handler(input, ctx) {
141
141
  ```ts
142
142
  import { notFound, serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
143
143
  throw notFound('Organization not found', { ein });
144
- throw serviceUnavailable('ProPublica API unavailable', { url }, { cause: err });
144
+ throw serviceUnavailable('ProPublica API unavailable', { reason: 'upstream_error' }, { cause: err });
145
145
  ```
146
146
 
147
147
  See framework CLAUDE.md and the `api-errors` skill for the full auto-classification table, all available factories, and the contract reference.
@@ -159,7 +159,7 @@ src/
159
159
  types.ts # Domain types (RawOrg, RawFiling, etc.)
160
160
  mcp-server/
161
161
  tools/definitions/
162
- nonprofit-search.tool.ts # nonprofit_search
162
+ nonprofit-search-organizations.tool.ts # nonprofit_search_organizations
163
163
  nonprofit-get-organization.tool.ts# nonprofit_get_organization
164
164
  nonprofit-get-filings.tool.ts # nonprofit_get_filings
165
165
  ```
@@ -170,8 +170,8 @@ src/
170
170
 
171
171
  | What | Convention | Example |
172
172
  |:-----|:-----------|:--------|
173
- | Files | kebab-case with suffix | `nonprofit-search.tool.ts` |
174
- | Tool/resource/prompt names | snake_case | `nonprofit_search` |
173
+ | Files | kebab-case with suffix | `nonprofit-search-organizations.tool.ts` |
174
+ | Tool/resource/prompt names | snake_case | `nonprofit_search_organizations` |
175
175
  | Directories | kebab-case | `src/services/nonprofit-explorer/` |
176
176
  | Descriptions | Single string or template literal, no `+` concatenation | `'Search orgs by name and filter.'` |
177
177
 
@@ -179,7 +179,7 @@ src/
179
179
 
180
180
  ## Skills
181
181
 
182
- Skills are modular instructions in `framework-skills/` at the project root. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. The directory is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, so a server that ships `.claude-plugin/` or `.codex-plugin/` would hand these development skills to every agent that installs it. Keep `skills/` free for skills meant for those agents.
182
+ Development instructions live in `framework-skills/`; read the matching skill when a task calls for it. `bun run list-skills` prints the registry. Root `skills/` is a separate, opt-in tree for agents using this server, authored deliberately with `add-skill`. Plugin installs and `.mcpb` bundles ship it as-is; npm and Docker carry it, and MCP serves it when `createApp({ skills: 'skills' })` is set. Maintenance never creates or copies the published tree; `lint:packaging` validates it.
183
183
 
184
184
  **Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `framework-skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
185
185
 
@@ -193,6 +193,7 @@ Available skills:
193
193
  | `add-app-tool` | Scaffold an MCP App tool + paired UI resource |
194
194
  | `add-resource` | Scaffold a new resource definition |
195
195
  | `add-prompt` | Scaffold a new prompt definition |
196
+ | `add-skill` | Author a skill the server publishes in root `skills/` for the agents that use it — when one earns its place, structure, validation, delivery |
196
197
  | `add-service` | Scaffold a new service integration |
197
198
  | `add-test` | Scaffold test file for a tool, resource, or service |
198
199
  | `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
@@ -258,6 +259,8 @@ When you complete a skill's checklist, check the boxes and add a completion time
258
259
 
259
260
  ## Bundling
260
261
 
262
+ Keep root-anchored exclusions in `.mcpbignore` for source, scripts, tests, docs, caches, logs, agent docs, plugin manifests, and local configuration. Root `skills/` ships deliberately. The cleaner also removes node-gyp generator output and framework build-only files. Its agent-doc selector must match only package-root documentation directories: SDK runtime paths such as `dist/ext/skills/` remain executable code. Keep that local selector fix in `scripts/clean-mcpb.ts` and `scripts/lint-packaging.ts` until the framework supplies it.
263
+
261
264
  `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 (`framework-skills/`, `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.
262
265
 
263
266
  **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, that every `user_config` option is wired into `mcp_config.env` as `"X": "${user_config.X}"` (the host substitutes nothing else — `"${X}"` reaches the server as that literal string), and that an optional string option carries `"default": ""`.
package/CLAUDE.md CHANGED
@@ -1,11 +1,11 @@
1
1
  # Developer Protocol
2
2
 
3
3
  **Server:** nonprofit-explorer-mcp-server
4
- **Version:** 0.1.10
5
- **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.14`
4
+ **Version:** 0.3.0
5
+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.18`
6
6
  **Engines:** Bun ≥1.4.0, Node ≥24.0.0
7
- **MCP SDK:** `@modelcontextprotocol/server` ^2.2.0
8
- **Zod:** ^4.6.5
7
+ **MCP SDK:** `@modelcontextprotocol/server` ^2.4.0
8
+ **Zod:** ^4.6.7
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.
11
11
 
@@ -32,7 +32,7 @@ import { tool, z } from '@cyanheads/mcp-ts-core';
32
32
  import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
33
33
  import { getNonprofitExplorerService } from '@/services/nonprofit-explorer/nonprofit-explorer-service.js';
34
34
 
35
- export const nonprofitSearch = tool('nonprofit_search', {
35
+ export const nonprofitSearchOrganizations = tool('nonprofit_search_organizations', {
36
36
  title: 'Search Nonprofits',
37
37
  description: 'Search 1.8M+ IRS-recognized tax-exempt organizations by name, keyword, city, or phrase.',
38
38
  annotations: { readOnlyHint: true },
@@ -125,7 +125,7 @@ import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
125
125
  errors: [
126
126
  { reason: 'not_found', code: JsonRpcErrorCode.NotFound,
127
127
  when: 'EIN does not correspond to a known org',
128
- recovery: 'Verify the EIN with nonprofit_search. Use the integer EIN value.' },
128
+ recovery: 'Verify the EIN with nonprofit_search_organizations. Use the integer EIN value.' },
129
129
  ],
130
130
  async handler(input, ctx) {
131
131
  const org = await svc.getOrganization(normalizeEin(input.ein), ctx);
@@ -141,7 +141,7 @@ async handler(input, ctx) {
141
141
  ```ts
142
142
  import { notFound, serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
143
143
  throw notFound('Organization not found', { ein });
144
- throw serviceUnavailable('ProPublica API unavailable', { url }, { cause: err });
144
+ throw serviceUnavailable('ProPublica API unavailable', { reason: 'upstream_error' }, { cause: err });
145
145
  ```
146
146
 
147
147
  See framework CLAUDE.md and the `api-errors` skill for the full auto-classification table, all available factories, and the contract reference.
@@ -159,7 +159,7 @@ src/
159
159
  types.ts # Domain types (RawOrg, RawFiling, etc.)
160
160
  mcp-server/
161
161
  tools/definitions/
162
- nonprofit-search.tool.ts # nonprofit_search
162
+ nonprofit-search-organizations.tool.ts # nonprofit_search_organizations
163
163
  nonprofit-get-organization.tool.ts# nonprofit_get_organization
164
164
  nonprofit-get-filings.tool.ts # nonprofit_get_filings
165
165
  ```
@@ -170,8 +170,8 @@ src/
170
170
 
171
171
  | What | Convention | Example |
172
172
  |:-----|:-----------|:--------|
173
- | Files | kebab-case with suffix | `nonprofit-search.tool.ts` |
174
- | Tool/resource/prompt names | snake_case | `nonprofit_search` |
173
+ | Files | kebab-case with suffix | `nonprofit-search-organizations.tool.ts` |
174
+ | Tool/resource/prompt names | snake_case | `nonprofit_search_organizations` |
175
175
  | Directories | kebab-case | `src/services/nonprofit-explorer/` |
176
176
  | Descriptions | Single string or template literal, no `+` concatenation | `'Search orgs by name and filter.'` |
177
177
 
@@ -179,7 +179,7 @@ src/
179
179
 
180
180
  ## Skills
181
181
 
182
- Skills are modular instructions in `framework-skills/` at the project root. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. The directory is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, so a server that ships `.claude-plugin/` or `.codex-plugin/` would hand these development skills to every agent that installs it. Keep `skills/` free for skills meant for those agents.
182
+ Development instructions live in `framework-skills/`; read the matching skill when a task calls for it. `bun run list-skills` prints the registry. Root `skills/` is a separate, opt-in tree for agents using this server, authored deliberately with `add-skill`. Plugin installs and `.mcpb` bundles ship it as-is; npm and Docker carry it, and MCP serves it when `createApp({ skills: 'skills' })` is set. Maintenance never creates or copies the published tree; `lint:packaging` validates it.
183
183
 
184
184
  **Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `framework-skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
185
185
 
@@ -193,6 +193,7 @@ Available skills:
193
193
  | `add-app-tool` | Scaffold an MCP App tool + paired UI resource |
194
194
  | `add-resource` | Scaffold a new resource definition |
195
195
  | `add-prompt` | Scaffold a new prompt definition |
196
+ | `add-skill` | Author a skill the server publishes in root `skills/` for the agents that use it — when one earns its place, structure, validation, delivery |
196
197
  | `add-service` | Scaffold a new service integration |
197
198
  | `add-test` | Scaffold test file for a tool, resource, or service |
198
199
  | `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
@@ -258,6 +259,8 @@ When you complete a skill's checklist, check the boxes and add a completion time
258
259
 
259
260
  ## Bundling
260
261
 
262
+ Keep root-anchored exclusions in `.mcpbignore` for source, scripts, tests, docs, caches, logs, agent docs, plugin manifests, and local configuration. Root `skills/` ships deliberately. The cleaner also removes node-gyp generator output and framework build-only files. Its agent-doc selector must match only package-root documentation directories: SDK runtime paths such as `dist/ext/skills/` remain executable code. Keep that local selector fix in `scripts/clean-mcpb.ts` and `scripts/lint-packaging.ts` until the framework supplies it.
263
+
261
264
  `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 (`framework-skills/`, `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.
262
265
 
263
266
  **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, that every `user_config` option is wired into `mcp_config.env` as `"X": "${user_config.X}"` (the host substitutes nothing else — `"${X}"` reaches the server as that literal string), and that an optional string option carries `"default": ""`.
package/Dockerfile CHANGED
@@ -14,7 +14,7 @@
14
14
  # output. A stage that compiles a native addon needs the target-arch toolchain
15
15
  # and cannot cross-compile this way — drop the flag there.
16
16
  # ==============================================================================
17
- FROM --platform=$BUILDPLATFORM oven/bun:1.4.2 AS build
17
+ FROM --platform=$BUILDPLATFORM oven/bun:1.4.4 AS build
18
18
 
19
19
  WORKDIR /usr/src/app
20
20
 
@@ -28,6 +28,7 @@ RUN --mount=type=cache,target=/root/.bun/install/cache \
28
28
 
29
29
  # Copy the rest of the source code
30
30
  COPY . .
31
+ RUN mkdir -p skills
31
32
 
32
33
  # Build the application
33
34
  RUN bun run build
@@ -46,7 +47,7 @@ RUN bun run build
46
47
  # A clean image rather than `FROM build`: the build stage's node_modules holds
47
48
  # devDependencies.
48
49
  # ==============================================================================
49
- FROM --platform=$BUILDPLATFORM oven/bun:1.4.2 AS deps
50
+ FROM --platform=$BUILDPLATFORM oven/bun:1.4.4 AS deps
50
51
 
51
52
  WORKDIR /usr/src/app
52
53
 
@@ -114,7 +115,7 @@ RUN rm -rf node_modules/@socketsecurity/bun-security-scanner
114
115
  # dependencies and build artifacts. Its only Bun invocations are HEALTHCHECK
115
116
  # and CMD, which run on the real target at container start.
116
117
  # ==============================================================================
117
- FROM oven/bun:1.4.2-slim AS production
118
+ FROM oven/bun:1.4.4-slim AS production
118
119
 
119
120
  WORKDIR /usr/src/app
120
121
 
@@ -136,6 +137,7 @@ COPY --from=deps /usr/src/app/node_modules ./node_modules
136
137
 
137
138
  # Copy the compiled application code from the build stage
138
139
  COPY --from=build /usr/src/app/dist ./dist
140
+ COPY --from=build /usr/src/app/skills ./skills
139
141
 
140
142
  # Mirror CLI (MirrorService adopters only — Tier 3, opt-in):
141
143
  # Copy your mirror lifecycle scripts and emit a runtime tsconfig so Bun resolves
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.10-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-^2.2.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.4.2-blueviolet.svg?style=flat-square)](https://bun.sh/)
10
+ [![Version](https://img.shields.io/badge/Version-0.3.0-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-^2.4.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.4.4-blueviolet.svg?style=flat-square)](https://bun.sh/)
11
11
 
12
12
  </div>
13
13
 
@@ -29,22 +29,23 @@
29
29
 
30
30
  ## Overview
31
31
 
32
- IRS Form 990 data for 1.8M+ tax-exempt organizations, via the ProPublica Nonprofit Explorer API. Search by name, fetch an org's financial snapshot, and pull its full filing history from any MCP client. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.
32
+ IRS Form 990 data for 1.8M+ tax-exempt organizations, via the ProPublica Nonprofit Explorer API. Search by name, fetch an org's financial snapshot, and pull its full filing history.
33
33
 
34
34
  ### Tools
35
35
 
36
36
  | Tool | Description |
37
37
  |:---|:---|
38
- | `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 |
39
- | `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 |
40
- | `nonprofit_get_filings` | All Form 990 filings for an org by EIN: year-by-year financials, revenue breakdown, executive compensation, and source PDF links |
38
+ | `nonprofit_search_organizations` | Search 1.8M+ IRS-recognized tax-exempt organizations by name, keyword, city, or phrase with optional state, NTEE sector, and 501(c) filters |
39
+ | `nonprofit_get_organization` | Full profile by EIN: legal identity, IRS classification, filing requirements, newest-return metadata, and latest extracted financial snapshot |
40
+ | `nonprofit_get_filings` | Form 990 history by EIN, optionally filtered by fiscal year: financials, fundraising figures, executive compensation, and source PDF links |
41
41
 
42
42
  ## Capability reference
43
43
 
44
- ### `nonprofit_search` <sub>tool</sub>
44
+ ### `nonprofit_search_organizations` <sub>tool</sub>
45
45
 
46
46
  - Full-text query — supports quoted phrases (`"Red Cross"`), required terms (`+evanston`), excluded terms (`-dental`)
47
- - Optional filters: US state/territory or military postal code (`ZZ` for foreign entities; a code outside that set is rejected rather than silently returning national results), NTEE major sector (1–10), 501(c) subsection code (`3` covers both public charities and private foundations — see `foundation_type` on `nonprofit_get_organization` to tell them apart)
47
+ - Optional filters: state/territory name or postal code (including military codes and `ZZ` for foreign entities), NTEE major sector (`1`–`10` or a case-insensitive major letter), and 501(c) subsection code (`3` covers both public charities and private foundations — see `foundation_type` on `nonprofit_get_organization` to tell them apart). Names and letters normalize to the upstream codes shown in `active_filters`; unrecognized states are rejected before a request
48
+ - `sub_name` is the upstream legal name with an optional secondary line; it can repeat `name` or be null
48
49
  - Paginated at 25 per page (`page`, zero-indexed); `num_pages`, `per_page`, and `page_offset` track position
49
50
  - API caps total results at 10,000 — `total_results === 10000` means the actual count may be higher, and a page whose offset reaches that ceiling is refused (`pagination_ceiling`)
50
51
  - Zero matches and a page past the last one both succeed with an empty `organizations` array and a `notice` explaining which case it is
@@ -54,21 +55,26 @@ IRS Form 990 data for 1.8M+ tax-exempt organizations, via the ProPublica Nonprof
54
55
 
55
56
  ### `nonprofit_get_organization` <sub>tool</sub>
56
57
 
57
- - Accepts EIN as integer (`530196605`) or string with or without hyphen (`"53-0196605"`); use `nonprofit_search` first if you only have an org name
58
+ - Accepts EIN as integer (`530196605`) or string with or without hyphen (`"53-0196605"`); use `nonprofit_search_organizations` first if you only have an org name
58
59
  - Returns legal identity, address, NTEE code, 501(c) type, and IRS ruling date
59
60
  - IRS Business Master File standing: deductibility (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
60
- - Financial snapshot from the most recent Form 990: revenue, expenses, assets, liabilities, net assets, plus the source PDF link
61
- - `filing_count` shows how many filings with extracted data are on record
61
+ - `latest_filing` is the latest extracted financial snapshot: revenue, expenses, assets, liabilities, net assets, and source PDF link. `latest_return` separately identifies the newest return across extracted and PDF-only histories; a newer return need not have extracted figures
62
+ - Filing requirements, private-foundation filing requirements, affiliation, and group exemption number come from the IRS Business Master File. Empty-history guidance uses these codes without claiming why a particular filing is absent
63
+ - `filing_count` counts filings with extracted data; `filing_count_pdf_only` separately counts PDFs without financial extracts. Use `nonprofit_get_filings` for those links; PDF-only histories have no financial snapshot
62
64
  - Data lags 1–2 years — `tax_prd_yr` in the snapshot is the fiscal year of the filing, not the current year
63
65
 
64
66
  ---
65
67
 
66
68
  ### `nonprofit_get_filings` <sub>tool</sub>
67
69
 
68
- - All Form 990 filings with extracted data, sorted newest first — per filing: revenue, expenses, assets, liabilities, net assets, revenue breakdown (contributions, program service, investment income), and the source PDF link
70
+ - All Form 990 filings with extracted data, sorted by full tax period newest first — per filing: revenue, expenses, assets, liabilities, net assets, revenue breakdown (contributions, program service, investment income), and the source PDF link
71
+ - Optional inclusive `from_year` / `to_year` bounds apply to both extracted and PDF-only histories. Totals remain unfiltered; an empty selected interval does not mean the organization has no history
72
+ - Financial fields follow each return's form type. For 990-PF, investment income is savings interest plus dividends and securities interest (Part I column (a), lines 3–4); both components must be extracted. It excludes capital gains, rents, and net investment income
73
+ - 990-PF filings include `grants_paid`, `distributable_amount`, `fair_market_value_assets`, and `net_investment_income`. The distributable amount is a payout requirement, not actual payments or a compliance measure
69
74
  - `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
70
- - Executive compensation summary with field-name transparency and a note pointing to Schedule J for per-officer detail
71
- - `filings_pdf_only` lists older filings with a PDF but no extracted data
75
+ - Form 990 includes other salaries and wages, payroll taxes, professional fundraising fees, and fundraising event gross, direct expenses, and net income. For 990-EZ, event gross is separate from combined gaming/fundraising expenses and net income; the combined figures cannot establish event-only results
76
+ - Executive compensation includes the source field for 990 and 990-PF. The 990-EZ extract has no compensation source: amount and field name are null, with guidance to Part IV of the PDF
77
+ - `filings_pdf_only` retains fiscal years and tax periods for returns without extracted data, including returns newer than the financial snapshots
72
78
  - An EIN that resolves to a real org with no 990 on record returns an empty `filings` array plus a `notice`, not an error
73
79
  - Data lags 1–2 years — always cite `tax_prd_yr` (fiscal year) when presenting figures
74
80
 
@@ -91,6 +97,8 @@ Agent-friendly output:
91
97
  - 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
92
98
  - Field-name transparency on compensation — `field_name` and `form_type` exposed so agents know exactly which IRS field was read
93
99
 
100
+ The published [nonprofit-explorer-guide](./skills/nonprofit-explorer-guide/SKILL.md) covers diligence, financial comparisons, and when to inspect the source return. It is included in npm, Docker, and desktop bundles and served through MCP skill resources.
101
+
94
102
  ## Getting started
95
103
 
96
104
  ### Public Hosted Instance
@@ -265,6 +273,7 @@ The Dockerfile defaults to HTTP transport, stateless session mode, and logs to `
265
273
  | `src/index.ts` | `createApp()` entry point — registers tools and inits the service. |
266
274
  | `src/mcp-server/tools` | Tool definitions (`*.tool.ts`). Three tools for search and financial data. |
267
275
  | `src/services/nonprofit-explorer` | ProPublica Nonprofit Explorer API client and domain types. |
276
+ | `skills/` | Published agent guidance for diligence and financial interpretation. |
268
277
  | `tests/` | Unit and integration tests mirroring `src/`. |
269
278
 
270
279
  ## Development guide
@@ -0,0 +1,31 @@
1
+ ---
2
+ summary: "Form-aware nonprofit financials and separate PDF-only filing counts."
3
+ breaking: true
4
+ security: false
5
+ ---
6
+
7
+ # 0.2.0 — 2026-10-21
8
+
9
+ ## Added
10
+
11
+ - **990-PF financials:** expose `grants_paid`, `distributable_amount`, `fair_market_value_assets`, and `net_investment_income`; the distributable amount is a payout requirement, not actual payments or a compliance measure ([#19](https://github.com/cyanheads/nonprofit-explorer-mcp-server/issues/19)).
12
+ - **`filing_count_pdf_only`:** count PDFs separately from extracted filings and direct PDF-only profiles to filing links without inferring a financial snapshot ([#21](https://github.com/cyanheads/nonprofit-explorer-mcp-server/issues/21)).
13
+
14
+ ## Changed
15
+
16
+ - **Search tool:** Rename `nonprofit_search` to `nonprofit_search_organizations`; update callers to use the new name ([#16](https://github.com/cyanheads/nonprofit-explorer-mcp-server/issues/16)).
17
+ - **Development guidance:** synchronize framework references and release procedures; use Bun 1.4.2 → 1.4.3 for development and container images.
18
+
19
+ ## Fixed
20
+
21
+ - **Form-specific financials:** select 990, 990-EZ, and 990-PF source fields per filing; preserve reported zero and missing values. PF investment income requires both savings-interest and dividend components ([#18](https://github.com/cyanheads/nonprofit-explorer-mcp-server/issues/18)).
22
+ - **Service failures:** omit request URLs from service error data and debug metadata; keep network exceptions as internal causes behind a stable public message ([#14](https://github.com/cyanheads/nonprofit-explorer-mcp-server/issues/14)).
23
+ - **Cancellation and timeouts:** preserve caller cancellation, distinguish attempt expiry from upstream failures, and enforce the derived 64,375 ms total retry deadline with post-read abort checks ([#20](https://github.com/cyanheads/nonprofit-explorer-mcp-server/issues/20)).
24
+
25
+ ## Dependencies
26
+
27
+ - `@cyanheads/mcp-ts-core` ^0.13.14 → ^0.13.15.
28
+ - `zod` ^4.6.5 → ^4.6.7.
29
+ - `@types/node` ^26.6.4 → ^26.6.5.
30
+ - `tsc-alias` ^1.9.7 → ^1.9.8.
31
+ - `vitest` ^5.0.3 → ^5.0.5.
@@ -0,0 +1,35 @@
1
+ ---
2
+ summary: "Distinguish filing coverage and form-specific financials for nonprofit diligence."
3
+ breaking: true
4
+ security: false
5
+ ---
6
+
7
+ # 0.3.0 — 2026-11-03
8
+
9
+ ## Added
10
+
11
+ - **`latest_return`** identifies the newest return across extracted and PDF-only histories; PDF-only output retains full tax periods ([#23](https://github.com/cyanheads/nonprofit-explorer-mcp-server/issues/23)).
12
+ - **BMF filing requirements, affiliation, and group exemption number** contextualize missing history without inferring its cause ([#25](https://github.com/cyanheads/nonprofit-explorer-mcp-server/issues/25)).
13
+ - **`from_year` / `to_year`** select inclusive fiscal-year windows across both filing collections while retaining unfiltered totals ([#26](https://github.com/cyanheads/nonprofit-explorer-mcp-server/issues/26)).
14
+ - **Fundraising and Part IX figures** expose eight nullable financial fields, keeping 990 event amounts distinct from 990-EZ combined gaming/fundraising amounts ([#27](https://github.com/cyanheads/nonprofit-explorer-mcp-server/issues/27)).
15
+ - **`nonprofit-explorer-guide`** supplies diligence and comparison gates through plugins, npm, Docker, desktop bundles, and MCP skill resources.
16
+
17
+ ## Changed
18
+
19
+ - **Search filters** accept state/territory names and case-insensitive NTEE major letters, normalized to upstream codes; secondary-name descriptions reflect repeated legal names ([#28](https://github.com/cyanheads/nonprofit-explorer-mcp-server/issues/28)).
20
+ - **Filing rendering** groups invariant notes by form and preserves every field's null meaning; upstream strings and source links retain their values through CommonMark rendering.
21
+ - **Packaging and development tooling** support Agent Plugins root manifests and published skills; desktop bundles exclude authoring/build files while retaining SDK skill runtime modules.
22
+
23
+ ## Fixed
24
+
25
+ - **`executive_compensation.field_name`** is nullable for 990-EZ, whose extract has no compensation source; its amount stays null and guidance points to Part IV ([#24](https://github.com/cyanheads/nonprofit-explorer-mcp-server/issues/24)).
26
+ - **`latest_filing`** is labeled as the latest extracted snapshot, and both filing histories sort by full tax period without discarding ties or implying amendment precedence.
27
+
28
+ ## Dependencies
29
+
30
+ - `@cyanheads/mcp-ts-core` ^0.13.15 → ^0.13.18.
31
+ - `@biomejs/biome` ^2.5.15 → ^2.6.4.
32
+ - `@types/node` ^26.6.5 → ^26.6.6.
33
+ - `ignore` ^7.0.12 → ^7.0.14.
34
+ - `tsc-alias` ^1.9.8 → ^1.9.10.
35
+ - Bun package manager and Docker images 1.4.3 → 1.4.4.
package/dist/index.js CHANGED
@@ -6,14 +6,15 @@
6
6
  import { createApp } from '@cyanheads/mcp-ts-core';
7
7
  import { nonprofitGetFilings } from './mcp-server/tools/definitions/nonprofit-get-filings.tool.js';
8
8
  import { nonprofitGetOrganization } from './mcp-server/tools/definitions/nonprofit-get-organization.tool.js';
9
- import { nonprofitSearch } from './mcp-server/tools/definitions/nonprofit-search.tool.js';
9
+ import { nonprofitSearchOrganizations } from './mcp-server/tools/definitions/nonprofit-search-organizations.tool.js';
10
10
  import { initNonprofitExplorerService } from './services/nonprofit-explorer/nonprofit-explorer-service.js';
11
11
  await createApp({
12
12
  name: 'nonprofit-explorer-mcp-server',
13
13
  title: 'nonprofit-explorer-mcp-server',
14
- tools: [nonprofitSearch, nonprofitGetOrganization, nonprofitGetFilings],
14
+ tools: [nonprofitSearchOrganizations, nonprofitGetOrganization, nonprofitGetFilings],
15
15
  resources: [],
16
16
  prompts: [],
17
+ skills: 'skills',
17
18
  /**
18
19
  * The tool list is fixed at build time — three unconditional registrations, no
19
20
  * feature gate, no auth scope, nothing that emits `toolsChanged` — so every
@@ -32,10 +33,6 @@ await createApp({
32
33
  setup(core) {
33
34
  initNonprofitExplorerService(core.config, core.storage);
34
35
  },
35
- instructions: 'ProPublica Nonprofit Explorer — keyless read-only access to IRS Form 990 data on 1.8M+ tax-exempt organizations.\n' +
36
- '- Start with nonprofit_search to find an org by name and get its EIN\n' +
37
- '- Use nonprofit_get_organization for the full profile and latest financial snapshot\n' +
38
- '- Use nonprofit_get_filings for year-by-year 990 data, executive comp, and source PDF links\n' +
39
- '- Data lags 1–2 years; always cite the fiscal year (tax_prd_yr) when presenting financial figures',
36
+ instructions: 'ProPublica Nonprofit Explorer provides keyless read-only access to IRS Form 990 data on 1.8M+ tax-exempt organizations. Resolve names to EINs with nonprofit_search_organizations; use nonprofit_get_organization for the profile, latest extracted financial snapshot, and newest-return metadata, then nonprofit_get_filings for financial history and source PDF links. The newest return may be PDF-only and newer than the extracted snapshot. Filings can be selected with inclusive fiscal-year bounds; omitted bounds return the full history. Data typically lags 1–2 years: cite tax_prd_yr and distinguish the tax period from the filing date.',
40
37
  });
41
38
  //# sourceMappingURL=index.js.map
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,8DAA8D,CAAC;AACnG,OAAO,EAAE,wBAAwB,EAAE,MAAM,mEAAmE,CAAC;AAC7G,OAAO,EAAE,eAAe,EAAE,MAAM,yDAAyD,CAAC;AAC1F,OAAO,EAAE,4BAA4B,EAAE,MAAM,6DAA6D,CAAC;AAE3G,MAAM,SAAS,CAAC;IACd,IAAI,EAAE,+BAA+B;IACrC,KAAK,EAAE,+BAA+B;IACtC,KAAK,EAAE,CAAC,eAAe,EAAE,wBAAwB,EAAE,mBAAmB,CAAC;IACvE,SAAS,EAAE,EAAE;IACb,OAAO,EAAE,EAAE;IACX;;;;;;OAMG;IACH,UAAU,EAAE,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,EAAE;IACxE;;;;;OAKG;IACH,WAAW,EAAE,WAAW;IACxB,KAAK,CAAC,IAAI;QACR,4BAA4B,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAC1D,CAAC;IACD,YAAY,EACV,oHAAoH;QACpH,wEAAwE;QACxE,uFAAuF;QACvF,+FAA+F;QAC/F,mGAAmG;CACtG,CAAC,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,8DAA8D,CAAC;AACnG,OAAO,EAAE,wBAAwB,EAAE,MAAM,mEAAmE,CAAC;AAC7G,OAAO,EAAE,4BAA4B,EAAE,MAAM,uEAAuE,CAAC;AACrH,OAAO,EAAE,4BAA4B,EAAE,MAAM,6DAA6D,CAAC;AAE3G,MAAM,SAAS,CAAC;IACd,IAAI,EAAE,+BAA+B;IACrC,KAAK,EAAE,+BAA+B;IACtC,KAAK,EAAE,CAAC,4BAA4B,EAAE,wBAAwB,EAAE,mBAAmB,CAAC;IACpF,SAAS,EAAE,EAAE;IACb,OAAO,EAAE,EAAE;IACX,MAAM,EAAE,QAAQ;IAChB;;;;;;OAMG;IACH,UAAU,EAAE,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,EAAE;IACxE;;;;;OAKG;IACH,WAAW,EAAE,WAAW;IACxB,KAAK,CAAC,IAAI;QACR,4BAA4B,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAC1D,CAAC;IACD,YAAY,EACV,4nBAA4nB;CAC/nB,CAAC,CAAC"}
@@ -6,9 +6,13 @@ import { z } from '@cyanheads/mcp-ts-core';
6
6
  import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
7
7
  export declare const nonprofitGetFilings: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
8
8
  ein: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
9
+ from_year: z.ZodOptional<z.ZodNumber>;
10
+ to_year: z.ZodOptional<z.ZodNumber>;
9
11
  }, z.core.$strip>, z.ZodObject<{
10
12
  ein: z.ZodNumber;
11
13
  name: z.ZodString;
14
+ from_year: z.ZodNullable<z.ZodNumber>;
15
+ to_year: z.ZodNullable<z.ZodNumber>;
12
16
  filings: z.ZodArray<z.ZodObject<{
13
17
  tax_prd_yr: z.ZodNumber;
14
18
  tax_prd: z.ZodNumber;
@@ -27,6 +31,18 @@ export declare const nonprofitGetFilings: import("@cyanheads/mcp-ts-core").ToolD
27
31
  contributions_and_grants: z.ZodNullable<z.ZodNumber>;
28
32
  program_service_revenue: z.ZodNullable<z.ZodNumber>;
29
33
  investment_income: z.ZodNullable<z.ZodNumber>;
34
+ other_salaries_and_wages: z.ZodNullable<z.ZodNumber>;
35
+ payroll_taxes: z.ZodNullable<z.ZodNumber>;
36
+ professional_fundraising_fees: z.ZodNullable<z.ZodNumber>;
37
+ fundraising_events_gross: z.ZodNullable<z.ZodNumber>;
38
+ fundraising_events_direct_expenses: z.ZodNullable<z.ZodNumber>;
39
+ fundraising_events_net: z.ZodNullable<z.ZodNumber>;
40
+ gaming_and_fundraising_direct_expenses: z.ZodNullable<z.ZodNumber>;
41
+ gaming_and_fundraising_net: z.ZodNullable<z.ZodNumber>;
42
+ grants_paid: z.ZodNullable<z.ZodNumber>;
43
+ distributable_amount: z.ZodNullable<z.ZodNumber>;
44
+ fair_market_value_assets: z.ZodNullable<z.ZodNumber>;
45
+ net_investment_income: z.ZodNullable<z.ZodNumber>;
30
46
  program_expense_ratio: z.ZodNullable<z.ZodObject<{
31
47
  ratio: z.ZodNullable<z.ZodNumber>;
32
48
  program_expenses: z.ZodNullable<z.ZodNumber>;
@@ -38,10 +54,10 @@ export declare const nonprofitGetFilings: import("@cyanheads/mcp-ts-core").ToolD
38
54
  }, z.core.$strip>>;
39
55
  executive_compensation: z.ZodObject<{
40
56
  amount: z.ZodNullable<z.ZodNumber>;
41
- field_name: z.ZodEnum<{
57
+ field_name: z.ZodNullable<z.ZodEnum<{
42
58
  compnsatncurrofcr: "compnsatncurrofcr";
43
59
  compofficers: "compofficers";
44
- }>;
60
+ }>>;
45
61
  form_type: z.ZodEnum<{
46
62
  990: "990";
47
63
  "990-EZ": "990-EZ";
@@ -52,6 +68,7 @@ export declare const nonprofitGetFilings: import("@cyanheads/mcp-ts-core").ToolD
52
68
  }, z.core.$strip>>;
53
69
  filings_pdf_only: z.ZodArray<z.ZodObject<{
54
70
  tax_prd_yr: z.ZodNumber;
71
+ tax_prd: z.ZodNullable<z.ZodNumber>;
55
72
  form_type_str: z.ZodString;
56
73
  pdf_url: z.ZodNullable<z.ZodString>;
57
74
  }, z.core.$strip>>;
@@ -60,11 +77,30 @@ export declare const nonprofitGetFilings: import("@cyanheads/mcp-ts-core").ToolD
60
77
  data_source: z.ZodString;
61
78
  propublica_url: z.ZodString;
62
79
  }, z.core.$strip>, readonly [{
80
+ readonly reason: "invalid_year_range";
81
+ readonly code: JsonRpcErrorCode.InvalidParams;
82
+ readonly when: "from_year is greater than to_year";
83
+ readonly recovery: "Set from_year less than or equal to to_year, or omit either bound.";
84
+ }, {
85
+ readonly reason: "timeout";
86
+ readonly code: JsonRpcErrorCode.Timeout;
87
+ readonly thrownBy: "service";
88
+ readonly when: "A ProPublica API attempt expires before its response body finishes";
89
+ readonly retryable: true;
90
+ readonly recovery: "Wait a moment and retry the request.";
91
+ }, {
92
+ readonly reason: "retry_deadline_exceeded";
93
+ readonly code: JsonRpcErrorCode.Timeout;
94
+ readonly thrownBy: "service";
95
+ readonly when: "The complete ProPublica API retry exchange exceeds its deadline";
96
+ readonly retryable: true;
97
+ readonly recovery: "Wait a moment and retry the request.";
98
+ }, {
63
99
  readonly reason: "not_found";
64
100
  readonly code: JsonRpcErrorCode.NotFound;
65
101
  readonly thrownBy: "service";
66
102
  readonly when: "The EIN does not correspond to a known organization in the Nonprofit Explorer database";
67
- readonly recovery: "Verify the EIN with nonprofit_search. Use the integer EIN value (leading zeros stripped).";
103
+ readonly recovery: "Verify the EIN with nonprofit_search_organizations. Use the integer EIN value (leading zeros stripped).";
68
104
  }, {
69
105
  readonly reason: "upstream_error";
70
106
  readonly code: JsonRpcErrorCode.ServiceUnavailable;
@@ -1 +1 @@
1
- {"version":3,"file":"nonprofit-get-filings.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/nonprofit-get-filings.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AA6DjE,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAoY9B,CAAC"}
1
+ {"version":3,"file":"nonprofit-get-filings.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/nonprofit-get-filings.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAuEjE,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAwnB9B,CAAC"}