@cyanheads/openalex-mcp-server 0.7.13 → 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 +25 -10
- package/CLAUDE.md +25 -10
- package/README.md +167 -88
- package/changelog/0.7.x/0.7.14.md +28 -0
- package/changelog/0.7.x/0.7.15.md +33 -0
- package/changelog/template.md +7 -7
- package/dist/index.js +2 -0
- package/dist/index.js.map +1 -1
- 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 +32 -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 -33
- 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 +13 -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 +132 -20
- 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 +105 -29
- 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 +7 -7
- package/server.json +3 -3
|
@@ -18,6 +18,7 @@ export const analyzeTrendsTool = tool('openalex_analyze_trends', {
|
|
|
18
18
|
when: 'OpenAlex throttled the request for exceeding its per-second ceiling (HTTP 429).',
|
|
19
19
|
retryable: true,
|
|
20
20
|
recovery: 'Wait several seconds and retry; consider lowering request frequency for this caller.',
|
|
21
|
+
thrownBy: 'service',
|
|
21
22
|
},
|
|
22
23
|
{
|
|
23
24
|
reason: 'upstream_budget_exhausted',
|
|
@@ -25,6 +26,7 @@ export const analyzeTrendsTool = tool('openalex_analyze_trends', {
|
|
|
25
26
|
when: 'The OpenAlex daily usage budget is spent (HTTP 429).',
|
|
26
27
|
retryable: false,
|
|
27
28
|
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.',
|
|
29
|
+
thrownBy: 'service',
|
|
28
30
|
},
|
|
29
31
|
{
|
|
30
32
|
reason: 'upstream_timeout',
|
|
@@ -32,6 +34,7 @@ export const analyzeTrendsTool = tool('openalex_analyze_trends', {
|
|
|
32
34
|
when: 'OpenAlex did not respond within the request deadline.',
|
|
33
35
|
retryable: true,
|
|
34
36
|
recovery: 'Retry after a short delay; if timeouts persist, narrow the request with tighter filters to reduce upstream load.',
|
|
37
|
+
thrownBy: 'service',
|
|
35
38
|
},
|
|
36
39
|
{
|
|
37
40
|
reason: 'upstream_unavailable',
|
|
@@ -39,60 +42,79 @@ export const analyzeTrendsTool = tool('openalex_analyze_trends', {
|
|
|
39
42
|
when: 'OpenAlex was unreachable or unusable — HTTP 503, a connection failure, or a body that was empty, HTML, or unparseable JSON.',
|
|
40
43
|
retryable: true,
|
|
41
44
|
recovery: 'Wait and retry; check https://openalex.org for service status if the outage persists.',
|
|
45
|
+
thrownBy: 'service',
|
|
42
46
|
},
|
|
43
47
|
{
|
|
44
48
|
reason: 'upstream_unauthorized',
|
|
45
49
|
code: JsonRpcErrorCode.Unauthorized,
|
|
46
50
|
when: 'OpenAlex rejected the API key (HTTP 401).',
|
|
47
51
|
recovery: 'Check that OPENALEX_API_KEY is set to a valid OpenAlex account API key (free from https://openalex.org/settings/api).',
|
|
52
|
+
thrownBy: 'service',
|
|
48
53
|
},
|
|
49
54
|
{
|
|
50
55
|
reason: 'upstream_forbidden',
|
|
51
56
|
code: JsonRpcErrorCode.Forbidden,
|
|
52
57
|
when: 'OpenAlex denied access to the requested resource (HTTP 403).',
|
|
53
58
|
recovery: 'Confirm the API key has access to this entity type or endpoint, then retry the request.',
|
|
59
|
+
thrownBy: 'service',
|
|
54
60
|
},
|
|
55
61
|
{
|
|
56
62
|
reason: 'comma_in_filter_value',
|
|
57
63
|
code: JsonRpcErrorCode.InvalidParams,
|
|
58
64
|
when: 'A filter value contains a comma, which collides with the OpenAlex filter separator.',
|
|
59
65
|
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.',
|
|
66
|
+
thrownBy: 'service',
|
|
60
67
|
},
|
|
61
68
|
{
|
|
62
69
|
reason: 'upstream_invalid_params',
|
|
63
70
|
code: JsonRpcErrorCode.InvalidParams,
|
|
64
71
|
when: 'OpenAlex rejected an invalid group_by or filter field name (HTTP 400).',
|
|
65
72
|
recovery: 'The upstream message names the rejected key and suggests close matches. Use openalex_describe_fields(entity_type, "group_by") to browse valid group_by fields, or openalex_describe_fields(entity_type, "filter") for filter fields.',
|
|
73
|
+
thrownBy: 'service',
|
|
66
74
|
},
|
|
67
75
|
{
|
|
68
76
|
reason: 'upstream_invalid_id_value',
|
|
69
77
|
code: JsonRpcErrorCode.InvalidParams,
|
|
70
78
|
when: 'An entity-ID filter received a value that is not an OpenAlex ID — usually a name (HTTP 400).',
|
|
71
79
|
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.',
|
|
80
|
+
thrownBy: 'service',
|
|
72
81
|
},
|
|
73
82
|
{
|
|
74
83
|
reason: 'upstream_ungroupable_group_by',
|
|
75
84
|
code: JsonRpcErrorCode.InvalidParams,
|
|
76
85
|
when: 'group_by targets a raw date, float, or *.search field OpenAlex cannot aggregate (HTTP 400).',
|
|
77
86
|
recovery: 'Group by a categorical or year field (e.g. publication_year, type, oa_status, or an integer count field) — raw date fields and *.search operators cannot be grouped. Call openalex_describe_fields(entity_type, "group_by") for the groupable set.',
|
|
87
|
+
thrownBy: 'service',
|
|
78
88
|
},
|
|
79
89
|
{
|
|
80
90
|
reason: 'upstream_invalid_params_other',
|
|
81
91
|
code: JsonRpcErrorCode.InvalidParams,
|
|
82
92
|
when: 'OpenAlex rejected the request (HTTP 400) for a reason other than an invalid field name.',
|
|
83
93
|
recovery: 'Read the upstream message in the error above and adjust the request — check filter operators, value formats, and the group_by field.',
|
|
94
|
+
thrownBy: 'service',
|
|
84
95
|
},
|
|
85
96
|
{
|
|
86
97
|
reason: 'upstream_validation_failed',
|
|
87
98
|
code: JsonRpcErrorCode.ValidationError,
|
|
88
99
|
when: 'OpenAlex rejected the request as semantically invalid (HTTP 422).',
|
|
89
100
|
recovery: 'Read the upstream message for the specific field, then adjust the request to satisfy validation.',
|
|
101
|
+
thrownBy: 'service',
|
|
102
|
+
},
|
|
103
|
+
{
|
|
104
|
+
reason: 'upstream_missing_group_by',
|
|
105
|
+
code: JsonRpcErrorCode.ServiceUnavailable,
|
|
106
|
+
when: 'OpenAlex answered with its plain list shape, carrying no aggregation for the requested group_by.',
|
|
107
|
+
retryable: true,
|
|
108
|
+
recovery: 'Retry the request; if it repeats, confirm group_by names a field OpenAlex can aggregate with openalex_describe_fields(entity_type, "group_by").',
|
|
109
|
+
thrownBy: 'service',
|
|
90
110
|
},
|
|
91
111
|
],
|
|
112
|
+
inputAliases: { filter: 'filters' },
|
|
92
113
|
input: z.object({
|
|
93
114
|
entity_type: z.enum(ENTITY_TYPES).describe('Entity type to aggregate.'),
|
|
94
115
|
group_by: z
|
|
95
116
|
.string()
|
|
117
|
+
.min(1)
|
|
96
118
|
.describe('Field to group by. Works examples: "publication_year", "type", "oa_status", "primary_topic.field.id", "authorships.institutions.country_code", "is_retracted". Authors: "last_known_institutions.country_code", "has_orcid". Sources: "type", "is_oa", "country_code". Not all fields support group_by — check entity docs if unsure.'),
|
|
97
119
|
filters: z
|
|
98
120
|
.record(z.string(), z.string())
|
|
@@ -115,8 +137,9 @@ export const analyzeTrendsTool = tool('openalex_analyze_trends', {
|
|
|
115
137
|
.describe('Sort order for groups. Omit or pass "count" (default) to return the top-N groups by count descending — no further pages. Pass "key" to enumerate all distinct values in key-ascending order with cursor pagination. Use "key" only when you need a full traversal; most analysis calls want "count".'),
|
|
116
138
|
cursor: z
|
|
117
139
|
.string()
|
|
140
|
+
.min(1)
|
|
118
141
|
.optional()
|
|
119
|
-
.describe('Pagination cursor from a previous response. Only relevant when order is "key" — count-descending results have no next page. Pass the next_cursor from the previous response to advance.'),
|
|
142
|
+
.describe('Pagination cursor from a previous response. Only relevant when order is "key" — count-descending results have no next page. Pass the next_cursor from the previous response to advance. 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.'),
|
|
120
143
|
}),
|
|
121
144
|
output: z.object({
|
|
122
145
|
meta: z
|
|
@@ -152,7 +175,7 @@ export const analyzeTrendsTool = tool('openalex_analyze_trends', {
|
|
|
152
175
|
notice: z
|
|
153
176
|
.string()
|
|
154
177
|
.optional()
|
|
155
|
-
.describe('Guidance notice. Set when no groups
|
|
178
|
+
.describe('Guidance notice. Set when a first call returns no groups (recovery suggestions), when a `cursor` continuation returns none because the traversal is already finished, or when the page is full and more groups likely exist (truncation signal with narrowing advice). Absent otherwise.'),
|
|
156
179
|
budget: z
|
|
157
180
|
.object({
|
|
158
181
|
costUsd: z
|
|
@@ -194,8 +217,14 @@ export const analyzeTrendsTool = tool('openalex_analyze_trends', {
|
|
|
194
217
|
});
|
|
195
218
|
const echo = buildAnalyzeEcho(input);
|
|
196
219
|
ctx.enrich({ echo, totalCount: result.meta.count });
|
|
220
|
+
// An empty page on a `cursor` continuation means the key-ascending traversal already
|
|
221
|
+
// enumerated every group, so there is nothing left to remove or regroup. On a first call
|
|
222
|
+
// the same shape can still be an honest zero — including the all-values-unknown case,
|
|
223
|
+
// where `count` is nonzero but every matched entity is null for the grouped field.
|
|
197
224
|
if (result.groups.length === 0) {
|
|
198
|
-
ctx.enrich.notice(
|
|
225
|
+
ctx.enrich.notice(input.cursor === undefined
|
|
226
|
+
? `No groups returned for ${echo}. Try removing filters or grouping by a different field.`
|
|
227
|
+
: `Pagination exhausted for ${echo} — the previous page held the last group, so this one came back empty. Stop paging rather than removing filters or regrouping.`);
|
|
199
228
|
}
|
|
200
229
|
else if (input.order === 'key') {
|
|
201
230
|
// Key-ascending traversal: omitted groups sit beyond the cursor, not in a count tail, so
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"analyze-trends.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/analyze-trends.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;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,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAC;AAC7E,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAE5D,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,CAAC,yBAAyB,EAAE;IAC/D,WAAW,EACT,oXAAoX;IACtX,SAAS,EACP,oHAAoH;IACtH,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,iFAAiF;YACvF,SAAS,EAAE,IAAI;YACf,QAAQ,EACN,sFAAsF;
|
|
1
|
+
{"version":3,"file":"analyze-trends.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/analyze-trends.tool.ts"],"names":[],"mappings":"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"}
|
|
@@ -32,63 +32,74 @@ export declare const getCitationGraphTool: import("@cyanheads/mcp-ts-core").Tool
|
|
|
32
32
|
readonly when: "OpenAlex throttled the request for exceeding its per-second ceiling (HTTP 429).";
|
|
33
33
|
readonly retryable: true;
|
|
34
34
|
readonly recovery: "Wait several seconds and retry; consider lowering request frequency for this caller.";
|
|
35
|
+
readonly thrownBy: "service";
|
|
35
36
|
}, {
|
|
36
37
|
readonly reason: "upstream_budget_exhausted";
|
|
37
38
|
readonly code: JsonRpcErrorCode.RateLimited;
|
|
38
39
|
readonly when: "The OpenAlex daily usage budget is spent (HTTP 429).";
|
|
39
40
|
readonly retryable: false;
|
|
40
41
|
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.";
|
|
42
|
+
readonly thrownBy: "service";
|
|
41
43
|
}, {
|
|
42
44
|
readonly reason: "upstream_timeout";
|
|
43
45
|
readonly code: JsonRpcErrorCode.Timeout;
|
|
44
46
|
readonly when: "OpenAlex did not respond within the request deadline.";
|
|
45
47
|
readonly retryable: true;
|
|
46
48
|
readonly recovery: "Retry after a short delay; if timeouts persist, narrow the request with tighter filters to reduce upstream load.";
|
|
49
|
+
readonly thrownBy: "service";
|
|
47
50
|
}, {
|
|
48
51
|
readonly reason: "upstream_unavailable";
|
|
49
52
|
readonly code: JsonRpcErrorCode.ServiceUnavailable;
|
|
50
53
|
readonly when: "OpenAlex was unreachable or unusable — HTTP 503, a connection failure, or a body that was empty, HTML, or unparseable JSON.";
|
|
51
54
|
readonly retryable: true;
|
|
52
55
|
readonly recovery: "Wait and retry; check https://openalex.org for service status if the outage persists.";
|
|
56
|
+
readonly thrownBy: "service";
|
|
53
57
|
}, {
|
|
54
58
|
readonly reason: "upstream_unauthorized";
|
|
55
59
|
readonly code: JsonRpcErrorCode.Unauthorized;
|
|
56
60
|
readonly when: "OpenAlex rejected the API key (HTTP 401).";
|
|
57
61
|
readonly recovery: "Check that OPENALEX_API_KEY is set to a valid OpenAlex account API key (free from https://openalex.org/settings/api).";
|
|
62
|
+
readonly thrownBy: "service";
|
|
58
63
|
}, {
|
|
59
64
|
readonly reason: "upstream_forbidden";
|
|
60
65
|
readonly code: JsonRpcErrorCode.Forbidden;
|
|
61
66
|
readonly when: "OpenAlex denied access to the requested resource (HTTP 403).";
|
|
62
67
|
readonly recovery: "Confirm the API key has access to this entity type or endpoint, then retry the request.";
|
|
68
|
+
readonly thrownBy: "service";
|
|
63
69
|
}, {
|
|
64
70
|
readonly reason: "comma_in_filter_value";
|
|
65
71
|
readonly code: JsonRpcErrorCode.InvalidParams;
|
|
66
72
|
readonly when: "A filter value contains a comma, which collides with the OpenAlex filter separator.";
|
|
67
73
|
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.";
|
|
74
|
+
readonly thrownBy: "service";
|
|
68
75
|
}, {
|
|
69
76
|
readonly reason: "upstream_invalid_params";
|
|
70
77
|
readonly code: JsonRpcErrorCode.InvalidParams;
|
|
71
78
|
readonly when: "OpenAlex rejected an invalid filter or sort field name (HTTP 400).";
|
|
72
79
|
readonly 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.";
|
|
80
|
+
readonly thrownBy: "service";
|
|
73
81
|
}, {
|
|
74
82
|
readonly reason: "upstream_invalid_id_value";
|
|
75
83
|
readonly code: JsonRpcErrorCode.InvalidParams;
|
|
76
84
|
readonly when: "An entity-ID filter received a value that is not an OpenAlex ID — usually a name (HTTP 400).";
|
|
77
85
|
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 and primary_topic.id accept IDs only.";
|
|
86
|
+
readonly thrownBy: "service";
|
|
78
87
|
}, {
|
|
79
88
|
readonly reason: "upstream_sort_requires_search";
|
|
80
89
|
readonly code: JsonRpcErrorCode.InvalidParams;
|
|
81
90
|
readonly when: "sort=-relevance_score was used but the citation-graph query has no active search (HTTP 400).";
|
|
82
91
|
readonly 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.";
|
|
92
|
+
readonly thrownBy: "service";
|
|
83
93
|
}, {
|
|
84
94
|
readonly reason: "upstream_invalid_params_other";
|
|
85
95
|
readonly code: JsonRpcErrorCode.InvalidParams;
|
|
86
96
|
readonly when: "OpenAlex rejected the request (HTTP 400) for a reason other than an invalid field name.";
|
|
87
97
|
readonly recovery: "Read the upstream message in the error above and adjust the request — check filter operators, value formats, and cursor/per_page bounds.";
|
|
98
|
+
readonly thrownBy: "service";
|
|
88
99
|
}, {
|
|
89
100
|
readonly reason: "reserved_filter_key";
|
|
90
101
|
readonly code: JsonRpcErrorCode.ValidationError;
|
|
91
|
-
readonly when: "filters contains cites/cited_by/related_to — the direction parameter reserves those keys.";
|
|
102
|
+
readonly when: "filters contains cites/cited_by/related_to, or an alias of one such as cited_works — the direction parameter reserves those keys.";
|
|
92
103
|
readonly recovery: "Remove the reserved key from filters, or restate the relationship through direction.";
|
|
93
104
|
}, {
|
|
94
105
|
readonly reason: "entity_not_found";
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"citation-graph.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/citation-graph.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;
|
|
1
|
+
{"version":3,"file":"citation-graph.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/citation-graph.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AA2BjE,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmW/B,CAAC"}
|
|
@@ -6,24 +6,8 @@ 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
13
|
function buildCitationEcho(input) {
|
|
@@ -46,6 +30,7 @@ export const getCitationGraphTool = tool('openalex_get_citation_graph', {
|
|
|
46
30
|
when: 'OpenAlex throttled the request for exceeding its per-second ceiling (HTTP 429).',
|
|
47
31
|
retryable: true,
|
|
48
32
|
recovery: 'Wait several seconds and retry; consider lowering request frequency for this caller.',
|
|
33
|
+
thrownBy: 'service',
|
|
49
34
|
},
|
|
50
35
|
{
|
|
51
36
|
reason: 'upstream_budget_exhausted',
|
|
@@ -53,6 +38,7 @@ export const getCitationGraphTool = tool('openalex_get_citation_graph', {
|
|
|
53
38
|
when: 'The OpenAlex daily usage budget is spent (HTTP 429).',
|
|
54
39
|
retryable: false,
|
|
55
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',
|
|
56
42
|
},
|
|
57
43
|
{
|
|
58
44
|
reason: 'upstream_timeout',
|
|
@@ -60,6 +46,7 @@ export const getCitationGraphTool = tool('openalex_get_citation_graph', {
|
|
|
60
46
|
when: 'OpenAlex did not respond within the request deadline.',
|
|
61
47
|
retryable: true,
|
|
62
48
|
recovery: 'Retry after a short delay; if timeouts persist, narrow the request with tighter filters to reduce upstream load.',
|
|
49
|
+
thrownBy: 'service',
|
|
63
50
|
},
|
|
64
51
|
{
|
|
65
52
|
reason: 'upstream_unavailable',
|
|
@@ -67,53 +54,61 @@ export const getCitationGraphTool = tool('openalex_get_citation_graph', {
|
|
|
67
54
|
when: 'OpenAlex was unreachable or unusable — HTTP 503, a connection failure, or a body that was empty, HTML, or unparseable JSON.',
|
|
68
55
|
retryable: true,
|
|
69
56
|
recovery: 'Wait and retry; check https://openalex.org for service status if the outage persists.',
|
|
57
|
+
thrownBy: 'service',
|
|
70
58
|
},
|
|
71
59
|
{
|
|
72
60
|
reason: 'upstream_unauthorized',
|
|
73
61
|
code: JsonRpcErrorCode.Unauthorized,
|
|
74
62
|
when: 'OpenAlex rejected the API key (HTTP 401).',
|
|
75
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',
|
|
76
65
|
},
|
|
77
66
|
{
|
|
78
67
|
reason: 'upstream_forbidden',
|
|
79
68
|
code: JsonRpcErrorCode.Forbidden,
|
|
80
69
|
when: 'OpenAlex denied access to the requested resource (HTTP 403).',
|
|
81
70
|
recovery: 'Confirm the API key has access to this entity type or endpoint, then retry the request.',
|
|
71
|
+
thrownBy: 'service',
|
|
82
72
|
},
|
|
83
73
|
{
|
|
84
74
|
reason: 'comma_in_filter_value',
|
|
85
75
|
code: JsonRpcErrorCode.InvalidParams,
|
|
86
76
|
when: 'A filter value contains a comma, which collides with the OpenAlex filter separator.',
|
|
87
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',
|
|
88
79
|
},
|
|
89
80
|
{
|
|
90
81
|
reason: 'upstream_invalid_params',
|
|
91
82
|
code: JsonRpcErrorCode.InvalidParams,
|
|
92
83
|
when: 'OpenAlex rejected an invalid filter or sort field name (HTTP 400).',
|
|
93
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',
|
|
94
86
|
},
|
|
95
87
|
{
|
|
96
88
|
reason: 'upstream_invalid_id_value',
|
|
97
89
|
code: JsonRpcErrorCode.InvalidParams,
|
|
98
90
|
when: 'An entity-ID filter received a value that is not an OpenAlex ID — usually a name (HTTP 400).',
|
|
99
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',
|
|
100
93
|
},
|
|
101
94
|
{
|
|
102
95
|
reason: 'upstream_sort_requires_search',
|
|
103
96
|
code: JsonRpcErrorCode.InvalidParams,
|
|
104
97
|
when: 'sort=-relevance_score was used but the citation-graph query has no active search (HTTP 400).',
|
|
105
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',
|
|
106
100
|
},
|
|
107
101
|
{
|
|
108
102
|
reason: 'upstream_invalid_params_other',
|
|
109
103
|
code: JsonRpcErrorCode.InvalidParams,
|
|
110
104
|
when: 'OpenAlex rejected the request (HTTP 400) for a reason other than an invalid field name.',
|
|
111
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',
|
|
112
107
|
},
|
|
113
108
|
{
|
|
114
109
|
reason: 'reserved_filter_key',
|
|
115
110
|
code: JsonRpcErrorCode.ValidationError,
|
|
116
|
-
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.',
|
|
117
112
|
recovery: 'Remove the reserved key from filters, or restate the relationship through direction.',
|
|
118
113
|
},
|
|
119
114
|
{
|
|
@@ -123,6 +118,7 @@ export const getCitationGraphTool = tool('openalex_get_citation_graph', {
|
|
|
123
118
|
recovery: 'Verify seed_id with openalex_resolve_name, or pass a known OpenAlex work ID (W…), DOI, or PMID. OpenAlex indexes no PMCIDs, so convert a PMCID to a PMID or DOI before passing it.',
|
|
124
119
|
},
|
|
125
120
|
],
|
|
121
|
+
inputAliases: { filter: 'filters' },
|
|
126
122
|
input: z.object({
|
|
127
123
|
seed_id: z
|
|
128
124
|
.string()
|
|
@@ -134,7 +130,7 @@ export const getCitationGraphTool = tool('openalex_get_citation_graph', {
|
|
|
134
130
|
filters: z
|
|
135
131
|
.record(z.string(), z.string())
|
|
136
132
|
.optional()
|
|
137
|
-
.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.'),
|
|
138
134
|
sort: z
|
|
139
135
|
.string()
|
|
140
136
|
.optional()
|
|
@@ -152,8 +148,9 @@ export const getCitationGraphTool = tool('openalex_get_citation_graph', {
|
|
|
152
148
|
.describe('Results per page (1-100). Default 25.'),
|
|
153
149
|
cursor: z
|
|
154
150
|
.string()
|
|
151
|
+
.min(1)
|
|
155
152
|
.optional()
|
|
156
|
-
.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.'),
|
|
157
154
|
}),
|
|
158
155
|
output: z.object({
|
|
159
156
|
meta: z
|
|
@@ -161,7 +158,9 @@ export const getCitationGraphTool = tool('openalex_get_citation_graph', {
|
|
|
161
158
|
count: z
|
|
162
159
|
.number()
|
|
163
160
|
.describe('Total edges from seed_id in this direction (across all pages).'),
|
|
164
|
-
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.'),
|
|
165
164
|
next_cursor: z
|
|
166
165
|
.string()
|
|
167
166
|
.nullable()
|
|
@@ -192,7 +191,7 @@ export const getCitationGraphTool = tool('openalex_get_citation_graph', {
|
|
|
192
191
|
notice: z
|
|
193
192
|
.string()
|
|
194
193
|
.optional()
|
|
195
|
-
.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.'),
|
|
196
195
|
budget: z
|
|
197
196
|
.object({
|
|
198
197
|
costUsd: z
|
|
@@ -216,18 +215,37 @@ export const getCitationGraphTool = tool('openalex_get_citation_graph', {
|
|
|
216
215
|
budget: { render: renderBudgetTrailer },
|
|
217
216
|
},
|
|
218
217
|
async handler(input, ctx) {
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
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
|
+
});
|
|
228
233
|
}
|
|
229
234
|
const service = getOpenAlexService();
|
|
230
|
-
|
|
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, '');
|
|
231
249
|
const mergedFilters = {
|
|
232
250
|
...(input.filters ?? {}),
|
|
233
251
|
[input.direction]: workId,
|
|
@@ -248,8 +266,12 @@ export const getCitationGraphTool = tool('openalex_get_citation_graph', {
|
|
|
248
266
|
});
|
|
249
267
|
const echo = buildCitationEcho(input);
|
|
250
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.
|
|
251
271
|
if (result.results.length === 0) {
|
|
252
|
-
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.`);
|
|
253
275
|
}
|
|
254
276
|
return {
|
|
255
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"}
|