@cyanheads/openalex-mcp-server 0.7.14 → 0.7.15
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 +8 -4
- package/CLAUDE.md +8 -4
- package/README.md +7 -6
- package/changelog/0.7.x/0.7.15.md +33 -0
- package/dist/mcp-server/prompts/definitions/literature-review.prompt.js +1 -1
- package/dist/mcp-server/prompts/definitions/literature-review.prompt.js.map +1 -1
- package/dist/mcp-server/tools/definitions/analyze-trends.tool.d.ts +19 -0
- package/dist/mcp-server/tools/definitions/analyze-trends.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/analyze-trends.tool.js +31 -3
- package/dist/mcp-server/tools/definitions/analyze-trends.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/citation-graph.tool.d.ts +12 -1
- package/dist/mcp-server/tools/definitions/citation-graph.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/citation-graph.tool.js +55 -38
- package/dist/mcp-server/tools/definitions/citation-graph.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/resolve-name.tool.d.ts +11 -0
- package/dist/mcp-server/tools/definitions/resolve-name.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/resolve-name.tool.js +12 -1
- package/dist/mcp-server/tools/definitions/resolve-name.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/search-entities.tool.d.ts +40 -0
- package/dist/mcp-server/tools/definitions/search-entities.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/search-entities.tool.js +146 -39
- package/dist/mcp-server/tools/definitions/search-entities.tool.js.map +1 -1
- package/dist/services/openalex/openalex-service.d.ts +16 -0
- package/dist/services/openalex/openalex-service.d.ts.map +1 -1
- package/dist/services/openalex/openalex-service.js +103 -27
- package/dist/services/openalex/openalex-service.js.map +1 -1
- package/dist/services/openalex/types.d.ts +11 -0
- package/dist/services/openalex/types.d.ts.map +1 -1
- package/dist/services/openalex/types.js +7 -0
- package/dist/services/openalex/types.js.map +1 -1
- package/package.json +3 -3
- package/server.json +3 -3
|
@@ -6,39 +6,10 @@ import { tool, z } from '@cyanheads/mcp-ts-core';
|
|
|
6
6
|
import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
|
|
7
7
|
import { renderBudgetTrailer } from '../render-budget.js';
|
|
8
8
|
import { renderEntityRecord } from '../render-entity-record.js';
|
|
9
|
-
import { getOpenAlexService } from '../../../services/openalex/openalex-service.js';
|
|
9
|
+
import { getOpenAlexService, translateFilterKey } from '../../../services/openalex/openalex-service.js';
|
|
10
10
|
const OPENALEX_URL_PREFIX = 'https://openalex.org/';
|
|
11
|
-
/**
|
|
12
|
-
* Resolve any accepted seed identifier to a bare W-ID and confirm it exists. The graph
|
|
13
|
-
* filters (`cites`/`cited_by`/`related_to`) themselves don't validate the seed — passing
|
|
14
|
-
* a non-existent W-ID returns zero edges, indistinguishable from a valid seed with no
|
|
15
|
-
* citations yet. A singleton `/works/{id}` lookup gates the query so bad seeds surface
|
|
16
|
-
* as NotFound (bubbles via the service as `entity_not_found`) and good seeds with empty
|
|
17
|
-
* graphs return honest empty results.
|
|
18
|
-
*/
|
|
19
|
-
async function resolveSeedToWorkId(service, seedId, ctx) {
|
|
20
|
-
const lookup = await service.search({ entityType: 'works', id: seedId, select: ['id'] }, ctx);
|
|
21
|
-
const record = lookup.results[0];
|
|
22
|
-
if (!record?.id) {
|
|
23
|
-
throw ctx.fail('entity_not_found', `Could not resolve seed_id "${seedId}" to an OpenAlex work ID.`, { ...ctx.recoveryFor('entity_not_found'), seedId });
|
|
24
|
-
}
|
|
25
|
-
return record.id.replace(OPENALEX_URL_PREFIX, '');
|
|
26
|
-
}
|
|
27
11
|
const DIRECTIONS = ['cites', 'cited_by', 'related_to'];
|
|
28
12
|
const RESERVED_FILTER_KEYS = new Set(DIRECTIONS);
|
|
29
|
-
/** Reject a `filters` key that `direction` owns — merging it would silently overwrite one. */
|
|
30
|
-
function assertNoReservedFilterKey(input, ctx) {
|
|
31
|
-
if (!input.filters)
|
|
32
|
-
return;
|
|
33
|
-
const reserved = Object.keys(input.filters).find((key) => RESERVED_FILTER_KEYS.has(key));
|
|
34
|
-
if (reserved === undefined)
|
|
35
|
-
return;
|
|
36
|
-
throw ctx.fail('reserved_filter_key', `${reserved} cannot be passed in filters — direction reserves cites/cited_by/related_to.`, {
|
|
37
|
-
...ctx.recoveryFor('reserved_filter_key'),
|
|
38
|
-
reservedKey: reserved,
|
|
39
|
-
direction: input.direction,
|
|
40
|
-
});
|
|
41
|
-
}
|
|
42
13
|
function buildCitationEcho(input) {
|
|
43
14
|
const parts = [`seed_id=${input.seed_id}`, `direction=${input.direction}`];
|
|
44
15
|
if (input.filters && Object.keys(input.filters).length > 0) {
|
|
@@ -59,6 +30,7 @@ export const getCitationGraphTool = tool('openalex_get_citation_graph', {
|
|
|
59
30
|
when: 'OpenAlex throttled the request for exceeding its per-second ceiling (HTTP 429).',
|
|
60
31
|
retryable: true,
|
|
61
32
|
recovery: 'Wait several seconds and retry; consider lowering request frequency for this caller.',
|
|
33
|
+
thrownBy: 'service',
|
|
62
34
|
},
|
|
63
35
|
{
|
|
64
36
|
reason: 'upstream_budget_exhausted',
|
|
@@ -66,6 +38,7 @@ export const getCitationGraphTool = tool('openalex_get_citation_graph', {
|
|
|
66
38
|
when: 'The OpenAlex daily usage budget is spent (HTTP 429).',
|
|
67
39
|
retryable: false,
|
|
68
40
|
recovery: 'The daily budget refills at midnight UTC — retrying sooner will not succeed. Set OPENALEX_API_KEY to a free key (https://openalex.org/settings/api) for a larger daily budget than anonymous access, or wait for the reset.',
|
|
41
|
+
thrownBy: 'service',
|
|
69
42
|
},
|
|
70
43
|
{
|
|
71
44
|
reason: 'upstream_timeout',
|
|
@@ -73,6 +46,7 @@ export const getCitationGraphTool = tool('openalex_get_citation_graph', {
|
|
|
73
46
|
when: 'OpenAlex did not respond within the request deadline.',
|
|
74
47
|
retryable: true,
|
|
75
48
|
recovery: 'Retry after a short delay; if timeouts persist, narrow the request with tighter filters to reduce upstream load.',
|
|
49
|
+
thrownBy: 'service',
|
|
76
50
|
},
|
|
77
51
|
{
|
|
78
52
|
reason: 'upstream_unavailable',
|
|
@@ -80,53 +54,61 @@ export const getCitationGraphTool = tool('openalex_get_citation_graph', {
|
|
|
80
54
|
when: 'OpenAlex was unreachable or unusable — HTTP 503, a connection failure, or a body that was empty, HTML, or unparseable JSON.',
|
|
81
55
|
retryable: true,
|
|
82
56
|
recovery: 'Wait and retry; check https://openalex.org for service status if the outage persists.',
|
|
57
|
+
thrownBy: 'service',
|
|
83
58
|
},
|
|
84
59
|
{
|
|
85
60
|
reason: 'upstream_unauthorized',
|
|
86
61
|
code: JsonRpcErrorCode.Unauthorized,
|
|
87
62
|
when: 'OpenAlex rejected the API key (HTTP 401).',
|
|
88
63
|
recovery: 'Check that OPENALEX_API_KEY is set to a valid OpenAlex account API key (free from https://openalex.org/settings/api).',
|
|
64
|
+
thrownBy: 'service',
|
|
89
65
|
},
|
|
90
66
|
{
|
|
91
67
|
reason: 'upstream_forbidden',
|
|
92
68
|
code: JsonRpcErrorCode.Forbidden,
|
|
93
69
|
when: 'OpenAlex denied access to the requested resource (HTTP 403).',
|
|
94
70
|
recovery: 'Confirm the API key has access to this entity type or endpoint, then retry the request.',
|
|
71
|
+
thrownBy: 'service',
|
|
95
72
|
},
|
|
96
73
|
{
|
|
97
74
|
reason: 'comma_in_filter_value',
|
|
98
75
|
code: JsonRpcErrorCode.InvalidParams,
|
|
99
76
|
when: 'A filter value contains a comma, which collides with the OpenAlex filter separator.',
|
|
100
77
|
recovery: 'Use `|` for OR within a filter value (e.g. "2020|2021"), or use a `.search` filter or the `query` parameter for free-text phrases that contain commas.',
|
|
78
|
+
thrownBy: 'service',
|
|
101
79
|
},
|
|
102
80
|
{
|
|
103
81
|
reason: 'upstream_invalid_params',
|
|
104
82
|
code: JsonRpcErrorCode.InvalidParams,
|
|
105
83
|
when: 'OpenAlex rejected an invalid filter or sort field name (HTTP 400).',
|
|
106
84
|
recovery: 'The upstream message names the rejected token and suggests close matches. Pass a valid OpenAlex work ID (W…), DOI, or PMID for seed_id, or use openalex_describe_fields(entity_type, "filter") to browse valid filter fields.',
|
|
85
|
+
thrownBy: 'service',
|
|
107
86
|
},
|
|
108
87
|
{
|
|
109
88
|
reason: 'upstream_invalid_id_value',
|
|
110
89
|
code: JsonRpcErrorCode.InvalidParams,
|
|
111
90
|
when: 'An entity-ID filter received a value that is not an OpenAlex ID — usually a name (HTTP 400).',
|
|
112
91
|
recovery: 'Call openalex_resolve_name to turn the name into an OpenAlex ID, then filter by that ID. Entity filters such as authorships.author.id and primary_topic.id accept IDs only.',
|
|
92
|
+
thrownBy: 'service',
|
|
113
93
|
},
|
|
114
94
|
{
|
|
115
95
|
reason: 'upstream_sort_requires_search',
|
|
116
96
|
code: JsonRpcErrorCode.InvalidParams,
|
|
117
97
|
when: 'sort=-relevance_score was used but the citation-graph query has no active search (HTTP 400).',
|
|
118
98
|
recovery: 'Sorting by relevance_score requires an active search, which a citation-graph walk lacks — choose a concrete sort field such as -cited_by_count or -publication_date, or add a `*.search` filter.',
|
|
99
|
+
thrownBy: 'service',
|
|
119
100
|
},
|
|
120
101
|
{
|
|
121
102
|
reason: 'upstream_invalid_params_other',
|
|
122
103
|
code: JsonRpcErrorCode.InvalidParams,
|
|
123
104
|
when: 'OpenAlex rejected the request (HTTP 400) for a reason other than an invalid field name.',
|
|
124
105
|
recovery: 'Read the upstream message in the error above and adjust the request — check filter operators, value formats, and cursor/per_page bounds.',
|
|
106
|
+
thrownBy: 'service',
|
|
125
107
|
},
|
|
126
108
|
{
|
|
127
109
|
reason: 'reserved_filter_key',
|
|
128
110
|
code: JsonRpcErrorCode.ValidationError,
|
|
129
|
-
when: 'filters contains cites/cited_by/related_to — the direction parameter reserves those keys.',
|
|
111
|
+
when: 'filters contains cites/cited_by/related_to, or an alias of one such as cited_works — the direction parameter reserves those keys.',
|
|
130
112
|
recovery: 'Remove the reserved key from filters, or restate the relationship through direction.',
|
|
131
113
|
},
|
|
132
114
|
{
|
|
@@ -148,7 +130,7 @@ export const getCitationGraphTool = tool('openalex_get_citation_graph', {
|
|
|
148
130
|
filters: z
|
|
149
131
|
.record(z.string(), z.string())
|
|
150
132
|
.optional()
|
|
151
|
-
.describe('Additional filters to narrow the graph, same syntax as openalex_search_entities. Example: publication_year=">2020", is_oa="true". Do not include cites/cited_by/related_to — those are set by the `direction` parameter.'),
|
|
133
|
+
.describe('Additional filters to narrow the graph, same syntax as openalex_search_entities. Example: publication_year=">2020", is_oa="true". Do not include cites/cited_by/related_to, nor an alias of one such as cited_works — those keys are set by the `direction` parameter.'),
|
|
152
134
|
sort: z
|
|
153
135
|
.string()
|
|
154
136
|
.optional()
|
|
@@ -166,8 +148,9 @@ export const getCitationGraphTool = tool('openalex_get_citation_graph', {
|
|
|
166
148
|
.describe('Results per page (1-100). Default 25.'),
|
|
167
149
|
cursor: z
|
|
168
150
|
.string()
|
|
151
|
+
.min(1)
|
|
169
152
|
.optional()
|
|
170
|
-
.describe('Pagination cursor from a previous response. Pass to get the next page.'),
|
|
153
|
+
.describe('Pagination cursor from a previous response. Pass to get the next page. Omit it on the first call — an empty string is rejected, since a supplied-but-blank cursor is a caller mistake rather than a request for the first page.'),
|
|
171
154
|
}),
|
|
172
155
|
output: z.object({
|
|
173
156
|
meta: z
|
|
@@ -175,7 +158,9 @@ export const getCitationGraphTool = tool('openalex_get_citation_graph', {
|
|
|
175
158
|
count: z
|
|
176
159
|
.number()
|
|
177
160
|
.describe('Total edges from seed_id in this direction (across all pages).'),
|
|
178
|
-
per_page: z
|
|
161
|
+
per_page: z
|
|
162
|
+
.number()
|
|
163
|
+
.describe('Page size OpenAlex echoed for this request — the requested per_page, not the number of records returned. A short or exhausted page carries fewer records than this.'),
|
|
179
164
|
next_cursor: z
|
|
180
165
|
.string()
|
|
181
166
|
.nullable()
|
|
@@ -206,7 +191,7 @@ export const getCitationGraphTool = tool('openalex_get_citation_graph', {
|
|
|
206
191
|
notice: z
|
|
207
192
|
.string()
|
|
208
193
|
.optional()
|
|
209
|
-
.describe('
|
|
194
|
+
.describe('Guidance when no edges are returned. A first call suggests verifying the seed_id, broadening filters, or trying a different direction; a `cursor` continuation says the walk is already past its last edge instead. Absent when results are present.'),
|
|
210
195
|
budget: z
|
|
211
196
|
.object({
|
|
212
197
|
costUsd: z
|
|
@@ -230,9 +215,37 @@ export const getCitationGraphTool = tool('openalex_get_citation_graph', {
|
|
|
230
215
|
budget: { render: renderBudgetTrailer },
|
|
231
216
|
},
|
|
232
217
|
async handler(input, ctx) {
|
|
233
|
-
|
|
218
|
+
/**
|
|
219
|
+
* Reject a `filters` key that `direction` owns — merging it would silently overwrite one.
|
|
220
|
+
* The check runs on the *translated* key, not the raw one: `cited_works` is an alias of
|
|
221
|
+
* `cites`, so reading the caller's spelling alone let it past the guard and the collision
|
|
222
|
+
* happened a layer down, where the direction won and the caller's filter disappeared.
|
|
223
|
+
*/
|
|
224
|
+
const reserved = Object.keys(input.filters ?? {}).find((key) => RESERVED_FILTER_KEYS.has(translateFilterKey('works', key)));
|
|
225
|
+
if (reserved !== undefined) {
|
|
226
|
+
const upstreamKey = translateFilterKey('works', reserved);
|
|
227
|
+
const resolution = upstreamKey === reserved ? '' : ` — it resolves to \`${upstreamKey}\``;
|
|
228
|
+
throw ctx.fail('reserved_filter_key', `${reserved} cannot be passed in filters${resolution}, and direction reserves cites/cited_by/related_to.`, {
|
|
229
|
+
...ctx.recoveryFor('reserved_filter_key'),
|
|
230
|
+
reservedKey: reserved,
|
|
231
|
+
direction: input.direction,
|
|
232
|
+
});
|
|
233
|
+
}
|
|
234
234
|
const service = getOpenAlexService();
|
|
235
|
-
|
|
235
|
+
/**
|
|
236
|
+
* Resolve any accepted seed identifier to a bare W-ID and confirm it exists. The graph
|
|
237
|
+
* filters (`cites`/`cited_by`/`related_to`) themselves don't validate the seed — passing a
|
|
238
|
+
* non-existent W-ID returns zero edges, indistinguishable from a valid seed with no citations
|
|
239
|
+
* yet. A singleton `/works/{id}` lookup gates the query so bad seeds surface as NotFound
|
|
240
|
+
* (a 404 bubbles from the service as `entity_not_found` too) and good seeds with empty graphs
|
|
241
|
+
* return honest empty results.
|
|
242
|
+
*/
|
|
243
|
+
const seedLookup = await service.search({ entityType: 'works', id: input.seed_id, select: ['id'] }, ctx);
|
|
244
|
+
const seedRecord = seedLookup.results[0];
|
|
245
|
+
if (!seedRecord?.id) {
|
|
246
|
+
throw ctx.fail('entity_not_found', `Could not resolve seed_id "${input.seed_id}" to an OpenAlex work ID.`, { ...ctx.recoveryFor('entity_not_found'), seedId: input.seed_id });
|
|
247
|
+
}
|
|
248
|
+
const workId = seedRecord.id.replace(OPENALEX_URL_PREFIX, '');
|
|
236
249
|
const mergedFilters = {
|
|
237
250
|
...(input.filters ?? {}),
|
|
238
251
|
[input.direction]: workId,
|
|
@@ -253,8 +266,12 @@ export const getCitationGraphTool = tool('openalex_get_citation_graph', {
|
|
|
253
266
|
});
|
|
254
267
|
const echo = buildCitationEcho(input);
|
|
255
268
|
ctx.enrich({ echo, totalCount: result.meta.count });
|
|
269
|
+
// An empty page on a `cursor` continuation means the walk already returned every edge it
|
|
270
|
+
// had, so the verify-the-seed advice would send the caller after a seed that is fine.
|
|
256
271
|
if (result.results.length === 0) {
|
|
257
|
-
ctx.enrich.notice(
|
|
272
|
+
ctx.enrich.notice(input.cursor === undefined
|
|
273
|
+
? `No edges for ${echo}. Verify the seed_id with openalex_resolve_name, broaden filters, or try a different direction.`
|
|
274
|
+
: `Pagination exhausted for ${echo} — the previous page held the last edge, so this one came back empty. Stop paging rather than broadening filters or changing direction.`);
|
|
258
275
|
}
|
|
259
276
|
return {
|
|
260
277
|
meta: {
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"citation-graph.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/citation-graph.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;
|
|
1
|
+
{"version":3,"file":"citation-graph.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/citation-graph.tool.ts"],"names":[],"mappings":"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"}
|
|
@@ -34,59 +34,70 @@ export declare const resolveNameTool: import("@cyanheads/mcp-ts-core").ToolDefin
|
|
|
34
34
|
readonly when: "OpenAlex throttled the autocomplete request for exceeding its per-second ceiling (HTTP 429).";
|
|
35
35
|
readonly retryable: true;
|
|
36
36
|
readonly recovery: "Wait several seconds and retry; consider lowering request frequency for this caller.";
|
|
37
|
+
readonly thrownBy: "service";
|
|
37
38
|
}, {
|
|
38
39
|
readonly reason: "upstream_budget_exhausted";
|
|
39
40
|
readonly code: JsonRpcErrorCode.RateLimited;
|
|
40
41
|
readonly when: "The OpenAlex daily usage budget is spent (HTTP 429).";
|
|
41
42
|
readonly retryable: false;
|
|
42
43
|
readonly recovery: "The daily budget refills at midnight UTC — retrying sooner will not succeed. Set OPENALEX_API_KEY to a free key (https://openalex.org/settings/api) for a larger daily budget than anonymous access, or wait for the reset.";
|
|
44
|
+
readonly thrownBy: "service";
|
|
43
45
|
}, {
|
|
44
46
|
readonly reason: "upstream_timeout";
|
|
45
47
|
readonly code: JsonRpcErrorCode.Timeout;
|
|
46
48
|
readonly when: "OpenAlex did not respond within the request deadline.";
|
|
47
49
|
readonly retryable: true;
|
|
48
50
|
readonly recovery: "Retry after a short delay; if timeouts persist, narrow the request with tighter filters to reduce upstream load.";
|
|
51
|
+
readonly thrownBy: "service";
|
|
49
52
|
}, {
|
|
50
53
|
readonly reason: "upstream_unavailable";
|
|
51
54
|
readonly code: JsonRpcErrorCode.ServiceUnavailable;
|
|
52
55
|
readonly when: "OpenAlex was unreachable or unusable — HTTP 503, a connection failure, or a body that was empty, HTML, or unparseable JSON.";
|
|
53
56
|
readonly retryable: true;
|
|
54
57
|
readonly recovery: "Wait and retry; check https://openalex.org for service status if the outage persists.";
|
|
58
|
+
readonly thrownBy: "service";
|
|
55
59
|
}, {
|
|
56
60
|
readonly reason: "upstream_unauthorized";
|
|
57
61
|
readonly code: JsonRpcErrorCode.Unauthorized;
|
|
58
62
|
readonly when: "OpenAlex rejected the API key (HTTP 401).";
|
|
59
63
|
readonly recovery: "Check that OPENALEX_API_KEY is set to a valid OpenAlex account API key (free from https://openalex.org/settings/api).";
|
|
64
|
+
readonly thrownBy: "service";
|
|
60
65
|
}, {
|
|
61
66
|
readonly reason: "upstream_forbidden";
|
|
62
67
|
readonly code: JsonRpcErrorCode.Forbidden;
|
|
63
68
|
readonly when: "OpenAlex denied access to autocomplete (HTTP 403).";
|
|
64
69
|
readonly recovery: "Confirm the API key has access to autocomplete, then retry the request.";
|
|
70
|
+
readonly thrownBy: "service";
|
|
65
71
|
}, {
|
|
66
72
|
readonly reason: "comma_in_filter_value";
|
|
67
73
|
readonly code: JsonRpcErrorCode.InvalidParams;
|
|
68
74
|
readonly when: "A `filters` value contains a comma, which collides with the OpenAlex filter separator.";
|
|
69
75
|
readonly recovery: "Use `|` for OR within a filter value (e.g. \"2020|2021\"), or move a free-text phrase containing commas into the `query` parameter.";
|
|
76
|
+
readonly thrownBy: "service";
|
|
70
77
|
}, {
|
|
71
78
|
readonly reason: "upstream_invalid_params";
|
|
72
79
|
readonly code: JsonRpcErrorCode.InvalidParams;
|
|
73
80
|
readonly when: "OpenAlex rejected an invalid filter field name on the autocomplete query (HTTP 400).";
|
|
74
81
|
readonly recovery: "The upstream message names the rejected field and suggests close matches. Use openalex_describe_fields(entity_type, \"filter\") to browse valid filter fields, or drop `filters` entirely.";
|
|
82
|
+
readonly thrownBy: "service";
|
|
75
83
|
}, {
|
|
76
84
|
readonly reason: "upstream_invalid_id_value";
|
|
77
85
|
readonly code: JsonRpcErrorCode.InvalidParams;
|
|
78
86
|
readonly when: "A `filters` entry expecting an entity ID received a value that is not an OpenAlex ID — usually a name (HTTP 400).";
|
|
79
87
|
readonly recovery: "Resolve that name to an OpenAlex ID first — run this tool without the ID-valued filter, take the `id` from a match, then re-run with the ID.";
|
|
88
|
+
readonly thrownBy: "service";
|
|
80
89
|
}, {
|
|
81
90
|
readonly reason: "upstream_invalid_params_other";
|
|
82
91
|
readonly code: JsonRpcErrorCode.InvalidParams;
|
|
83
92
|
readonly when: "OpenAlex rejected the autocomplete request (HTTP 400) for a reason other than an invalid field name.";
|
|
84
93
|
readonly recovery: "Read the upstream message in the error above and adjust the request — trim the query, check filter value formats, and ensure entity_type is a supported value.";
|
|
94
|
+
readonly thrownBy: "service";
|
|
85
95
|
}, {
|
|
86
96
|
readonly reason: "upstream_validation_failed";
|
|
87
97
|
readonly code: JsonRpcErrorCode.ValidationError;
|
|
88
98
|
readonly when: "OpenAlex rejected the autocomplete request as semantically invalid (HTTP 422).";
|
|
89
99
|
readonly recovery: "Read the upstream message for the specific field, then adjust the request to satisfy validation.";
|
|
100
|
+
readonly thrownBy: "service";
|
|
90
101
|
}], {
|
|
91
102
|
readonly notice: z.ZodOptional<z.ZodString>;
|
|
92
103
|
readonly budget: z.ZodOptional<z.ZodObject<{
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"resolve-name.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/resolve-name.tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AASjE,eAAO,MAAM,eAAe
|
|
1
|
+
{"version":3,"file":"resolve-name.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/resolve-name.tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AASjE,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAsR1B,CAAC"}
|
|
@@ -19,6 +19,7 @@ export const resolveNameTool = tool('openalex_resolve_name', {
|
|
|
19
19
|
when: 'OpenAlex throttled the autocomplete request for exceeding its per-second ceiling (HTTP 429).',
|
|
20
20
|
retryable: true,
|
|
21
21
|
recovery: 'Wait several seconds and retry; consider lowering request frequency for this caller.',
|
|
22
|
+
thrownBy: 'service',
|
|
22
23
|
},
|
|
23
24
|
{
|
|
24
25
|
reason: 'upstream_budget_exhausted',
|
|
@@ -26,6 +27,7 @@ export const resolveNameTool = tool('openalex_resolve_name', {
|
|
|
26
27
|
when: 'The OpenAlex daily usage budget is spent (HTTP 429).',
|
|
27
28
|
retryable: false,
|
|
28
29
|
recovery: 'The daily budget refills at midnight UTC — retrying sooner will not succeed. Set OPENALEX_API_KEY to a free key (https://openalex.org/settings/api) for a larger daily budget than anonymous access, or wait for the reset.',
|
|
30
|
+
thrownBy: 'service',
|
|
29
31
|
},
|
|
30
32
|
{
|
|
31
33
|
reason: 'upstream_timeout',
|
|
@@ -33,6 +35,7 @@ export const resolveNameTool = tool('openalex_resolve_name', {
|
|
|
33
35
|
when: 'OpenAlex did not respond within the request deadline.',
|
|
34
36
|
retryable: true,
|
|
35
37
|
recovery: 'Retry after a short delay; if timeouts persist, narrow the request with tighter filters to reduce upstream load.',
|
|
38
|
+
thrownBy: 'service',
|
|
36
39
|
},
|
|
37
40
|
{
|
|
38
41
|
reason: 'upstream_unavailable',
|
|
@@ -40,48 +43,56 @@ export const resolveNameTool = tool('openalex_resolve_name', {
|
|
|
40
43
|
when: 'OpenAlex was unreachable or unusable — HTTP 503, a connection failure, or a body that was empty, HTML, or unparseable JSON.',
|
|
41
44
|
retryable: true,
|
|
42
45
|
recovery: 'Wait and retry; check https://openalex.org for service status if the outage persists.',
|
|
46
|
+
thrownBy: 'service',
|
|
43
47
|
},
|
|
44
48
|
{
|
|
45
49
|
reason: 'upstream_unauthorized',
|
|
46
50
|
code: JsonRpcErrorCode.Unauthorized,
|
|
47
51
|
when: 'OpenAlex rejected the API key (HTTP 401).',
|
|
48
52
|
recovery: 'Check that OPENALEX_API_KEY is set to a valid OpenAlex account API key (free from https://openalex.org/settings/api).',
|
|
53
|
+
thrownBy: 'service',
|
|
49
54
|
},
|
|
50
55
|
{
|
|
51
56
|
reason: 'upstream_forbidden',
|
|
52
57
|
code: JsonRpcErrorCode.Forbidden,
|
|
53
58
|
when: 'OpenAlex denied access to autocomplete (HTTP 403).',
|
|
54
59
|
recovery: 'Confirm the API key has access to autocomplete, then retry the request.',
|
|
60
|
+
thrownBy: 'service',
|
|
55
61
|
},
|
|
56
62
|
{
|
|
57
63
|
reason: 'comma_in_filter_value',
|
|
58
64
|
code: JsonRpcErrorCode.InvalidParams,
|
|
59
65
|
when: 'A `filters` value contains a comma, which collides with the OpenAlex filter separator.',
|
|
60
66
|
recovery: 'Use `|` for OR within a filter value (e.g. "2020|2021"), or move a free-text phrase containing commas into the `query` parameter.',
|
|
67
|
+
thrownBy: 'service',
|
|
61
68
|
},
|
|
62
69
|
{
|
|
63
70
|
reason: 'upstream_invalid_params',
|
|
64
71
|
code: JsonRpcErrorCode.InvalidParams,
|
|
65
72
|
when: 'OpenAlex rejected an invalid filter field name on the autocomplete query (HTTP 400).',
|
|
66
73
|
recovery: 'The upstream message names the rejected field and suggests close matches. Use openalex_describe_fields(entity_type, "filter") to browse valid filter fields, or drop `filters` entirely.',
|
|
74
|
+
thrownBy: 'service',
|
|
67
75
|
},
|
|
68
76
|
{
|
|
69
77
|
reason: 'upstream_invalid_id_value',
|
|
70
78
|
code: JsonRpcErrorCode.InvalidParams,
|
|
71
79
|
when: 'A `filters` entry expecting an entity ID received a value that is not an OpenAlex ID — usually a name (HTTP 400).',
|
|
72
80
|
recovery: 'Resolve that name to an OpenAlex ID first — run this tool without the ID-valued filter, take the `id` from a match, then re-run with the ID.',
|
|
81
|
+
thrownBy: 'service',
|
|
73
82
|
},
|
|
74
83
|
{
|
|
75
84
|
reason: 'upstream_invalid_params_other',
|
|
76
85
|
code: JsonRpcErrorCode.InvalidParams,
|
|
77
86
|
when: 'OpenAlex rejected the autocomplete request (HTTP 400) for a reason other than an invalid field name.',
|
|
78
87
|
recovery: 'Read the upstream message in the error above and adjust the request — trim the query, check filter value formats, and ensure entity_type is a supported value.',
|
|
88
|
+
thrownBy: 'service',
|
|
79
89
|
},
|
|
80
90
|
{
|
|
81
91
|
reason: 'upstream_validation_failed',
|
|
82
92
|
code: JsonRpcErrorCode.ValidationError,
|
|
83
93
|
when: 'OpenAlex rejected the autocomplete request as semantically invalid (HTTP 422).',
|
|
84
94
|
recovery: 'Read the upstream message for the specific field, then adjust the request to satisfy validation.',
|
|
95
|
+
thrownBy: 'service',
|
|
85
96
|
},
|
|
86
97
|
],
|
|
87
98
|
inputAliases: { name: 'query', filter: 'filters' },
|
|
@@ -93,7 +104,7 @@ export const resolveNameTool = tool('openalex_resolve_name', {
|
|
|
93
104
|
query: z
|
|
94
105
|
.string()
|
|
95
106
|
.min(1)
|
|
96
|
-
.describe('Name or partial name to resolve. Also accepts an identifier, bare or in URL form — OpenAlex ID ("W2741809807", "F4320332161"), DOI ("10.1038/nature12373"), ORCID ("0000-0002-1825-0097"), ROR ("https://ror.org/00hx57361"), PMID ("12345678" or "https://pubmed.ncbi.nlm.nih.gov/12345678"), ISSN ("1234-5678") — which resolves straight to that one record instead of running a name search. A PMCID ("PMC1234567" or a PubMed Central URL) is recognized but OpenAlex indexes no PMCIDs, so it resolves nothing — pass the work\'s PMID or DOI instead.'),
|
|
107
|
+
.describe('Name or partial name to resolve. Also accepts an identifier, bare or in URL form — OpenAlex ID ("W2741809807", "F4320332161"), DOI ("10.1038/nature12373"), ORCID ("0000-0002-1825-0097"), ROR ("https://ror.org/00hx57361"), PMID ("12345678" or "https://pubmed.ncbi.nlm.nih.gov/12345678"), ISSN ("1234-5678") — which resolves straight to that one record instead of running a name search. A keyword URL ("https://openalex.org/keywords/groundwater") resolves the same way; a bare keyword slug reads as a name and runs a name search, which finds it too. A PMCID ("PMC1234567" or a PubMed Central URL) is recognized but OpenAlex indexes no PMCIDs, so it resolves nothing — pass the work\'s PMID or DOI instead.'),
|
|
97
108
|
filters: z
|
|
98
109
|
.record(z.string(), z.string())
|
|
99
110
|
.optional()
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"resolve-name.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/resolve-name.tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,sBAAsB,GACvB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAE5D,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAC,uBAAuB,EAAE;IAC3D,WAAW,EACT,wgBAAwgB;IAC1gB,SAAS,EACP,kHAAkH;IACpH,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE;IAC9E,MAAM,EAAE;QACN;YACE,MAAM,EAAE,cAAc;YACtB,IAAI,EAAE,gBAAgB,CAAC,WAAW;YAClC,IAAI,EAAE,8FAA8F;YACpG,SAAS,EAAE,IAAI;YACf,QAAQ,EACN,sFAAsF;
|
|
1
|
+
{"version":3,"file":"resolve-name.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/resolve-name.tool.ts"],"names":[],"mappings":"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"}
|
|
@@ -27,6 +27,7 @@ export declare const searchEntitiesTool: import("@cyanheads/mcp-ts-core").ToolDe
|
|
|
27
27
|
select: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
28
28
|
per_page: z.ZodDefault<z.ZodNumber>;
|
|
29
29
|
cursor: z.ZodOptional<z.ZodString>;
|
|
30
|
+
page: z.ZodOptional<z.ZodNumber>;
|
|
30
31
|
sample: z.ZodOptional<z.ZodNumber>;
|
|
31
32
|
seed: z.ZodOptional<z.ZodString>;
|
|
32
33
|
}, z.core.$strip>, z.ZodObject<{
|
|
@@ -44,11 +45,31 @@ export declare const searchEntitiesTool: import("@cyanheads/mcp-ts-core").ToolDe
|
|
|
44
45
|
readonly code: JsonRpcErrorCode.ValidationError;
|
|
45
46
|
readonly when: "A search (no `id`) set per_page above the semantic-search cap of 50.";
|
|
46
47
|
readonly recovery: "Reduce per_page to 50 or less, or switch search_mode to keyword.";
|
|
48
|
+
}, {
|
|
49
|
+
readonly reason: "semantic_without_query";
|
|
50
|
+
readonly code: JsonRpcErrorCode.ValidationError;
|
|
51
|
+
readonly when: "A search set search_mode to \"semantic\" without supplying the `query` it embeds.";
|
|
52
|
+
readonly recovery: "Pass the text to match in `query`, or switch search_mode to keyword for a filter-only listing.";
|
|
53
|
+
}, {
|
|
54
|
+
readonly reason: "semantic_with_cursor";
|
|
55
|
+
readonly code: JsonRpcErrorCode.ValidationError;
|
|
56
|
+
readonly when: "A search set search_mode to \"semantic\" and supplied `cursor`, which OpenAlex rejects on a semantic query.";
|
|
57
|
+
readonly recovery: "Drop `cursor` and walk semantic results with `page` (1-based), or switch search_mode to keyword or exact, which paginate by cursor.";
|
|
58
|
+
}, {
|
|
59
|
+
readonly reason: "page_without_semantic";
|
|
60
|
+
readonly code: JsonRpcErrorCode.ValidationError;
|
|
61
|
+
readonly when: "A search supplied `page` under a search_mode other than \"semantic\".";
|
|
62
|
+
readonly recovery: "Drop `page` and paginate with `cursor`, or set search_mode to \"semantic\" — the only mode `page` applies to.";
|
|
47
63
|
}, {
|
|
48
64
|
readonly reason: "sample_with_cursor";
|
|
49
65
|
readonly code: JsonRpcErrorCode.ValidationError;
|
|
50
66
|
readonly when: "A search (no `id`) provided both `sample` and `cursor`.";
|
|
51
67
|
readonly recovery: "Sampling returns a single page only; remove `cursor` or remove `sample`.";
|
|
68
|
+
}, {
|
|
69
|
+
readonly reason: "sample_with_page";
|
|
70
|
+
readonly code: JsonRpcErrorCode.ValidationError;
|
|
71
|
+
readonly when: "A search (no `id`) provided both `sample` and `page`.";
|
|
72
|
+
readonly recovery: "Sampling returns a single page only; remove `page` or remove `sample`.";
|
|
52
73
|
}, {
|
|
53
74
|
readonly reason: "seed_without_sample";
|
|
54
75
|
readonly code: JsonRpcErrorCode.ValidationError;
|
|
@@ -59,70 +80,89 @@ export declare const searchEntitiesTool: import("@cyanheads/mcp-ts-core").ToolDe
|
|
|
59
80
|
readonly code: JsonRpcErrorCode.NotFound;
|
|
60
81
|
readonly when: "Lookup by id matched no OpenAlex entity.";
|
|
61
82
|
readonly recovery: "Verify the ID format or call openalex_resolve_name to find the correct ID.";
|
|
83
|
+
readonly thrownBy: "service";
|
|
62
84
|
}, {
|
|
63
85
|
readonly reason: "rate_limited";
|
|
64
86
|
readonly code: JsonRpcErrorCode.RateLimited;
|
|
65
87
|
readonly when: "OpenAlex throttled the request for exceeding its per-second ceiling (HTTP 429).";
|
|
66
88
|
readonly retryable: true;
|
|
67
89
|
readonly recovery: "Wait several seconds and retry; consider lowering request frequency for this caller.";
|
|
90
|
+
readonly thrownBy: "service";
|
|
68
91
|
}, {
|
|
69
92
|
readonly reason: "upstream_budget_exhausted";
|
|
70
93
|
readonly code: JsonRpcErrorCode.RateLimited;
|
|
71
94
|
readonly when: "The OpenAlex daily usage budget is spent (HTTP 429).";
|
|
72
95
|
readonly retryable: false;
|
|
73
96
|
readonly recovery: "The daily budget refills at midnight UTC — retrying sooner will not succeed. Set OPENALEX_API_KEY to a free key (https://openalex.org/settings/api) for a larger daily budget than anonymous access, or wait for the reset.";
|
|
97
|
+
readonly thrownBy: "service";
|
|
74
98
|
}, {
|
|
75
99
|
readonly reason: "upstream_timeout";
|
|
76
100
|
readonly code: JsonRpcErrorCode.Timeout;
|
|
77
101
|
readonly when: "OpenAlex did not respond within the request deadline.";
|
|
78
102
|
readonly retryable: true;
|
|
79
103
|
readonly recovery: "Retry after a short delay; if timeouts persist, narrow the request with tighter filters to reduce upstream load.";
|
|
104
|
+
readonly thrownBy: "service";
|
|
80
105
|
}, {
|
|
81
106
|
readonly reason: "upstream_unavailable";
|
|
82
107
|
readonly code: JsonRpcErrorCode.ServiceUnavailable;
|
|
83
108
|
readonly when: "OpenAlex was unreachable or unusable — HTTP 503, a connection failure, or a body that was empty, HTML, or unparseable JSON.";
|
|
84
109
|
readonly retryable: true;
|
|
85
110
|
readonly recovery: "Wait and retry; check https://openalex.org for service status if the outage persists.";
|
|
111
|
+
readonly thrownBy: "service";
|
|
86
112
|
}, {
|
|
87
113
|
readonly reason: "upstream_unauthorized";
|
|
88
114
|
readonly code: JsonRpcErrorCode.Unauthorized;
|
|
89
115
|
readonly when: "OpenAlex rejected the API key (HTTP 401).";
|
|
90
116
|
readonly recovery: "Check that OPENALEX_API_KEY is set to a valid OpenAlex account API key (free from https://openalex.org/settings/api).";
|
|
117
|
+
readonly thrownBy: "service";
|
|
91
118
|
}, {
|
|
92
119
|
readonly reason: "upstream_forbidden";
|
|
93
120
|
readonly code: JsonRpcErrorCode.Forbidden;
|
|
94
121
|
readonly when: "OpenAlex denied access to the requested resource (HTTP 403).";
|
|
95
122
|
readonly recovery: "Confirm the API key has access to this entity type or endpoint, then retry the request.";
|
|
123
|
+
readonly thrownBy: "service";
|
|
96
124
|
}, {
|
|
97
125
|
readonly reason: "comma_in_filter_value";
|
|
98
126
|
readonly code: JsonRpcErrorCode.InvalidParams;
|
|
99
127
|
readonly when: "A filter value contains a comma, which collides with the OpenAlex filter separator.";
|
|
100
128
|
readonly recovery: "Use `|` for OR within a filter value (e.g. \"2020|2021\"), or use a `.search` filter or the `query` parameter for free-text phrases that contain commas.";
|
|
129
|
+
readonly thrownBy: "service";
|
|
101
130
|
}, {
|
|
102
131
|
readonly reason: "upstream_invalid_params";
|
|
103
132
|
readonly code: JsonRpcErrorCode.InvalidParams;
|
|
104
133
|
readonly when: "OpenAlex rejected an invalid filter, select, or sort field name (HTTP 400).";
|
|
105
134
|
readonly recovery: "The upstream message names the rejected field and suggests close matches. Use openalex_describe_fields(entity_type, context) to browse all valid fields for the given entity type and context.";
|
|
135
|
+
readonly thrownBy: "service";
|
|
106
136
|
}, {
|
|
107
137
|
readonly reason: "upstream_invalid_id_value";
|
|
108
138
|
readonly code: JsonRpcErrorCode.InvalidParams;
|
|
109
139
|
readonly when: "An entity-ID filter received a value that is not an OpenAlex ID — usually a name (HTTP 400).";
|
|
110
140
|
readonly recovery: "Call openalex_resolve_name to turn the name into an OpenAlex ID, then filter by that ID. Entity filters such as authorships.author.id, primary_topic.id, and cites accept IDs only.";
|
|
141
|
+
readonly thrownBy: "service";
|
|
111
142
|
}, {
|
|
112
143
|
readonly reason: "upstream_sort_requires_search";
|
|
113
144
|
readonly code: JsonRpcErrorCode.InvalidParams;
|
|
114
145
|
readonly when: "sort=-relevance_score was used without an active search (HTTP 400).";
|
|
115
146
|
readonly recovery: "Sorting by relevance_score requires an active search — add a `query` or a `*.search` filter (e.g. title.search), or choose a concrete sort field such as -cited_by_count or -publication_date.";
|
|
147
|
+
readonly thrownBy: "service";
|
|
148
|
+
}, {
|
|
149
|
+
readonly reason: "query_too_long";
|
|
150
|
+
readonly code: JsonRpcErrorCode.InvalidParams;
|
|
151
|
+
readonly when: "OpenAlex rejected `query` as longer than the search length it accepts (HTTP 400).";
|
|
152
|
+
readonly recovery: "Shorten `query` to the character limit the upstream message names, or split the text into several shorter searches and merge their results.";
|
|
153
|
+
readonly thrownBy: "service";
|
|
116
154
|
}, {
|
|
117
155
|
readonly reason: "upstream_invalid_params_other";
|
|
118
156
|
readonly code: JsonRpcErrorCode.InvalidParams;
|
|
119
157
|
readonly when: "OpenAlex rejected the request (HTTP 400) for a reason other than an invalid field name.";
|
|
120
158
|
readonly recovery: "Read the upstream message in the error above and adjust the request — check filter operators, value formats, and cursor/per_page bounds.";
|
|
159
|
+
readonly thrownBy: "service";
|
|
121
160
|
}, {
|
|
122
161
|
readonly reason: "upstream_validation_failed";
|
|
123
162
|
readonly code: JsonRpcErrorCode.ValidationError;
|
|
124
163
|
readonly when: "OpenAlex rejected the request as semantically invalid (HTTP 422).";
|
|
125
164
|
readonly recovery: "Read the upstream message for the specific field, then adjust the request to satisfy validation.";
|
|
165
|
+
readonly thrownBy: "service";
|
|
126
166
|
}], {
|
|
127
167
|
readonly echo: z.ZodString;
|
|
128
168
|
readonly totalCount: z.ZodNumber;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"search-entities.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/search-entities.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;
|
|
1
|
+
{"version":3,"file":"search-entities.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/search-entities.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AA0EjE,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkgB7B,CAAC"}
|