@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 +11 -10
- package/CLAUDE.md +11 -10
- package/Dockerfile +91 -41
- package/README.md +14 -22
- package/changelog/0.1.x/0.1.6.md +26 -0
- package/dist/services/finnhub/finnhub-service.d.ts +1 -1
- package/dist/services/finnhub/finnhub-service.js +1 -1
- package/package.json +10 -9
- package/server.json +10 -24
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
|
-
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.
|
|
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.
|
|
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` |
|
|
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` |
|
|
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.
|
|
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}
|
|
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
|
|
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
|
-
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.
|
|
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.
|
|
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` |
|
|
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` |
|
|
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.
|
|
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}
|
|
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
|
|
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
|
-
#
|
|
8
|
-
#
|
|
9
|
-
#
|
|
10
|
-
#
|
|
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.
|
|
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
|
-
#
|
|
36
|
-
#
|
|
37
|
-
#
|
|
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.
|
|
49
|
+
FROM --platform=$BUILDPLATFORM oven/bun:1.4.2 AS deps
|
|
40
50
|
|
|
41
51
|
WORKDIR /usr/src/app
|
|
42
52
|
|
|
43
|
-
#
|
|
44
|
-
#
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
#
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
#
|
|
56
|
-
|
|
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.
|
|
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
|
-
#
|
|
70
|
-
# with: docker build --build-arg OTEL_ENABLED=
|
|
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
|
|
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
|
-
[](./CHANGELOG.md) [](./LICENSE) [](https://github.com/users/cyanheads/packages/container/package/finnhub-mcp-server) [](https://modelcontextprotocol.io/) [](https://www.npmjs.com/package/@cyanheads/finnhub-mcp-server) [](https://www.typescriptlang.org/) [](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
|
-
-
|
|
52
|
-
- `
|
|
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
|
-
-
|
|
61
|
-
-
|
|
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
|
-
-
|
|
71
|
-
-
|
|
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`
|
|
80
|
-
- `
|
|
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`
|
|
89
|
-
- `
|
|
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
|
|
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
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
99
|
-
"@socketsecurity/bun-security-scanner": "^1.1.
|
|
100
|
-
"@types/node": "26.6.
|
|
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.
|
|
103
|
-
"tsc-alias": "^1.9.
|
|
103
|
+
"ignore": "^7.0.12",
|
|
104
|
+
"tsc-alias": "^1.9.7",
|
|
104
105
|
"typescript": "^7.0.2",
|
|
105
|
-
"vitest": "^5.0.
|
|
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.
|
|
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": "
|
|
16
|
-
"version": "0.1.
|
|
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": "
|
|
58
|
-
"version": "0.1.
|
|
59
|
-
"
|
|
47
|
+
"runtimeHint": "npx",
|
|
48
|
+
"version": "0.1.6",
|
|
49
|
+
"environmentVariables": [
|
|
60
50
|
{
|
|
61
|
-
"
|
|
62
|
-
"
|
|
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.",
|