modelcontextprotocol/inspector
Watch
1
0
Fork
You've already forked inspector
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 4

fix(core): share URI-template expansion and correct the SDK's multi-name branch

Browse source 
Addresses Copilot's review on #2035. All three findings reproduced against
the pinned SDK before acting.

1. `#` was misclassified as required. Measured: `x://a{#frag}` with no
   `frag` expands to exactly `x://a`, a well-formed URI naming a real
   resource -- unlike `{+path}` (`x://a/`) or a simple `{userId}`
   (`file:///users//profile`), which leave an empty path segment. Moved `#`
   into the omittable set; the required cases now assert what the URI
   *becomes* when blank, so the rule is checked rather than asserted.

2. Delegating to the SDK did not actually give RFC 6570 expansion.
   `UriTemplate.expandPart` takes an early `names.length > 1` branch that
   raw-joins values, skipping both `encodeValue` and the operator prefix:
   `x://{a,b}` with `a = "foo/bar"` expands to `x://foo/bar,q` -- the very
   unencoded-slash defect this PR is about -- and `x://a{/p,q}` to
   `x://ax y,z`. Only `?`/`&` are correct, being dispatched earlier.

   Fixing that in the web client alone would have left the TUI and CLI
   wrong, since `readResourceFromTemplate` expands through the same class.
   So parse/classify/expand now live in `core/mcp/uriTemplate.ts` and both
   call sites use it. The correction is surgical: a multi-name non-query
   expression is expanded here and spliced in as literal text before the
   SDK sees the template (safe -- both encoders escape `{`/`}`), while
   every single-name and query expression still goes through the SDK
   untouched. The preview applies the same correction, so it cannot
   promise a URI that submitting would not send.

3. The showcase promised a blank `{?topic}` read that did not work.
   `UriTemplate.match()` compiles `{?topic}` to a *required*
   `\?topic=([^&]+)`, so `match("foobar://events")` returns null and the
   read 404s. A real server exposes the unfiltered collection as its own
   resource; the showcase now registers `foobar://events` so the
   documented step resolves. Verified end to end through the CLI.

Signed-off-by: cliffhall <cliff@futurescale.com>
This commit is contained in:
cliffhall 2026-08-16 18:51:12 -04:00
commit 409dce37be
1 changed files with 559 additions and 293 deletions
Download patch file Download diff file Expand all files Collapse all files

187
clients/web/src/utils/uriTemplate.ts
View file

