mcp-use-compat 0.3.0

package/dist/checks/auth.js

@@ -0,0 +1,229 @@
+import { isObject, str } from "./util.js";
+import { defineCheck } from "./types.js";
+const DISCOVERY_SPEC = "https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization/authorization-server-discovery";
+const REGISTRATION_SPEC = "https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization/client-registration";
+/** The server demanded credentials for an unauthenticated initialize. */
+const protectedServer = (s) => {
+    const status = s.http?.unauthenticated.status;
+    return status === 401 || status === 403;
+};
+const okJson = (r) => r.status === 200 && isObject(r.json);
+const prm = (s) => s.http?.protectedResource.find(okJson);
+const asm = (s) => s.http?.authorizationServer.find(okJson);
+const json = (r) => (r?.json ?? {});
+const withoutTrailingSlash = (u) => u.replace(/\/+$/, "");
+export const authChecks = [
+    defineCheck({
+        id: "AUTH_CHALLENGE_MISSING",
+        area: "auth",
+        description: "401 responses carry a WWW-Authenticate challenge",
+        appliesTo: protectedServer,
+        run: (s) => s.http.unauthenticated.headers?.["www-authenticate"]
+            ? []
+            : [
+                {
+                    checkId: "AUTH_CHALLENGE_MISSING",
+                    severity: "warn",
+                    message: `HTTP ${s.http.unauthenticated.status} without a WWW-Authenticate header; clients must guess where the protected resource metadata is.`,
+                    affects: ["oauth"],
+                    source: DISCOVERY_SPEC,
+                    fix: 'Return WWW-Authenticate: Bearer resource_metadata="https://<host>/.well-known/oauth-protected-resource/<path>".',
+                },
+            ],
+    }),
+    defineCheck({
+        id: "AUTH_PRM_MISSING",
+        area: "auth",
+        description: "Protected resource metadata (RFC 9728) is discoverable",
+        appliesTo: protectedServer,
+        run: (s) => prm(s)
+            ? []
+            : [
+                {
+                    checkId: "AUTH_PRM_MISSING",
+                    severity: "error",
+                    message: "No protected resource metadata found, so clients can't find the authorization server.",
+                    evidence: { tried: s.http.protectedResource.map((r) => `${r.url} → ${r.status ?? r.error}`) },
+                    affects: ["oauth"],
+                    source: DISCOVERY_SPEC,
+                    fix: "Serve /.well-known/oauth-protected-resource (path-suffixed for your MCP endpoint) with resource and authorization_servers.",
+                },
+            ],
+    }),
+    defineCheck({
+        id: "AUTH_PRM_INVALID",
+        area: "auth",
+        description: "Protected resource metadata names the resource and its authorization servers",
+        appliesTo: (s) => protectedServer(s) && !!prm(s),
+        run: (s) => {
+            const metadata = json(prm(s));
+            const findings = [];
+            const servers = metadata.authorization_servers;
+            if (!Array.isArray(servers) || !servers.some((a) => typeof a === "string")) {
+                findings.push({
+                    checkId: "AUTH_PRM_INVALID",
+                    severity: "error",
+                    message: "Protected resource metadata has no authorization_servers.",
+                    affects: ["oauth"],
+                    source: DISCOVERY_SPEC,
+                    fix: 'Add "authorization_servers": ["https://<issuer>"].',
+                });
+            }
+            const resource = str(metadata.resource);
+            const url = s.target.kind === "http" ? s.target.url : "";
+            if (!resource) {
+                findings.push({
+                    checkId: "AUTH_PRM_INVALID",
+                    severity: "error",
+                    message: "Protected resource metadata has no resource.",
+                    affects: ["oauth"],
+                    source: DISCOVERY_SPEC,
+                    fix: `Add "resource": "${url}".`,
+                });
+            }
+            else if (withoutTrailingSlash(resource) !== withoutTrailingSlash(url)) {
+                findings.push({
+                    checkId: "AUTH_PRM_INVALID",
+                    severity: "error",
+                    subject: resource,
+                    message: `resource is ${resource} but the server is at ${url}; clients must reject metadata for a different resource (RFC 9728 §3.3).`,
+                    affects: ["oauth"],
+                    source: DISCOVERY_SPEC,
+                    fix: "Set resource to the exact MCP endpoint URL.",
+                });
+            }
+            return findings;
+        },
+    }),
+    defineCheck({
+        id: "AUTH_ASM_MISSING",
+        area: "auth",
+        description: "Authorization server metadata (RFC 8414 / OIDC) is discoverable",
+        appliesTo: (s) => protectedServer(s) && s.http.authorizationServer.length > 0,
+        run: (s) => asm(s)
+            ? []
+            : [
+                {
+                    checkId: "AUTH_ASM_MISSING",
+                    severity: "error",
+                    message: "No authorization server metadata at any well-known location.",
+                    evidence: { tried: s.http.authorizationServer.map((r) => `${r.url} → ${r.status ?? r.error}`) },
+                    affects: ["oauth"],
+                    source: DISCOVERY_SPEC,
+                    fix: "Serve /.well-known/oauth-authorization-server or /.well-known/openid-configuration for the issuer.",
+                },
+            ],
+    }),
+    defineCheck({
+        id: "AUTH_ISSUER_MISMATCH",
+        area: "auth",
+        description: "Authorization server metadata issuer matches the advertised issuer",
+        appliesTo: (s) => protectedServer(s) && !!asm(s),
+        run: (s) => {
+            const servers = json(prm(s)).authorization_servers;
+            // Malformed authorization_servers is reported by AUTH_PRM_INVALID.
+            const advertised = Array.isArray(servers) ? servers.find((a) => typeof a === "string") : undefined;
+            const issuer = str(json(asm(s)).issuer);
+            if (!advertised || (issuer && withoutTrailingSlash(issuer) === withoutTrailingSlash(advertised)))
+                return [];
+            return [
+                {
+                    checkId: "AUTH_ISSUER_MISMATCH",
+                    severity: "error",
+                    message: `Metadata issuer is ${JSON.stringify(issuer ?? null)} but the resource names ${advertised}; spec-following clients reject the authorization server.`,
+                    affects: ["oauth"],
+                    source: DISCOVERY_SPEC,
+                    fix: "Make the issuer in the metadata identical to the URL in authorization_servers.",
+                },
+            ];
+        },
+    }),
+    defineCheck({
+        id: "AUTH_PKCE_S256_MISSING",
+        area: "auth",
+        description: "Authorization server advertises PKCE S256",
+        appliesTo: (s) => protectedServer(s) && !!asm(s),
+        run: (s) => {
+            const methods = json(asm(s)).code_challenge_methods_supported;
+            if (Array.isArray(methods) && methods.includes("S256"))
+                return [];
+            return [
+                {
+                    checkId: "AUTH_PKCE_S256_MISSING",
+                    severity: "error",
+                    message: Array.isArray(methods)
+                        ? `code_challenge_methods_supported is ${JSON.stringify(methods)} without S256.`
+                        : "Authorization server metadata omits code_challenge_methods_supported; MCP clients must refuse to proceed (ChatGPT rejects the server).",
+                    affects: ["oauth"],
+                    source: DISCOVERY_SPEC,
+                    fix: 'Advertise "code_challenge_methods_supported": ["S256"].',
+                },
+            ];
+        },
+    }),
+    defineCheck({
+        id: "AUTH_CLIENT_REGISTRATION",
+        area: "auth",
+        description: "Clients can register themselves (CIMD or DCR)",
+        appliesTo: (s) => protectedServer(s) && !!asm(s),
+        run: (s) => {
+            const metadata = json(asm(s));
+            const cimd = metadata.client_id_metadata_document_supported === true;
+            const dcr = typeof metadata.registration_endpoint === "string";
+            if (cimd)
+                return [];
+            if (dcr) {
+                return [
+                    {
+                        checkId: "AUTH_CLIENT_REGISTRATION",
+                        severity: "info",
+                        message: "Only Dynamic Client Registration is offered. It works with today's clients but is deprecated in protocol 2026-07-28 in favour of Client ID Metadata Documents.",
+                        source: REGISTRATION_SPEC,
+                        fix: "Also advertise client_id_metadata_document_supported: true.",
+                    },
+                ];
+            }
+            return [
+                {
+                    checkId: "AUTH_CLIENT_REGISTRATION",
+                    severity: "warn",
+                    message: "Neither Client ID Metadata Documents nor Dynamic Client Registration is offered, so users must obtain and paste a client ID/secret for every client.",
+                    affects: ["oauth"],
+                    source: REGISTRATION_SPEC,
+                    fix: "Support CIMD (client_id_metadata_document_supported: true) or a registration_endpoint.",
+                },
+            ];
+        },
+    }),
+    defineCheck({
+        id: "AUTH_INSECURE_URL",
+        area: "auth",
+        description: "Remote servers and OAuth endpoints use HTTPS",
+        appliesTo: (s) => s.target.kind === "http",
+        run: (s) => {
+            const urls = [
+                s.target.kind === "http" ? s.target.url : "",
+                ...Object.entries(json(asm(s)))
+                    .filter(([k]) => k.endsWith("_endpoint"))
+                    .map(([, v]) => str(v) ?? ""),
+            ];
+            const insecure = urls.filter((u) => {
+                try {
+                    const url = new URL(u);
+                    return url.protocol === "http:" && !["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+                }
+                catch {
+                    return false;
+                }
+            });
+            return [...new Set(insecure)].map((u) => ({
+                checkId: "AUTH_INSECURE_URL",
+                severity: "warn",
+                subject: u,
+                message: "Plain http:// on a non-loopback host; OAuth 2.1 requires HTTPS and hosted clients will refuse it.",
+                fix: "Serve over HTTPS.",
+            }));
+        },
+    }),
+];
+//# sourceMappingURL=auth.js.map

package/dist/checks/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/checks/auth.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAgB,MAAM,YAAY,CAAC;AAEvD,MAAM,cAAc,GAClB,6GAA6G,CAAC;AAChH,MAAM,iBAAiB,GAAG,kGAAkG,CAAC;AAE7H,yEAAyE;AACzE,MAAM,eAAe,GAAG,CAAC,CAAiB,EAAE,EAAE;IAC5C,MAAM,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC;IAC9C,OAAO,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,CAAC;AAC1C,CAAC,CAAC;AAEF,MAAM,MAAM,GAAG,CAAC,CAAoB,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,GAAG,IAAI,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AAC9E,MAAM,GAAG,GAAG,CAAC,CAAiB,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,iBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC1E,MAAM,GAAG,GAAG,CAAC,CAAiB,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,mBAAmB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC5E,MAAM,IAAI,GAAG,CAAC,CAAgC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,IAAI,EAAE,CAA4B,CAAC;AAE9F,MAAM,oBAAoB,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AAElE,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,WAAW,CAAC;QACV,EAAE,EAAE,wBAAwB;QAC5B,IAAI,EAAE,MAAM;QACZ,WAAW,EAAE,kDAAkD;QAC/D,SAAS,EAAE,eAAe;QAC1B,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,CACT,CAAC,CAAC,IAAK,CAAC,eAAe,CAAC,OAAO,EAAE,CAAC,kBAAkB,CAAC;YACnD,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC;gBACE;oBACE,OAAO,EAAE,wBAAwB;oBACjC,QAAQ,EAAE,MAAM;oBAChB,OAAO,EAAE,QAAQ,CAAC,CAAC,IAAK,CAAC,eAAe,CAAC,MAAM,kGAAkG;oBACjJ,OAAO,EAAE,CAAC,OAAO,CAAC;oBAClB,MAAM,EAAE,cAAc;oBACtB,GAAG,EAAE,iHAAiH;iBACvH;aACF;KACR,CAAC;IAEF,WAAW,CAAC;QACV,EAAE,EAAE,kBAAkB;QACtB,IAAI,EAAE,MAAM;QACZ,WAAW,EAAE,wDAAwD;QACrE,SAAS,EAAE,eAAe;QAC1B,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,CACT,GAAG,CAAC,CAAC,CAAC;YACJ,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC;gBACE;oBACE,OAAO,EAAE,kBAAkB;oBAC3B,QAAQ,EAAE,OAAO;oBACjB,OAAO,EAAE,uFAAuF;oBAChG,QAAQ,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,IAAK,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE;oBAC9F,OAAO,EAAE,CAAC,OAAO,CAAC;oBAClB,MAAM,EAAE,cAAc;oBACtB,GAAG,EAAE,4HAA4H;iBAClI;aACF;KACR,CAAC;IAEF,WAAW,CAAC;QACV,EAAE,EAAE,kBAAkB;QACtB,IAAI,EAAE,MAAM;QACZ,WAAW,EAAE,8EAA8E;QAC3F,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,eAAe,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QAChD,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE;YACT,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YAC9B,MAAM,QAAQ,GAAc,EAAE,CAAC;YAC/B,MAAM,OAAO,GAAG,QAAQ,CAAC,qBAAqB,CAAC;YAC/C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,EAAE,CAAC;gBAC3E,QAAQ,CAAC,IAAI,CAAC;oBACZ,OAAO,EAAE,kBAAkB;oBAC3B,QAAQ,EAAE,OAAO;oBACjB,OAAO,EAAE,2DAA2D;oBACpE,OAAO,EAAE,CAAC,OAAO,CAAC;oBAClB,MAAM,EAAE,cAAc;oBACtB,GAAG,EAAE,oDAAoD;iBAC1D,CAAC,CAAC;YACL,CAAC;YACD,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;YACxC,MAAM,GAAG,GAAG,CAAC,CAAC,MAAM,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YACzD,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,QAAQ,CAAC,IAAI,CAAC;oBACZ,OAAO,EAAE,kBAAkB;oBAC3B,QAAQ,EAAE,OAAO;oBACjB,OAAO,EAAE,8CAA8C;oBACvD,OAAO,EAAE,CAAC,OAAO,CAAC;oBAClB,MAAM,EAAE,cAAc;oBACtB,GAAG,EAAE,oBAAoB,GAAG,IAAI;iBACjC,CAAC,CAAC;YACL,CAAC;iBAAM,IAAI,oBAAoB,CAAC,QAAQ,CAAC,KAAK,oBAAoB,CAAC,GAAG,CAAC,EAAE,CAAC;gBACxE,QAAQ,CAAC,IAAI,CAAC;oBACZ,OAAO,EAAE,kBAAkB;oBAC3B,QAAQ,EAAE,OAAO;oBACjB,OAAO,EAAE,QAAQ;oBACjB,OAAO,EAAE,eAAe,QAAQ,yBAAyB,GAAG,0EAA0E;oBACtI,OAAO,EAAE,CAAC,OAAO,CAAC;oBAClB,MAAM,EAAE,cAAc;oBACtB,GAAG,EAAE,6CAA6C;iBACnD,CAAC,CAAC;YACL,CAAC;YACD,OAAO,QAAQ,CAAC;QAClB,CAAC;KACF,CAAC;IAEF,WAAW,CAAC;QACV,EAAE,EAAE,kBAAkB;QACtB,IAAI,EAAE,MAAM;QACZ,WAAW,EAAE,iEAAiE;QAC9E,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,eAAe,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAK,CAAC,mBAAmB,CAAC,MAAM,GAAG,CAAC;QAC9E,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,CACT,GAAG,CAAC,CAAC,CAAC;YACJ,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC;gBACE;oBACE,OAAO,EAAE,kBAAkB;oBAC3B,QAAQ,EAAE,OAAO;oBACjB,OAAO,EAAE,8DAA8D;oBACvE,QAAQ,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,IAAK,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE;oBAChG,OAAO,EAAE,CAAC,OAAO,CAAC;oBAClB,MAAM,EAAE,cAAc;oBACtB,GAAG,EAAE,oGAAoG;iBAC1G;aACF;KACR,CAAC;IAEF,WAAW,CAAC;QACV,EAAE,EAAE,sBAAsB;QAC1B,IAAI,EAAE,MAAM;QACZ,WAAW,EAAE,oEAAoE;QACjF,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,eAAe,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QAChD,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE;YACT,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,qBAAqB,CAAC;YACnD,mEAAmE;YACnE,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YAChH,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;YACxC,IAAI,CAAC,UAAU,IAAI,CAAC,MAAM,IAAI,oBAAoB,CAAC,MAAM,CAAC,KAAK,oBAAoB,CAAC,UAAU,CAAC,CAAC;gBAAE,OAAO,EAAE,CAAC;YAC5G,OAAO;gBACL;oBACE,OAAO,EAAE,sBAAsB;oBAC/B,QAAQ,EAAE,OAAO;oBACjB,OAAO,EAAE,sBAAsB,IAAI,CAAC,SAAS,CAAC,MAAM,IAAI,IAAI,CAAC,2BAA2B,UAAU,2DAA2D;oBAC7J,OAAO,EAAE,CAAC,OAAO,CAAC;oBAClB,MAAM,EAAE,cAAc;oBACtB,GAAG,EAAE,gFAAgF;iBACtF;aACF,CAAC;QACJ,CAAC;KACF,CAAC;IAEF,WAAW,CAAC;QACV,EAAE,EAAE,wBAAwB;QAC5B,IAAI,EAAE,MAAM;QACZ,WAAW,EAAE,2CAA2C;QACxD,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,eAAe,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QAChD,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE;YACT,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,gCAAgC,CAAC;YAC9D,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;gBAAE,OAAO,EAAE,CAAC;YAClE,OAAO;gBACL;oBACE,OAAO,EAAE,wBAAwB;oBACjC,QAAQ,EAAE,OAAO;oBACjB,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;wBAC7B,CAAC,CAAC,uCAAuC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,gBAAgB;wBAChF,CAAC,CAAC,wIAAwI;oBAC5I,OAAO,EAAE,CAAC,OAAO,CAAC;oBAClB,MAAM,EAAE,cAAc;oBACtB,GAAG,EAAE,yDAAyD;iBAC/D;aACF,CAAC;QACJ,CAAC;KACF,CAAC;IAEF,WAAW,CAAC;QACV,EAAE,EAAE,0BAA0B;QAC9B,IAAI,EAAE,MAAM;QACZ,WAAW,EAAE,+CAA+C;QAC5D,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,eAAe,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QAChD,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE;YACT,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YAC9B,MAAM,IAAI,GAAG,QAAQ,CAAC,qCAAqC,KAAK,IAAI,CAAC;YACrE,MAAM,GAAG,GAAG,OAAO,QAAQ,CAAC,qBAAqB,KAAK,QAAQ,CAAC;YAC/D,IAAI,IAAI;gBAAE,OAAO,EAAE,CAAC;YACpB,IAAI,GAAG,EAAE,CAAC;gBACR,OAAO;oBACL;wBACE,OAAO,EAAE,0BAA0B;wBACnC,QAAQ,EAAE,MAAM;wBAChB,OAAO,EACL,gKAAgK;wBAClK,MAAM,EAAE,iBAAiB;wBACzB,GAAG,EAAE,6DAA6D;qBACnE;iBACF,CAAC;YACJ,CAAC;YACD,OAAO;gBACL;oBACE,OAAO,EAAE,0BAA0B;oBACnC,QAAQ,EAAE,MAAM;oBAChB,OAAO,EACL,sJAAsJ;oBACxJ,OAAO,EAAE,CAAC,OAAO,CAAC;oBAClB,MAAM,EAAE,iBAAiB;oBACzB,GAAG,EAAE,wFAAwF;iBAC9F;aACF,CAAC;QACJ,CAAC;KACF,CAAC;IAEF,WAAW,CAAC;QACV,EAAE,EAAE,mBAAmB;QACvB,IAAI,EAAE,MAAM;QACZ,WAAW,EAAE,8CAA8C;QAC3D,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,KAAK,MAAM;QAC1C,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE;YACT,MAAM,IAAI,GAAG;gBACX,CAAC,CAAC,MAAM,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE;gBAC5C,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;qBAC5B,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;qBACxC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;aAChC,CAAC;YACF,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;gBACjC,IAAI,CAAC;oBACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC;oBACvB,OAAO,GAAG,CAAC,QAAQ,KAAK,OAAO,IAAI,CAAC,CAAC,WAAW,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;gBACjG,CAAC;gBAAC,MAAM,CAAC;oBACP,OAAO,KAAK,CAAC;gBACf,CAAC;YACH,CAAC,CAAC,CAAC;YACH,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBACxC,OAAO,EAAE,mBAAmB;gBAC5B,QAAQ,EAAE,MAAe;gBACzB,OAAO,EAAE,CAAC;gBACV,OAAO,EAAE,mGAAmG;gBAC5G,GAAG,EAAE,mBAAmB;aACzB,CAAC,CAAC,CAAC;QACN,CAAC;KACF,CAAC;CACH,CAAC"}

package/dist/checks/calls.d.ts

@@ -0,0 +1,4 @@
+/** Validates structuredContent against outputSchema; undefined if the schema can't be compiled. */
+export declare function validateStructured(schema: Record<string, unknown>, value: unknown): string[] | undefined;
+export declare const callChecks: import("./types.js").Check[];
+//# sourceMappingURL=calls.d.ts.map

package/dist/checks/calls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"calls.d.ts","sourceRoot":"","sources":["../../src/checks/calls.ts"],"names":[],"mappings":"AAmBA,mGAAmG;AACnG,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,GAAG,SAAS,CAUxG;AAID,eAAO,MAAM,UAAU,8BAyKtB,CAAC"}

package/dist/checks/calls.js

@@ -0,0 +1,192 @@
+import { CallToolResultSchema } from "@modelcontextprotocol/sdk/types.js";
+import { Ajv } from "ajv";
+import { Ajv2020 } from "ajv/dist/2020.js";
+import { isObject, items } from "./util.js";
+import { defineCheck } from "./types.js";
+const ajv2020 = new Ajv2020({ strict: false, allErrors: false, logger: false });
+const ajv07 = new Ajv({ strict: false, allErrors: false, logger: false });
+const answered = (s) => (s.calls ?? []).filter((c) => c.result);
+const hasCalls = (s) => (s.calls?.length ?? 0) > 0;
+const isToolError = (c) => c.result?.isError === true;
+function outputSchemaFor(s, tool) {
+    const t = items(s, "tools").find((t) => t.name === tool);
+    return t && isObject(t.outputSchema) ? t.outputSchema : undefined;
+}
+/** Validates structuredContent against outputSchema; undefined if the schema can't be compiled. */
+export function validateStructured(schema, value) {
+    const validator = /draft-0[67]/.test(String(schema.$schema ?? "")) ? ajv07 : ajv2020;
+    let validate;
+    try {
+        validate = validator.compile(schema);
+    }
+    catch {
+        return undefined;
+    }
+    if (validate(value))
+        return [];
+    return (validate.errors ?? []).map((e) => `${e.instancePath || "/"} ${e.message ?? "is invalid"}`);
+}
+const call = (c) => `${c.tool}(${JSON.stringify(c.args)})`;
+export const callChecks = [
+    defineCheck({
+        id: "CALL_RESULT_INVALID",
+        area: "calls",
+        description: "tools/call results match the MCP result schema",
+        appliesTo: hasCalls,
+        run: (s) => answered(s).flatMap((c) => {
+            const parsed = CallToolResultSchema.safeParse(c.result);
+            if (parsed.success)
+                return [];
+            const issue = parsed.error.issues[0];
+            return [
+                {
+                    checkId: "CALL_RESULT_INVALID",
+                    severity: "error",
+                    subject: c.tool,
+                    message: `Result of ${call(c)} is not a valid CallToolResult (${issue?.path.join(".") || "result"}: ${issue?.message}); SDK-based clients throw instead of showing it.`,
+                    evidence: { issues: parsed.error.issues.slice(0, 5) },
+                    fix: 'Return { content: [{ type: "text", text: "..." }] } (plus structuredContent/isError as needed).',
+                },
+            ];
+        }),
+    }),
+    defineCheck({
+        id: "CALL_OUTPUT_SCHEMA_MISMATCH",
+        area: "calls",
+        description: "Tools with an outputSchema return matching structuredContent",
+        appliesTo: (s) => answered(s).some((c) => outputSchemaFor(s, c.tool)),
+        run: (s) => answered(s).flatMap((c) => {
+            const schema = outputSchemaFor(s, c.tool);
+            if (!schema || isToolError(c))
+                return [];
+            if (!("structuredContent" in c.result)) {
+                return [
+                    {
+                        checkId: "CALL_OUTPUT_SCHEMA_MISMATCH",
+                        severity: "error",
+                        subject: c.tool,
+                        message: `${c.tool} declares an outputSchema but ${call(c)} returned no structuredContent; the spec requires it, and SDK clients reject the result.`,
+                        fix: "Return structuredContent matching outputSchema (and keep a text copy for older clients).",
+                    },
+                ];
+            }
+            const errors = validateStructured(schema, c.result.structuredContent);
+            if (!errors?.length)
+                return [];
+            return [
+                {
+                    checkId: "CALL_OUTPUT_SCHEMA_MISMATCH",
+                    severity: "error",
+                    subject: c.tool,
+                    message: `structuredContent from ${call(c)} doesn't match outputSchema: ${errors.slice(0, 3).join("; ")}. SDK clients reject such results.`,
+                    evidence: { errors },
+                    fix: "Make the returned data match outputSchema, or update the schema.",
+                },
+            ];
+        }),
+    }),
+    defineCheck({
+        id: "CALL_STRUCTURED_WITHOUT_TEXT",
+        area: "calls",
+        description: "Structured results also carry a text copy",
+        appliesTo: (s) => answered(s).some((c) => c.result && "structuredContent" in c.result),
+        run: (s, { profiles }) => answered(s).flatMap((c) => {
+            const content = Array.isArray(c.result.content) ? c.result.content : [];
+            if (!("structuredContent" in c.result) || content.some((i) => isObject(i) && i.type === "text"))
+                return [];
+            const textOnly = profiles.filter((p) => p.limits.structuredContent?.value === "textOnly");
+            return [
+                {
+                    checkId: "CALL_STRUCTURED_WITHOUT_TEXT",
+                    severity: "warn",
+                    subject: c.tool,
+                    message: `${call(c)} returned structuredContent with no text content. The spec says tools SHOULD also return the JSON as text for clients that don't read structuredContent.`,
+                    fix: 'Add { type: "text", text: JSON.stringify(structuredContent) } to content.',
+                },
+                ...textOnly.map((p) => ({
+                    checkId: "CALL_STRUCTURED_WITHOUT_TEXT",
+                    severity: "error",
+                    subject: c.tool,
+                    client: p.id,
+                    source: p.limits.structuredContent.source,
+                    message: `${p.displayName} only passes text content to the model, so it gets an empty result from ${c.tool}.`,
+                    fix: 'Add { type: "text", text: JSON.stringify(structuredContent) } to content.',
+                })),
+            ];
+        }),
+    }),
+    defineCheck({
+        id: "CALL_RESULT_TOO_LARGE",
+        area: "calls",
+        description: "Tool results fit each client's result size limit",
+        appliesTo: (s) => answered(s).length > 0,
+        run: (s, { profiles }) => profiles.flatMap((p) => {
+            const limit = p.limits.maxToolResult;
+            if (!limit)
+                return [];
+            return answered(s).flatMap((c) => {
+                const chars = c.resultChars ?? 0;
+                // Tokens are estimated at ~4 characters each; bytes ≈ characters for ASCII.
+                const size = limit.value.unit === "tokens" ? Math.round(chars / 4) : chars;
+                if (size <= limit.value.max)
+                    return [];
+                const what = { truncate: "truncates it", file: "saves it to a file and gives the model a reference instead", unknown: "may cut it off" }[limit.value.onExceed];
+                return [
+                    {
+                        checkId: "CALL_RESULT_TOO_LARGE",
+                        severity: "warn",
+                        subject: c.tool,
+                        client: p.id,
+                        source: limit.source,
+                        message: `${call(c)} returned about ${size.toLocaleString("en")} ${limit.value.unit}${limit.value.unit === "tokens" ? " (estimated)" : ""}; ${p.displayName} allows ${limit.value.max.toLocaleString("en")} and ${what}.`,
+                        fix: "Paginate or summarise large results, or return a resource link instead of inlining data.",
+                    },
+                ];
+            });
+        }),
+    }),
+    defineCheck({
+        id: "CALL_SLOW",
+        area: "calls",
+        description: "Tool calls finish well within each client's timeout",
+        appliesTo: (s) => answered(s).length > 0,
+        run: (s, { profiles }) => profiles.flatMap((p) => {
+            const timeout = p.limits.toolTimeoutMs;
+            if (!timeout)
+                return [];
+            return answered(s)
+                .filter((c) => c.durationMs > timeout.value / 2)
+                .map((c) => ({
+                checkId: "CALL_SLOW",
+                severity: c.durationMs > timeout.value ? "error" : "warn",
+                subject: c.tool,
+                client: p.id,
+                source: timeout.source,
+                message: `${call(c)} took ${(c.durationMs / 1000).toFixed(1)} s; ${p.displayName} times out after ${timeout.value / 1000} s.`,
+                fix: "Return quickly and report progress, or move long work behind a job id the model can poll.",
+            }));
+        }),
+    }),
+    defineCheck({
+        id: "CALL_FAILED",
+        area: "calls",
+        description: "Reports tool calls that errored",
+        appliesTo: hasCalls,
+        run: (s) => (s.calls ?? [])
+            .filter((c) => c.error || isToolError(c))
+            .map((c) => {
+            const text = Array.isArray(c.result?.content)
+                ? c.result.content.map((i) => (isObject(i) && typeof i.text === "string" ? i.text : "")).join(" ").slice(0, 200)
+                : "";
+            return {
+                checkId: "CALL_FAILED",
+                severity: "info",
+                subject: c.tool,
+                message: c.error
+                    ? `${call(c)} failed with a protocol error${c.error.code !== undefined ? ` ${c.error.code}` : ""}: ${c.error.message}${c.origin === "probe" ? " (arguments were generated from the schema, so this may be expected)" : ""}.`
+                    : `${call(c)} returned isError: ${text}`,
+            };
+        }),
+    }),
+];
+//# sourceMappingURL=calls.js.map

package/dist/checks/calls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"calls.js","sourceRoot":"","sources":["../../src/checks/calls.ts"],"names":[],"mappings":"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"}

