@cyanheads/finnhub-mcp-server 0.2.0 → 0.2.1
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 +7 -5
- package/CLAUDE.md +7 -5
- package/README.md +15 -12
- package/changelog/0.2.x/0.2.1.md +35 -0
- package/changelog/template.md +10 -3
- package/dist/mcp-server/tools/definitions/get-company.tool.d.ts +11 -1
- package/dist/mcp-server/tools/definitions/get-company.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-company.tool.js +11 -5
- package/dist/mcp-server/tools/definitions/get-company.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-earnings.tool.d.ts +25 -2
- package/dist/mcp-server/tools/definitions/get-earnings.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-earnings.tool.js +84 -40
- package/dist/mcp-server/tools/definitions/get-earnings.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-news.tool.d.ts +16 -0
- package/dist/mcp-server/tools/definitions/get-news.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-news.tool.js +87 -33
- package/dist/mcp-server/tools/definitions/get-news.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-recommendations.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-recommendations.tool.js +1 -2
- package/dist/mcp-server/tools/definitions/get-recommendations.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/index.d.ts +135 -84
- package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/search-symbols.tool.d.ts +2 -0
- package/dist/mcp-server/tools/definitions/search-symbols.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/search-symbols.tool.js +28 -18
- package/dist/mcp-server/tools/definitions/search-symbols.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/window-page.d.ts +21 -0
- package/dist/mcp-server/tools/definitions/window-page.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/window-page.js +39 -0
- package/dist/mcp-server/tools/definitions/window-page.js.map +1 -0
- package/dist/services/finnhub/date-window.d.ts +13 -0
- package/dist/services/finnhub/date-window.d.ts.map +1 -0
- package/dist/services/finnhub/date-window.js +32 -0
- package/dist/services/finnhub/date-window.js.map +1 -0
- package/dist/services/finnhub/finnhub-service.d.ts +4 -4
- package/dist/services/finnhub/finnhub-service.d.ts.map +1 -1
- package/dist/services/finnhub/finnhub-service.js +6 -6
- package/dist/services/finnhub/finnhub-service.js.map +1 -1
- package/dist/services/finnhub/normalize-article-text.d.ts +6 -0
- package/dist/services/finnhub/normalize-article-text.d.ts.map +1 -0
- package/dist/services/finnhub/normalize-article-text.js +97 -0
- package/dist/services/finnhub/normalize-article-text.js.map +1 -0
- package/dist/services/finnhub/types.d.ts +3 -3
- package/dist/services/finnhub/types.d.ts.map +1 -1
- package/package.json +10 -7
- package/server.json +3 -3
- package/skills/finnhub-guide/SKILL.md +5 -5
package/AGENTS.md
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
# Developer Protocol
|
|
2
2
|
|
|
3
3
|
**Server:** finnhub-mcp-server
|
|
4
|
-
**Version:** 0.2.
|
|
5
|
-
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.
|
|
6
|
-
**Engines:** Bun ≥1.4.
|
|
4
|
+
**Version:** 0.2.1
|
|
5
|
+
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.22`
|
|
6
|
+
**Engines:** Bun ≥1.4.4, Node ≥24.0.0
|
|
7
7
|
**MCP SDK:** `@modelcontextprotocol/server` 2.4.0
|
|
8
8
|
**Zod:** ^4.6.7
|
|
9
9
|
|
|
@@ -327,7 +327,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
|
|
|
327
327
|
| `bun run clean` | Remove build artifacts |
|
|
328
328
|
| `bun run devcheck` | Lint + format + typecheck + security + changelog sync |
|
|
329
329
|
| `bun run lint:mcp` | Run the MCP definition linter standalone (rule catalog: `api-linter` skill) |
|
|
330
|
-
| `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity (run by devcheck) |
|
|
330
|
+
| `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity, `.mcpbignore` coverage, plugin manifests, and the published `skills/` tree (run by devcheck) |
|
|
331
331
|
| `bun run list-skills` | Print the skill registry |
|
|
332
332
|
| `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` |
|
|
333
333
|
| `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` |
|
|
@@ -347,7 +347,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
|
|
|
347
347
|
|
|
348
348
|
## Bundling
|
|
349
349
|
|
|
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
|
|
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/`, `AGENTS.md`, and `CLAUDE.md` at a package's root, and `SKILL.md` anywhere (a `skills/` deeper in a package is runtime code and stays); 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/`, 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.
|
|
351
351
|
|
|
352
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": ""`.
|
|
353
353
|
|
|
@@ -414,7 +414,9 @@ import { getMyService } from '@/services/my-domain/my-service.js';
|
|
|
414
414
|
- [ ] If wrapping external API: tests include at least one sparse payload case with omitted upstream fields
|
|
415
415
|
- [ ] Registered in `createApp()` arrays (directly or via barrel exports)
|
|
416
416
|
- [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
|
|
417
|
+
- [ ] Root `plugin.json` and `mcp.json` match the package metadata and fixed stdio configuration. User-supplied variables are forwarded through the `.codex-plugin/mcp.json` `env_vars` overlay, referenced by `.codex-plugin/plugin.json`.
|
|
417
418
|
- [ ] `.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
|
|
418
419
|
- [ ] `.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
|
|
419
420
|
- [ ] `.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`
|
|
420
421
|
- [ ] `npm run devcheck` passes
|
|
422
|
+
- [ ] New root development paths have anchored `.mcpbignore` entries. Run `bun run bundle` and `bun run lint:packaging` when changing the bundle.
|
package/CLAUDE.md
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
# Developer Protocol
|
|
2
2
|
|
|
3
3
|
**Server:** finnhub-mcp-server
|
|
4
|
-
**Version:** 0.2.
|
|
5
|
-
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.
|
|
6
|
-
**Engines:** Bun ≥1.4.
|
|
4
|
+
**Version:** 0.2.1
|
|
5
|
+
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.22`
|
|
6
|
+
**Engines:** Bun ≥1.4.4, Node ≥24.0.0
|
|
7
7
|
**MCP SDK:** `@modelcontextprotocol/server` 2.4.0
|
|
8
8
|
**Zod:** ^4.6.7
|
|
9
9
|
|
|
@@ -327,7 +327,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
|
|
|
327
327
|
| `bun run clean` | Remove build artifacts |
|
|
328
328
|
| `bun run devcheck` | Lint + format + typecheck + security + changelog sync |
|
|
329
329
|
| `bun run lint:mcp` | Run the MCP definition linter standalone (rule catalog: `api-linter` skill) |
|
|
330
|
-
| `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity (run by devcheck) |
|
|
330
|
+
| `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity, `.mcpbignore` coverage, plugin manifests, and the published `skills/` tree (run by devcheck) |
|
|
331
331
|
| `bun run list-skills` | Print the skill registry |
|
|
332
332
|
| `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` |
|
|
333
333
|
| `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` |
|
|
@@ -347,7 +347,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
|
|
|
347
347
|
|
|
348
348
|
## Bundling
|
|
349
349
|
|
|
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
|
|
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/`, `AGENTS.md`, and `CLAUDE.md` at a package's root, and `SKILL.md` anywhere (a `skills/` deeper in a package is runtime code and stays); 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/`, 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.
|
|
351
351
|
|
|
352
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": ""`.
|
|
353
353
|
|
|
@@ -414,7 +414,9 @@ import { getMyService } from '@/services/my-domain/my-service.js';
|
|
|
414
414
|
- [ ] If wrapping external API: tests include at least one sparse payload case with omitted upstream fields
|
|
415
415
|
- [ ] Registered in `createApp()` arrays (directly or via barrel exports)
|
|
416
416
|
- [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
|
|
417
|
+
- [ ] Root `plugin.json` and `mcp.json` match the package metadata and fixed stdio configuration. User-supplied variables are forwarded through the `.codex-plugin/mcp.json` `env_vars` overlay, referenced by `.codex-plugin/plugin.json`.
|
|
417
418
|
- [ ] `.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
|
|
418
419
|
- [ ] `.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
|
|
419
420
|
- [ ] `.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`
|
|
420
421
|
- [ ] `npm run devcheck` passes
|
|
422
|
+
- [ ] New root development paths have anchored `.mcpbignore` entries. Run `bun run bundle` and `bun run lint:packaging` when changing the bundle.
|
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
|
|
|
@@ -31,10 +31,10 @@ Ticker inputs are trimmed and uppercased; punctuation such as `BRK.B` is preserv
|
|
|
31
31
|
|
|
32
32
|
| Tool | Description |
|
|
33
33
|
|:---|:---|
|
|
34
|
-
| `finnhub_search_symbols` | Resolve a company name or
|
|
34
|
+
| `finnhub_search_symbols` | Resolve a company name or ticker, optionally within one exchange. Exact ticker matches rank first. |
|
|
35
35
|
| `finnhub_get_quote` | Real-time price quote for one US symbol, paired with live market-status so the response states whether the price is live or the prior close, including the returned session and named holiday. |
|
|
36
|
-
| `finnhub_get_company` |
|
|
37
|
-
| `finnhub_get_earnings` |
|
|
36
|
+
| `finnhub_get_company` | Get a company profile, headline fundamentals, and peers grouped by sub-industry, industry, or sector. |
|
|
37
|
+
| `finnhub_get_earnings` | Get quarterly EPS surprises or a calendar of releases with EPS and revenue estimates and reported actuals where available. |
|
|
38
38
|
| `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`). |
|
|
39
39
|
| `finnhub_get_recommendations` | Analyst recommendation trends for one US symbol — strong-buy / buy / hold / sell / strong-sell counts per month, newest first. |
|
|
40
40
|
|
|
@@ -52,7 +52,8 @@ The news-category reference mirrors the `category` enum on `finnhub_get_news`. T
|
|
|
52
52
|
### `finnhub_search_symbols` <sub>tool</sub>
|
|
53
53
|
|
|
54
54
|
- Search by company name or ticker fragment with `query` (1–20 characters) and `limit` (1–50, default 10).
|
|
55
|
-
-
|
|
55
|
+
- Exact `symbol` or `displaySymbol` matches rank first, ignoring case and retaining Finnhub's order among ties. Likely-US common stocks lead the remaining results. `isLikelyUS` describes symbol format. Endpoint coverage varies by security.
|
|
56
|
+
- Supply `exchange: "US"` for US listings. An omitted or blank exchange searches globally. A name search within one exchange can miss an ADR that a ticker search finds.
|
|
56
57
|
|
|
57
58
|
---
|
|
58
59
|
|
|
@@ -65,29 +66,31 @@ The news-category reference mirrors the `category` enum on `finnhub_get_news`. T
|
|
|
65
66
|
|
|
66
67
|
### `finnhub_get_company` <sub>tool</sub>
|
|
67
68
|
|
|
68
|
-
- Requires `symbol
|
|
69
|
+
- Requires `symbol` and returns the profile, nullable headline fundamentals, and peers. Set `peerGrouping` to `subIndustry` (default), `industry`, or `sector`. The response identifies the selected grouping.
|
|
69
70
|
- Failed metrics or peers appear in `partial`; the profile determines `symbol_not_found` and `not_us_or_paid` errors.
|
|
70
71
|
|
|
71
72
|
---
|
|
72
73
|
|
|
73
74
|
### `finnhub_get_earnings` <sub>tool</sub>
|
|
74
75
|
|
|
75
|
-
- `history` requires
|
|
76
|
-
- `
|
|
76
|
+
- `history` requires a symbol and returns up to `limit` available quarters of EPS actuals, estimates, and surprises (default 50).
|
|
77
|
+
- `calendar` accepts an optional symbol and inclusive UTC dates (`YYYY-MM-DD`, default today through 14 days ahead). Recently reported releases can include EPS and revenue actuals alongside estimates. Missing values are null. Report times include `bmo` (before open), `dmh` (during market hours), and `amc` (after close).
|
|
78
|
+
- Calendar pages contain up to 100 entries (default 50). Pass `nextOffset` as `offset` with the same filters to continue. At 1,500 fetched rows, Finnhub may have omitted earlier releases. Narrow the window or filter by symbol to check.
|
|
77
79
|
|
|
78
80
|
---
|
|
79
81
|
|
|
80
82
|
### `finnhub_get_news` <sub>tool</sub>
|
|
81
83
|
|
|
82
84
|
- `company` requires `symbol` and accepts a date range (default last 7 days). `market` uses `category`: `general`, `forex`, `crypto`, or `merger` (see `finnhub://news-categories`).
|
|
83
|
-
- Returns
|
|
85
|
+
- Returns plain-text headlines and summaries, source, ISO 8601 timestamp, and URL, newest first. Pages contain up to 100 articles (default 15).
|
|
86
|
+
- Company mode accepts inclusive UTC dates (`YYYY-MM-DD`). Follow `nextOffset` with the same filters for more fetched articles. Finnhub can omit older articles even below 250 results. Check the observed timestamps and query earlier windows for older coverage.
|
|
84
87
|
|
|
85
88
|
---
|
|
86
89
|
|
|
87
90
|
### `finnhub_get_recommendations` <sub>tool</sub>
|
|
88
91
|
|
|
89
92
|
- Per-month strong-buy / buy / hold / sell / strong-sell counts, newest first; history depth depends on Finnhub coverage.
|
|
90
|
-
- `limit` (
|
|
93
|
+
- `limit` accepts a positive integer (default 12). The response reports the number of months Finnhub supplied and whether more fetched rows were available.
|
|
91
94
|
- Empty result → `no_coverage`; it cannot distinguish an invalid symbol from a valid symbol without coverage. International or paid-only symbol → `not_us_or_paid`.
|
|
92
95
|
|
|
93
96
|
---
|
|
@@ -117,7 +120,7 @@ Agent-friendly output:
|
|
|
117
120
|
- Two distinct "not available" signals — `symbol_not_found` (all-zero quote / empty profile sentinel) vs. `not_us_or_paid` (international or paid-only, HTTP 403). An empty profile can also reflect missing instrument coverage.
|
|
118
121
|
- ETFs, funds, or trusts may lack company profiles, earnings history, or analyst recommendations. Empty responses retain ticker verification guidance and suggest `finnhub_get_quote` for price data without promising quote availability.
|
|
119
122
|
- Typed error contracts with recovery hints on every failure, plus the `isLikelyUS` search heuristic so an agent can prioritize likely free-tier symbols
|
|
120
|
-
-
|
|
123
|
+
- Calendar and company-news pages report the fetched count and observed bounds. Each page refetches Finnhub, so new or revised records can shift between requests.
|
|
121
124
|
|
|
122
125
|
## Getting started
|
|
123
126
|
|
|
@@ -173,7 +176,7 @@ See [`.env.example`](./.env.example) for the full list of optional overrides.
|
|
|
173
176
|
|
|
174
177
|
### Local development
|
|
175
178
|
|
|
176
|
-
Requires [Bun v1.4.
|
|
179
|
+
Requires [Bun v1.4.4](https://bun.sh/) or higher (or Node.js v24+), and a free [Finnhub API key](https://finnhub.io/register).
|
|
177
180
|
|
|
178
181
|
```sh
|
|
179
182
|
git clone https://github.com/cyanheads/finnhub-mcp-server.git
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
---
|
|
2
|
+
summary: "Page Finnhub earnings and company news and see reported EPS and revenue in the calendar."
|
|
3
|
+
breaking: false
|
|
4
|
+
security: false
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# 0.2.1 — 2026-11-20
|
|
8
|
+
|
|
9
|
+
## Added
|
|
10
|
+
|
|
11
|
+
- **Earnings calendar and company news** return `nextOffset` when additional fetched results are available. Earnings history and analyst recommendations accept larger limits (#17).
|
|
12
|
+
- **Earnings calendar** includes reported EPS and revenue where available and documents `dmh` for reports during market hours (#19).
|
|
13
|
+
- **Symbol search** accepts an exchange filter (#18).
|
|
14
|
+
- **Company peers** support sub-industry, industry, and sector grouping (#20).
|
|
15
|
+
|
|
16
|
+
## Changed
|
|
17
|
+
|
|
18
|
+
- Synced framework tooling and updated the Finnhub tool guide.
|
|
19
|
+
|
|
20
|
+
## Fixed
|
|
21
|
+
|
|
22
|
+
- **Earnings calendar and company news** report fetched date bounds and flag possible upstream omissions (#13).
|
|
23
|
+
- **Date windows** validate real, inclusive UTC dates and reject ranges whose start follows their end (#14).
|
|
24
|
+
- **Symbol search** ranks exact ticker matches first (#15).
|
|
25
|
+
- **Financial news** converts headline and summary HTML to plain text (#16).
|
|
26
|
+
|
|
27
|
+
## Dependencies
|
|
28
|
+
|
|
29
|
+
- `@cyanheads/mcp-ts-core` ^0.13.18 → ^0.13.22
|
|
30
|
+
- Added `parse5` ^8.1.1 for news normalization.
|
|
31
|
+
- `@biomejs/biome` 2.6.4 → 2.6.8
|
|
32
|
+
- Added `commonmark` ^0.31.2 and `@types/commonmark` ^0.27.10 for Markdown rendering tests.
|
|
33
|
+
- `ignore` ^7.0.14 → ^7.0.16
|
|
34
|
+
- `tsc-alias` ^1.9.9 → ^1.9.10
|
|
35
|
+
- `vitest` ^5.0.5 → ^5.1.1
|
package/changelog/template.md
CHANGED
|
@@ -116,14 +116,21 @@ security: false
|
|
|
116
116
|
resolves to whatever real item already owns 42, and timeline previews pull
|
|
117
117
|
in that unrelated item's metadata.
|
|
118
118
|
|
|
119
|
+
Outside reporters: when the issue or PR came from outside the project
|
|
120
|
+
(`git-wrapup` step 5 says how to tell), thank its author in the same
|
|
121
|
+
parenthetical, profile linked by full URL for the same reason:
|
|
122
|
+
|
|
123
|
+
([#38](https://github.com/cyanheads/mcp-ts-core/issues/38), thanks [@octocat](https://github.com/octocat)!)
|
|
124
|
+
|
|
119
125
|
TAG ANNOTATIONS — the annotated tag body renders as the GitHub Release body
|
|
120
126
|
via `gh release create --notes-from-tag`. It is a condensed digest of this
|
|
121
127
|
entry, never a copy, and its format is owned by the `release-and-publish`
|
|
122
128
|
skill (step 4, "Create the annotated tag"): a short subject line without the
|
|
123
129
|
version, flat headline bullets — no Keep-a-Changelog section headers, no
|
|
124
|
-
gates line — at most one deps line, issue backlinks
|
|
125
|
-
last. In release-PR mode the `git-wrapup`
|
|
126
|
-
PR body's `## Changes` and the tag copies
|
|
130
|
+
gates line — at most one deps line, issue backlinks with any outside-reporter
|
|
131
|
+
thanks, and the changelog link last. In release-PR mode the `git-wrapup`
|
|
132
|
+
skill authors those bullets as the PR body's `## Changes` and the tag copies
|
|
133
|
+
them.
|
|
127
134
|
-->
|
|
128
135
|
|
|
129
136
|
## Added
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* @fileoverview finnhub_get_company — full company context for one US symbol in
|
|
3
|
-
* a single call: profile, headline fundamentals, and
|
|
3
|
+
* a single call: profile, headline fundamentals, and a selectable peer group. Combines
|
|
4
4
|
* three endpoints so "tell me about Apple" needs one tool call, not three. The
|
|
5
5
|
* profile is the spine (drives errors); metrics and peers degrade to partial.
|
|
6
6
|
* @module mcp-server/tools/definitions/get-company.tool
|
|
@@ -9,6 +9,11 @@ import { z } from '@cyanheads/mcp-ts-core';
|
|
|
9
9
|
import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
|
|
10
10
|
export declare const getCompany: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
|
|
11
11
|
symbol: z.ZodString;
|
|
12
|
+
peerGrouping: z.ZodDefault<z.ZodEnum<{
|
|
13
|
+
industry: "industry";
|
|
14
|
+
sector: "sector";
|
|
15
|
+
subIndustry: "subIndustry";
|
|
16
|
+
}>>;
|
|
12
17
|
}, z.core.$strip>, z.ZodObject<{
|
|
13
18
|
symbol: z.ZodString;
|
|
14
19
|
profile: z.ZodObject<{
|
|
@@ -35,6 +40,11 @@ export declare const getCompany: import("@cyanheads/mcp-ts-core").ToolDefinition
|
|
|
35
40
|
revenueGrowthTTMYoy: z.ZodNullable<z.ZodNumber>;
|
|
36
41
|
roeTTM: z.ZodNullable<z.ZodNumber>;
|
|
37
42
|
}, z.core.$strip>;
|
|
43
|
+
peerGrouping: z.ZodEnum<{
|
|
44
|
+
industry: "industry";
|
|
45
|
+
sector: "sector";
|
|
46
|
+
subIndustry: "subIndustry";
|
|
47
|
+
}>;
|
|
38
48
|
peers: z.ZodArray<z.ZodString>;
|
|
39
49
|
partial: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
40
50
|
}, z.core.$strip>, readonly [{
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"get-company.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-company.tool.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAY,MAAM,+BAA+B,CAAC;
|
|
1
|
+
{"version":3,"file":"get-company.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-company.tool.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAY,MAAM,+BAA+B,CAAC;AAY3E,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA0NrB,CAAC"}
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* @fileoverview finnhub_get_company — full company context for one US symbol in
|
|
3
|
-
* a single call: profile, headline fundamentals, and
|
|
3
|
+
* a single call: profile, headline fundamentals, and a selectable peer group. Combines
|
|
4
4
|
* three endpoints so "tell me about Apple" needs one tool call, not three. The
|
|
5
5
|
* profile is the spine (drives errors); metrics and peers degrade to partial.
|
|
6
6
|
* @module mcp-server/tools/definitions/get-company.tool
|
|
@@ -8,13 +8,14 @@
|
|
|
8
8
|
import { tool, z } from '@cyanheads/mcp-ts-core';
|
|
9
9
|
import { JsonRpcErrorCode, McpError } from '@cyanheads/mcp-ts-core/errors';
|
|
10
10
|
import { getFinnhubService } from '../../../services/finnhub/finnhub-service.js';
|
|
11
|
+
const peerGroupingSchema = z.enum(['subIndustry', 'industry', 'sector']);
|
|
11
12
|
/** Pick a numeric metric, preserving absence as null (never zero-filled). */
|
|
12
13
|
function metricNum(metric, key) {
|
|
13
14
|
const value = metric?.[key];
|
|
14
15
|
return typeof value === 'number' ? value : null;
|
|
15
16
|
}
|
|
16
17
|
export const getCompany = tool('finnhub_get_company', {
|
|
17
|
-
description: 'Full company context for one US symbol in a single call: profile (name, exchange, industry, country, market cap, shares outstanding, IPO date, website, logo), headline fundamentals (P/E, EPS, 52-week range, beta, dividend yield, margins, growth), and
|
|
18
|
+
description: 'Full company context for one US symbol in a single call: profile (name, exchange, industry, country, market cap, shares outstanding, IPO date, website, logo), headline fundamentals (P/E, EPS, 52-week range, beta, dividend yield, margins, growth), and peers by sub-industry (default), industry, or sector. Resolve a company name with finnhub_search_symbols first. International symbols are not on the free tier.',
|
|
18
19
|
annotations: { readOnlyHint: true, openWorldHint: true },
|
|
19
20
|
input: z.object({
|
|
20
21
|
symbol: z
|
|
@@ -23,6 +24,9 @@ export const getCompany = tool('finnhub_get_company', {
|
|
|
23
24
|
.toUpperCase()
|
|
24
25
|
.min(1)
|
|
25
26
|
.describe('US stock ticker (e.g., "AAPL"), trimmed and uppercased with punctuation preserved. Resolve a company name with finnhub_search_symbols first. International symbols are not on the free tier.'),
|
|
27
|
+
peerGrouping: peerGroupingSchema
|
|
28
|
+
.default('subIndustry')
|
|
29
|
+
.describe('Peer group to request. Defaults to Finnhub’s sub-industry grouping.'),
|
|
26
30
|
}),
|
|
27
31
|
output: z.object({
|
|
28
32
|
symbol: z.string().describe('The symbol queried, trimmed and uppercased.'),
|
|
@@ -60,9 +64,10 @@ export const getCompany = tool('finnhub_get_company', {
|
|
|
60
64
|
roeTTM: z.number().nullable().describe('Return on equity %, TTM.'),
|
|
61
65
|
})
|
|
62
66
|
.describe('Curated headline fundamentals: P/E, EPS, 52-week range, beta, dividend yield, margins, and growth. Every field nullable — Finnhub omits metrics for thinly-covered names.'),
|
|
67
|
+
peerGrouping: peerGroupingSchema.describe('The peer grouping requested from Finnhub.'),
|
|
63
68
|
peers: z
|
|
64
69
|
.array(z.string())
|
|
65
|
-
.describe('
|
|
70
|
+
.describe('Finnhub peer symbols for the selected grouping. The list can include the queried symbol.'),
|
|
66
71
|
partial: z
|
|
67
72
|
.array(z.string())
|
|
68
73
|
.optional()
|
|
@@ -87,7 +92,7 @@ export const getCompany = tool('finnhub_get_company', {
|
|
|
87
92
|
const [profileResult, metricsResult, peersResult] = await Promise.allSettled([
|
|
88
93
|
service.profile(input.symbol, ctx),
|
|
89
94
|
service.metrics(input.symbol, ctx),
|
|
90
|
-
service.peers(input.symbol, ctx),
|
|
95
|
+
service.peers(input.symbol, ctx, input.peerGrouping === 'subIndustry' ? undefined : input.peerGrouping),
|
|
91
96
|
]);
|
|
92
97
|
// Profile leg drives errors.
|
|
93
98
|
if (profileResult.status === 'rejected') {
|
|
@@ -147,6 +152,7 @@ export const getCompany = tool('finnhub_get_company', {
|
|
|
147
152
|
symbol: input.symbol,
|
|
148
153
|
profile,
|
|
149
154
|
fundamentals,
|
|
155
|
+
peerGrouping: input.peerGrouping,
|
|
150
156
|
peers,
|
|
151
157
|
...(partial.length > 0 && { partial }),
|
|
152
158
|
};
|
|
@@ -183,7 +189,7 @@ export const getCompany = tool('finnhub_get_company', {
|
|
|
183
189
|
else {
|
|
184
190
|
lines.push('\n**Fundamentals:** Not available (thinly covered).');
|
|
185
191
|
}
|
|
186
|
-
lines.push(`\n**Peers:** ${result.peers.length > 0 ? result.peers.join(', ') : 'None'}`);
|
|
192
|
+
lines.push(`\n**Peers (${result.peerGrouping}):** ${result.peers.length > 0 ? result.peers.join(', ') : 'None'}`);
|
|
187
193
|
if (result.partial && result.partial.length > 0) {
|
|
188
194
|
lines.push(`\n⚠ partial: ${result.partial.join(', ')} unavailable`);
|
|
189
195
|
}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"get-company.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-company.tool.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAC3E,OAAO,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAG1E,6EAA6E;AAC7E,SAAS,SAAS,CAAC,MAAuC,EAAE,GAAW;IACrE,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC;IAC5B,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AAClD,CAAC;AAED,MAAM,CAAC,MAAM,UAAU,GAAG,IAAI,CAAC,qBAAqB,EAAE;IACpD,WAAW,EACT,
|
|
1
|
+
{"version":3,"file":"get-company.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-company.tool.ts"],"names":[],"mappings":"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"}
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* @fileoverview finnhub_get_earnings — earnings in two modes. `history`: a
|
|
3
3
|
* symbol's past quarters with actual-vs-estimate surprises. `calendar`:
|
|
4
|
-
*
|
|
4
|
+
* releases in a date window, optionally filtered by symbol.
|
|
5
5
|
* Mode-consolidated because both are the same noun (earnings) from two angles.
|
|
6
6
|
* @module mcp-server/tools/definitions/get-earnings.tool
|
|
7
7
|
*/
|
|
@@ -16,6 +16,7 @@ export declare const getEarnings: import("@cyanheads/mcp-ts-core").ToolDefinitio
|
|
|
16
16
|
from: z.ZodOptional<z.ZodString>;
|
|
17
17
|
to: z.ZodOptional<z.ZodString>;
|
|
18
18
|
limit: z.ZodDefault<z.ZodNumber>;
|
|
19
|
+
offset: z.ZodOptional<z.ZodNumber>;
|
|
19
20
|
}, z.core.$strip>, z.ZodObject<{
|
|
20
21
|
mode: z.ZodEnum<{
|
|
21
22
|
calendar: "calendar";
|
|
@@ -34,8 +35,10 @@ export declare const getEarnings: import("@cyanheads/mcp-ts-core").ToolDefinitio
|
|
|
34
35
|
symbol: z.ZodString;
|
|
35
36
|
date: z.ZodString;
|
|
36
37
|
hour: z.ZodString;
|
|
38
|
+
epsActual: z.ZodNullable<z.ZodNumber>;
|
|
37
39
|
epsEstimate: z.ZodNullable<z.ZodNumber>;
|
|
38
40
|
revenueEstimate: z.ZodNullable<z.ZodNumber>;
|
|
41
|
+
revenueActual: z.ZodNullable<z.ZodNumber>;
|
|
39
42
|
year: z.ZodNumber;
|
|
40
43
|
quarter: z.ZodNumber;
|
|
41
44
|
}, z.core.$strip>>>;
|
|
@@ -43,13 +46,33 @@ export declare const getEarnings: import("@cyanheads/mcp-ts-core").ToolDefinitio
|
|
|
43
46
|
readonly reason: "missing_symbol";
|
|
44
47
|
readonly code: JsonRpcErrorCode.ValidationError;
|
|
45
48
|
readonly when: "mode 'history' was requested without a symbol.";
|
|
46
|
-
readonly recovery: "Provide a `symbol` for history mode, or switch to mode
|
|
49
|
+
readonly recovery: "Provide a `symbol` for history mode, or switch to calendar mode for market-wide releases.";
|
|
50
|
+
}, {
|
|
51
|
+
readonly reason: "invalid_date";
|
|
52
|
+
readonly code: JsonRpcErrorCode.ValidationError;
|
|
53
|
+
readonly when: "A calendar bound is not a real YYYY-MM-DD date.";
|
|
54
|
+
readonly recovery: "Use YYYY-MM-DD for a real calendar date.";
|
|
55
|
+
readonly thrownBy: "service";
|
|
56
|
+
}, {
|
|
57
|
+
readonly reason: "inverted_date_window";
|
|
58
|
+
readonly code: JsonRpcErrorCode.ValidationError;
|
|
59
|
+
readonly when: "The resolved calendar start date is later than the end date.";
|
|
60
|
+
readonly recovery: "Choose a start date on or before the end date.";
|
|
61
|
+
readonly thrownBy: "service";
|
|
62
|
+
}, {
|
|
63
|
+
readonly reason: "calendar_limit_exceeded";
|
|
64
|
+
readonly code: JsonRpcErrorCode.ValidationError;
|
|
65
|
+
readonly when: "Calendar mode requested more than 100 rows per page.";
|
|
66
|
+
readonly recovery: "Use a limit of 100 or less and continue with nextOffset.";
|
|
47
67
|
}, {
|
|
48
68
|
readonly reason: "not_us_or_paid";
|
|
49
69
|
readonly code: JsonRpcErrorCode.Forbidden;
|
|
50
70
|
readonly when: "Upstream HTTP 403 on the symbol.";
|
|
51
71
|
readonly recovery: "Free tier is US equities only; use a US symbol or a paid plan.";
|
|
52
72
|
}], {
|
|
73
|
+
readonly fetchedFrom: z.ZodOptional<z.ZodString>;
|
|
74
|
+
readonly fetchedTo: z.ZodOptional<z.ZodString>;
|
|
75
|
+
readonly nextOffset: z.ZodOptional<z.ZodNumber>;
|
|
53
76
|
readonly totalCount: z.ZodNumber;
|
|
54
77
|
readonly truncated: z.ZodOptional<z.ZodBoolean>;
|
|
55
78
|
readonly shown: z.ZodOptional<z.ZodNumber>;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"get-earnings.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-earnings.tool.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAY,MAAM,+BAA+B,CAAC;AAQ3E,eAAO,MAAM,WAAW
|
|
1
|
+
{"version":3,"file":"get-earnings.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-earnings.tool.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAY,MAAM,+BAA+B,CAAC;AAQ3E,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmTtB,CAAC"}
|