@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/dist/index.js
ADDED
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* @fileoverview nonprofit-explorer-mcp-server MCP server entry point.
|
|
4
|
+
* @module index
|
|
5
|
+
*/
|
|
6
|
+
import { createApp } from '@cyanheads/mcp-ts-core';
|
|
7
|
+
import { nonprofitGetFilings } from './mcp-server/tools/definitions/nonprofit-get-filings.tool.js';
|
|
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';
|
|
10
|
+
import { initNonprofitExplorerService } from './services/nonprofit-explorer/nonprofit-explorer-service.js';
|
|
11
|
+
await createApp({
|
|
12
|
+
tools: [nonprofitSearch, nonprofitGetOrganization, nonprofitGetFilings],
|
|
13
|
+
resources: [],
|
|
14
|
+
prompts: [],
|
|
15
|
+
setup(core) {
|
|
16
|
+
initNonprofitExplorerService(core.config, core.storage);
|
|
17
|
+
},
|
|
18
|
+
instructions: 'ProPublica Nonprofit Explorer — keyless read-only access to IRS Form 990 data on 1.8M+ tax-exempt organizations.\n' +
|
|
19
|
+
'- Start with nonprofit_search to find an org by name and get its EIN\n' +
|
|
20
|
+
'- Use nonprofit_get_organization for the full profile and latest financial snapshot\n' +
|
|
21
|
+
'- Use nonprofit_get_filings for year-by-year 990 data, program expense ratios, executive comp, and PDF links\n' +
|
|
22
|
+
'- Data lags 1–2 years; always cite the fiscal year (tax_prd_yr) when presenting financial figures',
|
|
23
|
+
});
|
|
24
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +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,KAAK,EAAE,CAAC,eAAe,EAAE,wBAAwB,EAAE,mBAAmB,CAAC;IACvE,SAAS,EAAE,EAAE;IACb,OAAO,EAAE,EAAE;IACX,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,gHAAgH;QAChH,mGAAmG;CACtG,CAAC,CAAC"}
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview All Form 990 filings for an org with financials, program-expense ratio, and PDF links.
|
|
3
|
+
* @module mcp-server/tools/definitions/nonprofit-get-filings.tool
|
|
4
|
+
*/
|
|
5
|
+
import { z } from '@cyanheads/mcp-ts-core';
|
|
6
|
+
import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
|
|
7
|
+
export declare const nonprofitGetFilings: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
|
|
8
|
+
ein: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
|
|
9
|
+
}, z.core.$strip>, z.ZodObject<{
|
|
10
|
+
ein: z.ZodNumber;
|
|
11
|
+
name: z.ZodString;
|
|
12
|
+
filings: z.ZodArray<z.ZodObject<{
|
|
13
|
+
tax_prd_yr: z.ZodNumber;
|
|
14
|
+
tax_prd: z.ZodNumber;
|
|
15
|
+
form_type: z.ZodEnum<{
|
|
16
|
+
990: "990";
|
|
17
|
+
"990-EZ": "990-EZ";
|
|
18
|
+
"990-PF": "990-PF";
|
|
19
|
+
}>;
|
|
20
|
+
pdf_url: z.ZodNullable<z.ZodString>;
|
|
21
|
+
updated: z.ZodNullable<z.ZodString>;
|
|
22
|
+
total_revenue: z.ZodNullable<z.ZodNumber>;
|
|
23
|
+
total_expenses: z.ZodNullable<z.ZodNumber>;
|
|
24
|
+
total_assets: z.ZodNullable<z.ZodNumber>;
|
|
25
|
+
total_liabilities: z.ZodNullable<z.ZodNumber>;
|
|
26
|
+
net_assets: z.ZodNullable<z.ZodNumber>;
|
|
27
|
+
contributions_and_grants: z.ZodNullable<z.ZodNumber>;
|
|
28
|
+
program_service_revenue: z.ZodNullable<z.ZodNumber>;
|
|
29
|
+
investment_income: z.ZodNullable<z.ZodNumber>;
|
|
30
|
+
program_expense_ratio: z.ZodNullable<z.ZodObject<{
|
|
31
|
+
ratio: z.ZodNullable<z.ZodNumber>;
|
|
32
|
+
program_expenses: z.ZodNullable<z.ZodNumber>;
|
|
33
|
+
total_expenses: z.ZodNullable<z.ZodNumber>;
|
|
34
|
+
management_compensation: z.ZodNullable<z.ZodNumber>;
|
|
35
|
+
other_salaries: z.ZodNullable<z.ZodNumber>;
|
|
36
|
+
fundraising_expenses: z.ZodNullable<z.ZodNumber>;
|
|
37
|
+
note: z.ZodString;
|
|
38
|
+
}, z.core.$strip>>;
|
|
39
|
+
executive_compensation: z.ZodNullable<z.ZodObject<{
|
|
40
|
+
amount: z.ZodNullable<z.ZodNumber>;
|
|
41
|
+
field_name: z.ZodString;
|
|
42
|
+
form_type: z.ZodString;
|
|
43
|
+
note: z.ZodString;
|
|
44
|
+
}, z.core.$strip>>;
|
|
45
|
+
}, z.core.$strip>>;
|
|
46
|
+
filings_pdf_only: z.ZodArray<z.ZodObject<{
|
|
47
|
+
tax_prd_yr: z.ZodNumber;
|
|
48
|
+
form_type_str: z.ZodString;
|
|
49
|
+
pdf_url: z.ZodNullable<z.ZodString>;
|
|
50
|
+
}, z.core.$strip>>;
|
|
51
|
+
total_filings_with_data: z.ZodNumber;
|
|
52
|
+
total_filings_pdf_only: z.ZodNumber;
|
|
53
|
+
data_source: z.ZodString;
|
|
54
|
+
propublica_url: z.ZodString;
|
|
55
|
+
}, z.core.$strip>, readonly [{
|
|
56
|
+
readonly reason: "not_found";
|
|
57
|
+
readonly code: JsonRpcErrorCode.NotFound;
|
|
58
|
+
readonly when: "The EIN does not correspond to a known organization in the Nonprofit Explorer database";
|
|
59
|
+
readonly recovery: "Verify the EIN with nonprofit_search. Use the integer EIN value (leading zeros stripped).";
|
|
60
|
+
}, {
|
|
61
|
+
readonly reason: "no_filings";
|
|
62
|
+
readonly code: JsonRpcErrorCode.NotFound;
|
|
63
|
+
readonly when: "Org is known but has no Form 990 data in Nonprofit Explorer — typically a small org filing Form 990N (e-Postcard)";
|
|
64
|
+
readonly recovery: string;
|
|
65
|
+
}, {
|
|
66
|
+
readonly reason: "upstream_error";
|
|
67
|
+
readonly code: JsonRpcErrorCode.ServiceUnavailable;
|
|
68
|
+
readonly when: "ProPublica API returns a non-JSON body or network error";
|
|
69
|
+
readonly retryable: true;
|
|
70
|
+
readonly recovery: "Wait a moment and retry.";
|
|
71
|
+
}], undefined>;
|
|
72
|
+
//# sourceMappingURL=nonprofit-get-filings.tool.d.ts.map
|
|
@@ -0,0 +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;AAkGjE,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAiY9B,CAAC"}
|
|
@@ -0,0 +1,391 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview All Form 990 filings for an org with financials, program-expense ratio, and PDF links.
|
|
3
|
+
* @module mcp-server/tools/definitions/nonprofit-get-filings.tool
|
|
4
|
+
*/
|
|
5
|
+
import { tool, z } from '@cyanheads/mcp-ts-core';
|
|
6
|
+
import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
|
|
7
|
+
import { getNonprofitExplorerService, normalizeEin, } from '../../../services/nonprofit-explorer/nonprofit-explorer-service.js';
|
|
8
|
+
const USD = (n) => `$${n.toLocaleString()}`;
|
|
9
|
+
const PCT = (n) => `${(n * 100).toFixed(1)}%`;
|
|
10
|
+
/** Map formtype integer to form label. */
|
|
11
|
+
function formTypeLabel(ft) {
|
|
12
|
+
if (ft === 1)
|
|
13
|
+
return '990-EZ';
|
|
14
|
+
if (ft === 2)
|
|
15
|
+
return '990-PF';
|
|
16
|
+
return '990';
|
|
17
|
+
}
|
|
18
|
+
/** Compute program-expense ratio for 990/990-EZ (formtype 0 or 1). Returns null for 990-PF. */
|
|
19
|
+
function computeProgramExpenseRatio(filing) {
|
|
20
|
+
if (filing.formtype === 2) {
|
|
21
|
+
// 990-PF: fields not available
|
|
22
|
+
return null;
|
|
23
|
+
}
|
|
24
|
+
const total = filing.totfuncexpns ?? null;
|
|
25
|
+
const officerComp = filing.compnsatncurrofcr ?? null;
|
|
26
|
+
const otherSalaries = filing.othrsalwages ?? null;
|
|
27
|
+
const fundraising = filing.profndraising ?? null;
|
|
28
|
+
// Only compute ratio when we have enough inputs
|
|
29
|
+
let ratio = null;
|
|
30
|
+
let programExpenses = null;
|
|
31
|
+
if (total != null &&
|
|
32
|
+
officerComp != null &&
|
|
33
|
+
otherSalaries != null &&
|
|
34
|
+
fundraising != null &&
|
|
35
|
+
total > 0) {
|
|
36
|
+
programExpenses = total - officerComp - otherSalaries - fundraising;
|
|
37
|
+
ratio = programExpenses / total;
|
|
38
|
+
}
|
|
39
|
+
else if (total != null && total > 0) {
|
|
40
|
+
// Partial: compute what we can
|
|
41
|
+
const deductions = (officerComp ?? 0) + (otherSalaries ?? 0) + (fundraising ?? 0);
|
|
42
|
+
programExpenses = total - deductions;
|
|
43
|
+
ratio = programExpenses / total;
|
|
44
|
+
}
|
|
45
|
+
return {
|
|
46
|
+
ratio,
|
|
47
|
+
program_expenses: programExpenses,
|
|
48
|
+
total_expenses: total,
|
|
49
|
+
management_compensation: officerComp,
|
|
50
|
+
other_salaries: otherSalaries,
|
|
51
|
+
fundraising_expenses: fundraising,
|
|
52
|
+
note: 'Program expenses = total − officer/director comp − other salaries/wages − professional fundraising. ' +
|
|
53
|
+
'Approximation — consult the source PDF Part IX for the full expense schedule.',
|
|
54
|
+
};
|
|
55
|
+
}
|
|
56
|
+
/** Build executive compensation object. Returns null if no compensation field available. */
|
|
57
|
+
function buildExecComp(filing) {
|
|
58
|
+
if (filing.formtype === 2) {
|
|
59
|
+
// 990-PF: compofficers (may be null/absent in the extract)
|
|
60
|
+
return {
|
|
61
|
+
amount: filing.compofficers ?? null,
|
|
62
|
+
field_name: 'compofficers',
|
|
63
|
+
form_type: '990-PF',
|
|
64
|
+
note: '990-PF: compensation of officers, directors, trustees.',
|
|
65
|
+
};
|
|
66
|
+
}
|
|
67
|
+
// 990 / 990-EZ: compnsatncurrofcr
|
|
68
|
+
return {
|
|
69
|
+
amount: filing.compnsatncurrofcr ?? null,
|
|
70
|
+
field_name: 'compnsatncurrofcr',
|
|
71
|
+
form_type: filing.formtype === 1 ? '990-EZ' : '990',
|
|
72
|
+
note: '990/990-EZ: total compensation of current officers, directors, trustees, and key employees. ' +
|
|
73
|
+
'Per-officer breakdown requires Schedule J in the source PDF.',
|
|
74
|
+
};
|
|
75
|
+
}
|
|
76
|
+
export const nonprofitGetFilings = tool('nonprofit_get_filings', {
|
|
77
|
+
title: 'Get Nonprofit Filings',
|
|
78
|
+
description: 'All Form 990 filings for a tax-exempt org by EIN: year-by-year revenue, expenses, assets, ' +
|
|
79
|
+
'program-expense ratio (with inputs shown), executive compensation, and source PDF/XML links. ' +
|
|
80
|
+
'Use for trend analysis, due diligence, and accessing primary 990 documents. ' +
|
|
81
|
+
'The filing year (tax_prd_yr) is the fiscal year of the return — data lags 1–2 years; always cite the year. ' +
|
|
82
|
+
'Program expense ratio is computed as (total_expenses − officer comp − other wages − fundraising) / total_expenses ' +
|
|
83
|
+
'for 990/990-EZ; not available for 990-PF. ' +
|
|
84
|
+
'Also returns filings_pdf_only — older filings with a PDF but no extracted financial data. ' +
|
|
85
|
+
'Data from ProPublica Nonprofit Explorer, sourced from IRS Form 990 filings.',
|
|
86
|
+
annotations: { readOnlyHint: true, idempotentHint: true },
|
|
87
|
+
input: z.object({
|
|
88
|
+
ein: z
|
|
89
|
+
.union([
|
|
90
|
+
z
|
|
91
|
+
.number()
|
|
92
|
+
.int()
|
|
93
|
+
.positive()
|
|
94
|
+
.describe('EIN as integer (e.g., 530196605). Leading zeros are stripped — treat EIN as an integer key.'),
|
|
95
|
+
z
|
|
96
|
+
.string()
|
|
97
|
+
.regex(/^\d{2}-?\d{7}$/)
|
|
98
|
+
.describe('EIN as string, with or without hyphen (e.g., "53-0196605" or "530196605").'),
|
|
99
|
+
])
|
|
100
|
+
.describe('Employer Identification Number. Use nonprofit_search to resolve an org name to its EIN.'),
|
|
101
|
+
}),
|
|
102
|
+
output: z.object({
|
|
103
|
+
ein: z.number().describe('Employer Identification Number as integer.'),
|
|
104
|
+
name: z.string().describe('Legal org name per IRS.'),
|
|
105
|
+
filings: z
|
|
106
|
+
.array(z
|
|
107
|
+
.object({
|
|
108
|
+
tax_prd_yr: z
|
|
109
|
+
.number()
|
|
110
|
+
.describe('Fiscal year of this filing (e.g., 2023). NOT the filing date — data lags 1–2 years. Always cite.'),
|
|
111
|
+
tax_prd: z
|
|
112
|
+
.number()
|
|
113
|
+
.describe('YYYYMM month the fiscal year ended (e.g., 202306 = June 2023 fiscal year end).'),
|
|
114
|
+
form_type: z.enum(['990', '990-EZ', '990-PF']).describe('IRS form type filed.'),
|
|
115
|
+
pdf_url: z
|
|
116
|
+
.string()
|
|
117
|
+
.nullable()
|
|
118
|
+
.describe('Source Form 990 PDF link. Null for some IRS processing batches — check filings_pdf_only.'),
|
|
119
|
+
updated: z
|
|
120
|
+
.string()
|
|
121
|
+
.nullable()
|
|
122
|
+
.describe('ISO datetime ProPublica last updated this record. Null when not provided.'),
|
|
123
|
+
total_revenue: z
|
|
124
|
+
.number()
|
|
125
|
+
.nullable()
|
|
126
|
+
.describe('Total revenue in USD. Null when not extracted.'),
|
|
127
|
+
total_expenses: z
|
|
128
|
+
.number()
|
|
129
|
+
.nullable()
|
|
130
|
+
.describe('Total expenses in USD. Null when not extracted.'),
|
|
131
|
+
total_assets: z
|
|
132
|
+
.number()
|
|
133
|
+
.nullable()
|
|
134
|
+
.describe('Total assets (end of year) in USD. Null when not extracted.'),
|
|
135
|
+
total_liabilities: z
|
|
136
|
+
.number()
|
|
137
|
+
.nullable()
|
|
138
|
+
.describe('Total liabilities (end of year) in USD. Null when not extracted.'),
|
|
139
|
+
net_assets: z
|
|
140
|
+
.number()
|
|
141
|
+
.nullable()
|
|
142
|
+
.describe('Net assets/fund balances (end of year) in USD. From totnetassetend. Null when not extracted.'),
|
|
143
|
+
contributions_and_grants: z
|
|
144
|
+
.number()
|
|
145
|
+
.nullable()
|
|
146
|
+
.describe('Total contributions and grants (totcntrbgfts). 990/990-EZ only; null for 990-PF.'),
|
|
147
|
+
program_service_revenue: z
|
|
148
|
+
.number()
|
|
149
|
+
.nullable()
|
|
150
|
+
.describe('Program service revenue (totprgmrevnue). 990/990-EZ only; null for 990-PF.'),
|
|
151
|
+
investment_income: z
|
|
152
|
+
.number()
|
|
153
|
+
.nullable()
|
|
154
|
+
.describe('Investment income (invstmntinc). 990/990-EZ only; null for 990-PF.'),
|
|
155
|
+
program_expense_ratio: z
|
|
156
|
+
.object({
|
|
157
|
+
ratio: z
|
|
158
|
+
.number()
|
|
159
|
+
.nullable()
|
|
160
|
+
.describe('Program expense ratio as decimal 0.0–1.0. Null if inputs insufficient.'),
|
|
161
|
+
program_expenses: z
|
|
162
|
+
.number()
|
|
163
|
+
.nullable()
|
|
164
|
+
.describe('Computed program expenses (total − officer comp − other wages − fundraising) in USD.'),
|
|
165
|
+
total_expenses: z
|
|
166
|
+
.number()
|
|
167
|
+
.nullable()
|
|
168
|
+
.describe('Total functional expenses (denominator) in USD. From totfuncexpns.'),
|
|
169
|
+
management_compensation: z
|
|
170
|
+
.number()
|
|
171
|
+
.nullable()
|
|
172
|
+
.describe('Officer/director/trustee compensation (compnsatncurrofcr) in USD. Null when not reported.'),
|
|
173
|
+
other_salaries: z
|
|
174
|
+
.number()
|
|
175
|
+
.nullable()
|
|
176
|
+
.describe('Other salaries and wages (othrsalwages) in USD. Null when not reported.'),
|
|
177
|
+
fundraising_expenses: z
|
|
178
|
+
.number()
|
|
179
|
+
.nullable()
|
|
180
|
+
.describe('Professional fundraising fees (profndraising) in USD. Null when not reported.'),
|
|
181
|
+
note: z
|
|
182
|
+
.string()
|
|
183
|
+
.describe('Methodology note explaining the computation and its limitations.'),
|
|
184
|
+
})
|
|
185
|
+
.nullable()
|
|
186
|
+
.describe('Program-expense ratio with inputs. Null for 990-PF (different field set). ' +
|
|
187
|
+
'Approximation — consult the source PDF for the full expense schedule.'),
|
|
188
|
+
executive_compensation: z
|
|
189
|
+
.object({
|
|
190
|
+
amount: z
|
|
191
|
+
.number()
|
|
192
|
+
.nullable()
|
|
193
|
+
.describe('Total executive compensation in USD. Null when not reported.'),
|
|
194
|
+
field_name: z
|
|
195
|
+
.string()
|
|
196
|
+
.describe('Source API field name for transparency (compnsatncurrofcr or compofficers).'),
|
|
197
|
+
form_type: z
|
|
198
|
+
.string()
|
|
199
|
+
.describe('Form type this compensation field is sourced from.'),
|
|
200
|
+
note: z
|
|
201
|
+
.string()
|
|
202
|
+
.describe('Plain-English description of what this field covers and where to find per-officer detail.'),
|
|
203
|
+
})
|
|
204
|
+
.nullable()
|
|
205
|
+
.describe('Executive compensation summary. Field varies by form type. ' +
|
|
206
|
+
'Per-officer breakdown requires Schedule J in the source PDF.'),
|
|
207
|
+
})
|
|
208
|
+
.describe('Form 990 filing with extracted financial data for one fiscal year.'))
|
|
209
|
+
.describe('Filings with extracted financial data, sorted newest first.'),
|
|
210
|
+
filings_pdf_only: z
|
|
211
|
+
.array(z
|
|
212
|
+
.object({
|
|
213
|
+
tax_prd_yr: z.number().describe('Fiscal year of this filing.'),
|
|
214
|
+
form_type_str: z
|
|
215
|
+
.string()
|
|
216
|
+
.describe('Form type string as returned by API ("990", "990EZ", "990PF").'),
|
|
217
|
+
pdf_url: z
|
|
218
|
+
.string()
|
|
219
|
+
.nullable()
|
|
220
|
+
.describe('Source Form 990 PDF link. Null for some batches.'),
|
|
221
|
+
})
|
|
222
|
+
.describe('Older filing with a PDF link but no extracted financial data.'))
|
|
223
|
+
.describe('Older filings with a PDF but no extracted financial data.'),
|
|
224
|
+
total_filings_with_data: z.number().describe('Count of filings with extracted financial data.'),
|
|
225
|
+
total_filings_pdf_only: z.number().describe('Count of PDF-only filings (no extracted data).'),
|
|
226
|
+
data_source: z.string().describe('ProPublica + IRS attribution text.'),
|
|
227
|
+
propublica_url: z.string().describe('ProPublica Nonprofit Explorer URL for this org.'),
|
|
228
|
+
}),
|
|
229
|
+
errors: [
|
|
230
|
+
{
|
|
231
|
+
reason: 'not_found',
|
|
232
|
+
code: JsonRpcErrorCode.NotFound,
|
|
233
|
+
when: 'The EIN does not correspond to a known organization in the Nonprofit Explorer database',
|
|
234
|
+
recovery: 'Verify the EIN with nonprofit_search. Use the integer EIN value (leading zeros stripped).',
|
|
235
|
+
},
|
|
236
|
+
{
|
|
237
|
+
reason: 'no_filings',
|
|
238
|
+
code: JsonRpcErrorCode.NotFound,
|
|
239
|
+
when: 'Org is known but has no Form 990 data in Nonprofit Explorer — typically a small org filing Form 990N (e-Postcard)',
|
|
240
|
+
recovery: 'Small organizations with under $50,000 in revenue file Form 990N (e-Postcard), ' +
|
|
241
|
+
'which is not included in Nonprofit Explorer. The org exists but has no 990 data to display.',
|
|
242
|
+
},
|
|
243
|
+
{
|
|
244
|
+
reason: 'upstream_error',
|
|
245
|
+
code: JsonRpcErrorCode.ServiceUnavailable,
|
|
246
|
+
when: 'ProPublica API returns a non-JSON body or network error',
|
|
247
|
+
retryable: true,
|
|
248
|
+
recovery: 'Wait a moment and retry.',
|
|
249
|
+
},
|
|
250
|
+
],
|
|
251
|
+
async handler(input, ctx) {
|
|
252
|
+
const ein = normalizeEin(input.ein);
|
|
253
|
+
ctx.log.info('Fetching nonprofit filings', { ein });
|
|
254
|
+
const svc = getNonprofitExplorerService();
|
|
255
|
+
// Service throws notFound (reason: 'not_found') or serviceUnavailable (reason: 'upstream_error').
|
|
256
|
+
const raw = await svc.getOrganization(ein, ctx);
|
|
257
|
+
// Service validates organization presence and throws notFound before returning — safe to assert.
|
|
258
|
+
// biome-ignore lint/style/noNonNullAssertion: guaranteed by service not-found checks
|
|
259
|
+
const org = raw.organization;
|
|
260
|
+
const filingsWithData = raw.filings_with_data ?? [];
|
|
261
|
+
const filingsWithoutData = raw.filings_without_data ?? [];
|
|
262
|
+
// Check for org with no filings at all (small org, 990N filer)
|
|
263
|
+
if (filingsWithData.length === 0 && filingsWithoutData.length === 0) {
|
|
264
|
+
throw ctx.fail('no_filings', `Organization "${org.name}" (EIN ${ein}) has no Form 990 data in Nonprofit Explorer. ` +
|
|
265
|
+
'It may file Form 990N (e-Postcard) for organizations with under $50,000 in annual revenue.', { ...ctx.recoveryFor('no_filings') });
|
|
266
|
+
}
|
|
267
|
+
// Sort by fiscal year descending (newest first)
|
|
268
|
+
const sortedFilings = [...filingsWithData].sort((a, b) => (b.tax_prd_yr ?? 0) - (a.tax_prd_yr ?? 0));
|
|
269
|
+
const mappedFilings = sortedFilings.map((f) => ({
|
|
270
|
+
tax_prd_yr: f.tax_prd_yr ?? 0,
|
|
271
|
+
tax_prd: f.tax_prd ?? 0,
|
|
272
|
+
form_type: formTypeLabel(f.formtype),
|
|
273
|
+
pdf_url: f.pdf_url ?? null,
|
|
274
|
+
updated: f.updated ?? null,
|
|
275
|
+
total_revenue: f.totrevenue ?? null,
|
|
276
|
+
total_expenses: f.totfuncexpns ?? null,
|
|
277
|
+
total_assets: f.totassetsend ?? null,
|
|
278
|
+
total_liabilities: f.totliabend ?? null,
|
|
279
|
+
net_assets: f.totnetassetend ?? null,
|
|
280
|
+
contributions_and_grants: f.totcntrbgfts ?? null,
|
|
281
|
+
program_service_revenue: f.totprgmrevnue ?? null,
|
|
282
|
+
investment_income: f.invstmntinc ?? null,
|
|
283
|
+
program_expense_ratio: computeProgramExpenseRatio(f),
|
|
284
|
+
executive_compensation: buildExecComp(f),
|
|
285
|
+
}));
|
|
286
|
+
const mappedPdfOnly = filingsWithoutData.map((f) => ({
|
|
287
|
+
tax_prd_yr: f.tax_prd_yr ?? 0,
|
|
288
|
+
form_type_str: f.formtype_str ?? '',
|
|
289
|
+
pdf_url: f.pdf_url ?? null,
|
|
290
|
+
}));
|
|
291
|
+
const einNum = org.ein ?? ein;
|
|
292
|
+
return {
|
|
293
|
+
ein: einNum,
|
|
294
|
+
name: org.name ?? '',
|
|
295
|
+
filings: mappedFilings,
|
|
296
|
+
filings_pdf_only: mappedPdfOnly,
|
|
297
|
+
total_filings_with_data: filingsWithData.length,
|
|
298
|
+
total_filings_pdf_only: filingsWithoutData.length,
|
|
299
|
+
data_source: raw.data_source ?? 'ProPublica Nonprofit Explorer, IRS Form 990 data.',
|
|
300
|
+
propublica_url: `https://projects.propublica.org/nonprofits/organizations/${einNum}`,
|
|
301
|
+
};
|
|
302
|
+
},
|
|
303
|
+
format: (result) => {
|
|
304
|
+
const lines = [];
|
|
305
|
+
lines.push(`# ${result.name} — Form 990 Filings`);
|
|
306
|
+
lines.push(`**EIN:** ${result.ein}`);
|
|
307
|
+
lines.push(`**Filings with data:** ${result.total_filings_with_data} | ` +
|
|
308
|
+
`**PDF-only filings:** ${result.total_filings_pdf_only}`);
|
|
309
|
+
lines.push(`**Profile:** ${result.propublica_url}`);
|
|
310
|
+
lines.push('');
|
|
311
|
+
lines.push('> ⚠️ Data lags 1–2 years. FY shown is the fiscal year, not the current year. Always cite the year.');
|
|
312
|
+
for (const f of result.filings) {
|
|
313
|
+
lines.push('');
|
|
314
|
+
lines.push(`## FY ${f.tax_prd_yr} — ${f.form_type} (period: ${f.tax_prd})`);
|
|
315
|
+
if (f.pdf_url) {
|
|
316
|
+
lines.push(`**Source 990 PDF:** ${f.pdf_url}`);
|
|
317
|
+
}
|
|
318
|
+
else {
|
|
319
|
+
lines.push('**Source 990 PDF:** Not yet available for this period');
|
|
320
|
+
}
|
|
321
|
+
if (f.updated)
|
|
322
|
+
lines.push(`**Last updated:** ${f.updated}`);
|
|
323
|
+
lines.push('');
|
|
324
|
+
lines.push('### Financials');
|
|
325
|
+
if (f.total_revenue != null)
|
|
326
|
+
lines.push(`**Revenue:** ${USD(f.total_revenue)}`);
|
|
327
|
+
if (f.total_expenses != null)
|
|
328
|
+
lines.push(`**Expenses:** ${USD(f.total_expenses)}`);
|
|
329
|
+
if (f.total_assets != null)
|
|
330
|
+
lines.push(`**Assets (EoY):** ${USD(f.total_assets)}`);
|
|
331
|
+
if (f.total_liabilities != null)
|
|
332
|
+
lines.push(`**Liabilities (EoY):** ${USD(f.total_liabilities)}`);
|
|
333
|
+
if (f.net_assets != null)
|
|
334
|
+
lines.push(`**Net Assets (EoY):** ${USD(f.net_assets)}`);
|
|
335
|
+
if (f.contributions_and_grants != null ||
|
|
336
|
+
f.program_service_revenue != null ||
|
|
337
|
+
f.investment_income != null) {
|
|
338
|
+
lines.push('');
|
|
339
|
+
lines.push('### Revenue Breakdown');
|
|
340
|
+
if (f.contributions_and_grants != null)
|
|
341
|
+
lines.push(`**Contributions & Grants:** ${USD(f.contributions_and_grants)}`);
|
|
342
|
+
if (f.program_service_revenue != null)
|
|
343
|
+
lines.push(`**Program Service Revenue:** ${USD(f.program_service_revenue)}`);
|
|
344
|
+
if (f.investment_income != null)
|
|
345
|
+
lines.push(`**Investment Income:** ${USD(f.investment_income)}`);
|
|
346
|
+
}
|
|
347
|
+
if (f.program_expense_ratio != null) {
|
|
348
|
+
const r = f.program_expense_ratio;
|
|
349
|
+
lines.push('');
|
|
350
|
+
lines.push('### Program Expense Ratio');
|
|
351
|
+
if (r.ratio != null)
|
|
352
|
+
lines.push(`**Ratio:** ${PCT(r.ratio)}`);
|
|
353
|
+
if (r.program_expenses != null)
|
|
354
|
+
lines.push(`**Program Expenses:** ${USD(r.program_expenses)}`);
|
|
355
|
+
if (r.total_expenses != null)
|
|
356
|
+
lines.push(`**Total Expenses (denominator):** ${USD(r.total_expenses)}`);
|
|
357
|
+
if (r.management_compensation != null)
|
|
358
|
+
lines.push(`**Officer/Director Comp:** ${USD(r.management_compensation)}`);
|
|
359
|
+
if (r.other_salaries != null)
|
|
360
|
+
lines.push(`**Other Salaries & Wages:** ${USD(r.other_salaries)}`);
|
|
361
|
+
if (r.fundraising_expenses != null)
|
|
362
|
+
lines.push(`**Professional Fundraising:** ${USD(r.fundraising_expenses)}`);
|
|
363
|
+
lines.push(`*${r.note}*`);
|
|
364
|
+
}
|
|
365
|
+
if (f.executive_compensation != null) {
|
|
366
|
+
const ec = f.executive_compensation;
|
|
367
|
+
lines.push('');
|
|
368
|
+
lines.push(`### Executive Compensation (${ec.form_type})`);
|
|
369
|
+
if (ec.amount != null) {
|
|
370
|
+
lines.push(`**Total (${ec.field_name}):** ${USD(ec.amount)}`);
|
|
371
|
+
}
|
|
372
|
+
else {
|
|
373
|
+
lines.push(`**Total (${ec.field_name}):** Not reported`);
|
|
374
|
+
}
|
|
375
|
+
lines.push(`*${ec.note}*`);
|
|
376
|
+
}
|
|
377
|
+
}
|
|
378
|
+
if (result.filings_pdf_only.length > 0) {
|
|
379
|
+
lines.push('');
|
|
380
|
+
lines.push('## Older Filings (PDF only — no extracted data)');
|
|
381
|
+
for (const f of result.filings_pdf_only) {
|
|
382
|
+
const pdfLine = f.pdf_url ? `[PDF](${f.pdf_url})` : 'PDF not available';
|
|
383
|
+
lines.push(`- FY ${f.tax_prd_yr} ${f.form_type_str}: ${pdfLine}`);
|
|
384
|
+
}
|
|
385
|
+
}
|
|
386
|
+
lines.push('');
|
|
387
|
+
lines.push(`*${result.data_source}*`);
|
|
388
|
+
return [{ type: 'text', text: lines.join('\n') }];
|
|
389
|
+
},
|
|
390
|
+
});
|
|
391
|
+
//# sourceMappingURL=nonprofit-get-filings.tool.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"nonprofit-get-filings.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/nonprofit-get-filings.tool.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,53 @@
|
|
|
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 { z } from '@cyanheads/mcp-ts-core';
|
|
6
|
+
import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
|
|
7
|
+
export declare const nonprofitGetOrganization: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
|
|
8
|
+
ein: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
|
|
9
|
+
}, z.core.$strip>, z.ZodObject<{
|
|
10
|
+
ein: z.ZodNumber;
|
|
11
|
+
strein: z.ZodString;
|
|
12
|
+
name: z.ZodString;
|
|
13
|
+
sort_name: z.ZodNullable<z.ZodString>;
|
|
14
|
+
address: z.ZodNullable<z.ZodString>;
|
|
15
|
+
city: z.ZodNullable<z.ZodString>;
|
|
16
|
+
state: z.ZodNullable<z.ZodString>;
|
|
17
|
+
zipcode: z.ZodNullable<z.ZodString>;
|
|
18
|
+
ntee_code: z.ZodNullable<z.ZodString>;
|
|
19
|
+
subsection_code: z.ZodNullable<z.ZodNumber>;
|
|
20
|
+
ruling_date: z.ZodNullable<z.ZodString>;
|
|
21
|
+
asset_amount: z.ZodNullable<z.ZodNumber>;
|
|
22
|
+
income_amount: z.ZodNullable<z.ZodNumber>;
|
|
23
|
+
revenue_amount: z.ZodNullable<z.ZodNumber>;
|
|
24
|
+
latest_filing: z.ZodNullable<z.ZodObject<{
|
|
25
|
+
tax_prd_yr: z.ZodNumber;
|
|
26
|
+
form_type: z.ZodEnum<{
|
|
27
|
+
990: "990";
|
|
28
|
+
"990-EZ": "990-EZ";
|
|
29
|
+
"990-PF": "990-PF";
|
|
30
|
+
}>;
|
|
31
|
+
total_revenue: z.ZodNullable<z.ZodNumber>;
|
|
32
|
+
total_expenses: z.ZodNullable<z.ZodNumber>;
|
|
33
|
+
total_assets: z.ZodNullable<z.ZodNumber>;
|
|
34
|
+
total_liabilities: z.ZodNullable<z.ZodNumber>;
|
|
35
|
+
net_assets: z.ZodNullable<z.ZodNumber>;
|
|
36
|
+
pdf_url: z.ZodNullable<z.ZodString>;
|
|
37
|
+
}, z.core.$strip>>;
|
|
38
|
+
filing_count: z.ZodNumber;
|
|
39
|
+
data_source: z.ZodString;
|
|
40
|
+
propublica_url: z.ZodString;
|
|
41
|
+
}, z.core.$strip>, readonly [{
|
|
42
|
+
readonly reason: "not_found";
|
|
43
|
+
readonly code: JsonRpcErrorCode.NotFound;
|
|
44
|
+
readonly when: "The EIN does not correspond to a known organization in the Nonprofit Explorer database";
|
|
45
|
+
readonly recovery: "Verify the EIN with nonprofit_search. EINs with leading zeros are stored without them — try the integer value.";
|
|
46
|
+
}, {
|
|
47
|
+
readonly reason: "upstream_error";
|
|
48
|
+
readonly code: JsonRpcErrorCode.ServiceUnavailable;
|
|
49
|
+
readonly when: "ProPublica API returns a non-JSON body (HTML 500) or network error";
|
|
50
|
+
readonly retryable: true;
|
|
51
|
+
readonly recovery: "Wait a moment and retry.";
|
|
52
|
+
}], undefined>;
|
|
53
|
+
//# sourceMappingURL=nonprofit-get-organization.tool.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"nonprofit-get-organization.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/nonprofit-get-organization.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAgBjE,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA2PnC,CAAC"}
|