@cyanheads/finnhub-mcp-server 0.1.4 → 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 CHANGED
@@ -1,11 +1,11 @@
1
1
  # Developer Protocol
2
2
 
3
3
  **Server:** finnhub-mcp-server
4
- **Version:** 0.1.4
5
- **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.12.3`
6
- **Engines:** Bun ≥1.3.0, Node ≥24.0.0
4
+ **Version:** 0.1.5
5
+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.6`
6
+ **Engines:** Bun ≥1.4.0, Node ≥24.0.0
7
7
  **MCP SDK:** `@modelcontextprotocol/server` 2.0.0
8
- **Zod:** ^4.4.3
8
+ **Zod:** ^4.6.5
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.
11
11
 
@@ -18,6 +18,7 @@
18
18
  - **Use `ctx.state`** for tenant-scoped storage. Never access persistence directly.
19
19
  - **Need input the caller didn't supply?** `return ctx.requestInput(...)` and read `ctx.inputs` when the handler is re-entered. Never `await` for user input mid-handler.
20
20
  - **Secrets in env vars only** — never hardcoded.
21
+ - **Cut noise.** Add only what earns its place: no speculative generality, no guards for states the framework already prevents (Zod-validated params, classified errors), no abstraction until a third caller proves it, no option nothing sets.
21
22
  - **Close the loop on issues.** When implementing work tracked by a GitHub issue, comment on the issue with what landed and close it. Do both — a comment without a close leaves stale issues open; a close without a comment leaves no record of what shipped. The comment is for future readers — state the concrete changes, not the conversation that produced them.
22
23
 
23
24
  ---