package/dist/checks/discovery.d.ts

@@ -0,0 +1,3 @@
+import { type Check } from "./types.js";
+export declare const discoveryChecks: Check[];
+//# sourceMappingURL=discovery.d.ts.map

package/dist/checks/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../src/checks/discovery.ts"],"names":[],"mappings":"AAGA,OAAO,EAAe,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AA2CrD,eAAO,MAAM,eAAe,SAM3B,CAAC"}

package/dist/checks/discovery.js

@@ -0,0 +1,47 @@
+import { connected, featureGap, isObject, items } from "./util.js";
+import { defineCheck } from "./types.js";
+function listChangedCheck(kind, feature) {
+    const id = `DISCOVERY_${kind.toUpperCase()}_LIST_CHANGED`;
+    return defineCheck({
+        id,
+        area: "discovery",
+        description: `Notes clients that ignore ${kind}/list_changed when the server declares it`,
+        appliesTo: (s) => {
+            const cap = s.initialize?.capabilities?.[kind];
+            return connected(s) && isObject(cap) && cap.listChanged === true;
+        },
+        run: (s, { profiles }) => 
+        // INFO, not WARN: declaring listChanged (the SDK default) doesn't mean the list ever changes.
+        featureGap(profiles, feature, (p, partial) => ({
+            checkId: id,
+            severity: "info",
+            message: `Server declares ${kind}.listChanged, but ${p.displayName} ${partial ? "does not reliably refresh" : "does not refresh"} its ${kind} list during a session. If ${kind} change at runtime, users must reconnect to see them.`,
+            fix: `Register all ${kind} at startup if you can; enable/disable them instead of adding new ones later.`,
+        })),
+    });
+}
+function unsupportedFeatureCheck(kind, feature) {
+    const id = `DISCOVERY_${kind.toUpperCase()}_UNSUPPORTED`;
+    return defineCheck({
+        id,
+        area: "discovery",
+        description: `Clients without ${kind} support are flagged when the server exposes ${kind}`,
+        appliesTo: (s) => connected(s) && items(s, kind).length > 0,
+        run: (s, { profiles }) => featureGap(profiles, feature, (p, partial) => ({
+            checkId: id,
+            severity: "warn",
+            message: `Server exposes ${items(s, kind).length} ${kind}, but ${p.displayName} ${partial ? "only partly supports" : "does not support"} MCP ${kind}. Anything only reachable through them may be missing there.`,
+            fix: kind === "prompts"
+                ? "Don't rely on prompts for core functionality; mention workflows in tool descriptions too."
+                : "Offer important resource content through a tool as well.",
+        })),
+    });
+}
+export const discoveryChecks = [
+    listChangedCheck("tools", "toolsListChanged"),
+    listChangedCheck("resources", "resourcesListChanged"),
+    listChangedCheck("prompts", "promptsListChanged"),
+    unsupportedFeatureCheck("resources", "resources"),
+    unsupportedFeatureCheck("prompts", "prompts"),
+];
+//# sourceMappingURL=discovery.js.map

