@cyanheads/finnhub-mcp-server 0.1.5 → 0.2.0

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.
Files changed (31) hide show
  1. package/AGENTS.md +25 -14
  2. package/CLAUDE.md +25 -14
  3. package/Dockerfile +95 -41
  4. package/README.md +47 -113
  5. package/changelog/0.1.x/0.1.6.md +26 -0
  6. package/changelog/0.2.x/0.2.0.md +35 -0
  7. package/dist/index.js +2 -1
  8. package/dist/index.js.map +1 -1
  9. package/dist/mcp-server/tools/definitions/get-company.tool.d.ts +1 -1
  10. package/dist/mcp-server/tools/definitions/get-company.tool.d.ts.map +1 -1
  11. package/dist/mcp-server/tools/definitions/get-company.tool.js +5 -3
  12. package/dist/mcp-server/tools/definitions/get-company.tool.js.map +1 -1
  13. package/dist/mcp-server/tools/definitions/get-earnings.tool.d.ts.map +1 -1
  14. package/dist/mcp-server/tools/definitions/get-earnings.tool.js +4 -2
  15. package/dist/mcp-server/tools/definitions/get-earnings.tool.js.map +1 -1
  16. package/dist/mcp-server/tools/definitions/get-news.tool.d.ts.map +1 -1
  17. package/dist/mcp-server/tools/definitions/get-news.tool.js +3 -1
  18. package/dist/mcp-server/tools/definitions/get-news.tool.js.map +1 -1
  19. package/dist/mcp-server/tools/definitions/get-quote.tool.d.ts.map +1 -1
  20. package/dist/mcp-server/tools/definitions/get-quote.tool.js +4 -2
  21. package/dist/mcp-server/tools/definitions/get-quote.tool.js.map +1 -1
  22. package/dist/mcp-server/tools/definitions/get-recommendations.tool.d.ts +1 -1
  23. package/dist/mcp-server/tools/definitions/get-recommendations.tool.d.ts.map +1 -1
  24. package/dist/mcp-server/tools/definitions/get-recommendations.tool.js +7 -5
  25. package/dist/mcp-server/tools/definitions/get-recommendations.tool.js.map +1 -1
  26. package/dist/mcp-server/tools/definitions/index.d.ts +47 -47
  27. package/dist/services/finnhub/finnhub-service.d.ts +1 -1
  28. package/dist/services/finnhub/finnhub-service.js +1 -1
  29. package/package.json +13 -11
  30. package/server.json +10 -24
  31. package/skills/finnhub-guide/SKILL.md +31 -0
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
5
- **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.6`
4
+ **Version:** 0.2.0
5
+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.18`
6
6
  **Engines:** Bun ≥1.4.0, Node ≥24.0.0
7
- **MCP SDK:** `@modelcontextprotocol/server` 2.0.0
8
- **Zod:** ^4.6.5
7
+ **MCP SDK:** `@modelcontextprotocol/server` 2.4.0
8
+ **Zod:** ^4.6.7
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
 