@@ -141,6 +142,22 @@ await createApp({
141
142
 
142
143
  `instructions` is optional server-level orientation, sent on every `initialize` as session-level context. Use it for deployment guidance (connection aliases, regional notes, scope hints) instead of repeating the same context across tool descriptions. Client adoption is uneven, but there's no downside when set.
143
144
 
145
+ ### Session posture and shutdown
146
+
147
+ Two more `createApp()` options shape how the server runs rather than how it presents itself:
148
+
149
+ ```ts
150
+ await createApp({
151
+ sessionMode: 'stateless', // or { default: 'stateful', require: 'stateful' }
152
+ setup(core) { startMyWatcher(core.config); },
153
+ async teardown() { await stopMyWatcher(); },
154
+ });
155
+ ```
156
+
157
+ `sessionMode` declares the HTTP session posture in `src/` instead of leaving it to a deployment's `MCP_SESSION_MODE`, which still wins whenever it carries a meaningful value (an empty string and an unsubstituted `${…}` placeholder read as unset and fall through to the option). Add `require: 'stateful'` when a tool asks the caller for input mid-handler via `ctx.requestInput`: startup then fails with a `ConfigurationError` rather than serving a mode in which a 2025-era client can never answer the prompt. Stdio is never refused.
158
+
159
+ `teardown(core)` is the `setup()` counterpart — release a watcher, socket, or non-`unref()`'d timer there. It runs after the transport stops and before the logger closes, on every shutdown path, and a signal-triggered shutdown then exits the process explicitly (0, or 1 if a step never settles within the framework's 10 s ceiling).
160
+
144
161
  ---
145
162
 
146
163
  ## Context
@@ -165,7 +182,7 @@ Handlers receive a unified `ctx` object. Key properties:
165
182
 
166
183
  Handlers throw — the framework catches, classifies, and formats.
167
184
 
168
- **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.
185
+ **Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` 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 unless the message already contains it verbatim); override with an explicit `{ recovery: { hint: '...' } }` when dynamic runtime context matters. Forwarding it is lint-enforced per throw site (`error-contract-recovery-unforwarded`). Mark an entry the service layer throws with `thrownBy: 'service'` so `error-contract-unthrown` skips it — lint-only metadata, nothing at runtime reads it. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely and don't need declaring.
169
186
 
170
187
  ```ts
171
188
  import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
@@ -198,7 +215,7 @@ throw new Error('Invalid query format'); // → ValidationError
198
215
 
199
216
  // McpError — when no factory exists for the code
200
217
  import { McpError, JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
201
- throw new McpError(JsonRpcErrorCode.DatabaseError, 'Connection failed', { pool: 'primary' });
218
+ throw new McpError(JsonRpcErrorCode.InitializationFailed, 'Connection failed', { pool: 'primary' });
202
219
  ```
203
220
 
204
221
  See framework CLAUDE.md and the `api-errors` skill for the full auto-classification table, all available factories, and the contract reference.
@@ -240,9 +257,9 @@ src/
240
257
 
241
258
  ## Skills
242
259
 
243
- 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.
260
+ Skills are modular instructions in `framework-skills/` at the project root. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. The directory is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, so a server that ships `.claude-plugin/` or `.codex-plugin/` would hand these development skills to every agent that installs it. Keep `skills/` free for skills meant for those agents.
244
261
 
245
- **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.
262
+ **Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `framework-skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
246
263
 
247
264
  Available skills:
248
265
 
@@ -261,12 +278,14 @@ Available skills:
261
278
  | `security-pass` | Audit server for MCP-flavored security gaps: output injection, scope blast radius, input sinks, tenant isolation |
262
279
  | `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase |
263
280
  | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
264
- | `git-wrapup` | Land working-tree changes as a versioned commit + annotated tag — version bump, changelog, verify, tag. Local only. |
265
- | `release-and-publish` | Push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
281
+ | `git-wrapup` | Land working-tree changes as a commit stack — version bump, changelog, verify, commit by concern, release commit on top. No tag, no push to main; opens the release PR when the project declares release PR mode |
282
+ | `release-pr-review` | Review pass on an open release PR — simplifier + correctness review, fixes as ordinary commits on top of the stack, PR body kept in sync. Release PR mode only |
283
+ | `release-and-publish` | Fast-forward merge (release PR mode) + tag + push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
266
284
  | `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
267
285
  | `orchestrations` | Chain task skills into a gated multi-phase pipeline — build-out, QA-fix, update-ship — when you can spawn sub-agents |
268
286
  | `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
269
287
  | `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
288
+ | `techniques` | Catalog of response/data-shaping techniques — overflow handling, payload shaping, retrieval patterns |
270
289
  | `api-auth` | Auth modes, scopes, JWT/OAuth |
271
290
  | `api-canvas` | DataCanvas: register tabular data, run SQL, export, plus the `spillover()` helper for big result sets — Tier 3 opt-in |
272
291
  | `api-config` | AppConfig, parseConfig, env vars |
@@ -279,9 +298,8 @@ Available skills:
279
298
  | `api-utils` | Formatting, parsing, security, pagination, scheduling, telemetry helpers |
280
299
  | `api-telemetry` | OTel catalog: spans, metrics, completion logs, env config, cardinality rules |
281
300
  | `api-workers` | Cloudflare Workers runtime |
282
- | `techniques` | Catalog of response/data-shaping techniques — overflow handling, payload shaping, retrieval patterns |
283
301
 
284
- **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.
302
+ **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*, `framework-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.
285
303
 
286
304
  When you complete a skill's checklist, check the boxes and add a completion timestamp at the end (e.g., `Completed: 2026-03-11`).
287
305
 
@@ -300,7 +318,8 @@ When you complete a skill's checklist, check the boxes and add a completion time
300
318
  | `bun run lint:mcp` | Run the MCP definition linter standalone (rule catalog: `api-linter` skill) |
301
319
  | `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity (run by devcheck) |
302
320
  | `bun run list-skills` | Print the skill registry |
303
- | `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. |
321
+ | `bun run audit:fix` | `bun audit fix` — upgrade vulnerable packages to the lowest safe version within existing ranges (`--dry-run` previews, `--latest` rewrites ranges). First response when `devcheck` flags a transitive advisory; then `bun update <name>`, then `bun dedupe` |
322
+ | `bun run audit:refresh` | Delete `bun.lock` and reinstall. Last resort after `audit:fix`, `bun update <name>`, and `bun dedupe` — re-resolves every ranged dep (the framework pin included) and rewrites the lockfile as `lockfileVersion: 2` |
304
323
  | `bun run tree` | Generate directory structure doc |
305
324
  | `bun run format` | Auto-fix formatting (safe fixes only) |
306
325
  | `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
@@ -311,15 +330,17 @@ When you complete a skill's checklist, check the boxes and add a completion time
311
330
  | `bun run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
312
331
  | `bun run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install |
313
332
 
333
+ **CI is one file.** `.github/workflows/codeql.yml` (scaffolded) is the only GitHub Actions workflow: CodeQL is GitHub-owned end to end, and the file runs only while the repo's CodeQL *default setup* is turned off. Verification — `devcheck`, tests, the release gates — runs locally; don't add a workflow that re-runs it.
334
+
314
335
  ---
315
336
 
316
337
  ## Bundling
317
338
 
318
- `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.
339
+ `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 (`framework-skills/`, `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.
319
340
 
320
- **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.
341
+ **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, that every `user_config` option is wired into `mcp_config.env` as `"X": "${user_config.X}"` (the host substitutes nothing else — `"${X}"` reaches the server as that literal string), and that an optional string option carries `"default": ""`.
321
342
 
322
- **README install badges** (Claude Desktop `.mcpb`, Cursor, VS Code) and the `base64` / `encodeURIComponent` config-generation commands are ship-time concerns — run the `polish-docs-meta` skill, which carries the badge format, layout, and generation snippets in `skills/polish-docs-meta/references/readme.md`.
343
+ **README install badges** (Claude Desktop `.mcpb`, Cursor, VS Code) and the `base64` / `encodeURIComponent` config-generation commands are ship-time concerns — run the `polish-docs-meta` skill, which carries the badge format, layout, and generation snippets in `framework-skills/polish-docs-meta/references/readme.md`.
323
344
 
324
345
  ---
325
346
 
@@ -344,12 +365,18 @@ security: false # optional — true ONLY for a source
344
365
 
345
366
  `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.
346
367
 
347
- **Section order** (Keep a Changelog): Added, Changed, Deprecated, Removed, Fixed, Security. Include only sections with entries — don't ship empty headers.
368
+ **Section order:** the Keep a Changelog sequence — Added, Changed, Deprecated, Removed, Fixed, Security — then `Dependencies` last. Include only sections with entries — don't ship empty headers.
348
369
 
349
370
  **Tag annotations** render as GitHub Release bodies via `--notes-from-tag`. They must be structured markdown — never a flat comma-separated string. Subject omits the version number (GitHub prepends it). See `changelog/template.md` for the full format reference.
350
371
 
351
372
  ---
352
373
 
374
+ ## Publishing
375
+
376
+ **Every release goes through a release PR, straight-through** — `git-wrapup`'s "Release PR mode", mode `straight-through`. One run: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the changelog entry plus a gates section); `release-and-publish` then fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the branch, and publishes. A caller's brief may run a given release as `gated` instead — a `release-pr-review` pass on the open PR before `release-and-publish`. **Never merge through the GitHub UI or `gh pr merge`**: squash and rebase-merge are disabled in the repo settings because both rewrite the stack (rebase-merge also strips the SSH signatures), and a merge commit breaks the linear history.
377
+
378
+ ---
379
+
353
380
  ## Imports
354
381
 
355
382
  ```ts
@@ -376,7 +403,7 @@ import { getMyService } from '@/services/my-domain/my-service.js';
376
403
  - [ ] If wrapping external API: tests include at least one sparse payload case with omitted upstream fields
377
404
  - [ ] Registered in `createApp()` arrays (directly or via barrel exports)
378
405
  - [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
379
- - [ ] `.codex-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; `interface.displayName` = package name; `interface.shortDescription` from `package.json` description
380
- - [ ] `.codex-plugin/mcp.json` updated — server name key matches `package.json` name; env vars added for any required API keys
381
- - [ ] `.claude-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; inline `mcpServers` entry with server name key, env vars for any required API keys
406
+ - [ ] `.codex-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; `interface.displayName` = the unscoped repo name (never the npm scope — `lint:packaging` enforces this); `interface.shortDescription` from `package.json` description
407
+ - [ ] `.codex-plugin/mcp.json` updated — server name key is the unscoped repo name; every user-supplied variable (API key, contact email, instance URL) is listed in `env_vars` so Codex forwards it from the user's environment. Never write `"KEY": ""` into `env` — an empty value replaces the user's exported key and is read as unset
408
+ - [ ] `.claude-plugin/plugin.json` populated — `name`, `version`, `description`, `author`, `repository`, `license`, `keywords` from `package.json`; inline `mcpServers` entry keyed by the unscoped repo name. Every user-supplied variable is declared under `userConfig` (`type`, `title`, `description`; `sensitive: true` for keys and tokens; `required: true` or `default: ""`) and referenced from `env` as `"KEY": "${user_config.<option>}"` — mirror the `user_config` block in `manifest.json`. Never write `"KEY": ""` into `env`
382
409
  - [ ] `npm run devcheck` passes
package/CLAUDE.md CHANGED
@@ -1,11 +1,11 @@
1
1
  # Developer Protocol
2
2
 
3
3
  **Server:** finnhub-mcp-server
4
- **Version:** 0.1.4
5
- **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.12.3`
6
- **Engines:** Bun ≥1.3.0, Node ≥24.0.0
4
+ **Version:** 0.1.5
5
+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.6`
6
+ **Engines:** Bun ≥1.4.0, Node ≥24.0.0
7
7
  **MCP SDK:** `@modelcontextprotocol/server` 2.0.0
8
- **Zod:** ^4.4.3
8
+ **Zod:** ^4.6.5
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.
11
11
 
@@ -18,6 +18,7 @@
18
18
  - **Use `ctx.state`** for tenant-scoped storage. Never access persistence directly.
19
19
  - **Need input the caller didn't supply?** `return ctx.requestInput(...)` and read `ctx.inputs` when the handler is re-entered. Never `await` for user input mid-handler.
20
20
  - **Secrets in env vars only** — never hardcoded.
21
+ - **Cut noise.** Add only what earns its place: no speculative generality, no guards for states the framework already prevents (Zod-validated params, classified errors), no abstraction until a third caller proves it, no option nothing sets.
21
22
  - **Close the loop on issues.** When implementing work tracked by a GitHub issue, comment on the issue with what landed and close it. Do both — a comment without a close leaves stale issues open; a close without a comment leaves no record of what shipped. The comment is for future readers — state the concrete changes, not the conversation that produced them.
22
23
 
23
24
  ---
@@ -141,6 +142,22 @@ await createApp({
141
142
 
142
143
  `instructions` is optional server-level orientation, sent on every `initialize` as session-level context. Use it for deployment guidance (connection aliases, regional notes, scope hints) instead of repeating the same context across tool descriptions. Client adoption is uneven, but there's no downside when set.
143
144
 
145
+ ### Session posture and shutdown
146
+
147
+ Two more `createApp()` options shape how the server runs rather than how it presents itself:
148
+
149
+ ```ts
150
+ await createApp({
151
+ sessionMode: 'stateless', // or { default: 'stateful', require: 'stateful' }
152
+ setup(core) { startMyWatcher(core.config); },
153
+ async teardown() { await stopMyWatcher(); },
154
+ });
155
+ ```
156
+
157
+ `sessionMode` declares the HTTP session posture in `src/` instead of leaving it to a deployment's `MCP_SESSION_MODE`, which still wins whenever it carries a meaningful value (an empty string and an unsubstituted `${…}` placeholder read as unset and fall through to the option). Add `require: 'stateful'` when a tool asks the caller for input mid-handler via `ctx.requestInput`: startup then fails with a `ConfigurationError` rather than serving a mode in which a 2025-era client can never answer the prompt. Stdio is never refused.
158
+
159
+ `teardown(core)` is the `setup()` counterpart — release a watcher, socket, or non-`unref()`'d timer there. It runs after the transport stops and before the logger closes, on every shutdown path, and a signal-triggered shutdown then exits the process explicitly (0, or 1 if a step never settles within the framework's 10 s ceiling).
160
+
144
161
  ---
145
162
 
146
163
  ## Context
@@ -165,7 +182,7 @@ Handlers receive a unified `ctx` object. Key properties:
165
182
 
166
183
  Handlers throw — the framework catches, classifies, and formats.
167
184
 
168
- **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.
185
+ **Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` 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 unless the message already contains it verbatim); override with an explicit `{ recovery: { hint: '...' } }` when dynamic runtime context matters. Forwarding it is lint-enforced per throw site (`error-contract-recovery-unforwarded`). Mark an entry the service layer throws with `thrownBy: 'service'` so `error-contract-unthrown` skips it — lint-only metadata, nothing at runtime reads it. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely and don't need declaring.
169
186
 
170
187
  ```ts
171
188
  import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
@@ -198,7 +215,7 @@ throw new Error('Invalid query format'); // → ValidationError
198
215
 
199
216
  // McpError — when no factory exists for the code
200
217
  import { McpError, JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
201
- throw new McpError(JsonRpcErrorCode.DatabaseError, 'Connection failed', { pool: 'primary' });
218
+ throw new McpError(JsonRpcErrorCode.InitializationFailed, 'Connection failed', { pool: 'primary' });
202
219
  ```
203
220
 
204
221
  See framework CLAUDE.md and the `api-errors` skill for the full auto-classification table, all available factories, and the contract reference.
@@ -240,9 +257,9 @@ src/
240
257
 
241
258
  ## Skills
242
259
 
243
- 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.
260
+ Skills are modular instructions in `framework-skills/` at the project root. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. The directory is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, so a server that ships `.claude-plugin/` or `.codex-plugin/` would hand these development skills to every agent that installs it. Keep `skills/` free for skills meant for those agents.
244
261
 
245
- **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.
262
+ **Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `framework-skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
246
263
 
247
264
  Available skills:
248
265
 
@@ -261,12 +278,14 @@ Available skills:
261
278
  | `security-pass` | Audit server for MCP-flavored security gaps: output injection, scope blast radius, input sinks, tenant isolation |
262
279
  | `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase |
263
280
  | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
264
- | `git-wrapup` | Land working-tree changes as a versioned commit + annotated tag — version bump, changelog, verify, tag. Local only. |
265
- | `release-and-publish` | Push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
281
+ | `git-wrapup` | Land working-tree changes as a commit stack — version bump, changelog, verify, commit by concern, release commit on top. No tag, no push to main; opens the release PR when the project declares release PR mode |
282
+ | `release-pr-review` | Review pass on an open release PR — simplifier + correctness review, fixes as ordinary commits on top of the stack, PR body kept in sync. Release PR mode only |
283
+ | `release-and-publish` | Fast-forward merge (release PR mode) + tag + push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
266
284
  | `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
267
285
  | `orchestrations` | Chain task skills into a gated multi-phase pipeline — build-out, QA-fix, update-ship — when you can spawn sub-agents |
268
286
  | `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
269
287
  | `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
288
+ | `techniques` | Catalog of response/data-shaping techniques — overflow handling, payload shaping, retrieval patterns |
270
289
  | `api-auth` | Auth modes, scopes, JWT/OAuth |
271
290
  | `api-canvas` | DataCanvas: register tabular data, run SQL, export, plus the `spillover()` helper for big result sets — Tier 3 opt-in |
272
291
  | `api-config` | AppConfig, parseConfig, env vars |
@@ -279,9 +298,8 @@ Available skills:
279
298
  | `api-utils` | Formatting, parsing, security, pagination, scheduling, telemetry helpers |
280
299
  | `api-telemetry` | OTel catalog: spans, metrics, completion logs, env config, cardinality rules |
281
300
  | `api-workers` | Cloudflare Workers runtime |
282
- | `techniques` | Catalog of response/data-shaping techniques — overflow handling, payload shaping, retrieval patterns |
283
301
 
284
- **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.
302
+ **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*, `framework-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.
285
303
 
286
304
  When you complete a skill's checklist, check the boxes and add a completion timestamp at the end (e.g., `Completed: 2026-03-11`).
287
305
 
@@ -300,7 +318,8 @@ When you complete a skill's checklist, check the boxes and add a completion time
300
318
  | `bun run lint:mcp` | Run the MCP definition linter standalone (rule catalog: `api-linter` skill) |
301
319
  | `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity (run by devcheck) |
302
320
  | `bun run list-skills` | Print the skill registry |
303
- | `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. |
321
+ | `bun run audit:fix` | `bun audit fix` — upgrade vulnerable packages to the lowest safe version within existing ranges (`--dry-run` previews, `--latest` rewrites ranges). First response when `devcheck` flags a transitive advisory; then `bun update <name>`, then `bun dedupe` |
322
+ | `bun run audit:refresh` | Delete `bun.lock` and reinstall. Last resort after `audit:fix`, `bun update <name>`, and `bun dedupe` — re-resolves every ranged dep (the framework pin included) and rewrites the lockfile as `lockfileVersion: 2` |
304
323
  | `bun run tree` | Generate directory structure doc |
305
324
  | `bun run format` | Auto-fix formatting (safe fixes only) |
306
325
  | `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
@@ -311,15 +330,17 @@ When you complete a skill's checklist, check the boxes and add a completion time
311
330
  | `bun run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
312
331
  | `bun run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install |
313
332
 
333
+ **CI is one file.** `.github/workflows/codeql.yml` (scaffolded) is the only GitHub Actions workflow: CodeQL is GitHub-owned end to end, and the file runs only while the repo's CodeQL *default setup* is turned off. Verification — `devcheck`, tests, the release gates — runs locally; don't add a workflow that re-runs it.
334
+
314
335
  ---
315
336
 
316
337
  ## Bundling
317
338
 
318
- `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.
339
+ `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 (`framework-skills/`, `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.
319
340
 
320
- **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.
341
+ **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, that every `user_config` option is wired into `mcp_config.env` as `"X": "${user_config.X}"` (the host substitutes nothing else — `"${X}"` reaches the server as that literal string), and that an optional string option carries `"default": ""`.
321
342
 
322
- **README install badges** (Claude Desktop `.mcpb`, Cursor, VS Code) and the `base64` / `encodeURIComponent` config-generation commands are ship-time concerns — run the `polish-docs-meta` skill, which carries the badge format, layout, and generation snippets in `skills/polish-docs-meta/references/readme.md`.
343
+ **README install badges** (Claude Desktop `.mcpb`, Cursor, VS Code) and the `base64` / `encodeURIComponent` config-generation commands are ship-time concerns — run the `polish-docs-meta` skill, which carries the badge format, layout, and generation snippets in `framework-skills/polish-docs-meta/references/readme.md`.
323
344
 
324
345
  ---
325
346
 
@@ -344,12 +365,18 @@ security: false # optional — true ONLY for a source
344
365
 
345
366
  `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.
346
367
 
347
- **Section order** (Keep a Changelog): Added, Changed, Deprecated, Removed, Fixed, Security. Include only sections with entries — don't ship empty headers.
368
+ **Section order:** the Keep a Changelog sequence — Added, Changed, Deprecated, Removed, Fixed, Security — then `Dependencies` last. Include only sections with entries — don't ship empty headers.
348
369
 
349
370
  **Tag annotations** render as GitHub Release bodies via `--notes-from-tag`. They must be structured markdown — never a flat comma-separated string. Subject omits the version number (GitHub prepends it). See `changelog/template.md` for the full format reference.
350
371
 
351
372
  ---
352
373
 
374
+ ## Publishing
375
+
376
+ **Every release goes through a release PR, straight-through** — `git-wrapup`'s "Release PR mode", mode `straight-through`. One run: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the changelog entry plus a gates section); `release-and-publish` then fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the branch, and publishes. A caller's brief may run a given release as `gated` instead — a `release-pr-review` pass on the open PR before `release-and-publish`. **Never merge through the GitHub UI or `gh pr merge`**: squash and rebase-merge are disabled in the repo settings because both rewrite the stack (rebase-merge also strips the SSH signatures), and a merge commit breaks the linear history.
377
+
378
+ ---
379
+
353
380
  ## Imports
354
381
 
355
382
  ```ts
@@ -376,7 +403,7 @@ import { getMyService } from '@/services/my-domain/my-service.js';
376
403
  - [ ] If wrapping external API: tests include at least one sparse payload case with omitted upstream fields
377
404
  - [ ] Registered in `createApp()` arrays (directly or via barrel exports)
378
405
  - [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
379
- - [ ] `.codex-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; `interface.displayName` = package name; `interface.shortDescription` from `package.json` description
380
- - [ ] `.codex-plugin/mcp.json` updated — server name key matches `package.json` name; env vars added for any required API keys
381
- - [ ] `.claude-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; inline `mcpServers` entry with server name key, env vars for any required API keys
406
+ - [ ] `.codex-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; `interface.displayName` = the unscoped repo name (never the npm scope — `lint:packaging` enforces this); `interface.shortDescription` from `package.json` description
407
+ - [ ] `.codex-plugin/mcp.json` updated — server name key is the unscoped repo name; every user-supplied variable (API key, contact email, instance URL) is listed in `env_vars` so Codex forwards it from the user's environment. Never write `"KEY": ""` into `env` — an empty value replaces the user's exported key and is read as unset
408
+ - [ ] `.claude-plugin/plugin.json` populated — `name`, `version`, `description`, `author`, `repository`, `license`, `keywords` from `package.json`; inline `mcpServers` entry keyed by the unscoped repo name. Every user-supplied variable is declared under `userConfig` (`type`, `title`, `description`; `sensitive: true` for keys and tokens; `required: true` or `default: ""`) and referenced from `env` as `"KEY": "${user_config.<option>}"` — mirror the `user_config` block in `manifest.json`. Never write `"KEY": ""` into `env`
382
409
  - [ ] `npm run devcheck` passes
package/README.md CHANGED
@@ -7,7 +7,7 @@
7
7
 
8
8
  <div align="center">
9
9
 
10
- [![Version](https://img.shields.io/badge/Version-0.1.4-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/finnhub-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/finnhub-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/finnhub-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.0-blueviolet.svg?style=flat-square)](https://bun.sh/)
10
+ [![Version](https://img.shields.io/badge/Version-0.1.5-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/finnhub-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/finnhub-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/finnhub-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.0-blueviolet.svg?style=flat-square)](https://bun.sh/)
11
11
 
12
12
  </div>
13
13
 
@@ -21,9 +21,11 @@
21
21
 
22
22
  ---
23
23
 
24
- ## Tools
24
+ ## Overview
25
25
 
26
- Six tools, name-first: `finnhub_search_symbols` resolves a company name to a US ticker, then the other five work from that symbol — a live quote, full company context, earnings, news, and analyst consensus.
26
+ Real-time US-equity data from Finnhub — quotes, company fundamentals, earnings, analyst recommendations, and financial news. Resolve a company name to a symbol with `finnhub_search_symbols`, then pull live pricing, valuation, or news for it from any MCP client. Runs as a stdio process or a local Streamable HTTP server.
27
+
28
+ ### Tools
27
29
 
28
30
  | Tool | Description |
29
31
  |:---|:---|
@@ -34,9 +36,17 @@ Six tools, name-first: `finnhub_search_symbols` resolves a company name to a US
34
36
  | `finnhub_get_news` | Financial news in two modes: recent articles for one symbol over a date range (`company`), or broad market headlines by category (`market`). |
35
37
  | `finnhub_get_recommendations` | Analyst recommendation trends for one US symbol — strong-buy / buy / hold / sell / strong-sell counts per month, newest first. |
36
38
 
37
- ### `finnhub_search_symbols`
39
+ ### Resources
40
+
41
+ | Resource | Description |
42
+ |:---|:---|
43
+ | `finnhub://news-categories` | The four valid market-news categories (`general`, `forex`, `crypto`, `merger`) with one-line descriptions. |
44
+
45
+ Fully covered by the `category` enum on `finnhub_get_news`, so tool-only clients lose nothing.
38
46
 
39
- Resolve a company name, partial name, or ticker fragment to Finnhub stock symbols. Run this first when you have a name, not a ticker — the rest of the surface needs a symbol.
47
+ ## Capability reference
48
+
49
+ ### `finnhub_search_symbols` <sub>tool</sub>
40
50
 
41
51
  - Full-text match across symbols and descriptions; likely-US Common Stock matches surfaced first
42
52
  - `query` accepts 1–20 characters; use a shorter company name or ticker fragment when needed
@@ -45,9 +55,7 @@ Resolve a company name, partial name, or ticker fragment to Finnhub stock symbol
45
55
 
46
56
  ---
47
57
 
48
- ### `finnhub_get_quote`
49
-
50
- Real-time price quote for one US symbol. The market-hours flag is the point — the response never presents a stale price as live.
58
+ ### `finnhub_get_quote` <sub>tool</sub>
51
59
 
52
60
  - Current price, absolute and percent change, session open/high/low, previous close, and an ISO 8601 quote time
53
61
  - Pairs `/quote` with `/stock/market-status` (parallel fan-out) to derive `priceIsLive` — `true` only when the US market is open; when closed, `current` is the prior close, surfaced as such
@@ -57,9 +65,7 @@ Real-time price quote for one US symbol. The market-hours flag is the point —
57
65
 
58
66
  ---
59
67
 
60
- ### `finnhub_get_company`
61
-
62
- Full company context for one US symbol in a single call — profile is hollow without the valuation numbers, so this is deliberately one tool over three.
68
+ ### `finnhub_get_company` <sub>tool</sub>
63
69
 
64
70
  - Profile: name, exchange, industry, country, currency, market cap, shares outstanding, IPO date, website, logo
65
71
  - Headline fundamentals: P/E (TTM), EPS (TTM), 52-week range, beta, dividend yield, net/gross margin, revenue growth YoY, ROE — every field nullable, surfaced honestly for thinly-covered names rather than zero-filled
@@ -68,52 +74,41 @@ Full company context for one US symbol in a single call — profile is hollow wi
68
74
 
69
75
  ---
70
76
 
71
- ### `finnhub_get_earnings`
72
-
73
- Earnings data for one symbol or across the market, selected by `mode`.
77
+ ### `finnhub_get_earnings` <sub>tool</sub>
74
78
 
75
79
  - `history` (requires `symbol`): past quarters — actual vs. estimate EPS, absolute surprise, and surprise % (the market-moving signal), newest first
76
80
  - `calendar` (uses `from` / `to`, defaults to today through +14 days; optional `symbol` filter): upcoming releases across the market or for one symbol — date, EPS/revenue estimates, expected report time
77
81
  - `limit` (1–100, default 50); reports total rows and discloses truncation
82
+ - `history` without `symbol` → `missing_symbol`; international or paid-only symbol → `not_us_or_paid`
78
83
 
79
84
  ---
80
85
 
81
- ### `finnhub_get_news`
82
-
83
- Financial news for one company or the broad market, selected by `mode`.
86
+ ### `finnhub_get_news` <sub>tool</sub>
84
87
 
85
88
  - `company` (requires `symbol`): recent articles over a date range (defaults to the last 7 days) — headline, source, ISO 8601 datetime, summary, URL
86
89
  - `market` (uses `category`): broad headlines by `general`, `forex`, `crypto`, or `merger` (see the `finnhub://news-categories` resource)
87
90
  - `limit` (1–100, default 15 — news lists run long); articles newest first, with total and truncation disclosure
91
+ - `company` without `symbol` → `missing_symbol`; international or paid-only symbol → `not_us_or_paid`
88
92
 
89
93
  ---
90
94
 
91
- ### `finnhub_get_recommendations`
92
-
93
- Analyst recommendation consensus for one US symbol — the view to pair with the live quote and fundamentals.
95
+ ### `finnhub_get_recommendations` <sub>tool</sub>
94
96
 
95
97
  - Per-month strong-buy / buy / hold / sell / strong-sell counts, newest first (typically 12–24 months of history)
96
98
  - `limit` (1–24, default 12 — one year); reports total months and discloses truncation
97
- - Empty result (no analyst coverage) → `no_coverage`, distinct from an invalid symbol
99
+ - Empty result (no analyst coverage) → `no_coverage`, distinct from an invalid symbol; international or paid-only symbol → `not_us_or_paid`
98
100
 
99
- ## Resource
101
+ ---
100
102
 
101
- | Type | Name | Description |
102
- |:---|:---|:---|
103
- | Resource | `finnhub://news-categories` | The four valid market-news categories (`general`, `forex`, `crypto`, `merger`) with one-line descriptions. |
103
+ ### `finnhub://news-categories` <sub>resource</sub>
104
104
 
105
- The resource is a convenience mirror — its data is fully covered by the `category` enum on `finnhub_get_news`, so tool-only clients lose nothing. Live data (quotes, news, earnings) is intentionally not exposed as a resource: it's time-sensitive, and the value is in the freshness, so it's reachable only through the tools.
105
+ - Returns the four valid `finnhub_get_news` market-mode categories (`general`, `forex`, `crypto`, `merger`) with one-line descriptions, as `application/json`
106
+ - Convenience mirror — fully covered by the `category` enum's `.describe()` on `finnhub_get_news`, so tool-only clients lose nothing
107
+ - Live data (quotes, news, earnings) is intentionally not exposed as a resource — it's time-sensitive, so freshness lives only in the tools
106
108
 
107
109
  ## Features
108
110
 
109
- Built on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core):
110
-
111
- - Declarative tool and resource definitions — single file per primitive, framework handles registration and validation
112
- - Unified error handling — handlers throw, framework catches, classifies, and formats
113
- - Pluggable auth: `none`, `jwt`, `oauth`
114
- - Swappable storage backends: `in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`
115
- - Structured logging with optional OpenTelemetry tracing
116
- - STDIO and Streamable HTTP transports
111
+ Built on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core): stdio and Streamable HTTP transports, pluggable auth (`none` / `jwt` / `oauth`), swappable storage (`in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`), structured logging with optional OpenTelemetry tracing.
117
112
 
118
113
  Finnhub-specific:
119
114
 
@@ -201,7 +196,7 @@ MCP_TRANSPORT_TYPE=http MCP_SESSION_MODE=stateless MCP_HTTP_PORT=3010 FINNHUB_AP
201
196
 
202
197
  ### Prerequisites
203
198
 
204
- - [Bun v1.3.0](https://bun.sh/) or higher (or Node.js v24+).
199
+ - [Bun v1.4.0](https://bun.sh/) or higher (or Node.js v24+).
205
200
  - A free [Finnhub API key](https://finnhub.io/register). The free tier is US equities only, real-time, 60 req/min — international symbols (any exchange-suffixed ticker like `.TO` or `.DE`) and candle/forex endpoints are paid-tier and return a clear error.
206
201
 
207
202
  ### Installation
@@ -242,7 +237,7 @@ All configuration is validated at startup via Zod schemas in `src/config/server-
242
237
  | `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |
243
238
  | `MCP_HTTP_PORT` | Port for the HTTP server. | `3010` |
244
239
  | `MCP_HTTP_ENDPOINT_PATH` | HTTP endpoint path where the MCP server is mounted. | `/mcp` |
245
- | `MCP_SESSION_MODE` | Session handling: `auto`, `stateful`, or `stateless`. This project's `.env.example` and Docker image explicitly select `stateless`; an explicit environment value takes precedence. When unset, the framework defaults to `auto`, which currently resolves to `stateful`. | `auto` when unset; project example uses `stateless` |
240
+ | `MCP_SESSION_MODE` | Session handling: `auto`, `stateful`, or `stateless`. The server declares `stateless` in `src/index.ts`, so an unset variable resolves there; `.env.example` and the Docker image set it explicitly too. An explicit environment value takes precedence. | `stateless` |
246
241
  | `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |
247
242
  | `MCP_LOG_LEVEL` | Log level (RFC 5424: `debug`, `info`, `notice`, `warning`, `error`). | `info` |
248
243
  | `STORAGE_PROVIDER_TYPE` | Storage backend: `in-memory`, `filesystem`, `supabase`, `cloudflare-kv/r2/d1`. | `in-memory` |
@@ -305,7 +300,7 @@ See [`CLAUDE.md`](./CLAUDE.md) / [`AGENTS.md`](./AGENTS.md) for development guid
305
300
 
306
301
  ## Contributing
307
302
 
308
- Issues and pull requests are welcome. Run checks and tests before submitting:
303
+ Issues are welcome. Run checks and tests before submitting:
309
304
 
310
305
  ```sh
311
306
  bun run devcheck
@@ -0,0 +1,26 @@
1
+ ---
2
+ summary: "HTTP sessions default to stateless via a source-level declaration when MCP_SESSION_MODE is unset; Claude Code and Codex plugin installs now deliver FINNHUB_API_KEY instead of a placeholder; mcp-ts-core bumped to ^0.13.6."
3
+ breaking: false
4
+ security: false
5
+ ---
6
+
7
+ # 0.1.5 — 2026-09-20
8
+
9
+ ## Changed
10
+
11
+ - **`MCP_SESSION_MODE`** — `src/index.ts` declares `sessionMode: 'stateless'` via `createApp()`; an unset variable now resolves there instead of the framework's `auto` default, which previously resolved to `stateful`. An explicit environment value still wins. ([#8](https://github.com/cyanheads/finnhub-mcp-server/issues/8))
12
+ - **Repo hygiene** — development skills moved from `skills/` to `framework-skills/` (Claude Code and Codex auto-load a plugin's root `skills/`); adds `CODE_OF_CONDUCT.md`, `CONTRIBUTING.md`, and a CodeQL workflow.
13
+
14
+ ## Fixed
15
+
16
+ - **Plugin installs deliver `FINNHUB_API_KEY`** — `.claude-plugin/plugin.json` gains a `userConfig` block and `.codex-plugin/mcp.json` gains `env_vars`, replacing a hardcoded placeholder that never reached the server.
17
+
18
+ ## Dependencies
19
+
20
+ - `@cyanheads/mcp-ts-core` `^0.12.3` → `^0.13.6`
21
+ - `zod` `^4.4.3` → `^4.6.5`
22
+ - `@biomejs/biome` `2.5.11` → `2.5.14`
23
+ - `@types/node` `26.4.0` → `26.6.1`
24
+ - `ignore` `^7.0.6` → `^7.0.9`
25
+ - `tsc-alias` `^1.9.2` → `^1.9.5`
26
+ - `vitest` `^4.1.11` → `^5.0.1`
@@ -6,8 +6,8 @@
6
6
 
7
7
  # Required. One-line GitHub Release-style headline. 350 character cap — a
8
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
9
+ # unrelated changes with commas/semicolons into an inventory — pick the one
10
+ # headline the release is about. Quotes required: unquoted YAML treats
11
11
  # `: ` inside the value as a key separator and fails GitHub's strict parser.
12
12
  summary: ""
13
13
 
@@ -117,30 +117,13 @@ security: false
117
117
  in that unrelated item's metadata.
118
118
 
119
119
  TAG ANNOTATIONS — the annotated tag body renders as the GitHub Release body
120
- via `gh release create --notes-from-tag`. The tag is a derivative of this
121
- changelog entry — a condensed, scannable version, not a copy. Format:
122
-
123
- <theme — omit version number, GitHub prepends it>
124
- ← blank line
125
- <1-2 sentence context: what this release does>
126
- ← blank line
127
- Dependency bumps: ← section header
128
- ← blank line
129
- - `@cyanheads/mcp-ts-core` ^0.9.1 → ^0.9.6 ← bullet
130
- ← blank line
131
- Changed: ← only sections with entries
132
- ← blank line
133
- - `format()` output includes `query` in text mode
134
- ← blank line
135
- Added:
136
- ← blank line
137
- - `manifest.json` scaffolded for MCPB bundle support
138
- - Install badges (Claude Desktop, Cursor, VS Code)
139
- ← blank line
140
- <N> tests pass; `bun run devcheck` clean. ← footer
141
-
142
- Never a flat comma-separated string. Always structured markdown with
143
- sections. The tag must scan well as a rendered GitHub Release page.
120
+ via `gh release create --notes-from-tag`. It is a condensed digest of this
121
+ entry, never a copy, and its format is owned by the `release-and-publish`
122
+ skill (step 4, "Create the annotated tag"): a short subject line without the
123
+ version, flat headline bullets — no Keep-a-Changelog section headers, no
124
+ gates line — at most one deps line, issue backlinks, and the changelog link
125
+ last. In release-PR mode the `git-wrapup` skill authors those bullets as the
126
+ PR body's `## Changes` and the tag copies them.
144
127
  -->
145
128
 
146
129
  ## Added
package/dist/index.js CHANGED
@@ -13,6 +13,13 @@ await createApp({
13
13
  title: 'finnhub-mcp-server',
14
14
  tools: allToolDefinitions,
15
15
  resources: allResourceDefinitions,
16
+ /**
17
+ * Every tool here is a single-shot read against Finnhub — nothing calls
18
+ * `ctx.requestInput`, so no HTTP caller needs a live session. Declaring the
19
+ * posture in source makes it independent of the launch environment; an
20
+ * explicit `MCP_SESSION_MODE` still wins.
21
+ */
22
+ sessionMode: 'stateless',
16
23
  instructions: 'Real-time US-equity market data via Finnhub. Start from a company name: finnhub_search_symbols resolves it to a US ticker, then finnhub_get_quote / _company / _earnings / _news / _recommendations work from that symbol. Free tier is US equities only — international symbols (exchange-suffixed like ".TO") return a clear not_us_or_paid error. Quotes report whether the price is live or the prior close via priceIsLive.',
17
24
  setup(core) {
18
25
  initFinnhubService(core.config, core.storage);
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,sBAAsB,EAAE,MAAM,6CAA6C,CAAC;AACrF,OAAO,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAC;AAC7E,OAAO,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AAE3E,MAAM,SAAS,CAAC;IACd,IAAI,EAAE,oBAAoB;IAC1B,KAAK,EAAE,oBAAoB;IAC3B,KAAK,EAAE,kBAAkB;IACzB,SAAS,EAAE,sBAAsB;IACjC,YAAY,EACV,kaAAka;IACpa,KAAK,CAAC,IAAI;QACR,kBAAkB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAChD,CAAC;CACF,CAAC,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,sBAAsB,EAAE,MAAM,6CAA6C,CAAC;AACrF,OAAO,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAC;AAC7E,OAAO,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AAE3E,MAAM,SAAS,CAAC;IACd,IAAI,EAAE,oBAAoB;IAC1B,KAAK,EAAE,oBAAoB;IAC3B,KAAK,EAAE,kBAAkB;IACzB,SAAS,EAAE,sBAAsB;IACjC;;;;;OAKG;IACH,WAAW,EAAE,WAAW;IACxB,YAAY,EACV,kaAAka;IACpa,KAAK,CAAC,IAAI;QACR,kBAAkB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAChD,CAAC;CACF,CAAC,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cyanheads/finnhub-mcp-server",
3
- "version": "0.1.4",
3
+ "version": "0.1.5",
4
4
  "mcpName": "io.github.cyanheads/finnhub-mcp-server",
5
5
  "description": "Real-time US-equity quotes, company fundamentals, earnings, analyst trends, and financial news via Finnhub. STDIO or Streamable HTTP.",
6
6
  "type": "module",
@@ -24,6 +24,7 @@
24
24
  "rebuild": "bun run scripts/clean.ts && bun run scripts/build.ts",
25
25
  "clean": "bun run scripts/clean.ts",
26
26
  "devcheck": "bun run scripts/devcheck.ts",
27
+ "audit:fix": "bun audit fix",
27
28
  "audit:refresh": "rm -f bun.lock && bun install && bun audit",
28
29
  "tree": "bun run scripts/tree.ts",
29
30
  "list-skills": "bun run scripts/list-skills.ts",
@@ -72,25 +73,35 @@
72
73
  "packageManager": "bun@1.4.0",
73
74
  "author": "Casey Hand <casey@caseyjhand.com> (https://caseyjhand.com)",
74
75
  "engines": {
75
- "bun": ">=1.3.0",
76
+ "bun": ">=1.4.0",
76
77
  "node": ">=24.0.0"
77
78
  },
79
+ "funding": [
80
+ {
81
+ "type": "github",
82
+ "url": "https://github.com/sponsors/cyanheads"
83
+ },
84
+ {
85
+ "type": "buy_me_a_coffee",
86
+ "url": "https://www.buymeacoffee.com/cyanheads"
87
+ }
88
+ ],
78
89
  "publishConfig": {
79
90
  "access": "public"
80
91
  },
81
92
  "dependencies": {
82
- "@cyanheads/mcp-ts-core": "^0.12.3",
93
+ "@cyanheads/mcp-ts-core": "^0.13.6",
83
94
  "pino-pretty": "^13.1.3",
84
- "zod": "^4.4.3"
95
+ "zod": "^4.6.5"
85
96
  },
86
97
  "devDependencies": {
87
- "@biomejs/biome": "2.5.11",
98
+ "@biomejs/biome": "2.5.14",
88
99
  "@socketsecurity/bun-security-scanner": "^1.1.2",
89
- "@types/node": "26.4.0",
100
+ "@types/node": "26.6.1",
90
101
  "depcheck": "^1.4.7",
91
- "ignore": "^7.0.6",
92
- "tsc-alias": "^1.9.2",
102
+ "ignore": "^7.0.9",
103
+ "tsc-alias": "^1.9.5",
93
104
  "typescript": "^7.0.2",
94
- "vitest": "^4.1.11"
105
+ "vitest": "^5.0.1"
95
106
  }
96
107
  }
package/server.json CHANGED
@@ -6,14 +6,14 @@
6
6
  "url": "https://github.com/cyanheads/finnhub-mcp-server",
7
7
  "source": "github"
8
8
  },
9
- "version": "0.1.4",
9
+ "version": "0.1.5",
10
10
  "packages": [
11
11
  {
12
12
  "registryType": "npm",
13
13
  "registryBaseUrl": "https://registry.npmjs.org",
14
14
  "identifier": "@cyanheads/finnhub-mcp-server",
15
15
  "runtimeHint": "node",
16
- "version": "0.1.4",
16
+ "version": "0.1.5",
17
17
  "packageArguments": [
18
18
  {
19
19
  "type": "positional",
@@ -55,7 +55,7 @@
55
55
  "registryBaseUrl": "https://registry.npmjs.org",
56
56
  "identifier": "@cyanheads/finnhub-mcp-server",
57
57
  "runtimeHint": "node",
58
- "version": "0.1.4",
58
+ "version": "0.1.5",
59
59
  "packageArguments": [
60
60
  {
61
61
  "type": "positional",