@cyanheads/cdc-health-mcp-server 0.6.4 → 0.6.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/.mcpbignore +10 -0
- package/CLAUDE.md +51 -13
- package/README.md +9 -3
- package/manifest.json +40 -0
- package/package.json +25 -8
- package/server.json +4 -4
package/.mcpbignore
ADDED
package/CLAUDE.md
CHANGED
|
@@ -1,8 +1,9 @@
|
|
|
1
1
|
# Agent Protocol
|
|
2
2
|
|
|
3
3
|
**Server:** cdc-health-statistics-mcp-server
|
|
4
|
-
**Version:** 0.6.
|
|
5
|
-
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
|
|
4
|
+
**Version:** 0.6.5
|
|
5
|
+
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.9.6`
|
|
6
|
+
**Engines:** Bun ≥1.3.2, Node ≥24.0.0
|
|
6
7
|
|
|
7
8
|
> **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.
|
|
8
9
|
|
|
@@ -64,8 +65,9 @@ When the user asks what to do next, what's left, or needs direction, suggest rel
|
|
|
64
65
|
5. **Add tests** — scaffold tests for existing definitions using the `add-test` skill
|
|
65
66
|
6. **Field-test definitions** — exercise tools/resources/prompts with real inputs using the `field-test` skill, get a report of issues and pain points
|
|
66
67
|
7. **Run `devcheck`** — lint, format, typecheck, and security audit
|
|
67
|
-
8. **Run the `
|
|
68
|
-
9. **Run the `
|
|
68
|
+
8. **Run the `security-pass` skill** — audit handlers for MCP-specific security gaps: output injection, scope blast radius, input sinks, tenant isolation
|
|
69
|
+
9. **Run the `polish-docs-meta` skill** — finalize README, CHANGELOG, metadata, and agent protocol for shipping
|
|
70
|
+
10. **Run the `maintenance` skill** — investigate changelogs, adopt upstream changes, and sync skills after `bun update --latest`
|
|
69
71
|
|
|
70
72
|
Tailor suggestions to what's actually missing or stale — don't recite the full list every time.
|
|
71
73
|
|
|
@@ -73,7 +75,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
|
|
|
73
75
|
|
|
74
76
|
## Core Rules
|
|
75
77
|
|
|
76
|
-
- **Logic throws, framework catches.** Tool/resource handlers are pure — throw on failure, no `try/catch`.
|
|
78
|
+
- **Logic throws, framework catches.** Tool/resource handlers are pure — throw on failure, no `try/catch`. Plain `Error` is fine; the framework catches, classifies, and formats. Use error factories (`notFound()`, `validationError()`, etc.) when the error code matters.
|
|
77
79
|
- **Use `ctx.log`** for request-scoped logging. No `console` calls.
|
|
78
80
|
- **Use `ctx.state`** for tenant-scoped storage. Never access persistence directly.
|
|
79
81
|
- **Check `ctx.elicit` / `ctx.sample`** for presence before calling.
|
|
@@ -285,7 +287,7 @@ src/
|
|
|
285
287
|
|
|
286
288
|
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.
|
|
287
289
|
|
|
288
|
-
**Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent).
|
|
290
|
+
**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.
|
|
289
291
|
|
|
290
292
|
Available skills:
|
|
291
293
|
|
|
@@ -299,17 +301,17 @@ Available skills:
|
|
|
299
301
|
| `add-prompt` | Scaffold a new prompt definition |
|
|
300
302
|
| `add-service` | Scaffold a new service integration |
|
|
301
303
|
| `add-test` | Scaffold test file for a tool, resource, or service |
|
|
302
|
-
| `field-test` | Exercise tools/resources/prompts
|
|
304
|
+
| `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
|
|
303
305
|
| `tool-defs-analysis` | Read-only audit of definition language across the surface (10 categories) |
|
|
304
306
|
| `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
|
|
305
307
|
| `security-pass` | Eight-axis security audit before release (injection, scope, input sinks, leakage, etc.) |
|
|
306
308
|
| `release-and-publish` | Post-wrapup ship workflow — npm, MCP Registry, GHCR |
|
|
307
|
-
| `maintenance` | Investigate, adopt
|
|
309
|
+
| `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
|
|
308
310
|
| `migrate-mcp-ts-template` | Migrate a fork of mcp-ts-template to depend on the framework as a package |
|
|
309
311
|
| `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
|
|
310
312
|
| `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
|
|
311
313
|
| `api-auth` | Auth modes, scopes, JWT/OAuth |
|
|
312
|
-
| `api-canvas` | DataCanvas
|
|
314
|
+
| `api-canvas` | DataCanvas: register tabular data, run SQL, export, plus the `spillover()` helper for big result sets — Tier 3 opt-in |
|
|
313
315
|
| `api-config` | AppConfig, parseConfig, parseEnvConfig, env vars |
|
|
314
316
|
| `api-context` | Context interface, logger, state, progress |
|
|
315
317
|
| `api-errors` | McpError, JsonRpcErrorCode, typed error contracts, error patterns |
|
|
@@ -317,7 +319,7 @@ Available skills:
|
|
|
317
319
|
| `api-services` | LLM, Speech, Graph services |
|
|
318
320
|
| `api-telemetry` | OTel catalog: spans, metrics, completion logs, env config, cardinality rules |
|
|
319
321
|
| `api-testing` | createMockContext, test patterns |
|
|
320
|
-
| `api-utils` | Formatting, parsing, security, pagination, scheduling |
|
|
322
|
+
| `api-utils` | Formatting, parsing, security, pagination, scheduling, telemetry helpers |
|
|
321
323
|
| `api-workers` | Cloudflare Workers runtime |
|
|
322
324
|
|
|
323
325
|
When you complete a skill's checklist, check the boxes and add a completion timestamp at the end (e.g., `Completed: 2026-03-11`).
|
|
@@ -331,15 +333,49 @@ When you complete a skill's checklist, check the boxes and add a completion time
|
|
|
331
333
|
| `bun run build` | Compile TypeScript |
|
|
332
334
|
| `bun run rebuild` | Clean + build |
|
|
333
335
|
| `bun run clean` | Remove build artifacts |
|
|
334
|
-
| `bun run devcheck` | Lint + format + typecheck + security |
|
|
336
|
+
| `bun run devcheck` | Lint + format + typecheck + security + changelog sync |
|
|
337
|
+
| `bun run audit:refresh` | Delete `bun.lock`, reinstall, and re-audit. Use when `devcheck` flags a transitive advisory — stale lockfile can mask already-patched deps. If advisory survives, it's real. |
|
|
335
338
|
| `bun run tree` | Generate directory structure doc |
|
|
336
339
|
| `bun run format` | Auto-fix formatting |
|
|
340
|
+
| `bun run list-skills` | Print skill index from project `skills/` |
|
|
341
|
+
| `bun run bundle` | Build and pack as `.mcpb` for one-click Claude Desktop install |
|
|
342
|
+
| `bun run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
|
|
343
|
+
| `bun run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
|
|
337
344
|
| `bun run test` | Run tests |
|
|
338
345
|
| `bun run start:stdio` | Production mode (stdio) — `bun run rebuild && bun run start:stdio` for dev smoke-tests |
|
|
339
346
|
| `bun run start:http` | Production mode (HTTP) — `bun run rebuild && bun run start:http` for dev smoke-tests |
|
|
340
347
|
|
|
341
348
|
---
|
|
342
349
|
|
|
350
|
+
## Bundling
|
|
351
|
+
|
|
352
|
+
`bun run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. MCPB is stdio-only — HTTP deployments are unaffected. Delete `manifest.json` and `.mcpbignore` to skip; `lint:packaging` skips cleanly when `manifest.json` is absent.
|
|
353
|
+
|
|
354
|
+
**Adding an env var requires both files:** `server.json` (`environmentVariables[]`) and `manifest.json` (`mcp_config.env` + `user_config`). `lint:packaging` (wired into `devcheck`) verifies alignment.
|
|
355
|
+
|
|
356
|
+
---
|
|
357
|
+
|
|
358
|
+
## Changelog
|
|
359
|
+
|
|
360
|
+
Directory-based, grouped by minor series. Source of truth: `changelog/<major.minor>.x/<version>.md` — one file per release. `changelog/template.md` is a pristine format reference — never edit or move it. `CHANGELOG.md` is a navigation index regenerated by `bun run changelog:build` — devcheck hard-fails on drift; never hand-edit it.
|
|
361
|
+
|
|
362
|
+
Each per-version file opens with YAML frontmatter:
|
|
363
|
+
|
|
364
|
+
```markdown
|
|
365
|
+
---
|
|
366
|
+
summary: "One-line headline, ≤350 chars"
|
|
367
|
+
breaking: false
|
|
368
|
+
security: false
|
|
369
|
+
---
|
|
370
|
+
|
|
371
|
+
# 0.7.0 — YYYY-MM-DD
|
|
372
|
+
...
|
|
373
|
+
```
|
|
374
|
+
|
|
375
|
+
**Section order** (Keep a Changelog): Added, Changed, Deprecated, Removed, Fixed, Security. Include only sections with entries.
|
|
376
|
+
|
|
377
|
+
---
|
|
378
|
+
|
|
343
379
|
## Imports
|
|
344
380
|
|
|
345
381
|
```ts
|
|
@@ -359,9 +395,11 @@ import { getSocrataService } from '@/services/socrata/socrata-service.js';
|
|
|
359
395
|
- [ ] Optional nested objects: handler guards for empty inner values from form-based clients (`if (input.obj?.field && ...)`, not just `if (input.obj)`). When regex/length constraints matter, use `z.union([z.literal(''), z.string().regex(...).describe(...)])` — literal variants are exempt from `describe-on-fields`.
|
|
360
396
|
- [ ] JSDoc `@fileoverview` + `@module` on every file
|
|
361
397
|
- [ ] `ctx.log` for logging, `ctx.state` for storage
|
|
362
|
-
- [ ] Handlers throw on failure —
|
|
398
|
+
- [ ] Handlers throw on failure — error factories or plain `Error`, no try/catch
|
|
363
399
|
- [ ] `format()` renders all data the LLM needs — different clients forward different surfaces (Claude Code → `structuredContent`, Claude Desktop → `content[]`); both must carry the same data
|
|
364
|
-
- [ ]
|
|
400
|
+
- [ ] If wrapping external API: raw/domain/output schemas reviewed against real upstream sparsity/nullability before finalizing required vs optional fields
|
|
401
|
+
- [ ] If wrapping external API: normalization and `format()` preserve uncertainty; do not fabricate facts from missing upstream data
|
|
402
|
+
- [ ] If wrapping external API: tests include at least one sparse payload case with omitted upstream fields
|
|
365
403
|
- [ ] Registered in `createApp()` arrays (directly or via barrel exports)
|
|
366
404
|
- [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
|
|
367
405
|
- [ ] `bun run devcheck` passes
|
package/README.md
CHANGED
|
@@ -1,15 +1,21 @@
|
|
|
1
1
|
<div align="center">
|
|
2
2
|
<h1>@cyanheads/cdc-health-mcp-server</h1>
|
|
3
|
-
<p><b>
|
|
3
|
+
<p><b>Discover and query CDC public health datasets via the Socrata SODA API via MCP. STDIO or Streamable HTTP.</b>
|
|
4
4
|
<div>3 Tools • 2 Resources • 1 Prompt</div>
|
|
5
5
|
</p>
|
|
6
6
|
</div>
|
|
7
7
|
|
|
8
8
|
<div align="center">
|
|
9
9
|
|
|
10
|
-
[](./CHANGELOG.md) [](./LICENSE) [](https://github.com/users/cyanheads/packages/container/package/cdc-health-mcp-server) [](https://modelcontextprotocol.io/) [](https://www.npmjs.com/package/@cyanheads/cdc-health-mcp-server) [](https://www.typescriptlang.org/) [](https://bun.sh/)
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
</div>
|
|
13
|
+
|
|
14
|
+
<div align="center">
|
|
15
|
+
|
|
16
|
+
[](https://github.com/cyanheads/cdc-health-mcp-server/releases/latest/download/cdc-health-mcp-server.mcpb) [](https://cursor.com/en/install-mcp?name=cdc-health-mcp-server&config=eyJjb21tYW5kIjogIm5weCIsICJhcmdzIjogWyIteSIsICJAY3lhbmhlYWRzL2NkYy1oZWFsdGgtbWNwLXNlcnZlckBsYXRlc3QiXSwgImVudiI6IHsiTUNQX1RSQU5TUE9SVF9UWVBFIjogInN0ZGlvIiwgIk1DUF9MT0dfTEVWRUwiOiAiaW5mbyJ9fQ==) [](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%20%22cdc-health-mcp-server%22%2C%20%22command%22%3A%20%22npx%22%2C%20%22args%22%3A%20%5B%22-y%22%2C%20%22%40cyanheads/cdc-health-mcp-server%40latest%22%5D%2C%20%22env%22%3A%20%7B%22MCP_TRANSPORT_TYPE%22%3A%20%22stdio%22%2C%20%22MCP_LOG_LEVEL%22%3A%20%22info%22%7D%7D)
|
|
17
|
+
|
|
18
|
+
[](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
|
|
13
19
|
|
|
14
20
|
</div>
|
|
15
21
|
|
package/manifest.json
ADDED
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
{
|
|
2
|
+
"manifest_version": "0.3",
|
|
3
|
+
"name": "cdc-health-mcp-server",
|
|
4
|
+
"version": "0.6.5",
|
|
5
|
+
"description": "Discover and query CDC public health datasets via the Socrata SODA API.",
|
|
6
|
+
"author": { "name": "cyanheads" },
|
|
7
|
+
"server": {
|
|
8
|
+
"type": "node",
|
|
9
|
+
"entry_point": "dist/index.js",
|
|
10
|
+
"mcp_config": {
|
|
11
|
+
"command": "node",
|
|
12
|
+
"args": ["${__dirname}/dist/index.js"],
|
|
13
|
+
"env": {
|
|
14
|
+
"MCP_TRANSPORT_TYPE": "stdio",
|
|
15
|
+
"MCP_AUTH_MODE": "none",
|
|
16
|
+
"NODE_ENV": "production"
|
|
17
|
+
}
|
|
18
|
+
}
|
|
19
|
+
},
|
|
20
|
+
"compatibility": {
|
|
21
|
+
"runtimes": { "node": ">=24.0.0" }
|
|
22
|
+
},
|
|
23
|
+
"tools_generated": true,
|
|
24
|
+
"prompts_generated": true,
|
|
25
|
+
"user_config": {
|
|
26
|
+
"CDC_APP_TOKEN": {
|
|
27
|
+
"title": "Socrata App Token",
|
|
28
|
+
"type": "string",
|
|
29
|
+
"description": "Optional app token for higher CDC Open Data rate limits.",
|
|
30
|
+
"required": false
|
|
31
|
+
},
|
|
32
|
+
"MCP_LOG_LEVEL": {
|
|
33
|
+
"title": "Log Level",
|
|
34
|
+
"type": "string",
|
|
35
|
+
"description": "Minimum log level for output (debug, info, warn, error).",
|
|
36
|
+
"required": false,
|
|
37
|
+
"default": "info"
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
}
|
package/package.json
CHANGED
|
@@ -1,14 +1,23 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@cyanheads/cdc-health-mcp-server",
|
|
3
|
-
"version": "0.6.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.6.5",
|
|
4
|
+
"description": "Discover and query CDC public health datasets via the Socrata SODA API via MCP. STDIO or Streamable HTTP.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
7
7
|
"types": "dist/index.d.ts",
|
|
8
8
|
"bin": {
|
|
9
9
|
"cdc-health-mcp-server": "dist/index.js"
|
|
10
10
|
},
|
|
11
|
-
"files": [
|
|
11
|
+
"files": [
|
|
12
|
+
"dist/",
|
|
13
|
+
"README.md",
|
|
14
|
+
"LICENSE",
|
|
15
|
+
"CLAUDE.md",
|
|
16
|
+
"Dockerfile",
|
|
17
|
+
"server.json",
|
|
18
|
+
"manifest.json",
|
|
19
|
+
".mcpbignore"
|
|
20
|
+
],
|
|
12
21
|
"scripts": {
|
|
13
22
|
"build": "bun scripts/build.ts",
|
|
14
23
|
"rebuild": "bun scripts/clean.ts && bun scripts/build.ts",
|
|
@@ -17,6 +26,13 @@
|
|
|
17
26
|
"tree": "bun scripts/tree.ts",
|
|
18
27
|
"format": "biome check --write --unsafe .",
|
|
19
28
|
"lint:mcp": "bun scripts/lint-mcp.ts",
|
|
29
|
+
"lint:packaging": "bun scripts/lint-packaging.ts",
|
|
30
|
+
"list-skills": "bun scripts/list-skills.ts",
|
|
31
|
+
"audit:refresh": "rm -f bun.lock && bun install && bun audit",
|
|
32
|
+
"bundle": "bun run build && npx -y @anthropic-ai/mcpb pack . dist/cdc-health-mcp-server.mcpb",
|
|
33
|
+
"publish-mcp": "bun run build && npm publish --access public",
|
|
34
|
+
"changelog:build": "bun scripts/build-changelog.ts",
|
|
35
|
+
"changelog:check": "bun scripts/check-docs-sync.ts",
|
|
20
36
|
"test": "vitest run",
|
|
21
37
|
"start:stdio": "MCP_TRANSPORT_TYPE=stdio node dist/index.js",
|
|
22
38
|
"start:http": "MCP_TRANSPORT_TYPE=http node dist/index.js"
|
|
@@ -61,18 +77,19 @@
|
|
|
61
77
|
"access": "public"
|
|
62
78
|
},
|
|
63
79
|
"dependencies": {
|
|
64
|
-
"@cyanheads/mcp-ts-core": "^0.9.
|
|
65
|
-
"pino-pretty": "^13.1.3"
|
|
80
|
+
"@cyanheads/mcp-ts-core": "^0.9.6",
|
|
81
|
+
"pino-pretty": "^13.1.3",
|
|
82
|
+
"zod": "^4.4.3"
|
|
66
83
|
},
|
|
67
84
|
"devDependencies": {
|
|
68
85
|
"@biomejs/biome": "^2.4.15",
|
|
69
86
|
"@opentelemetry/api": "^1.9.1",
|
|
70
|
-
"@types/node": "^25.
|
|
71
|
-
"@vitest/coverage-istanbul": "^4.1.
|
|
87
|
+
"@types/node": "^25.9.1",
|
|
88
|
+
"@vitest/coverage-istanbul": "^4.1.7",
|
|
72
89
|
"depcheck": "^1.4.7",
|
|
73
90
|
"ignore": "^7.0.5",
|
|
74
91
|
"tsc-alias": "^1.8.17",
|
|
75
92
|
"typescript": "^6.0.3",
|
|
76
|
-
"vitest": "^4.1.
|
|
93
|
+
"vitest": "^4.1.7"
|
|
77
94
|
}
|
|
78
95
|
}
|
package/server.json
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
{
|
|
2
2
|
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
|
|
3
3
|
"name": "io.github.cyanheads/cdc-health-mcp-server",
|
|
4
|
-
"description": "
|
|
4
|
+
"description": "Discover and query CDC public health datasets via the Socrata SODA API.",
|
|
5
5
|
"repository": {
|
|
6
6
|
"url": "https://github.com/cyanheads/cdc-health-mcp-server",
|
|
7
7
|
"source": "github"
|
|
8
8
|
},
|
|
9
|
-
"version": "0.6.
|
|
9
|
+
"version": "0.6.5",
|
|
10
10
|
"remotes": [
|
|
11
11
|
{
|
|
12
12
|
"type": "streamable-http",
|
|
@@ -19,7 +19,7 @@
|
|
|
19
19
|
"registryBaseUrl": "https://registry.npmjs.org",
|
|
20
20
|
"identifier": "@cyanheads/cdc-health-mcp-server",
|
|
21
21
|
"runtimeHint": "node",
|
|
22
|
-
"version": "0.6.
|
|
22
|
+
"version": "0.6.5",
|
|
23
23
|
"packageArguments": [
|
|
24
24
|
{
|
|
25
25
|
"type": "positional",
|
|
@@ -54,7 +54,7 @@
|
|
|
54
54
|
"registryBaseUrl": "https://registry.npmjs.org",
|
|
55
55
|
"identifier": "@cyanheads/cdc-health-mcp-server",
|
|
56
56
|
"runtimeHint": "node",
|
|
57
|
-
"version": "0.6.
|
|
57
|
+
"version": "0.6.5",
|
|
58
58
|
"packageArguments": [
|
|
59
59
|
{
|
|
60
60
|
"type": "positional",
|