@cyanheads/finnhub-mcp-server 0.1.4 → 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 +54 -26
- package/CLAUDE.md +54 -26
- package/Dockerfile +91 -41
- package/README.md +43 -56
- package/changelog/0.1.x/0.1.5.md +26 -0
- package/changelog/0.1.x/0.1.6.md +26 -0
- package/changelog/template.md +9 -26
- package/dist/index.js +7 -0
- package/dist/index.js.map +1 -1
- package/dist/services/finnhub/finnhub-service.d.ts +1 -1
- package/dist/services/finnhub/finnhub-service.js +1 -1
- package/package.json +23 -11
- package/server.json +10 -24
package/AGENTS.md
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
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.
|
|
6
|
-
**Engines:** Bun ≥1.
|
|
7
|
-
**MCP SDK:** `@modelcontextprotocol/server` 2.
|
|
8
|
-
**Zod:** ^4.
|
|
4
|
+
**Version:** 0.1.6
|
|
5
|
+
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.13`
|
|
6
|
+
**Engines:** Bun ≥1.4.0, Node ≥24.0.0
|
|
7
|
+
**MCP SDK:** `@modelcontextprotocol/server` 2.2.0
|
|
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
|
---
|
|
@@ -34,7 +35,7 @@ export const searchItems = tool('search_items', {
|
|
|
34
35
|
annotations: { readOnlyHint: true },
|
|
35
36
|
input: z.object({
|
|
36
37
|
query: z.string().describe('Search terms'),
|
|
37
|
-
limit: z.number().default(10).describe('Max results'),
|
|
38
|
+
limit: z.number().int().min(1).max(100).default(10).describe('Max results (1–100)'),
|
|
38
39
|
}),
|
|
39
40
|
output: z.object({
|
|
40
41
|
items: z.array(z.object({
|
|
@@ -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
|
|
@@ -150,13 +167,14 @@ Handlers receive a unified `ctx` object. Key properties:
|
|
|
150
167
|
| Property | Description |
|
|
151
168
|
|:---------|:------------|
|
|
152
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. |
|
|
153
|
-
| `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). |
|
|
154
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. |
|
|
155
|
-
| `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. |
|
|
156
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). |
|
|
157
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`. |
|
|
158
176
|
| `ctx.signal` | `AbortSignal` for cancellation. |
|
|
159
|
-
| `ctx.requestId` |
|
|
177
|
+
| `ctx.requestId` | Request ID — the one every log record of the call carries and its error envelope returns as `data.requestId`. |
|
|
160
178
|
| `ctx.tenantId` | Tenant ID from JWT; `'default'` for stdio or HTTP with auth off. |
|
|
161
179
|
|
|
162
180
|
---
|
|
@@ -165,7 +183,7 @@ Handlers receive a unified `ctx` object. Key properties:
|
|
|
165
183
|
|
|
166
184
|
Handlers throw — the framework catches, classifies, and formats.
|
|
167
185
|
|
|
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.
|
|
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.
|
|
169
187
|
|
|
170
188
|
```ts
|
|
171
189
|
import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
|
|
@@ -177,7 +195,7 @@ errors: [
|
|
|
177
195
|
],
|
|
178
196
|
async handler(input, ctx) {
|
|
179
197
|
const item = await db.find(input.id);
|
|
180
|
-
if (!item) throw ctx.fail('no_match', `No item ${input.id}
|
|
198
|
+
if (!item) throw ctx.fail('no_match', `No item ${input.id}`);
|
|
181
199
|
return item;
|
|
182
200
|
}
|
|
183
201
|
```
|
|
@@ -198,7 +216,7 @@ throw new Error('Invalid query format'); // → ValidationError
|
|
|
198
216
|
|
|
199
217
|
// McpError — when no factory exists for the code
|
|
200
218
|
import { McpError, JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
|
|
201
|
-
throw new McpError(JsonRpcErrorCode.
|
|
219
|
+
throw new McpError(JsonRpcErrorCode.InitializationFailed, 'Connection failed', { pool: 'primary' });
|
|
202
220
|
```
|
|
203
221
|
|
|
204
222
|
See framework CLAUDE.md and the `api-errors` skill for the full auto-classification table, all available factories, and the contract reference.
|
|
@@ -240,9 +258,9 @@ src/
|
|
|
240
258
|
|
|
241
259
|
## Skills
|
|
242
260
|
|
|
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.
|
|
261
|
+
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
262
|
|
|
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.
|
|
263
|
+
**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
264
|
|
|
247
265
|
Available skills:
|
|
248
266
|
|
|
@@ -261,12 +279,14 @@ Available skills:
|
|
|
261
279
|
| `security-pass` | Audit server for MCP-flavored security gaps: output injection, scope blast radius, input sinks, tenant isolation |
|
|
262
280
|
| `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase |
|
|
263
281
|
| `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
|
|
264
|
-
| `git-wrapup` | Land working-tree changes as a
|
|
265
|
-
| `release-
|
|
282
|
+
| `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 |
|
|
283
|
+
| `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 |
|
|
284
|
+
| `release-and-publish` | Fast-forward merge (release PR mode) + tag + push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
|
|
266
285
|
| `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
|
|
267
286
|
| `orchestrations` | Chain task skills into a gated multi-phase pipeline — build-out, QA-fix, update-ship — when you can spawn sub-agents |
|
|
268
287
|
| `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
|
|
269
288
|
| `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
|
|
289
|
+
| `techniques` | Catalog of response/data-shaping techniques — overflow handling, payload shaping, retrieval patterns |
|
|
270
290
|
| `api-auth` | Auth modes, scopes, JWT/OAuth |
|
|
271
291
|
| `api-canvas` | DataCanvas: register tabular data, run SQL, export, plus the `spillover()` helper for big result sets — Tier 3 opt-in |
|
|
272
292
|
| `api-config` | AppConfig, parseConfig, env vars |
|
|
@@ -279,9 +299,8 @@ Available skills:
|
|
|
279
299
|
| `api-utils` | Formatting, parsing, security, pagination, scheduling, telemetry helpers |
|
|
280
300
|
| `api-telemetry` | OTel catalog: spans, metrics, completion logs, env config, cardinality rules |
|
|
281
301
|
| `api-workers` | Cloudflare Workers runtime |
|
|
282
|
-
| `techniques` | Catalog of response/data-shaping techniques — overflow handling, payload shaping, retrieval patterns |
|
|
283
302
|
|
|
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.
|
|
303
|
+
**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
304
|
|
|
286
305
|
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
306
|
|
|
@@ -300,7 +319,8 @@ When you complete a skill's checklist, check the boxes and add a completion time
|
|
|
300
319
|
| `bun run lint:mcp` | Run the MCP definition linter standalone (rule catalog: `api-linter` skill) |
|
|
301
320
|
| `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity (run by devcheck) |
|
|
302
321
|
| `bun run list-skills` | Print the skill registry |
|
|
303
|
-
| `bun run audit:
|
|
322
|
+
| `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` |
|
|
323
|
+
| `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
324
|
| `bun run tree` | Generate directory structure doc |
|
|
305
325
|
| `bun run format` | Auto-fix formatting (safe fixes only) |
|
|
306
326
|
| `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
|
|
@@ -311,15 +331,17 @@ When you complete a skill's checklist, check the boxes and add a completion time
|
|
|
311
331
|
| `bun run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
|
|
312
332
|
| `bun run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install |
|
|
313
333
|
|
|
334
|
+
**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.
|
|
335
|
+
|
|
314
336
|
---
|
|
315
337
|
|
|
316
338
|
## Bundling
|
|
317
339
|
|
|
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.
|
|
340
|
+
`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
341
|
|
|
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.
|
|
342
|
+
**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
343
|
|
|
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`.
|
|
344
|
+
**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
345
|
|
|
324
346
|
---
|
|
325
347
|
|
|
@@ -344,12 +366,18 @@ security: false # optional — true ONLY for a source
|
|
|
344
366
|
|
|
345
367
|
`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
368
|
|
|
347
|
-
**Section order
|
|
369
|
+
**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
370
|
|
|
349
371
|
**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
372
|
|
|
351
373
|
---
|
|
352
374
|
|
|
375
|
+
## Publishing
|
|
376
|
+
|
|
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.
|
|
378
|
+
|
|
379
|
+
---
|
|
380
|
+
|
|
353
381
|
## Imports
|
|
354
382
|
|
|
355
383
|
```ts
|
|
@@ -376,7 +404,7 @@ import { getMyService } from '@/services/my-domain/my-service.js';
|
|
|
376
404
|
- [ ] If wrapping external API: tests include at least one sparse payload case with omitted upstream fields
|
|
377
405
|
- [ ] Registered in `createApp()` arrays (directly or via barrel exports)
|
|
378
406
|
- [ ] 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` =
|
|
380
|
-
- [ ] `.codex-plugin/mcp.json` updated — server name key
|
|
381
|
-
- [ ] `.claude-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; inline `mcpServers` entry
|
|
407
|
+
- [ ] `.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
|
|
408
|
+
- [ ] `.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
|
|
409
|
+
- [ ] `.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
410
|
- [ ] `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.
|
|
5
|
-
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.
|
|
6
|
-
**Engines:** Bun ≥1.
|
|
7
|
-
**MCP SDK:** `@modelcontextprotocol/server` 2.
|
|
8
|
-
**Zod:** ^4.
|
|
4
|
+
**Version:** 0.1.6
|
|
5
|
+
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.13`
|
|
6
|
+
**Engines:** Bun ≥1.4.0, Node ≥24.0.0
|
|
7
|
+
**MCP SDK:** `@modelcontextprotocol/server` 2.2.0
|
|
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
|
---
|
|
@@ -34,7 +35,7 @@ export const searchItems = tool('search_items', {
|
|
|
34
35
|
annotations: { readOnlyHint: true },
|
|
35
36
|
input: z.object({
|
|
36
37
|
query: z.string().describe('Search terms'),
|
|
37
|
-
limit: z.number().default(10).describe('Max results'),
|
|
38
|
+
limit: z.number().int().min(1).max(100).default(10).describe('Max results (1–100)'),
|
|
38
39
|
}),
|
|
39
40
|
output: z.object({
|
|
40
41
|
items: z.array(z.object({
|
|
@@ -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
|
|
@@ -150,13 +167,14 @@ Handlers receive a unified `ctx` object. Key properties:
|
|
|
150
167
|
| Property | Description |
|
|
151
168
|
|:---------|:------------|
|
|
152
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. |
|
|
153
|
-
| `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). |
|
|
154
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. |
|
|
155
|
-
| `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. |
|
|
156
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). |
|
|
157
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`. |
|
|
158
176
|
| `ctx.signal` | `AbortSignal` for cancellation. |
|
|
159
|
-
| `ctx.requestId` |
|
|
177
|
+
| `ctx.requestId` | Request ID — the one every log record of the call carries and its error envelope returns as `data.requestId`. |
|
|
160
178
|
| `ctx.tenantId` | Tenant ID from JWT; `'default'` for stdio or HTTP with auth off. |
|
|
161
179
|
|
|
162
180
|
---
|
|
@@ -165,7 +183,7 @@ Handlers receive a unified `ctx` object. Key properties:
|
|
|
165
183
|
|
|
166
184
|
Handlers throw — the framework catches, classifies, and formats.
|
|
167
185
|
|
|
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.
|
|
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.
|
|
169
187
|
|
|
170
188
|
```ts
|
|
171
189
|
import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
|
|
@@ -177,7 +195,7 @@ errors: [
|
|
|
177
195
|
],
|
|
178
196
|
async handler(input, ctx) {
|
|
179
197
|
const item = await db.find(input.id);
|
|
180
|
-
if (!item) throw ctx.fail('no_match', `No item ${input.id}
|
|
198
|
+
if (!item) throw ctx.fail('no_match', `No item ${input.id}`);
|
|
181
199
|
return item;
|
|
182
200
|
}
|
|
183
201
|
```
|
|
@@ -198,7 +216,7 @@ throw new Error('Invalid query format'); // → ValidationError
|
|
|
198
216
|
|
|
199
217
|
// McpError — when no factory exists for the code
|
|
200
218
|
import { McpError, JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
|
|
201
|
-
throw new McpError(JsonRpcErrorCode.
|
|
219
|
+
throw new McpError(JsonRpcErrorCode.InitializationFailed, 'Connection failed', { pool: 'primary' });
|
|
202
220
|
```
|
|
203
221
|
|
|
204
222
|
See framework CLAUDE.md and the `api-errors` skill for the full auto-classification table, all available factories, and the contract reference.
|
|
@@ -240,9 +258,9 @@ src/
|
|
|
240
258
|
|
|
241
259
|
## Skills
|
|
242
260
|
|
|
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.
|
|
261
|
+
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
262
|
|
|
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.
|
|
263
|
+
**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
264
|
|
|
247
265
|
Available skills:
|
|
248
266
|
|
|
@@ -261,12 +279,14 @@ Available skills:
|
|
|
261
279
|
| `security-pass` | Audit server for MCP-flavored security gaps: output injection, scope blast radius, input sinks, tenant isolation |
|
|
262
280
|
| `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase |
|
|
263
281
|
| `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
|
|
264
|
-
| `git-wrapup` | Land working-tree changes as a
|
|
265
|
-
| `release-
|
|
282
|
+
| `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 |
|
|
283
|
+
| `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 |
|
|
284
|
+
| `release-and-publish` | Fast-forward merge (release PR mode) + tag + push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
|
|
266
285
|
| `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
|
|
267
286
|
| `orchestrations` | Chain task skills into a gated multi-phase pipeline — build-out, QA-fix, update-ship — when you can spawn sub-agents |
|
|
268
287
|
| `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
|
|
269
288
|
| `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
|
|
289
|
+
| `techniques` | Catalog of response/data-shaping techniques — overflow handling, payload shaping, retrieval patterns |
|
|
270
290
|
| `api-auth` | Auth modes, scopes, JWT/OAuth |
|
|
271
291
|
| `api-canvas` | DataCanvas: register tabular data, run SQL, export, plus the `spillover()` helper for big result sets — Tier 3 opt-in |
|
|
272
292
|
| `api-config` | AppConfig, parseConfig, env vars |
|
|
@@ -279,9 +299,8 @@ Available skills:
|
|
|
279
299
|
| `api-utils` | Formatting, parsing, security, pagination, scheduling, telemetry helpers |
|
|
280
300
|
| `api-telemetry` | OTel catalog: spans, metrics, completion logs, env config, cardinality rules |
|
|
281
301
|
| `api-workers` | Cloudflare Workers runtime |
|
|
282
|
-
| `techniques` | Catalog of response/data-shaping techniques — overflow handling, payload shaping, retrieval patterns |
|
|
283
302
|
|
|
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.
|
|
303
|
+
**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
304
|
|
|
286
305
|
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
306
|
|
|
@@ -300,7 +319,8 @@ When you complete a skill's checklist, check the boxes and add a completion time
|
|
|
300
319
|
| `bun run lint:mcp` | Run the MCP definition linter standalone (rule catalog: `api-linter` skill) |
|
|
301
320
|
| `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity (run by devcheck) |
|
|
302
321
|
| `bun run list-skills` | Print the skill registry |
|
|
303
|
-
| `bun run audit:
|
|
322
|
+
| `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` |
|
|
323
|
+
| `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
324
|
| `bun run tree` | Generate directory structure doc |
|
|
305
325
|
| `bun run format` | Auto-fix formatting (safe fixes only) |
|
|
306
326
|
| `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
|
|
@@ -311,15 +331,17 @@ When you complete a skill's checklist, check the boxes and add a completion time
|
|
|
311
331
|
| `bun run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
|
|
312
332
|
| `bun run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install |
|
|
313
333
|
|
|
334
|
+
**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.
|
|
335
|
+
|
|
314
336
|
---
|
|
315
337
|
|
|
316
338
|
## Bundling
|
|
317
339
|
|
|
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.
|
|
340
|
+
`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
341
|
|
|
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.
|
|
342
|
+
**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
343
|
|
|
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`.
|
|
344
|
+
**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
345
|
|
|
324
346
|
---
|
|
325
347
|
|
|
@@ -344,12 +366,18 @@ security: false # optional — true ONLY for a source
|
|
|
344
366
|
|
|
345
367
|
`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
368
|
|
|
347
|
-
**Section order
|
|
369
|
+
**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
370
|
|
|
349
371
|
**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
372
|
|
|
351
373
|
---
|
|
352
374
|
|
|
375
|
+
## Publishing
|
|
376
|
+
|
|
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.
|
|
378
|
+
|
|
379
|
+
---
|
|
380
|
+
|
|
353
381
|
## Imports
|
|
354
382
|
|
|
355
383
|
```ts
|
|
@@ -376,7 +404,7 @@ import { getMyService } from '@/services/my-domain/my-service.js';
|
|
|
376
404
|
- [ ] If wrapping external API: tests include at least one sparse payload case with omitted upstream fields
|
|
377
405
|
- [ ] Registered in `createApp()` arrays (directly or via barrel exports)
|
|
378
406
|
- [ ] 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` =
|
|
380
|
-
- [ ] `.codex-plugin/mcp.json` updated — server name key
|
|
381
|
-
- [ ] `.claude-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; inline `mcpServers` entry
|
|
407
|
+
- [ ] `.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
|
|
408
|
+
- [ ] `.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
|
|
409
|
+
- [ ] `.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
410
|
- [ ] `npm run devcheck` passes
|
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
|
|
|
@@ -21,9 +21,11 @@
|
|
|
21
21
|
|
|
22
22
|
---
|
|
23
23
|
|
|
24
|
-
##
|
|
24
|
+
## Overview
|
|
25
25
|
|
|
26
|
-
|
|
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,86 +36,68 @@ 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
|
-
###
|
|
38
|
-
|
|
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.
|
|
39
|
+
### Resources
|
|
40
40
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
- `limit` (1–50, default 10); reports the total match count and discloses truncation when more matched than returned
|
|
41
|
+
| Resource | Description |
|
|
42
|
+
|:---|:---|
|
|
43
|
+
| `finnhub://news-categories` | The four valid market-news categories (`general`, `forex`, `crypto`, `merger`) with one-line descriptions. |
|
|
45
44
|
|
|
46
|
-
|
|
45
|
+
Fully covered by the `category` enum on `finnhub_get_news`, so tool-only clients lose nothing.
|
|
47
46
|
|
|
48
|
-
|
|
47
|
+
## Capability reference
|
|
49
48
|
|
|
50
|
-
|
|
49
|
+
### `finnhub_search_symbols` <sub>tool</sub>
|
|
51
50
|
|
|
52
|
-
-
|
|
53
|
-
-
|
|
54
|
-
- Exposes Finnhub's nullable `session` (`pre-market`, `regular`, or `post-market`) and returned holiday event name without inferring either value
|
|
55
|
-
- Market-status failing degrades to `marketOpen: null`, `session: null`, and `holiday: null` rather than tanking the quote
|
|
56
|
-
- Unknown US ticker → `symbol_not_found`; international or paid-only symbol → `not_us_or_paid`
|
|
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.
|
|
57
53
|
|
|
58
54
|
---
|
|
59
55
|
|
|
60
|
-
### `
|
|
56
|
+
### `finnhub_get_quote` <sub>tool</sub>
|
|
61
57
|
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
- Profile: name, exchange, industry, country, currency, market cap, shares outstanding, IPO date, website, logo
|
|
65
|
-
- 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
|
|
66
|
-
- Sector peers from `/stock/peers` (includes the queried symbol)
|
|
67
|
-
- Combines three endpoints under a parallel fan-out; metrics or peers failing degrade to a `partial` list, profile drives the not-found / forbidden errors
|
|
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`.
|
|
68
60
|
|
|
69
61
|
---
|
|
70
62
|
|
|
71
|
-
### `
|
|
72
|
-
|
|
73
|
-
Earnings data for one symbol or across the market, selected by `mode`.
|
|
63
|
+
### `finnhub_get_company` <sub>tool</sub>
|
|
74
64
|
|
|
75
|
-
-
|
|
76
|
-
-
|
|
77
|
-
- `limit` (1–100, default 50); reports total rows and discloses truncation
|
|
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.
|
|
78
67
|
|
|
79
68
|
---
|
|
80
69
|
|
|
81
|
-
### `
|
|
82
|
-
|
|
83
|
-
Financial news for one company or the broad market, selected by `mode`.
|
|
70
|
+
### `finnhub_get_earnings` <sub>tool</sub>
|
|
84
71
|
|
|
85
|
-
- `
|
|
86
|
-
- `
|
|
87
|
-
- `limit` (1–100, default 15 — news lists run long); articles newest first, with total and truncation disclosure
|
|
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`.
|
|
88
74
|
|
|
89
75
|
---
|
|
90
76
|
|
|
91
|
-
### `
|
|
77
|
+
### `finnhub_get_news` <sub>tool</sub>
|
|
92
78
|
|
|
93
|
-
|
|
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`.
|
|
81
|
+
|
|
82
|
+
---
|
|
83
|
+
|
|
84
|
+
### `finnhub_get_recommendations` <sub>tool</sub>
|
|
94
85
|
|
|
95
86
|
- Per-month strong-buy / buy / hold / sell / strong-sell counts, newest first (typically 12–24 months of history)
|
|
96
87
|
- `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
|
|
88
|
+
- Empty result (no analyst coverage) → `no_coverage`, distinct from an invalid symbol; international or paid-only symbol → `not_us_or_paid`
|
|
98
89
|
|
|
99
|
-
|
|
90
|
+
---
|
|
100
91
|
|
|
101
|
-
|
|
102
|
-
|:---|:---|:---|
|
|
103
|
-
| Resource | `finnhub://news-categories` | The four valid market-news categories (`general`, `forex`, `crypto`, `merger`) with one-line descriptions. |
|
|
92
|
+
### `finnhub://news-categories` <sub>resource</sub>
|
|
104
93
|
|
|
105
|
-
|
|
94
|
+
- Returns the four valid `finnhub_get_news` market-mode categories (`general`, `forex`, `crypto`, `merger`) with one-line descriptions, as `application/json`
|
|
95
|
+
- Convenience mirror — fully covered by the `category` enum's `.describe()` on `finnhub_get_news`, so tool-only clients lose nothing
|
|
96
|
+
- Live data (quotes, news, earnings) is intentionally not exposed as a resource — it's time-sensitive, so freshness lives only in the tools
|
|
106
97
|
|
|
107
98
|
## Features
|
|
108
99
|
|
|
109
|
-
Built on [`@cyanheads/mcp-ts-core`](https://
|
|
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
|
|
100
|
+
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
101
|
|
|
118
102
|
Finnhub-specific:
|
|
119
103
|
|
|
@@ -201,7 +185,7 @@ MCP_TRANSPORT_TYPE=http MCP_SESSION_MODE=stateless MCP_HTTP_PORT=3010 FINNHUB_AP
|
|
|
201
185
|
|
|
202
186
|
### Prerequisites
|
|
203
187
|
|
|
204
|
-
- [Bun v1.
|
|
188
|
+
- [Bun v1.4.0](https://bun.sh/) or higher (or Node.js v24+).
|
|
205
189
|
- 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
190
|
|
|
207
191
|
### Installation
|
|
@@ -242,11 +226,14 @@ All configuration is validated at startup via Zod schemas in `src/config/server-
|
|
|
242
226
|
| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |
|
|
243
227
|
| `MCP_HTTP_PORT` | Port for the HTTP server. | `3010` |
|
|
244
228
|
| `MCP_HTTP_ENDPOINT_PATH` | HTTP endpoint path where the MCP server is mounted. | `/mcp` |
|
|
245
|
-
| `MCP_SESSION_MODE` | Session handling: `auto`, `stateful`, or `stateless`.
|
|
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` |
|
|
246
230
|
| `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |
|
|
247
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` |
|
|
248
233
|
| `STORAGE_PROVIDER_TYPE` | Storage backend: `in-memory`, `filesystem`, `supabase`, `cloudflare-kv/r2/d1`. | `in-memory` |
|
|
249
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. | — |
|
|
250
237
|
|
|
251
238
|
See [`.env.example`](./.env.example) for the full list of optional overrides.
|
|
252
239
|
|
|
@@ -305,7 +292,7 @@ See [`CLAUDE.md`](./CLAUDE.md) / [`AGENTS.md`](./AGENTS.md) for development guid
|
|
|
305
292
|
|
|
306
293
|
## Contributing
|
|
307
294
|
|
|
308
|
-
Issues
|
|
295
|
+
Issues are welcome. Run checks and tests before submitting:
|
|
309
296
|
|
|
310
297
|
```sh
|
|
311
298
|
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`
|
|
@@ -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.
|
package/changelog/template.md
CHANGED
|
@@ -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
|
|
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`.
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
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"}
|
|
@@ -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",
|
|
@@ -24,6 +25,7 @@
|
|
|
24
25
|
"rebuild": "bun run scripts/clean.ts && bun run scripts/build.ts",
|
|
25
26
|
"clean": "bun run scripts/clean.ts",
|
|
26
27
|
"devcheck": "bun run scripts/devcheck.ts",
|
|
28
|
+
"audit:fix": "bun audit fix",
|
|
27
29
|
"audit:refresh": "rm -f bun.lock && bun install && bun audit",
|
|
28
30
|
"tree": "bun run scripts/tree.ts",
|
|
29
31
|
"list-skills": "bun run scripts/list-skills.ts",
|
|
@@ -69,28 +71,38 @@
|
|
|
69
71
|
"url": "https://github.com/cyanheads/finnhub-mcp-server/issues"
|
|
70
72
|
},
|
|
71
73
|
"license": "Apache-2.0",
|
|
72
|
-
"packageManager": "bun@1.4.
|
|
74
|
+
"packageManager": "bun@1.4.2",
|
|
73
75
|
"author": "Casey Hand <casey@caseyjhand.com> (https://caseyjhand.com)",
|
|
74
76
|
"engines": {
|
|
75
|
-
"bun": ">=1.
|
|
77
|
+
"bun": ">=1.4.0",
|
|
76
78
|
"node": ">=24.0.0"
|
|
77
79
|
},
|
|
80
|
+
"funding": [
|
|
81
|
+
{
|
|
82
|
+
"type": "github",
|
|
83
|
+
"url": "https://github.com/sponsors/cyanheads"
|
|
84
|
+
},
|
|
85
|
+
{
|
|
86
|
+
"type": "buy_me_a_coffee",
|
|
87
|
+
"url": "https://www.buymeacoffee.com/cyanheads"
|
|
88
|
+
}
|
|
89
|
+
],
|
|
78
90
|
"publishConfig": {
|
|
79
91
|
"access": "public"
|
|
80
92
|
},
|
|
81
93
|
"dependencies": {
|
|
82
|
-
"@cyanheads/mcp-ts-core": "^0.
|
|
94
|
+
"@cyanheads/mcp-ts-core": "^0.13.13",
|
|
83
95
|
"pino-pretty": "^13.1.3",
|
|
84
|
-
"zod": "^4.
|
|
96
|
+
"zod": "^4.6.5"
|
|
85
97
|
},
|
|
86
98
|
"devDependencies": {
|
|
87
|
-
"@biomejs/biome": "2.5.
|
|
88
|
-
"@socketsecurity/bun-security-scanner": "^1.1.
|
|
89
|
-
"@types/node": "26.4
|
|
99
|
+
"@biomejs/biome": "2.5.15",
|
|
100
|
+
"@socketsecurity/bun-security-scanner": "^1.1.3",
|
|
101
|
+
"@types/node": "26.6.4",
|
|
90
102
|
"depcheck": "^1.4.7",
|
|
91
|
-
"ignore": "^7.0.
|
|
92
|
-
"tsc-alias": "^1.9.
|
|
103
|
+
"ignore": "^7.0.12",
|
|
104
|
+
"tsc-alias": "^1.9.7",
|
|
93
105
|
"typescript": "^7.0.2",
|
|
94
|
-
"vitest": "^
|
|
106
|
+
"vitest": "^5.0.3"
|
|
95
107
|
}
|
|
96
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.",
|