@cyanheads/nonprofit-explorer-mcp-server 0.1.3 → 0.1.5
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 +34 -18
- package/CLAUDE.md +34 -18
- package/Dockerfile +17 -8
- package/LICENSE +1 -1
- package/README.md +6 -5
- package/changelog/0.1.x/0.1.4.md +27 -0
- package/changelog/0.1.x/0.1.5.md +40 -0
- package/changelog/template.md +60 -19
- package/dist/mcp-server/tools/definitions/nonprofit-search.tool.d.ts +24 -14
- package/dist/mcp-server/tools/definitions/nonprofit-search.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/nonprofit-search.tool.js +63 -12
- package/dist/mcp-server/tools/definitions/nonprofit-search.tool.js.map +1 -1
- package/dist/services/nonprofit-explorer/nonprofit-explorer-service.d.ts +6 -0
- package/dist/services/nonprofit-explorer/nonprofit-explorer-service.d.ts.map +1 -1
- package/dist/services/nonprofit-explorer/nonprofit-explorer-service.js +79 -32
- package/dist/services/nonprofit-explorer/nonprofit-explorer-service.js.map +1 -1
- package/dist/services/nonprofit-explorer/types.d.ts +12 -1
- package/dist/services/nonprofit-explorer/types.d.ts.map +1 -1
- package/package.json +12 -11
- package/server.json +3 -3
package/AGENTS.md
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
# Developer Protocol
|
|
2
2
|
|
|
3
3
|
**Server:** nonprofit-explorer-mcp-server
|
|
4
|
-
**Version:** 0.1.
|
|
5
|
-
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.
|
|
4
|
+
**Version:** 0.1.5
|
|
5
|
+
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.11.5`
|
|
6
6
|
**Engines:** Bun ≥1.3.0, Node ≥24.0.0
|
|
7
|
-
**MCP SDK:** `@modelcontextprotocol/sdk` ^1.
|
|
7
|
+
**MCP SDK:** `@modelcontextprotocol/sdk` ^1.30.0
|
|
8
8
|
**Zod:** ^4.4.3
|
|
9
9
|
|
|
10
10
|
> **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
|
|
@@ -47,19 +47,24 @@ export const nonprofitSearch = tool('nonprofit_search', {
|
|
|
47
47
|
name: z.string().describe('Legal org name.'),
|
|
48
48
|
})).describe('Matching organizations for the current page.'),
|
|
49
49
|
}),
|
|
50
|
+
enrichment: {
|
|
51
|
+
notice: z.string().optional().describe('Present when the page carried no organizations.'),
|
|
52
|
+
},
|
|
50
53
|
errors: [
|
|
51
54
|
{
|
|
52
|
-
reason: '
|
|
53
|
-
code: JsonRpcErrorCode.
|
|
54
|
-
when: '
|
|
55
|
-
|
|
55
|
+
reason: 'upstream_error',
|
|
56
|
+
code: JsonRpcErrorCode.ServiceUnavailable,
|
|
57
|
+
when: 'ProPublica returns a 5xx or the request fails at the network layer',
|
|
58
|
+
retryable: true,
|
|
59
|
+
recovery: 'Wait a moment and retry.',
|
|
56
60
|
},
|
|
57
61
|
],
|
|
58
62
|
async handler(input, ctx) {
|
|
59
63
|
const svc = getNonprofitExplorerService();
|
|
60
64
|
const raw = await svc.search(input, ctx);
|
|
61
65
|
const orgs = raw.organizations ?? [];
|
|
62
|
-
|
|
66
|
+
// A zero-hit search succeeded — return an empty list plus a notice, never an error.
|
|
67
|
+
if (orgs.length === 0) ctx.enrich.notice(`No organizations matched "${input.query}".`);
|
|
63
68
|
return { total_results: raw.total_results ?? 0, organizations: orgs.map(o => ({ ein: o.ein, name: o.name ?? '' })) };
|
|
64
69
|
},
|
|
65
70
|
format: (result) => [{ type: 'text', text: result.organizations.map(o => `**${o.name}** (EIN: ${o.ein})`).join('\n') }],
|
|
@@ -79,10 +84,14 @@ Handlers receive a unified `ctx` object. Key properties:
|
|
|
79
84
|
| Property | Description |
|
|
80
85
|
|:---------|:------------|
|
|
81
86
|
| `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. |
|
|
82
|
-
| `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |
|
|
87
|
+
| `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |
|
|
88
|
+
| `ctx.elicit` | Ask user for structured input — form call `(message, schema)` or `.url(message, url)` for an external link. **Check for presence first:** `if (ctx.elicit) { ... }` |
|
|
89
|
+
| `ctx.enrich` | Success-path agent context (empty-result notices, query echo, pagination totals) — `ctx.enrich(...)` or `.notice()` / `.total()` / `.echo()` / `.truncated()`. Reaches `structuredContent` and `content[]`; lands only when the definition declares an `enrichment` block (no-op otherwise). |
|
|
90
|
+
| `ctx.content` | Non-text content blocks — `.image(data, mimeType)`, `.audio(data, mimeType)`, or `ctx.content(block)` for a raw block. Prepended to `content[]` after `format()`; never enters `structuredContent`. |
|
|
83
91
|
| `ctx.signal` | `AbortSignal` for cancellation. |
|
|
92
|
+
| `ctx.progress` | Task progress (present when `task: true`) — `.setTotal(n)`, `.increment()`, `.update(message)`. |
|
|
84
93
|
| `ctx.requestId` | Unique request ID. |
|
|
85
|
-
| `ctx.tenantId` | Tenant ID from JWT
|
|
94
|
+
| `ctx.tenantId` | Tenant ID from JWT; `'default'` for stdio or HTTP with auth off. |
|
|
86
95
|
|
|
87
96
|
---
|
|
88
97
|
|
|
@@ -90,7 +99,7 @@ Handlers receive a unified `ctx` object. Key properties:
|
|
|
90
99
|
|
|
91
100
|
Handlers throw — the framework catches, classifies, and formats.
|
|
92
101
|
|
|
93
|
-
**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required
|
|
102
|
+
**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required (≥ 5 words, lint-validated) — the single source of truth for the agent's next move. Pass `ctx.recoveryFor('reason')` as the throw's data to put it on the wire (`data.recovery.hint`, mirrored into `content[]` text); override with an explicit `{ recovery: { hint: '...' } }` when dynamic runtime context matters. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring.
|
|
94
103
|
|
|
95
104
|
```ts
|
|
96
105
|
import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
|
|
@@ -107,6 +116,8 @@ async handler(input, ctx) {
|
|
|
107
116
|
}
|
|
108
117
|
```
|
|
109
118
|
|
|
119
|
+
**Declare contracts inline on each tool.** The contract is part of the tool's public surface — one file should give the full picture. Don't extract a shared `errors[]` constant; per-tool repetition is the intended cost of locality.
|
|
120
|
+
|
|
110
121
|
**Fallback (no contract entry fits):** throw via factories or plain `Error`.
|
|
111
122
|
|
|
112
123
|
```ts
|
|
@@ -150,7 +161,7 @@ src/
|
|
|
150
161
|
|
|
151
162
|
## Skills
|
|
152
163
|
|
|
153
|
-
Skills are modular instructions in `skills/` at the project root. Read them directly when a task matches — e.g., `skills/add-tool/SKILL.md` when adding a tool.
|
|
164
|
+
Skills are modular instructions in `skills/` at the project root. Read them directly when a task matches — e.g., `skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry.
|
|
154
165
|
|
|
155
166
|
**Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
|
|
156
167
|
|
|
@@ -170,7 +181,6 @@ Available skills:
|
|
|
170
181
|
| `tool-defs-analysis` | Read-only audit of MCP definition language across the surface — voice, leaks, defaults, recovery hints, output descriptions |
|
|
171
182
|
| `security-pass` | Audit server for MCP-flavored security gaps: output injection, scope blast radius, input sinks, tenant isolation |
|
|
172
183
|
| `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase |
|
|
173
|
-
| `devcheck` | Lint, format, typecheck, audit |
|
|
174
184
|
| `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
|
|
175
185
|
| `git-wrapup` | Land working-tree changes as a versioned commit + annotated tag — version bump, changelog, verify, tag. Local only. |
|
|
176
186
|
| `release-and-publish` | Push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
|
|
@@ -178,19 +188,22 @@ Available skills:
|
|
|
178
188
|
| `orchestrations` | Chain task skills into a gated multi-phase pipeline — build-out, QA-fix, update-ship — when you can spawn sub-agents |
|
|
179
189
|
| `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
|
|
180
190
|
| `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
|
|
181
|
-
| `techniques` |
|
|
191
|
+
| `techniques` | Catalog of response/data-shaping techniques — overflow handling, payload shaping, retrieval patterns |
|
|
182
192
|
| `api-auth` | Auth modes, scopes, JWT/OAuth |
|
|
183
193
|
| `api-canvas` | DataCanvas: register tabular data, run SQL, export, plus the `spillover()` helper for big result sets — Tier 3 opt-in |
|
|
184
194
|
| `api-config` | AppConfig, parseConfig, env vars |
|
|
185
195
|
| `api-context` | Context interface, logger, state, progress |
|
|
186
196
|
| `api-errors` | McpError, JsonRpcErrorCode, error patterns |
|
|
187
197
|
| `api-linter` | Definition linter rule catalog — invoked by `bun run lint:mcp` and `devcheck` |
|
|
198
|
+
| `api-mirror` | MirrorService: persistent self-refreshing local mirror (embedded SQLite + FTS5) of a bulk upstream dataset — Tier 3 opt-in |
|
|
188
199
|
| `api-services` | LLM, Speech, Graph services |
|
|
189
200
|
| `api-testing` | createMockContext, test patterns |
|
|
190
201
|
| `api-utils` | Formatting, parsing, security, pagination, scheduling, telemetry helpers |
|
|
191
202
|
| `api-telemetry` | OTel catalog: spans, metrics, completion logs, env config, cardinality rules |
|
|
192
203
|
| `api-workers` | Cloudflare Workers runtime |
|
|
193
204
|
|
|
205
|
+
**Chaining skills into pipelines.** When the user wants a multi-phase effort — build this server out, QA-and-fix the surface, update-and-ship — *and you can spawn sub-agents*, `skills/orchestrations/SKILL.md` sequences the task skills above into a gated pipeline with verification at each step. Read it to drive the run. Optional: skip it if you can't orchestrate sub-agents, and ignore it entirely if you were *spawned* as one — you've already been scoped to a single phase.
|
|
206
|
+
|
|
194
207
|
When you complete a skill's checklist, check the boxes and add a completion timestamp at the end (e.g., `Completed: 2026-06-01`).
|
|
195
208
|
|
|
196
209
|
---
|
|
@@ -206,10 +219,13 @@ When you complete a skill's checklist, check the boxes and add a completion time
|
|
|
206
219
|
| `bun run clean` | Remove build artifacts |
|
|
207
220
|
| `bun run devcheck` | Lint + format + typecheck + security + changelog sync |
|
|
208
221
|
| `bun run audit:refresh` | Delete `bun.lock`, reinstall, and re-run `bun audit`. Use when `devcheck` flags a transitive advisory — Bun's `update` is sticky on transitive resolutions, so the advisory may be a stale-lockfile false positive. If it survives the refresh, it's real. |
|
|
222
|
+
| `bun run lint:mcp` | Run the MCP definition linter standalone (rule catalog: `api-linter` skill) |
|
|
223
|
+
| `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity (run by devcheck) |
|
|
224
|
+
| `bun run list-skills` | Print the skill registry |
|
|
209
225
|
| `bun run tree` | Generate directory structure doc |
|
|
210
226
|
| `bun run format` | Auto-fix formatting (safe fixes only) |
|
|
211
227
|
| `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
|
|
212
|
-
| `bun run test` | Run tests |
|
|
228
|
+
| `bun run test` | Run tests (Vitest — use `bun run test`, not `bun test`) |
|
|
213
229
|
| `bun run start:stdio` | Production mode (stdio) |
|
|
214
230
|
| `bun run start:http` | Production mode (HTTP) |
|
|
215
231
|
| `bun run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
|
|
@@ -220,7 +236,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
|
|
|
220
236
|
|
|
221
237
|
## Bundling
|
|
222
238
|
|
|
223
|
-
`bun run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips dependency-shipped agent docs (`
|
|
239
|
+
`bun run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips two classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`skills/`, `.claude/`, `.agents/`, `SKILL.md`) and platform-specific native bindings, which would otherwise lock the bundle to the platform it was packed on. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
|
|
224
240
|
|
|
225
241
|
**Adding an env var requires both files:** `server.json` (registry discovery, `environmentVariables[]`) and `manifest.json` (bundle install UX, `mcp_config.env` + `user_config`). `lint:packaging` (run by `devcheck`) verifies the env var names match.
|
|
226
242
|
|
|
@@ -238,14 +254,14 @@ Each per-version file opens with YAML frontmatter:
|
|
|
238
254
|
---
|
|
239
255
|
summary: "One-line headline, ≤350 chars" # required — powers the rollup index
|
|
240
256
|
breaking: false # optional — true flags breaking changes
|
|
241
|
-
security: false # optional — true
|
|
257
|
+
security: false # optional — true ONLY for a source-code security fix, never a dependency CVE bump
|
|
242
258
|
---
|
|
243
259
|
|
|
244
260
|
# 0.1.0 — YYYY-MM-DD
|
|
245
261
|
...
|
|
246
262
|
```
|
|
247
263
|
|
|
248
|
-
`breaking: true` renders a `· ⚠️ Breaking` badge — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames). `security: true` renders a `· 🛡️ Security` badge and pairs with a `## Security` body section. When both are set, badges render `· ⚠️ Breaking · 🛡️ Security`.
|
|
264
|
+
`breaking: true` renders a `· ⚠️ Breaking` badge — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames). `security: true` renders a `· 🛡️ Security` badge and pairs with a `## Security` body section — set it only for a security fix in this server's *own source code*, never for a routine dependency or transitive CVE bump (record those under `## Dependencies`). When both are set, badges render `· ⚠️ Breaking · 🛡️ Security`.
|
|
249
265
|
|
|
250
266
|
`agent-notes` is an optional free-form field for maintenance agents processing the release downstream. Content here won't appear in the rendered CHANGELOG — it's consumed by agents running the `maintenance` skill. Use it for adoption instructions that don't fit the human-facing sections: new files to create, fields to populate, one-time migration steps. Omit entirely when there's nothing to say.
|
|
251
267
|
|
package/CLAUDE.md
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
# Developer Protocol
|
|
2
2
|
|
|
3
3
|
**Server:** nonprofit-explorer-mcp-server
|
|
4
|
-
**Version:** 0.1.
|
|
5
|
-
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.
|
|
4
|
+
**Version:** 0.1.5
|
|
5
|
+
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.11.5`
|
|
6
6
|
**Engines:** Bun ≥1.3.0, Node ≥24.0.0
|
|
7
|
-
**MCP SDK:** `@modelcontextprotocol/sdk` ^1.
|
|
7
|
+
**MCP SDK:** `@modelcontextprotocol/sdk` ^1.30.0
|
|
8
8
|
**Zod:** ^4.4.3
|
|
9
9
|
|
|
10
10
|
> **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
|
|
@@ -47,19 +47,24 @@ export const nonprofitSearch = tool('nonprofit_search', {
|
|
|
47
47
|
name: z.string().describe('Legal org name.'),
|
|
48
48
|
})).describe('Matching organizations for the current page.'),
|
|
49
49
|
}),
|
|
50
|
+
enrichment: {
|
|
51
|
+
notice: z.string().optional().describe('Present when the page carried no organizations.'),
|
|
52
|
+
},
|
|
50
53
|
errors: [
|
|
51
54
|
{
|
|
52
|
-
reason: '
|
|
53
|
-
code: JsonRpcErrorCode.
|
|
54
|
-
when: '
|
|
55
|
-
|
|
55
|
+
reason: 'upstream_error',
|
|
56
|
+
code: JsonRpcErrorCode.ServiceUnavailable,
|
|
57
|
+
when: 'ProPublica returns a 5xx or the request fails at the network layer',
|
|
58
|
+
retryable: true,
|
|
59
|
+
recovery: 'Wait a moment and retry.',
|
|
56
60
|
},
|
|
57
61
|
],
|
|
58
62
|
async handler(input, ctx) {
|
|
59
63
|
const svc = getNonprofitExplorerService();
|
|
60
64
|
const raw = await svc.search(input, ctx);
|
|
61
65
|
const orgs = raw.organizations ?? [];
|
|
62
|
-
|
|
66
|
+
// A zero-hit search succeeded — return an empty list plus a notice, never an error.
|
|
67
|
+
if (orgs.length === 0) ctx.enrich.notice(`No organizations matched "${input.query}".`);
|
|
63
68
|
return { total_results: raw.total_results ?? 0, organizations: orgs.map(o => ({ ein: o.ein, name: o.name ?? '' })) };
|
|
64
69
|
},
|
|
65
70
|
format: (result) => [{ type: 'text', text: result.organizations.map(o => `**${o.name}** (EIN: ${o.ein})`).join('\n') }],
|
|
@@ -79,10 +84,14 @@ Handlers receive a unified `ctx` object. Key properties:
|
|
|
79
84
|
| Property | Description |
|
|
80
85
|
|:---------|:------------|
|
|
81
86
|
| `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. |
|
|
82
|
-
| `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |
|
|
87
|
+
| `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |
|
|
88
|
+
| `ctx.elicit` | Ask user for structured input — form call `(message, schema)` or `.url(message, url)` for an external link. **Check for presence first:** `if (ctx.elicit) { ... }` |
|
|
89
|
+
| `ctx.enrich` | Success-path agent context (empty-result notices, query echo, pagination totals) — `ctx.enrich(...)` or `.notice()` / `.total()` / `.echo()` / `.truncated()`. Reaches `structuredContent` and `content[]`; lands only when the definition declares an `enrichment` block (no-op otherwise). |
|
|
90
|
+
| `ctx.content` | Non-text content blocks — `.image(data, mimeType)`, `.audio(data, mimeType)`, or `ctx.content(block)` for a raw block. Prepended to `content[]` after `format()`; never enters `structuredContent`. |
|
|
83
91
|
| `ctx.signal` | `AbortSignal` for cancellation. |
|
|
92
|
+
| `ctx.progress` | Task progress (present when `task: true`) — `.setTotal(n)`, `.increment()`, `.update(message)`. |
|
|
84
93
|
| `ctx.requestId` | Unique request ID. |
|
|
85
|
-
| `ctx.tenantId` | Tenant ID from JWT
|
|
94
|
+
| `ctx.tenantId` | Tenant ID from JWT; `'default'` for stdio or HTTP with auth off. |
|
|
86
95
|
|
|
87
96
|
---
|
|
88
97
|
|
|
@@ -90,7 +99,7 @@ Handlers receive a unified `ctx` object. Key properties:
|
|
|
90
99
|
|
|
91
100
|
Handlers throw — the framework catches, classifies, and formats.
|
|
92
101
|
|
|
93
|
-
**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required
|
|
102
|
+
**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required (≥ 5 words, lint-validated) — the single source of truth for the agent's next move. Pass `ctx.recoveryFor('reason')` as the throw's data to put it on the wire (`data.recovery.hint`, mirrored into `content[]` text); override with an explicit `{ recovery: { hint: '...' } }` when dynamic runtime context matters. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring.
|
|
94
103
|
|
|
95
104
|
```ts
|
|
96
105
|
import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
|
|
@@ -107,6 +116,8 @@ async handler(input, ctx) {
|
|
|
107
116
|
}
|
|
108
117
|
```
|
|
109
118
|
|
|
119
|
+
**Declare contracts inline on each tool.** The contract is part of the tool's public surface — one file should give the full picture. Don't extract a shared `errors[]` constant; per-tool repetition is the intended cost of locality.
|
|
120
|
+
|
|
110
121
|
**Fallback (no contract entry fits):** throw via factories or plain `Error`.
|
|
111
122
|
|
|
112
123
|
```ts
|
|
@@ -150,7 +161,7 @@ src/
|
|
|
150
161
|
|
|
151
162
|
## Skills
|
|
152
163
|
|
|
153
|
-
Skills are modular instructions in `skills/` at the project root. Read them directly when a task matches — e.g., `skills/add-tool/SKILL.md` when adding a tool.
|
|
164
|
+
Skills are modular instructions in `skills/` at the project root. Read them directly when a task matches — e.g., `skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry.
|
|
154
165
|
|
|
155
166
|
**Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
|
|
156
167
|
|
|
@@ -170,7 +181,6 @@ Available skills:
|
|
|
170
181
|
| `tool-defs-analysis` | Read-only audit of MCP definition language across the surface — voice, leaks, defaults, recovery hints, output descriptions |
|
|
171
182
|
| `security-pass` | Audit server for MCP-flavored security gaps: output injection, scope blast radius, input sinks, tenant isolation |
|
|
172
183
|
| `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase |
|
|
173
|
-
| `devcheck` | Lint, format, typecheck, audit |
|
|
174
184
|
| `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
|
|
175
185
|
| `git-wrapup` | Land working-tree changes as a versioned commit + annotated tag — version bump, changelog, verify, tag. Local only. |
|
|
176
186
|
| `release-and-publish` | Push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
|
|
@@ -178,19 +188,22 @@ Available skills:
|
|
|
178
188
|
| `orchestrations` | Chain task skills into a gated multi-phase pipeline — build-out, QA-fix, update-ship — when you can spawn sub-agents |
|
|
179
189
|
| `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
|
|
180
190
|
| `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
|
|
181
|
-
| `techniques` |
|
|
191
|
+
| `techniques` | Catalog of response/data-shaping techniques — overflow handling, payload shaping, retrieval patterns |
|
|
182
192
|
| `api-auth` | Auth modes, scopes, JWT/OAuth |
|
|
183
193
|
| `api-canvas` | DataCanvas: register tabular data, run SQL, export, plus the `spillover()` helper for big result sets — Tier 3 opt-in |
|
|
184
194
|
| `api-config` | AppConfig, parseConfig, env vars |
|
|
185
195
|
| `api-context` | Context interface, logger, state, progress |
|
|
186
196
|
| `api-errors` | McpError, JsonRpcErrorCode, error patterns |
|
|
187
197
|
| `api-linter` | Definition linter rule catalog — invoked by `bun run lint:mcp` and `devcheck` |
|
|
198
|
+
| `api-mirror` | MirrorService: persistent self-refreshing local mirror (embedded SQLite + FTS5) of a bulk upstream dataset — Tier 3 opt-in |
|
|
188
199
|
| `api-services` | LLM, Speech, Graph services |
|
|
189
200
|
| `api-testing` | createMockContext, test patterns |
|
|
190
201
|
| `api-utils` | Formatting, parsing, security, pagination, scheduling, telemetry helpers |
|
|
191
202
|
| `api-telemetry` | OTel catalog: spans, metrics, completion logs, env config, cardinality rules |
|
|
192
203
|
| `api-workers` | Cloudflare Workers runtime |
|
|
193
204
|
|
|
205
|
+
**Chaining skills into pipelines.** When the user wants a multi-phase effort — build this server out, QA-and-fix the surface, update-and-ship — *and you can spawn sub-agents*, `skills/orchestrations/SKILL.md` sequences the task skills above into a gated pipeline with verification at each step. Read it to drive the run. Optional: skip it if you can't orchestrate sub-agents, and ignore it entirely if you were *spawned* as one — you've already been scoped to a single phase.
|
|
206
|
+
|
|
194
207
|
When you complete a skill's checklist, check the boxes and add a completion timestamp at the end (e.g., `Completed: 2026-06-01`).
|
|
195
208
|
|
|
196
209
|
---
|
|
@@ -206,10 +219,13 @@ When you complete a skill's checklist, check the boxes and add a completion time
|
|
|
206
219
|
| `bun run clean` | Remove build artifacts |
|
|
207
220
|
| `bun run devcheck` | Lint + format + typecheck + security + changelog sync |
|
|
208
221
|
| `bun run audit:refresh` | Delete `bun.lock`, reinstall, and re-run `bun audit`. Use when `devcheck` flags a transitive advisory — Bun's `update` is sticky on transitive resolutions, so the advisory may be a stale-lockfile false positive. If it survives the refresh, it's real. |
|
|
222
|
+
| `bun run lint:mcp` | Run the MCP definition linter standalone (rule catalog: `api-linter` skill) |
|
|
223
|
+
| `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity (run by devcheck) |
|
|
224
|
+
| `bun run list-skills` | Print the skill registry |
|
|
209
225
|
| `bun run tree` | Generate directory structure doc |
|
|
210
226
|
| `bun run format` | Auto-fix formatting (safe fixes only) |
|
|
211
227
|
| `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
|
|
212
|
-
| `bun run test` | Run tests |
|
|
228
|
+
| `bun run test` | Run tests (Vitest — use `bun run test`, not `bun test`) |
|
|
213
229
|
| `bun run start:stdio` | Production mode (stdio) |
|
|
214
230
|
| `bun run start:http` | Production mode (HTTP) |
|
|
215
231
|
| `bun run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
|
|
@@ -220,7 +236,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
|
|
|
220
236
|
|
|
221
237
|
## Bundling
|
|
222
238
|
|
|
223
|
-
`bun run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips dependency-shipped agent docs (`
|
|
239
|
+
`bun run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips two classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`skills/`, `.claude/`, `.agents/`, `SKILL.md`) and platform-specific native bindings, which would otherwise lock the bundle to the platform it was packed on. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
|
|
224
240
|
|
|
225
241
|
**Adding an env var requires both files:** `server.json` (registry discovery, `environmentVariables[]`) and `manifest.json` (bundle install UX, `mcp_config.env` + `user_config`). `lint:packaging` (run by `devcheck`) verifies the env var names match.
|
|
226
242
|
|
|
@@ -238,14 +254,14 @@ Each per-version file opens with YAML frontmatter:
|
|
|
238
254
|
---
|
|
239
255
|
summary: "One-line headline, ≤350 chars" # required — powers the rollup index
|
|
240
256
|
breaking: false # optional — true flags breaking changes
|
|
241
|
-
security: false # optional — true
|
|
257
|
+
security: false # optional — true ONLY for a source-code security fix, never a dependency CVE bump
|
|
242
258
|
---
|
|
243
259
|
|
|
244
260
|
# 0.1.0 — YYYY-MM-DD
|
|
245
261
|
...
|
|
246
262
|
```
|
|
247
263
|
|
|
248
|
-
`breaking: true` renders a `· ⚠️ Breaking` badge — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames). `security: true` renders a `· 🛡️ Security` badge and pairs with a `## Security` body section. When both are set, badges render `· ⚠️ Breaking · 🛡️ Security`.
|
|
264
|
+
`breaking: true` renders a `· ⚠️ Breaking` badge — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames). `security: true` renders a `· 🛡️ Security` badge and pairs with a `## Security` body section — set it only for a security fix in this server's *own source code*, never for a routine dependency or transitive CVE bump (record those under `## Dependencies`). When both are set, badges render `· ⚠️ Breaking · 🛡️ Security`.
|
|
249
265
|
|
|
250
266
|
`agent-notes` is an optional free-form field for maintenance agents processing the release downstream. Content here won't appear in the rendered CHANGELOG — it's consumed by agents running the `maintenance` skill. Use it for adoption instructions that don't fit the human-facing sections: new files to create, fields to populate, one-time migration steps. Omit entirely when there's nothing to say.
|
|
251
267
|
|
package/Dockerfile
CHANGED
|
@@ -4,15 +4,17 @@
|
|
|
4
4
|
# This stage installs all dependencies (including dev), builds the TypeScript
|
|
5
5
|
# source code into JavaScript, and prepares the production assets.
|
|
6
6
|
# ==============================================================================
|
|
7
|
-
FROM oven/bun:1.3 AS build
|
|
7
|
+
FROM oven/bun:1.3.14 AS build
|
|
8
8
|
|
|
9
9
|
WORKDIR /usr/src/app
|
|
10
10
|
|
|
11
11
|
# Copy dependency manifests for optimized layer caching
|
|
12
12
|
COPY package.json bun.lock ./
|
|
13
13
|
|
|
14
|
-
# Install all dependencies (including dev dependencies for building)
|
|
15
|
-
|
|
14
|
+
# Install all dependencies (including dev dependencies for building).
|
|
15
|
+
# The BuildKit cache mount persists Bun's global package cache across builds.
|
|
16
|
+
RUN --mount=type=cache,target=/root/.bun/install/cache \
|
|
17
|
+
bun install --frozen-lockfile --ignore-scripts
|
|
16
18
|
|
|
17
19
|
# Copy the rest of the source code
|
|
18
20
|
COPY . .
|
|
@@ -28,7 +30,7 @@ RUN bun run build
|
|
|
28
30
|
# application. It uses a slim base image and only includes production
|
|
29
31
|
# dependencies and build artifacts.
|
|
30
32
|
# ==============================================================================
|
|
31
|
-
FROM oven/bun:1.3-slim AS production
|
|
33
|
+
FROM oven/bun:1.3.14-slim AS production
|
|
32
34
|
|
|
33
35
|
WORKDIR /usr/src/app
|
|
34
36
|
|
|
@@ -39,7 +41,7 @@ ENV NODE_ENV=production
|
|
|
39
41
|
# OCI image metadata (https://github.com/opencontainers/image-spec/blob/main/annotations.md)
|
|
40
42
|
ARG APP_VERSION=dev
|
|
41
43
|
LABEL org.opencontainers.image.title="nonprofit-explorer-mcp-server"
|
|
42
|
-
LABEL org.opencontainers.image.description="
|
|
44
|
+
LABEL org.opencontainers.image.description="Search and explore 1.8M+ US nonprofits, fetch Form 990 financials, and access IRS filing history via MCP. STDIO or Streamable HTTP."
|
|
43
45
|
LABEL org.opencontainers.image.licenses="Apache-2.0"
|
|
44
46
|
LABEL org.opencontainers.image.source="https://github.com/cyanheads/nonprofit-explorer-mcp-server"
|
|
45
47
|
LABEL org.opencontainers.image.version="${APP_VERSION}"
|
|
@@ -49,14 +51,21 @@ COPY package.json bun.lock ./
|
|
|
49
51
|
|
|
50
52
|
# Install only production dependencies, ignoring any lifecycle scripts (like 'prepare')
|
|
51
53
|
# that are not needed in the final production image.
|
|
52
|
-
|
|
54
|
+
# `--omit=peer` drops the framework's optional peer tiers (test runner, service
|
|
55
|
+
# SDKs, parsers) that Bun would otherwise auto-install. Anything this server
|
|
56
|
+
# actually imports belongs in its own `dependencies`, so nothing needed at
|
|
57
|
+
# runtime is lost. The OTEL step below carries the same flag — without it, that
|
|
58
|
+
# install re-resolves the graph and pulls every optional peer back in.
|
|
59
|
+
RUN --mount=type=cache,target=/root/.bun/install/cache \
|
|
60
|
+
bun install --production --omit=peer --frozen-lockfile --ignore-scripts
|
|
53
61
|
|
|
54
62
|
# Conditionally install OpenTelemetry optional peer dependencies (Tier 3).
|
|
55
63
|
# These are not bundled by default to keep the base image lean. Enable at build time
|
|
56
64
|
# with: docker build --build-arg OTEL_ENABLED=true
|
|
57
65
|
ARG OTEL_ENABLED=true
|
|
58
|
-
RUN
|
|
59
|
-
|
|
66
|
+
RUN --mount=type=cache,target=/root/.bun/install/cache \
|
|
67
|
+
if [ "$OTEL_ENABLED" = "true" ]; then \
|
|
68
|
+
bun add --omit=dev --omit=peer --ignore-scripts @hono/otel \
|
|
60
69
|
@opentelemetry/instrumentation-http \
|
|
61
70
|
@opentelemetry/exporter-metrics-otlp-http \
|
|
62
71
|
@opentelemetry/exporter-trace-otlp-http \
|
package/LICENSE
CHANGED
|
@@ -186,7 +186,7 @@ Apache License
|
|
|
186
186
|
same "printed page" as the copyright notice for easier
|
|
187
187
|
identification within third-party archives.
|
|
188
188
|
|
|
189
|
-
Copyright
|
|
189
|
+
Copyright 2026 Casey Hand @cyanheads
|
|
190
190
|
|
|
191
191
|
Licensed under the Apache License, Version 2.0 (the "License");
|
|
192
192
|
you may not use this file except in compliance with the License.
|
package/README.md
CHANGED
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
|
|
8
8
|
<div align="center">
|
|
9
9
|
|
|
10
|
-
[](./CHANGELOG.md) [](./LICENSE) [](https://github.com/users/cyanheads/packages/container/package/nonprofit-explorer-mcp-server) [](https://modelcontextprotocol.io/) [](https://www.npmjs.com/package/@cyanheads/nonprofit-explorer-mcp-server) [](https://www.typescriptlang.org/) [](https://bun.sh/)
|
|
11
11
|
|
|
12
12
|
</div>
|
|
13
13
|
|
|
@@ -43,11 +43,12 @@ Search for tax-exempt organizations across the IRS Nonprofit Explorer dataset.
|
|
|
43
43
|
|
|
44
44
|
- Full-text search across org name, alternate name, and city with relevance ranking
|
|
45
45
|
- Supports quoted phrases (`"Red Cross"`), required terms (`+evanston`), excluded terms (`-dental`)
|
|
46
|
-
- Filter by US state
|
|
46
|
+
- Filter by US state, territory, or military postal code (`ZZ` for foreign entities); case-insensitive, and a code outside that set is rejected rather than silently returning national results
|
|
47
47
|
- Filter by NTEE major sector (Arts, Education, Health, Human Services, etc., 1–10)
|
|
48
48
|
- Filter by 501(c) subsection code (e.g., `3` = public charity, `4` = social welfare)
|
|
49
|
-
- Paginated at 25 per page; use `page` (zero-indexed)
|
|
50
|
-
-
|
|
49
|
+
- Paginated at 25 per page; use `page` (zero-indexed) with `num_pages`, `per_page`, and `page_offset` to walk large result sets
|
|
50
|
+
- Zero matches and a page past the last one are both successful searches with an empty `organizations` array and a `notice` explaining which case it is
|
|
51
|
+
- API caps total results at 10,000; `total_results === 10000` means the actual count may be higher, and a `page` whose offset reaches 10,000 is refused with the `pagination_ceiling` error
|
|
51
52
|
- Returns EINs — pass to `nonprofit_get_organization` or `nonprofit_get_filings` for details
|
|
52
53
|
|
|
53
54
|
---
|
|
@@ -184,7 +185,7 @@ MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
|
|
|
184
185
|
|
|
185
186
|
### Prerequisites
|
|
186
187
|
|
|
187
|
-
- [Bun v1.3.
|
|
188
|
+
- [Bun v1.3.14](https://bun.sh/) or higher (or Node.js v24+).
|
|
188
189
|
- No API key required — ProPublica Nonprofit Explorer is a keyless public API.
|
|
189
190
|
|
|
190
191
|
### Installation
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
---
|
|
2
|
+
summary: "Maintenance — mcp-ts-core ^0.10.9 adoption; devcheck gains dependency-specifier and plugin-manifest guards, fresh-scaffold script hardening, and re-synced vendored skills. No tool-surface changes."
|
|
3
|
+
breaking: false
|
|
4
|
+
security: false
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# 0.1.4 — 2026-06-20
|
|
8
|
+
|
|
9
|
+
Framework and tooling refresh. No tool-surface or behavior changes.
|
|
10
|
+
|
|
11
|
+
## Added
|
|
12
|
+
|
|
13
|
+
- **`Dependency Specifiers` devcheck step** — `scripts/check-dependency-specifiers.ts` hard-fails on floating specifiers (`latest`, `*`, pre-release dist-tags) in `package.json` dependency sections and the `bun.lock` `workspaces` map, catching the case where a `bun update --latest` writes a literal dist-tag into the lock and lets a later `bun install` re-resolve past the manifest range. ([cyanheads/mcp-ts-core#246](https://github.com/cyanheads/mcp-ts-core/issues/246))
|
|
14
|
+
- **`packaging.pluginManifests` config flag** (`devcheck.config.json`, default on) — enables `lint:packaging` check 10, validating `.claude-plugin/plugin.json` and `.codex-plugin/{plugin,mcp}.json` for non-empty descriptions, unscoped display names, and a full-name `npx -y` install arg. ([cyanheads/mcp-ts-core#240](https://github.com/cyanheads/mcp-ts-core/issues/240))
|
|
15
|
+
|
|
16
|
+
## Changed
|
|
17
|
+
|
|
18
|
+
- **Vendored skills re-synced** to mcp-ts-core `^0.10.9` — `api-context` documents the new `ctx.content` media-block collector ([cyanheads/mcp-ts-core#239](https://github.com/cyanheads/mcp-ts-core/issues/239)); `api-config`, `api-telemetry`, and `polish-docs-meta` correct the `OTEL_SERVICE_NAME` seeding precedence ([cyanheads/mcp-ts-core#233](https://github.com/cyanheads/mcp-ts-core/issues/233)); `git-wrapup` and `orchestrations` carry the v1.4 tag-annotation and isolation guidance.
|
|
19
|
+
|
|
20
|
+
## Fixed
|
|
21
|
+
|
|
22
|
+
- **Fresh-scaffold devcheck guards** — `build-changelog.ts` (`--check`), `devcheck.ts`, and `check-framework-antipatterns.ts` now skip git-dependent checks cleanly when run before `git init`; `check-skill-versions.ts` skips a `SKILL.md` deleted from the worktree instead of crashing on the stale path. ([cyanheads/mcp-ts-core#237](https://github.com/cyanheads/mcp-ts-core/issues/237), [cyanheads/mcp-ts-core#242](https://github.com/cyanheads/mcp-ts-core/issues/242), [cyanheads/mcp-ts-core#243](https://github.com/cyanheads/mcp-ts-core/issues/243))
|
|
23
|
+
|
|
24
|
+
## Dependencies
|
|
25
|
+
|
|
26
|
+
- `@cyanheads/mcp-ts-core` ^0.10.6 → ^0.10.9
|
|
27
|
+
- `@types/node` ^25.9.3 → ^26.0.0
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
---
|
|
2
|
+
summary: "Fixes nonprofit_search state-filter case handling and pagination-boundary misclassification, wires recovery hints into service-originated errors, and adopts mcp-ts-core ^0.11.5."
|
|
3
|
+
breaking: false
|
|
4
|
+
security: false
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# 0.1.5 — 2026-08-13
|
|
8
|
+
|
|
9
|
+
## Added
|
|
10
|
+
|
|
11
|
+
- **`per_page` / `page_offset`** on `nonprofit_search` output, mirroring ProPublica's pagination metadata when present.
|
|
12
|
+
- **Bun install-security scanner** (`bunfig.toml`) — `@socketsecurity/bun-security-scanner` scans every install; `minimumReleaseAge` blocks packages published in the last 3 days, with `@cyanheads/mcp-ts-core` exempted for same-day framework adoption.
|
|
13
|
+
- **`.mcpb` native-binding strip** — `scripts/clean-mcpb.ts` and `lint:packaging` now also strip and verify `@duckdb/node-bindings-*` platform-specific entries, alongside the existing agent-doc strip.
|
|
14
|
+
- **GitHub community health files** — `CODE_OF_CONDUCT.md`, `CONTRIBUTING.md`, `SECURITY.md`, `FUNDING.yml` under `.github/`, and `.gitattributes` for line-ending normalization and generated-file marking.
|
|
15
|
+
|
|
16
|
+
## Changed
|
|
17
|
+
|
|
18
|
+
- **`tsconfig.json` split** — typechecks `src/` and `tests/` with `noEmit: true`; `tsconfig.build.json` narrows to `src/` for the actual compile.
|
|
19
|
+
- Vendored skills resynced to mcp-ts-core `^0.11.5` conventions.
|
|
20
|
+
- Dockerfile adopts BuildKit cache mounts for `bun install` layers and pins the exact Bun patch (`1.3.14`) over a floating minor tag.
|
|
21
|
+
- devcheck's outdated-dependency check now tolerates versions held back by `minimumReleaseAge` and skips peer-range rows.
|
|
22
|
+
|
|
23
|
+
## Fixed
|
|
24
|
+
|
|
25
|
+
- **`nonprofit_search` state filter** — `state` is uppercased before the ProPublica request and validated against US states, DC, territories, and military codes (plus `ZZ`); an unrecognized value is now rejected as `invalid_state` instead of silently returning unfiltered national results. (#2)
|
|
26
|
+
- **`nonprofit_search` empty-page handling** — a zero-match query and a page past the end of the result set are now both successes (empty `organizations`, plus a `notice` distinguishing which) instead of sharing the same `no_results` error. (#5)
|
|
27
|
+
- **`nonprofit_search` pagination ceiling** — a page at or beyond ProPublica's 10,000-result offset ceiling is now a non-retryable `pagination_ceiling` error instead of the generic `upstream_error`. (#5)
|
|
28
|
+
- **Service-layer error recovery hints** — `nonprofit_get_organization`, `nonprofit_get_filings`, and `nonprofit_search` now attach each tool's own declared `recovery` hint to service-originated `not_found`/`upstream_error`/`pagination_ceiling` throws, not just handler-level ones. (#6)
|
|
29
|
+
|
|
30
|
+
## Dependencies
|
|
31
|
+
|
|
32
|
+
- `@cyanheads/mcp-ts-core` ^0.10.9 → ^0.11.5
|
|
33
|
+
- `typescript` ^6.0.3 → ^7.0.2
|
|
34
|
+
- `@biomejs/biome` ^2.5.0 → ^2.5.7
|
|
35
|
+
- `@types/node` ^26.0.0 → ^26.2.0
|
|
36
|
+
- `tsc-alias` ^1.8.17 → ^1.9.1
|
|
37
|
+
- `vitest` ^4.1.9 → ^4.1.10
|
|
38
|
+
- `ignore` ^7.0.5 → ^7.0.6
|
|
39
|
+
- `@socketsecurity/bun-security-scanner` added ^1.1.2
|
|
40
|
+
- Bun `1.3.11` → `1.3.14`; MCP SDK (peer, via framework) `^1.29.0` → `^1.30.0`
|
package/changelog/template.md
CHANGED
|
@@ -4,10 +4,11 @@
|
|
|
4
4
|
# to author a new release. Set that file's H1 to `# <version> — YYYY-MM-DD`
|
|
5
5
|
# with a concrete date.
|
|
6
6
|
|
|
7
|
-
# Required. One-line GitHub Release-style headline. 350 character cap
|
|
8
|
-
# Default short and scannable. Don't pad, don't stitch
|
|
9
|
-
#
|
|
10
|
-
#
|
|
7
|
+
# Required. One-line GitHub Release-style headline. 350 character cap — a
|
|
8
|
+
# ceiling, not a target. Default short and scannable. Don't pad, don't stitch
|
|
9
|
+
# unrelated changes with commas/semicolons into an inventory — pick the
|
|
10
|
+
# headline, like a tag's theme line. Quotes required: unquoted YAML treats
|
|
11
|
+
# `: ` inside the value as a key separator and fails GitHub's strict parser.
|
|
11
12
|
summary: ""
|
|
12
13
|
|
|
13
14
|
# Set `true` when consumers must change code to upgrade: API removals,
|
|
@@ -15,16 +16,19 @@ summary: ""
|
|
|
15
16
|
# usage. Flagged as `Breaking` in the rollup.
|
|
16
17
|
breaking: false
|
|
17
18
|
|
|
18
|
-
# Set `true`
|
|
19
|
-
#
|
|
20
|
-
#
|
|
19
|
+
# Set `true` ONLY for a security fix in THIS project's own source code — a
|
|
20
|
+
# vulnerability or hardening in code you ship. A dependency or transitive CVE
|
|
21
|
+
# bump is routine maintenance, NOT a security release: record it under
|
|
22
|
+
# `## Dependencies` (with the advisory ID) and leave this `false`. When true,
|
|
23
|
+
# pairs with the `## Security` section below and flags `Security` in the rollup.
|
|
21
24
|
security: false
|
|
22
25
|
|
|
23
26
|
# Optional free-form notes for maintenance agents processing this release.
|
|
24
27
|
# Not rendered in CHANGELOG — consumed by agents running `maintenance` on
|
|
25
|
-
# downstream servers.
|
|
26
|
-
#
|
|
27
|
-
#
|
|
28
|
+
# downstream servers. ADOPTION STEPS ONLY — new files to create, fields to
|
|
29
|
+
# populate, one-time migration steps. Never a second rendering of the body:
|
|
30
|
+
# if a body bullet already says it, name the bullet's symbol instead of
|
|
31
|
+
# re-explaining. Omit the field entirely when there's nothing to say.
|
|
28
32
|
# agent-notes: |
|
|
29
33
|
# <instructions for downstream maintenance agents>
|
|
30
34
|
---
|
|
@@ -39,17 +43,54 @@ security: false
|
|
|
39
43
|
each bullet with the symbol or concept name in **bold** so they can skip
|
|
40
44
|
what's irrelevant and zoom in on what's not.
|
|
41
45
|
|
|
42
|
-
Tone: terse, fact-dense, not verbose.
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
46
|
+
Tone: terse, fact-dense, not verbose. Bullet shape: **symbol** + what
|
|
47
|
+
changed + at most one consumer-facing caveat. One sentence by default, two
|
|
48
|
+
when the second carries weight — a bullet past ~40 words or three sentences
|
|
49
|
+
is wrong. The depth lives one hop away: the linked issue carries the why,
|
|
50
|
+
the commit diff carries the how. The changelog names what changed and what
|
|
51
|
+
a consumer does about it; a reader who wants mechanism opens the link.
|
|
52
|
+
|
|
53
|
+
Model length on THIS guide, never on the previous entry — entries modeled
|
|
54
|
+
on entries compound.
|
|
55
|
+
|
|
56
|
+
Cut (each has shipped as a wall of text; these are the cruft):
|
|
57
|
+
- History/justification narration — how the bug worked, why the old
|
|
58
|
+
behavior was wrong. One short clause at most; the issue carries the story.
|
|
59
|
+
- Design-rationale defense — "chosen over Y because…", "guarding the
|
|
60
|
+
getter is not enough…". That is the author arguing with a reviewer;
|
|
61
|
+
reviewers read the PR, not the changelog.
|
|
62
|
+
- Defensive unchanged-clauses — "X is unchanged", "byte-identical to
|
|
63
|
+
<prev>". Keep one only where its absence would cause a real misread,
|
|
64
|
+
as a short parenthetical.
|
|
65
|
+
- Edge-case inventories — marker lists, not-flagged lists, escape tables.
|
|
66
|
+
Tests and the issue carry those.
|
|
67
|
+
- Mechanism walkthroughs (JSDoc, CLAUDE.md/AGENTS.md, or the relevant
|
|
68
|
+
skill own those), ceremonial framings ("This release introduces…"),
|
|
69
|
+
backwards-compat paragraphs, file-by-file test enumerations. Prefer
|
|
70
|
+
code/symbol names over English re-explanations.
|
|
71
|
+
|
|
72
|
+
Verified ≠ included: the every-claim-verified-from-the-diff rule bounds
|
|
73
|
+
the TRUTH of what you write, never the AMOUNT.
|
|
74
|
+
|
|
75
|
+
Example — same fact, right size:
|
|
76
|
+
|
|
77
|
+
TOO LONG: **`fetchWithTimeout`'s `timeoutMs` bounds the whole exchange**
|
|
78
|
+
(#341). `fetch` resolves once headers arrive and the deadline was
|
|
79
|
+
cleared as the helper returned, so a peer that answered promptly and
|
|
80
|
+
then stalled the stream held the request open indefinitely. A 2xx
|
|
81
|
+
carrying a body now comes back as a passthrough wrapper that disarms
|
|
82
|
+
the deadline when the body closes, errors, or is cancelled; …
|
|
83
|
+
[+90 more words of mechanism and edge cases]
|
|
84
|
+
|
|
85
|
+
RIGHT: **`fetchWithTimeout`'s `timeoutMs` now bounds the whole
|
|
86
|
+
exchange, not just the headers** (#341). A stalled body aborts with
|
|
87
|
+
the same `Timeout` error; the returned `Response` is a wrapper, so
|
|
88
|
+
identity assertions (`toBe(response)`) no longer hold.
|
|
50
89
|
|
|
51
90
|
Narrative intro: skip by default. Add one short sentence only when the
|
|
52
|
-
release theme genuinely needs framing the bullets can't carry.
|
|
91
|
+
release theme genuinely needs framing the bullets can't carry. When many
|
|
92
|
+
bullets share one upgrade consequence, state it ONCE — intro line or
|
|
93
|
+
agent-notes — never per bullet.
|
|
53
94
|
|
|
54
95
|
Sections: Keep a Changelog order — Added, Changed, Deprecated, Removed,
|
|
55
96
|
Fixed, Security. Include only sections with entries; delete the rest
|