@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,171 @@
|
|
|
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 { McpError, notFound, serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
|
|
7
|
+
import { withRetry } from '@cyanheads/mcp-ts-core/utils';
|
|
8
|
+
const BASE_URL = 'https://projects.propublica.org/nonprofits/api/v2';
|
|
9
|
+
const FETCH_TIMEOUT_MS = 15_000;
|
|
10
|
+
export class NonprofitExplorerService {
|
|
11
|
+
// AppConfig and StorageService are injected for future extensibility (caching, config flags)
|
|
12
|
+
// but are not referenced directly by this keyless, stateless service.
|
|
13
|
+
constructor(_config, _storage) { }
|
|
14
|
+
/**
|
|
15
|
+
* Fetch a URL with timeout, tolerating specific non-2xx statuses instead of throwing.
|
|
16
|
+
* Returns `{ status, text }` — caller decides whether the status is an error.
|
|
17
|
+
* Throws `serviceUnavailable` on network errors or unexpected non-JSON responses.
|
|
18
|
+
*/
|
|
19
|
+
async fetchTolerant(url, toleratedStatuses, ctx) {
|
|
20
|
+
const controller = new AbortController();
|
|
21
|
+
const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
|
|
22
|
+
// Forward caller's cancellation signal to the AbortController
|
|
23
|
+
if (ctx.signal) {
|
|
24
|
+
if (ctx.signal.aborted) {
|
|
25
|
+
clearTimeout(timeoutId);
|
|
26
|
+
controller.abort(ctx.signal.reason);
|
|
27
|
+
}
|
|
28
|
+
else {
|
|
29
|
+
ctx.signal.addEventListener('abort', () => controller.abort(ctx.signal.reason), {
|
|
30
|
+
once: true,
|
|
31
|
+
signal: controller.signal,
|
|
32
|
+
});
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
try {
|
|
36
|
+
const response = await fetch(url, {
|
|
37
|
+
signal: controller.signal,
|
|
38
|
+
headers: { Accept: 'application/json' },
|
|
39
|
+
});
|
|
40
|
+
const text = await response.text();
|
|
41
|
+
// Non-2xx that isn't in the tolerated list is a service error
|
|
42
|
+
if (!response.ok && !toleratedStatuses.includes(response.status)) {
|
|
43
|
+
throw serviceUnavailable(`ProPublica API returned unexpected status ${response.status}.`, {
|
|
44
|
+
url,
|
|
45
|
+
statusCode: response.status,
|
|
46
|
+
reason: 'upstream_error',
|
|
47
|
+
});
|
|
48
|
+
}
|
|
49
|
+
return { status: response.status, text };
|
|
50
|
+
}
|
|
51
|
+
catch (err) {
|
|
52
|
+
if (err instanceof McpError)
|
|
53
|
+
throw err;
|
|
54
|
+
throw serviceUnavailable(`Network error reaching ProPublica API: ${err instanceof Error ? err.message : String(err)}`, { url, reason: 'upstream_error' });
|
|
55
|
+
}
|
|
56
|
+
finally {
|
|
57
|
+
clearTimeout(timeoutId);
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
/** Search organizations by keyword and optional filters. */
|
|
61
|
+
search(params, ctx) {
|
|
62
|
+
const rctx = ctx;
|
|
63
|
+
return withRetry(async () => {
|
|
64
|
+
const url = new URL(`${BASE_URL}/search.json`);
|
|
65
|
+
if (params.query)
|
|
66
|
+
url.searchParams.set('q', params.query);
|
|
67
|
+
if (params.state)
|
|
68
|
+
url.searchParams.set('state[id]', params.state);
|
|
69
|
+
if (params.ntee_category)
|
|
70
|
+
url.searchParams.set('ntee[id]', params.ntee_category);
|
|
71
|
+
if (params.subsection_code)
|
|
72
|
+
url.searchParams.set('c_code[id]', params.subsection_code);
|
|
73
|
+
url.searchParams.set('page', String(params.page));
|
|
74
|
+
ctx.log.debug('Searching nonprofits', { url: url.toString() });
|
|
75
|
+
// ProPublica returns HTTP 404 (not 200) when there are zero results — tolerate it
|
|
76
|
+
// so the tool handler can throw the correct no_results contract error.
|
|
77
|
+
const { text } = await this.fetchTolerant(url.toString(), [404], ctx);
|
|
78
|
+
return this.parseJson(text, url.toString());
|
|
79
|
+
}, {
|
|
80
|
+
operation: 'NonprofitExplorer.search',
|
|
81
|
+
context: rctx,
|
|
82
|
+
baseDelayMs: 500,
|
|
83
|
+
signal: ctx.signal,
|
|
84
|
+
});
|
|
85
|
+
}
|
|
86
|
+
/**
|
|
87
|
+
* Fetch full organization profile and all filings by EIN.
|
|
88
|
+
* Handles the three not-found signatures and throws notFound when detected.
|
|
89
|
+
*/
|
|
90
|
+
getOrganization(ein, ctx) {
|
|
91
|
+
const rctx = ctx;
|
|
92
|
+
return withRetry(async () => {
|
|
93
|
+
const url = `${BASE_URL}/organizations/${ein}.json`;
|
|
94
|
+
ctx.log.debug('Fetching nonprofit org', { ein });
|
|
95
|
+
// Tolerate 404 — the API returns HTTP 404 + JSON body for "org not found" (not-found
|
|
96
|
+
// pattern 1). We inspect the body before deciding how to classify the error, rather
|
|
97
|
+
// than letting the network layer throw a generic FetchHttpError.
|
|
98
|
+
const { status, text } = await this.fetchTolerant(url, [404], ctx);
|
|
99
|
+
const data = this.parseJson(text, url);
|
|
100
|
+
// Not-found pattern 1: HTTP 404 + {"error": "Organization not found"}
|
|
101
|
+
if (status === 404) {
|
|
102
|
+
throw notFound(`No organization found for EIN ${ein}.`, {
|
|
103
|
+
ein,
|
|
104
|
+
reason: 'not_found',
|
|
105
|
+
});
|
|
106
|
+
}
|
|
107
|
+
const org = data.organization;
|
|
108
|
+
// Not-found pattern 2: HTTP 200 + id=0
|
|
109
|
+
if (!org || org.id === 0) {
|
|
110
|
+
throw notFound(`No organization found for EIN ${ein}.`, {
|
|
111
|
+
ein,
|
|
112
|
+
reason: 'not_found',
|
|
113
|
+
});
|
|
114
|
+
}
|
|
115
|
+
// Not-found pattern 3: HTTP 200 + name="Unknown Organization" + address=null
|
|
116
|
+
if (org.name === 'Unknown Organization' && org.address === null) {
|
|
117
|
+
throw notFound(`No organization found for EIN ${ein}.`, {
|
|
118
|
+
ein,
|
|
119
|
+
reason: 'not_found',
|
|
120
|
+
});
|
|
121
|
+
}
|
|
122
|
+
return data;
|
|
123
|
+
}, {
|
|
124
|
+
operation: 'NonprofitExplorer.getOrganization',
|
|
125
|
+
context: rctx,
|
|
126
|
+
baseDelayMs: 500,
|
|
127
|
+
signal: ctx.signal,
|
|
128
|
+
});
|
|
129
|
+
}
|
|
130
|
+
/** Parse JSON from an upstream response; throws serviceUnavailable on HTML error pages. */
|
|
131
|
+
parseJson(text, url) {
|
|
132
|
+
if (/^\s*<(!DOCTYPE\s+html|html[\s>])/i.test(text)) {
|
|
133
|
+
throw serviceUnavailable('ProPublica API returned HTML instead of JSON — likely a transient server error.', { url, reason: 'upstream_error' });
|
|
134
|
+
}
|
|
135
|
+
try {
|
|
136
|
+
return JSON.parse(text);
|
|
137
|
+
}
|
|
138
|
+
catch {
|
|
139
|
+
throw serviceUnavailable('ProPublica API returned unparseable response.', {
|
|
140
|
+
url,
|
|
141
|
+
reason: 'upstream_error',
|
|
142
|
+
});
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
// --- Init/accessor pattern ---
|
|
147
|
+
let _service;
|
|
148
|
+
export function initNonprofitExplorerService(config, storage) {
|
|
149
|
+
_service = new NonprofitExplorerService(config, storage);
|
|
150
|
+
}
|
|
151
|
+
export function getNonprofitExplorerService() {
|
|
152
|
+
if (!_service) {
|
|
153
|
+
throw new Error('NonprofitExplorerService not initialized — call initNonprofitExplorerService() in setup()');
|
|
154
|
+
}
|
|
155
|
+
return _service;
|
|
156
|
+
}
|
|
157
|
+
/** Normalize an EIN input (number or string with/without hyphen) to an integer. */
|
|
158
|
+
export function normalizeEin(ein) {
|
|
159
|
+
if (typeof ein === 'number')
|
|
160
|
+
return ein;
|
|
161
|
+
return parseInt(ein.replace('-', ''), 10);
|
|
162
|
+
}
|
|
163
|
+
/**
|
|
164
|
+
* Format an EIN integer as "XX-XXXXXXX" string.
|
|
165
|
+
* EINs are 9 digits; the first two form the prefix. Leading zeros are preserved via padding.
|
|
166
|
+
*/
|
|
167
|
+
export function formatEin(ein) {
|
|
168
|
+
const s = String(ein).padStart(9, '0');
|
|
169
|
+
return `${s.slice(0, 2)}-${s.slice(2)}`;
|
|
170
|
+
}
|
|
171
|
+
//# sourceMappingURL=nonprofit-explorer-service.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"nonprofit-explorer-service.js","sourceRoot":"","sources":["../../../src/services/nonprofit-explorer/nonprofit-explorer-service.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview Domain types for the ProPublica Nonprofit Explorer API v2.
|
|
3
|
+
* @module services/nonprofit-explorer/types
|
|
4
|
+
*/
|
|
5
|
+
/** Raw org record from the search results array. */
|
|
6
|
+
export interface RawSearchOrg {
|
|
7
|
+
city?: string | null;
|
|
8
|
+
ein: number;
|
|
9
|
+
name?: string;
|
|
10
|
+
ntee_code?: string | null;
|
|
11
|
+
score?: number;
|
|
12
|
+
state?: string | null;
|
|
13
|
+
strein?: string;
|
|
14
|
+
sub_name?: string | null;
|
|
15
|
+
subseccd?: number | null;
|
|
16
|
+
}
|
|
17
|
+
/** Raw search response envelope. */
|
|
18
|
+
export interface RawSearchResponse {
|
|
19
|
+
cur_page?: number;
|
|
20
|
+
data_source?: string;
|
|
21
|
+
num_pages?: number;
|
|
22
|
+
organizations?: RawSearchOrg[];
|
|
23
|
+
total_results?: number;
|
|
24
|
+
}
|
|
25
|
+
/** Raw filing with extracted financial data. */
|
|
26
|
+
export interface RawFiling {
|
|
27
|
+
compnsatncurrofcr?: number | null;
|
|
28
|
+
compofficers?: number | null;
|
|
29
|
+
form_type?: string;
|
|
30
|
+
formtype?: number;
|
|
31
|
+
invstmntinc?: number | null;
|
|
32
|
+
othrsalwages?: number | null;
|
|
33
|
+
pdf_url?: string | null;
|
|
34
|
+
profndraising?: number | null;
|
|
35
|
+
tax_prd?: number;
|
|
36
|
+
tax_prd_yr?: number;
|
|
37
|
+
totassetsend?: number | null;
|
|
38
|
+
totcntrbgfts?: number | null;
|
|
39
|
+
totfuncexpns?: number | null;
|
|
40
|
+
totliabend?: number | null;
|
|
41
|
+
totnetassetend?: number | null;
|
|
42
|
+
totprgmrevnue?: number | null;
|
|
43
|
+
totrevenue?: number | null;
|
|
44
|
+
updated?: string | null;
|
|
45
|
+
}
|
|
46
|
+
/** Raw PDF-only filing (filings_without_data). */
|
|
47
|
+
export interface RawPdfOnlyFiling {
|
|
48
|
+
formtype?: number;
|
|
49
|
+
formtype_str?: string;
|
|
50
|
+
pdf_url?: string | null;
|
|
51
|
+
tax_prd?: number;
|
|
52
|
+
tax_prd_yr?: number;
|
|
53
|
+
}
|
|
54
|
+
/** Raw organization profile from the org endpoint. */
|
|
55
|
+
export interface RawOrganization {
|
|
56
|
+
address?: string | null;
|
|
57
|
+
asset_amount?: number | null;
|
|
58
|
+
city?: string | null;
|
|
59
|
+
data_source?: string;
|
|
60
|
+
ein?: number;
|
|
61
|
+
filings_with_data?: RawFiling[];
|
|
62
|
+
filings_without_data?: RawPdfOnlyFiling[];
|
|
63
|
+
id?: number;
|
|
64
|
+
income_amount?: number | null;
|
|
65
|
+
name?: string;
|
|
66
|
+
ntee_code?: string | null;
|
|
67
|
+
revenue_amount?: number | null;
|
|
68
|
+
ruling_date?: string | null;
|
|
69
|
+
sort_name?: string | null;
|
|
70
|
+
state?: string | null;
|
|
71
|
+
strein?: string;
|
|
72
|
+
subsection_code?: number | null;
|
|
73
|
+
zipcode?: string | null;
|
|
74
|
+
}
|
|
75
|
+
/** Raw org endpoint response envelope. */
|
|
76
|
+
export interface RawOrgResponse {
|
|
77
|
+
data_source?: string;
|
|
78
|
+
filings_with_data?: RawFiling[];
|
|
79
|
+
filings_without_data?: RawPdfOnlyFiling[];
|
|
80
|
+
organization?: RawOrganization;
|
|
81
|
+
}
|
|
82
|
+
export interface SearchParams {
|
|
83
|
+
ntee_category?: string | undefined;
|
|
84
|
+
page: number;
|
|
85
|
+
query: string;
|
|
86
|
+
state?: string | undefined;
|
|
87
|
+
subsection_code?: string | undefined;
|
|
88
|
+
}
|
|
89
|
+
//# sourceMappingURL=types.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/services/nonprofit-explorer/types.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/services/nonprofit-explorer/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}
|
package/package.json
ADDED
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@cyanheads/nonprofit-explorer-mcp-server",
|
|
3
|
+
"version": "0.1.1",
|
|
4
|
+
"mcpName": "io.github.cyanheads/nonprofit-explorer-mcp-server",
|
|
5
|
+
"description": "MCP server for US nonprofit financials via ProPublica — IRS Form 990 data for 1.8M+ tax-exempt organizations.",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"main": "dist/index.js",
|
|
8
|
+
"types": "dist/index.d.ts",
|
|
9
|
+
"bin": {
|
|
10
|
+
"nonprofit-explorer-mcp-server": "dist/index.js"
|
|
11
|
+
},
|
|
12
|
+
"files": [
|
|
13
|
+
"changelog/",
|
|
14
|
+
"dist/",
|
|
15
|
+
"README.md",
|
|
16
|
+
"LICENSE",
|
|
17
|
+
"CLAUDE.md",
|
|
18
|
+
"AGENTS.md",
|
|
19
|
+
"Dockerfile",
|
|
20
|
+
"server.json"
|
|
21
|
+
],
|
|
22
|
+
"scripts": {
|
|
23
|
+
"build": "bun run scripts/build.ts",
|
|
24
|
+
"rebuild": "bun run scripts/clean.ts && bun run scripts/build.ts",
|
|
25
|
+
"clean": "bun run scripts/clean.ts",
|
|
26
|
+
"devcheck": "bun run scripts/devcheck.ts",
|
|
27
|
+
"audit:refresh": "rm -f bun.lock && bun install && bun audit",
|
|
28
|
+
"tree": "bun run scripts/tree.ts",
|
|
29
|
+
"list-skills": "bun run scripts/list-skills.ts",
|
|
30
|
+
"format": "biome check --write .",
|
|
31
|
+
"format:unsafe": "biome check --write --unsafe .",
|
|
32
|
+
"lint:mcp": "bun run scripts/lint-mcp.ts",
|
|
33
|
+
"lint:packaging": "bun run scripts/lint-packaging.ts",
|
|
34
|
+
"bundle": "bun run build && npx -y @anthropic-ai/mcpb pack . dist/nonprofit-explorer-mcp-server.mcpb",
|
|
35
|
+
"changelog:build": "bun run scripts/build-changelog.ts",
|
|
36
|
+
"changelog:check": "bun run scripts/build-changelog.ts --check",
|
|
37
|
+
"publish-mcp": "mcp-publisher login github -token \"$(security find-generic-password -a \"$USER\" -s mcp-publisher-github-pat -w)\" && mcp-publisher publish",
|
|
38
|
+
"release:github": "bun run scripts/release-github.ts",
|
|
39
|
+
"test": "bunx vitest run",
|
|
40
|
+
"start:stdio": "MCP_TRANSPORT_TYPE=stdio bun ./dist/index.js",
|
|
41
|
+
"start:http": "MCP_TRANSPORT_TYPE=http bun ./dist/index.js"
|
|
42
|
+
},
|
|
43
|
+
"keywords": [
|
|
44
|
+
"nonprofit",
|
|
45
|
+
"propublica",
|
|
46
|
+
"irs",
|
|
47
|
+
"form-990",
|
|
48
|
+
"tax-exempt",
|
|
49
|
+
"charity",
|
|
50
|
+
"mcp",
|
|
51
|
+
"mcp-server",
|
|
52
|
+
"model-context-protocol",
|
|
53
|
+
"typescript",
|
|
54
|
+
"bun",
|
|
55
|
+
"stdio",
|
|
56
|
+
"streamable-http",
|
|
57
|
+
"ai-agent"
|
|
58
|
+
],
|
|
59
|
+
"repository": {
|
|
60
|
+
"type": "git",
|
|
61
|
+
"url": "git+https://github.com/cyanheads/nonprofit-explorer-mcp-server.git"
|
|
62
|
+
},
|
|
63
|
+
"bugs": {
|
|
64
|
+
"url": "https://github.com/cyanheads/nonprofit-explorer-mcp-server/issues"
|
|
65
|
+
},
|
|
66
|
+
"homepage": "https://github.com/cyanheads/nonprofit-explorer-mcp-server#readme",
|
|
67
|
+
"author": "cyanheads <casey@caseyjhand.com> (https://github.com/cyanheads/nonprofit-explorer-mcp-server#readme)",
|
|
68
|
+
"funding": [
|
|
69
|
+
{
|
|
70
|
+
"type": "github",
|
|
71
|
+
"url": "https://github.com/sponsors/cyanheads"
|
|
72
|
+
},
|
|
73
|
+
{
|
|
74
|
+
"type": "buy_me_a_coffee",
|
|
75
|
+
"url": "https://www.buymeacoffee.com/cyanheads"
|
|
76
|
+
}
|
|
77
|
+
],
|
|
78
|
+
"license": "Apache-2.0",
|
|
79
|
+
"packageManager": "bun@1.3.11",
|
|
80
|
+
"engines": {
|
|
81
|
+
"bun": ">=1.3.0",
|
|
82
|
+
"node": ">=24.0.0"
|
|
83
|
+
},
|
|
84
|
+
"publishConfig": {
|
|
85
|
+
"access": "public"
|
|
86
|
+
},
|
|
87
|
+
"dependencies": {
|
|
88
|
+
"@cyanheads/mcp-ts-core": "^0.9.19",
|
|
89
|
+
"pino-pretty": "^13.1.3",
|
|
90
|
+
"zod": "^4.4.3"
|
|
91
|
+
},
|
|
92
|
+
"devDependencies": {
|
|
93
|
+
"@biomejs/biome": "^2.4.7",
|
|
94
|
+
"@types/node": "^25.6.0",
|
|
95
|
+
"depcheck": "^1.4.7",
|
|
96
|
+
"ignore": "^7.0.5",
|
|
97
|
+
"tsc-alias": "^1.8.16",
|
|
98
|
+
"typescript": "^5.9.3",
|
|
99
|
+
"vitest": "^4.1.8"
|
|
100
|
+
}
|
|
101
|
+
}
|
package/server.json
ADDED
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
|
|
3
|
+
"name": "io.github.cyanheads/nonprofit-explorer-mcp-server",
|
|
4
|
+
"description": "MCP server for nonprofit financials via ProPublica — IRS Form 990 data for 1.8M+ nonprofits.",
|
|
5
|
+
"repository": {
|
|
6
|
+
"url": "https://github.com/cyanheads/nonprofit-explorer-mcp-server",
|
|
7
|
+
"source": "github"
|
|
8
|
+
},
|
|
9
|
+
"version": "0.1.1",
|
|
10
|
+
"packages": [
|
|
11
|
+
{
|
|
12
|
+
"registryType": "npm",
|
|
13
|
+
"registryBaseUrl": "https://registry.npmjs.org",
|
|
14
|
+
"identifier": "@cyanheads/nonprofit-explorer-mcp-server",
|
|
15
|
+
"runtimeHint": "bun",
|
|
16
|
+
"version": "0.1.1",
|
|
17
|
+
"packageArguments": [
|
|
18
|
+
{
|
|
19
|
+
"type": "positional",
|
|
20
|
+
"value": "run"
|
|
21
|
+
},
|
|
22
|
+
{
|
|
23
|
+
"type": "positional",
|
|
24
|
+
"value": "start:stdio"
|
|
25
|
+
}
|
|
26
|
+
],
|
|
27
|
+
"environmentVariables": [
|
|
28
|
+
{
|
|
29
|
+
"name": "MCP_LOG_LEVEL",
|
|
30
|
+
"description": "Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').",
|
|
31
|
+
"format": "string",
|
|
32
|
+
"isRequired": false,
|
|
33
|
+
"default": "info"
|
|
34
|
+
}
|
|
35
|
+
],
|
|
36
|
+
"transport": {
|
|
37
|
+
"type": "stdio"
|
|
38
|
+
}
|
|
39
|
+
},
|
|
40
|
+
{
|
|
41
|
+
"registryType": "npm",
|
|
42
|
+
"registryBaseUrl": "https://registry.npmjs.org",
|
|
43
|
+
"identifier": "@cyanheads/nonprofit-explorer-mcp-server",
|
|
44
|
+
"runtimeHint": "bun",
|
|
45
|
+
"version": "0.1.1",
|
|
46
|
+
"packageArguments": [
|
|
47
|
+
{
|
|
48
|
+
"type": "positional",
|
|
49
|
+
"value": "run"
|
|
50
|
+
},
|
|
51
|
+
{
|
|
52
|
+
"type": "positional",
|
|
53
|
+
"value": "start:http"
|
|
54
|
+
}
|
|
55
|
+
],
|
|
56
|
+
"environmentVariables": [
|
|
57
|
+
{
|
|
58
|
+
"name": "MCP_HTTP_HOST",
|
|
59
|
+
"description": "The hostname for the HTTP server.",
|
|
60
|
+
"format": "string",
|
|
61
|
+
"isRequired": false,
|
|
62
|
+
"default": "127.0.0.1"
|
|
63
|
+
},
|
|
64
|
+
{
|
|
65
|
+
"name": "MCP_HTTP_PORT",
|
|
66
|
+
"description": "The port to run the HTTP server on.",
|
|
67
|
+
"format": "string",
|
|
68
|
+
"isRequired": false,
|
|
69
|
+
"default": "3010"
|
|
70
|
+
},
|
|
71
|
+
{
|
|
72
|
+
"name": "MCP_HTTP_ENDPOINT_PATH",
|
|
73
|
+
"description": "The endpoint path for the MCP server.",
|
|
74
|
+
"format": "string",
|
|
75
|
+
"isRequired": false,
|
|
76
|
+
"default": "/mcp"
|
|
77
|
+
},
|
|
78
|
+
{
|
|
79
|
+
"name": "MCP_PUBLIC_URL",
|
|
80
|
+
"description": "Public origin override for deployments behind a TLS-terminating reverse proxy (e.g. https://mcp.example.com).",
|
|
81
|
+
"format": "string",
|
|
82
|
+
"isRequired": false
|
|
83
|
+
},
|
|
84
|
+
{
|
|
85
|
+
"name": "MCP_AUTH_MODE",
|
|
86
|
+
"description": "Authentication mode to use: 'none', 'jwt', or 'oauth'.",
|
|
87
|
+
"format": "string",
|
|
88
|
+
"isRequired": false,
|
|
89
|
+
"default": "none"
|
|
90
|
+
},
|
|
91
|
+
{
|
|
92
|
+
"name": "MCP_LOG_LEVEL",
|
|
93
|
+
"description": "Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').",
|
|
94
|
+
"format": "string",
|
|
95
|
+
"isRequired": false,
|
|
96
|
+
"default": "info"
|
|
97
|
+
}
|
|
98
|
+
],
|
|
99
|
+
"transport": {
|
|
100
|
+
"type": "streamable-http",
|
|
101
|
+
"url": "http://localhost:3010/mcp"
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
]
|
|
105
|
+
}
|