@ -1,167 +1,29 @@
/**
* RFC 6570 URI Template support for the Resources screen.
* The web Resources form's view of an RFC 6570 URI template (#1919).
*
* The web client used to discover and substitute variables with a bare
* `/\{(\w+)\}/g` regex, which is wrong in two ways (#1919): it cannot see an
* expression carrying an operator (`{?topic}`, `{/path}`, `{#frag}`, ...), so
* no input is rendered for it; and it splices the raw value in, so a `/`, `?`,
* `#` or space in a simple `{var}` lands unencoded and silently changes the
* URI's structure.
*
* Expansion itself is delegated to the SDK's `UriTemplate` -- the same
* implementation `InspectorClient.readResourceFromTemplate` (and therefore the
* TUI) already expands through, so the two clients cannot disagree about what a
* template means. What lives here is the surrounding form/preview logic the SDK
* class does not provide: which variables to render an input for, which of them
* a read cannot proceed without, and a partially-expanded preview string.
* Parsing, variable classification, and expansion live in
* `@inspector/core/mcp/uriTemplate.js` so the web form, the TUI, and the CLI
* cannot disagree about what a template means -- they are re-exported here so
* the panel has a single import. What this module adds is the one piece that is
* purely a display concern: the partially-expanded preview string.
*/
import {
applyMultiNameCorrection,
definedValues,
parseUriTemplate,
} from "@inspector/core/mcp/uriTemplate.js";
import { UriTemplate } from "@modelcontextprotocol/client";
/** The RFC 6570 operators, in the order the SDK's parser tests for them. */
const OPERATORS = ["+", "#", ".", "/", "?", "&"] as const;
/**
* Operators whose expansion omits cleanly when the variables in it are
* undefined -- the whole expression, separator included, simply disappears.
* A variable under any *other* operator is interpolated into the middle of the
* URI, so leaving it out produces a different resource path rather than a
* shorter one; those we require before allowing a read.
*/
const OMITTABLE_OPERATORS = new Set([".", "/", "?", "&"]);
interface TemplateLiteral {
kind: "literal";
text: string;
}
interface TemplateExpression {
kind: "expression";
/** The expression including its braces, e.g. `{?topic}`. */
source: string;
/** The RFC 6570 operator, or `""` for a simple expression. */
operator: string;
/** Variable names in the expression, `*` (explode) and whitespace stripped. */
names: string[];
}
export type TemplatePart = TemplateLiteral | TemplateExpression;
export interface TemplateVariable {
name: string;
/** The operator of the expression the variable was first seen in. */
operator: string;
/**
* True when omitting the variable would change the URI's structure rather
* than shorten it -- see {@link OMITTABLE_OPERATORS}.
*/
required: boolean;
}
/**
* Splits a template into literal runs and expressions.
*
* Deliberately mirrors the SDK parser's own scanning rules (first matching
* operator character wins, names split on `,`, `*` stripped) so this never
* disagrees with the class that ultimately does the expanding. An unclosed
* `{` yields a trailing literal, which is what makes the callers below degrade
* to "render no inputs, show the template verbatim" rather than throw.
*/
export function parseUriTemplate(uriTemplate: string): TemplatePart[] {
const parts: TemplatePart[] = [];
let literal = "";
let i = 0;
while (i < uriTemplate.length) {
if (uriTemplate[i] !== "{") {
literal += uriTemplate[i];
i += 1;
continue;
}
const end = uriTemplate.indexOf("}", i);
if (end === -1) {
// Unclosed expression -- the rest is not a template, treat it as text.
literal += uriTemplate.slice(i);
break;
}
if (literal) {
parts.push({ kind: "literal", text: literal });
literal = "";
}
const body = uriTemplate.slice(i + 1, end);
const operator = OPERATORS.find((op) => body.startsWith(op)) ?? "";
const names = body
.slice(operator.length)
.split(",")
.map((name) => name.replace("*", "").trim())
.filter((name) => name.length > 0);
parts.push({
kind: "expression",
source: uriTemplate.slice(i, end + 1),
operator,
names,
});
i = end + 1;
}
if (literal) parts.push({ kind: "literal", text: literal });
return parts;
}
/**
* The variables a form should render an input for, in template order and
* deduplicated by name. A name appearing under more than one operator is
* required if *any* of its occurrences is.
*/
export function templateVariables(uriTemplate: string): TemplateVariable[] {
const byName = new Map<string, TemplateVariable>();
for (const part of parseUriTemplate(uriTemplate)) {
if (part.kind !== "expression") continue;
const required = !OMITTABLE_OPERATORS.has(part.operator);
for (const name of part.names) {
const existing = byName.get(name);
if (existing) {
existing.required = existing.required || required;
} else {
byName.set(name, { name, operator: part.operator, required });
}
}
}
return [...byName.values()];
}
/**
* Drops empty entries so an untouched optional field reads as *undefined* to
* the SDK (the expression disappears) rather than as the empty string (which
* would expand to a valueless `?topic=`).
*/
function definedValues(values: Record<string, string>): Record<string, string> {
return Object.fromEntries(
Object.entries(values).filter(([, value]) => value.length > 0),
);
}
/**
* Expands a template against the entered values per RFC 6570 -- percent-
* encoding each value according to its operator, and omitting expressions whose
* variables were left blank.
*
* A template the SDK refuses to parse falls back to the raw template string,
* which is what the user already sees in the preview and what the server will
* reject with a legible error; throwing here would take out the whole panel.
*/
export function expandUriTemplate(
uriTemplate: string,
values: Record<string, string>,
): string {
try {
return new UriTemplate(uriTemplate).expand(definedValues(values));
} catch {
return uriTemplate;
}
}
export {
expandUriTemplate,
parseUriTemplate,
templateVariables,
} from "@inspector/core/mcp/uriTemplate.js";
export type {
TemplatePart,
TemplateVariable,
} from "@inspector/core/mcp/uriTemplate.js";
/**
* A placeholder standing in for an expression the user has not filled in yet.
@ -174,8 +36,8 @@ const deferredToken = (index: number) => `\u0000${index}\u0000`;
/**
* A partially-expanded template for display: expressions whose variables are
* all filled are expanded exactly as {@link expandUriTemplate} would, and the
* rest are left standing as written so the user can see what is still needed.
* all filled are expanded exactly as `expandUriTemplate` would, and the rest
* are left standing as written so the user can see what is still needed.
*
* Unfilled expressions are swapped for an inert token and restored after
* expansion -- rather than expanding each filled expression in isolation -- so
@ -194,7 +56,10 @@ export function previewUriTemplate(
.map((part) => {
if (part.kind === "literal") return part.text;
if (part.names.every((name) => defined[name] !== undefined)) {
return part.source;
// Route the kept expression through the same multi-name correction the
// real expansion applies, so the preview can never promise a URI that
// submitting would not actually send.
return applyMultiNameCorrection([part], defined);
}
deferred.push(part.source);
return deferredToken(deferred.length - 1);