@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
|
@@ -0,0 +1,245 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview Full org profile by EIN: legal identity, IRS classification, and financial snapshot.
|
|
3
|
+
* @module mcp-server/tools/definitions/nonprofit-get-organization.tool
|
|
4
|
+
*/
|
|
5
|
+
import { tool, z } from '@cyanheads/mcp-ts-core';
|
|
6
|
+
import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
|
|
7
|
+
import { formatEin, getNonprofitExplorerService, normalizeEin, } from '../../../services/nonprofit-explorer/nonprofit-explorer-service.js';
|
|
8
|
+
const USD = (n) => `$${n.toLocaleString()}`;
|
|
9
|
+
/** Map formtype integer to form label. */
|
|
10
|
+
function formTypeLabel(ft) {
|
|
11
|
+
if (ft === 1)
|
|
12
|
+
return '990-EZ';
|
|
13
|
+
if (ft === 2)
|
|
14
|
+
return '990-PF';
|
|
15
|
+
return '990';
|
|
16
|
+
}
|
|
17
|
+
export const nonprofitGetOrganization = tool('nonprofit_get_organization', {
|
|
18
|
+
title: 'Get Nonprofit Organization',
|
|
19
|
+
description: 'Full profile for a single tax-exempt org by EIN: legal name, address, NTEE classification, ' +
|
|
20
|
+
'501(c) type, IRS ruling date, and a financial snapshot from the most recent Form 990 filing ' +
|
|
21
|
+
'(revenue, expenses, assets, net assets, and the source PDF link). ' +
|
|
22
|
+
'Use nonprofit_search first if you only have an org name — this tool requires an EIN. ' +
|
|
23
|
+
'Data lags 1–2 years; the tax year is shown prominently. ' +
|
|
24
|
+
'Data from ProPublica Nonprofit Explorer, sourced from IRS Form 990 filings.',
|
|
25
|
+
annotations: { readOnlyHint: true, idempotentHint: true },
|
|
26
|
+
input: z.object({
|
|
27
|
+
ein: z
|
|
28
|
+
.union([
|
|
29
|
+
z
|
|
30
|
+
.number()
|
|
31
|
+
.int()
|
|
32
|
+
.positive()
|
|
33
|
+
.describe('EIN as integer (e.g., 530196605). Leading zeros are stripped — treat EIN as an integer key.'),
|
|
34
|
+
z
|
|
35
|
+
.string()
|
|
36
|
+
.regex(/^\d{2}-?\d{7}$/)
|
|
37
|
+
.describe('EIN as string, with or without hyphen (e.g., "53-0196605" or "530196605").'),
|
|
38
|
+
])
|
|
39
|
+
.describe('Employer Identification Number. Accepts integer (530196605) or string with optional hyphen ' +
|
|
40
|
+
'("53-0196605"). Obtain from nonprofit_search results.'),
|
|
41
|
+
}),
|
|
42
|
+
output: z.object({
|
|
43
|
+
ein: z.number().describe('Employer Identification Number as integer.'),
|
|
44
|
+
strein: z.string().describe('EIN in "XX-XXXXXXX" format.'),
|
|
45
|
+
name: z.string().describe('Legal org name per IRS.'),
|
|
46
|
+
sort_name: z
|
|
47
|
+
.string()
|
|
48
|
+
.nullable()
|
|
49
|
+
.describe('Alternate or subtitle name from the org record. Null when absent.'),
|
|
50
|
+
address: z.string().nullable().describe('Street address. Null when not on record.'),
|
|
51
|
+
city: z.string().nullable().describe('City. Null when not on record.'),
|
|
52
|
+
state: z
|
|
53
|
+
.string()
|
|
54
|
+
.nullable()
|
|
55
|
+
.describe('Two-letter state abbreviation. Null when not on record.'),
|
|
56
|
+
zipcode: z.string().nullable().describe('ZIP code. Null when not on record.'),
|
|
57
|
+
ntee_code: z
|
|
58
|
+
.string()
|
|
59
|
+
.nullable()
|
|
60
|
+
.describe('Full NTEE code (e.g., "E210" = hospital). Null when unclassified.'),
|
|
61
|
+
subsection_code: z
|
|
62
|
+
.number()
|
|
63
|
+
.nullable()
|
|
64
|
+
.describe('501(c) subsection number (e.g., 3 = public charity). Null when not classified.'),
|
|
65
|
+
ruling_date: z
|
|
66
|
+
.string()
|
|
67
|
+
.nullable()
|
|
68
|
+
.describe('ISO date of IRS recognition (e.g., "1946-07"). Null when not on record.'),
|
|
69
|
+
asset_amount: z
|
|
70
|
+
.number()
|
|
71
|
+
.nullable()
|
|
72
|
+
.describe('Most recent IRS BMF total assets in USD. Null when not reported.'),
|
|
73
|
+
income_amount: z
|
|
74
|
+
.number()
|
|
75
|
+
.nullable()
|
|
76
|
+
.describe('Most recent IRS BMF total income in USD. Null when not reported.'),
|
|
77
|
+
revenue_amount: z
|
|
78
|
+
.number()
|
|
79
|
+
.nullable()
|
|
80
|
+
.describe('Most recent IRS BMF total revenue in USD. Null when not reported.'),
|
|
81
|
+
latest_filing: z
|
|
82
|
+
.object({
|
|
83
|
+
tax_prd_yr: z
|
|
84
|
+
.number()
|
|
85
|
+
.describe('Fiscal year of this filing (e.g., 2023). NOT the current year — data lags 1–2 years.'),
|
|
86
|
+
form_type: z.enum(['990', '990-EZ', '990-PF']).describe('IRS form type filed.'),
|
|
87
|
+
total_revenue: z
|
|
88
|
+
.number()
|
|
89
|
+
.nullable()
|
|
90
|
+
.describe('Total revenue in USD. Null when not extracted.'),
|
|
91
|
+
total_expenses: z
|
|
92
|
+
.number()
|
|
93
|
+
.nullable()
|
|
94
|
+
.describe('Total expenses in USD. Null when not extracted.'),
|
|
95
|
+
total_assets: z
|
|
96
|
+
.number()
|
|
97
|
+
.nullable()
|
|
98
|
+
.describe('Total assets (end of year) in USD. Null when not extracted.'),
|
|
99
|
+
total_liabilities: z
|
|
100
|
+
.number()
|
|
101
|
+
.nullable()
|
|
102
|
+
.describe('Total liabilities (end of year) in USD. Null when not extracted.'),
|
|
103
|
+
net_assets: z
|
|
104
|
+
.number()
|
|
105
|
+
.nullable()
|
|
106
|
+
.describe('Net assets/fund balances (end of year) in USD. From totnetassetend. Null when not extracted.'),
|
|
107
|
+
pdf_url: z
|
|
108
|
+
.string()
|
|
109
|
+
.nullable()
|
|
110
|
+
.describe('Source Form 990 PDF link. Null for some IRS processing batches — check filings via nonprofit_get_filings.'),
|
|
111
|
+
})
|
|
112
|
+
.nullable()
|
|
113
|
+
.describe('Financial snapshot from the most recent Form 990. Null if no filings_with_data are available.'),
|
|
114
|
+
filing_count: z.number().describe('Total filings with extracted data on record.'),
|
|
115
|
+
data_source: z.string().describe('ProPublica + IRS attribution text.'),
|
|
116
|
+
propublica_url: z.string().describe('ProPublica Nonprofit Explorer URL for this org.'),
|
|
117
|
+
}),
|
|
118
|
+
errors: [
|
|
119
|
+
{
|
|
120
|
+
reason: 'not_found',
|
|
121
|
+
code: JsonRpcErrorCode.NotFound,
|
|
122
|
+
when: 'The EIN does not correspond to a known organization in the Nonprofit Explorer database',
|
|
123
|
+
recovery: 'Verify the EIN with nonprofit_search. EINs with leading zeros are stored without them — try the integer value.',
|
|
124
|
+
},
|
|
125
|
+
{
|
|
126
|
+
reason: 'upstream_error',
|
|
127
|
+
code: JsonRpcErrorCode.ServiceUnavailable,
|
|
128
|
+
when: 'ProPublica API returns a non-JSON body (HTML 500) or network error',
|
|
129
|
+
retryable: true,
|
|
130
|
+
recovery: 'Wait a moment and retry.',
|
|
131
|
+
},
|
|
132
|
+
],
|
|
133
|
+
async handler(input, ctx) {
|
|
134
|
+
const ein = normalizeEin(input.ein);
|
|
135
|
+
ctx.log.info('Fetching nonprofit organization', { ein });
|
|
136
|
+
const svc = getNonprofitExplorerService();
|
|
137
|
+
// Service throws notFound (with reason: 'not_found') or serviceUnavailable (reason: 'upstream_error')
|
|
138
|
+
// propagated unchanged by the framework auto-classifier.
|
|
139
|
+
const raw = await svc.getOrganization(ein, ctx);
|
|
140
|
+
// Service validates organization presence and throws notFound before returning — safe to assert.
|
|
141
|
+
// biome-ignore lint/style/noNonNullAssertion: guaranteed by service not-found checks
|
|
142
|
+
const org = raw.organization;
|
|
143
|
+
const filings = raw.filings_with_data ?? [];
|
|
144
|
+
// Pick the latest filing (most recent tax_prd_yr)
|
|
145
|
+
const sorted = [...filings].sort((a, b) => (b.tax_prd_yr ?? 0) - (a.tax_prd_yr ?? 0));
|
|
146
|
+
const latest = sorted[0] ?? null;
|
|
147
|
+
const latestFiling = latest
|
|
148
|
+
? {
|
|
149
|
+
tax_prd_yr: latest.tax_prd_yr ?? 0,
|
|
150
|
+
form_type: formTypeLabel(latest.formtype),
|
|
151
|
+
total_revenue: latest.totrevenue ?? null,
|
|
152
|
+
total_expenses: latest.totfuncexpns ?? null,
|
|
153
|
+
total_assets: latest.totassetsend ?? null,
|
|
154
|
+
total_liabilities: latest.totliabend ?? null,
|
|
155
|
+
net_assets: latest.totnetassetend ?? null,
|
|
156
|
+
pdf_url: latest.pdf_url ?? null,
|
|
157
|
+
}
|
|
158
|
+
: null;
|
|
159
|
+
const einNum = org.ein ?? ein;
|
|
160
|
+
const strein = org.strein ?? formatEin(einNum);
|
|
161
|
+
return {
|
|
162
|
+
ein: einNum,
|
|
163
|
+
strein,
|
|
164
|
+
name: org.name ?? '',
|
|
165
|
+
sort_name: org.sort_name ?? null,
|
|
166
|
+
address: org.address ?? null,
|
|
167
|
+
city: org.city ?? null,
|
|
168
|
+
state: org.state ?? null,
|
|
169
|
+
zipcode: org.zipcode ?? null,
|
|
170
|
+
ntee_code: org.ntee_code ?? null,
|
|
171
|
+
subsection_code: org.subsection_code ?? null,
|
|
172
|
+
ruling_date: org.ruling_date ?? null,
|
|
173
|
+
asset_amount: org.asset_amount ?? null,
|
|
174
|
+
income_amount: org.income_amount ?? null,
|
|
175
|
+
revenue_amount: org.revenue_amount ?? null,
|
|
176
|
+
latest_filing: latestFiling,
|
|
177
|
+
filing_count: filings.length,
|
|
178
|
+
data_source: raw.data_source ?? 'ProPublica Nonprofit Explorer, IRS Form 990 data.',
|
|
179
|
+
propublica_url: `https://projects.propublica.org/nonprofits/organizations/${einNum}`,
|
|
180
|
+
};
|
|
181
|
+
},
|
|
182
|
+
format: (result) => {
|
|
183
|
+
const lines = [];
|
|
184
|
+
lines.push(`# ${result.name}`);
|
|
185
|
+
if (result.sort_name)
|
|
186
|
+
lines.push(`*${result.sort_name}*`);
|
|
187
|
+
lines.push('');
|
|
188
|
+
lines.push(`**EIN:** ${result.strein} (${result.ein})`);
|
|
189
|
+
if (result.subsection_code != null) {
|
|
190
|
+
lines.push(`**Type:** 501(c)(${result.subsection_code})`);
|
|
191
|
+
}
|
|
192
|
+
if (result.ntee_code)
|
|
193
|
+
lines.push(`**NTEE Code:** ${result.ntee_code}`);
|
|
194
|
+
if (result.ruling_date)
|
|
195
|
+
lines.push(`**IRS Recognition:** ${result.ruling_date}`);
|
|
196
|
+
lines.push('');
|
|
197
|
+
const addrParts = [result.address, result.city, result.state, result.zipcode].filter(Boolean);
|
|
198
|
+
if (addrParts.length > 0) {
|
|
199
|
+
lines.push(`**Address:** ${addrParts.join(', ')}`);
|
|
200
|
+
}
|
|
201
|
+
lines.push(`**Filings on record:** ${result.filing_count}`);
|
|
202
|
+
lines.push('');
|
|
203
|
+
lines.push(`**Profile:** ${result.propublica_url}`);
|
|
204
|
+
if (result.latest_filing) {
|
|
205
|
+
const f = result.latest_filing;
|
|
206
|
+
lines.push('');
|
|
207
|
+
lines.push(`## Latest Filing (${f.form_type}, FY ${f.tax_prd_yr})`);
|
|
208
|
+
lines.push('> ⚠️ Data lags 1–2 years. FY shown is the fiscal year, not the current year.');
|
|
209
|
+
if (f.total_revenue != null)
|
|
210
|
+
lines.push(`**Revenue:** ${USD(f.total_revenue)}`);
|
|
211
|
+
if (f.total_expenses != null)
|
|
212
|
+
lines.push(`**Expenses:** ${USD(f.total_expenses)}`);
|
|
213
|
+
if (f.total_assets != null)
|
|
214
|
+
lines.push(`**Assets:** ${USD(f.total_assets)}`);
|
|
215
|
+
if (f.total_liabilities != null)
|
|
216
|
+
lines.push(`**Liabilities:** ${USD(f.total_liabilities)}`);
|
|
217
|
+
if (f.net_assets != null)
|
|
218
|
+
lines.push(`**Net Assets:** ${USD(f.net_assets)}`);
|
|
219
|
+
if (f.pdf_url) {
|
|
220
|
+
lines.push(`**Source 990 PDF:** ${f.pdf_url}`);
|
|
221
|
+
}
|
|
222
|
+
else {
|
|
223
|
+
lines.push('**Source 990 PDF:** Not yet available for this period');
|
|
224
|
+
}
|
|
225
|
+
}
|
|
226
|
+
else {
|
|
227
|
+
lines.push('');
|
|
228
|
+
lines.push('*No Form 990 data on file. Org may file Form 990N (under $50K revenue).*');
|
|
229
|
+
}
|
|
230
|
+
if (result.asset_amount != null || result.income_amount != null) {
|
|
231
|
+
lines.push('');
|
|
232
|
+
lines.push('## IRS Business Master File Summary');
|
|
233
|
+
if (result.asset_amount != null)
|
|
234
|
+
lines.push(`**Total Assets (BMF):** ${USD(result.asset_amount)}`);
|
|
235
|
+
if (result.income_amount != null)
|
|
236
|
+
lines.push(`**Total Income (BMF):** ${USD(result.income_amount)}`);
|
|
237
|
+
if (result.revenue_amount != null)
|
|
238
|
+
lines.push(`**Total Revenue (BMF):** ${USD(result.revenue_amount)}`);
|
|
239
|
+
}
|
|
240
|
+
lines.push('');
|
|
241
|
+
lines.push(`*${result.data_source}*`);
|
|
242
|
+
return [{ type: 'text', text: lines.join('\n') }];
|
|
243
|
+
},
|
|
244
|
+
});
|
|
245
|
+
//# sourceMappingURL=nonprofit-get-organization.tool.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"nonprofit-get-organization.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/nonprofit-get-organization.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EACL,SAAS,EACT,2BAA2B,EAC3B,YAAY,GACb,MAAM,6DAA6D,CAAC;AAErE,MAAM,GAAG,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,cAAc,EAAE,EAAE,CAAC;AAEpD,0CAA0C;AAC1C,SAAS,aAAa,CAAC,EAAsB;IAC3C,IAAI,EAAE,KAAK,CAAC;QAAE,OAAO,QAAQ,CAAC;IAC9B,IAAI,EAAE,KAAK,CAAC;QAAE,OAAO,QAAQ,CAAC;IAC9B,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,CAAC,MAAM,wBAAwB,GAAG,IAAI,CAAC,4BAA4B,EAAE;IACzE,KAAK,EAAE,4BAA4B;IACnC,WAAW,EACT,6FAA6F;QAC7F,8FAA8F;QAC9F,oEAAoE;QACpE,uFAAuF;QACvF,0DAA0D;QAC1D,6EAA6E;IAC/E,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE;IAEzD,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC;QACd,GAAG,EAAE,CAAC;aACH,KAAK,CAAC;YACL,CAAC;iBACE,MAAM,EAAE;iBACR,GAAG,EAAE;iBACL,QAAQ,EAAE;iBACV,QAAQ,CACP,6FAA6F,CAC9F;YACH,CAAC;iBACE,MAAM,EAAE;iBACR,KAAK,CAAC,gBAAgB,CAAC;iBACvB,QAAQ,CAAC,4EAA4E,CAAC;SAC1F,CAAC;aACD,QAAQ,CACP,6FAA6F;YAC3F,uDAAuD,CAC1D;KACJ,CAAC;IAEF,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,4CAA4C,CAAC;QACtE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,6BAA6B,CAAC;QAC1D,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,yBAAyB,CAAC;QACpD,SAAS,EAAE,CAAC;aACT,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CAAC,mEAAmE,CAAC;QAChF,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,0CAA0C,CAAC;QACnF,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,gCAAgC,CAAC;QACtE,KAAK,EAAE,CAAC;aACL,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CAAC,yDAAyD,CAAC;QACtE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,oCAAoC,CAAC;QAC7E,SAAS,EAAE,CAAC;aACT,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CAAC,mEAAmE,CAAC;QAChF,eAAe,EAAE,CAAC;aACf,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CAAC,gFAAgF,CAAC;QAC7F,WAAW,EAAE,CAAC;aACX,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CAAC,yEAAyE,CAAC;QACtF,YAAY,EAAE,CAAC;aACZ,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CAAC,kEAAkE,CAAC;QAC/E,aAAa,EAAE,CAAC;aACb,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CAAC,kEAAkE,CAAC;QAC/E,cAAc,EAAE,CAAC;aACd,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CAAC,mEAAmE,CAAC;QAChF,aAAa,EAAE,CAAC;aACb,MAAM,CAAC;YACN,UAAU,EAAE,CAAC;iBACV,MAAM,EAAE;iBACR,QAAQ,CACP,sFAAsF,CACvF;YACH,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,sBAAsB,CAAC;YAC/E,aAAa,EAAE,CAAC;iBACb,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,gDAAgD,CAAC;YAC7D,cAAc,EAAE,CAAC;iBACd,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,iDAAiD,CAAC;YAC9D,YAAY,EAAE,CAAC;iBACZ,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,6DAA6D,CAAC;YAC1E,iBAAiB,EAAE,CAAC;iBACjB,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,kEAAkE,CAAC;YAC/E,UAAU,EAAE,CAAC;iBACV,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CACP,8FAA8F,CAC/F;YACH,OAAO,EAAE,CAAC;iBACP,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CACP,2GAA2G,CAC5G;SACJ,CAAC;aACD,QAAQ,EAAE;aACV,QAAQ,CACP,+FAA+F,CAChG;QACH,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,8CAA8C,CAAC;QACjF,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oCAAoC,CAAC;QACtE,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,iDAAiD,CAAC;KACvF,CAAC;IAEF,MAAM,EAAE;QACN;YACE,MAAM,EAAE,WAAW;YACnB,IAAI,EAAE,gBAAgB,CAAC,QAAQ;YAC/B,IAAI,EAAE,wFAAwF;YAC9F,QAAQ,EACN,gHAAgH;SACnH;QACD;YACE,MAAM,EAAE,gBAAgB;YACxB,IAAI,EAAE,gBAAgB,CAAC,kBAAkB;YACzC,IAAI,EAAE,oEAAoE;YAC1E,SAAS,EAAE,IAAI;YACf,QAAQ,EAAE,0BAA0B;SACrC;KACF;IAED,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG;QACtB,MAAM,GAAG,GAAG,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACpC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,iCAAiC,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;QAEzD,MAAM,GAAG,GAAG,2BAA2B,EAAE,CAAC;QAE1C,sGAAsG;QACtG,yDAAyD;QACzD,MAAM,GAAG,GAAG,MAAM,GAAG,CAAC,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QAEhD,iGAAiG;QACjG,qFAAqF;QACrF,MAAM,GAAG,GAAG,GAAG,CAAC,YAAa,CAAC;QAC9B,MAAM,OAAO,GAAG,GAAG,CAAC,iBAAiB,IAAI,EAAE,CAAC;QAE5C,kDAAkD;QAClD,MAAM,MAAM,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,CAAC,CAAC;QACtF,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;QAEjC,MAAM,YAAY,GAAG,MAAM;YACzB,CAAC,CAAC;gBACE,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,CAAC;gBAClC,SAAS,EAAE,aAAa,CAAC,MAAM,CAAC,QAAQ,CAAC;gBACzC,aAAa,EAAE,MAAM,CAAC,UAAU,IAAI,IAAI;gBACxC,cAAc,EAAE,MAAM,CAAC,YAAY,IAAI,IAAI;gBAC3C,YAAY,EAAE,MAAM,CAAC,YAAY,IAAI,IAAI;gBACzC,iBAAiB,EAAE,MAAM,CAAC,UAAU,IAAI,IAAI;gBAC5C,UAAU,EAAE,MAAM,CAAC,cAAc,IAAI,IAAI;gBACzC,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,IAAI;aAChC;YACH,CAAC,CAAC,IAAI,CAAC;QAET,MAAM,MAAM,GAAG,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC;QAC9B,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,IAAI,SAAS,CAAC,MAAM,CAAC,CAAC;QAE/C,OAAO;YACL,GAAG,EAAE,MAAM;YACX,MAAM;YACN,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,EAAE;YACpB,SAAS,EAAE,GAAG,CAAC,SAAS,IAAI,IAAI;YAChC,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,IAAI;YAC5B,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,IAAI;YACtB,KAAK,EAAE,GAAG,CAAC,KAAK,IAAI,IAAI;YACxB,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,IAAI;YAC5B,SAAS,EAAE,GAAG,CAAC,SAAS,IAAI,IAAI;YAChC,eAAe,EAAE,GAAG,CAAC,eAAe,IAAI,IAAI;YAC5C,WAAW,EAAE,GAAG,CAAC,WAAW,IAAI,IAAI;YACpC,YAAY,EAAE,GAAG,CAAC,YAAY,IAAI,IAAI;YACtC,aAAa,EAAE,GAAG,CAAC,aAAa,IAAI,IAAI;YACxC,cAAc,EAAE,GAAG,CAAC,cAAc,IAAI,IAAI;YAC1C,aAAa,EAAE,YAAY;YAC3B,YAAY,EAAE,OAAO,CAAC,MAAM;YAC5B,WAAW,EAAE,GAAG,CAAC,WAAW,IAAI,mDAAmD;YACnF,cAAc,EAAE,4DAA4D,MAAM,EAAE;SACrF,CAAC;IACJ,CAAC;IAED,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE;QACjB,MAAM,KAAK,GAAa,EAAE,CAAC;QAE3B,KAAK,CAAC,IAAI,CAAC,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;QAC/B,IAAI,MAAM,CAAC,SAAS;YAAE,KAAK,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,SAAS,GAAG,CAAC,CAAC;QAC1D,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAEf,KAAK,CAAC,IAAI,CAAC,YAAY,MAAM,CAAC,MAAM,KAAK,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC;QACxD,IAAI,MAAM,CAAC,eAAe,IAAI,IAAI,EAAE,CAAC;YACnC,KAAK,CAAC,IAAI,CAAC,oBAAoB,MAAM,CAAC,eAAe,GAAG,CAAC,CAAC;QAC5D,CAAC;QACD,IAAI,MAAM,CAAC,SAAS;YAAE,KAAK,CAAC,IAAI,CAAC,kBAAkB,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC;QACvE,IAAI,MAAM,CAAC,WAAW;YAAE,KAAK,CAAC,IAAI,CAAC,wBAAwB,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC;QACjF,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAEf,MAAM,SAAS,GAAG,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC9F,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACzB,KAAK,CAAC,IAAI,CAAC,gBAAgB,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACrD,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,0BAA0B,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC;QAC5D,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,gBAAgB,MAAM,CAAC,cAAc,EAAE,CAAC,CAAC;QAEpD,IAAI,MAAM,CAAC,aAAa,EAAE,CAAC;YACzB,MAAM,CAAC,GAAG,MAAM,CAAC,aAAa,CAAC;YAC/B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACf,KAAK,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC,SAAS,QAAQ,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC;YACpE,KAAK,CAAC,IAAI,CAAC,8EAA8E,CAAC,CAAC;YAC3F,IAAI,CAAC,CAAC,aAAa,IAAI,IAAI;gBAAE,KAAK,CAAC,IAAI,CAAC,gBAAgB,GAAG,CAAC,CAAC,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC;YAChF,IAAI,CAAC,CAAC,cAAc,IAAI,IAAI;gBAAE,KAAK,CAAC,IAAI,CAAC,iBAAiB,GAAG,CAAC,CAAC,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC;YACnF,IAAI,CAAC,CAAC,YAAY,IAAI,IAAI;gBAAE,KAAK,CAAC,IAAI,CAAC,eAAe,GAAG,CAAC,CAAC,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;YAC7E,IAAI,CAAC,CAAC,iBAAiB,IAAI,IAAI;gBAAE,KAAK,CAAC,IAAI,CAAC,oBAAoB,GAAG,CAAC,CAAC,CAAC,iBAAiB,CAAC,EAAE,CAAC,CAAC;YAC5F,IAAI,CAAC,CAAC,UAAU,IAAI,IAAI;gBAAE,KAAK,CAAC,IAAI,CAAC,mBAAmB,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;YAC7E,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC;gBACd,KAAK,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;YACjD,CAAC;iBAAM,CAAC;gBACN,KAAK,CAAC,IAAI,CAAC,uDAAuD,CAAC,CAAC;YACtE,CAAC;QACH,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACf,KAAK,CAAC,IAAI,CAAC,0EAA0E,CAAC,CAAC;QACzF,CAAC;QAED,IAAI,MAAM,CAAC,YAAY,IAAI,IAAI,IAAI,MAAM,CAAC,aAAa,IAAI,IAAI,EAAE,CAAC;YAChE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACf,KAAK,CAAC,IAAI,CAAC,qCAAqC,CAAC,CAAC;YAClD,IAAI,MAAM,CAAC,YAAY,IAAI,IAAI;gBAC7B,KAAK,CAAC,IAAI,CAAC,2BAA2B,GAAG,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;YACpE,IAAI,MAAM,CAAC,aAAa,IAAI,IAAI;gBAC9B,KAAK,CAAC,IAAI,CAAC,2BAA2B,GAAG,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC;YACrE,IAAI,MAAM,CAAC,cAAc,IAAI,IAAI;gBAC/B,KAAK,CAAC,IAAI,CAAC,4BAA4B,GAAG,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC;QACzE,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,WAAW,GAAG,CAAC,CAAC;QAEtC,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACpD,CAAC;CACF,CAAC,CAAC"}
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview Search 1.8M+ tax-exempt organizations by name/keyword with optional filters.
|
|
3
|
+
* @module mcp-server/tools/definitions/nonprofit-search.tool
|
|
4
|
+
*/
|
|
5
|
+
import { z } from '@cyanheads/mcp-ts-core';
|
|
6
|
+
import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
|
|
7
|
+
export declare const nonprofitSearch: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
|
|
8
|
+
query: z.ZodString;
|
|
9
|
+
state: z.ZodOptional<z.ZodString>;
|
|
10
|
+
ntee_category: z.ZodOptional<z.ZodEnum<{
|
|
11
|
+
1: "1";
|
|
12
|
+
2: "2";
|
|
13
|
+
3: "3";
|
|
14
|
+
4: "4";
|
|
15
|
+
5: "5";
|
|
16
|
+
6: "6";
|
|
17
|
+
7: "7";
|
|
18
|
+
8: "8";
|
|
19
|
+
9: "9";
|
|
20
|
+
10: "10";
|
|
21
|
+
}>>;
|
|
22
|
+
subsection_code: z.ZodOptional<z.ZodEnum<{
|
|
23
|
+
2: "2";
|
|
24
|
+
3: "3";
|
|
25
|
+
4: "4";
|
|
26
|
+
5: "5";
|
|
27
|
+
6: "6";
|
|
28
|
+
7: "7";
|
|
29
|
+
8: "8";
|
|
30
|
+
9: "9";
|
|
31
|
+
10: "10";
|
|
32
|
+
11: "11";
|
|
33
|
+
12: "12";
|
|
34
|
+
13: "13";
|
|
35
|
+
14: "14";
|
|
36
|
+
15: "15";
|
|
37
|
+
16: "16";
|
|
38
|
+
17: "17";
|
|
39
|
+
18: "18";
|
|
40
|
+
19: "19";
|
|
41
|
+
21: "21";
|
|
42
|
+
22: "22";
|
|
43
|
+
23: "23";
|
|
44
|
+
25: "25";
|
|
45
|
+
26: "26";
|
|
46
|
+
27: "27";
|
|
47
|
+
28: "28";
|
|
48
|
+
92: "92";
|
|
49
|
+
}>>;
|
|
50
|
+
page: z.ZodDefault<z.ZodNumber>;
|
|
51
|
+
}, z.core.$strip>, z.ZodObject<{
|
|
52
|
+
total_results: z.ZodNumber;
|
|
53
|
+
num_pages: z.ZodNumber;
|
|
54
|
+
cur_page: z.ZodNumber;
|
|
55
|
+
organizations: z.ZodArray<z.ZodObject<{
|
|
56
|
+
ein: z.ZodNumber;
|
|
57
|
+
strein: z.ZodString;
|
|
58
|
+
name: z.ZodString;
|
|
59
|
+
sub_name: z.ZodNullable<z.ZodString>;
|
|
60
|
+
city: z.ZodNullable<z.ZodString>;
|
|
61
|
+
state: z.ZodNullable<z.ZodString>;
|
|
62
|
+
ntee_code: z.ZodNullable<z.ZodString>;
|
|
63
|
+
subseccd: z.ZodNullable<z.ZodNumber>;
|
|
64
|
+
score: z.ZodNumber;
|
|
65
|
+
}, z.core.$strip>>;
|
|
66
|
+
active_filters: z.ZodObject<{
|
|
67
|
+
query: z.ZodString;
|
|
68
|
+
state: z.ZodNullable<z.ZodString>;
|
|
69
|
+
ntee_category: z.ZodNullable<z.ZodString>;
|
|
70
|
+
subsection_code: z.ZodNullable<z.ZodString>;
|
|
71
|
+
}, z.core.$strip>;
|
|
72
|
+
data_source: z.ZodString;
|
|
73
|
+
}, z.core.$strip>, readonly [{
|
|
74
|
+
readonly reason: "no_results";
|
|
75
|
+
readonly code: JsonRpcErrorCode.NotFound;
|
|
76
|
+
readonly when: "No organizations match the given query and filters";
|
|
77
|
+
readonly recovery: "Broaden the keyword query, remove one or more filters, or check spelling.";
|
|
78
|
+
}, {
|
|
79
|
+
readonly reason: "upstream_error";
|
|
80
|
+
readonly code: JsonRpcErrorCode.ServiceUnavailable;
|
|
81
|
+
readonly when: "ProPublica API returns a 500 or network error";
|
|
82
|
+
readonly retryable: true;
|
|
83
|
+
readonly recovery: "Wait a moment and retry. ProPublica's API is keyless and generally stable.";
|
|
84
|
+
}], undefined>;
|
|
85
|
+
//# sourceMappingURL=nonprofit-search.tool.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"nonprofit-search.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/nonprofit-search.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAGjE,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAmP1B,CAAC"}
|
|
@@ -0,0 +1,216 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview Search 1.8M+ tax-exempt organizations by name/keyword with optional filters.
|
|
3
|
+
* @module mcp-server/tools/definitions/nonprofit-search.tool
|
|
4
|
+
*/
|
|
5
|
+
import { tool, z } from '@cyanheads/mcp-ts-core';
|
|
6
|
+
import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
|
|
7
|
+
import { getNonprofitExplorerService } from '../../../services/nonprofit-explorer/nonprofit-explorer-service.js';
|
|
8
|
+
export const nonprofitSearch = tool('nonprofit_search', {
|
|
9
|
+
title: 'Search Nonprofits',
|
|
10
|
+
description: 'Search 1.8M+ IRS-recognized tax-exempt organizations by name, keyword, city, or phrase. ' +
|
|
11
|
+
'Optionally narrow by US state, NTEE major sector (1–10), or 501(c) subsection type. ' +
|
|
12
|
+
'Returns EINs — pass them to nonprofit_get_organization or nonprofit_get_filings for details. ' +
|
|
13
|
+
'Results are paginated at 25 per page; use the page parameter and num_pages to paginate. ' +
|
|
14
|
+
'Total results cap at 10,000 in the API; if total_results === 10000 the actual count may be higher. ' +
|
|
15
|
+
'Supports quoted phrases ("Red Cross"), required terms (+evanston), excluded terms (-dental). ' +
|
|
16
|
+
'Data from ProPublica Nonprofit Explorer, sourced from IRS Form 990 filings.',
|
|
17
|
+
annotations: { readOnlyHint: true },
|
|
18
|
+
input: z.object({
|
|
19
|
+
query: z
|
|
20
|
+
.string()
|
|
21
|
+
.describe('Keyword search string. Searched against org name, alternate name, and city in order of relevance. ' +
|
|
22
|
+
'Supports: quoted phrases ("Red Cross"), required terms (+evanston), excluded terms (-dental). ' +
|
|
23
|
+
'Empty string returns all orgs within the active filters.'),
|
|
24
|
+
state: z
|
|
25
|
+
.string()
|
|
26
|
+
.length(2)
|
|
27
|
+
.optional()
|
|
28
|
+
.describe('Two-letter US state abbreviation (e.g., "WA", "NY"). Use "ZZ" for foreign entities. ' +
|
|
29
|
+
'Restricts results to orgs headquartered in that state.'),
|
|
30
|
+
ntee_category: z
|
|
31
|
+
.enum(['1', '2', '3', '4', '5', '6', '7', '8', '9', '10'])
|
|
32
|
+
.optional()
|
|
33
|
+
.describe('NTEE (National Taxonomy of Exempt Entities) major group integer (1–10). ' +
|
|
34
|
+
'1=Arts/Culture/Humanities, 2=Education, 3=Environment/Animals, 4=Health, ' +
|
|
35
|
+
'5=Human Services, 6=International/Foreign Affairs, 7=Public/Societal Benefit, ' +
|
|
36
|
+
'8=Religion Related, 9=Mutual/Membership Benefit, 10=Unknown/Unclassified.'),
|
|
37
|
+
subsection_code: z
|
|
38
|
+
.enum([
|
|
39
|
+
'2',
|
|
40
|
+
'3',
|
|
41
|
+
'4',
|
|
42
|
+
'5',
|
|
43
|
+
'6',
|
|
44
|
+
'7',
|
|
45
|
+
'8',
|
|
46
|
+
'9',
|
|
47
|
+
'10',
|
|
48
|
+
'11',
|
|
49
|
+
'12',
|
|
50
|
+
'13',
|
|
51
|
+
'14',
|
|
52
|
+
'15',
|
|
53
|
+
'16',
|
|
54
|
+
'17',
|
|
55
|
+
'18',
|
|
56
|
+
'19',
|
|
57
|
+
'21',
|
|
58
|
+
'22',
|
|
59
|
+
'23',
|
|
60
|
+
'25',
|
|
61
|
+
'26',
|
|
62
|
+
'27',
|
|
63
|
+
'28',
|
|
64
|
+
'92',
|
|
65
|
+
])
|
|
66
|
+
.optional()
|
|
67
|
+
.describe('501(c) subsection code. "3" = public charity (most common — donations tax-deductible), ' +
|
|
68
|
+
'"4" = social welfare org, "6" = business league/trade association, ' +
|
|
69
|
+
'"92" = 4947(a)(1) nonexempt charitable trust. Filters by tax status, not sector.'),
|
|
70
|
+
page: z
|
|
71
|
+
.number()
|
|
72
|
+
.int()
|
|
73
|
+
.min(0)
|
|
74
|
+
.default(0)
|
|
75
|
+
.describe('Zero-indexed page number. 25 results per page. Total pages is in num_pages. ' +
|
|
76
|
+
'Increment to paginate large result sets.'),
|
|
77
|
+
}),
|
|
78
|
+
output: z.object({
|
|
79
|
+
total_results: z
|
|
80
|
+
.number()
|
|
81
|
+
.describe('Total matching orgs (up to 10,000 — the API ceiling). If 10000, actual count may be higher.'),
|
|
82
|
+
num_pages: z.number().describe('Total pages available (total_results / 25, ceiling).'),
|
|
83
|
+
cur_page: z.number().describe('Current page (zero-indexed).'),
|
|
84
|
+
organizations: z
|
|
85
|
+
.array(z
|
|
86
|
+
.object({
|
|
87
|
+
ein: z
|
|
88
|
+
.number()
|
|
89
|
+
.describe('Employer Identification Number — use with nonprofit_get_organization and nonprofit_get_filings.'),
|
|
90
|
+
strein: z.string().describe('EIN in "XX-XXXXXXX" format (preserves leading zeros).'),
|
|
91
|
+
name: z.string().describe('Legal org name per IRS.'),
|
|
92
|
+
sub_name: z
|
|
93
|
+
.string()
|
|
94
|
+
.nullable()
|
|
95
|
+
.describe('Alternate or subtitle name, or chapter identifier. Null when absent.'),
|
|
96
|
+
city: z.string().nullable().describe('Headquarters city. Null when not on record.'),
|
|
97
|
+
state: z
|
|
98
|
+
.string()
|
|
99
|
+
.nullable()
|
|
100
|
+
.describe('Two-letter state abbreviation. Null when not on record.'),
|
|
101
|
+
ntee_code: z
|
|
102
|
+
.string()
|
|
103
|
+
.nullable()
|
|
104
|
+
.describe('Full NTEE code (e.g., "E210" = hospital). More specific than the ntee_category filter.'),
|
|
105
|
+
subseccd: z
|
|
106
|
+
.number()
|
|
107
|
+
.nullable()
|
|
108
|
+
.describe('501(c) subsection code (e.g., 3 = public charity). Null when not classified.'),
|
|
109
|
+
score: z.number().describe('Relevance score — higher = better match.'),
|
|
110
|
+
})
|
|
111
|
+
.describe('A matched tax-exempt organization.'))
|
|
112
|
+
.describe('Matching organizations for the current page.'),
|
|
113
|
+
active_filters: z
|
|
114
|
+
.object({
|
|
115
|
+
query: z.string().describe('Search query as submitted.'),
|
|
116
|
+
state: z.string().nullable().describe('State filter applied, or null.'),
|
|
117
|
+
ntee_category: z.string().nullable().describe('NTEE major group filter applied, or null.'),
|
|
118
|
+
subsection_code: z
|
|
119
|
+
.string()
|
|
120
|
+
.nullable()
|
|
121
|
+
.describe('501(c) subsection filter applied, or null.'),
|
|
122
|
+
})
|
|
123
|
+
.describe('Active filters echoed back for verification.'),
|
|
124
|
+
data_source: z.string().describe('ProPublica + IRS attribution text.'),
|
|
125
|
+
}),
|
|
126
|
+
errors: [
|
|
127
|
+
{
|
|
128
|
+
reason: 'no_results',
|
|
129
|
+
code: JsonRpcErrorCode.NotFound,
|
|
130
|
+
when: 'No organizations match the given query and filters',
|
|
131
|
+
recovery: 'Broaden the keyword query, remove one or more filters, or check spelling.',
|
|
132
|
+
},
|
|
133
|
+
{
|
|
134
|
+
reason: 'upstream_error',
|
|
135
|
+
code: JsonRpcErrorCode.ServiceUnavailable,
|
|
136
|
+
when: 'ProPublica API returns a 500 or network error',
|
|
137
|
+
retryable: true,
|
|
138
|
+
recovery: "Wait a moment and retry. ProPublica's API is keyless and generally stable.",
|
|
139
|
+
},
|
|
140
|
+
],
|
|
141
|
+
async handler(input, ctx) {
|
|
142
|
+
ctx.log.info('Searching nonprofits', {
|
|
143
|
+
query: input.query,
|
|
144
|
+
state: input.state,
|
|
145
|
+
ntee_category: input.ntee_category,
|
|
146
|
+
subsection_code: input.subsection_code,
|
|
147
|
+
page: input.page,
|
|
148
|
+
});
|
|
149
|
+
const svc = getNonprofitExplorerService();
|
|
150
|
+
const raw = await svc.search(input, ctx);
|
|
151
|
+
const orgs = raw.organizations ?? [];
|
|
152
|
+
const total = raw.total_results ?? 0;
|
|
153
|
+
const numPages = raw.num_pages ?? 0;
|
|
154
|
+
const curPage = raw.cur_page ?? input.page;
|
|
155
|
+
if (orgs.length === 0) {
|
|
156
|
+
throw ctx.fail('no_results', `No organizations matched query="${input.query}" with the active filters.`, { ...ctx.recoveryFor('no_results') });
|
|
157
|
+
}
|
|
158
|
+
return {
|
|
159
|
+
total_results: total,
|
|
160
|
+
num_pages: numPages,
|
|
161
|
+
cur_page: curPage,
|
|
162
|
+
organizations: orgs.map((o) => ({
|
|
163
|
+
ein: o.ein,
|
|
164
|
+
strein: o.strein ?? String(o.ein),
|
|
165
|
+
name: o.name ?? '',
|
|
166
|
+
sub_name: o.sub_name ?? null,
|
|
167
|
+
city: o.city ?? null,
|
|
168
|
+
state: o.state ?? null,
|
|
169
|
+
ntee_code: o.ntee_code ?? null,
|
|
170
|
+
subseccd: o.subseccd ?? null,
|
|
171
|
+
score: o.score ?? 0,
|
|
172
|
+
})),
|
|
173
|
+
active_filters: {
|
|
174
|
+
query: input.query,
|
|
175
|
+
state: input.state ?? null,
|
|
176
|
+
ntee_category: input.ntee_category ?? null,
|
|
177
|
+
subsection_code: input.subsection_code ?? null,
|
|
178
|
+
},
|
|
179
|
+
data_source: raw.data_source ?? 'ProPublica Nonprofit Explorer, IRS Form 990 data.',
|
|
180
|
+
};
|
|
181
|
+
},
|
|
182
|
+
format: (result) => {
|
|
183
|
+
const lines = [];
|
|
184
|
+
lines.push(`**Found:** ${result.total_results.toLocaleString()} total org${result.total_results !== 1 ? 's' : ''} ` +
|
|
185
|
+
`| Page ${result.cur_page} of ${result.num_pages} total pages` +
|
|
186
|
+
(result.total_results === 10000 ? ' — API cap reached; actual count may be higher' : ''));
|
|
187
|
+
lines.push(`**Query:** ${result.active_filters.query}`);
|
|
188
|
+
const filters = [];
|
|
189
|
+
if (result.active_filters.state)
|
|
190
|
+
filters.push(`state=${result.active_filters.state}`);
|
|
191
|
+
if (result.active_filters.ntee_category)
|
|
192
|
+
filters.push(`ntee=${result.active_filters.ntee_category}`);
|
|
193
|
+
if (result.active_filters.subsection_code)
|
|
194
|
+
filters.push(`501(c)=${result.active_filters.subsection_code}`);
|
|
195
|
+
if (filters.length > 0)
|
|
196
|
+
lines.push(`**Filters:** ${filters.join(', ')}`);
|
|
197
|
+
lines.push('');
|
|
198
|
+
for (const org of result.organizations) {
|
|
199
|
+
lines.push(`## ${org.name}`);
|
|
200
|
+
lines.push(`**EIN (int):** ${org.ein} | **EIN:** ${org.strein} | **Score:** ${org.score}`);
|
|
201
|
+
const loc = [org.city, org.state].filter(Boolean).join(', ');
|
|
202
|
+
if (loc)
|
|
203
|
+
lines.push(`**Location:** ${loc}`);
|
|
204
|
+
if (org.ntee_code)
|
|
205
|
+
lines.push(`**NTEE Code:** ${org.ntee_code}`);
|
|
206
|
+
if (org.subseccd != null)
|
|
207
|
+
lines.push(`**501(c):** 501(c)(${org.subseccd})`);
|
|
208
|
+
if (org.sub_name)
|
|
209
|
+
lines.push(`**Alternate Name:** ${org.sub_name}`);
|
|
210
|
+
lines.push('');
|
|
211
|
+
}
|
|
212
|
+
lines.push(`*${result.data_source}*`);
|
|
213
|
+
return [{ type: 'text', text: lines.join('\n') }];
|
|
214
|
+
},
|
|
215
|
+
});
|
|
216
|
+
//# sourceMappingURL=nonprofit-search.tool.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"nonprofit-search.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/nonprofit-search.tool.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview ProPublica Nonprofit Explorer API v2 service layer.
|
|
3
|
+
* Keyless, read-only REST wrapper — search and org-profile endpoints.
|
|
4
|
+
* @module services/nonprofit-explorer/nonprofit-explorer-service
|
|
5
|
+
*/
|
|
6
|
+
import type { Context } from '@cyanheads/mcp-ts-core';
|
|
7
|
+
import type { AppConfig } from '@cyanheads/mcp-ts-core/config';
|
|
8
|
+
import type { StorageService } from '@cyanheads/mcp-ts-core/storage';
|
|
9
|
+
import type { RawOrgResponse, RawSearchResponse, SearchParams } from './types.js';
|
|
10
|
+
export declare class NonprofitExplorerService {
|
|
11
|
+
constructor(_config: AppConfig, _storage: StorageService);
|
|
12
|
+
/**
|
|
13
|
+
* Fetch a URL with timeout, tolerating specific non-2xx statuses instead of throwing.
|
|
14
|
+
* Returns `{ status, text }` — caller decides whether the status is an error.
|
|
15
|
+
* Throws `serviceUnavailable` on network errors or unexpected non-JSON responses.
|
|
16
|
+
*/
|
|
17
|
+
private fetchTolerant;
|
|
18
|
+
/** Search organizations by keyword and optional filters. */
|
|
19
|
+
search(params: SearchParams, ctx: Context): Promise<RawSearchResponse>;
|
|
20
|
+
/**
|
|
21
|
+
* Fetch full organization profile and all filings by EIN.
|
|
22
|
+
* Handles the three not-found signatures and throws notFound when detected.
|
|
23
|
+
*/
|
|
24
|
+
getOrganization(ein: number, ctx: Context): Promise<RawOrgResponse>;
|
|
25
|
+
/** Parse JSON from an upstream response; throws serviceUnavailable on HTML error pages. */
|
|
26
|
+
private parseJson;
|
|
27
|
+
}
|
|
28
|
+
export declare function initNonprofitExplorerService(config: AppConfig, storage: StorageService): void;
|
|
29
|
+
export declare function getNonprofitExplorerService(): NonprofitExplorerService;
|
|
30
|
+
/** Normalize an EIN input (number or string with/without hyphen) to an integer. */
|
|
31
|
+
export declare function normalizeEin(ein: number | string): number;
|
|
32
|
+
/**
|
|
33
|
+
* Format an EIN integer as "XX-XXXXXXX" string.
|
|
34
|
+
* EINs are 9 digits; the first two form the prefix. Leading zeros are preserved via padding.
|
|
35
|
+
*/
|
|
36
|
+
export declare function formatEin(ein: number): string;
|
|
37
|
+
//# sourceMappingURL=nonprofit-explorer-service.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"nonprofit-explorer-service.d.ts","sourceRoot":"","sources":["../../../src/services/nonprofit-explorer/nonprofit-explorer-service.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAE/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAErE,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAKlF,qBAAa,wBAAwB;gBAGvB,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,cAAc;IAExD;;;;OAIG;YACW,aAAa;IAkD3B,4DAA4D;IAC5D,MAAM,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA2BtE;;;OAGG;IACH,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,CAAC;IAmDnE,2FAA2F;IAC3F,OAAO,CAAC,SAAS;CAgBlB;AAMD,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAE7F;AAED,wBAAgB,2BAA2B,IAAI,wBAAwB,CAOtE;AAED,mFAAmF;AACnF,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAGzD;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAG7C"}
|