@chrischall/mcp-utils 0.24.0 → 0.25.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 +42 -3
- package/dist/healthcheck/index.d.ts +105 -2
- package/dist/healthcheck/index.d.ts.map +1 -1
- package/dist/healthcheck/index.js +121 -0
- package/dist/healthcheck/index.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -831,9 +831,48 @@ registerCredentialHealthcheckTool({
|
|
|
831
831
|
});
|
|
832
832
|
```
|
|
833
833
|
|
|
834
|
-
Arms: `ok`, `no_credential`, `credential_rejected` (401/403),
|
|
835
|
-
`
|
|
836
|
-
hooks as the bridge
|
|
834
|
+
Arms: `ok`, `no_credential`, `credential_rejected` (401/403),
|
|
835
|
+
`session_expired`, `verification_pending`, `timeout`, `http`, `transport`,
|
|
836
|
+
`unknown` — with the same `classifyThrown` / `hints` hooks as the bridge
|
|
837
|
+
factory.
|
|
838
|
+
|
|
839
|
+
#### Cookie-session connectors: `sessionProbe` / `sessionClassifier`
|
|
840
|
+
|
|
841
|
+
`probeFn` reports failure **only by throwing**, so a probe that resolves is
|
|
842
|
+
reported healthy whatever it resolved to. Connectors whose probe rides a client
|
|
843
|
+
that throws on non-2xx comply by accident — and that accident does not hold
|
|
844
|
+
against a *soft* wall, where a dead session comes back `200` with a login page.
|
|
845
|
+
One connector reported `ok: true` and "the credential works" on an account that
|
|
846
|
+
could not load a single record.
|
|
847
|
+
|
|
848
|
+
`sessionProbe` builds a compliant probe from the one closure only you can
|
|
849
|
+
write:
|
|
850
|
+
|
|
851
|
+
```ts
|
|
852
|
+
probeFn: sessionProbe({
|
|
853
|
+
request: () => auth.request('Home'), // must not sign in
|
|
854
|
+
signedOut: (body) => isAuthWall(body), // the site-specific part
|
|
855
|
+
hostLabel: 'my.atriumhealth.org',
|
|
856
|
+
}),
|
|
857
|
+
classifyThrown: sessionClassifier({
|
|
858
|
+
prefix: 'mah',
|
|
859
|
+
hostLabel: 'my.atriumhealth.org',
|
|
860
|
+
verificationPending: () => auth.mfaPending,
|
|
861
|
+
credentialsRejected: () => auth.credentialsRejected,
|
|
862
|
+
}),
|
|
863
|
+
```
|
|
864
|
+
|
|
865
|
+
The library owns the generic rules — a 3xx is signed out (a manual-redirect
|
|
866
|
+
bounce has no body to judge), any other non-2xx is an upstream error carrying
|
|
867
|
+
its status, a 2xx is signed out if your closure says so — and turns the three
|
|
868
|
+
signed-out states into arms with distinct remedies. A refused credential
|
|
869
|
+
outranks a pending verification: both flags can be set, and retrying a code
|
|
870
|
+
against a password the far side refuses is futile.
|
|
871
|
+
|
|
872
|
+
`signedOut` stays yours because getting it wrong is silent and specific. One
|
|
873
|
+
portal links to two-factor setup from every signed-in page, so a body-wide
|
|
874
|
+
match on `twoFactor` reports "signed out" for every request. A library that
|
|
875
|
+
guessed this would be wrong in both directions.
|
|
837
876
|
|
|
838
877
|
#### Two transports, one healthcheck
|
|
839
878
|
|
|
@@ -15,7 +15,11 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
|
|
15
15
|
* question each answers: is there a credential at all, did the far side accept
|
|
16
16
|
* it, and did the round-trip work.
|
|
17
17
|
*/
|
|
18
|
-
export type CredentialHealthcheckArm = 'ok' | 'no_credential' | 'credential_rejected'
|
|
18
|
+
export type CredentialHealthcheckArm = 'ok' | 'no_credential' | 'credential_rejected'
|
|
19
|
+
/** Credentials are fine; no session is live. See {@link sessionProbe}. */
|
|
20
|
+
| 'session_expired'
|
|
21
|
+
/** A second factor is outstanding, so the far side is holding the sign-in. */
|
|
22
|
+
| 'verification_pending' | 'timeout' | 'http' | 'transport' | 'unknown';
|
|
19
23
|
/** What a consumer's resolver reports. NEVER the credential value itself. */
|
|
20
24
|
export interface CredentialState {
|
|
21
25
|
/**
|
|
@@ -72,7 +76,16 @@ export interface RegisterCredentialHealthcheckToolArgs {
|
|
|
72
76
|
* are already set.
|
|
73
77
|
*/
|
|
74
78
|
resolveCredential: () => Promise<CredentialState>;
|
|
75
|
-
/**
|
|
79
|
+
/**
|
|
80
|
+
* One authenticated round-trip. Only called when a credential resolved.
|
|
81
|
+
*
|
|
82
|
+
* **It reports failure only by THROWING.** A probe that resolves is reported
|
|
83
|
+
* healthy, whatever it resolved to — so a 2xx is not, on its own, proof of a
|
|
84
|
+
* session. A cookie-session portal answers a dead session with a login page
|
|
85
|
+
* served 200, or a redirect to one; a probe that hands either back reports
|
|
86
|
+
* `ok: true` and tells the caller to go debug a tool. {@link sessionProbe}
|
|
87
|
+
* builds a compliant probe from the one closure only the consumer can write.
|
|
88
|
+
*/
|
|
76
89
|
probeFn: () => Promise<unknown>;
|
|
77
90
|
/**
|
|
78
91
|
* Classify a thrown error into an arm, and optionally override the hint and
|
|
@@ -164,4 +177,94 @@ export declare function runCredentialHealthcheck(args: RegisterCredentialHealthc
|
|
|
164
177
|
* {@link runCredentialHealthcheck}.
|
|
165
178
|
*/
|
|
166
179
|
export declare function registerCredentialHealthcheckTool(args: RegisterCredentialHealthcheckToolArgs): void;
|
|
180
|
+
/**
|
|
181
|
+
* The probe reached the far side and it declined to serve the data — a login
|
|
182
|
+
* page, or a redirect to one. Its own class so a classifier can tell it apart
|
|
183
|
+
* from a network failure.
|
|
184
|
+
*/
|
|
185
|
+
export declare class SessionNotLiveError extends Error {
|
|
186
|
+
readonly hostLabel: string;
|
|
187
|
+
readonly detail: string;
|
|
188
|
+
constructor(hostLabel: string, detail: string);
|
|
189
|
+
}
|
|
190
|
+
/** A non-2xx from the far side, carrying the status the healthcheck reports. */
|
|
191
|
+
export declare class ProbeHttpError extends Error {
|
|
192
|
+
readonly hostLabel: string;
|
|
193
|
+
readonly status: number;
|
|
194
|
+
constructor(hostLabel: string, status: number);
|
|
195
|
+
}
|
|
196
|
+
/** The minimum a {@link sessionProbe} request has to report. */
|
|
197
|
+
export interface ProbeResponse {
|
|
198
|
+
status: number;
|
|
199
|
+
body: string;
|
|
200
|
+
}
|
|
201
|
+
export interface SessionProbeOptions {
|
|
202
|
+
/** Make the authenticated request. Must NOT sign in — a diagnostic observes. */
|
|
203
|
+
request: () => Promise<ProbeResponse>;
|
|
204
|
+
/**
|
|
205
|
+
* **The site-specific closure**, and the only part of this that cannot be
|
|
206
|
+
* generalised: does this body mean "not signed in"?
|
|
207
|
+
*
|
|
208
|
+
* It stays with the consumer because getting it wrong is silent and specific.
|
|
209
|
+
* One real portal links to two-factor setup from every signed-in page, so a
|
|
210
|
+
* body-wide match on `twoFactor` reports "signed out" for every request; the
|
|
211
|
+
* fix was to scope it to the `<title>`, which is knowable only next to the
|
|
212
|
+
* markup. A library that guessed this would be wrong in both directions.
|
|
213
|
+
*/
|
|
214
|
+
signedOut: (body: string) => boolean;
|
|
215
|
+
/** Used in the thrown messages. Defaults to a neutral phrase. */
|
|
216
|
+
hostLabel?: string;
|
|
217
|
+
}
|
|
218
|
+
/**
|
|
219
|
+
* Build a `probeFn` that JUDGES its response instead of merely completing.
|
|
220
|
+
*
|
|
221
|
+
* `probeFn`'s contract is that it reports failure by throwing, so any probe
|
|
222
|
+
* that can resolve on a signed-out response silently reports healthy. Every
|
|
223
|
+
* connector whose probe rides a client that throws on non-2xx complies by
|
|
224
|
+
* accident — and that accident does not hold against a SOFT wall, where a dead
|
|
225
|
+
* session comes back 200 with a login page.
|
|
226
|
+
*
|
|
227
|
+
* The rules here are the generic ones:
|
|
228
|
+
*
|
|
229
|
+
* - a 3xx is signed out, because under a manual-redirect fetch the bounce to
|
|
230
|
+
* the login page arrives with no body to judge;
|
|
231
|
+
* - any other non-2xx is an upstream error carrying its status;
|
|
232
|
+
* - a 2xx is signed out if the consumer's closure says so.
|
|
233
|
+
*
|
|
234
|
+
* Pair with {@link sessionClassifier} to turn those into arms and remedies.
|
|
235
|
+
*/
|
|
236
|
+
export declare function sessionProbe(opts: SessionProbeOptions): () => Promise<string>;
|
|
237
|
+
export interface SessionClassifierOptions {
|
|
238
|
+
/** Tool-name prefix, used to name the remedy tools in the default copy. */
|
|
239
|
+
prefix: string;
|
|
240
|
+
/** Display host named in the default copy, e.g. `'my.atriumhealth.org'`. */
|
|
241
|
+
hostLabel: string;
|
|
242
|
+
/** A second factor is outstanding. Read at classification time, not captured. */
|
|
243
|
+
verificationPending?: () => boolean;
|
|
244
|
+
/** The far side refused this username and password. */
|
|
245
|
+
credentialsRejected?: () => boolean;
|
|
246
|
+
/** Per-kind copy overrides, for a connector whose remedy is not a tool call. */
|
|
247
|
+
hints?: Partial<Record<'session_expired' | 'verification_pending' | 'credential_rejected' | 'http', string>>;
|
|
248
|
+
}
|
|
249
|
+
/**
|
|
250
|
+
* Build a `classifyThrown` that names WHICH signed-out state a
|
|
251
|
+
* {@link sessionProbe} failure is.
|
|
252
|
+
*
|
|
253
|
+
* All three arrive as the same login page and have three different remedies,
|
|
254
|
+
* so reporting them as one sends people to the wrong fix — telling somebody
|
|
255
|
+
* with an outstanding code to check their password sends them to change a
|
|
256
|
+
* credential that is already correct.
|
|
257
|
+
*
|
|
258
|
+
* **A refused credential outranks a pending verification.** Both flags can be
|
|
259
|
+
* set at once, and retrying a code against a password the far side refuses is
|
|
260
|
+
* futile. Two call sites in one repo disagreed about this order, which is the
|
|
261
|
+
* argument for the order living in exactly one place.
|
|
262
|
+
*
|
|
263
|
+
* Returns `undefined` for anything it does not recognise, so the built-in
|
|
264
|
+
* ladder still classifies a network failure rather than being shadowed.
|
|
265
|
+
*/
|
|
266
|
+
export declare function sessionClassifier(opts: SessionClassifierOptions): (err: unknown) => {
|
|
267
|
+
kind: string;
|
|
268
|
+
hint?: string;
|
|
269
|
+
} | undefined;
|
|
167
270
|
//# sourceMappingURL=index.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/healthcheck/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGzE;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAChC,IAAI,GACJ,eAAe,GACf,qBAAqB,
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/healthcheck/index.ts"],"names":[],"mappings":"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"}
|
|
@@ -11,6 +11,8 @@ const CREDENTIAL_ARMS = new Set([
|
|
|
11
11
|
'ok',
|
|
12
12
|
'no_credential',
|
|
13
13
|
'credential_rejected',
|
|
14
|
+
'session_expired',
|
|
15
|
+
'verification_pending',
|
|
14
16
|
'timeout',
|
|
15
17
|
'http',
|
|
16
18
|
'transport',
|
|
@@ -28,6 +30,10 @@ function credentialHint(arm, prefix, hostLabel, source) {
|
|
|
28
30
|
return `No credential resolved. Nothing was available to authenticate with — sign in and reconnect the connector so ${prefix} receives a token, or set the documented environment variable.`;
|
|
29
31
|
case 'credential_rejected':
|
|
30
32
|
return `${hostLabel} rejected the credential from '${source}'. It is present but no longer valid — most often expired or revoked upstream. Re-authenticate and reconnect; retrying will not fix it.`;
|
|
33
|
+
case 'session_expired':
|
|
34
|
+
return `The credential from '${source}' is configured, but no session is live — ${hostLabel} served a sign-in page rather than the data. Sign in again; a cookie-session portal expires these on its own, so this recurs between uses.`;
|
|
35
|
+
case 'verification_pending':
|
|
36
|
+
return `${hostLabel} is holding the sign-in on a second factor rather than refusing it. Supply the verification code the ACCOUNT HOLDER received — the credential itself is not the problem, so changing it will not help.`;
|
|
31
37
|
case 'timeout':
|
|
32
38
|
return `The credential from '${source}' resolved, but ${hostLabel} did not answer in time. Usually transient — retry. If it persists, ${hostLabel} is slow or unreachable from here.`;
|
|
33
39
|
case 'http':
|
|
@@ -207,4 +213,119 @@ export function registerCredentialHealthcheckTool(args) {
|
|
|
207
213
|
inputSchema: {},
|
|
208
214
|
}, async () => runCredentialHealthcheck(args));
|
|
209
215
|
}
|
|
216
|
+
/**
|
|
217
|
+
* The probe reached the far side and it declined to serve the data — a login
|
|
218
|
+
* page, or a redirect to one. Its own class so a classifier can tell it apart
|
|
219
|
+
* from a network failure.
|
|
220
|
+
*/
|
|
221
|
+
export class SessionNotLiveError extends Error {
|
|
222
|
+
hostLabel;
|
|
223
|
+
detail;
|
|
224
|
+
constructor(hostLabel, detail) {
|
|
225
|
+
super(`${hostLabel} served a sign-in page rather than the data (${detail}).`);
|
|
226
|
+
this.hostLabel = hostLabel;
|
|
227
|
+
this.detail = detail;
|
|
228
|
+
this.name = 'SessionNotLiveError';
|
|
229
|
+
}
|
|
230
|
+
}
|
|
231
|
+
/** A non-2xx from the far side, carrying the status the healthcheck reports. */
|
|
232
|
+
export class ProbeHttpError extends Error {
|
|
233
|
+
hostLabel;
|
|
234
|
+
status;
|
|
235
|
+
constructor(hostLabel, status) {
|
|
236
|
+
super(`${hostLabel} answered ${status}.`);
|
|
237
|
+
this.hostLabel = hostLabel;
|
|
238
|
+
this.status = status;
|
|
239
|
+
this.name = 'ProbeHttpError';
|
|
240
|
+
}
|
|
241
|
+
}
|
|
242
|
+
/**
|
|
243
|
+
* Build a `probeFn` that JUDGES its response instead of merely completing.
|
|
244
|
+
*
|
|
245
|
+
* `probeFn`'s contract is that it reports failure by throwing, so any probe
|
|
246
|
+
* that can resolve on a signed-out response silently reports healthy. Every
|
|
247
|
+
* connector whose probe rides a client that throws on non-2xx complies by
|
|
248
|
+
* accident — and that accident does not hold against a SOFT wall, where a dead
|
|
249
|
+
* session comes back 200 with a login page.
|
|
250
|
+
*
|
|
251
|
+
* The rules here are the generic ones:
|
|
252
|
+
*
|
|
253
|
+
* - a 3xx is signed out, because under a manual-redirect fetch the bounce to
|
|
254
|
+
* the login page arrives with no body to judge;
|
|
255
|
+
* - any other non-2xx is an upstream error carrying its status;
|
|
256
|
+
* - a 2xx is signed out if the consumer's closure says so.
|
|
257
|
+
*
|
|
258
|
+
* Pair with {@link sessionClassifier} to turn those into arms and remedies.
|
|
259
|
+
*/
|
|
260
|
+
export function sessionProbe(opts) {
|
|
261
|
+
const host = opts.hostLabel ?? 'the upstream';
|
|
262
|
+
return async () => {
|
|
263
|
+
const { status, body } = await opts.request();
|
|
264
|
+
if (status >= 300 && status < 400) {
|
|
265
|
+
throw new SessionNotLiveError(host, `redirected with ${status}`);
|
|
266
|
+
}
|
|
267
|
+
if (status < 200 || status >= 300)
|
|
268
|
+
throw new ProbeHttpError(host, status);
|
|
269
|
+
if (opts.signedOut(body))
|
|
270
|
+
throw new SessionNotLiveError(host, 'sign-in or verification page');
|
|
271
|
+
return body;
|
|
272
|
+
};
|
|
273
|
+
}
|
|
274
|
+
/**
|
|
275
|
+
* Build a `classifyThrown` that names WHICH signed-out state a
|
|
276
|
+
* {@link sessionProbe} failure is.
|
|
277
|
+
*
|
|
278
|
+
* All three arrive as the same login page and have three different remedies,
|
|
279
|
+
* so reporting them as one sends people to the wrong fix — telling somebody
|
|
280
|
+
* with an outstanding code to check their password sends them to change a
|
|
281
|
+
* credential that is already correct.
|
|
282
|
+
*
|
|
283
|
+
* **A refused credential outranks a pending verification.** Both flags can be
|
|
284
|
+
* set at once, and retrying a code against a password the far side refuses is
|
|
285
|
+
* futile. Two call sites in one repo disagreed about this order, which is the
|
|
286
|
+
* argument for the order living in exactly one place.
|
|
287
|
+
*
|
|
288
|
+
* Returns `undefined` for anything it does not recognise, so the built-in
|
|
289
|
+
* ladder still classifies a network failure rather than being shadowed.
|
|
290
|
+
*/
|
|
291
|
+
export function sessionClassifier(opts) {
|
|
292
|
+
const { prefix, hostLabel, hints } = opts;
|
|
293
|
+
return (err) => {
|
|
294
|
+
if (err instanceof ProbeHttpError) {
|
|
295
|
+
return {
|
|
296
|
+
kind: 'http',
|
|
297
|
+
hint: hints?.http ??
|
|
298
|
+
`${hostLabel} answered ${err.status}. The credential was never judged — that is an ` +
|
|
299
|
+
'upstream problem, so retry, and if it persists the far side is down.',
|
|
300
|
+
};
|
|
301
|
+
}
|
|
302
|
+
if (!(err instanceof SessionNotLiveError))
|
|
303
|
+
return undefined;
|
|
304
|
+
if (opts.credentialsRejected?.() === true) {
|
|
305
|
+
return {
|
|
306
|
+
kind: 'credential_rejected',
|
|
307
|
+
hint: hints?.credential_rejected ??
|
|
308
|
+
`${hostLabel} refused this username and password. Correct them, then call ` +
|
|
309
|
+
`${prefix}_sign_in. Nothing retries for you: repeated failures escalate to a ` +
|
|
310
|
+
'captcha or a lockout.',
|
|
311
|
+
};
|
|
312
|
+
}
|
|
313
|
+
if (opts.verificationPending?.() === true) {
|
|
314
|
+
return {
|
|
315
|
+
kind: 'verification_pending',
|
|
316
|
+
hint: hints?.verification_pending ??
|
|
317
|
+
`A verification code is outstanding, so ${hostLabel} is holding the sign-in rather ` +
|
|
318
|
+
`than refusing it. Call ${prefix}_send_verification_code, then pass the code the ` +
|
|
319
|
+
`ACCOUNT HOLDER receives to ${prefix}_verify_code.`,
|
|
320
|
+
};
|
|
321
|
+
}
|
|
322
|
+
return {
|
|
323
|
+
kind: 'session_expired',
|
|
324
|
+
hint: hints?.session_expired ??
|
|
325
|
+
`The credentials are configured but no session is live — ${hostLabel} sessions are ` +
|
|
326
|
+
`short-lived, so this recurs between uses. Call ${prefix}_sign_in; expect a ` +
|
|
327
|
+
'verification code, which goes to the account holder.',
|
|
328
|
+
};
|
|
329
|
+
};
|
|
330
|
+
}
|
|
210
331
|
//# sourceMappingURL=index.js.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/healthcheck/index.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,oBAAoB,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/healthcheck/index.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@chrischall/mcp-utils",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.25.0",
|
|
4
4
|
"description": "Shared scaffolding for the chrischall MCP fleet — server bootstrap, tool-result formatting, helpful errors, hardened env/config, a bearer API-client kit, zod atoms, session registries, a fetchproxy transport adapter, auth resolver skeletons, an in-memory test harness, and opt-in HTML helpers. The generic MCP glue hoisted out of ~19 sibling servers.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|