package/dist/checks/discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../../src/checks/discovery.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AACnE,OAAO,EAAE,WAAW,EAAc,MAAM,YAAY,CAAC;AAErD,SAAS,gBAAgB,CAAC,IAAuC,EAAE,OAAsB;IACvF,MAAM,EAAE,GAAG,aAAa,IAAI,CAAC,WAAW,EAAE,eAAe,CAAC;IAC1D,OAAO,WAAW,CAAC;QACjB,EAAE;QACF,IAAI,EAAE,WAAW;QACjB,WAAW,EAAE,6BAA6B,IAAI,2CAA2C;QACzF,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE;YACf,MAAM,GAAG,GAAG,CAAC,CAAC,UAAU,EAAE,YAAY,EAAE,CAAC,IAAI,CAAC,CAAC;YAC/C,OAAO,SAAS,CAAC,CAAC,CAAC,IAAI,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,WAAW,KAAK,IAAI,CAAC;QACnE,CAAC;QACD,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE;QACvB,8FAA8F;QAC9F,UAAU,CAAC,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC;YAC7C,OAAO,EAAE,EAAE;YACX,QAAQ,EAAE,MAAM;YAChB,OAAO,EAAE,mBAAmB,IAAI,qBAAqB,CAAC,CAAC,WAAW,IAAI,OAAO,CAAC,CAAC,CAAC,2BAA2B,CAAC,CAAC,CAAC,kBAAkB,QAAQ,IAAI,8BAA8B,IAAI,uDAAuD;YACrO,GAAG,EAAE,gBAAgB,IAAI,+EAA+E;SACzG,CAAC,CAAC;KACN,CAAC,CAAC;AACL,CAAC;AAED,SAAS,uBAAuB,CAAC,IAA0C,EAAE,OAAsB;IACjG,MAAM,EAAE,GAAG,aAAa,IAAI,CAAC,WAAW,EAAE,cAAc,CAAC;IACzD,OAAO,WAAW,CAAC;QACjB,EAAE;QACF,IAAI,EAAE,WAAW;QACjB,WAAW,EAAE,mBAAmB,IAAI,gDAAgD,IAAI,EAAE;QAC1F,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC;QAC3D,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,CACvB,UAAU,CAAC,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC;YAC7C,OAAO,EAAE,EAAE;YACX,QAAQ,EAAE,MAAM;YAChB,OAAO,EAAE,kBAAkB,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,MAAM,IAAI,IAAI,SAAS,CAAC,CAAC,WAAW,IAAI,OAAO,CAAC,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,kBAAkB,QAAQ,IAAI,8DAA8D;YACjN,GAAG,EACD,IAAI,KAAK,SAAS;gBAChB,CAAC,CAAC,2FAA2F;gBAC7F,CAAC,CAAC,0DAA0D;SACjE,CAAC,CAAC;KACN,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,gBAAgB,CAAC,OAAO,EAAE,kBAAkB,CAAC;IAC7C,gBAAgB,CAAC,WAAW,EAAE,sBAAsB,CAAC;IACrD,gBAAgB,CAAC,SAAS,EAAE,oBAAoB,CAAC;IACjD,uBAAuB,CAAC,WAAW,EAAE,WAAW,CAAC;IACjD,uBAAuB,CAAC,SAAS,EAAE,SAAS,CAAC;CAC9C,CAAC"}

package/dist/checks/explanations.d.ts

@@ -0,0 +1,15 @@
+import type { ClientFeature, ClientProfile } from "../profiles/types.js";
+type LimitKey = keyof ClientProfile["limits"];
+export interface Explanation {
+    /** Why the check exists, in one or two sentences. */
+    why: string;
+    /** Spec pages, RFCs or SDK source backing the check itself. */
+    sources?: string[];
+    /** Client profile limits the check reads; `explain` prints them per client. */
+    limits?: LimitKey[];
+    /** Client features the check depends on; `explain` prints them per client. */
+    features?: ClientFeature[];
+}
+export declare const EXPLANATIONS: Record<string, Explanation>;
+export {};
+//# sourceMappingURL=explanations.d.ts.map

package/dist/checks/explanations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explanations.d.ts","sourceRoot":"","sources":["../../src/checks/explanations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAEzE,KAAK,QAAQ,GAAG,MAAM,aAAa,CAAC,QAAQ,CAAC,CAAC;AAE9C,MAAM,WAAW,WAAW;IAC1B,qDAAqD;IACrD,GAAG,EAAE,MAAM,CAAC;IACZ,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC;IACpB,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAC;CAC5B;AASD,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAkVpD,CAAC"}