@cyanheads/nonprofit-explorer-mcp-server 0.1.1
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 +285 -0
- package/CLAUDE.md +285 -0
- package/Dockerfile +99 -0
- package/LICENSE +201 -0
- package/README.md +279 -0
- package/changelog/0.1.x/0.1.0.md +11 -0
- package/changelog/0.1.x/0.1.1.md +23 -0
- package/changelog/template.md +127 -0
- package/dist/index.d.ts +7 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +24 -0
- package/dist/index.js.map +1 -0
- package/dist/mcp-server/tools/definitions/nonprofit-get-filings.tool.d.ts +72 -0
- package/dist/mcp-server/tools/definitions/nonprofit-get-filings.tool.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/nonprofit-get-filings.tool.js +391 -0
- package/dist/mcp-server/tools/definitions/nonprofit-get-filings.tool.js.map +1 -0
- package/dist/mcp-server/tools/definitions/nonprofit-get-organization.tool.d.ts +53 -0
- package/dist/mcp-server/tools/definitions/nonprofit-get-organization.tool.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/nonprofit-get-organization.tool.js +245 -0
- package/dist/mcp-server/tools/definitions/nonprofit-get-organization.tool.js.map +1 -0
- package/dist/mcp-server/tools/definitions/nonprofit-search.tool.d.ts +85 -0
- package/dist/mcp-server/tools/definitions/nonprofit-search.tool.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/nonprofit-search.tool.js +216 -0
- package/dist/mcp-server/tools/definitions/nonprofit-search.tool.js.map +1 -0
- package/dist/services/nonprofit-explorer/nonprofit-explorer-service.d.ts +37 -0
- package/dist/services/nonprofit-explorer/nonprofit-explorer-service.d.ts.map +1 -0
- package/dist/services/nonprofit-explorer/nonprofit-explorer-service.js +171 -0
- package/dist/services/nonprofit-explorer/nonprofit-explorer-service.js.map +1 -0
- package/dist/services/nonprofit-explorer/types.d.ts +89 -0
- package/dist/services/nonprofit-explorer/types.d.ts.map +1 -0
- package/dist/services/nonprofit-explorer/types.js +6 -0
- package/dist/services/nonprofit-explorer/types.js.map +1 -0
- package/package.json +101 -0
- package/server.json +105 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
Apache License
|
|
2
|
+
Version 2.0, January 2004
|
|
3
|
+
http://www.apache.org/licenses/
|
|
4
|
+
|
|
5
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
6
|
+
|
|
7
|
+
1. Definitions.
|
|
8
|
+
|
|
9
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
10
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
11
|
+
|
|
12
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
13
|
+
the copyright owner that is granting the License.
|
|
14
|
+
|
|
15
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
16
|
+
other entities that control, are controlled by, or are under common
|
|
17
|
+
control with that entity. For the purposes of this definition,
|
|
18
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
19
|
+
direction or management of such entity, whether by contract or
|
|
20
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
21
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
22
|
+
|
|
23
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
24
|
+
exercising permissions granted by this License.
|
|
25
|
+
|
|
26
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
27
|
+
including but not limited to software source code, documentation
|
|
28
|
+
source, and configuration files.
|
|
29
|
+
|
|
30
|
+
"Object" form shall mean any form resulting from mechanical
|
|
31
|
+
transformation or translation of a Source form, including but
|
|
32
|
+
not limited to compiled object code, generated documentation,
|
|
33
|
+
and conversions to other media types.
|
|
34
|
+
|
|
35
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
36
|
+
Object form, made available under the License, as indicated by a
|
|
37
|
+
copyright notice that is included in or attached to the work
|
|
38
|
+
(an example is provided in the Appendix below).
|
|
39
|
+
|
|
40
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
41
|
+
form, that is based on (or derived from) the Work and for which the
|
|
42
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
43
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
44
|
+
of this License, Derivative Works shall not include works that remain
|
|
45
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
46
|
+
the Work and Derivative Works thereof.
|
|
47
|
+
|
|
48
|
+
"Contribution" shall mean any work of authorship, including
|
|
49
|
+
the original version of the Work and any modifications or additions
|
|
50
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
51
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
|
52
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
53
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
54
|
+
means any form of electronic, verbal, or written communication sent
|
|
55
|
+
to the Licensor or its representatives, including but not limited to
|
|
56
|
+
communication on electronic mailing lists, source code control systems,
|
|
57
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
58
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
59
|
+
excluding communication that is conspicuously marked or otherwise
|
|
60
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
61
|
+
|
|
62
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
63
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
64
|
+
subsequently incorporated within the Work.
|
|
65
|
+
|
|
66
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
67
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
68
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
69
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
70
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
71
|
+
Work and such Derivative Works in Source or Object form.
|
|
72
|
+
|
|
73
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
74
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
75
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
76
|
+
(except as stated in this section) patent license to make, have made,
|
|
77
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
78
|
+
where such license applies only to those patent claims licensable
|
|
79
|
+
by such Contributor that are necessarily infringed by their
|
|
80
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
81
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
82
|
+
institute patent litigation against any entity (including a
|
|
83
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
84
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
85
|
+
or contributory patent infringement, then any patent licenses
|
|
86
|
+
granted to You under this License for that Work shall terminate
|
|
87
|
+
as of the date such litigation is filed.
|
|
88
|
+
|
|
89
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
90
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
91
|
+
modifications, and in Source or Object form, provided that You
|
|
92
|
+
meet the following conditions:
|
|
93
|
+
|
|
94
|
+
(a) You must give any other recipients of the Work or
|
|
95
|
+
Derivative Works a copy of this License; and
|
|
96
|
+
|
|
97
|
+
(b) You must cause any modified files to carry prominent notices
|
|
98
|
+
stating that You changed the files; and
|
|
99
|
+
|
|
100
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
101
|
+
that You distribute, all copyright, patent, trademark, and
|
|
102
|
+
attribution notices from the Source form of the Work,
|
|
103
|
+
excluding those notices that do not pertain to any part of
|
|
104
|
+
the Derivative Works; and
|
|
105
|
+
|
|
106
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
107
|
+
distribution, then any Derivative Works that You distribute must
|
|
108
|
+
include a readable copy of the attribution notices contained
|
|
109
|
+
within such NOTICE file, excluding those notices that do not
|
|
110
|
+
pertain to any part of the Derivative Works, in at least one
|
|
111
|
+
of the following places: within a NOTICE text file distributed
|
|
112
|
+
as part of the Derivative Works; within the Source form or
|
|
113
|
+
documentation, if provided along with the Derivative Works; or,
|
|
114
|
+
within a display generated by the Derivative Works, if and
|
|
115
|
+
wherever such third-party notices normally appear. The contents
|
|
116
|
+
of the NOTICE file are for informational purposes only and
|
|
117
|
+
do not modify the License. You may add Your own attribution
|
|
118
|
+
notices within Derivative Works that You distribute, alongside
|
|
119
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
120
|
+
that such additional attribution notices cannot be construed
|
|
121
|
+
as modifying the License.
|
|
122
|
+
|
|
123
|
+
You may add Your own copyright statement to Your modifications and
|
|
124
|
+
may provide additional or different license terms and conditions
|
|
125
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
126
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
127
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
128
|
+
the conditions stated in this License.
|
|
129
|
+
|
|
130
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
131
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
132
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
133
|
+
this License, without any additional terms or conditions.
|
|
134
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
135
|
+
the terms of any separate license agreement you may have executed
|
|
136
|
+
with Licensor regarding such Contributions.
|
|
137
|
+
|
|
138
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
139
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
140
|
+
except as required for reasonable and customary use in describing the
|
|
141
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
142
|
+
|
|
143
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
144
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
145
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
146
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
147
|
+
implied, including, without limitation, any warranties or conditions
|
|
148
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
149
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
150
|
+
appropriateness of using or redistributing the Work and assume any
|
|
151
|
+
risks associated with Your exercise of permissions under this License.
|
|
152
|
+
|
|
153
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
154
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
155
|
+
unless required by applicable law (such as deliberate and grossly
|
|
156
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
157
|
+
liable to You for damages, including any direct, indirect, special,
|
|
158
|
+
incidental, or consequential damages of any character arising as a
|
|
159
|
+
result of this License or out of the use or inability to use the
|
|
160
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
161
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
162
|
+
other commercial damages or losses), even if such Contributor
|
|
163
|
+
has been advised of the possibility of such damages.
|
|
164
|
+
|
|
165
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
166
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
167
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
168
|
+
or other liability obligations and/or rights consistent with this
|
|
169
|
+
License. However, in accepting such obligations, You may act only
|
|
170
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
171
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
172
|
+
defend, and hold each Contributor harmless for any liability
|
|
173
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
174
|
+
of your accepting any such warranty or additional liability.
|
|
175
|
+
|
|
176
|
+
END OF TERMS AND CONDITIONS
|
|
177
|
+
|
|
178
|
+
APPENDIX: How to apply the Apache License to your work.
|
|
179
|
+
|
|
180
|
+
To apply the Apache License to your work, attach the following
|
|
181
|
+
boilerplate notice, with the fields enclosed by brackets "[]"
|
|
182
|
+
replaced with your own identifying information. (Don't include
|
|
183
|
+
the brackets!) The text should be enclosed in the appropriate
|
|
184
|
+
comment syntax for the file format. We also recommend that a
|
|
185
|
+
file or class name and description of purpose be included on the
|
|
186
|
+
same "printed page" as the copyright notice for easier
|
|
187
|
+
identification within third-party archives.
|
|
188
|
+
|
|
189
|
+
Copyright 2025 Casey Hand @cyanheads
|
|
190
|
+
|
|
191
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
192
|
+
you may not use this file except in compliance with the License.
|
|
193
|
+
You may obtain a copy of the License at
|
|
194
|
+
|
|
195
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
196
|
+
|
|
197
|
+
Unless required by applicable law or agreed to in writing, software
|
|
198
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
199
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
200
|
+
See the License for the specific language governing permissions and
|
|
201
|
+
limitations under the License.
|
package/README.md
ADDED
|
@@ -0,0 +1,279 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
<h1>@cyanheads/nonprofit-explorer-mcp-server</h1>
|
|
3
|
+
<p><b>Search and explore 1.8M+ US nonprofits, fetch Form 990 financials, and access IRS filing history via MCP. STDIO or Streamable HTTP.</b>
|
|
4
|
+
<div>3 Tools</div>
|
|
5
|
+
</p>
|
|
6
|
+
</div>
|
|
7
|
+
|
|
8
|
+
<div align="center">
|
|
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
|
+
|
|
12
|
+
</div>
|
|
13
|
+
|
|
14
|
+
<div align="center">
|
|
15
|
+
|
|
16
|
+
[](https://github.com/cyanheads/nonprofit-explorer-mcp-server/releases/latest/download/nonprofit-explorer-mcp-server.mcpb) [](https://cursor.com/en/install-mcp?name=nonprofit-explorer-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvbm9ucHJvZml0LWV4cGxvcmVyLW1jcC1zZXJ2ZXIiXX0=) [](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22nonprofit-explorer-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fnonprofit-explorer-mcp-server%22%5D%7D)
|
|
17
|
+
|
|
18
|
+
[](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
|
|
19
|
+
|
|
20
|
+
</div>
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## Tools
|
|
25
|
+
|
|
26
|
+
3 tools for working with US nonprofit and IRS Form 990 data:
|
|
27
|
+
|
|
28
|
+
| Tool | Description |
|
|
29
|
+
|:---|:---|
|
|
30
|
+
| `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 |
|
|
31
|
+
| `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 |
|
|
32
|
+
| `nonprofit_get_filings` | All Form 990 filings for an org by EIN: year-by-year financials, program-expense ratio, executive compensation, and source PDF/XML links |
|
|
33
|
+
|
|
34
|
+
### `nonprofit_search`
|
|
35
|
+
|
|
36
|
+
Search for tax-exempt organizations across the IRS Nonprofit Explorer dataset.
|
|
37
|
+
|
|
38
|
+
- Full-text search across org name, alternate name, and city with relevance ranking
|
|
39
|
+
- Supports quoted phrases (`"Red Cross"`), required terms (`+evanston`), excluded terms (`-dental`)
|
|
40
|
+
- Filter by US state (two-letter abbreviation; `ZZ` for foreign entities)
|
|
41
|
+
- Filter by NTEE major sector (Arts, Education, Health, Human Services, etc., 1–10)
|
|
42
|
+
- Filter by 501(c) subsection code (e.g., `3` = public charity, `4` = social welfare)
|
|
43
|
+
- Paginated at 25 per page; use `page` (zero-indexed) and `num_pages` to walk large result sets
|
|
44
|
+
- API caps total results at 10,000; `total_results === 10000` means the actual count may be higher
|
|
45
|
+
- Returns EINs — pass to `nonprofit_get_organization` or `nonprofit_get_filings` for details
|
|
46
|
+
|
|
47
|
+
---
|
|
48
|
+
|
|
49
|
+
### `nonprofit_get_organization`
|
|
50
|
+
|
|
51
|
+
Fetch the full profile for a single tax-exempt org by EIN.
|
|
52
|
+
|
|
53
|
+
- Accepts EIN as integer (`530196605`) or string with or without hyphen (`"53-0196605"`)
|
|
54
|
+
- Returns legal name, address, NTEE code, 501(c) type, and IRS ruling date
|
|
55
|
+
- Financial snapshot from the most recent Form 990: revenue, expenses, assets, liabilities, net assets
|
|
56
|
+
- Includes source 990 PDF link and IRS Business Master File summary figures
|
|
57
|
+
- `filing_count` shows how many filings with extracted data are on record
|
|
58
|
+
- Data lags 1–2 years; `tax_prd_yr` in the snapshot is the fiscal year of the filing, not the current year
|
|
59
|
+
- Use `nonprofit_search` first if you only have an org name
|
|
60
|
+
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
### `nonprofit_get_filings`
|
|
64
|
+
|
|
65
|
+
Fetch the full filing history for an org by EIN.
|
|
66
|
+
|
|
67
|
+
- All Form 990 filings with extracted financial data, sorted newest first
|
|
68
|
+
- Per-filing: revenue, expenses, assets, liabilities, net assets, revenue breakdown (contributions, program service, investment income)
|
|
69
|
+
- Program-expense ratio computed from 990 inputs with the full breakdown shown (officer comp, other salaries, fundraising); not available for 990-PF
|
|
70
|
+
- Executive compensation summary with field-name transparency and a note pointing to Schedule J for per-officer detail
|
|
71
|
+
- Source 990 PDF and XML links per filing
|
|
72
|
+
- `filings_pdf_only` lists older filings with a PDF but no extracted data
|
|
73
|
+
- Data lags 1–2 years; always cite `tax_prd_yr` (fiscal year) when presenting figures
|
|
74
|
+
|
|
75
|
+
## Features
|
|
76
|
+
|
|
77
|
+
Built on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core):
|
|
78
|
+
|
|
79
|
+
- Declarative tool definitions — single file per tool, framework handles registration and validation
|
|
80
|
+
- Unified error handling — handlers throw, framework catches, classifies, and formats
|
|
81
|
+
- Pluggable auth: `none`, `jwt`, `oauth`
|
|
82
|
+
- Swappable storage backends: `in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`
|
|
83
|
+
- Structured logging with optional OpenTelemetry tracing
|
|
84
|
+
- STDIO and Streamable HTTP transports
|
|
85
|
+
|
|
86
|
+
ProPublica Nonprofit Explorer / IRS-specific:
|
|
87
|
+
|
|
88
|
+
- Keyless access — ProPublica Nonprofit Explorer API requires no API key
|
|
89
|
+
- Covers 1.8M+ IRS-recognized tax-exempt organizations
|
|
90
|
+
- IRS Form 990 data: annual filings for public charities (990), small orgs (990-EZ), and private foundations (990-PF)
|
|
91
|
+
- Source filing links (PDF and XML) on every filing record
|
|
92
|
+
- Data sourced from ProPublica Nonprofit Explorer, derived from IRS Form 990 filings; data lags 1–2 years
|
|
93
|
+
|
|
94
|
+
Agent-friendly output:
|
|
95
|
+
|
|
96
|
+
- Provenance on every response — `data_source` attribution on all tool outputs, ProPublica URL for direct verification
|
|
97
|
+
- Filing-year clarity — `tax_prd_yr` prominently labeled as fiscal year with explicit lag caveat in every financial response
|
|
98
|
+
- Program-expense ratio with inputs — ratio is accompanied by the full expense breakdown so agents and users can verify the computation
|
|
99
|
+
- Field-name transparency on compensation — `field_name` and `form_type` exposed so agents know exactly which IRS field was read
|
|
100
|
+
|
|
101
|
+
## Getting started
|
|
102
|
+
|
|
103
|
+
Add the following to your MCP client configuration file.
|
|
104
|
+
|
|
105
|
+
```json
|
|
106
|
+
{
|
|
107
|
+
"mcpServers": {
|
|
108
|
+
"nonprofit-explorer": {
|
|
109
|
+
"type": "stdio",
|
|
110
|
+
"command": "bunx",
|
|
111
|
+
"args": ["@cyanheads/nonprofit-explorer-mcp-server@latest"],
|
|
112
|
+
"env": {
|
|
113
|
+
"MCP_TRANSPORT_TYPE": "stdio",
|
|
114
|
+
"MCP_LOG_LEVEL": "info"
|
|
115
|
+
}
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
Or with npx (no Bun required):
|
|
122
|
+
|
|
123
|
+
```json
|
|
124
|
+
{
|
|
125
|
+
"mcpServers": {
|
|
126
|
+
"nonprofit-explorer": {
|
|
127
|
+
"type": "stdio",
|
|
128
|
+
"command": "npx",
|
|
129
|
+
"args": ["-y", "@cyanheads/nonprofit-explorer-mcp-server@latest"],
|
|
130
|
+
"env": {
|
|
131
|
+
"MCP_TRANSPORT_TYPE": "stdio",
|
|
132
|
+
"MCP_LOG_LEVEL": "info"
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
Or with Docker:
|
|
140
|
+
|
|
141
|
+
```json
|
|
142
|
+
{
|
|
143
|
+
"mcpServers": {
|
|
144
|
+
"nonprofit-explorer": {
|
|
145
|
+
"type": "stdio",
|
|
146
|
+
"command": "docker",
|
|
147
|
+
"args": [
|
|
148
|
+
"run", "-i", "--rm",
|
|
149
|
+
"-e", "MCP_TRANSPORT_TYPE=stdio",
|
|
150
|
+
"ghcr.io/cyanheads/nonprofit-explorer-mcp-server:latest"
|
|
151
|
+
]
|
|
152
|
+
}
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
For Streamable HTTP, set the transport and start the server:
|
|
158
|
+
|
|
159
|
+
```sh
|
|
160
|
+
MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
|
|
161
|
+
# Server listens at http://localhost:3010/mcp
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
### Prerequisites
|
|
165
|
+
|
|
166
|
+
- [Bun v1.3.11](https://bun.sh/) or higher (or Node.js v24+).
|
|
167
|
+
- No API key required — ProPublica Nonprofit Explorer is a keyless public API.
|
|
168
|
+
|
|
169
|
+
### Installation
|
|
170
|
+
|
|
171
|
+
1. **Clone the repository:**
|
|
172
|
+
|
|
173
|
+
```sh
|
|
174
|
+
git clone https://github.com/cyanheads/nonprofit-explorer-mcp-server.git
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
2. **Navigate into the directory:**
|
|
178
|
+
|
|
179
|
+
```sh
|
|
180
|
+
cd nonprofit-explorer-mcp-server
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
3. **Install dependencies:**
|
|
184
|
+
|
|
185
|
+
```sh
|
|
186
|
+
bun install
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
4. **Configure environment:**
|
|
190
|
+
|
|
191
|
+
```sh
|
|
192
|
+
cp .env.example .env
|
|
193
|
+
# edit .env as needed (no required vars — server works out of the box)
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
## Configuration
|
|
197
|
+
|
|
198
|
+
All configuration is validated at startup. Key environment variables:
|
|
199
|
+
|
|
200
|
+
| Variable | Description | Default |
|
|
201
|
+
|:---------|:------------|:--------|
|
|
202
|
+
| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http` | `stdio` |
|
|
203
|
+
| `MCP_HTTP_PORT` | HTTP server port | `3010` |
|
|
204
|
+
| `MCP_HTTP_HOST` | HTTP server hostname | `127.0.0.1` |
|
|
205
|
+
| `MCP_HTTP_ENDPOINT_PATH` | HTTP endpoint path | `/mcp` |
|
|
206
|
+
| `MCP_PUBLIC_URL` | Public origin override for TLS-terminating reverse-proxy deployments | — |
|
|
207
|
+
| `MCP_AUTH_MODE` | Authentication: `none`, `jwt`, or `oauth` | `none` |
|
|
208
|
+
| `MCP_LOG_LEVEL` | Log level (`debug`, `info`, `warning`, `error`, etc.) | `info` |
|
|
209
|
+
| `LOGS_DIR` | Directory for log files (Node.js only) | `<project-root>/logs` |
|
|
210
|
+
| `STORAGE_PROVIDER_TYPE` | Storage backend: `in-memory`, `filesystem`, `supabase`, `cloudflare-kv/r2/d1` | `in-memory` |
|
|
211
|
+
| `OTEL_ENABLED` | Enable [OpenTelemetry instrumentation](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry) | `false` |
|
|
212
|
+
|
|
213
|
+
No server-specific required variables. ProPublica Nonprofit Explorer is a keyless public API.
|
|
214
|
+
|
|
215
|
+
See [`.env.example`](./.env.example) for the full list of optional overrides.
|
|
216
|
+
|
|
217
|
+
## Running the server
|
|
218
|
+
|
|
219
|
+
### Local development
|
|
220
|
+
|
|
221
|
+
- **Build and run:**
|
|
222
|
+
|
|
223
|
+
```sh
|
|
224
|
+
# One-time build
|
|
225
|
+
bun run rebuild
|
|
226
|
+
|
|
227
|
+
# Run the built server
|
|
228
|
+
bun run start:stdio
|
|
229
|
+
# or
|
|
230
|
+
bun run start:http
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
- **Run checks and tests:**
|
|
234
|
+
|
|
235
|
+
```sh
|
|
236
|
+
bun run devcheck # Lint, format, typecheck, security
|
|
237
|
+
bun run test # Vitest test suite
|
|
238
|
+
bun run lint:mcp # Validate MCP definitions against spec
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
### Docker
|
|
242
|
+
|
|
243
|
+
```sh
|
|
244
|
+
docker build -t nonprofit-explorer-mcp-server .
|
|
245
|
+
docker run --rm -p 3010:3010 nonprofit-explorer-mcp-server
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
The Dockerfile defaults to HTTP transport, stateless session mode, and logs to `/var/log/nonprofit-explorer-mcp-server`. OpenTelemetry peer dependencies are installed by default — build with `--build-arg OTEL_ENABLED=false` to omit them.
|
|
249
|
+
|
|
250
|
+
## Project structure
|
|
251
|
+
|
|
252
|
+
| Directory | Purpose |
|
|
253
|
+
|:----------|:--------|
|
|
254
|
+
| `src/index.ts` | `createApp()` entry point — registers tools and inits the service. |
|
|
255
|
+
| `src/mcp-server/tools` | Tool definitions (`*.tool.ts`). Three tools for search and financial data. |
|
|
256
|
+
| `src/services/nonprofit-explorer` | ProPublica Nonprofit Explorer API client and domain types. |
|
|
257
|
+
| `tests/` | Unit and integration tests mirroring `src/`. |
|
|
258
|
+
|
|
259
|
+
## Development guide
|
|
260
|
+
|
|
261
|
+
See [`CLAUDE.md`/`AGENTS.md`](./CLAUDE.md) for development guidelines and architectural rules. The short version:
|
|
262
|
+
|
|
263
|
+
- Handlers throw, framework catches — no `try/catch` in tool logic
|
|
264
|
+
- Use `ctx.log` for request-scoped logging, `ctx.state` for tenant-scoped storage
|
|
265
|
+
- Register new tools via the arrays in `createApp()` in `src/index.ts`
|
|
266
|
+
- Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields
|
|
267
|
+
|
|
268
|
+
## Contributing
|
|
269
|
+
|
|
270
|
+
Issues and pull requests are welcome. Run checks and tests before submitting:
|
|
271
|
+
|
|
272
|
+
```sh
|
|
273
|
+
bun run devcheck
|
|
274
|
+
bun run test
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
## License
|
|
278
|
+
|
|
279
|
+
Apache-2.0 — see [LICENSE](LICENSE) for details.
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
---
|
|
2
|
+
summary: "Public launch — nonprofit search, organization lookup, and Form 990 filing history over the ProPublica Nonprofit Explorer API."
|
|
3
|
+
breaking: false
|
|
4
|
+
security: false
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# 0.1.1 — 2026-06-01
|
|
8
|
+
|
|
9
|
+
Initial public release. Provides MCP access to 1.8M+ IRS-recognized tax-exempt organizations and their Form 990 financial filings via the ProPublica Nonprofit Explorer API. No API key required.
|
|
10
|
+
|
|
11
|
+
## Added
|
|
12
|
+
|
|
13
|
+
- **`nonprofit_search`** — keyword search across 1.8M+ tax-exempt organizations with optional state, NTEE category, and subsection code filters; returns paginated results (25/page).
|
|
14
|
+
- **`nonprofit_get_organization`** — fetch full organizational profile by EIN, including latest Form 990 financials (revenue, expenses, assets, liabilities), officer list, and filing metadata.
|
|
15
|
+
- **`nonprofit_get_filings`** — paginated Form 990 filing history for an organization by EIN; each record carries tax year, form type, financials, and a ProPublica permalink.
|
|
16
|
+
|
|
17
|
+
## Changed
|
|
18
|
+
|
|
19
|
+
- **`formTypeLabel`** extracted from inline arrow to module-level function for clarity.
|
|
20
|
+
- **`McpError` instanceof guard** replaces string-code check in the service error re-throw path.
|
|
21
|
+
- **`svc.search(input, ctx)`** called directly instead of reconstructing an intermediate object.
|
|
22
|
+
- **`parseJson`** helper consolidates the HTML-masquerade check and JSON.parse error handling in the service.
|
|
23
|
+
- Metadata polished: `manifest.json` description and author populated; `server.json` runtime hints set to `bun`; `Dockerfile` description label and source label added; `.claude-plugin` and `.codex-plugin` plugin manifests populated.
|
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
---
|
|
2
|
+
# FORMAT REFERENCE — do not edit. Copy this file to
|
|
3
|
+
# `changelog/<major.minor>.x/<version>.md` (e.g. `changelog/0.8.x/0.8.6.md`)
|
|
4
|
+
# to author a new release. Set that file's H1 to `# <version> — YYYY-MM-DD`
|
|
5
|
+
# with a concrete date.
|
|
6
|
+
|
|
7
|
+
# Required. One-line GitHub Release-style headline. 350 character cap.
|
|
8
|
+
# Default short and scannable. Don't pad, don't stitch unrelated changes with
|
|
9
|
+
# semicolons — pick the headline. Quotes required: unquoted YAML treats `: `
|
|
10
|
+
# inside the value as a key separator and fails GitHub's strict parser.
|
|
11
|
+
summary: ""
|
|
12
|
+
|
|
13
|
+
# Set `true` when consumers must change code to upgrade: API removals,
|
|
14
|
+
# signature changes, config renames, behavior changes that break existing
|
|
15
|
+
# usage. Flagged as `Breaking` in the rollup.
|
|
16
|
+
breaking: false
|
|
17
|
+
|
|
18
|
+
# Set `true` if this release contains any security fix. Pairs with the
|
|
19
|
+
# `## Security` section below. Flagged as `Security` in the rollup so
|
|
20
|
+
# users can triage upgrade urgency at a glance.
|
|
21
|
+
security: false
|
|
22
|
+
|
|
23
|
+
# Optional free-form notes for maintenance agents processing this release.
|
|
24
|
+
# Not rendered in CHANGELOG — consumed by agents running `maintenance` on
|
|
25
|
+
# downstream servers. Use for adoption instructions that don't fit the
|
|
26
|
+
# human-facing sections: new files to create, fields to populate, one-time
|
|
27
|
+
# migration steps. Omit the field entirely when there's nothing to say.
|
|
28
|
+
# agent-notes: |
|
|
29
|
+
# <instructions for downstream maintenance agents>
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
# <version> — YYYY-MM-DD
|
|
33
|
+
|
|
34
|
+
<!--
|
|
35
|
+
AUTHORING GUIDE — applies to the new per-version file you create from this
|
|
36
|
+
template.
|
|
37
|
+
|
|
38
|
+
Audience: someone scanning release notes to decide what affects them. Lead
|
|
39
|
+
each bullet with the symbol or concept name in **bold** so they can skip
|
|
40
|
+
what's irrelevant and zoom in on what's not.
|
|
41
|
+
|
|
42
|
+
Tone: terse, fact-dense, not verbose. Default to one sentence per bullet —
|
|
43
|
+
name the symbol, state what changed, stop. Use a second sentence only when
|
|
44
|
+
it carries weight. If a bullet feels long, it is.
|
|
45
|
+
|
|
46
|
+
Cut: mechanism walkthroughs (those belong in JSDoc, CLAUDE.md/AGENTS.md, or the
|
|
47
|
+
relevant skill), ceremonial framings ("This release introduces…",
|
|
48
|
+
backwards-compat paragraphs), file-by-file test enumerations, internal
|
|
49
|
+
implementation notes. Prefer code/symbol names over English re-explanations.
|
|
50
|
+
|
|
51
|
+
Narrative intro: skip by default. Add one short sentence only when the
|
|
52
|
+
release theme genuinely needs framing the bullets can't carry.
|
|
53
|
+
|
|
54
|
+
Sections: Keep a Changelog order — Added, Changed, Deprecated, Removed,
|
|
55
|
+
Fixed, Security. Include only sections with entries; delete the rest
|
|
56
|
+
(including the commented-out scaffolding below). Don't ship empty headers.
|
|
57
|
+
|
|
58
|
+
Include: every distinct fact a reader needs to adopt or audit the release —
|
|
59
|
+
new exports, signatures, lint rule IDs, env vars, breaking changes, version
|
|
60
|
+
bumps on shipped skills. Nothing more.
|
|
61
|
+
|
|
62
|
+
Links: link issues, PRs, docs, or skills where they help a reader jump to
|
|
63
|
+
context. Once per item per entry — don't re-link the same issue in summary,
|
|
64
|
+
narrative, and bullet. Skip links for inline symbol names; code spans speak
|
|
65
|
+
for themselves.
|
|
66
|
+
|
|
67
|
+
Issue/PR URLs: use full URLs. GitHub's bare `#NN` auto-link only resolves
|
|
68
|
+
inside its own UI, not in npm reads or local editors.
|
|
69
|
+
|
|
70
|
+
[#38](https://github.com/cyanheads/mcp-ts-core/issues/38) ← issue
|
|
71
|
+
[#42](https://github.com/cyanheads/mcp-ts-core/pull/42) ← PR
|
|
72
|
+
|
|
73
|
+
Verify numbers exist before linking (`gh issue view NN`, `gh pr view NN`).
|
|
74
|
+
Never speculate on a future number — `#42` for an upcoming PR silently
|
|
75
|
+
resolves to whatever real item already owns 42, and timeline previews pull
|
|
76
|
+
in that unrelated item's metadata.
|
|
77
|
+
|
|
78
|
+
TAG ANNOTATIONS — the annotated tag body renders as the GitHub Release body
|
|
79
|
+
via `gh release create --notes-from-tag`. The tag is a derivative of this
|
|
80
|
+
changelog entry — a condensed, scannable version, not a copy. Format:
|
|
81
|
+
|
|
82
|
+
<theme — omit version number, GitHub prepends it>
|
|
83
|
+
← blank line
|
|
84
|
+
<1-2 sentence context: what this release does>
|
|
85
|
+
← blank line
|
|
86
|
+
Dependency bumps: ← section header
|
|
87
|
+
← blank line
|
|
88
|
+
- `@cyanheads/mcp-ts-core` ^0.9.1 → ^0.9.6 ← bullet
|
|
89
|
+
← blank line
|
|
90
|
+
Changed: ← only sections with entries
|
|
91
|
+
← blank line
|
|
92
|
+
- `format()` output includes `query` in text mode
|
|
93
|
+
← blank line
|
|
94
|
+
Added:
|
|
95
|
+
← blank line
|
|
96
|
+
- `manifest.json` scaffolded for MCPB bundle support
|
|
97
|
+
- Install badges (Claude Desktop, Cursor, VS Code)
|
|
98
|
+
← blank line
|
|
99
|
+
<N> tests pass; `bun run devcheck` clean. ← footer
|
|
100
|
+
|
|
101
|
+
Never a flat comma-separated string. Always structured markdown with
|
|
102
|
+
sections. The tag must scan well as a rendered GitHub Release page.
|
|
103
|
+
-->
|
|
104
|
+
|
|
105
|
+
## Added
|
|
106
|
+
|
|
107
|
+
-
|
|
108
|
+
|
|
109
|
+
## Changed
|
|
110
|
+
|
|
111
|
+
-
|
|
112
|
+
|
|
113
|
+
<!-- ## Deprecated
|
|
114
|
+
|
|
115
|
+
- -->
|
|
116
|
+
|
|
117
|
+
<!-- ## Removed
|
|
118
|
+
|
|
119
|
+
- -->
|
|
120
|
+
|
|
121
|
+
## Fixed
|
|
122
|
+
|
|
123
|
+
-
|
|
124
|
+
|
|
125
|
+
<!-- ## Security
|
|
126
|
+
|
|
127
|
+
- -->
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG"}
|