@@ -35,7 +35,7 @@ export const searchItems = tool('search_items', {
35
35
  annotations: { readOnlyHint: true },
36
36
  input: z.object({
37
37
  query: z.string().describe('Search terms'),
38
- limit: z.number().default(10).describe('Max results'),
38
+ limit: z.number().int().min(1).max(100).default(10).describe('Max results (1–100)'),
39
39
  }),
40
40
  output: z.object({
41
41
  items: z.array(z.object({
@@ -167,13 +167,14 @@ Handlers receive a unified `ctx` object. Key properties:
167
167
  | Property | Description |
168
168
  |:---------|:------------|
169
169
  | `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. Dual-sink: Pino **and** `notifications/message` to the client, so treat it as client-visible. |
170
- | `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |
170
+ | `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts any JSON-serializable value; reads return its JSON form (a `Date` comes back as an ISO string). |
171
171
  | `ctx.requestInput` | Suspend and ask the caller for more input — `return ctx.requestInput({ inputRequests: { key: inputRequired.elicit({ message, requestedSchema }) } })`. Never returns; the handler is re-entered with the answers. Always present. |
172
- | `ctx.inputs` | Reader over a retried request's responses — `.accepted(key, schema)`, `.view(key)`, `.state()`, `.dropped`. Empty on the first round. |
172
+ | `ctx.inputs` | The request's responses — `.accepted(key, schema)`, `.view(key)`, `.state()`, `.dropped` — limited to what the client declared (`elicitation` and its form/url modes, `sampling`, `roots`). Client-supplied: a consent gate trusts only a `ctx.state` record it stored when it asked, bound to the operation, caller, and target (see the `api-context` skill). |
173
+ | `ctx.clientCapabilities` | What the client declared for this request, `undefined` when no view exists. Decides whether to ask for optional context (e.g. roots); never a reason to skip a consent prompt. |
173
174
  | `ctx.enrich` | Success-path agent context (empty-result notices, query echo, pagination totals) — `ctx.enrich(...)` or `.notice()` / `.total()` / `.echo()` / `.truncated()`. Reaches `structuredContent` and `content[]`; lands only when the definition declares an `enrichment` block (no-op otherwise). |
174
175
  | `ctx.content` | Non-text content blocks — `.image(data, mimeType)`, `.audio(data, mimeType)`, or `ctx.content(block)` for a raw block. Prepended to `content[]` after `format()`; never enters `structuredContent`. |
175
176
  | `ctx.signal` | `AbortSignal` for cancellation. |
176
- | `ctx.requestId` | Unique request ID. |
177
+ | `ctx.requestId` | Request ID — the one every log record of the call carries and its error envelope returns as `data.requestId`. |
177
178
  | `ctx.tenantId` | Tenant ID from JWT; `'default'` for stdio or HTTP with auth off. |
178
179
 
179
180
  ---
@@ -182,7 +183,7 @@ Handlers receive a unified `ctx` object. Key properties:
182
183
 
183
184
  Handlers throw — the framework catches, classifies, and formats.
184
185
 
185
- **Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required (≥ 5 words, lint-validated) — the single source of truth for the agent's next move. Pass `ctx.recoveryFor('reason')` as the throw's data to put it on the wire (`data.recovery.hint`, mirrored into `content[]` text unless the message already contains it verbatim); override with an explicit `{ recovery: { hint: '...' } }` when dynamic runtime context matters. Forwarding it is lint-enforced per throw site (`error-contract-recovery-unforwarded`). Mark an entry the service layer throws with `thrownBy: 'service'` so `error-contract-unthrown` skips it — lint-only metadata, nothing at runtime reads it. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely and don't need declaring.
186
+ **Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required (≥ 5 words, lint-validated) — the single source of truth for the agent's next move. The framework puts it on the wire whenever a failure carrying that `reason` arrives without a hint — a bare `ctx.fail('reason')` or a service throw with `data: { reason }` — as `data.recovery.hint`, mirrored into `content[]` text unless the message already contains it verbatim; override with an explicit `{ recovery: { hint: '...' } }` when dynamic runtime context matters. Every error envelope also carries `data.requestId`, the id the server's log records for that call carry, and `content[]` closes with `(reason … · request <id>)`. Mark an entry the service layer throws with `thrownBy: 'service'` so `error-contract-unthrown` skips it — lint-only metadata, nothing at runtime reads it. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely and don't need declaring.
186
187
 
187
188
  ```ts
188
189
  import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
@@ -194,7 +195,7 @@ errors: [
194
195
  ],
195
196
  async handler(input, ctx) {
196
197
  const item = await db.find(input.id);
197
- if (!item) throw ctx.fail('no_match', `No item ${input.id}`, ctx.recoveryFor('no_match'));
198
+ if (!item) throw ctx.fail('no_match', `No item ${input.id}`);
198
199
  return item;
199
200
  }
200
201
  ```
@@ -257,9 +258,18 @@ src/
257
258
 
258
259
  ## Skills
259
260
 
260
- Skills are modular instructions in `framework-skills/` at the project root. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. The directory is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, so a server that ships `.claude-plugin/` or `.codex-plugin/` would hand these development skills to every agent that installs it. Keep `skills/` free for skills meant for those agents.
261
+ Two skill trees live at the project root, written for different readers:
261
262
 
262
- **Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `framework-skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
263
+ | Tree | For | Written by |
264
+ |:-----|:----|:-----------|
265
+ | `framework-skills/` | The agent developing this server — framework skills (`metadata.audience: external`) plus any development-time skills of the server's own | `init` and the `maintenance` sync (framework skills); you (your own) |
266
+ | `skills/` | The agents that install the server and call its tools — tool chains, identifier sources, gates | You, deliberately, with the `add-skill` skill. Absent by default; usually none is needed |
267
+
268
+ Development skills are modular instructions. 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. Their 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 them to every agent that installs it.
269
+
270
+ A published skill in root `skills/` reaches plugin installs and the `.mcpb` bundle as-is, ships in the npm package and the Docker image, and reaches MCP clients when the server opts in with `createApp({ skills: 'skills' })`. `lint:packaging` validates the tree.
271
+
272
+ **Agent skill directory:** Copy `framework-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.
263
273
 
264
274
  Available skills:
265
275
 
@@ -271,6 +281,7 @@ Available skills:
271
281
  | `add-app-tool` | Scaffold an MCP App tool + paired UI resource |
272
282
  | `add-resource` | Scaffold a new resource definition |
273
283
  | `add-prompt` | Scaffold a new prompt definition |
284
+ | `add-skill` | Author a skill the server publishes in root `skills/` for the agents that use it — when one earns its place, structure, validation, delivery |
274
285
  | `add-service` | Scaffold a new service integration |
275
286
  | `add-test` | Scaffold test file for a tool, resource, or service |
276
287
  | `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
@@ -336,7 +347,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
336
347
 
337
348
  ## Bundling
338
349
 
339
- `bun run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips two classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`framework-skills/`, `skills/`, `.claude/`, `.agents/`, `SKILL.md`) and platform-specific native bindings, which would otherwise lock the bundle to the platform it was packed on. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
350
+ `npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. `mcpb pack` reads `.mcpbignore`, not `.gitignore`, so every root path the bundle must not ship — source, tests, docs, caches, logs, agent docs, plugin manifests, gitignored local files — needs a root-anchored line there (`/docs/`, never `docs/`, which also strips `node_modules/*/docs/`); `lint:packaging` names each missing or unanchored line. Root `skills/` ships on purpose. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips four classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`framework-skills/`, `skills/`, `.claude/`, `.agents/`, `SKILL.md`); platform-specific native bindings, which would otherwise lock the bundle to the platform it was packed on; node-gyp build output beside a `binding.gyp` (`config.gypi`, Makefiles, `obj.target/`, `.deps/`, object files and debug symbols), which records the packing machine's paths — compiled `*.node` addons stay; and build-only package files — the framework's `changelog/`, `scripts/`, `templates/`, `CLAUDE.md`, `AGENTS.md`, and config bases (`biome.json`, `vitest.config.base.mjs`, `config/tsconfig.base.json`), and `better-sqlite3`'s `deps/` and `src/` C sources. A server using DataCanvas therefore ships a portable bundle without the DuckDB native — `@duckdb/node-api` is an optional peer loaded lazily, so canvas tools report an actionable install hint and every other tool works normally. 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
351
 
341
352
  **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": ""`.
342
353
 
@@ -373,7 +384,7 @@ security: false # optional — true ONLY for a source
373
384
 
374
385
  ## Publishing
375
386
 
376
- **Every release goes through a release PR, straight-through** — `git-wrapup`'s "Release PR mode", mode `straight-through`. One run: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the changelog entry plus a gates section); `release-and-publish` then fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the branch, and publishes. A caller's brief may run a given release as `gated` instead — a `release-pr-review` pass on the open PR before `release-and-publish`. **Never merge through the GitHub UI or `gh pr merge`**: squash and rebase-merge are disabled in the repo settings because both rewrite the stack (rebase-merge also strips the SSH signatures), and a merge commit breaks the linear history.
387
+ **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
388
 
378
389
  ---
379
390
 
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
5
- **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.6`
4
+ **Version:** 0.2.0
5
+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.18`
6
6
  **Engines:** Bun ≥1.4.0, Node ≥24.0.0
7
- **MCP SDK:** `@modelcontextprotocol/server` 2.0.0
8
- **Zod:** ^4.6.5
7
+ **MCP SDK:** `@modelcontextprotocol/server` 2.4.0
8
+ **Zod:** ^4.6.7
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
 
@@ -35,7 +35,7 @@ export const searchItems = tool('search_items', {
35
35
  annotations: { readOnlyHint: true },
36
36
  input: z.object({
37
37
  query: z.string().describe('Search terms'),
38
- limit: z.number().default(10).describe('Max results'),
38
+ limit: z.number().int().min(1).max(100).default(10).describe('Max results (1–100)'),
39
39
  }),
40
40
  output: z.object({
41
41
  items: z.array(z.object({
@@ -167,13 +167,14 @@ Handlers receive a unified `ctx` object. Key properties:
167
167
  | Property | Description |
168
168
  |:---------|:------------|
169
169
  | `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. Dual-sink: Pino **and** `notifications/message` to the client, so treat it as client-visible. |
170
- | `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |
170
+ | `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts any JSON-serializable value; reads return its JSON form (a `Date` comes back as an ISO string). |
171
171
  | `ctx.requestInput` | Suspend and ask the caller for more input — `return ctx.requestInput({ inputRequests: { key: inputRequired.elicit({ message, requestedSchema }) } })`. Never returns; the handler is re-entered with the answers. Always present. |
172
- | `ctx.inputs` | Reader over a retried request's responses — `.accepted(key, schema)`, `.view(key)`, `.state()`, `.dropped`. Empty on the first round. |
172
+ | `ctx.inputs` | The request's responses — `.accepted(key, schema)`, `.view(key)`, `.state()`, `.dropped` — limited to what the client declared (`elicitation` and its form/url modes, `sampling`, `roots`). Client-supplied: a consent gate trusts only a `ctx.state` record it stored when it asked, bound to the operation, caller, and target (see the `api-context` skill). |
173
+ | `ctx.clientCapabilities` | What the client declared for this request, `undefined` when no view exists. Decides whether to ask for optional context (e.g. roots); never a reason to skip a consent prompt. |
173
174
  | `ctx.enrich` | Success-path agent context (empty-result notices, query echo, pagination totals) — `ctx.enrich(...)` or `.notice()` / `.total()` / `.echo()` / `.truncated()`. Reaches `structuredContent` and `content[]`; lands only when the definition declares an `enrichment` block (no-op otherwise). |
174
175
  | `ctx.content` | Non-text content blocks — `.image(data, mimeType)`, `.audio(data, mimeType)`, or `ctx.content(block)` for a raw block. Prepended to `content[]` after `format()`; never enters `structuredContent`. |
175
176
  | `ctx.signal` | `AbortSignal` for cancellation. |
176
- | `ctx.requestId` | Unique request ID. |
177
+ | `ctx.requestId` | Request ID — the one every log record of the call carries and its error envelope returns as `data.requestId`. |
177
178
  | `ctx.tenantId` | Tenant ID from JWT; `'default'` for stdio or HTTP with auth off. |
178
179
 
179
180
  ---
@@ -182,7 +183,7 @@ Handlers receive a unified `ctx` object. Key properties:
182
183
 
183
184
  Handlers throw — the framework catches, classifies, and formats.
184
185
 
185
- **Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required (≥ 5 words, lint-validated) — the single source of truth for the agent's next move. Pass `ctx.recoveryFor('reason')` as the throw's data to put it on the wire (`data.recovery.hint`, mirrored into `content[]` text unless the message already contains it verbatim); override with an explicit `{ recovery: { hint: '...' } }` when dynamic runtime context matters. Forwarding it is lint-enforced per throw site (`error-contract-recovery-unforwarded`). Mark an entry the service layer throws with `thrownBy: 'service'` so `error-contract-unthrown` skips it — lint-only metadata, nothing at runtime reads it. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely and don't need declaring.
186
+ **Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required (≥ 5 words, lint-validated) — the single source of truth for the agent's next move. The framework puts it on the wire whenever a failure carrying that `reason` arrives without a hint — a bare `ctx.fail('reason')` or a service throw with `data: { reason }` — as `data.recovery.hint`, mirrored into `content[]` text unless the message already contains it verbatim; override with an explicit `{ recovery: { hint: '...' } }` when dynamic runtime context matters. Every error envelope also carries `data.requestId`, the id the server's log records for that call carry, and `content[]` closes with `(reason … · request <id>)`. Mark an entry the service layer throws with `thrownBy: 'service'` so `error-contract-unthrown` skips it — lint-only metadata, nothing at runtime reads it. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely and don't need declaring.
186
187
 
187
188
  ```ts
188
189
  import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
@@ -194,7 +195,7 @@ errors: [
194
195
  ],
195
196
  async handler(input, ctx) {
196
197
  const item = await db.find(input.id);
197
- if (!item) throw ctx.fail('no_match', `No item ${input.id}`, ctx.recoveryFor('no_match'));
198
+ if (!item) throw ctx.fail('no_match', `No item ${input.id}`);
198
199
  return item;
199
200
  }
200
201
  ```
@@ -257,9 +258,18 @@ src/
257
258
 
258
259
  ## Skills
259
260
 
260
- Skills are modular instructions in `framework-skills/` at the project root. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. The directory is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, so a server that ships `.claude-plugin/` or `.codex-plugin/` would hand these development skills to every agent that installs it. Keep `skills/` free for skills meant for those agents.
261
+ Two skill trees live at the project root, written for different readers:
261
262
 
262
- **Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `framework-skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
263
+ | Tree | For | Written by |
264
+ |:-----|:----|:-----------|
265
+ | `framework-skills/` | The agent developing this server — framework skills (`metadata.audience: external`) plus any development-time skills of the server's own | `init` and the `maintenance` sync (framework skills); you (your own) |
266
+ | `skills/` | The agents that install the server and call its tools — tool chains, identifier sources, gates | You, deliberately, with the `add-skill` skill. Absent by default; usually none is needed |
267
+
268
+ Development skills are modular instructions. 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. Their 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 them to every agent that installs it.
269
+
270
+ A published skill in root `skills/` reaches plugin installs and the `.mcpb` bundle as-is, ships in the npm package and the Docker image, and reaches MCP clients when the server opts in with `createApp({ skills: 'skills' })`. `lint:packaging` validates the tree.
271
+
272
+ **Agent skill directory:** Copy `framework-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.
263
273
 
264
274
  Available skills:
265
275
 
@@ -271,6 +281,7 @@ Available skills:
271
281
  | `add-app-tool` | Scaffold an MCP App tool + paired UI resource |
272
282
  | `add-resource` | Scaffold a new resource definition |
273
283
  | `add-prompt` | Scaffold a new prompt definition |
284
+ | `add-skill` | Author a skill the server publishes in root `skills/` for the agents that use it — when one earns its place, structure, validation, delivery |
274
285
  | `add-service` | Scaffold a new service integration |
275
286
  | `add-test` | Scaffold test file for a tool, resource, or service |
276
287
  | `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
@@ -336,7 +347,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
336
347
 
337
348
  ## Bundling
338
349
 
339
- `bun run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips two classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`framework-skills/`, `skills/`, `.claude/`, `.agents/`, `SKILL.md`) and platform-specific native bindings, which would otherwise lock the bundle to the platform it was packed on. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
350
+ `npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. `mcpb pack` reads `.mcpbignore`, not `.gitignore`, so every root path the bundle must not ship — source, tests, docs, caches, logs, agent docs, plugin manifests, gitignored local files — needs a root-anchored line there (`/docs/`, never `docs/`, which also strips `node_modules/*/docs/`); `lint:packaging` names each missing or unanchored line. Root `skills/` ships on purpose. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips four classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`framework-skills/`, `skills/`, `.claude/`, `.agents/`, `SKILL.md`); platform-specific native bindings, which would otherwise lock the bundle to the platform it was packed on; node-gyp build output beside a `binding.gyp` (`config.gypi`, Makefiles, `obj.target/`, `.deps/`, object files and debug symbols), which records the packing machine's paths — compiled `*.node` addons stay; and build-only package files — the framework's `changelog/`, `scripts/`, `templates/`, `CLAUDE.md`, `AGENTS.md`, and config bases (`biome.json`, `vitest.config.base.mjs`, `config/tsconfig.base.json`), and `better-sqlite3`'s `deps/` and `src/` C sources. A server using DataCanvas therefore ships a portable bundle without the DuckDB native — `@duckdb/node-api` is an optional peer loaded lazily, so canvas tools report an actionable install hint and every other tool works normally. 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
351
 
341
352
  **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": ""`.
342
353
 
@@ -373,7 +384,7 @@ security: false # optional — true ONLY for a source
373
384
 
374
385
  ## Publishing
375
386
 
376
- **Every release goes through a release PR, straight-through** — `git-wrapup`'s "Release PR mode", mode `straight-through`. One run: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the changelog entry plus a gates section); `release-and-publish` then fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the branch, and publishes. A caller's brief may run a given release as `gated` instead — a `release-pr-review` pass on the open PR before `release-and-publish`. **Never merge through the GitHub UI or `gh pr merge`**: squash and rebase-merge are disabled in the repo settings because both rewrite the stack (rebase-merge also strips the SSH signatures), and a merge commit breaks the linear history.
387
+ **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
388
 
378
389
  ---
379
390
 
package/Dockerfile CHANGED
@@ -4,12 +4,17 @@
4
4
  # This stage installs all dependencies (including dev), builds the TypeScript
5
5
  # source code into JavaScript, and prepares the production assets.
6
6
  #
7
- # --platform=$BUILDPLATFORM runs the build natively on the host arch: the output
8
- # is platform-independent JS (only dist/ copies forward), so a multi-arch
9
- # buildx push must not emulate this stage — Bun under QEMU aborts with
10
- # JSC MemoryExhaustion.
7
+ # Pinned to $BUILDPLATFORM rather than the target platform: `bun run build` emits
8
+ # JavaScript, and only `dist/` crosses into the production stage. Built for the
9
+ # target instead, the non-native leg of a `--platform linux/amd64,linux/arm64`
10
+ # build runs under QEMU, where bun >= 1.4 aborts with a JavaScriptCore allocator
11
+ # assertion and fails the multi-arch push.
12
+ #
13
+ # The constraint this assumes: the build stage produces platform-independent
14
+ # output. A stage that compiles a native addon needs the target-arch toolchain
15
+ # and cannot cross-compile this way — drop the flag there.
11
16
  # ==============================================================================
12
- FROM --platform=$BUILDPLATFORM oven/bun:1.4.0 AS build
17
+ FROM --platform=$BUILDPLATFORM oven/bun:1.4.4 AS build
13
18
 
14
19
  WORKDIR /usr/src/app
15
20
 
@@ -18,73 +23,123 @@ 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
 
25
29
  # Copy the rest of the source code
26
30
  COPY . .
27
31
 
32
+ # Published skills are read from the application root at runtime.
33
+ RUN mkdir -p skills
34
+
28
35
  # Build the application
29
36
  RUN bun run build
30
37
 
31
38
 
32
39
  # ==============================================================================
33
- # Production Stage
40
+ # Production Dependencies Stage
34
41
  #
35
- # This stage creates a minimal, optimized, and secure image for running the
36
- # application. It uses a slim base image and only includes production
37
- # dependencies and build artifacts.
42
+ # Installs the production dependency tree for the target platform. Every step
43
+ # here can run JavaScript — bunfig.toml's security scanner runs as a Bun
44
+ # program, and so do the OTel and musl-prune scripts — so the stage runs on
45
+ # $BUILDPLATFORM and cross-installs with `--os`/`--cpu`, which pick each
46
+ # platform-specific optional dependency (native bindings such as DuckDB's) for
47
+ # the target. Only `node_modules` leaves this stage.
48
+ #
49
+ # A clean image rather than `FROM build`: the build stage's node_modules holds
50
+ # devDependencies.
38
51
  # ==============================================================================
39
- FROM oven/bun:1.4.0-slim AS production
52
+ FROM --platform=$BUILDPLATFORM oven/bun:1.4.4 AS deps
40
53
 
41
54
  WORKDIR /usr/src/app
42
55
 
43
- # Set the environment to production for performance and to ensure only
44
- # production dependencies are installed.
45
- ENV NODE_ENV=production
46
-
47
- # OCI image metadata (https://github.com/opencontainers/image-spec/blob/main/annotations.md)
48
- ARG APP_VERSION
49
- LABEL org.opencontainers.image.title="finnhub-mcp-server"
50
- LABEL org.opencontainers.image.description="Real-time US-equity quotes, company fundamentals, earnings, analyst trends, and news via Finnhub."
51
- LABEL org.opencontainers.image.licenses="Apache-2.0"
52
- LABEL org.opencontainers.image.version="${APP_VERSION}"
53
- LABEL org.opencontainers.image.source="https://github.com/cyanheads/finnhub-mcp-server"
54
-
55
- # Copy dependency manifests
56
- COPY package.json bun.lock ./
56
+ # Copy dependency manifests. `bunfig.toml` rides along so every install below
57
+ # passes its release-age gate and security scanner, as a local install does.
58
+ COPY package.json bun.lock bunfig.toml ./
59
+
60
+ # The scanner bunfig.toml names is a devDependency, and Bun installs a missing
61
+ # scanner through the same production-filtered install, which omits it and
62
+ # aborts. Seed it from the build stage's full install instead. Remove this line,
63
+ # and the `rm` at the end of this stage, if bunfig.toml stops naming a scanner.
64
+ COPY --from=build /usr/src/app/node_modules/@socketsecurity/bun-security-scanner ./node_modules/@socketsecurity/bun-security-scanner
65
+
66
+ # Docker names the target architecture `amd64`/`arm64`; Bun's `--cpu` takes
67
+ # `x64`/`arm64`. Mapped once here, read by both installs below. `oven/bun`
68
+ # publishes only these two architectures, so any other target fails here.
69
+ ARG TARGETOS
70
+ ARG TARGETARCH
71
+ RUN case "$TARGETARCH" in \
72
+ amd64) echo x64 ;; \
73
+ arm64) echo arm64 ;; \
74
+ *) echo "Unsupported TARGETARCH '$TARGETARCH': expected amd64 or arm64" >&2; exit 1 ;; \
75
+ esac > .bun-cpu
57
76
 
58
77
  # Install only production dependencies, ignoring any lifecycle scripts (like 'prepare')
59
78
  # that are not needed in the final production image.
60
79
  # `--omit=peer` drops the framework's optional peer tiers (test runner, service
61
80
  # SDKs, parsers) that Bun would otherwise auto-install. Anything this server
62
81
  # actually imports belongs in its own `dependencies`, so nothing needed at
63
- # runtime is lost. The OTEL step below carries the same flag — without it, that
64
- # install re-resolves the graph and pulls every optional peer back in.
82
+ # runtime is lost.
65
83
  RUN --mount=type=cache,target=/root/.bun/install/cache \
66
- bun install --production --omit=peer --frozen-lockfile --ignore-scripts
84
+ bun install --production --omit=peer --frozen-lockfile --ignore-scripts \
85
+ --os="$TARGETOS" --cpu="$(cat .bun-cpu)"
67
86
 
68
87
  # Conditionally install OpenTelemetry optional peer dependencies (Tier 3).
69
- # These are not bundled by default to keep the base image lean. Enable at build time
70
- # with: docker build --build-arg OTEL_ENABLED=true
88
+ # Installed by default. Omit them for a leaner image at build time
89
+ # with: docker build --build-arg OTEL_ENABLED=false
90
+ # The script reads the list and each range from the installed framework's
91
+ # `peerDependencies` and passes the target flags on to its `bun install`.
92
+ COPY scripts/install-otel.ts ./scripts/
71
93
  ARG OTEL_ENABLED=true
72
94
  RUN --mount=type=cache,target=/root/.bun/install/cache \
73
95
  if [ "$OTEL_ENABLED" = "true" ]; then \
74
- bun add --omit=dev --omit=peer --ignore-scripts @hono/otel \
75
- @opentelemetry/instrumentation-http \
76
- @opentelemetry/exporter-metrics-otlp-http \
77
- @opentelemetry/exporter-trace-otlp-http \
78
- @opentelemetry/instrumentation-pino \
79
- @opentelemetry/resources \
80
- @opentelemetry/sdk-metrics \
81
- @opentelemetry/sdk-node \
82
- @opentelemetry/sdk-trace-node \
83
- @opentelemetry/semantic-conventions; \
96
+ bun scripts/install-otel.ts --os="$TARGETOS" --cpu="$(cat .bun-cpu)"; \
84
97
  fi
85
98
 
99
+ # `--os`/`--cpu` have no libc counterpart, so a native dependency published in
100
+ # glibc and musl variants (DuckDB's bindings, for one) installs both. The
101
+ # runtime image is Debian (glibc) and never loads the musl copy; the script
102
+ # deletes every package whose own `libc` admits only musl. It follows every
103
+ # install, since a later `bun install` restores what it removes. A server on a
104
+ # musl (Alpine) runtime image drops these two lines.
105
+ COPY scripts/prune-musl-packages.ts ./scripts/
106
+ RUN bun scripts/prune-musl-packages.ts
107
+
108
+ # The seeded scanner served only the installs above; keep it out of the image.
109
+ RUN rm -rf node_modules/@socketsecurity/bun-security-scanner
110
+
111
+
112
+ # ==============================================================================
113
+ # Production Stage
114
+ #
115
+ # This stage creates a minimal, optimized, and secure image for running the
116
+ # application. It uses a slim base image and only includes production
117
+ # dependencies and build artifacts. Its only Bun invocations are HEALTHCHECK
118
+ # and CMD, which run on the real target at container start.
119
+ # ==============================================================================
120
+ FROM oven/bun:1.4.4-slim AS production
121
+
122
+ WORKDIR /usr/src/app
123
+
124
+ # Set the environment to production for performance.
125
+ ENV NODE_ENV=production
126
+
127
+ # OCI image metadata (https://github.com/opencontainers/image-spec/blob/main/annotations.md)
128
+ ARG APP_VERSION
129
+ LABEL org.opencontainers.image.title="finnhub-mcp-server"
130
+ LABEL org.opencontainers.image.description="Real-time US-equity quotes, company fundamentals, earnings, analyst trends, and news via Finnhub."
131
+ LABEL org.opencontainers.image.licenses="Apache-2.0"
132
+ LABEL org.opencontainers.image.version="${APP_VERSION}"
133
+ LABEL org.opencontainers.image.source="https://github.com/cyanheads/finnhub-mcp-server"
134
+
135
+ # The manifest comes from the build context: the deps stage's copy was rewritten
136
+ # by the OTel install, and the runtime reads only its name, version, and type.
137
+ COPY package.json ./
138
+ COPY --from=deps /usr/src/app/node_modules ./node_modules
139
+
86
140
  # Copy the compiled application code from the build stage
87
141
  COPY --from=build /usr/src/app/dist ./dist
142
+ COPY --from=build /usr/src/app/skills ./skills
88
143
 
89
144
  # Mirror CLI (MirrorService adopters only — Tier 3, opt-in):
90
145
  # Copy your mirror lifecycle scripts and emit a runtime tsconfig so Bun resolves
@@ -124,7 +179,6 @@ ENV MCP_TRANSPORT_TYPE="http"
124
179
  ENV MCP_SESSION_MODE="stateless"
125
180
  ENV MCP_LOG_LEVEL="info"
126
181
  ENV LOGS_DIR="/var/log/finnhub-mcp-server"
127
- ENV MCP_FORCE_CONSOLE_LOGGING="true"
128
182
 
129
183
  # Expose the port the server listens on
130
184
  EXPOSE ${MCP_HTTP_PORT}