@cyanheads/finnhub-mcp-server 0.1.5 → 0.1.6

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,10 +1,10 @@
1
1
  # Developer Protocol
2
2
 
3
3
  **Server:** finnhub-mcp-server
4
- **Version:** 0.1.5
5
- **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.6`
4
+ **Version:** 0.1.6
5
+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.13`
6
6
  **Engines:** Bun ≥1.4.0, Node ≥24.0.0
7
- **MCP SDK:** `@modelcontextprotocol/server` 2.0.0
7
+ **MCP SDK:** `@modelcontextprotocol/server` 2.2.0
8
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.
@@ -35,7 +35,7 @@ export const searchItems = tool('search_items', {
35
35
  annotations: { readOnlyHint: true },
36
36
  input: z.object({
37
37
  query: z.string().describe('Search terms'),
38
- limit: z.number().default(10).describe('Max results'),
38
+ limit: z.number().int().min(1).max(100).default(10).describe('Max results (1–100)'),
39
39
  }),
40
40
  output: z.object({
41
41
  items: z.array(z.object({
@@ -167,13 +167,14 @@ Handlers receive a unified `ctx` object. Key properties:
167
167
  | Property | Description |
168
168
  |:---------|:------------|
169
169
  | `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. Dual-sink: Pino **and** `notifications/message` to the client, so treat it as client-visible. |
170
- | `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |
170
+ | `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts any JSON-serializable value; reads return its JSON form (a `Date` comes back as an ISO string). |
171
171
  | `ctx.requestInput` | Suspend and ask the caller for more input — `return ctx.requestInput({ inputRequests: { key: inputRequired.elicit({ message, requestedSchema }) } })`. Never returns; the handler is re-entered with the answers. Always present. |
172
- | `ctx.inputs` | Reader over a retried request's responses — `.accepted(key, schema)`, `.view(key)`, `.state()`, `.dropped`. Empty on the first round. |
172
+ | `ctx.inputs` | The request's responses — `.accepted(key, schema)`, `.view(key)`, `.state()`, `.dropped` — limited to what the client declared (`elicitation` and its form/url modes, `sampling`, `roots`). Client-supplied: a consent gate trusts only a `ctx.state` record it stored when it asked, bound to the operation, caller, and target (see the `api-context` skill). |
173
+ | `ctx.clientCapabilities` | What the client declared for this request, `undefined` when no view exists. Decides whether to ask for optional context (e.g. roots); never a reason to skip a consent prompt. |
173
174
  | `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). |
174
175
  | `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`. |
175
176
  | `ctx.signal` | `AbortSignal` for cancellation. |
176
- | `ctx.requestId` | Unique request ID. |
177
+ | `ctx.requestId` | Request ID — the one every log record of the call carries and its error envelope returns as `data.requestId`. |
177
178
  | `ctx.tenantId` | Tenant ID from JWT; `'default'` for stdio or HTTP with auth off. |
178
179
 
179
180
  ---
@@ -182,7 +183,7 @@ Handlers receive a unified `ctx` object. Key properties:
182
183
 
183
184
  Handlers throw — the framework catches, classifies, and formats.
184
185
 
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.
186
+ **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. The framework puts it on the wire whenever a failure carrying that `reason` arrives without a hint — a bare `ctx.fail('reason')` or a service throw with `data: { reason }` — as `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. Every error envelope also carries `data.requestId`, the id the server's log records for that call carry, and `content[]` closes with `(reason … · request <id>)`. 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.
186
187
 
187
188
  ```ts
188
189
  import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
@@ -194,7 +195,7 @@ errors: [
194
195
  ],
195
196
  async handler(input, ctx) {
196
197
  const item = await db.find(input.id);
197
- if (!item) throw ctx.fail('no_match', `No item ${input.id}`, ctx.recoveryFor('no_match'));
198
+ if (!item) throw ctx.fail('no_match', `No item ${input.id}`);
198
199
  return item;
199
200
  }
200
201
  ```
@@ -373,7 +374,7 @@ security: false # optional — true ONLY for a source
373
374
 
374
375
  ## Publishing
375
376
 
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
+ **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 release digest: theme line, `## Changes`, `## Gates`, changelog link last); `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
 
378
379
  ---
379
380
 
package/CLAUDE.md CHANGED
@@ -1,10 +1,10 @@
1
1
  # Developer Protocol
2
2
 
3
3
  **Server:** finnhub-mcp-server
4
- **Version:** 0.1.5
5
- **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.6`
4
+ **Version:** 0.1.6
5
+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.13`
6
6
  **Engines:** Bun ≥1.4.0, Node ≥24.0.0
7
- **MCP SDK:** `@modelcontextprotocol/server` 2.0.0
7
+ **MCP SDK:** `@modelcontextprotocol/server` 2.2.0
8
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.
@@ -35,7 +35,7 @@ export const searchItems = tool('search_items', {
35
35
  annotations: { readOnlyHint: true },
36
36
  input: z.object({
37
37
  query: z.string().describe('Search terms'),
38
- limit: z.number().default(10).describe('Max results'),
38
+ limit: z.number().int().min(1).max(100).default(10).describe('Max results (1–100)'),
39
39
  }),
40
40
  output: z.object({
41
41
  items: z.array(z.object({
@@ -167,13 +167,14 @@ Handlers receive a unified `ctx` object. Key properties:
167
167
  | Property | Description |
168
168
  |:---------|:------------|
169
169
  | `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. Dual-sink: Pino **and** `notifications/message` to the client, so treat it as client-visible. |
170
- | `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |
170
+ | `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts any JSON-serializable value; reads return its JSON form (a `Date` comes back as an ISO string). |
171
171
  | `ctx.requestInput` | Suspend and ask the caller for more input — `return ctx.requestInput({ inputRequests: { key: inputRequired.elicit({ message, requestedSchema }) } })`. Never returns; the handler is re-entered with the answers. Always present. |
172
- | `ctx.inputs` | Reader over a retried request's responses — `.accepted(key, schema)`, `.view(key)`, `.state()`, `.dropped`. Empty on the first round. |
172
+ | `ctx.inputs` | The request's responses — `.accepted(key, schema)`, `.view(key)`, `.state()`, `.dropped` — limited to what the client declared (`elicitation` and its form/url modes, `sampling`, `roots`). Client-supplied: a consent gate trusts only a `ctx.state` record it stored when it asked, bound to the operation, caller, and target (see the `api-context` skill). |
173
+ | `ctx.clientCapabilities` | What the client declared for this request, `undefined` when no view exists. Decides whether to ask for optional context (e.g. roots); never a reason to skip a consent prompt. |
173
174
  | `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). |
174
175
  | `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`. |
175
176
  | `ctx.signal` | `AbortSignal` for cancellation. |
176
- | `ctx.requestId` | Unique request ID. |
177
+ | `ctx.requestId` | Request ID — the one every log record of the call carries and its error envelope returns as `data.requestId`. |
177
178
  | `ctx.tenantId` | Tenant ID from JWT; `'default'` for stdio or HTTP with auth off. |
178
179
 
179
180
  ---
@@ -182,7 +183,7 @@ Handlers receive a unified `ctx` object. Key properties:
182
183
 
183
184
  Handlers throw — the framework catches, classifies, and formats.
184
185
 
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.
186
+ **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. The framework puts it on the wire whenever a failure carrying that `reason` arrives without a hint — a bare `ctx.fail('reason')` or a service throw with `data: { reason }` — as `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. Every error envelope also carries `data.requestId`, the id the server's log records for that call carry, and `content[]` closes with `(reason … · request <id>)`. 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.
186
187
 
187
188
  ```ts
188
189
  import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
@@ -194,7 +195,7 @@ errors: [
194
195
  ],
195
196
  async handler(input, ctx) {
196
197
  const item = await db.find(input.id);
197
- if (!item) throw ctx.fail('no_match', `No item ${input.id}`, ctx.recoveryFor('no_match'));
198
+ if (!item) throw ctx.fail('no_match', `No item ${input.id}`);
198
199
  return item;
199
200
  }
200
201
  ```
@@ -373,7 +374,7 @@ security: false # optional — true ONLY for a source
373
374
 
374
375
  ## Publishing
375
376
 
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
+ **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 release digest: theme line, `## Changes`, `## Gates`, changelog link last); `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
 
378
379
  ---
379
380
 
package/Dockerfile CHANGED
@@ -4,12 +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
- # --platform=$BUILDPLATFORM runs the build natively on the host arch: the output
8
- # is platform-independent JS (only dist/ copies forward), so a multi-arch
9
- # buildx push must not emulate this stage — Bun under QEMU aborts with
10
- # JSC MemoryExhaustion.
7
+ # Pinned to $BUILDPLATFORM rather than the target platform: `bun run build` emits
8
+ # JavaScript, and only `dist/` crosses into the production stage. Built for the
9
+ # target instead, the non-native leg of a `--platform linux/amd64,linux/arm64`
10
+ # build runs under QEMU, where bun >= 1.4 aborts with a JavaScriptCore allocator
11
+ # assertion and fails the multi-arch push.
12
+ #
13
+ # The constraint this assumes: the build stage produces platform-independent
14
+ # output. A stage that compiles a native addon needs the target-arch toolchain
15
+ # and cannot cross-compile this way — drop the flag there.
11
16
  # ==============================================================================
12
- FROM --platform=$BUILDPLATFORM oven/bun:1.4.0 AS build
17
+ FROM --platform=$BUILDPLATFORM oven/bun:1.4.2 AS build
13
18
 
14
19
  WORKDIR /usr/src/app
15
20
 
@@ -18,7 +23,6 @@ COPY package.json bun.lock ./
18
23
 
19
24
  # Install all dependencies (including dev dependencies for building).
20
25
  # The BuildKit cache mount persists Bun's global package cache across builds.
21
- # --ignore-scripts skips native postinstalls the tsc-only build never needs.
22
26
  RUN --mount=type=cache,target=/root/.bun/install/cache \
23
27
  bun install --frozen-lockfile --ignore-scripts
24
28
 
@@ -30,59 +34,106 @@ RUN bun run build
30
34
 
31
35
 
32
36
  # ==============================================================================
33
- # Production Stage
37
+ # Production Dependencies Stage
34
38
  #
35
- # This stage creates a minimal, optimized, and secure image for running the
36
- # application. It uses a slim base image and only includes production
37
- # dependencies and build artifacts.
39
+ # Installs the production dependency tree for the target platform. Every step
40
+ # here can run JavaScript — bunfig.toml's security scanner runs as a Bun
41
+ # program, and so do the OTel and musl-prune scripts — so the stage runs on
42
+ # $BUILDPLATFORM and cross-installs with `--os`/`--cpu`, which pick each
43
+ # platform-specific optional dependency (native bindings such as DuckDB's) for
44
+ # the target. Only `node_modules` leaves this stage.
45
+ #
46
+ # A clean image rather than `FROM build`: the build stage's node_modules holds
47
+ # devDependencies.
38
48
  # ==============================================================================
39
- FROM oven/bun:1.4.0-slim AS production
49
+ FROM --platform=$BUILDPLATFORM oven/bun:1.4.2 AS deps
40
50
 
41
51
  WORKDIR /usr/src/app
42
52
 
43
- # Set the environment to production for performance and to ensure only
44
- # production dependencies are installed.
45
- ENV NODE_ENV=production
46
-
47
- # OCI image metadata (https://github.com/opencontainers/image-spec/blob/main/annotations.md)
48
- ARG APP_VERSION
49
- LABEL org.opencontainers.image.title="finnhub-mcp-server"
50
- LABEL org.opencontainers.image.description="Real-time US-equity quotes, company fundamentals, earnings, analyst trends, and news via Finnhub."
51
- LABEL org.opencontainers.image.licenses="Apache-2.0"
52
- LABEL org.opencontainers.image.version="${APP_VERSION}"
53
- LABEL org.opencontainers.image.source="https://github.com/cyanheads/finnhub-mcp-server"
54
-
55
- # Copy dependency manifests
56
- COPY package.json bun.lock ./
53
+ # Copy dependency manifests. `bunfig.toml` rides along so every install below
54
+ # passes its release-age gate and security scanner, as a local install does.
55
+ COPY package.json bun.lock bunfig.toml ./
56
+
57
+ # The scanner bunfig.toml names is a devDependency, and Bun installs a missing
58
+ # scanner through the same production-filtered install, which omits it and
59
+ # aborts. Seed it from the build stage's full install instead. Remove this line,
60
+ # and the `rm` at the end of this stage, if bunfig.toml stops naming a scanner.
61
+ COPY --from=build /usr/src/app/node_modules/@socketsecurity/bun-security-scanner ./node_modules/@socketsecurity/bun-security-scanner
62
+
63
+ # Docker names the target architecture `amd64`/`arm64`; Bun's `--cpu` takes
64
+ # `x64`/`arm64`. Mapped once here, read by both installs below. `oven/bun`
65
+ # publishes only these two architectures, so any other target fails here.
66
+ ARG TARGETOS
67
+ ARG TARGETARCH
68
+ RUN case "$TARGETARCH" in \
69
+ amd64) echo x64 ;; \
70
+ arm64) echo arm64 ;; \
71
+ *) echo "Unsupported TARGETARCH '$TARGETARCH': expected amd64 or arm64" >&2; exit 1 ;; \
72
+ esac > .bun-cpu
57
73
 
58
74
  # Install only production dependencies, ignoring any lifecycle scripts (like 'prepare')
59
75
  # that are not needed in the final production image.
60
76
  # `--omit=peer` drops the framework's optional peer tiers (test runner, service
61
77
  # SDKs, parsers) that Bun would otherwise auto-install. Anything this server
62
78
  # actually imports belongs in its own `dependencies`, so nothing needed at
63
- # runtime is lost. The OTEL step below carries the same flag — without it, that
64
- # install re-resolves the graph and pulls every optional peer back in.
79
+ # runtime is lost.
65
80
  RUN --mount=type=cache,target=/root/.bun/install/cache \
66
- bun install --production --omit=peer --frozen-lockfile --ignore-scripts
81
+ bun install --production --omit=peer --frozen-lockfile --ignore-scripts \
82
+ --os="$TARGETOS" --cpu="$(cat .bun-cpu)"
67
83
 
68
84
  # Conditionally install OpenTelemetry optional peer dependencies (Tier 3).
69
- # These are not bundled by default to keep the base image lean. Enable at build time
70
- # with: docker build --build-arg OTEL_ENABLED=true
85
+ # Installed by default. Omit them for a leaner image at build time
86
+ # with: docker build --build-arg OTEL_ENABLED=false
87
+ # The script reads the list and each range from the installed framework's
88
+ # `peerDependencies` and passes the target flags on to its `bun install`.
89
+ COPY scripts/install-otel.ts ./scripts/
71
90
  ARG OTEL_ENABLED=true
72
91
  RUN --mount=type=cache,target=/root/.bun/install/cache \
73
92
  if [ "$OTEL_ENABLED" = "true" ]; then \
74
- bun add --omit=dev --omit=peer --ignore-scripts @hono/otel \
75
- @opentelemetry/instrumentation-http \
76
- @opentelemetry/exporter-metrics-otlp-http \
77
- @opentelemetry/exporter-trace-otlp-http \
78
- @opentelemetry/instrumentation-pino \
79
- @opentelemetry/resources \
80
- @opentelemetry/sdk-metrics \
81
- @opentelemetry/sdk-node \
82
- @opentelemetry/sdk-trace-node \
83
- @opentelemetry/semantic-conventions; \
93
+ bun scripts/install-otel.ts --os="$TARGETOS" --cpu="$(cat .bun-cpu)"; \
84
94
  fi
85
95
 
96
+ # `--os`/`--cpu` have no libc counterpart, so a native dependency published in
97
+ # glibc and musl variants (DuckDB's bindings, for one) installs both. The
98
+ # runtime image is Debian (glibc) and never loads the musl copy; the script
99
+ # deletes every package whose own `libc` admits only musl. It follows every
100
+ # install, since a later `bun install` restores what it removes. A server on a
101
+ # musl (Alpine) runtime image drops these two lines.
102
+ COPY scripts/prune-musl-packages.ts ./scripts/
103
+ RUN bun scripts/prune-musl-packages.ts
104
+
105
+ # The seeded scanner served only the installs above; keep it out of the image.
106
+ RUN rm -rf node_modules/@socketsecurity/bun-security-scanner
107
+
108
+
109
+ # ==============================================================================
110
+ # Production Stage
111
+ #
112
+ # This stage creates a minimal, optimized, and secure image for running the
113
+ # application. It uses a slim base image and only includes production
114
+ # dependencies and build artifacts. Its only Bun invocations are HEALTHCHECK
115
+ # and CMD, which run on the real target at container start.
116
+ # ==============================================================================
117
+ FROM oven/bun:1.4.2-slim AS production
118
+
119
+ WORKDIR /usr/src/app
120
+
121
+ # Set the environment to production for performance.
122
+ ENV NODE_ENV=production
123
+
124
+ # OCI image metadata (https://github.com/opencontainers/image-spec/blob/main/annotations.md)
125
+ ARG APP_VERSION
126
+ LABEL org.opencontainers.image.title="finnhub-mcp-server"
127
+ LABEL org.opencontainers.image.description="Real-time US-equity quotes, company fundamentals, earnings, analyst trends, and news via Finnhub."
128
+ LABEL org.opencontainers.image.licenses="Apache-2.0"
129
+ LABEL org.opencontainers.image.version="${APP_VERSION}"
130
+ LABEL org.opencontainers.image.source="https://github.com/cyanheads/finnhub-mcp-server"
131
+
132
+ # The manifest comes from the build context: the deps stage's copy was rewritten
133
+ # by the OTel install, and the runtime reads only its name, version, and type.
134
+ COPY package.json ./
135
+ COPY --from=deps /usr/src/app/node_modules ./node_modules
136
+
86
137
  # Copy the compiled application code from the build stage
87
138
  COPY --from=build /usr/src/app/dist ./dist
88
139
 
@@ -124,7 +175,6 @@ ENV MCP_TRANSPORT_TYPE="http"
124
175
  ENV MCP_SESSION_MODE="stateless"
125
176
  ENV MCP_LOG_LEVEL="info"
126
177
  ENV LOGS_DIR="/var/log/finnhub-mcp-server"
127
- ENV MCP_FORCE_CONSOLE_LOGGING="true"
128
178
 
129
179
  # Expose the port the server listens on
130
180
  EXPOSE ${MCP_HTTP_PORT}
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.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/)
10
+ [![Version](https://img.shields.io/badge/Version-0.1.6-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.2.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.2-blueviolet.svg?style=flat-square)](https://bun.sh/)
11
11
 
12
12
  </div>
13
13
 
@@ -48,47 +48,36 @@ Fully covered by the `category` enum on `finnhub_get_news`, so tool-only clients
48
48
 
49
49
  ### `finnhub_search_symbols` <sub>tool</sub>
50
50
 
51
- - Full-text match across symbols and descriptions; likely-US Common Stock matches surfaced first
52
- - `query` accepts 1–20 characters; use a shorter company name or ticker fragment when needed
53
- - Each result carries `isLikelyUS`, a symbol-format heuristic: plain tickers and `.A`/`.B` class shares are likely US, while exchange suffixes such as `.SS`, `.T`, and `.L` are not. Quote and profile responses remain authoritative
54
- - `limit` (1–50, default 10); reports the total match count and discloses truncation when more matched than returned
51
+ - Search by company name or ticker fragment with `query` (1–20 characters) and `limit` (1–50, default 10).
52
+ - Returns likely-US Common Stock matches first, with an `isLikelyUS` symbol-format heuristic, total match count, and truncation disclosure. Quote and profile responses remain authoritative.
55
53
 
56
54
  ---
57
55
 
58
56
  ### `finnhub_get_quote` <sub>tool</sub>
59
57
 
60
- - Current price, absolute and percent change, session open/high/low, previous close, and an ISO 8601 quote time
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
62
- - Exposes Finnhub's nullable `session` (`pre-market`, `regular`, or `post-market`) and returned holiday event name without inferring either value
63
- - Market-status failing degrades to `marketOpen: null`, `session: null`, and `holiday: null` rather than tanking the quote
64
- - Unknown US ticker → `symbol_not_found`; international or paid-only symbol → `not_us_or_paid`
58
+ - Requires `symbol`; returns current price, change, session open/high/low, previous close, and an ISO 8601 quote time.
59
+ - `priceIsLive` distinguishes a live price from the prior close; `marketOpen`, `session`, and `holiday` are nullable when market status is unavailable. Unknown ticker → `symbol_not_found`; international or paid-only symbol → `not_us_or_paid`.
65
60
 
66
61
  ---
67
62
 
68
63
  ### `finnhub_get_company` <sub>tool</sub>
69
64
 
70
- - Profile: name, exchange, industry, country, currency, market cap, shares outstanding, IPO date, website, logo
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
72
- - Sector peers from `/stock/peers` (includes the queried symbol)
73
- - Combines three endpoints under a parallel fan-out; metrics or peers failing degrade to a `partial` list, profile drives the not-found / forbidden errors
65
+ - Requires `symbol`; returns company profile, nullable headline fundamentals (P/E, EPS, 52-week range, beta, dividend yield, margins, growth, ROE), and sector peers.
66
+ - Failed metrics or peers appear in `partial`; the profile determines `symbol_not_found` and `not_us_or_paid` errors.
74
67
 
75
68
  ---
76
69
 
77
70
  ### `finnhub_get_earnings` <sub>tool</sub>
78
71
 
79
- - `history` (requires `symbol`): past quarters — actual vs. estimate EPS, absolute surprise, and surprise % (the market-moving signal), newest first
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
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`
72
+ - `history` requires `symbol` and returns past quarters' actual/estimate EPS and surprise, newest first. `calendar` accepts `from` / `to` (default today through +14 days) and an optional `symbol`, returning release dates, EPS/revenue estimates, and report times.
73
+ - `limit` (1–100, default 50) caps rows with total and truncation disclosure. History without a symbol → `missing_symbol`; international or paid-only symbol → `not_us_or_paid`.
83
74
 
84
75
  ---
85
76
 
86
77
  ### `finnhub_get_news` <sub>tool</sub>
87
78
 
88
- - `company` (requires `symbol`): recent articles over a date range (defaults to the last 7 days) — headline, source, ISO 8601 datetime, summary, URL
89
- - `market` (uses `category`): broad headlines by `general`, `forex`, `crypto`, or `merger` (see the `finnhub://news-categories` resource)
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`
79
+ - `company` requires `symbol` and accepts a date range (default last 7 days). `market` uses `category`: `general`, `forex`, `crypto`, or `merger` (see `finnhub://news-categories`).
80
+ - Returns headline, source, ISO 8601 datetime, summary, and URL, newest first. `limit` (1–100, default 15) caps articles with total and truncation disclosure; company mode without a symbol → `missing_symbol`, international or paid-only symbol → `not_us_or_paid`.
92
81
 
93
82
  ---
94
83
 
@@ -240,8 +229,11 @@ All configuration is validated at startup via Zod schemas in `src/config/server-
240
229
  | `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` |
241
230
  | `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |
242
231
  | `MCP_LOG_LEVEL` | Log level (RFC 5424: `debug`, `info`, `notice`, `warning`, `error`). | `info` |
232
+ | `LOG_TOOL_FAILURE_PAYLOADS` | Log failed tool calls' arguments and results, redacted by key name and capped at `LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES` (default `16384`). Secrets inside free-form values are not redacted. | `false` |
243
233
  | `STORAGE_PROVIDER_TYPE` | Storage backend: `in-memory`, `filesystem`, `supabase`, `cloudflare-kv/r2/d1`. | `in-memory` |
244
234
  | `OTEL_ENABLED` | Enable [OpenTelemetry instrumentation](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry) (spans, metrics, completion logs). | `false` |
235
+ | `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP base URL for traces (`/v1/traces`) and metrics (`/v1/metrics`); signal-specific endpoints override it. | — |
236
+ | `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | Opt-in OTLP log endpoint, used as-is. The base URL does not enable log export. | — |
245
237
 
246
238
  See [`.env.example`](./.env.example) for the full list of optional overrides.
247
239
 
@@ -0,0 +1,26 @@
1
+ ---
2
+ summary: "Refresh framework error handling and logging, native Docker builds, bundle exclusions, and MCP Registry launch metadata."
3
+ breaking: false
4
+ security: false
5
+ ---
6
+
7
+ # 0.1.6 — 2026-10-07
8
+
9
+ ## Changed
10
+
11
+ - **Framework error handling** — clearer field-path argument hints and safe input repairs (0.13.9), automatic declared recovery hints and tool error request IDs (0.13.10), generated correlation IDs and origin-only URL redaction (0.13.12), and internal root causes kept off wire errors (0.13.13).
12
+ - **Framework logging** — client log messages honor the configured level and redact sensitive fields (0.13.11); every sink uses a bounded redacting walk (0.13.13). Document opt-in OTLP log export and failed-call payload logging introduced in 0.13.8.
13
+ - **Docker builds** — Bun 1.4.2 builds and cross-installs production dependencies on the native build platform, installs OTel peers at framework ranges through the supply-chain guards, and prunes musl-only packages before copying into the runtime image.
14
+ - **Bundles and metadata** — exclude built `.mcpb` files from npm packages and local caches, logs, and design notes from bundles; broaden env/token exclusions. MCP Registry entries launch through `npx`, with HTTP transport fixed through `MCP_TRANSPORT_TYPE`.
15
+ - **Development tooling and docs** — sync framework skills and verification scripts, including definition-load failures, packaging and tag checks; refresh per-language CodeQL categories, configuration examples, tool summaries, and directory documentation.
16
+
17
+ ## Dependencies
18
+
19
+ - `@cyanheads/mcp-ts-core` ^0.13.6 → ^0.13.13.
20
+ - Dev: `@biomejs/biome` 2.5.14 → 2.5.15.
21
+ - Dev: `@socketsecurity/bun-security-scanner` ^1.1.2 → ^1.1.3.
22
+ - Dev: `@types/node` 26.6.1 → 26.6.4.
23
+ - Dev: `ignore` ^7.0.9 → ^7.0.12.
24
+ - Dev: `tsc-alias` ^1.9.5 → ^1.9.7.
25
+ - Dev: `vitest` ^5.0.1 → ^5.0.3.
26
+ - Bun tooling and Docker images: 1.4.0 → 1.4.2.
@@ -47,7 +47,7 @@ export declare class FinnhubService {
47
47
  * retry while deterministic failures (401/403) fail fast.
48
48
  *
49
49
  * `fetchWithTimeout` throws a classified `McpError` on any non-OK status and
50
- * reduces URLs in errors/logs to origin + pathname, so the `token` query
50
+ * reduces URLs in errors/logs to their origin, so the `token` query
51
51
  * param never reaches a client or a log line. Its default status mapping
52
52
  * matches the design for 403 (→ `Forbidden`), 429 (→ `RateLimited`), and 5xx
53
53
  * (→ `ServiceUnavailable`); only 401 is re-keyed below from `Unauthorized` to
@@ -80,7 +80,7 @@ export class FinnhubService {
80
80
  * retry while deterministic failures (401/403) fail fast.
81
81
  *
82
82
  * `fetchWithTimeout` throws a classified `McpError` on any non-OK status and
83
- * reduces URLs in errors/logs to origin + pathname, so the `token` query
83
+ * reduces URLs in errors/logs to their origin, so the `token` query
84
84
  * param never reaches a client or a log line. Its default status mapping
85
85
  * matches the design for 403 (→ `Forbidden`), 429 (→ `RateLimited`), and 5xx
86
86
  * (→ `ServiceUnavailable`); only 401 is re-keyed below from `Unauthorized` to
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cyanheads/finnhub-mcp-server",
3
- "version": "0.1.5",
3
+ "version": "0.1.6",
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",
@@ -12,6 +12,7 @@
12
12
  "files": [
13
13
  "changelog/",
14
14
  "dist/",
15
+ "!dist/*.mcpb",
15
16
  "README.md",
16
17
  "LICENSE",
17
18
  "CLAUDE.md",
@@ -70,7 +71,7 @@
70
71
  "url": "https://github.com/cyanheads/finnhub-mcp-server/issues"
71
72
  },
72
73
  "license": "Apache-2.0",
73
- "packageManager": "bun@1.4.0",
74
+ "packageManager": "bun@1.4.2",
74
75
  "author": "Casey Hand <casey@caseyjhand.com> (https://caseyjhand.com)",
75
76
  "engines": {
76
77
  "bun": ">=1.4.0",
@@ -90,18 +91,18 @@
90
91
  "access": "public"
91
92
  },
92
93
  "dependencies": {
93
- "@cyanheads/mcp-ts-core": "^0.13.6",
94
+ "@cyanheads/mcp-ts-core": "^0.13.13",
94
95
  "pino-pretty": "^13.1.3",
95
96
  "zod": "^4.6.5"
96
97
  },
97
98
  "devDependencies": {
98
- "@biomejs/biome": "2.5.14",
99
- "@socketsecurity/bun-security-scanner": "^1.1.2",
100
- "@types/node": "26.6.1",
99
+ "@biomejs/biome": "2.5.15",
100
+ "@socketsecurity/bun-security-scanner": "^1.1.3",
101
+ "@types/node": "26.6.4",
101
102
  "depcheck": "^1.4.7",
102
- "ignore": "^7.0.9",
103
- "tsc-alias": "^1.9.5",
103
+ "ignore": "^7.0.12",
104
+ "tsc-alias": "^1.9.7",
104
105
  "typescript": "^7.0.2",
105
- "vitest": "^5.0.1"
106
+ "vitest": "^5.0.3"
106
107
  }
107
108
  }
package/server.json CHANGED
@@ -6,24 +6,14 @@
6
6
  "url": "https://github.com/cyanheads/finnhub-mcp-server",
7
7
  "source": "github"
8
8
  },
9
- "version": "0.1.5",
9
+ "version": "0.1.6",
10
10
  "packages": [
11
11
  {
12
12
  "registryType": "npm",
13
13
  "registryBaseUrl": "https://registry.npmjs.org",
14
14
  "identifier": "@cyanheads/finnhub-mcp-server",
15
- "runtimeHint": "node",
16
- "version": "0.1.5",
17
- "packageArguments": [
18
- {
19
- "type": "positional",
20
- "value": "run"
21
- },
22
- {
23
- "type": "positional",
24
- "value": "start:stdio"
25
- }
26
- ],
15
+ "runtimeHint": "npx",
16
+ "version": "0.1.6",
27
17
  "environmentVariables": [
28
18
  {
29
19
  "name": "FINNHUB_API_KEY",
@@ -54,19 +44,15 @@
54
44
  "registryType": "npm",
55
45
  "registryBaseUrl": "https://registry.npmjs.org",
56
46
  "identifier": "@cyanheads/finnhub-mcp-server",
57
- "runtimeHint": "node",
58
- "version": "0.1.5",
59
- "packageArguments": [
47
+ "runtimeHint": "npx",
48
+ "version": "0.1.6",
49
+ "environmentVariables": [
60
50
  {
61
- "type": "positional",
62
- "value": "run"
51
+ "name": "MCP_TRANSPORT_TYPE",
52
+ "description": "Selects the HTTP transport.",
53
+ "format": "string",
54
+ "value": "http"
63
55
  },
64
- {
65
- "type": "positional",
66
- "value": "start:http"
67
- }
68
- ],
69
- "environmentVariables": [
70
56
  {
71
57
  "name": "FINNHUB_API_KEY",
72
58
  "description": "Required. Free Finnhub API key from https://finnhub.io/register (Dashboard → API key). Free tier: 60 req/min, US real-time.",