toolmenu 0.12.0 → 0.14.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +84 -23
- package/dist/args.d.ts +31 -5
- package/dist/args.js +91 -14
- package/dist/auth.d.ts +4 -2
- package/dist/auth.js +59 -21
- package/dist/auto.d.ts +80 -6
- package/dist/auto.js +255 -19
- package/dist/breakdown.d.ts +2 -0
- package/dist/breakdown.js +64 -19
- package/dist/catalog.d.ts +87 -10
- package/dist/catalog.js +415 -58
- package/dist/cli.js +170 -185
- package/dist/close.d.ts +8 -0
- package/dist/close.js +18 -0
- package/dist/config.d.ts +7 -1
- package/dist/config.js +17 -0
- package/dist/connect.d.ts +14 -0
- package/dist/connect.js +150 -16
- package/dist/diff.d.ts +23 -1
- package/dist/diff.js +574 -120
- package/dist/difference.d.ts +2 -0
- package/dist/difference.js +13 -12
- package/dist/explain.d.ts +113 -0
- package/dist/explain.js +461 -0
- package/dist/failures.d.ts +15 -0
- package/dist/failures.js +59 -2
- package/dist/help.d.ts +11 -0
- package/dist/help.js +205 -0
- package/dist/history.d.ts +13 -0
- package/dist/history.js +86 -6
- package/dist/init.d.ts +93 -2
- package/dist/init.js +508 -21
- package/dist/menu.js +10 -2
- package/dist/options.d.ts +141 -0
- package/dist/options.js +50 -0
- package/dist/report.d.ts +2 -2
- package/dist/report.js +305 -101
- package/dist/rules/description.d.ts +7 -2
- package/dist/rules/description.js +86 -42
- package/dist/rules/determinism.d.ts +4 -1
- package/dist/rules/determinism.js +175 -11
- package/dist/rules/gated.d.ts +7 -0
- package/dist/rules/gated.js +77 -0
- package/dist/rules/ids.d.ts +1 -1
- package/dist/rules/ids.js +9 -4
- package/dist/rules/index.d.ts +6 -0
- package/dist/rules/index.js +18 -6
- package/dist/rules/naming.d.ts +1 -1
- package/dist/rules/naming.js +91 -21
- package/dist/rules/rule.d.ts +25 -0
- package/dist/rules/rule.js +25 -1
- package/dist/rules/spec.d.ts +6 -0
- package/dist/rules/spec.js +56 -9
- package/dist/rules/write.d.ts +1 -1
- package/dist/rules/write.js +64 -14
- package/dist/session.d.ts +34 -9
- package/dist/session.js +525 -94
- package/dist/snapshot.d.ts +8 -2
- package/dist/snapshot.js +33 -2
- package/dist/types.d.ts +21 -0
- package/dist/words.d.ts +5 -0
- package/dist/words.js +14 -0
- package/package.json +2 -2
package/dist/difference.d.ts
CHANGED
|
@@ -9,6 +9,8 @@ export interface Difference {
|
|
|
9
9
|
}
|
|
10
10
|
/** The first leaf where two values differ, depth first, keys in sorted order. Undefined when equal. */
|
|
11
11
|
export declare function firstDifference(a: unknown, b: unknown, path?: string): Difference | undefined;
|
|
12
|
+
/** Every leaf where two values differ, in the order firstDifference finds them. */
|
|
13
|
+
export declare function allDifferences(a: unknown, b: unknown, path?: string, out?: Difference[]): Difference[];
|
|
12
14
|
/**
|
|
13
15
|
* One line saying what differs in a tool between two menus, for a finding's
|
|
14
16
|
* detail: `jira_get_issue: inputSchema.properties.fields.default: same 11 items,
|
package/dist/difference.js
CHANGED
|
@@ -2,23 +2,24 @@ import { canonical } from './compare.js';
|
|
|
2
2
|
import { toolDefinition } from './menu.js';
|
|
3
3
|
/** The first leaf where two values differ, depth first, keys in sorted order. Undefined when equal. */
|
|
4
4
|
export function firstDifference(a, b, path = '') {
|
|
5
|
+
return allDifferences(a, b, path)[0];
|
|
6
|
+
}
|
|
7
|
+
/** Every leaf where two values differ, in the order firstDifference finds them. */
|
|
8
|
+
export function allDifferences(a, b, path = '', out = []) {
|
|
5
9
|
if (canonical(a) === canonical(b))
|
|
6
|
-
return
|
|
10
|
+
return out;
|
|
11
|
+
const before = out.length;
|
|
7
12
|
if (isObject(a) && isObject(b)) {
|
|
8
|
-
for (const key of [...new Set([...Object.keys(a), ...Object.keys(b)])].sort())
|
|
9
|
-
|
|
10
|
-
if (found)
|
|
11
|
-
return found;
|
|
12
|
-
}
|
|
13
|
+
for (const key of [...new Set([...Object.keys(a), ...Object.keys(b)])].sort())
|
|
14
|
+
allDifferences(a[key], b[key], join(path, key), out);
|
|
13
15
|
}
|
|
14
16
|
if (Array.isArray(a) && Array.isArray(b) && a.length === b.length && !samePermutation(a, b)) {
|
|
15
|
-
for (let i = 0; i < a.length; i++)
|
|
16
|
-
|
|
17
|
-
if (found)
|
|
18
|
-
return found;
|
|
19
|
-
}
|
|
17
|
+
for (let i = 0; i < a.length; i++)
|
|
18
|
+
allDifferences(a[i], b[i], `${path}[${i}]`, out);
|
|
20
19
|
}
|
|
21
|
-
|
|
20
|
+
if (out.length === before)
|
|
21
|
+
out.push({ path, before: a, after: b, reordered: samePermutation(a, b) });
|
|
22
|
+
return out;
|
|
22
23
|
}
|
|
23
24
|
/** Different order, same items: arrays, or strings that are comma-separated lists. */
|
|
24
25
|
function samePermutation(a, b) {
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
import type { ChildProcess } from 'node:child_process';
|
|
2
|
+
/** What connect() saw on the way to an error. */
|
|
3
|
+
export declare class Trace {
|
|
4
|
+
readonly startedAt: number;
|
|
5
|
+
/** stdio: when the process toolmenu keeps was started (after the server/discover probe, which runs on its own process). */
|
|
6
|
+
sessionStartedAt?: number;
|
|
7
|
+
/** Requests sent, in order, with when (ms since epoch). */
|
|
8
|
+
readonly sent: {
|
|
9
|
+
method: string;
|
|
10
|
+
at: number;
|
|
11
|
+
}[];
|
|
12
|
+
/** Methods that got an answer (a result or a JSON-RPC error). */
|
|
13
|
+
readonly answered: Set<string>;
|
|
14
|
+
/** HTTP: the last response to each method (status, content type, final URL). */
|
|
15
|
+
readonly http: Map<string, {
|
|
16
|
+
status: number;
|
|
17
|
+
statusText: string;
|
|
18
|
+
contentType: string;
|
|
19
|
+
url: string;
|
|
20
|
+
}>;
|
|
21
|
+
process?: ChildProcess;
|
|
22
|
+
/** How the process ended. `afterStop`: it ended after toolmenu sent it SIGTERM, so the exit may be toolmenu's doing. */
|
|
23
|
+
exit?: {
|
|
24
|
+
code: number | null;
|
|
25
|
+
signal: string | null;
|
|
26
|
+
afterStop?: boolean;
|
|
27
|
+
};
|
|
28
|
+
/** When connecting failed, before toolmenu stopped the server and read the rest of its stderr. */
|
|
29
|
+
failedAt?: number;
|
|
30
|
+
/** toolmenu sent the process SIGTERM (connecting had already failed). */
|
|
31
|
+
stopped: boolean;
|
|
32
|
+
/** stdout lines that aren't JSON-RPC: the first few, and how many in all. */
|
|
33
|
+
readonly stray: string[];
|
|
34
|
+
strayCount: number;
|
|
35
|
+
private stdoutPartial;
|
|
36
|
+
/** The last stderr lines, and how many there were in all. */
|
|
37
|
+
readonly stderrTail: string[];
|
|
38
|
+
stderrLines: number;
|
|
39
|
+
private stderrPartial;
|
|
40
|
+
send(method: string): void;
|
|
41
|
+
/** A chunk of the server's stdout: remembers lines that aren't JSON-RPC messages. */
|
|
42
|
+
stdout(chunk: string): void;
|
|
43
|
+
stderr(chunk: string): void;
|
|
44
|
+
private pushStderr;
|
|
45
|
+
/** The stderr tail, the unfinished last line included. */
|
|
46
|
+
stderrExcerpt(): {
|
|
47
|
+
lines: string[];
|
|
48
|
+
total: number;
|
|
49
|
+
};
|
|
50
|
+
/** The last request sent that got no answer. */
|
|
51
|
+
pending(): {
|
|
52
|
+
method: string;
|
|
53
|
+
at: number;
|
|
54
|
+
} | undefined;
|
|
55
|
+
}
|
|
56
|
+
/** How many of the server's last stderr lines an error shows: errors are at the end. */
|
|
57
|
+
export declare const STDERR_LINES = 12;
|
|
58
|
+
/** An error that already says what happened, where, and what to do. */
|
|
59
|
+
export declare class ConnectError extends Error {
|
|
60
|
+
readonly headline: string;
|
|
61
|
+
readonly facts: [string, string][];
|
|
62
|
+
readonly next: string | undefined;
|
|
63
|
+
readonly stage: string;
|
|
64
|
+
/** The HTTP status, when the server answered with one (read by tooMany and the action). */
|
|
65
|
+
status?: number;
|
|
66
|
+
constructor(headline: string, facts: [string, string][], next: string | undefined, stage: string, options?: {
|
|
67
|
+
cause?: unknown;
|
|
68
|
+
status?: number;
|
|
69
|
+
});
|
|
70
|
+
}
|
|
71
|
+
/** A headline, then aligned facts, then the next step. Multi-line facts are indented under their label. */
|
|
72
|
+
export declare function formatBlock(headline: string, facts: [string, string][], next?: string): string;
|
|
73
|
+
/** Printable text: no ANSI colours or control characters, at most `max` characters. */
|
|
74
|
+
export declare function clean(text: string, max: number): string;
|
|
75
|
+
/** "5.0 s", "0.3 s", "62 s". */
|
|
76
|
+
export declare function seconds(ms: number): string;
|
|
77
|
+
/** The command line, for a message: arguments with spaces quoted, cut at 120 characters. Never the --env values. */
|
|
78
|
+
export declare function commandLine(command: string, args: string[]): string;
|
|
79
|
+
/** The stderr fact: the last lines, and a note of how many came before. */
|
|
80
|
+
export declare function stderrFact(trace: Trace): [string, string];
|
|
81
|
+
/** A request header that carries credentials: Authorization, a cookie, or a name with key, token, secret or auth in it (x-mcp-api-key). */
|
|
82
|
+
export declare function isCredentialHeader(name: string): boolean;
|
|
83
|
+
/**
|
|
84
|
+
* The header a refusal names ("missing or invalid x-mcp-api-key header",
|
|
85
|
+
* "header 'X-Api-Key' required"), lower-cased. Only Authorization, or a hyphenated name
|
|
86
|
+
* that carries credentials (x-api-key): "the header" and "content-type header" aren't asked for.
|
|
87
|
+
*/
|
|
88
|
+
export declare function namedHeader(body: string | undefined): string | undefined;
|
|
89
|
+
/** A short, readable excerpt of a response body: an HTML page's title or first words, JSON's message. Never the whole body. */
|
|
90
|
+
export declare function bodyExcerpt(body: string | undefined, max?: number): string | undefined;
|
|
91
|
+
export interface ExplainContext {
|
|
92
|
+
target: {
|
|
93
|
+
kind: 'stdio';
|
|
94
|
+
command: string;
|
|
95
|
+
args: string[];
|
|
96
|
+
} | {
|
|
97
|
+
kind: 'http';
|
|
98
|
+
url: string;
|
|
99
|
+
headers?: Record<string, string>;
|
|
100
|
+
};
|
|
101
|
+
timeoutMs?: number;
|
|
102
|
+
/** A stored OAuth login was used. */
|
|
103
|
+
oauth?: boolean;
|
|
104
|
+
/** The stage when it isn't the connect handshake (tools/list). */
|
|
105
|
+
stage?: string;
|
|
106
|
+
/** --protocol, when it isn't auto. */
|
|
107
|
+
protocol?: 'legacy' | 'modern';
|
|
108
|
+
}
|
|
109
|
+
/**
|
|
110
|
+
* The error as a ConnectError that says what happened, or the error unchanged
|
|
111
|
+
* when there's nothing to add (a refusal for too many requests keeps its own path).
|
|
112
|
+
*/
|
|
113
|
+
export declare function explain(error: unknown, trace: Trace, context: ExplainContext): unknown;
|
package/dist/explain.js
ADDED
|
@@ -0,0 +1,461 @@
|
|
|
1
|
+
import { ProtocolError, SdkError, SdkErrorCode } from '@modelcontextprotocol/client';
|
|
2
|
+
import { LoginNeededError } from './auth.js';
|
|
3
|
+
/** What connect() saw on the way to an error. */
|
|
4
|
+
export class Trace {
|
|
5
|
+
startedAt = Date.now();
|
|
6
|
+
/** stdio: when the process toolmenu keeps was started (after the server/discover probe, which runs on its own process). */
|
|
7
|
+
sessionStartedAt;
|
|
8
|
+
/** Requests sent, in order, with when (ms since epoch). */
|
|
9
|
+
sent = [];
|
|
10
|
+
/** Methods that got an answer (a result or a JSON-RPC error). */
|
|
11
|
+
answered = new Set();
|
|
12
|
+
/** HTTP: the last response to each method (status, content type, final URL). */
|
|
13
|
+
http = new Map();
|
|
14
|
+
process;
|
|
15
|
+
/** How the process ended. `afterStop`: it ended after toolmenu sent it SIGTERM, so the exit may be toolmenu's doing. */
|
|
16
|
+
exit;
|
|
17
|
+
/** When connecting failed, before toolmenu stopped the server and read the rest of its stderr. */
|
|
18
|
+
failedAt;
|
|
19
|
+
/** toolmenu sent the process SIGTERM (connecting had already failed). */
|
|
20
|
+
stopped = false;
|
|
21
|
+
/** stdout lines that aren't JSON-RPC: the first few, and how many in all. */
|
|
22
|
+
stray = [];
|
|
23
|
+
strayCount = 0;
|
|
24
|
+
stdoutPartial = '';
|
|
25
|
+
/** The last stderr lines, and how many there were in all. */
|
|
26
|
+
stderrTail = [];
|
|
27
|
+
stderrLines = 0;
|
|
28
|
+
stderrPartial = '';
|
|
29
|
+
send(method) {
|
|
30
|
+
this.sent.push({ method, at: Date.now() });
|
|
31
|
+
}
|
|
32
|
+
/** A chunk of the server's stdout: remembers lines that aren't JSON-RPC messages. */
|
|
33
|
+
stdout(chunk) {
|
|
34
|
+
if (this.strayCount >= 1000)
|
|
35
|
+
return;
|
|
36
|
+
const lines = (this.stdoutPartial + chunk).split('\n');
|
|
37
|
+
const last = lines.pop() ?? '';
|
|
38
|
+
// A JSON-RPC line can be megabytes (a big tools/list): only its start matters here.
|
|
39
|
+
this.stdoutPartial = last.length > 4096 ? last.slice(0, 4096) : last;
|
|
40
|
+
for (const raw of lines) {
|
|
41
|
+
const line = raw.trim();
|
|
42
|
+
if (!line)
|
|
43
|
+
continue;
|
|
44
|
+
// JSON-RPC over stdio is one JSON object per line. A JSON log line (pino) is
|
|
45
|
+
// an object too, but without "jsonrpc".
|
|
46
|
+
if (line.startsWith('{') && line.slice(0, 4096).includes('"jsonrpc"'))
|
|
47
|
+
continue;
|
|
48
|
+
this.strayCount++;
|
|
49
|
+
if (this.stray.length < 2)
|
|
50
|
+
this.stray.push(clean(line, 160));
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
stderr(chunk) {
|
|
54
|
+
const lines = (this.stderrPartial + chunk).split('\n');
|
|
55
|
+
this.stderrPartial = (lines.pop() ?? '').slice(-2000);
|
|
56
|
+
for (const line of lines)
|
|
57
|
+
this.pushStderr(line);
|
|
58
|
+
}
|
|
59
|
+
pushStderr(line) {
|
|
60
|
+
const text = clean(line, 240);
|
|
61
|
+
if (!text)
|
|
62
|
+
return;
|
|
63
|
+
this.stderrLines++;
|
|
64
|
+
this.stderrTail.push(text);
|
|
65
|
+
if (this.stderrTail.length > STDERR_LINES)
|
|
66
|
+
this.stderrTail.shift();
|
|
67
|
+
}
|
|
68
|
+
/** The stderr tail, the unfinished last line included. */
|
|
69
|
+
stderrExcerpt() {
|
|
70
|
+
const partial = clean(this.stderrPartial, 240);
|
|
71
|
+
const lines = partial ? [...this.stderrTail, partial].slice(-STDERR_LINES) : this.stderrTail;
|
|
72
|
+
return { lines, total: this.stderrLines + (partial ? 1 : 0) };
|
|
73
|
+
}
|
|
74
|
+
/** The last request sent that got no answer. */
|
|
75
|
+
pending() {
|
|
76
|
+
for (let i = this.sent.length - 1; i >= 0; i--)
|
|
77
|
+
if (!this.answered.has(this.sent[i].method))
|
|
78
|
+
return this.sent[i];
|
|
79
|
+
return undefined;
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
/** How many of the server's last stderr lines an error shows: errors are at the end. */
|
|
83
|
+
export const STDERR_LINES = 12;
|
|
84
|
+
/** An error that already says what happened, where, and what to do. */
|
|
85
|
+
export class ConnectError extends Error {
|
|
86
|
+
headline;
|
|
87
|
+
facts;
|
|
88
|
+
next;
|
|
89
|
+
stage;
|
|
90
|
+
/** The HTTP status, when the server answered with one (read by tooMany and the action). */
|
|
91
|
+
status;
|
|
92
|
+
constructor(headline, facts, next, stage, options = {}) {
|
|
93
|
+
super(formatBlock(headline, facts, next), { cause: options.cause });
|
|
94
|
+
this.headline = headline;
|
|
95
|
+
this.facts = facts;
|
|
96
|
+
this.next = next;
|
|
97
|
+
this.stage = stage;
|
|
98
|
+
this.name = 'ConnectError';
|
|
99
|
+
if (options.status !== undefined)
|
|
100
|
+
this.status = options.status;
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
/** A headline, then aligned facts, then the next step. Multi-line facts are indented under their label. */
|
|
104
|
+
export function formatBlock(headline, facts, next) {
|
|
105
|
+
const width = Math.max(0, ...facts.map(([label]) => label.length));
|
|
106
|
+
const lines = [headline];
|
|
107
|
+
for (const [label, value] of facts) {
|
|
108
|
+
const [first, ...more] = value.split('\n');
|
|
109
|
+
lines.push(` ${label.padEnd(width)} ${first}`);
|
|
110
|
+
for (const line of more)
|
|
111
|
+
lines.push(` ${' '.repeat(width)} ${line}`);
|
|
112
|
+
}
|
|
113
|
+
if (next)
|
|
114
|
+
lines.push(` → Next: ${next}`);
|
|
115
|
+
return lines.join('\n');
|
|
116
|
+
}
|
|
117
|
+
/** Printable text: no ANSI colours or control characters, at most `max` characters. */
|
|
118
|
+
export function clean(text, max) {
|
|
119
|
+
// eslint-disable-next-line no-control-regex
|
|
120
|
+
const plain = text.replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, '').replace(/[\x00-\x08\x0b-\x1f\x7f]/g, '').trimEnd();
|
|
121
|
+
return plain.length > max ? `${plain.slice(0, max - 1)}…` : plain;
|
|
122
|
+
}
|
|
123
|
+
/** "5.0 s", "0.3 s", "62 s". */
|
|
124
|
+
export function seconds(ms) {
|
|
125
|
+
return `${ms < 10_000 ? (Math.round(ms / 100) / 10).toFixed(1) : Math.round(ms / 1000)} s`;
|
|
126
|
+
}
|
|
127
|
+
/** The command line, for a message: arguments with spaces quoted, cut at 120 characters. Never the --env values. */
|
|
128
|
+
export function commandLine(command, args) {
|
|
129
|
+
const quoted = [command, ...args].map((a) => (/^[\w@%+=:,./-]+$/.test(a) ? a : `'${a.replace(/'/g, `'\\''`)}'`)).join(' ');
|
|
130
|
+
return quoted.length > 120 ? `${quoted.slice(0, 119)}…` : quoted;
|
|
131
|
+
}
|
|
132
|
+
/** The stderr fact: the last lines, and a note of how many came before. */
|
|
133
|
+
export function stderrFact(trace) {
|
|
134
|
+
const { lines, total } = trace.stderrExcerpt();
|
|
135
|
+
if (!lines.length)
|
|
136
|
+
return ['stderr', '(nothing)'];
|
|
137
|
+
const cut = total - lines.length;
|
|
138
|
+
const header = cut > 0 ? `last ${lines.length} of ${total} lines (${cut} earlier lines not shown)` : `${total} line${total === 1 ? '' : 's'}`;
|
|
139
|
+
return ['stderr', [header, ...lines.map((l) => `│ ${l}`)].join('\n')];
|
|
140
|
+
}
|
|
141
|
+
function strayFact(trace) {
|
|
142
|
+
const quoted = trace.stray.map((l) => `“${l}”`).join('\n');
|
|
143
|
+
const more = trace.strayCount > trace.stray.length ? `\n(${trace.strayCount} such lines in all)` : '';
|
|
144
|
+
return ['stdout', `${quoted}${more}`];
|
|
145
|
+
}
|
|
146
|
+
const LOG_TO_STDERR = 'Log to stderr; stdout carries the protocol (in Node, console.error rather than console.log; in Python, logging or print(..., file=sys.stderr)).';
|
|
147
|
+
/** The error codes along an error's cause chain, innermost last. */
|
|
148
|
+
function causes(error) {
|
|
149
|
+
const out = [];
|
|
150
|
+
let e = error;
|
|
151
|
+
for (let i = 0; i < 6 && e instanceof Error; i++) {
|
|
152
|
+
out.push(e);
|
|
153
|
+
const next = e.cause ?? e.data?.cause;
|
|
154
|
+
if (next === e)
|
|
155
|
+
break;
|
|
156
|
+
e = next;
|
|
157
|
+
}
|
|
158
|
+
return out;
|
|
159
|
+
}
|
|
160
|
+
const STATUS_TEXT = {
|
|
161
|
+
400: 'Bad Request', 401: 'Unauthorized', 403: 'Forbidden', 404: 'Not Found', 405: 'Method Not Allowed', 406: 'Not Acceptable',
|
|
162
|
+
408: 'Request Timeout', 410: 'Gone', 415: 'Unsupported Media Type', 500: 'Internal Server Error', 502: 'Bad Gateway',
|
|
163
|
+
503: 'Service Unavailable', 504: 'Gateway Timeout',
|
|
164
|
+
};
|
|
165
|
+
const CREDENTIAL_WORDS = new Set(['authorization', 'cookie', 'key', 'apikey', 'token', 'secret', 'auth', 'password']);
|
|
166
|
+
/** A request header that carries credentials: Authorization, a cookie, or a name with key, token, secret or auth in it (x-mcp-api-key). */
|
|
167
|
+
export function isCredentialHeader(name) {
|
|
168
|
+
return name.toLowerCase().split(/[-_]/).some((w) => CREDENTIAL_WORDS.has(w));
|
|
169
|
+
}
|
|
170
|
+
/**
|
|
171
|
+
* The header a refusal names ("missing or invalid x-mcp-api-key header",
|
|
172
|
+
* "header 'X-Api-Key' required"), lower-cased. Only Authorization, or a hyphenated name
|
|
173
|
+
* that carries credentials (x-api-key): "the header" and "content-type header" aren't asked for.
|
|
174
|
+
*/
|
|
175
|
+
export function namedHeader(body) {
|
|
176
|
+
if (!body)
|
|
177
|
+
return undefined;
|
|
178
|
+
const name = /\b([A-Za-z][\w-]*)["'`]?\s+header\b/i.exec(body)?.[1] ?? /\bheader\s*[:(]?\s*["'`]?([A-Za-z][\w-]*)/i.exec(body)?.[1];
|
|
179
|
+
if (!name)
|
|
180
|
+
return undefined;
|
|
181
|
+
const lower = name.toLowerCase();
|
|
182
|
+
return lower === 'authorization' || (/-/.test(lower) && isCredentialHeader(lower)) ? lower : undefined;
|
|
183
|
+
}
|
|
184
|
+
/** A short, readable excerpt of a response body: an HTML page's title or first words, JSON's message. Never the whole body. */
|
|
185
|
+
export function bodyExcerpt(body, max = 100) {
|
|
186
|
+
if (!body?.trim())
|
|
187
|
+
return undefined;
|
|
188
|
+
const title = /<title[^>]*>([^<]*)<\/title>/i.exec(body)?.[1];
|
|
189
|
+
let text = title ?? body;
|
|
190
|
+
if (!title && /<[a-z!][^>]*>/i.test(body)) {
|
|
191
|
+
text = body.replace(/<(script|style)[^>]*>[\s\S]*?<\/\1>/gi, ' ').replace(/<[^>]+>/g, ' ');
|
|
192
|
+
}
|
|
193
|
+
const message = /"(?:message|error_description|error|detail)"\s*:\s*"((?:[^"\\]|\\.){1,300})"/.exec(text)?.[1];
|
|
194
|
+
if (message)
|
|
195
|
+
text = message.replace(/\\(.)/g, '$1');
|
|
196
|
+
text = text.replace(/ /g, ' ').replace(/&/g, '&').replace(/</g, '<').replace(/>/g, '>').replace(/"/g, '"').replace(/'/g, "'").replace(/\s+/g, ' ').trim();
|
|
197
|
+
return text ? clean(text, max) : undefined;
|
|
198
|
+
}
|
|
199
|
+
/**
|
|
200
|
+
* The error as a ConnectError that says what happened, or the error unchanged
|
|
201
|
+
* when there's nothing to add (a refusal for too many requests keeps its own path).
|
|
202
|
+
*/
|
|
203
|
+
export function explain(error, trace, context) {
|
|
204
|
+
if (error instanceof ConnectError || !(error instanceof Error))
|
|
205
|
+
return error;
|
|
206
|
+
// A stored OAuth login that can't be used already says why, and what to run.
|
|
207
|
+
const login = causes(error).find((e) => e instanceof LoginNeededError);
|
|
208
|
+
if (login)
|
|
209
|
+
return login;
|
|
210
|
+
// --protocol modern on a server without server/discover: the choice failed, not the connection.
|
|
211
|
+
if (context.protocol === 'modern' && causes(error).some((e) => /did not offer pinned protocol version|Version negotiation failed/i.test(e.message))) {
|
|
212
|
+
const where = context.target.kind === 'stdio' ? commandLine(context.target.command, context.target.args) : context.target.url;
|
|
213
|
+
return new ConnectError("The server doesn't speak the 2026-07-28 protocol, and --protocol modern allows nothing else.", [['server', where], ['stage', 'server/discover']], 'Drop --protocol (or use --protocol auto) to fall back to the 2025 handshake, or --protocol legacy to check it as a 2025 server on purpose.', 'server/discover', { cause: error });
|
|
214
|
+
}
|
|
215
|
+
return context.target.kind === 'stdio' ? explainStdio(error, trace, context, context.target) : explainHttp(error, trace, context, context.target);
|
|
216
|
+
}
|
|
217
|
+
/**
|
|
218
|
+
* What kind of failure this is. The SDK's own types come first: a JSON-RPC error
|
|
219
|
+
* response is the server's answer, whatever its words say ("upstream request
|
|
220
|
+
* timed out"). The words are read only for errors that aren't typed.
|
|
221
|
+
*/
|
|
222
|
+
function failureKind(error) {
|
|
223
|
+
for (const e of causes(error)) {
|
|
224
|
+
if (e instanceof ProtocolError)
|
|
225
|
+
return 'server';
|
|
226
|
+
if (e instanceof SdkError) {
|
|
227
|
+
if (e.code === SdkErrorCode.RequestTimeout)
|
|
228
|
+
return 'timeout';
|
|
229
|
+
if (e.code === SdkErrorCode.ConnectionClosed)
|
|
230
|
+
return 'closed';
|
|
231
|
+
return undefined;
|
|
232
|
+
}
|
|
233
|
+
}
|
|
234
|
+
if (/connection closed/i.test(error.message))
|
|
235
|
+
return 'closed';
|
|
236
|
+
if (/timed out|timeout/i.test(error.message))
|
|
237
|
+
return 'timeout';
|
|
238
|
+
return undefined;
|
|
239
|
+
}
|
|
240
|
+
/** The server's JSON-RPC error answer, said as such: its words and its code. */
|
|
241
|
+
function serverAnswered(error, stage, facts, next) {
|
|
242
|
+
const protocol = causes(error).find((e) => e instanceof ProtocolError);
|
|
243
|
+
const words = firstLine((protocol ?? error).message.replace(/^MCP error -?\d+:\s*/, ''));
|
|
244
|
+
const code = typeof protocol?.code === 'number' ? ` (${protocol.code})` : '';
|
|
245
|
+
return new ConnectError(`The server answered ${stage} with an error: “${words}”${code}.`, facts, next, stage, { cause: error });
|
|
246
|
+
}
|
|
247
|
+
function explainStdio(error, trace, context, target) {
|
|
248
|
+
const command = commandLine(target.command, target.args);
|
|
249
|
+
const spawnError = causes(error).find((e) => typeof e.syscall === 'string' && e.syscall.startsWith('spawn'));
|
|
250
|
+
if (spawnError) {
|
|
251
|
+
const code = spawnError.code;
|
|
252
|
+
if (code === 'ENOENT') {
|
|
253
|
+
return new ConnectError(`Couldn't start the server: “${target.command}” wasn't found (spawn ENOENT).`, [['command', command]], `Check it's installed and on PATH (which ${target.command}), or give its full path. The server gets a minimal environment: PATH comes from toolmenu's, or from --env PATH=….`, 'starting the server', { cause: error });
|
|
254
|
+
}
|
|
255
|
+
if (code === 'EACCES') {
|
|
256
|
+
return new ConnectError(`Couldn't start the server: “${target.command}” isn't executable (spawn EACCES).`, [['command', command]], `Make it executable (chmod +x ${target.command}), or run it through its interpreter (node, python3, uv run).`, 'starting the server', { cause: error });
|
|
257
|
+
}
|
|
258
|
+
return new ConnectError(`Couldn't start the server: ${error.message}.`, [['command', command]], `Run the command yourself to check it starts: ${command}`, 'starting the server', { cause: error });
|
|
259
|
+
}
|
|
260
|
+
const kind = failureKind(error);
|
|
261
|
+
const pending = trace.pending();
|
|
262
|
+
const facts = [['server', command]];
|
|
263
|
+
if (kind === 'server') {
|
|
264
|
+
// Its answer is the last request sent, so not pending any more.
|
|
265
|
+
const stage = context.stage ?? trace.sent.at(-1)?.method ?? (trace.sessionStartedAt ? 'initialize' : 'server/discover');
|
|
266
|
+
if (trace.strayCount)
|
|
267
|
+
facts.push(strayFact(trace));
|
|
268
|
+
facts.push(stderrFact(trace));
|
|
269
|
+
return serverAnswered(error, stage, facts, `That's the server's own error, not the connection: fix what it says (its stderr may say more), or retry if the cause upstream has passed. To see it yourself, run: ${command}`);
|
|
270
|
+
}
|
|
271
|
+
const stage = context.stage ?? pending?.method ?? (trace.sessionStartedAt ? 'initialize' : 'server/discover');
|
|
272
|
+
// An exit after toolmenu's own SIGTERM is toolmenu's doing, not the server's, when
|
|
273
|
+
// the request had already timed out or the process died of that very signal.
|
|
274
|
+
const ours = trace.exit?.afterStop && (kind === 'timeout' || trace.exit.signal === 'SIGTERM' || trace.exit.code === 143);
|
|
275
|
+
const exit = ours ? undefined : trace.exit;
|
|
276
|
+
const closed = kind === 'closed';
|
|
277
|
+
if (exit || closed) {
|
|
278
|
+
const how = !exit
|
|
279
|
+
? 'closed its stdout'
|
|
280
|
+
: exit.signal
|
|
281
|
+
? `was killed by ${exit.signal}${exit.signal === 'SIGKILL' ? ' (out of memory, or killed from outside)' : ''}`
|
|
282
|
+
: `exited with code ${exit.code}`;
|
|
283
|
+
if (trace.strayCount)
|
|
284
|
+
facts.push(strayFact(trace));
|
|
285
|
+
facts.push(stderrFact(trace));
|
|
286
|
+
const stderrText = trace.stderrExcerpt().lines.join('\n');
|
|
287
|
+
const rejected = rejectedCredentials(stderrText);
|
|
288
|
+
let next;
|
|
289
|
+
if (/cannot find (module|package)|ERR_MODULE_NOT_FOUND|ModuleNotFoundError|No module named/i.test(stderrText)) {
|
|
290
|
+
next = "The server is missing one of its own dependencies (see stderr): reinstall it, or try another version. It's a packaging problem, not your setup.";
|
|
291
|
+
}
|
|
292
|
+
else if (rejected) {
|
|
293
|
+
next = REJECTED_NEXT;
|
|
294
|
+
}
|
|
295
|
+
else if (trace.strayCount) {
|
|
296
|
+
next = `${LOG_TO_STDERR} Then fix what stderr says.`;
|
|
297
|
+
}
|
|
298
|
+
else if (trace.stderrLines) {
|
|
299
|
+
next = `Fix what the server's stderr says above, then rerun. To see all of it, run the command yourself: ${command}`;
|
|
300
|
+
}
|
|
301
|
+
else {
|
|
302
|
+
next = `Run the command yourself to see why it stops: ${command}`;
|
|
303
|
+
}
|
|
304
|
+
const when = stage === 'tools/list' || stage === 'initialize' || stage === 'server/discover' ? `before it answered ${stage}` : `during ${stage}`;
|
|
305
|
+
const why = next === REJECTED_NEXT ? `; its stderr looks like rejected credentials (“${rejected}”)` : '';
|
|
306
|
+
return new ConnectError(`The server ${how} ${when}${why}.`, facts, next, stage, { cause: error });
|
|
307
|
+
}
|
|
308
|
+
if (kind === 'timeout') {
|
|
309
|
+
const now = trace.failedAt ?? Date.now();
|
|
310
|
+
const waitedHere = pending ? now - pending.at : context.timeoutMs ?? 0;
|
|
311
|
+
const probeMs = trace.sessionStartedAt !== undefined ? trace.sessionStartedAt - trace.startedAt : undefined;
|
|
312
|
+
const limit = context.timeoutMs;
|
|
313
|
+
const probeTimedOut = probeMs !== undefined && limit !== undefined && probeMs >= limit * 0.95;
|
|
314
|
+
const waited = [
|
|
315
|
+
...(stage === 'initialize' && probeMs !== undefined ? [`${seconds(probeMs)} on server/discover${probeTimedOut ? ' (no answer)' : ''}, then `] : []),
|
|
316
|
+
`${seconds(waitedHere)} on ${stage}`,
|
|
317
|
+
limit !== undefined ? ` (--timeout ${limit} applies to each request)` : '',
|
|
318
|
+
].join('');
|
|
319
|
+
facts.push(['waited', waited]);
|
|
320
|
+
if (stage === 'initialize' && probeTimedOut) {
|
|
321
|
+
facts.push(['why twice', 'server/discover (the 2026 handshake) goes first, to a throwaway copy of the server.\nNo answer may just mean a 2025 server, so toolmenu starts it again and tries initialize.']);
|
|
322
|
+
}
|
|
323
|
+
if (trace.strayCount)
|
|
324
|
+
facts.push(strayFact(trace));
|
|
325
|
+
facts.push(stderrFact(trace));
|
|
326
|
+
const rejected = trace.strayCount ? undefined : rejectedCredentials(trace.stderrExcerpt().lines.join('\n'));
|
|
327
|
+
const headline = trace.strayCount
|
|
328
|
+
? `${stage} timed out after ${seconds(waitedHere)}: the server wrote lines that aren't JSON-RPC to stdout, and never answered.`
|
|
329
|
+
: rejected
|
|
330
|
+
? `${stage} timed out after ${seconds(waitedHere)}: the server is running but never answered; its stderr looks like rejected credentials (“${rejected}”).`
|
|
331
|
+
: `${stage} timed out after ${seconds(waitedHere)}: the server is running but never answered.`;
|
|
332
|
+
const next = trace.strayCount
|
|
333
|
+
? LOG_TO_STDERR
|
|
334
|
+
: rejected
|
|
335
|
+
? REJECTED_NEXT
|
|
336
|
+
: stage === 'tools/list'
|
|
337
|
+
? 'The server answered initialize, then hung on tools/list: check its logs (stderr above). If building the list is just slow, raise --timeout.'
|
|
338
|
+
: 'Check the command starts an MCP server on stdio (some need an argument such as "stdio" or "--stdio"). If it is only slow to start (npx downloading, a first build), raise --timeout.';
|
|
339
|
+
return new ConnectError(headline, facts, next, stage, { cause: error });
|
|
340
|
+
}
|
|
341
|
+
// Anything else: the transport's words, with what the server said.
|
|
342
|
+
if (trace.strayCount)
|
|
343
|
+
facts.push(strayFact(trace));
|
|
344
|
+
facts.push(['stage', stage], stderrFact(trace));
|
|
345
|
+
return new ConnectError(`${firstLine(error.message)}`, facts, trace.strayCount ? LOG_TO_STDERR : undefined, stage, { cause: error });
|
|
346
|
+
}
|
|
347
|
+
/** Words in a server's stderr that usually mean its API key or token was refused upstream. */
|
|
348
|
+
const REJECTED = /\b401\b(?:\s+Unauthori[sz]ed)?|\bUnauthori[sz]ed\b|invalid[_ -]api[_ -]key|invalid[_ -](?:access[_ -])?token|authentication failed|do not pass authentication/i;
|
|
349
|
+
/** The phrase in stderr that looks like rejected credentials, if any: a guess, so it's said as one. */
|
|
350
|
+
function rejectedCredentials(stderrText) {
|
|
351
|
+
return REJECTED.exec(stderrText)?.[0];
|
|
352
|
+
}
|
|
353
|
+
const REJECTED_NEXT = "Check the API key or token the server was given (--env, or its config): it's likely wrong, expired or for another account. This is a reading of the server's log, not certain: read its stderr above.";
|
|
354
|
+
function firstLine(text) {
|
|
355
|
+
return clean(text.split('\n')[0], 300);
|
|
356
|
+
}
|
|
357
|
+
const TLS = /^(CERT_|UNABLE_TO_|DEPTH_ZERO|SELF_SIGNED|ERR_TLS|ERR_SSL|EPROTO$)/;
|
|
358
|
+
function explainHttp(error, trace, context, target) {
|
|
359
|
+
const url = new URL(target.url);
|
|
360
|
+
const host = url.hostname;
|
|
361
|
+
const port = url.port || (url.protocol === 'https:' ? '443' : '80');
|
|
362
|
+
// Requests go one at a time while connecting: the last one sent is the one that failed.
|
|
363
|
+
const stage = context.stage ?? trace.sent.at(-1)?.method ?? 'server/discover';
|
|
364
|
+
const first = trace.sent.length <= 1 ? `${stage}, the first request` : stage;
|
|
365
|
+
const chain = causes(error);
|
|
366
|
+
const coded = [...chain].reverse().find((e) => typeof e.code === 'string' && !/^[A-Z_]+_FAILED$|^CLIENT_HTTP|^REQUEST_TIMEOUT$|^ERA_/.test(e.code));
|
|
367
|
+
const code = coded?.code;
|
|
368
|
+
const innermost = chain.at(-1);
|
|
369
|
+
// The network, before any HTTP answer.
|
|
370
|
+
if (code === 'ENOTFOUND' || code === 'EAI_AGAIN') {
|
|
371
|
+
return new ConnectError(code === 'ENOTFOUND' ? `Couldn't find ${host}: the name doesn't resolve (DNS: ENOTFOUND).` : `Couldn't look up ${host}: DNS failed for now (EAI_AGAIN).`, [['url', target.url], ['stage', first]], code === 'ENOTFOUND'
|
|
372
|
+
? "Check the host name for typos. If it's right, the server may have moved or shut down: look up its current URL in its docs or registry entry."
|
|
373
|
+
: 'Check this machine\'s network and DNS, then retry.', stage, { cause: error });
|
|
374
|
+
}
|
|
375
|
+
if (code === 'ECONNREFUSED') {
|
|
376
|
+
return new ConnectError(`Nothing is listening at ${host}:${port}: the connection was refused (ECONNREFUSED).`, [['url', target.url], ['stage', first]], `Start the server, or check the host and port${url.port ? '' : ` (no port in the URL means ${port})`}.`, stage, { cause: error });
|
|
377
|
+
}
|
|
378
|
+
if (innermost && /^bad port$/i.test(innermost.message)) {
|
|
379
|
+
return new ConnectError(`fetch won't connect to port ${port}: it's one of the ports Node blocks, because other protocols own them.`, [['url', target.url], ['stage', first]], 'Serve the MCP endpoint on another port (3000 and 8080 are common).', stage, { cause: error });
|
|
380
|
+
}
|
|
381
|
+
if (code && TLS.test(code)) {
|
|
382
|
+
const expired = code === 'CERT_HAS_EXPIRED';
|
|
383
|
+
const selfSigned = /SELF_SIGNED|UNABLE_TO_VERIFY|UNABLE_TO_GET_ISSUER/.test(code);
|
|
384
|
+
const plain = code === 'ERR_SSL_WRONG_VERSION_NUMBER' || /wrong version number/i.test(coded?.message ?? '');
|
|
385
|
+
return new ConnectError(`The TLS handshake with ${host} failed: ${coded?.message} (${code}).`, [['url', target.url], ['stage', first]], plain
|
|
386
|
+
? `That port speaks plain HTTP: use http://${url.host}${url.pathname}.`
|
|
387
|
+
: expired
|
|
388
|
+
? "The server's certificate has expired: its operator needs to renew it."
|
|
389
|
+
: selfSigned
|
|
390
|
+
? 'For a local or internal server with its own certificate authority, trust it with NODE_EXTRA_CA_CERTS=/path/to/ca.pem, or use http:// on a local port.'
|
|
391
|
+
: `Check the certificate: curl -v ${target.url}`, stage, { cause: error });
|
|
392
|
+
}
|
|
393
|
+
if (code === 'ETIMEDOUT' || code === 'UND_ERR_CONNECT_TIMEOUT') {
|
|
394
|
+
return new ConnectError(`Couldn't connect to ${host}:${port} in time (${code}).`, [['url', target.url], ['stage', first]], 'Check the host is reachable from here: a firewall, VPN or proxy may be dropping the connection.', stage, { cause: error });
|
|
395
|
+
}
|
|
396
|
+
if (code === 'EHOSTUNREACH' || code === 'ENETUNREACH') {
|
|
397
|
+
return new ConnectError(`No route to ${host} (${code}).`, [['url', target.url], ['stage', first]], "Check this machine's network, VPN or proxy.", stage, { cause: error });
|
|
398
|
+
}
|
|
399
|
+
if (code === 'ECONNRESET' || code === 'UND_ERR_SOCKET' || /other side closed|socket hang up/i.test(innermost?.message ?? '')) {
|
|
400
|
+
return new ConnectError(`${host} closed the connection in the middle of ${stage} (${code ?? innermost?.message}).`, [['url', target.url]], "Retry. If it keeps happening, check for a proxy between here and the server, or the server's logs.", stage, { cause: error });
|
|
401
|
+
}
|
|
402
|
+
// An HTTP answer that isn't MCP.
|
|
403
|
+
const data = error.data;
|
|
404
|
+
const response = trace.http.get(stage);
|
|
405
|
+
const status = typeof data?.status === 'number' ? data.status : typeof error.status === 'number' ? error.status : response?.status;
|
|
406
|
+
const unexpected = /unexpected content type/i.test(error.message);
|
|
407
|
+
if (status === 429)
|
|
408
|
+
return error;
|
|
409
|
+
if (status !== undefined && (status >= 400 || unexpected) || unexpected) {
|
|
410
|
+
const statusText = (typeof data?.statusText === 'string' && data.statusText) || response?.statusText || STATUS_TEXT[status ?? 0] || '';
|
|
411
|
+
const httpLine = status !== undefined ? `HTTP ${status}${statusText ? ` ${statusText}` : ''}` : 'a response';
|
|
412
|
+
const contentType = response?.contentType || (unexpected ? /content type:\s*(\S+)/i.exec(error.message)?.[1] ?? '' : '');
|
|
413
|
+
const shortType = contentType.split(';')[0].trim();
|
|
414
|
+
const body = typeof data?.text === 'string' ? data.text : undefined;
|
|
415
|
+
const excerpt = bodyExcerpt(body);
|
|
416
|
+
const finalUrl = response?.url && response.url !== target.url ? response.url : undefined;
|
|
417
|
+
const facts = [['url', target.url]];
|
|
418
|
+
if (finalUrl)
|
|
419
|
+
facts.push(['redirected', finalUrl]);
|
|
420
|
+
facts.push(['answer', `${httpLine}${shortType ? `, ${shortType}` : ''}`]);
|
|
421
|
+
if (excerpt)
|
|
422
|
+
facts.push([/html/i.test(shortType) || /<html|<!doctype/i.test(body ?? '') ? 'page' : 'body', `“${excerpt}”`]);
|
|
423
|
+
if (status === 401 || status === 403) {
|
|
424
|
+
const named = namedHeader(body);
|
|
425
|
+
const ownAuth = Object.keys(target.headers ?? {}).some((h) => isCredentialHeader(h) || h.toLowerCase() === named);
|
|
426
|
+
const next = context.oauth
|
|
427
|
+
? `The stored login was refused: log in again with toolmenu auth login ${target.url} (or skip it with --no-auth).`
|
|
428
|
+
: ownAuth
|
|
429
|
+
? status === 401
|
|
430
|
+
? 'The credentials you sent were refused: check the token is current and meant for this server.'
|
|
431
|
+
: "The credentials were accepted but don't grant access: check the account's permissions or the token's scopes."
|
|
432
|
+
: named && named !== 'authorization'
|
|
433
|
+
? `The server asks for ${/^[aeiox]/.test(named) ? 'an' : 'a'} ${named} header: pass it with --header "${named}: <key>".`
|
|
434
|
+
: `If the server uses OAuth, log in once with: toolmenu auth login ${target.url} (if it takes an API key instead, pass it with --header "Authorization: Bearer …").`;
|
|
435
|
+
return new ConnectError(status === 401 ? `${host} wants credentials: ${stage} got HTTP 401 Unauthorized.` : `${host} refused access: ${stage} got HTTP 403 Forbidden.`, facts.filter(([l]) => l !== 'answer'), next, stage, { cause: error, status });
|
|
436
|
+
}
|
|
437
|
+
// The server's own JSON-RPC error: its words, not a page.
|
|
438
|
+
const rpc = body && /"jsonrpc"/.test(body) ? bodyExcerpt(body, 200) : undefined;
|
|
439
|
+
if (rpc) {
|
|
440
|
+
return new ConnectError(`The server refused ${stage} (${httpLine}): “${rpc}”`, facts.filter(([l]) => l !== 'body'), "Check the server's docs for a required header or query parameter (pass headers with --header \"Key: value\").", stage, { cause: error, status });
|
|
441
|
+
}
|
|
442
|
+
if (status !== undefined && status >= 500) {
|
|
443
|
+
return new ConnectError(`${host} failed: ${stage} got ${httpLine}.`, facts, "That's on the server's side: retry later, or check its logs or status page.", stage, { cause: error, status });
|
|
444
|
+
}
|
|
445
|
+
const sse = /\/sse\/?$/.test(url.pathname);
|
|
446
|
+
const html = /html/i.test(shortType);
|
|
447
|
+
const why = status === 404 ? 'nothing is served at that path' : status === 405 ? "it doesn't accept POST there" : html ? 'it answered with a web page' : shortType ? `it answered with ${shortType}` : 'the answer isn\'t MCP';
|
|
448
|
+
return new ConnectError(`${target.url} isn't an MCP endpoint: ${stage} got ${httpLine}${shortType && status !== undefined ? ` (${shortType})` : ''}, so ${why}.`, facts.filter(([l]) => l !== 'answer'), sse
|
|
449
|
+
? `A URL ending in /sse is the older HTTP+SSE transport, which toolmenu doesn't speak. Most servers serve Streamable HTTP too: try ${url.origin}${url.pathname.replace(/\/sse\/?$/, '/mcp')}.`
|
|
450
|
+
: `Check the endpoint's path in the server's docs: Streamable HTTP servers usually answer at /mcp (not /sse, the older transport, and not the site's home page).`, stage, { cause: error, ...(status !== undefined ? { status } : {}) });
|
|
451
|
+
}
|
|
452
|
+
const kind = failureKind(error);
|
|
453
|
+
if (kind === 'server') {
|
|
454
|
+
return serverAnswered(error, stage, [['url', target.url]], "That's the server's own error, not the connection: fix what it says, or retry if the cause upstream has passed. If it persists, its operator's logs or status page may say more.");
|
|
455
|
+
}
|
|
456
|
+
if (kind === 'timeout') {
|
|
457
|
+
const got = response ? `${host} answered (HTTP ${response.status}) but sent no JSON-RPC reply` : `no response from ${host}`;
|
|
458
|
+
return new ConnectError(`${stage} timed out after ${seconds(context.timeoutMs ?? 0)}: ${got}.`, [['url', target.url], ['stage', first]], `Check the URL answers from here (curl -i -X POST ${target.url}); a firewall or VPN may be in the way. If the server is only slow, raise --timeout.`, stage, { cause: error });
|
|
459
|
+
}
|
|
460
|
+
return error;
|
|
461
|
+
}
|
package/dist/failures.d.ts
CHANGED
|
@@ -19,6 +19,12 @@ export declare function tooMany(error: unknown): boolean;
|
|
|
19
19
|
* the waiting off.
|
|
20
20
|
*/
|
|
21
21
|
export declare const RATE_LIMIT_WAITS_MS: number[];
|
|
22
|
+
/**
|
|
23
|
+
* A tool's error text with the reason up front: "400 Bad Request: {"message":"Filter by
|
|
24
|
+
* X is mandatory"}" says "400 Bad Request: Filter by X is mandatory". Text with no JSON
|
|
25
|
+
* message in it is returned as it is.
|
|
26
|
+
*/
|
|
27
|
+
export declare function errorWords(text: string): string;
|
|
22
28
|
/** What to do about a rate limit toolmenu couldn't wait out. */
|
|
23
29
|
export declare const RATE_LIMIT_ADVICE = "The limit counts every request from this address, toolmenu's included: give the run its own server instance, or raise the limit for it.";
|
|
24
30
|
/** Quoted words that end a sentence: “Rate limit exceeded”. but “Try again later.” (no second period). */
|
|
@@ -58,3 +64,12 @@ export declare function classifyFailure(text: string, options?: {
|
|
|
58
64
|
hadArguments?: boolean;
|
|
59
65
|
}): FailureClass;
|
|
60
66
|
export declare const FAILURE_LABELS: Record<FailureClass, string>;
|
|
67
|
+
/**
|
|
68
|
+
* The next step for calls that failed before reaching the tool, per SPEC §25.
|
|
69
|
+
* The class is read from the error's words, so it's a guess: `confidence` is
|
|
70
|
+
* 'unsure', and the step says what to check rather than what's wrong.
|
|
71
|
+
*/
|
|
72
|
+
export declare function setupFailureAdvice(classes: Iterable<FailureClass>, transport: 'stdio' | 'http'): {
|
|
73
|
+
fix: string;
|
|
74
|
+
confidence: 'unsure';
|
|
75
|
+
};
|