toolmenu 0.20.1 → 0.23.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 +119 -41
- package/dist/apps.d.ts +56 -0
- package/dist/apps.js +99 -0
- package/dist/auth.d.ts +14 -0
- package/dist/auth.js +75 -2
- package/dist/auto.d.ts +6 -0
- package/dist/auto.js +70 -7
- package/dist/card.d.ts +18 -0
- package/dist/card.js +39 -0
- package/dist/cli.js +108 -24
- package/dist/colour.d.ts +8 -0
- package/dist/colour.js +70 -0
- package/dist/config.d.ts +2 -0
- package/dist/config.js +2 -0
- package/dist/connect.d.ts +14 -0
- package/dist/connect.js +45 -7
- package/dist/diff.js +112 -13
- package/dist/explain.d.ts +1 -0
- package/dist/explain.js +11 -0
- package/dist/failures.d.ts +24 -0
- package/dist/failures.js +58 -1
- package/dist/help.d.ts +1 -1
- package/dist/help.js +36 -4
- package/dist/mrtr.d.ts +9 -1
- package/dist/mrtr.js +17 -0
- package/dist/options.d.ts +15 -0
- package/dist/options.js +5 -0
- package/dist/probe.d.ts +11 -1
- package/dist/probe.js +18 -3
- package/dist/report.d.ts +3 -0
- package/dist/report.js +15 -8
- package/dist/rule-docs.d.ts +26 -0
- package/dist/rule-docs.js +88 -0
- package/dist/rule-docs.json +597 -0
- package/dist/rules/apps.d.ts +11 -0
- package/dist/rules/apps.js +156 -0
- package/dist/rules/auth.d.ts +18 -0
- package/dist/rules/auth.js +29 -0
- package/dist/rules/capabilities.d.ts +21 -0
- package/dist/rules/capabilities.js +103 -0
- package/dist/rules/card.d.ts +7 -0
- package/dist/rules/card.js +65 -0
- package/dist/rules/clients.js +1 -0
- package/dist/rules/description.js +3 -0
- package/dist/rules/handles.d.ts +13 -0
- package/dist/rules/handles.js +78 -0
- package/dist/rules/ids.js +35 -1
- package/dist/rules/index.js +20 -2
- package/dist/rules/naming.js +3 -0
- package/dist/rules/network.d.ts +21 -0
- package/dist/rules/network.js +63 -0
- package/dist/rules/rule.d.ts +20 -0
- package/dist/rules/search.js +1 -0
- package/dist/rules/spec.d.ts +9 -1
- package/dist/rules/spec.js +117 -3
- package/dist/rules/write.d.ts +0 -6
- package/dist/rules/write.js +11 -5
- package/dist/scan.d.ts +47 -0
- package/dist/scan.js +334 -0
- package/dist/session.d.ts +2 -0
- package/dist/session.js +149 -9
- package/dist/snapshot.d.ts +15 -0
- package/dist/snapshot.js +130 -5
- package/dist/types.d.ts +5 -0
- package/dist/words.d.ts +10 -0
- package/dist/words.js +44 -2
- package/package.json +2 -2
- package/schemas/server-card.json +260 -0
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
import { APPS_MIME_TYPE } from '../connect.js';
|
|
2
|
+
import { isAppOnly, isAppsMimeType, LEGACY_URI_KEY, uiMeta } from '../apps.js';
|
|
3
|
+
import { clip, count, kept, names } from './rule.js';
|
|
4
|
+
/*
|
|
5
|
+
* MCP Apps (ext-apps): checks on the UI a tool names, as an Apps host reads it.
|
|
6
|
+
* Each traced to specification/draft/apps.mdx:
|
|
7
|
+
* "URI MUST start with ui:// scheme"; "Resource MUST exist on the server";
|
|
8
|
+
* "mimeType MUST be text/html;profile=mcp-app"; "Content MUST be provided via
|
|
9
|
+
* either text or blob"; visibility "model" | "app", "Host MUST NOT include tools in
|
|
10
|
+
* the agent's tool list when their visibility does not include "model"".
|
|
11
|
+
*/
|
|
12
|
+
const FALLBACK = 'An Apps host then shows no UI for the tool; the agent still gets its text result.';
|
|
13
|
+
export const appsResource = {
|
|
14
|
+
id: 'apps/resource',
|
|
15
|
+
severity: 'warn',
|
|
16
|
+
summary: "The UI a tool names (MCP Apps _meta.ui.resourceUri) is a ui:// resource the server serves as an app",
|
|
17
|
+
run(ctx) {
|
|
18
|
+
const problems = [];
|
|
19
|
+
const read = new Map((ctx.appResources ?? []).map((r) => [r.uri, r]));
|
|
20
|
+
for (const tool of kept(ctx.menu.tools, ctx)) {
|
|
21
|
+
const ui = uiMeta(tool);
|
|
22
|
+
if (!ui || (ui.resourceUri === undefined && ui.legacyUri === undefined))
|
|
23
|
+
continue;
|
|
24
|
+
const uri = ui.resourceUri ?? ui.legacyUri;
|
|
25
|
+
if (typeof uri !== 'string' || !uri) {
|
|
26
|
+
problems.push({ tool: tool.name, why: `_meta.ui.resourceUri is ${JSON.stringify(uri)}, not a ui:// URI` });
|
|
27
|
+
continue;
|
|
28
|
+
}
|
|
29
|
+
if (typeof ui.resourceUri === 'string' && typeof ui.legacyUri === 'string' && ui.resourceUri !== ui.legacyUri) {
|
|
30
|
+
problems.push({ tool: tool.name, why: `_meta.ui.resourceUri is ${ui.resourceUri} but _meta["${LEGACY_URI_KEY}"] is ${ui.legacyUri}: hosts that read the old key render another UI` });
|
|
31
|
+
}
|
|
32
|
+
if (!uri.startsWith('ui://')) {
|
|
33
|
+
problems.push({ tool: tool.name, why: `${clip(uri, 80)} isn't a ui:// URI, which MCP Apps require` });
|
|
34
|
+
continue;
|
|
35
|
+
}
|
|
36
|
+
const r = read.get(uri);
|
|
37
|
+
if (!r)
|
|
38
|
+
continue; // not read (over the limit, or the run read none)
|
|
39
|
+
const why = resourceProblem(r);
|
|
40
|
+
if (why)
|
|
41
|
+
problems.push({ tool: tool.name, why });
|
|
42
|
+
}
|
|
43
|
+
if (!problems.length)
|
|
44
|
+
return [];
|
|
45
|
+
const tools = [...new Set(problems.map((p) => p.tool))];
|
|
46
|
+
const one = tools.length === 1;
|
|
47
|
+
return [
|
|
48
|
+
{
|
|
49
|
+
...(one ? { tool: tools[0] } : {}),
|
|
50
|
+
message: `${one ? `${tools[0]} names` : `${count(tools.length, 'tool')} name`} an MCP Apps UI that a host can't render: ${one ? problems[0].why : names(tools, 6)}. ${FALLBACK}`,
|
|
51
|
+
...(one && problems.length === 1 ? {} : { detail: problems.map((p) => `${p.tool}: ${p.why}`) }),
|
|
52
|
+
fix: `Serve each UI as a ui:// resource that resources/read returns with mimeType "${APPS_MIME_TYPE}" and the HTML as text or blob, and point _meta.ui.resourceUri at it.`,
|
|
53
|
+
},
|
|
54
|
+
];
|
|
55
|
+
},
|
|
56
|
+
};
|
|
57
|
+
function resourceProblem(r) {
|
|
58
|
+
if (r.error)
|
|
59
|
+
return `resources/read of ${r.uri} failed (${clip(r.error, 120)}): the spec says the resource MUST exist on the server`;
|
|
60
|
+
const types = r.mimeTypes ?? [];
|
|
61
|
+
if (!types.length)
|
|
62
|
+
return `resources/read of ${r.uri} returned no contents`;
|
|
63
|
+
const wrong = types.filter((m) => !isAppsMimeType(m));
|
|
64
|
+
if (wrong.length)
|
|
65
|
+
return `resources/read of ${r.uri} gave mimeType ${wrong.map((m) => (m ? `"${m}"` : 'none')).join(', ')}, not "${APPS_MIME_TYPE}"`;
|
|
66
|
+
if (!r.hasContent)
|
|
67
|
+
return `resources/read of ${r.uri} returned no text or blob`;
|
|
68
|
+
return undefined;
|
|
69
|
+
}
|
|
70
|
+
export const appsLegacyKey = {
|
|
71
|
+
id: 'apps/legacy-key',
|
|
72
|
+
severity: 'info',
|
|
73
|
+
summary: 'Tools name their UI with _meta.ui.resourceUri, not the deprecated _meta["ui/resourceUri"]',
|
|
74
|
+
run(ctx) {
|
|
75
|
+
const old = kept(ctx.menu.tools, ctx).filter((t) => {
|
|
76
|
+
const ui = uiMeta(t);
|
|
77
|
+
return ui && ui.legacyUri !== undefined && ui.resourceUri === undefined;
|
|
78
|
+
});
|
|
79
|
+
if (!old.length)
|
|
80
|
+
return [];
|
|
81
|
+
const one = old.length === 1;
|
|
82
|
+
return [
|
|
83
|
+
{
|
|
84
|
+
...(one ? { tool: old[0].name } : {}),
|
|
85
|
+
message: `${one ? `${old[0].name} names its UI` : `${count(old.length, 'tool')} name their UI`} only with _meta["${LEGACY_URI_KEY}"], which MCP Apps deprecate ("will be removed before GA"). A host that reads only _meta.ui.resourceUri shows ${one ? 'it' : 'them'} without a UI.`,
|
|
86
|
+
...(one ? {} : { detail: [names(old.map((t) => t.name), 20)] }),
|
|
87
|
+
fix: `Add _meta: { ui: { resourceUri: "<the same ui:// URI>" } } to ${one ? old[0].name : 'each'}; keep the old key while older hosts need it.`,
|
|
88
|
+
},
|
|
89
|
+
];
|
|
90
|
+
},
|
|
91
|
+
};
|
|
92
|
+
const VISIBILITIES = new Set(['model', 'app']);
|
|
93
|
+
export const appsVisibility = {
|
|
94
|
+
id: 'apps/visibility',
|
|
95
|
+
severity: 'warn',
|
|
96
|
+
summary: 'MCP Apps _meta.ui.visibility is a list of "model" and "app"',
|
|
97
|
+
run(ctx) {
|
|
98
|
+
const problems = [];
|
|
99
|
+
for (const tool of kept(ctx.menu.tools, ctx)) {
|
|
100
|
+
const v = uiMeta(tool)?.visibility;
|
|
101
|
+
if (v === undefined)
|
|
102
|
+
continue;
|
|
103
|
+
if (!Array.isArray(v)) {
|
|
104
|
+
problems.push({ tool: tool.name, why: `visibility is ${clip(JSON.stringify(v), 60)}, not a list` });
|
|
105
|
+
continue;
|
|
106
|
+
}
|
|
107
|
+
const unknown = v.filter((x) => typeof x !== 'string' || !VISIBILITIES.has(x));
|
|
108
|
+
if (unknown.length)
|
|
109
|
+
problems.push({ tool: tool.name, why: `visibility has ${unknown.map((x) => JSON.stringify(x)).join(', ')}, which hosts don't know` });
|
|
110
|
+
if (!v.includes('model') && !v.includes('app'))
|
|
111
|
+
problems.push({ tool: tool.name, why: 'visibility names neither "model" nor "app", so no one can call it: not the agent, not the app' });
|
|
112
|
+
}
|
|
113
|
+
if (!problems.length)
|
|
114
|
+
return [];
|
|
115
|
+
const tools = [...new Set(problems.map((p) => p.tool))];
|
|
116
|
+
const one = tools.length === 1;
|
|
117
|
+
return [
|
|
118
|
+
{
|
|
119
|
+
...(one ? { tool: tools[0] } : {}),
|
|
120
|
+
message: `${one ? `${tools[0]}'s` : `${count(tools.length, 'tool')}' `} MCP Apps visibility ${one ? 'is' : 'are'} not what hosts read: ${one ? problems[0].why : names(tools, 6)}. Hosts show a tool to the agent only when visibility includes "model", and let the app call it only when it includes "app".`,
|
|
121
|
+
...(one && problems.length === 1 ? {} : { detail: problems.map((p) => `${p.tool}: ${p.why}`) }),
|
|
122
|
+
fix: 'Set _meta.ui.visibility to ["model", "app"] (the default when it is left out), ["model"], or ["app"] for a tool only the app calls.',
|
|
123
|
+
},
|
|
124
|
+
];
|
|
125
|
+
},
|
|
126
|
+
};
|
|
127
|
+
/**
|
|
128
|
+
* App-only tools listed to a client that didn't declare MCP Apps. Such a client doesn't
|
|
129
|
+
* read _meta.ui, so it puts them in its agent's list: tools meant to be called by an
|
|
130
|
+
* app's UI, offered to the agent. ext-apps: "Servers SHOULD check client capabilities
|
|
131
|
+
* before registering UI-enabled tools".
|
|
132
|
+
*/
|
|
133
|
+
export const appsAppOnlyListed = {
|
|
134
|
+
id: 'apps/app-only-listed',
|
|
135
|
+
severity: 'warn',
|
|
136
|
+
summary: 'App-only tools are listed only to clients that declare MCP Apps',
|
|
137
|
+
run(ctx) {
|
|
138
|
+
const plain = ctx.plain?.tools;
|
|
139
|
+
if (!plain)
|
|
140
|
+
return [];
|
|
141
|
+
// Marked for the app: a visibility that names neither is apps/visibility's.
|
|
142
|
+
const leaked = kept(plain.filter((t) => isAppOnly(t) && (uiMeta(t)?.visibility).includes('app')), ctx);
|
|
143
|
+
if (!leaked.length)
|
|
144
|
+
return [];
|
|
145
|
+
const one = leaked.length === 1;
|
|
146
|
+
const list = leaked.map((t) => t.name);
|
|
147
|
+
return [
|
|
148
|
+
{
|
|
149
|
+
...(one ? { tool: list[0] } : {}),
|
|
150
|
+
message: `${one ? `${list[0]} is` : `${names(list, 6)} are`} marked for the app only (_meta.ui.visibility without "model"), yet listed to a client that doesn't declare MCP Apps too. That client doesn't read _meta.ui, so its agent is offered ${one ? 'a tool' : 'tools'} meant for an app's UI.`,
|
|
151
|
+
...(one ? {} : { detail: [list.join(', ')] }),
|
|
152
|
+
fix: `List ${one ? 'it' : 'them'} only when the client declares the io.modelcontextprotocol/ui extension (ext-apps' getUiCapability), as the spec asks servers to.`,
|
|
153
|
+
},
|
|
154
|
+
];
|
|
155
|
+
},
|
|
156
|
+
};
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
import type { MenuTool } from '../types.js';
|
|
2
|
+
import { type Rule } from './rule.js';
|
|
3
|
+
/** What an HTTP server answered to the same listing with an invalid credential. */
|
|
4
|
+
export interface InvalidCredential {
|
|
5
|
+
/** It served a menu anyway. */
|
|
6
|
+
tools?: MenuTool[];
|
|
7
|
+
/** It refused with this HTTP status (401 or 403 is the answer a client can act on). */
|
|
8
|
+
status?: number;
|
|
9
|
+
/** It failed some other way. */
|
|
10
|
+
error?: string;
|
|
11
|
+
}
|
|
12
|
+
/**
|
|
13
|
+
* A credential that can't be valid, in place of the one this run used. A server that
|
|
14
|
+
* answers it with a menu, not 401, gives a client whose token expired or was revoked
|
|
15
|
+
* no reason to log in again: the agent just has fewer tools (Atlassian Rovo served 4
|
|
16
|
+
* of its tools to any Authorization header, 2026-11-03).
|
|
17
|
+
*/
|
|
18
|
+
export declare const invalidCredential: Rule;
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import { count, names, num } from './rule.js';
|
|
2
|
+
/**
|
|
3
|
+
* A credential that can't be valid, in place of the one this run used. A server that
|
|
4
|
+
* answers it with a menu, not 401, gives a client whose token expired or was revoked
|
|
5
|
+
* no reason to log in again: the agent just has fewer tools (Atlassian Rovo served 4
|
|
6
|
+
* of its tools to any Authorization header, 2026-11-03).
|
|
7
|
+
*/
|
|
8
|
+
export const invalidCredential = {
|
|
9
|
+
id: 'auth/invalid-accepted',
|
|
10
|
+
severity: 'warn',
|
|
11
|
+
summary: 'An invalid credential gets an auth error, not a menu',
|
|
12
|
+
run(ctx) {
|
|
13
|
+
const probe = ctx.invalidCredential;
|
|
14
|
+
if (!probe?.tools)
|
|
15
|
+
return [];
|
|
16
|
+
const mine = ctx.menu.tools.map((t) => t.name);
|
|
17
|
+
const theirs = probe.tools.map((t) => t.name);
|
|
18
|
+
const same = theirs.length === mine.length && theirs.every((n) => mine.includes(n));
|
|
19
|
+
return [
|
|
20
|
+
{
|
|
21
|
+
message: same
|
|
22
|
+
? `With an invalid credential in place of this run's, the server served the same ${count(theirs.length, 'tool')} instead of refusing (401). Listing doesn't check credentials, so a client learns its token expired or was revoked only when a call fails.`
|
|
23
|
+
: `With an invalid credential in place of this run's, the server served ${count(theirs.length, 'tool')} (of ${num(mine.length)} with it) instead of refusing (401). A client whose token expired or was revoked gets a smaller menu, not an auth error, so it has no reason to ask the user to log in again; the agent just has fewer tools.`,
|
|
24
|
+
detail: same ? [] : [`served to the invalid credential: ${names(theirs, 10)}`],
|
|
25
|
+
fix: "Answer a request whose credential doesn't verify with 401 and a WWW-Authenticate header, even for tools that need no login: a client re-authenticates on 401. If some tools are meant to work without a login, serve them to requests with no credential, not to ones with a bad credential.",
|
|
26
|
+
},
|
|
27
|
+
];
|
|
28
|
+
},
|
|
29
|
+
};
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
import { type Rule } from './rule.js';
|
|
2
|
+
import type { MenuTool } from '../types.js';
|
|
3
|
+
/**
|
|
4
|
+
* snapshot lists the menu as a client that supports elicitation and MCP Apps, and once
|
|
5
|
+
* more as one that declares neither. A server may list a tool only to clients that can
|
|
6
|
+
* ask the user to confirm (github-mcp-server 1.14's delete_repository), or register
|
|
7
|
+
* other tools, or other variants of them, for a host that renders apps (ext-apps:
|
|
8
|
+
* "Servers MAY register different tool variants based on host capabilities"). Allowed;
|
|
9
|
+
* worth knowing, because a client without the capability never sees those tools, and a
|
|
10
|
+
* baseline made without it misses them. When the two differ, a third listing with
|
|
11
|
+
* elicitation alone tells which capability each tool depends on.
|
|
12
|
+
*/
|
|
13
|
+
export interface PlainMenu {
|
|
14
|
+
tools?: MenuTool[];
|
|
15
|
+
error?: string;
|
|
16
|
+
/** Listed with elicitation and without MCP Apps: set only when `tools` differs from the main menu. */
|
|
17
|
+
elicitationOnly?: MenuTool[];
|
|
18
|
+
}
|
|
19
|
+
/** Whether the rule has anything to say about these two listings: snapshot lists a third time only then. */
|
|
20
|
+
export declare function listingsDiffer(main: MenuTool[], bare: MenuTool[]): boolean;
|
|
21
|
+
export declare const capabilityDependent: Rule;
|
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
import { names } from './rule.js';
|
|
2
|
+
import { isAppOnly } from '../apps.js';
|
|
3
|
+
const CAN = {
|
|
4
|
+
elicitation: 'supports elicitation (can ask the user to confirm)',
|
|
5
|
+
apps: 'renders MCP Apps (declares io.modelcontextprotocol/ui)',
|
|
6
|
+
either: 'supports elicitation and MCP Apps',
|
|
7
|
+
};
|
|
8
|
+
const CANNOT = {
|
|
9
|
+
elicitation: "doesn't support elicitation",
|
|
10
|
+
apps: "doesn't render MCP Apps",
|
|
11
|
+
either: 'supports neither elicitation nor MCP Apps',
|
|
12
|
+
};
|
|
13
|
+
const WITHOUT = {
|
|
14
|
+
elicitation: 'A client without elicitation',
|
|
15
|
+
apps: 'A client without MCP Apps',
|
|
16
|
+
either: 'A client with neither',
|
|
17
|
+
};
|
|
18
|
+
/** A tool's definition without toolmenu's token estimate. */
|
|
19
|
+
const definition = (t) => {
|
|
20
|
+
const { tokens: _tokens, ...rest } = t;
|
|
21
|
+
return JSON.stringify(rest);
|
|
22
|
+
};
|
|
23
|
+
/**
|
|
24
|
+
* What the rule compares, between the main listing and a bare one: tools listed only
|
|
25
|
+
* in the main one (app-only tools left out: listing those only to Apps hosts is what
|
|
26
|
+
* ext-apps asks for), only in the bare one, and same-name tools defined otherwise.
|
|
27
|
+
*/
|
|
28
|
+
function compareListings(main, bare) {
|
|
29
|
+
const theirs = new Map(bare.map((t) => [t.name, t]));
|
|
30
|
+
const mine = new Map(main.map((t) => [t.name, t]));
|
|
31
|
+
return {
|
|
32
|
+
theirs,
|
|
33
|
+
mine,
|
|
34
|
+
only: [...mine.keys()].filter((n) => !theirs.has(n) && !isAppOnly(mine.get(n))),
|
|
35
|
+
without: [...theirs.keys()].filter((n) => !mine.has(n)),
|
|
36
|
+
variants: [...mine.keys()].filter((n) => theirs.has(n) && definition(mine.get(n)) !== definition(theirs.get(n))),
|
|
37
|
+
};
|
|
38
|
+
}
|
|
39
|
+
/** Whether the rule has anything to say about these two listings: snapshot lists a third time only then. */
|
|
40
|
+
export function listingsDiffer(main, bare) {
|
|
41
|
+
const { only, without, variants } = compareListings(main, bare);
|
|
42
|
+
return only.length + without.length + variants.length > 0;
|
|
43
|
+
}
|
|
44
|
+
export const capabilityDependent = {
|
|
45
|
+
id: 'menu/capability-dependent',
|
|
46
|
+
severity: 'info',
|
|
47
|
+
summary: 'The tools a client sees depend on whether it supports elicitation or MCP Apps',
|
|
48
|
+
run(ctx) {
|
|
49
|
+
const plain = ctx.plain?.tools;
|
|
50
|
+
if (!plain)
|
|
51
|
+
return [];
|
|
52
|
+
const middle = ctx.plain?.elicitationOnly;
|
|
53
|
+
const { mine, only, without, variants } = compareListings(ctx.menu.tools, plain);
|
|
54
|
+
const halfway = middle ? new Map(middle.map((t) => [t.name, t])) : undefined;
|
|
55
|
+
// Which capability brings a tool, or its variant: the one elicitation alone doesn't.
|
|
56
|
+
const cause = (name, same) => (!halfway ? 'either' : same(halfway.get(name)) ? 'elicitation' : 'apps');
|
|
57
|
+
if (!only.length && !without.length && !variants.length)
|
|
58
|
+
return [];
|
|
59
|
+
const byCause = new Map();
|
|
60
|
+
for (const n of only) {
|
|
61
|
+
const c = cause(n, (m) => m !== undefined);
|
|
62
|
+
byCause.set(c, [...(byCause.get(c) ?? []), n]);
|
|
63
|
+
}
|
|
64
|
+
// A tool that goes away for a capable client (Supabase drops its cost-confirming tools
|
|
65
|
+
// when it can ask the user instead): the capability whose listing lacks it.
|
|
66
|
+
const withoutCause = new Map();
|
|
67
|
+
for (const n of without) {
|
|
68
|
+
const c = !halfway ? 'either' : halfway.has(n) ? 'apps' : 'elicitation';
|
|
69
|
+
withoutCause.set(c, [...(withoutCause.get(c) ?? []), n]);
|
|
70
|
+
}
|
|
71
|
+
const variantCause = new Map();
|
|
72
|
+
for (const n of variants) {
|
|
73
|
+
const c = cause(n, (m) => m !== undefined && definition(m) === definition(mine.get(n)));
|
|
74
|
+
variantCause.set(c, [...(variantCause.get(c) ?? []), n]);
|
|
75
|
+
}
|
|
76
|
+
const causes = new Set([...byCause.keys(), ...withoutCause.keys(), ...variantCause.keys()]);
|
|
77
|
+
const overall = causes.size === 1 ? [...causes][0] : 'either';
|
|
78
|
+
const parts = [];
|
|
79
|
+
for (const [c, ns] of byCause)
|
|
80
|
+
parts.push(`${names(ns, 10)} ${ns.length === 1 ? 'is' : 'are'} listed only to a client that ${CAN[c]}`);
|
|
81
|
+
for (const [c, ns] of withoutCause)
|
|
82
|
+
parts.push(`${names(ns, 10)} ${ns.length === 1 ? 'is' : 'are'} listed only to a client that ${CANNOT[c]}`);
|
|
83
|
+
for (const [c, ns] of variantCause)
|
|
84
|
+
parts.push(`${names(ns, 10)} ${ns.length === 1 ? 'is' : 'are'} listed with another definition to a client that ${CAN[c]}`);
|
|
85
|
+
const one = only.length + without.length + variants.length === 1;
|
|
86
|
+
const sentence = parts.join('; ');
|
|
87
|
+
const seen = only.length + variants.length;
|
|
88
|
+
const tail = seen > 0
|
|
89
|
+
? `The menu file holds the menu of a client with both, so diff sees ${seen === 1 ? 'that tool' : 'those tools'} as such a client gets ${seen === 1 ? 'it' : 'them'}.`
|
|
90
|
+
: `The menu file holds the menu of a client with both, which doesn't have ${without.length === 1 ? 'it' : 'them'}, so diff doesn't see changes to ${without.length === 1 ? 'it' : 'them'}.`;
|
|
91
|
+
return [
|
|
92
|
+
{
|
|
93
|
+
rule: 'menu/capability-dependent',
|
|
94
|
+
severity: 'info',
|
|
95
|
+
...(one ? { tool: only[0] ?? without[0] ?? variants[0] } : {}),
|
|
96
|
+
message: `${sentence}. ${WITHOUT[overall]} gets ${plain.length} ${plain.length === 1 ? 'tool' : 'tools'}${variants.length ? `, ${variants.length === 1 ? 'one' : 'some'} of them different` : ''}, not ${ctx.menu.tools.length}. ${tail}`,
|
|
97
|
+
fix: overall === 'apps'
|
|
98
|
+
? 'Nothing to change if this is deliberate (a UI variant for Apps hosts). Keep a text-only variant that works without the UI, and say in the README which tools need an Apps host.'
|
|
99
|
+
: 'Nothing to change if this is deliberate (a destructive tool that asks the user first, a UI variant for Apps hosts). Say in the README which tools need which client capability, so users of other clients know why they are missing.',
|
|
100
|
+
},
|
|
101
|
+
];
|
|
102
|
+
},
|
|
103
|
+
};
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
import { type Rule } from './rule.js';
|
|
2
|
+
/**
|
|
3
|
+
* The Server Card at `<url>/server-card`, against the live connection. A server without
|
|
4
|
+
* one is fine (cards are optional) and nothing is said. Name isn't compared: cards use
|
|
5
|
+
* registry names (io.github.upstash/context7), serverInfo a display name (Context7).
|
|
6
|
+
*/
|
|
7
|
+
export declare const serverCard: Rule;
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
import { CARD_MEDIA_TYPE } from '../card.js';
|
|
2
|
+
import { resultValidator } from './spec.js';
|
|
3
|
+
import { clip } from './rule.js';
|
|
4
|
+
const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
|
|
5
|
+
const trim = (u) => u.replace(/\/+$/, '');
|
|
6
|
+
/**
|
|
7
|
+
* The Server Card at `<url>/server-card`, against the live connection. A server without
|
|
8
|
+
* one is fine (cards are optional) and nothing is said. Name isn't compared: cards use
|
|
9
|
+
* registry names (io.github.upstash/context7), serverInfo a display name (Context7).
|
|
10
|
+
*/
|
|
11
|
+
export const serverCard = {
|
|
12
|
+
id: 'spec/server-card',
|
|
13
|
+
severity: 'warn',
|
|
14
|
+
summary: "The Server Card agrees with the live server: schema, version, protocol versions",
|
|
15
|
+
run(ctx) {
|
|
16
|
+
const read = ctx.serverCard;
|
|
17
|
+
if (!read || !isObject(read.card))
|
|
18
|
+
return [];
|
|
19
|
+
const card = read.card;
|
|
20
|
+
// Only a card says it is one: its media type, or the Server Card schema in $schema.
|
|
21
|
+
// A server that answers every path with JSON (an error object, a health check) has none.
|
|
22
|
+
const typed = !!read.contentType?.toLowerCase().startsWith(CARD_MEDIA_TYPE);
|
|
23
|
+
if (!typed && !(typeof card.$schema === 'string' && /server-card/i.test(card.$schema)))
|
|
24
|
+
return [];
|
|
25
|
+
const where = read.url;
|
|
26
|
+
const out = [];
|
|
27
|
+
const validate = resultValidator('server-card', 'ServerCard');
|
|
28
|
+
if (validate && !validate(card)) {
|
|
29
|
+
const errors = (validate.errors ?? []).slice(0, 5).map((e) => `${e.instancePath || '(the card)'} ${e.message ?? ''}`.trim());
|
|
30
|
+
out.push({
|
|
31
|
+
message: `The Server Card at ${where} doesn't match the Server Card schema, so clients that read cards before connecting may skip it or misread it: ${errors[0]}.`,
|
|
32
|
+
...(errors.length > 1 ? { detail: errors } : {}),
|
|
33
|
+
fix: 'Fix the card against schema.json in modelcontextprotocol/ext-server-card.',
|
|
34
|
+
});
|
|
35
|
+
}
|
|
36
|
+
const contradictions = [];
|
|
37
|
+
const live = ctx.serverInfo?.version;
|
|
38
|
+
if (typeof card.version === 'string' && live && card.version !== live)
|
|
39
|
+
contradictions.push(`version: the card says ${clip(card.version, 60)}, the server ${clip(live, 60)}`);
|
|
40
|
+
// The remote for the URL this run connected to; its protocol versions against the one negotiated.
|
|
41
|
+
const remotes = Array.isArray(card.remotes) ? card.remotes.filter(isObject) : [];
|
|
42
|
+
const mine = ctx.serverUrl ? remotes.find((r) => typeof r.url === 'string' && trim(r.url) === trim(ctx.serverUrl)) : undefined;
|
|
43
|
+
const versions = Array.isArray(mine?.supportedProtocolVersions) ? mine.supportedProtocolVersions.filter((v) => typeof v === 'string') : undefined;
|
|
44
|
+
// Not when this connection fell back to 2025 and a later one got 2026-07-28: the
|
|
45
|
+
// negotiated version then isn't all the server speaks (spec/discover says why).
|
|
46
|
+
if (versions?.length && ctx.protocolVersion && !ctx.laterModern && !versions.includes(ctx.protocolVersion)) {
|
|
47
|
+
contradictions.push(`protocol: the card lists ${versions.join(', ')} for ${mine.url}, the server negotiated ${ctx.protocolVersion}`);
|
|
48
|
+
}
|
|
49
|
+
if (contradictions.length) {
|
|
50
|
+
out.push({
|
|
51
|
+
message: `The Server Card at ${where} contradicts the live server (${contradictions.join('; ')}). Clients read the card before connecting, so they pick or configure the server by values it doesn't have; ext-server-card says the card SHOULD NOT contradict server/discover and serverInfo.`,
|
|
52
|
+
...(contradictions.length > 1 ? { detail: contradictions } : {}),
|
|
53
|
+
fix: 'Build the card from the same values the server reports (its package version, the protocol versions the SDK serves), or update it with each release.',
|
|
54
|
+
});
|
|
55
|
+
}
|
|
56
|
+
if (!typed) {
|
|
57
|
+
out.push({
|
|
58
|
+
severity: 'info',
|
|
59
|
+
message: `The Server Card at ${where} is served as ${read.contentType ? clip(read.contentType, 60) : 'no content type'}, not ${CARD_MEDIA_TYPE}, which ext-server-card says servers SHOULD use.`,
|
|
60
|
+
fix: `Serve it with Content-Type: ${CARD_MEDIA_TYPE}.`,
|
|
61
|
+
});
|
|
62
|
+
}
|
|
63
|
+
return out;
|
|
64
|
+
},
|
|
65
|
+
};
|
package/dist/rules/clients.js
CHANGED
|
@@ -111,6 +111,7 @@ export function sentInFull(tool, patterns) {
|
|
|
111
111
|
}
|
|
112
112
|
export const buried = {
|
|
113
113
|
id: 'description/buried',
|
|
114
|
+
scope: 'agent',
|
|
114
115
|
severity: 'warn',
|
|
115
116
|
lesson: 'truncated description',
|
|
116
117
|
summary: 'Instructions to the agent sit past the point where your client cuts descriptions',
|
|
@@ -153,6 +154,7 @@ function aroundTheCut(text, at) {
|
|
|
153
154
|
}
|
|
154
155
|
export const cut = {
|
|
155
156
|
id: 'description/cut',
|
|
157
|
+
scope: 'agent',
|
|
156
158
|
severity: 'info',
|
|
157
159
|
lesson: 'truncated description',
|
|
158
160
|
summary: 'Descriptions longer than your client sends',
|
|
@@ -187,6 +189,7 @@ export const cut = {
|
|
|
187
189
|
};
|
|
188
190
|
export const lateInstruction = {
|
|
189
191
|
id: 'description/late-instruction',
|
|
192
|
+
scope: 'agent',
|
|
190
193
|
severity: 'info',
|
|
191
194
|
lesson: 'truncated description',
|
|
192
195
|
summary: 'Instructions to the agent that a client cutting descriptions short would hide',
|
package/dist/rules/handles.d.ts
CHANGED
|
@@ -4,7 +4,20 @@ import { type Rule } from './rule.js';
|
|
|
4
4
|
export interface HandleProbe {
|
|
5
5
|
param: string;
|
|
6
6
|
kind: string;
|
|
7
|
+
/**
|
|
8
|
+
* --create-handles: a creating tool runs first, and this call gets the handle it
|
|
9
|
+
* returned instead of a made-up one (the made-up one when it returned none).
|
|
10
|
+
*/
|
|
11
|
+
fromCreated?: string;
|
|
7
12
|
}
|
|
13
|
+
/** Kinds --create-handles may create: scratch state that expires. Not a lock, lease or checkout. */
|
|
14
|
+
export declare const CREATABLE_KINDS: Set<string>;
|
|
15
|
+
/** The tool that creates handles of this kind, if the menu has one. */
|
|
16
|
+
export declare function creatorOf(tools: MenuTool[], kind: string): MenuTool | undefined;
|
|
17
|
+
export declare function handleFromResult(result: {
|
|
18
|
+
structuredContent?: unknown;
|
|
19
|
+
content?: unknown;
|
|
20
|
+
}, kind: string): string | undefined;
|
|
8
21
|
/** The handle kinds some tool in the menu creates. */
|
|
9
22
|
export declare function createdKinds(tools: MenuTool[]): Set<string>;
|
|
10
23
|
/** Parameters of a tool that take a handle of this kind: session_id, cartToken, `session`. */
|
package/dist/rules/handles.js
CHANGED
|
@@ -30,6 +30,84 @@ function createdKind(tool) {
|
|
|
30
30
|
return undefined;
|
|
31
31
|
return w.slice(1).find((x) => HANDLE_KINDS.has(x));
|
|
32
32
|
}
|
|
33
|
+
/** Kinds --create-handles may create: scratch state that expires. Not a lock, lease or checkout. */
|
|
34
|
+
export const CREATABLE_KINDS = new Set(['session', 'basket', 'cart']);
|
|
35
|
+
/** The tool that creates handles of this kind, if the menu has one. */
|
|
36
|
+
export function creatorOf(tools, kind) {
|
|
37
|
+
return tools.find((t) => createdKind(t) === kind);
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* The handle a creating tool's result carries: a `<kind>_id` / `<kind>Id` / `id` in its
|
|
41
|
+
* structured content, in JSON text, or written out ("session_id: s-1").
|
|
42
|
+
*/
|
|
43
|
+
const WRAPPERS = new Set(['data', 'result', 'results', 'item', 'response']);
|
|
44
|
+
export function handleFromResult(result, kind) {
|
|
45
|
+
// Compared without case, dashes or underscores: session_id, sessionId and session-id are one key.
|
|
46
|
+
const norm = (k) => k.toLowerCase().replace(/[-_\s]/g, '');
|
|
47
|
+
const own = new Set([`${kind}id`, kind, `${kind}handle`, `${kind}token`]);
|
|
48
|
+
const scalar = (x) => (typeof x === 'string' && x ? x : typeof x === 'number' ? String(x) : undefined);
|
|
49
|
+
// The kind's own key anywhere (breadth first, so the shallowest wins); a bare id or
|
|
50
|
+
// handle only at the top, where it names what was created, not a nested user or request.
|
|
51
|
+
const find = (root) => {
|
|
52
|
+
let level = [root];
|
|
53
|
+
for (let depth = 0; depth <= 3 && level.length; depth++) {
|
|
54
|
+
const next = [];
|
|
55
|
+
for (const v of level) {
|
|
56
|
+
if (!v || typeof v !== 'object')
|
|
57
|
+
continue;
|
|
58
|
+
for (const [k, x] of Object.entries(v)) {
|
|
59
|
+
const found = own.has(norm(k)) ? scalar(x) : undefined;
|
|
60
|
+
if (found)
|
|
61
|
+
return found;
|
|
62
|
+
if (x && typeof x === 'object')
|
|
63
|
+
next.push(x);
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
level = next;
|
|
67
|
+
}
|
|
68
|
+
// At the top, or right under a wrapper ({"data":{"id":…}}), never under another thing's key (user.id).
|
|
69
|
+
const bare = (v, inWrapper = false) => {
|
|
70
|
+
// Under a wrapper, a one-item list is the item ({"data":[{"id":…}]}); a longer one, or
|
|
71
|
+
// a list at the top, names no single handle.
|
|
72
|
+
const one = Array.isArray(v) ? (inWrapper && v.length === 1 ? v[0] : undefined) : v;
|
|
73
|
+
if (!one || typeof one !== 'object' || Array.isArray(one))
|
|
74
|
+
return undefined;
|
|
75
|
+
for (const [k, x] of Object.entries(one)) {
|
|
76
|
+
const found = norm(k) === 'id' || norm(k) === 'handle' ? scalar(x) : undefined;
|
|
77
|
+
if (found)
|
|
78
|
+
return found;
|
|
79
|
+
}
|
|
80
|
+
return undefined;
|
|
81
|
+
};
|
|
82
|
+
const top = bare(root);
|
|
83
|
+
if (top || !root || typeof root !== 'object' || Array.isArray(root))
|
|
84
|
+
return top;
|
|
85
|
+
for (const [k, x] of Object.entries(root)) {
|
|
86
|
+
const found = WRAPPERS.has(norm(k)) || norm(k) === kind ? bare(x, true) : undefined;
|
|
87
|
+
if (found)
|
|
88
|
+
return found;
|
|
89
|
+
}
|
|
90
|
+
return undefined;
|
|
91
|
+
};
|
|
92
|
+
const structured = find(result.structuredContent);
|
|
93
|
+
if (structured)
|
|
94
|
+
return structured;
|
|
95
|
+
const texts = Array.isArray(result.content) ? result.content.filter((c) => c.type === 'text' && c.text).map((c) => c.text) : [];
|
|
96
|
+
for (const t of texts) {
|
|
97
|
+
try {
|
|
98
|
+
const r = find(JSON.parse(t));
|
|
99
|
+
if (r)
|
|
100
|
+
return r;
|
|
101
|
+
}
|
|
102
|
+
catch {
|
|
103
|
+
// not JSON: look for "session_id: s-1" written out
|
|
104
|
+
}
|
|
105
|
+
const m = new RegExp(`\\b${kind}[_ -]?(?:id|handle|token)\\b["']?\\s*[:=]\\s*["']?([\\w.:-]+)`, 'i').exec(t);
|
|
106
|
+
if (m)
|
|
107
|
+
return m[1];
|
|
108
|
+
}
|
|
109
|
+
return undefined;
|
|
110
|
+
}
|
|
33
111
|
/** The handle kinds some tool in the menu creates. */
|
|
34
112
|
export function createdKinds(tools) {
|
|
35
113
|
return new Set(tools.map(createdKind).filter((k) => !!k));
|
package/dist/rules/ids.js
CHANGED
|
@@ -61,6 +61,9 @@ export function idParams(tool) {
|
|
|
61
61
|
// A qualifier alone (`parentId`, `targetId`) says how it relates, not what it is.
|
|
62
62
|
if (kindWords.length === 1 && QUALIFIERS.has(kindWords[0]))
|
|
63
63
|
kindWords.length = 0;
|
|
64
|
+
// A GraphQL node ID is the thing's own ID: commentNodeID is a comment's (GitHub).
|
|
65
|
+
if (kindWords.length > 1 && kindWords.at(-1) === 'node')
|
|
66
|
+
kindWords.pop();
|
|
64
67
|
const prefix = kindWords.join('_');
|
|
65
68
|
// A bare `id` doesn't say what it identifies (naming/vague-id covers that), so no kind is guessed.
|
|
66
69
|
params.push({ param, kind: prefix || undefined });
|
|
@@ -73,6 +76,30 @@ function looksLikeIdValue(schema) {
|
|
|
73
76
|
const type = schema.type;
|
|
74
77
|
return type === undefined || type === 'string' || type === 'integer' || (Array.isArray(type) && type.includes('string'));
|
|
75
78
|
}
|
|
79
|
+
/**
|
|
80
|
+
* A tool's operations, when an enum lists them under their own names: a router such as
|
|
81
|
+
* github-mcp-server's actions_list { method: list_workflows | list_workflow_runs } lists
|
|
82
|
+
* workflows as surely as a list_workflows tool would. Each value that reads as a list
|
|
83
|
+
* or search (list_project_views) counts as a tool of that name, with the router's parameters.
|
|
84
|
+
*/
|
|
85
|
+
/** Marks a tool made from an enum value: it counts only when its name says the kind. */
|
|
86
|
+
const OPERATION = Symbol('operation');
|
|
87
|
+
function withOperations(tools) {
|
|
88
|
+
const out = [...tools];
|
|
89
|
+
for (const t of tools) {
|
|
90
|
+
for (const schema of Object.values(t.inputSchema?.properties ?? {})) {
|
|
91
|
+
for (const v of Array.isArray(schema.enum) ? schema.enum : []) {
|
|
92
|
+
if (typeof v !== 'string' || !/^[a-z]+(?:_[a-z]+)+$/.test(v))
|
|
93
|
+
continue;
|
|
94
|
+
// Lists and searches only: a router's get_workflow needs the ID it would hand out.
|
|
95
|
+
if (!COLLECTION_VERBS.has(singular(v.split('_')[0])))
|
|
96
|
+
continue;
|
|
97
|
+
out.push({ ...t, name: v, outputSchema: undefined, [OPERATION]: true });
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
return out;
|
|
102
|
+
}
|
|
76
103
|
/** Does some other tool look like it hands out IDs of this kind? */
|
|
77
104
|
function isReturnedBySomeTool(kind, self, tools, common) {
|
|
78
105
|
return tools.some((other) => {
|
|
@@ -86,6 +113,11 @@ function isReturnedBySomeTool(kind, self, tools, common) {
|
|
|
86
113
|
const lookup = verbs.some((v) => LOOKUP_VERBS.has(v));
|
|
87
114
|
const collection = verbs.some((v) => COLLECTION_VERBS.has(v)) || w.includes('children');
|
|
88
115
|
const needsSameId = idParams(other).some((p) => p.kind === kind);
|
|
116
|
+
// An operation from an enum counts only when it names the kind (list_workflows):
|
|
117
|
+
// sapiens' action: list_public or list_mine says nothing about which IDs it lists.
|
|
118
|
+
// And after its verb: list_public lists no "list" IDs.
|
|
119
|
+
if (other[OPERATION])
|
|
120
|
+
return lookup && `_${w.slice(1).join('_')}_`.includes(`_${kind}_`) && !needsSameId;
|
|
89
121
|
// A list or search for that kind; a get that doesn't itself need the ID.
|
|
90
122
|
if (lookup && mentionsKind && (collection || !needsSameId))
|
|
91
123
|
return true;
|
|
@@ -115,6 +147,7 @@ function outputMentions(schema, kind, depth = 0, parent = '') {
|
|
|
115
147
|
}
|
|
116
148
|
export const authoredIds = {
|
|
117
149
|
id: 'ids/authored',
|
|
150
|
+
scope: 'agent',
|
|
118
151
|
// A heuristic: IDs that only appear in another tool's text output look the same
|
|
119
152
|
// as invented ones from the schema alone (FINDINGS F12).
|
|
120
153
|
severity: 'info',
|
|
@@ -123,9 +156,10 @@ export const authoredIds = {
|
|
|
123
156
|
run(ctx) {
|
|
124
157
|
const byKind = new Map();
|
|
125
158
|
const common = commonWords(ctx.menu.tools.map((t) => t.name));
|
|
159
|
+
const operations = withOperations(ctx.menu.tools);
|
|
126
160
|
for (const tool of kept(ctx.menu.tools, ctx)) {
|
|
127
161
|
for (const { param, kind } of idParams(tool)) {
|
|
128
|
-
if (!kind || isReturnedBySomeTool(kind, tool,
|
|
162
|
+
if (!kind || isReturnedBySomeTool(kind, tool, operations, common))
|
|
129
163
|
continue;
|
|
130
164
|
const schema = tool.inputSchema?.properties?.[param];
|
|
131
165
|
if (saysWhereItComesFrom(schema, ctx.menu.tools, tool.name))
|