@cyanheads/secedgar-mcp-server 0.18.1 → 0.19.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 +36 -24
- package/CLAUDE.md +36 -24
- package/README.md +16 -12
- package/changelog/0.19.x/0.19.0.md +47 -0
- package/changelog/0.19.x/0.19.1.md +35 -0
- package/changelog/template.md +10 -3
- package/dist/config/server-config.js +2 -2
- package/dist/config/server-config.js.map +1 -1
- package/dist/index.js +27 -9
- package/dist/index.js.map +1 -1
- package/dist/mcp-server/tools/dataset-schema.d.ts +14 -0
- package/dist/mcp-server/tools/dataset-schema.d.ts.map +1 -0
- package/dist/mcp-server/tools/dataset-schema.js +16 -0
- package/dist/mcp-server/tools/dataset-schema.js.map +1 -0
- package/dist/mcp-server/tools/definitions/company-search.tool.d.ts +44 -14
- package/dist/mcp-server/tools/definitions/company-search.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/company-search.tool.js +197 -62
- package/dist/mcp-server/tools/definitions/company-search.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/compare-companies.tool.d.ts +26 -12
- package/dist/mcp-server/tools/definitions/compare-companies.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/compare-companies.tool.js +41 -39
- package/dist/mcp-server/tools/definitions/compare-companies.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/dataframe-describe.tool.d.ts +12 -3
- package/dist/mcp-server/tools/definitions/dataframe-describe.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/dataframe-describe.tool.js +23 -9
- package/dist/mcp-server/tools/definitions/dataframe-describe.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/dataframe-drop.tool.js +2 -2
- package/dist/mcp-server/tools/definitions/dataframe-drop.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/dataframe-query.tool.d.ts +16 -16
- package/dist/mcp-server/tools/definitions/dataframe-query.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/dataframe-query.tool.js +17 -17
- package/dist/mcp-server/tools/definitions/dataframe-query.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/fetch-frames.tool.d.ts +26 -12
- package/dist/mcp-server/tools/definitions/fetch-frames.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/fetch-frames.tool.js +15 -37
- package/dist/mcp-server/tools/definitions/fetch-frames.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/find-holders.tool.d.ts +36 -20
- package/dist/mcp-server/tools/definitions/find-holders.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/find-holders.tool.js +26 -41
- package/dist/mcp-server/tools/definitions/find-holders.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.d.ts +28 -12
- package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.js +30 -44
- package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-filing.tool.d.ts +50 -14
- package/dist/mcp-server/tools/definitions/get-filing.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-filing.tool.js +193 -59
- package/dist/mcp-server/tools/definitions/get-filing.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-financials.tool.d.ts +14 -6
- package/dist/mcp-server/tools/definitions/get-financials.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-financials.tool.js +38 -41
- package/dist/mcp-server/tools/definitions/get-financials.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-fund-holdings.tool.d.ts +28 -12
- package/dist/mcp-server/tools/definitions/get-fund-holdings.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-fund-holdings.tool.js +22 -35
- package/dist/mcp-server/tools/definitions/get-fund-holdings.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-insider-transactions.tool.d.ts +28 -12
- package/dist/mcp-server/tools/definitions/get-insider-transactions.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-insider-transactions.tool.js +22 -31
- package/dist/mcp-server/tools/definitions/get-insider-transactions.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.d.ts +36 -20
- package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.js +22 -39
- package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-material-events.tool.d.ts +28 -12
- package/dist/mcp-server/tools/definitions/get-material-events.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-material-events.tool.js +23 -32
- package/dist/mcp-server/tools/definitions/get-material-events.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-snapshot.tool.d.ts +16 -7
- package/dist/mcp-server/tools/definitions/get-snapshot.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-snapshot.tool.js +24 -32
- package/dist/mcp-server/tools/definitions/get-snapshot.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/index.d.ts +232 -101
- package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/search-concepts.tool.js +3 -3
- package/dist/mcp-server/tools/definitions/search-concepts.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/search-filings.tool.d.ts +46 -20
- package/dist/mcp-server/tools/definitions/search-filings.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/search-filings.tool.js +126 -68
- package/dist/mcp-server/tools/definitions/search-filings.tool.js.map +1 -1
- package/dist/mcp-server/tools/resolved-as.d.ts +10 -0
- package/dist/mcp-server/tools/resolved-as.d.ts.map +1 -0
- package/dist/mcp-server/tools/resolved-as.js +13 -0
- package/dist/mcp-server/tools/resolved-as.js.map +1 -0
- package/dist/mcp-server/tools/sec-upstream-errors.d.ts +44 -0
- package/dist/mcp-server/tools/sec-upstream-errors.d.ts.map +1 -0
- package/dist/mcp-server/tools/sec-upstream-errors.js +48 -0
- package/dist/mcp-server/tools/sec-upstream-errors.js.map +1 -0
- package/dist/services/canvas-bridge/canvas-bridge.d.ts +98 -45
- package/dist/services/canvas-bridge/canvas-bridge.d.ts.map +1 -1
- package/dist/services/canvas-bridge/canvas-bridge.js +137 -126
- package/dist/services/canvas-bridge/canvas-bridge.js.map +1 -1
- package/dist/services/canvas-bridge/sql-gate-extras.d.ts +4 -17
- package/dist/services/canvas-bridge/sql-gate-extras.d.ts.map +1 -1
- package/dist/services/canvas-bridge/sql-gate-extras.js +4 -22
- package/dist/services/canvas-bridge/sql-gate-extras.js.map +1 -1
- package/dist/services/edgar/concept-map.d.ts +10 -6
- package/dist/services/edgar/concept-map.d.ts.map +1 -1
- package/dist/services/edgar/concept-map.js +90 -22
- package/dist/services/edgar/concept-map.js.map +1 -1
- package/dist/services/edgar/data/former-tickers.json +24159 -0
- package/dist/services/edgar/edgar-api-service.d.ts +250 -62
- package/dist/services/edgar/edgar-api-service.d.ts.map +1 -1
- package/dist/services/edgar/edgar-api-service.js +808 -189
- package/dist/services/edgar/edgar-api-service.js.map +1 -1
- package/dist/services/edgar/filing-to-text.d.ts +71 -2
- package/dist/services/edgar/filing-to-text.d.ts.map +1 -1
- package/dist/services/edgar/filing-to-text.js +533 -5
- package/dist/services/edgar/filing-to-text.js.map +1 -1
- package/dist/services/edgar/former-tickers.d.ts +47 -0
- package/dist/services/edgar/former-tickers.d.ts.map +1 -0
- package/dist/services/edgar/former-tickers.js +77 -0
- package/dist/services/edgar/former-tickers.js.map +1 -0
- package/dist/services/edgar/listing-codes.d.ts +47 -0
- package/dist/services/edgar/listing-codes.d.ts.map +1 -0
- package/dist/services/edgar/listing-codes.js +110 -0
- package/dist/services/edgar/listing-codes.js.map +1 -0
- package/dist/services/edgar/mirror/edgar-mirror.d.ts +11 -1
- package/dist/services/edgar/mirror/edgar-mirror.d.ts.map +1 -1
- package/dist/services/edgar/mirror/edgar-mirror.js +19 -1
- package/dist/services/edgar/mirror/edgar-mirror.js.map +1 -1
- package/dist/services/edgar/mirror/tickers-sync.d.ts.map +1 -1
- package/dist/services/edgar/mirror/tickers-sync.js +1 -3
- package/dist/services/edgar/mirror/tickers-sync.js.map +1 -1
- package/dist/services/edgar/mirror/types.d.ts +3 -1
- package/dist/services/edgar/mirror/types.d.ts.map +1 -1
- package/dist/services/edgar/mirror/types.js +3 -1
- package/dist/services/edgar/mirror/types.js.map +1 -1
- package/dist/services/edgar/trigram-similarity.d.ts +5 -3
- package/dist/services/edgar/trigram-similarity.d.ts.map +1 -1
- package/dist/services/edgar/trigram-similarity.js +18 -17
- package/dist/services/edgar/trigram-similarity.js.map +1 -1
- package/dist/services/edgar/types.d.ts +20 -7
- package/dist/services/edgar/types.d.ts.map +1 -1
- package/package.json +6 -5
- package/server.json +3 -3
- package/skills/secedgar-guide/SKILL.md +3 -3
- package/dist/mcp-server/tools/escape-inline.d.ts +0 -35
- package/dist/mcp-server/tools/escape-inline.d.ts.map +0 -1
- package/dist/mcp-server/tools/escape-inline.js +0 -51
- package/dist/mcp-server/tools/escape-inline.js.map +0 -1
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAmB3E;;;;GAIG;AACH,MAAM,WAAW,qBAAsB,SAAQ,iBAAiB;IAC9D;;;OAGG;IACH,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAmB3E;;;;GAIG;AACH,MAAM,WAAW,qBAAsB,SAAQ,iBAAiB;IAC9D;;;OAGG;IACH,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBA0BlE"}
|
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
* @module mcp-server/tools/definitions/search-concepts
|
|
7
7
|
*/
|
|
8
8
|
import { tool, z } from '@cyanheads/mcp-ts-core';
|
|
9
|
-
import {
|
|
9
|
+
import { escapeMarkdownInline } from '@cyanheads/mcp-ts-core/utils';
|
|
10
10
|
import { searchConcepts } from '../../../services/edgar/concept-map.js';
|
|
11
11
|
const GROUP_VALUES = [
|
|
12
12
|
'income_statement',
|
|
@@ -27,7 +27,7 @@ export const searchConceptsTool = tool('secedgar_search_concepts', {
|
|
|
27
27
|
search: z
|
|
28
28
|
.string()
|
|
29
29
|
.optional()
|
|
30
|
-
.describe('Case-insensitive substring matched against friendly name, label, and XBRL tags. Examples: "cash" finds cash and operating_cash_flow; "earnings" finds eps_basic and eps_diluted; "NetIncomeLoss" reverse-maps to net_income. Omit to list all concepts.'),
|
|
30
|
+
.describe('Case-insensitive substring matched against friendly name, aliases, label, and XBRL tags. Examples: "cash" finds cash and operating_cash_flow; "earnings" finds eps_basic and eps_diluted; "NetIncomeLoss" reverse-maps to net_income. Omit to list all concepts.'),
|
|
31
31
|
group: z
|
|
32
32
|
.enum(GROUP_VALUES)
|
|
33
33
|
.optional()
|
|
@@ -114,7 +114,7 @@ export const searchConceptsTool = tool('secedgar_search_concepts', {
|
|
|
114
114
|
filters.push(`taxonomy=${input.taxonomy}`);
|
|
115
115
|
const filterSuffix = filters.length ? ` with filters (${filters.join(', ')})` : '';
|
|
116
116
|
// The notice is authored Markdown, so the caller's search text is escaped.
|
|
117
|
-
ctx.enrich.notice(`No concepts matched "${input.search === undefined ? '(all)' :
|
|
117
|
+
ctx.enrich.notice(`No concepts matched "${input.search === undefined ? '(all)' : escapeMarkdownInline(input.search)}"${filterSuffix}. Try a broader search term, a different group, or call with no filters to see the full catalog.`);
|
|
118
118
|
}
|
|
119
119
|
return {
|
|
120
120
|
total: results.length,
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"search-concepts.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/search-concepts.tool.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,
|
|
1
|
+
{"version":3,"file":"search-concepts.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/search-concepts.tool.ts"],"names":[],"mappings":"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"}
|
|
@@ -83,6 +83,12 @@ export declare const searchFilingsTool: import("@cyanheads/mcp-ts-core").ToolDef
|
|
|
83
83
|
readonly when: "A cik: targeting token in the query is not a 1-10 digit number";
|
|
84
84
|
readonly recovery: "Pass a numeric CIK such as cik:320193 — find it with secedgar_company_search if unknown.";
|
|
85
85
|
readonly thrownBy: "service";
|
|
86
|
+
}, {
|
|
87
|
+
readonly reason: "unsupported_entity_scope";
|
|
88
|
+
readonly code: JsonRpcErrorCode.ValidationError;
|
|
89
|
+
readonly when: "A ticker: or cik: token in the query is led by - or a NOT term, or follows another entity token";
|
|
90
|
+
readonly recovery: "Keep one ticker: or cik: token as its own term with no - or NOT before it. To leave a company out, drop the token and skip the result rows whose cik is that company's.";
|
|
91
|
+
readonly thrownBy: "service";
|
|
86
92
|
}, {
|
|
87
93
|
readonly reason: "entity_not_found";
|
|
88
94
|
readonly code: JsonRpcErrorCode.NotFound;
|
|
@@ -106,26 +112,33 @@ export declare const searchFilingsTool: import("@cyanheads/mcp-ts-core").ToolDef
|
|
|
106
112
|
readonly recovery: "Use an offset of 9900 or less — a page there with limit 100 reaches EDGAR's 10,000-document cap — or narrow the search with a shorter filed_after/filed_before window, a forms filter, or more specific terms so fewer documents match.";
|
|
107
113
|
readonly retryable: false;
|
|
108
114
|
}, {
|
|
109
|
-
readonly reason:
|
|
115
|
+
readonly reason: 'rate_limited';
|
|
110
116
|
readonly code: JsonRpcErrorCode.RateLimited;
|
|
111
117
|
readonly when: "SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs";
|
|
112
|
-
readonly recovery:
|
|
118
|
+
readonly recovery: 'Wait the retryAfter seconds the error carries, then retry — SEC lifts the block only once requests stop for ten minutes.';
|
|
113
119
|
readonly retryable: true;
|
|
114
|
-
readonly thrownBy:
|
|
120
|
+
readonly thrownBy: 'service';
|
|
115
121
|
}, {
|
|
116
|
-
readonly reason:
|
|
122
|
+
readonly reason: 'sec_unreachable';
|
|
117
123
|
readonly code: JsonRpcErrorCode.ServiceUnavailable;
|
|
118
124
|
readonly when: "SEC EDGAR gave no complete, readable response — on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out) the connection failed, no response headers arrived within 15 seconds, or the body broke off or stalled for 15 seconds, each wait capped at what was left of that budget; a 200 body was not the JSON SEC serves; or earlier SEC failures had spent that budget, so the request was never sent";
|
|
119
|
-
readonly recovery:
|
|
125
|
+
readonly recovery: 'Retry the same call in a minute — SEC EDGAR did not deliver a complete, readable response, and nothing in the request needs to change.';
|
|
120
126
|
readonly retryable: true;
|
|
121
|
-
readonly thrownBy:
|
|
127
|
+
readonly thrownBy: 'service';
|
|
122
128
|
}, {
|
|
123
|
-
readonly reason:
|
|
129
|
+
readonly reason: 'sec_unavailable';
|
|
124
130
|
readonly code: JsonRpcErrorCode.ServiceUnavailable;
|
|
125
|
-
readonly when: "EDGAR
|
|
126
|
-
readonly recovery:
|
|
131
|
+
readonly when: "SEC EDGAR answered HTTP 500, 502, 503, or 504 on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out)";
|
|
132
|
+
readonly recovery: 'Retry the same call in a minute — SEC EDGAR failed on its side, and nothing in the request needs to change.';
|
|
127
133
|
readonly retryable: true;
|
|
128
|
-
readonly thrownBy:
|
|
134
|
+
readonly thrownBy: 'service';
|
|
135
|
+
}, {
|
|
136
|
+
readonly reason: 'efts_degraded_response';
|
|
137
|
+
readonly code: JsonRpcErrorCode.ServiceUnavailable;
|
|
138
|
+
readonly when: 'EDGAR full-text search answered without results — its search backend failed to run the search on every attempt made (a connection or timeout failure, retried like a request SEC never answered), refused the request (upstreamErrorType and upstreamErrorMessage carry its error, and the request is not retried), or sent a payload with no hit list';
|
|
139
|
+
readonly recovery: 'Retry the same call in a minute unless the error is marked not retryable; then change the request as upstreamErrorMessage indicates.';
|
|
140
|
+
readonly retryable: true;
|
|
141
|
+
readonly thrownBy: 'service';
|
|
129
142
|
}], {
|
|
130
143
|
readonly effectiveQuery: z.ZodString;
|
|
131
144
|
readonly notice: z.ZodOptional<z.ZodString>;
|
|
@@ -202,6 +215,12 @@ export declare function createSearchFilingsTool(options: LimitClampOptions): imp
|
|
|
202
215
|
readonly when: "A cik: targeting token in the query is not a 1-10 digit number";
|
|
203
216
|
readonly recovery: "Pass a numeric CIK such as cik:320193 — find it with secedgar_company_search if unknown.";
|
|
204
217
|
readonly thrownBy: "service";
|
|
218
|
+
}, {
|
|
219
|
+
readonly reason: "unsupported_entity_scope";
|
|
220
|
+
readonly code: JsonRpcErrorCode.ValidationError;
|
|
221
|
+
readonly when: "A ticker: or cik: token in the query is led by - or a NOT term, or follows another entity token";
|
|
222
|
+
readonly recovery: "Keep one ticker: or cik: token as its own term with no - or NOT before it. To leave a company out, drop the token and skip the result rows whose cik is that company's.";
|
|
223
|
+
readonly thrownBy: "service";
|
|
205
224
|
}, {
|
|
206
225
|
readonly reason: "entity_not_found";
|
|
207
226
|
readonly code: JsonRpcErrorCode.NotFound;
|
|
@@ -225,26 +244,33 @@ export declare function createSearchFilingsTool(options: LimitClampOptions): imp
|
|
|
225
244
|
readonly recovery: "Use an offset of 9900 or less — a page there with limit 100 reaches EDGAR's 10,000-document cap — or narrow the search with a shorter filed_after/filed_before window, a forms filter, or more specific terms so fewer documents match.";
|
|
226
245
|
readonly retryable: false;
|
|
227
246
|
}, {
|
|
228
|
-
readonly reason:
|
|
247
|
+
readonly reason: 'rate_limited';
|
|
229
248
|
readonly code: JsonRpcErrorCode.RateLimited;
|
|
230
249
|
readonly when: "SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs";
|
|
231
|
-
readonly recovery:
|
|
250
|
+
readonly recovery: 'Wait the retryAfter seconds the error carries, then retry — SEC lifts the block only once requests stop for ten minutes.';
|
|
232
251
|
readonly retryable: true;
|
|
233
|
-
readonly thrownBy:
|
|
252
|
+
readonly thrownBy: 'service';
|
|
234
253
|
}, {
|
|
235
|
-
readonly reason:
|
|
254
|
+
readonly reason: 'sec_unreachable';
|
|
236
255
|
readonly code: JsonRpcErrorCode.ServiceUnavailable;
|
|
237
256
|
readonly when: "SEC EDGAR gave no complete, readable response — on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out) the connection failed, no response headers arrived within 15 seconds, or the body broke off or stalled for 15 seconds, each wait capped at what was left of that budget; a 200 body was not the JSON SEC serves; or earlier SEC failures had spent that budget, so the request was never sent";
|
|
238
|
-
readonly recovery:
|
|
257
|
+
readonly recovery: 'Retry the same call in a minute — SEC EDGAR did not deliver a complete, readable response, and nothing in the request needs to change.';
|
|
239
258
|
readonly retryable: true;
|
|
240
|
-
readonly thrownBy:
|
|
259
|
+
readonly thrownBy: 'service';
|
|
241
260
|
}, {
|
|
242
|
-
readonly reason:
|
|
261
|
+
readonly reason: 'sec_unavailable';
|
|
243
262
|
readonly code: JsonRpcErrorCode.ServiceUnavailable;
|
|
244
|
-
readonly when: "EDGAR
|
|
245
|
-
readonly recovery:
|
|
263
|
+
readonly when: "SEC EDGAR answered HTTP 500, 502, 503, or 504 on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out)";
|
|
264
|
+
readonly recovery: 'Retry the same call in a minute — SEC EDGAR failed on its side, and nothing in the request needs to change.';
|
|
246
265
|
readonly retryable: true;
|
|
247
|
-
readonly thrownBy:
|
|
266
|
+
readonly thrownBy: 'service';
|
|
267
|
+
}, {
|
|
268
|
+
readonly reason: 'efts_degraded_response';
|
|
269
|
+
readonly code: JsonRpcErrorCode.ServiceUnavailable;
|
|
270
|
+
readonly when: 'EDGAR full-text search answered without results — its search backend failed to run the search on every attempt made (a connection or timeout failure, retried like a request SEC never answered), refused the request (upstreamErrorType and upstreamErrorMessage carry its error, and the request is not retried), or sent a payload with no hit list';
|
|
271
|
+
readonly recovery: 'Retry the same call in a minute unless the error is marked not retryable; then change the request as upstreamErrorMessage indicates.';
|
|
272
|
+
readonly retryable: true;
|
|
273
|
+
readonly thrownBy: 'service';
|
|
248
274
|
}], {
|
|
249
275
|
readonly effectiveQuery: z.ZodString;
|
|
250
276
|
readonly notice: z.ZodOptional<z.ZodString>;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"search-filings.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/search-filings.tool.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAsB,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EACL,gBAAgB,EAIjB,MAAM,+BAA+B,CAAC;
|
|
1
|
+
{"version":3,"file":"search-filings.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/search-filings.tool.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAsB,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EACL,gBAAgB,EAIjB,MAAM,+BAA+B,CAAC;AAKvC,OAAO,EACL,KAAK,iBAAiB,EAGvB,MAAM,mCAAmC,CAAC;AAmC3C;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,OAAQ,CAAC;AA00B1C,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgsB5B,CAAC;AAEH,+FAA+F;AAC/F,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAEjE"}
|
|
@@ -7,14 +7,17 @@
|
|
|
7
7
|
*/
|
|
8
8
|
import { tool, z } from '@cyanheads/mcp-ts-core';
|
|
9
9
|
import { JsonRpcErrorCode, McpError, notFound, validationError, } from '@cyanheads/mcp-ts-core/errors';
|
|
10
|
+
import { escapeMarkdownInline } from '@cyanheads/mcp-ts-core/utils';
|
|
10
11
|
import { ambiguousMatches } from '../ambiguous-matches.js';
|
|
11
|
-
import {
|
|
12
|
+
import { datasetSchema } from '../dataset-schema.js';
|
|
12
13
|
import { normalizeFormFilter } from '../form-filter.js';
|
|
13
14
|
import { limitClamp, withLimitClamps, } from '../limit-clamp.js';
|
|
15
|
+
import { EFTS_DEGRADED_ERROR, SEC_UPSTREAM_ERRORS, } from '../sec-upstream-errors.js';
|
|
14
16
|
import { dataframeGuidance, getCanvasBridge, toDatasetField, } from '../../../services/canvas-bridge/canvas-bridge.js';
|
|
15
17
|
import { CallScope } from '../../../services/edgar/call-scope.js';
|
|
16
18
|
import { cleanDisplayName, getEdgarApiService, quartersInRange, } from '../../../services/edgar/edgar-api-service.js';
|
|
17
19
|
import { filingToExtract } from '../../../services/edgar/filing-to-text.js';
|
|
20
|
+
import { nonUsListingNote } from '../../../services/edgar/listing-codes.js';
|
|
18
21
|
import { SubmissionsArchiveWalk } from '../../../services/edgar/submissions-archive.js';
|
|
19
22
|
/**
|
|
20
23
|
* The EFTS full-text index only covers filings from this date onward, even
|
|
@@ -192,9 +195,54 @@ function extractTicker(displayName) {
|
|
|
192
195
|
const first = match[1].split(',')[0]?.trim();
|
|
193
196
|
return first ? first : null;
|
|
194
197
|
}
|
|
195
|
-
/**
|
|
196
|
-
|
|
197
|
-
|
|
198
|
+
/** A word boundary, then `ticker:` or `cik:` and a value; `\S+` ends at whitespace, never backtracks. */
|
|
199
|
+
const ENTITY_TOKEN_RE = /\b(ticker|cik):(\S+)/gi;
|
|
200
|
+
/**
|
|
201
|
+
* Every entity token in the query, in order. A `-` or `+` touching the token is part of it, and
|
|
202
|
+
* so is an uppercase `NOT` term before it (EDGAR full-text search reads `NOT` as exclusion);
|
|
203
|
+
* the token is found inside a quoted phrase too. One forward scan over the query, plus a walk
|
|
204
|
+
* back over the whitespace before each token, so linear in the query's length.
|
|
205
|
+
*/
|
|
206
|
+
function entityTokens(query) {
|
|
207
|
+
const tokens = [];
|
|
208
|
+
for (const match of query.matchAll(ENTITY_TOKEN_RE)) {
|
|
209
|
+
const at = match.index;
|
|
210
|
+
const end = at + match[0].length;
|
|
211
|
+
const kind = match[1]?.toLowerCase() === 'cik' ? 'cik' : 'ticker';
|
|
212
|
+
const value = match[2] ?? '';
|
|
213
|
+
const sign = query[at - 1];
|
|
214
|
+
if (sign === '-') {
|
|
215
|
+
tokens.push({
|
|
216
|
+
kind,
|
|
217
|
+
value,
|
|
218
|
+
negated: true,
|
|
219
|
+
text: query.slice(at - 1, end),
|
|
220
|
+
start: at - 1,
|
|
221
|
+
end,
|
|
222
|
+
});
|
|
223
|
+
continue;
|
|
224
|
+
}
|
|
225
|
+
// A `+` is part of the token; a NOT term before it still negates it.
|
|
226
|
+
const lead = sign === '+' ? at - 1 : at;
|
|
227
|
+
let gap = lead;
|
|
228
|
+
while (gap > 0 && /\s/.test(query[gap - 1] ?? ''))
|
|
229
|
+
gap--;
|
|
230
|
+
const notStart = gap - 3;
|
|
231
|
+
const negated = gap < lead &&
|
|
232
|
+
notStart >= 0 &&
|
|
233
|
+
query.slice(notStart, gap) === 'NOT' &&
|
|
234
|
+
(notStart === 0 || /[\s(]/.test(query[notStart - 1] ?? ''));
|
|
235
|
+
const term = query.slice(lead, end);
|
|
236
|
+
tokens.push({
|
|
237
|
+
kind,
|
|
238
|
+
value,
|
|
239
|
+
negated,
|
|
240
|
+
text: negated ? `NOT ${term}` : term,
|
|
241
|
+
start: negated ? notStart : lead,
|
|
242
|
+
end,
|
|
243
|
+
});
|
|
244
|
+
}
|
|
245
|
+
return tokens;
|
|
198
246
|
}
|
|
199
247
|
/**
|
|
200
248
|
* Extract entity targeting (cik: or ticker:) from a query string and resolve it
|
|
@@ -208,15 +256,45 @@ function stripToken(query, token) {
|
|
|
208
256
|
* a silently-broadened search misleads, and a stripped token can leave EFTS
|
|
209
257
|
* with a blank query it rejects (#61). A `ticker:` token naming several companies
|
|
210
258
|
* fails the same way, listing them, rather than scoping to the first (#223).
|
|
259
|
+
*
|
|
260
|
+
* One bare token scopes, a `+` before it removed with it. A token led by `-` or `NOT`, or a
|
|
261
|
+
* second token, fails `unsupported_entity_scope` before any request: EDGAR's `ciks` param only
|
|
262
|
+
* scopes in, full-text search ignores a `-ticker:` term, and a second token sent as text matches
|
|
263
|
+
* nothing (#243). A token inside a quoted phrase scopes like a bare one.
|
|
264
|
+
*
|
|
265
|
+
* `reading` is how `resolveCik` read a ticker spelling EDGAR does not list (#235), for the
|
|
266
|
+
* caller to name beside the CIK in `effectiveQuery`; every page of a search resolves the token
|
|
267
|
+
* again, so it reads the same each time.
|
|
211
268
|
*/
|
|
212
269
|
async function resolveEntityTargeting(query, ctx, scope) {
|
|
213
|
-
const
|
|
214
|
-
|
|
215
|
-
|
|
270
|
+
const tokens = entityTokens(query);
|
|
271
|
+
const negated = tokens.find((token) => token.negated);
|
|
272
|
+
if (negated) {
|
|
273
|
+
throw validationError(`Entity targeting token '${negated.text}' is negated; an entity token scopes a search to a company and cannot exclude one.`, {
|
|
274
|
+
reason: 'unsupported_entity_scope',
|
|
275
|
+
recovery: {
|
|
276
|
+
hint: "To leave a company out, drop the token and skip the result rows whose cik is that company's.",
|
|
277
|
+
},
|
|
278
|
+
});
|
|
279
|
+
}
|
|
280
|
+
if (tokens.length > 1) {
|
|
281
|
+
throw validationError(`The query holds ${tokens.length} entity targeting tokens (${tokens.map((t) => `'${t.text}'`).join(', ')}); a search is scoped to one company.`, {
|
|
282
|
+
reason: 'unsupported_entity_scope',
|
|
283
|
+
recovery: { hint: 'Keep one ticker: or cik: token and run one search per company.' },
|
|
284
|
+
});
|
|
285
|
+
}
|
|
286
|
+
const [token] = tokens;
|
|
287
|
+
if (!token)
|
|
288
|
+
return { query };
|
|
289
|
+
const rest = `${query.slice(0, token.start)}${query.slice(token.end)}`
|
|
290
|
+
.replace(/\s+/g, ' ')
|
|
291
|
+
.trim();
|
|
292
|
+
if (token.kind === 'ticker') {
|
|
293
|
+
const resolved = await getEdgarApiService().resolveCik(token.value, scope);
|
|
216
294
|
if (Array.isArray(resolved) && resolved.length > 1) {
|
|
217
295
|
// The token is `\S+`, so a fuller name with spaces cannot be retried through it.
|
|
218
296
|
const { list, showing, data } = ambiguousMatches(resolved, { singleToken: true });
|
|
219
|
-
throw validationError(`Entity targeting token 'ticker:${
|
|
297
|
+
throw validationError(`Entity targeting token 'ticker:${token.value}' matches multiple companies: ${list}. Retry with ticker: or cik: and one of these tickers or 10-digit CIKs.${showing}`, {
|
|
220
298
|
reason: 'ambiguous_company',
|
|
221
299
|
...ctx.recoveryFor('ambiguous_company'),
|
|
222
300
|
...data,
|
|
@@ -224,18 +302,15 @@ async function resolveEntityTargeting(query, ctx, scope) {
|
|
|
224
302
|
}
|
|
225
303
|
const match = Array.isArray(resolved) ? resolved[0] : resolved;
|
|
226
304
|
if (!match?.cik) {
|
|
227
|
-
|
|
305
|
+
const note = nonUsListingNote(token.value);
|
|
306
|
+
throw validationError(`Entity targeting token 'ticker:${token.value}' does not resolve to a known company.${note ? ` ${note}` : ''}`, { reason: 'unresolved_ticker', ...ctx.recoveryFor('unresolved_ticker') });
|
|
228
307
|
}
|
|
229
|
-
return { query:
|
|
308
|
+
return { query: rest, entityCik: match.cik, reading: match.reading };
|
|
230
309
|
}
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
if (!/^\d{1,10}$/.test(cikMatch[1])) {
|
|
234
|
-
throw validationError(`Entity targeting token 'cik:${cikMatch[1]}' is not a valid CIK — expected 1-10 digits.`, { reason: 'invalid_cik', ...ctx.recoveryFor('invalid_cik') });
|
|
235
|
-
}
|
|
236
|
-
return { query: stripToken(query, cikMatch[0]), entityCik: cikMatch[1].padStart(10, '0') };
|
|
310
|
+
if (!/^\d{1,10}$/.test(token.value)) {
|
|
311
|
+
throw validationError(`Entity targeting token 'cik:${token.value}' is not a valid CIK — expected 1-10 digits.`, { reason: 'invalid_cik', ...ctx.recoveryFor('invalid_cik') });
|
|
237
312
|
}
|
|
238
|
-
return { query };
|
|
313
|
+
return { query: rest, entityCik: token.value.padStart(10, '0') };
|
|
239
314
|
}
|
|
240
315
|
/**
|
|
241
316
|
* Compile one query term to a matcher over converted filing text. Bare words and
|
|
@@ -593,7 +668,7 @@ export const searchFilingsTool = tool('secedgar_search_filings', {
|
|
|
593
668
|
enrichment: {
|
|
594
669
|
effectiveQuery: z
|
|
595
670
|
.string()
|
|
596
|
-
.describe('The query as executed: "(entity scope: CIK …)" for a ticker:/cik: token, "(browse: forms …)" for a forms
|
|
671
|
+
.describe('The query as executed: "(entity scope: CIK …)" for a ticker:/cik: token, with any reading of the ticker; "(browse: forms …)" for a forms browse; a pre-2001 range\'s archive route, dates, and quarters read if capped; "(filed <after> to <before>)" if given one bound.'),
|
|
597
672
|
notice: z
|
|
598
673
|
.string()
|
|
599
674
|
.optional()
|
|
@@ -627,6 +702,13 @@ export const searchFilingsTool = tool('secedgar_search_filings', {
|
|
|
627
702
|
recovery: 'Pass a numeric CIK such as cik:320193 — find it with secedgar_company_search if unknown.',
|
|
628
703
|
thrownBy: 'service',
|
|
629
704
|
},
|
|
705
|
+
{
|
|
706
|
+
reason: 'unsupported_entity_scope',
|
|
707
|
+
code: JsonRpcErrorCode.ValidationError,
|
|
708
|
+
when: 'A ticker: or cik: token in the query is led by - or a NOT term, or follows another entity token',
|
|
709
|
+
recovery: "Keep one ticker: or cik: token as its own term with no - or NOT before it. To leave a company out, drop the token and skip the result rows whose cik is that company's.",
|
|
710
|
+
thrownBy: 'service',
|
|
711
|
+
},
|
|
630
712
|
{
|
|
631
713
|
reason: 'entity_not_found',
|
|
632
714
|
code: JsonRpcErrorCode.NotFound,
|
|
@@ -653,30 +735,8 @@ export const searchFilingsTool = tool('secedgar_search_filings', {
|
|
|
653
735
|
recovery: `Use an offset of ${MAX_RELEVANCE_OFFSET} or less — a page there with limit 100 reaches EDGAR's 10,000-document cap — or narrow the search with a shorter filed_after/filed_before window, a forms filter, or more specific terms so fewer documents match.`,
|
|
654
736
|
retryable: false,
|
|
655
737
|
},
|
|
656
|
-
|
|
657
|
-
|
|
658
|
-
code: JsonRpcErrorCode.RateLimited,
|
|
659
|
-
when: "SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs",
|
|
660
|
-
recovery: 'Wait the retryAfter seconds the error carries, then retry — SEC lifts the block only once requests stop for ten minutes.',
|
|
661
|
-
retryable: true,
|
|
662
|
-
thrownBy: 'service',
|
|
663
|
-
},
|
|
664
|
-
{
|
|
665
|
-
reason: 'sec_unreachable',
|
|
666
|
-
code: JsonRpcErrorCode.ServiceUnavailable,
|
|
667
|
-
when: "SEC EDGAR gave no complete, readable response — on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out) the connection failed, no response headers arrived within 15 seconds, or the body broke off or stalled for 15 seconds, each wait capped at what was left of that budget; a 200 body was not the JSON SEC serves; or earlier SEC failures had spent that budget, so the request was never sent",
|
|
668
|
-
recovery: 'Retry the same call in a minute — SEC EDGAR did not deliver a complete, readable response, and nothing in the request needs to change.',
|
|
669
|
-
retryable: true,
|
|
670
|
-
thrownBy: 'service',
|
|
671
|
-
},
|
|
672
|
-
{
|
|
673
|
-
reason: 'efts_degraded_response',
|
|
674
|
-
code: JsonRpcErrorCode.ServiceUnavailable,
|
|
675
|
-
when: 'EDGAR full-text search answered without results — its search backend failed to run the search on every attempt made (a connection or timeout failure, retried like a request SEC never answered), refused the request (upstreamErrorType and upstreamErrorMessage carry its error, and the request is not retried), or sent a payload with no hit list',
|
|
676
|
-
recovery: 'Retry the same call in a minute unless the error is marked not retryable; then change the request as upstreamErrorMessage indicates.',
|
|
677
|
-
retryable: true,
|
|
678
|
-
thrownBy: 'service',
|
|
679
|
-
},
|
|
738
|
+
...SEC_UPSTREAM_ERRORS,
|
|
739
|
+
EFTS_DEGRADED_ERROR,
|
|
680
740
|
],
|
|
681
741
|
input: z.object({
|
|
682
742
|
query: z
|
|
@@ -686,10 +746,10 @@ export const searchFilingsTool = tool('secedgar_search_filings', {
|
|
|
686
746
|
.string()
|
|
687
747
|
.trim()
|
|
688
748
|
.min(1, 'Query cannot be blank')
|
|
689
|
-
.describe('Full-text search query. Supports: exact phrases ("material weakness"), boolean operators (revenue OR income), exclusion (-preliminary), wildcard suffix (account*), entity targeting (ticker:AAPL or cik:320193
|
|
749
|
+
.describe('Full-text search query. Supports: exact phrases ("material weakness"), boolean operators (revenue OR income), exclusion (-preliminary), wildcard suffix (account*), entity targeting (one ticker:AAPL or cik:320193 term, never led by - or NOT). Terms are AND\'d by default.'),
|
|
690
750
|
])
|
|
691
751
|
.optional()
|
|
692
|
-
.describe('Full-text search query. Optional — omit (or pass "") to browse by form type and/or entity instead, e.g. every S-1 in a date window, or a company\'s filings via ticker:/cik:. A date range alone is not a valid search; pair it with forms or entity targeting. The EFTS index that serves free text starts at 2001-01-01; a date range reaching earlier needs ticker:/cik: entity scope, which lets the tool read that entity\'s filings and match the terms locally (bounded to 50 documents, a few seconds at SEC\'s request rate), or drop the text terms and browse by form type (forms) and date. When present, supports exact phrases ("material weakness"), boolean operators (revenue OR income), exclusion (-preliminary), wildcard suffix (account*), and entity targeting (ticker:AAPL or cik:320193 in the query); terms are AND\'d by default. A multi-class share ticker resolves in either form — ticker:BRK-B and ticker:BRK.B scope to the same issuer. The pre-2001 local scan honors the same phrase / OR / exclusion / wildcard syntax.'),
|
|
752
|
+
.describe('Full-text search query. Optional — omit (or pass "") to browse by form type and/or entity instead, e.g. every S-1 in a date window, or a company\'s filings via ticker:/cik:. A date range alone is not a valid search; pair it with forms or entity targeting. The EFTS index that serves free text starts at 2001-01-01; a date range reaching earlier needs ticker:/cik: entity scope, which lets the tool read that entity\'s filings and match the terms locally (bounded to 50 documents, a few seconds at SEC\'s request rate), or drop the text terms and browse by form type (forms) and date. When present, supports exact phrases ("material weakness"), boolean operators (revenue OR income), exclusion (-preliminary), wildcard suffix (account*), and entity targeting (ticker:AAPL or cik:320193 in the query); terms are AND\'d by default. Entity targeting takes one ticker: or cik: term, never led by - or NOT: it scopes the search to one company and cannot exclude one. A multi-class share ticker resolves in either form — ticker:BRK-B and ticker:BRK.B scope to the same issuer — and an uppercase ticker also resolves as market-data feeds write it: venue-coded (UEC.N), a preferred class run together (CFGPH), or a class root (GLOP); a former ticker scopes to the company that last held it (ticker:AMRK, Gold.com). The pre-2001 local scan honors the same phrase / OR / exclusion / wildcard syntax.'),
|
|
693
753
|
forms: z
|
|
694
754
|
.array(z.string())
|
|
695
755
|
.optional()
|
|
@@ -743,11 +803,11 @@ export const searchFilingsTool = tool('secedgar_search_filings', {
|
|
|
743
803
|
.describe("Matching filings, one per accession; can exceed the rows returned. A search with terms counts the filings among the full-text documents fetched (100 per request): a lower bound unless total_is_exact. A forms- or entity-only browse from 2001 on gives EDGAR's own count; earlier ranges count rows read."),
|
|
744
804
|
total_is_exact: z
|
|
745
805
|
.boolean()
|
|
746
|
-
.describe("False when total is a lower bound: a search
|
|
806
|
+
.describe("False when total is a lower bound: a term search's 100-document window missed matches (or a relevance page past offset 0), EDGAR's 10,000 cap was hit, or a pre-2001 archive or text scan hit its cap."),
|
|
747
807
|
total_documents: z
|
|
748
808
|
.number()
|
|
749
809
|
.optional()
|
|
750
|
-
.describe("EDGAR's count of matching full-text documents, capped at 10,000
|
|
810
|
+
.describe("EDGAR's count of matching full-text documents, capped at 10,000; a search counts a filing once per matching document, a browse one document per filing. Absent on pure pre-2001 archive paths."),
|
|
751
811
|
results: z
|
|
752
812
|
.array(z
|
|
753
813
|
.object({
|
|
@@ -805,7 +865,7 @@ export const searchFilingsTool = tool('secedgar_search_filings', {
|
|
|
805
865
|
form_distribution: z
|
|
806
866
|
.record(z.string(), z.number())
|
|
807
867
|
.optional()
|
|
808
|
-
.describe('Filings in hand by form: every row assembled (what a dataframe holds), not only the page shown. Sums to total when every
|
|
868
|
+
.describe('Filings in hand by form: every row assembled (what a dataframe holds), not only the page shown. Sums to total when every match is in hand with a form.'),
|
|
809
869
|
scan: z
|
|
810
870
|
.object({
|
|
811
871
|
candidates: z.number().describe('Filings the form and date pre-filter selected.'),
|
|
@@ -816,14 +876,9 @@ export const searchFilingsTool = tool('secedgar_search_filings', {
|
|
|
816
876
|
.describe('True when candidates exceeded the 50-document cap; unread filings may match, so narrow forms or dates.'),
|
|
817
877
|
})
|
|
818
878
|
.optional()
|
|
819
|
-
.describe("Pre-2001 entity-scoped free-text path only. Each candidate's whole accession .txt is read, so a match may sit in an exhibit
|
|
820
|
-
dataset:
|
|
821
|
-
.
|
|
822
|
-
name: z
|
|
823
|
-
.string()
|
|
824
|
-
.describe('Dataframe handle (df_XXXXX_XXXXX) for secedgar_dataframe_describe, then secedgar_dataframe_query.'),
|
|
825
|
-
row_count: z.number().describe('Rows materialized in the dataframe.'),
|
|
826
|
-
expires_at: z.string().describe('ISO 8601 expiry timestamp.'),
|
|
879
|
+
.describe("Pre-2001 entity-scoped free-text path only. Each candidate's whole accession .txt is read, so a match may sit in an exhibit, not the requested form's body."),
|
|
880
|
+
dataset: datasetSchema
|
|
881
|
+
.extend({
|
|
827
882
|
truncated: z
|
|
828
883
|
.boolean()
|
|
829
884
|
.describe('True when matches exist beyond the staged rows: the full-text window was exceeded, or an archive scan hit its cap.'),
|
|
@@ -850,7 +905,10 @@ export const searchFilingsTool = tool('secedgar_search_filings', {
|
|
|
850
905
|
// server-side ciks param. Throws typed validation errors on bad tokens (#61).
|
|
851
906
|
// Default to '' so a browse request (undefined query) resolves cleanly.
|
|
852
907
|
const scope = new CallScope(ctx.signal);
|
|
853
|
-
const { query, entityCik } = await resolveEntityTargeting(input.query ?? '', ctx, scope);
|
|
908
|
+
const { query, entityCik, reading } = await resolveEntityTargeting(input.query ?? '', ctx, scope);
|
|
909
|
+
// The scope as effectiveQuery names it on every path: the CIK, and how a ticker spelling
|
|
910
|
+
// EDGAR does not list was read (#235).
|
|
911
|
+
const entityNote = entityCik && `CIK ${entityCik}${reading ? `, ${reading}` : ''}`;
|
|
854
912
|
const api = getEdgarApiService();
|
|
855
913
|
// Date-based routing at the EFTS full-text floor (2001-01-01). EFTS only
|
|
856
914
|
// indexes filings from 2001, so a range reaching earlier is served from the
|
|
@@ -917,7 +975,7 @@ export const searchFilingsTool = tool('secedgar_search_filings', {
|
|
|
917
975
|
const archiveIncomplete = archive.scanTruncated || (scan?.capped ?? false);
|
|
918
976
|
const eftsWindowIncomplete = efts !== undefined && !efts.totalIsExact;
|
|
919
977
|
const formsNote = forms ? `, forms ${forms.join(', ')}` : '';
|
|
920
|
-
const scopeNote =
|
|
978
|
+
const scopeNote = entityNote || 'full-index browse';
|
|
921
979
|
const archiveSource = entityCik
|
|
922
980
|
? 'the entity submissions history'
|
|
923
981
|
: 'the quarterly EDGAR full-index';
|
|
@@ -964,9 +1022,9 @@ export const searchFilingsTool = tool('secedgar_search_filings', {
|
|
|
964
1022
|
: `Served from ${archiveSource} — full-text search covers 2001-present only.${quarterNote}${scanNote}`,
|
|
965
1023
|
zeroHitCriteria: [
|
|
966
1024
|
// The notice is authored Markdown, so the caller's text inside it is escaped.
|
|
967
|
-
...(hasFreeText ? [`"${
|
|
1025
|
+
...(hasFreeText ? [`"${escapeMarkdownInline(query)}"`] : []),
|
|
968
1026
|
...(entityCik ? [`CIK ${entityCik}`] : []),
|
|
969
|
-
...(forms ? [`forms [${
|
|
1027
|
+
...(forms ? [`forms [${escapeMarkdownInline(forms.join(', '))}]`] : []),
|
|
970
1028
|
`dates ${startDate} to ${endDate}`,
|
|
971
1029
|
].join(', '),
|
|
972
1030
|
scan,
|
|
@@ -1053,8 +1111,8 @@ export const searchFilingsTool = tool('secedgar_search_filings', {
|
|
|
1053
1111
|
resultCount: results.length,
|
|
1054
1112
|
datasetName: dataset?.name,
|
|
1055
1113
|
});
|
|
1056
|
-
const searched =
|
|
1057
|
-
? `${query ? `${query} ` : ''}(entity scope:
|
|
1114
|
+
const searched = entityNote
|
|
1115
|
+
? `${query ? `${query} ` : ''}(entity scope: ${entityNote})`
|
|
1058
1116
|
: query || (forms ? `(browse: forms ${forms.join(', ')})` : '');
|
|
1059
1117
|
// A window the caller spelled out is already in their arguments; a filled one is not.
|
|
1060
1118
|
const effectiveQuery = dates?.filled
|
|
@@ -1067,11 +1125,11 @@ export const searchFilingsTool = tool('secedgar_search_filings', {
|
|
|
1067
1125
|
// empty quoted query. The notice is authored Markdown, so the query and forms are escaped.
|
|
1068
1126
|
const criteria = [];
|
|
1069
1127
|
if (query)
|
|
1070
|
-
criteria.push(`"${
|
|
1128
|
+
criteria.push(`"${escapeMarkdownInline(query)}"`);
|
|
1071
1129
|
if (entityCik)
|
|
1072
1130
|
criteria.push(`entity CIK ${entityCik}`);
|
|
1073
1131
|
if (forms)
|
|
1074
|
-
criteria.push(`forms [${
|
|
1132
|
+
criteria.push(`forms [${escapeMarkdownInline(forms.join(', '))}]`);
|
|
1075
1133
|
if (dates)
|
|
1076
1134
|
criteria.push(`dates ${dates.startDate} to ${dates.endDate}`);
|
|
1077
1135
|
const criteriaText = criteria.length > 0 ? criteria.join(', ') : 'the given criteria';
|
|
@@ -1146,20 +1204,20 @@ export const searchFilingsTool = tool('secedgar_search_filings', {
|
|
|
1146
1204
|
// Names, descriptions, filenames, and locations are SEC text, escaped to read back as written.
|
|
1147
1205
|
for (const r of result.results) {
|
|
1148
1206
|
const period = r.period_ending ? ` (period: ${r.period_ending})` : '';
|
|
1149
|
-
const desc = r.file_description ? ` — ${
|
|
1207
|
+
const desc = r.file_description ? ` — ${escapeMarkdownInline(r.file_description)}` : '';
|
|
1150
1208
|
const matched = r.matched_documents?.length
|
|
1151
1209
|
? ` | matched documents: ${r.matched_documents
|
|
1152
1210
|
.map((d) => {
|
|
1153
|
-
const name =
|
|
1154
|
-
return d.type ? `${name} (${
|
|
1211
|
+
const name = escapeMarkdownInline(d.name);
|
|
1212
|
+
return d.type ? `${name} (${escapeMarkdownInline(d.type)})` : name;
|
|
1155
1213
|
})
|
|
1156
1214
|
.join(', ')}`
|
|
1157
1215
|
: '';
|
|
1158
1216
|
const sic = r.sic ? ` | SIC ${r.sic}` : '';
|
|
1159
|
-
const loc = r.location ? ` | ${
|
|
1217
|
+
const loc = r.location ? ` | ${escapeMarkdownInline(r.location)}` : '';
|
|
1160
1218
|
const src = r.source ? ` | source: ${r.source}` : '';
|
|
1161
1219
|
const ident = r.ticker ? `${r.ticker}, CIK ${r.cik}` : `CIK ${r.cik}`;
|
|
1162
|
-
lines.push(`- ${r.form ?? 'N/A'} ${r.filing_date}${period} — ${
|
|
1220
|
+
lines.push(`- ${r.form ?? 'N/A'} ${r.filing_date}${period} — ${escapeMarkdownInline(r.company_name)} (${ident})${sic}${loc}${desc}${matched}${src} [${r.accession_number}]`);
|
|
1163
1221
|
}
|
|
1164
1222
|
if (result.form_distribution) {
|
|
1165
1223
|
const dist = Object.entries(result.form_distribution)
|