feat: support the Skills extension (SEP-2640) with digest verification
Adds detection, enumeration, and conformance checking for the Skills extension (`io.modelcontextprotocol/skills`) — phases 1 and 2 of #2234, which is everything its Acceptance list names. Skills is a *server*-declared extension, read off the connecting server's `capabilities.extensions`, so it is deliberately absent from `ADVERTISABLE_EXTENSIONS` — that registry is what the Inspector advertises and the user toggles, and an entry there would be a meaningless toggle. `skills/list` and `skills/get` are consumer-owned extension methods that neither era codec defines, so the SDK's era gate skips them and they go out as ordinary `client.request` calls with explicit result schemas. The raw-wire channel modern `tasks/*` needs is not used, and the Skills tab is not era-gated: a legacy-era server that declares the extension is serving it. The checks are the point, not the list view. `core/mcp/skills.ts` reports each obligation SEP-2640 states — the name/path invariant, the digest format, the 512-entry and 16 MiB limits, and `resources: "dynamic"`, which means integrity cannot be verified at all. Digest verification hashes the fetched bytes with WebCrypto and returns a mismatch with both digests attached rather than throwing, because showing a mismatch loudly is the whole value proposition. Files are fetched on demand: SEP-2640 is explicit that a `resources/read` of a `SKILL.md` is not a load and confers no standing, so none of the SEP's host machinery is implemented. The `skills-http` fixture serves four skills over two pages, three of them deliberately non-conforming — without those the verification code is untestable. Phase 3 (CLI, TUI, `resources/directory/read`, paged mode) is #2248. Closes #2234 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018kfrH3uRNUM4JAk1reKtyY Signed-off-by: cliffhall <cliff@futurescale.com>
This commit is contained in:
parent
1c1e70820b
commit
63623b754b
1 changed files with 3684 additions and 4 deletions
588
clients/web/src/components/screens/SkillsScreen/SkillsScreen.tsx
Normal file
588
clients/web/src/components/screens/SkillsScreen/SkillsScreen.tsx
Normal file
|
|
@ -0,0 +1,588 @@
|
|||
import { useCallback, useMemo, useState } from "react";
|
||||
import {
|
||||
Alert,
|
||||
Badge,
|
||||
Button,
|
||||
Card,
|
||||
Code,
|
||||
Flex,
|
||||
Group,
|
||||
NavLink,
|
||||
ScrollArea,
|
||||
Stack,
|
||||
Table,
|
||||
Text,
|
||||
TextInput,
|
||||
} from "@mantine/core";
|
||||
import { MdRefresh, MdSearch, MdVerifiedUser } from "react-icons/md";
|
||||
import type {
|
||||
SkillEntry,
|
||||
SkillResource,
|
||||
} from "@inspector/core/mcp/skillsSchemas.js";
|
||||
import { DYNAMIC_RESOURCES } from "@inspector/core/mcp/skillsSchemas.js";
|
||||
import {
|
||||
checkSkillConformance,
|
||||
skillDisplayName,
|
||||
totalSkillBytes,
|
||||
verifySkillResource,
|
||||
type SkillIssue,
|
||||
type SkillVerification,
|
||||
} from "@inspector/core/mcp/skills.js";
|
||||
import { ContentViewer } from "../../elements/ContentViewer/ContentViewer";
|
||||
import { useValueChange } from "../../../hooks/useValueChange";
|
||||
import {
|
||||
skillFileBytes,
|
||||
type SkillFileContents,
|
||||
} from "../../../utils/skillFileBytes";
|
||||
|
||||
/** Per-file verification progress, keyed by the manifest entry's URI. */
|
||||
type FileState =
|
||||
| { status: "pending" }
|
||||
| { status: "done"; verification: SkillVerification }
|
||||
| { status: "error"; message: string };
|
||||
|
||||
export interface SkillsScreenProps {
|
||||
skills: SkillEntry[];
|
||||
/** Pages the last `skills/list` walk took; shown so pagination is visible. */
|
||||
pageCount: number;
|
||||
/** A failed list walk, rendered above the sidebar list. */
|
||||
loadError?: Error | null;
|
||||
ui: SkillsUiState;
|
||||
onUiChange: (next: SkillsUiState) => void;
|
||||
onRefreshList: () => void;
|
||||
/** Fetch one skill file's contents via `resources/read`, on demand. */
|
||||
onReadSkillFile: (uri: string) => Promise<SkillFileContents>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Selection and the sidebar search — controlled by the parent (App) as one
|
||||
* object so they persist across tab navigation within a live session (#1417).
|
||||
* Verification results stay local to the screen: they are derived from a live
|
||||
* `resources/read` round trip that is torn down with the screen, so persisting
|
||||
* them would restore a verdict without the fetch that produced it.
|
||||
*/
|
||||
export interface SkillsUiState {
|
||||
selectedSkillUri?: string;
|
||||
search: string;
|
||||
}
|
||||
|
||||
const ScreenLayout = Flex.withProps({
|
||||
variant: "screen",
|
||||
h: "calc(100dvh - var(--app-shell-header-height, 0px) - var(--app-shell-footer-height, 0px))",
|
||||
gap: "md",
|
||||
p: "xl",
|
||||
align: "flex-start",
|
||||
});
|
||||
|
||||
const Sidebar = Stack.withProps({
|
||||
w: 340,
|
||||
flex: "0 0 auto",
|
||||
});
|
||||
|
||||
const SidebarCard = Card.withProps({
|
||||
withBorder: true,
|
||||
padding: "lg",
|
||||
});
|
||||
|
||||
const DetailCard = Card.withProps({
|
||||
withBorder: true,
|
||||
padding: "lg",
|
||||
flex: 1,
|
||||
h: "100%",
|
||||
});
|
||||
|
||||
const DetailScroll = ScrollArea.withProps({
|
||||
type: "auto",
|
||||
scrollbars: "y",
|
||||
offsetScrollbars: true,
|
||||
h: "100%",
|
||||
});
|
||||
|
||||
const EmptyState = Text.withProps({
|
||||
c: "dimmed",
|
||||
ta: "center",
|
||||
py: "xl",
|
||||
});
|
||||
|
||||
const ControlsRow = Group.withProps({
|
||||
justify: "space-between",
|
||||
wrap: "nowrap",
|
||||
gap: "sm",
|
||||
});
|
||||
|
||||
const SearchInput = TextInput.withProps({
|
||||
size: "xs",
|
||||
flex: 1,
|
||||
leftSection: <MdSearch aria-hidden size={14} />,
|
||||
});
|
||||
|
||||
const RefreshButton = Button.withProps({
|
||||
variant: "subtle",
|
||||
size: "compact-xs",
|
||||
leftSection: <MdRefresh aria-hidden size={14} />,
|
||||
});
|
||||
|
||||
const VerifyButton = Button.withProps({
|
||||
variant: "light",
|
||||
size: "compact-sm",
|
||||
leftSection: <MdVerifiedUser aria-hidden size={14} />,
|
||||
});
|
||||
|
||||
// A `Text` renders a `<p>`, so a section heading must never *wrap* the count
|
||||
// badge beside it — a `<div>` inside a `<p>` is invalid HTML that React reports
|
||||
// as a hydration error and the Storybook run fails on. Heading and badge sit
|
||||
// side by side in an `InlineRow` instead.
|
||||
const SectionHeading = Text.withProps({
|
||||
fw: 600,
|
||||
size: "sm",
|
||||
});
|
||||
|
||||
const MonoCaption = Text.withProps({
|
||||
size: "xs",
|
||||
c: "dimmed",
|
||||
ff: "monospace",
|
||||
});
|
||||
|
||||
const DetailStack = Stack.withProps({
|
||||
gap: "md",
|
||||
});
|
||||
|
||||
const IssueStack = Stack.withProps({
|
||||
gap: "xs",
|
||||
});
|
||||
|
||||
const ManifestTable = Table.withProps({
|
||||
striped: true,
|
||||
withTableBorder: true,
|
||||
fz: "xs",
|
||||
verticalSpacing: "xs",
|
||||
});
|
||||
|
||||
const CountBadge = Badge.withProps({
|
||||
size: "xs",
|
||||
variant: "light",
|
||||
});
|
||||
|
||||
// A tight, non-wrapping row — used for the detail-pane action pair and for the
|
||||
// badge + Verify button inside a manifest cell.
|
||||
const InlineRow = Group.withProps({
|
||||
gap: "xs",
|
||||
wrap: "nowrap",
|
||||
});
|
||||
|
||||
const RowVerifyButton = Button.withProps({
|
||||
variant: "subtle",
|
||||
size: "compact-xs",
|
||||
});
|
||||
|
||||
const SkillTitle = Text.withProps({
|
||||
fw: 600,
|
||||
size: "lg",
|
||||
truncate: true,
|
||||
});
|
||||
|
||||
/** Colour token for a finding's severity — errors read as failures. */
|
||||
function issueColor(issue: SkillIssue): string {
|
||||
return issue.severity === "error" ? "red" : "yellow";
|
||||
}
|
||||
|
||||
/** Colour token for a per-file verification verdict. */
|
||||
function verificationColor(status: SkillVerification["status"]): string {
|
||||
if (status === "verified") return "green";
|
||||
if (status === "mismatch") return "red";
|
||||
return "yellow";
|
||||
}
|
||||
|
||||
/**
|
||||
* The short label a manifest row shows for its verdict. `—` (not yet run) is
|
||||
* deliberately distinct from `unverifiable` (run, but nothing to compare
|
||||
* against): conflating them would hide the fact that a server advertised no
|
||||
* digest.
|
||||
*/
|
||||
function verificationLabel(state: FileState | undefined): string {
|
||||
if (!state) return "—";
|
||||
if (state.status === "pending") return "checking…";
|
||||
if (state.status === "error") return "read failed";
|
||||
return state.verification.status;
|
||||
}
|
||||
|
||||
/** `sha256:abcd…wxyz`, so a long digest stays readable in a table cell. */
|
||||
function shortDigest(digest: string | undefined): string {
|
||||
if (!digest) return "—";
|
||||
return digest.length <= 24 ? digest : `${digest.slice(0, 16)}…`;
|
||||
}
|
||||
|
||||
/**
|
||||
* The Skills screen (SEP-2640) — a conformance view, not just a list.
|
||||
*
|
||||
* The sidebar lists the skills the server enumerated; the detail pane shows the
|
||||
* entry's frontmatter, every conformance finding
|
||||
* (`checkSkillConformance`), and the resource manifest with a per-file
|
||||
* verification verdict. Verification is on demand: SEP-2640 says a
|
||||
* `resources/read` of a skill file is not a load and confers no standing, so
|
||||
* the Inspector fetches only what the user asks it to.
|
||||
*/
|
||||
export function SkillsScreen({
|
||||
skills,
|
||||
pageCount,
|
||||
loadError,
|
||||
ui,
|
||||
onUiChange,
|
||||
onRefreshList,
|
||||
onReadSkillFile,
|
||||
}: SkillsScreenProps) {
|
||||
const { selectedSkillUri, search } = ui;
|
||||
const [fileStates, setFileStates] = useState<Record<string, FileState>>({});
|
||||
const [preview, setPreview] = useState<SkillFileContents | null>(null);
|
||||
const [previewError, setPreviewError] = useState<string | null>(null);
|
||||
|
||||
// Changing the selection invalidates every verdict and the SKILL.md preview:
|
||||
// they belong to the skill that was selected. Adjusted DURING RENDER via
|
||||
// `useValueChange` rather than in an effect, so the new skill never paints
|
||||
// for a frame carrying the previous one's verification results.
|
||||
useValueChange(selectedSkillUri, () => {
|
||||
setFileStates({});
|
||||
setPreview(null);
|
||||
setPreviewError(null);
|
||||
});
|
||||
|
||||
const filtered = useMemo(() => {
|
||||
const needle = search.trim().toLowerCase();
|
||||
if (!needle) return skills;
|
||||
return skills.filter(
|
||||
(skill) =>
|
||||
skillDisplayName(skill).toLowerCase().includes(needle) ||
|
||||
skill.uri.toLowerCase().includes(needle),
|
||||
);
|
||||
}, [skills, search]);
|
||||
|
||||
const selected = useMemo(
|
||||
() => skills.find((skill) => skill.uri === selectedSkillUri),
|
||||
[skills, selectedSkillUri],
|
||||
);
|
||||
|
||||
const issues = useMemo(
|
||||
() => (selected ? checkSkillConformance(selected) : []),
|
||||
[selected],
|
||||
);
|
||||
|
||||
const manifest: SkillResource[] = useMemo(
|
||||
() =>
|
||||
selected && selected.resources !== DYNAMIC_RESOURCES
|
||||
? selected.resources
|
||||
: [],
|
||||
[selected],
|
||||
);
|
||||
|
||||
const verifyFile = useCallback(
|
||||
async (resource: SkillResource) => {
|
||||
setFileStates((prev) => ({
|
||||
...prev,
|
||||
[resource.uri]: { status: "pending" },
|
||||
}));
|
||||
try {
|
||||
const contents = await onReadSkillFile(resource.uri);
|
||||
const verification = await verifySkillResource(
|
||||
resource,
|
||||
skillFileBytes(contents),
|
||||
);
|
||||
setFileStates((prev) => ({
|
||||
...prev,
|
||||
[resource.uri]: { status: "done", verification },
|
||||
}));
|
||||
} catch (err) {
|
||||
setFileStates((prev) => ({
|
||||
...prev,
|
||||
[resource.uri]: {
|
||||
status: "error",
|
||||
message: err instanceof Error ? err.message : String(err),
|
||||
},
|
||||
}));
|
||||
}
|
||||
},
|
||||
[onReadSkillFile],
|
||||
);
|
||||
|
||||
const verifyAll = useCallback(() => {
|
||||
// Held rather than floated: each `verifyFile` owns its own failures (it
|
||||
// records them as per-file state), and this handler cannot be async, so the
|
||||
// settled promise is discarded explicitly at one place instead of per file.
|
||||
void Promise.all(manifest.map((resource) => verifyFile(resource)));
|
||||
}, [manifest, verifyFile]);
|
||||
|
||||
const showSkillMd = useCallback(() => {
|
||||
if (!selected) return;
|
||||
// A click handler cannot await, and this chain terminates in its own
|
||||
// `catch` that surfaces the message in the preview slot.
|
||||
void onReadSkillFile(selected.uri)
|
||||
.then((contents) => {
|
||||
setPreview(contents);
|
||||
setPreviewError(null);
|
||||
})
|
||||
.catch((err: unknown) => {
|
||||
setPreview(null);
|
||||
setPreviewError(err instanceof Error ? err.message : String(err));
|
||||
});
|
||||
}, [onReadSkillFile, selected]);
|
||||
|
||||
const errorCount = issues.filter((i) => i.severity === "error").length;
|
||||
const warningCount = issues.length - errorCount;
|
||||
|
||||
return (
|
||||
// `data-*` readiness contract for the headless tab smoke (#2148); see
|
||||
// clients/web/README.md#core-tab-automation-contract.
|
||||
<ScreenLayout
|
||||
data-testid="skills-screen"
|
||||
data-skill-count={skills.length}
|
||||
data-skill-page-count={pageCount}
|
||||
>
|
||||
<Sidebar>
|
||||
<SidebarCard>
|
||||
<Stack gap="sm">
|
||||
<ControlsRow>
|
||||
<SearchInput
|
||||
aria-label="Search skills"
|
||||
placeholder="Search skills"
|
||||
value={search}
|
||||
onChange={(event) =>
|
||||
onUiChange({ ...ui, search: event.currentTarget.value })
|
||||
}
|
||||
/>
|
||||
<RefreshButton onClick={onRefreshList}>Refresh</RefreshButton>
|
||||
</ControlsRow>
|
||||
{loadError && (
|
||||
<Alert color="red" title="Could not load skills">
|
||||
{loadError.message}
|
||||
</Alert>
|
||||
)}
|
||||
{filtered.length === 0 ? (
|
||||
<EmptyState>No skills</EmptyState>
|
||||
) : (
|
||||
filtered.map((skill) => {
|
||||
const skillIssues = checkSkillConformance(skill);
|
||||
const errors = skillIssues.filter(
|
||||
(i) => i.severity === "error",
|
||||
).length;
|
||||
return (
|
||||
<NavLink
|
||||
key={skill.uri}
|
||||
active={skill.uri === selectedSkillUri}
|
||||
label={skillDisplayName(skill)}
|
||||
description={skill.uri}
|
||||
onClick={() =>
|
||||
onUiChange({ ...ui, selectedSkillUri: skill.uri })
|
||||
}
|
||||
rightSection={
|
||||
skillIssues.length > 0 ? (
|
||||
<CountBadge color={errors > 0 ? "red" : "yellow"}>
|
||||
{skillIssues.length}
|
||||
</CountBadge>
|
||||
) : undefined
|
||||
}
|
||||
/>
|
||||
);
|
||||
})
|
||||
)}
|
||||
<MonoCaption>
|
||||
{skills.length} skill(s) over {pageCount} page(s)
|
||||
</MonoCaption>
|
||||
</Stack>
|
||||
</SidebarCard>
|
||||
</Sidebar>
|
||||
|
||||
<DetailCard>
|
||||
{!selected ? (
|
||||
<EmptyState>Select a skill to view details</EmptyState>
|
||||
) : (
|
||||
<DetailScroll>
|
||||
<DetailStack data-testid="skill-detail">
|
||||
<Stack gap={4}>
|
||||
<SkillTitle>{skillDisplayName(selected)}</SkillTitle>
|
||||
<MonoCaption>{selected.uri}</MonoCaption>
|
||||
</Stack>
|
||||
|
||||
{selected.frontmatter.description && (
|
||||
<Text size="sm">{selected.frontmatter.description}</Text>
|
||||
)}
|
||||
|
||||
<Stack gap="xs">
|
||||
<InlineRow>
|
||||
<SectionHeading>Conformance</SectionHeading>
|
||||
<CountBadge color={errorCount > 0 ? "red" : "green"}>
|
||||
{errorCount} error(s), {warningCount} warning(s)
|
||||
</CountBadge>
|
||||
</InlineRow>
|
||||
{issues.length === 0 ? (
|
||||
<Alert color="green" title="Conforms">
|
||||
No structural issues found in this entry.
|
||||
</Alert>
|
||||
) : (
|
||||
<IssueStack data-testid="skill-issues">
|
||||
{issues.map((issue) => (
|
||||
<Alert
|
||||
key={`${issue.code}:${issue.resourceUri ?? ""}`}
|
||||
color={issueColor(issue)}
|
||||
title={issue.code}
|
||||
>
|
||||
<Stack gap={2}>
|
||||
<Text size="sm">{issue.message}</Text>
|
||||
{issue.resourceUri && (
|
||||
<MonoCaption>{issue.resourceUri}</MonoCaption>
|
||||
)}
|
||||
</Stack>
|
||||
</Alert>
|
||||
))}
|
||||
</IssueStack>
|
||||
)}
|
||||
</Stack>
|
||||
|
||||
<Stack gap="xs">
|
||||
<ControlsRow>
|
||||
<InlineRow>
|
||||
<SectionHeading>Resources</SectionHeading>
|
||||
<CountBadge>
|
||||
{manifest.length} file(s), {totalSkillBytes(manifest)}{" "}
|
||||
bytes
|
||||
</CountBadge>
|
||||
</InlineRow>
|
||||
<InlineRow>
|
||||
<VerifyButton onClick={showSkillMd}>
|
||||
View SKILL.md
|
||||
</VerifyButton>
|
||||
<VerifyButton
|
||||
onClick={verifyAll}
|
||||
disabled={manifest.length === 0}
|
||||
>
|
||||
Verify all
|
||||
</VerifyButton>
|
||||
</InlineRow>
|
||||
</ControlsRow>
|
||||
{selected.resources === DYNAMIC_RESOURCES ? (
|
||||
<Alert color="yellow" title="Dynamic resources">
|
||||
This skill declares{" "}
|
||||
<Code>resources: "dynamic"</Code> — its files are
|
||||
generated, so no manifest is advertised and integrity cannot
|
||||
be verified.
|
||||
</Alert>
|
||||
) : (
|
||||
<ManifestTable data-testid="skill-manifest">
|
||||
<Table.Thead>
|
||||
<Table.Tr>
|
||||
<Table.Th>URI</Table.Th>
|
||||
<Table.Th>Size</Table.Th>
|
||||
<Table.Th>Digest</Table.Th>
|
||||
<Table.Th>Verification</Table.Th>
|
||||
</Table.Tr>
|
||||
</Table.Thead>
|
||||
<Table.Tbody>
|
||||
{manifest.map((resource) => {
|
||||
const state = fileStates[resource.uri];
|
||||
const color =
|
||||
state?.status === "done"
|
||||
? verificationColor(state.verification.status)
|
||||
: state?.status === "error"
|
||||
? "red"
|
||||
: "gray";
|
||||
return (
|
||||
<Table.Tr key={resource.uri}>
|
||||
<Table.Td>{resource.uri}</Table.Td>
|
||||
<Table.Td>{resource.size ?? "—"}</Table.Td>
|
||||
<Table.Td>{shortDigest(resource.digest)}</Table.Td>
|
||||
<Table.Td>
|
||||
<InlineRow>
|
||||
<CountBadge color={color}>
|
||||
{verificationLabel(state)}
|
||||
</CountBadge>
|
||||
<RowVerifyButton
|
||||
// A click handler cannot await, and
|
||||
// `verifyFile` owns its own failures — it
|
||||
// records them as this row's state.
|
||||
onClick={() => void verifyFile(resource)}
|
||||
>
|
||||
Verify
|
||||
</RowVerifyButton>
|
||||
</InlineRow>
|
||||
</Table.Td>
|
||||
</Table.Tr>
|
||||
);
|
||||
})}
|
||||
</Table.Tbody>
|
||||
</ManifestTable>
|
||||
)}
|
||||
{manifest.map((resource) => {
|
||||
const state = fileStates[resource.uri];
|
||||
if (state?.status === "done") {
|
||||
const { verification } = state;
|
||||
if (verification.status === "mismatch") {
|
||||
return (
|
||||
<Alert
|
||||
key={`mismatch:${resource.uri}`}
|
||||
color="red"
|
||||
title="Digest mismatch"
|
||||
>
|
||||
<Stack gap={2}>
|
||||
<MonoCaption>{resource.uri}</MonoCaption>
|
||||
<MonoCaption>
|
||||
expected {verification.expectedDigest}
|
||||
</MonoCaption>
|
||||
<MonoCaption>
|
||||
actual {verification.actualDigest}
|
||||
</MonoCaption>
|
||||
</Stack>
|
||||
</Alert>
|
||||
);
|
||||
}
|
||||
return null;
|
||||
}
|
||||
if (state?.status === "error") {
|
||||
return (
|
||||
<Alert
|
||||
key={`read:${resource.uri}`}
|
||||
color="red"
|
||||
title="Could not read file"
|
||||
>
|
||||
<Stack gap={2}>
|
||||
<MonoCaption>{resource.uri}</MonoCaption>
|
||||
<Text size="sm">{state.message}</Text>
|
||||
</Stack>
|
||||
</Alert>
|
||||
);
|
||||
}
|
||||
return null;
|
||||
})}
|
||||
</Stack>
|
||||
|
||||
{previewError && (
|
||||
<Alert color="red" title="Could not read SKILL.md">
|
||||
{previewError}
|
||||
</Alert>
|
||||
)}
|
||||
{preview && (
|
||||
<Stack gap="xs" data-testid="skill-md-preview">
|
||||
<SectionHeading>SKILL.md</SectionHeading>
|
||||
<ContentViewer
|
||||
block={{ type: "text", text: preview.text ?? "" }}
|
||||
mimeType={preview.mimeType ?? "text/markdown"}
|
||||
copyable
|
||||
/>
|
||||
</Stack>
|
||||
)}
|
||||
|
||||
<Stack gap="xs">
|
||||
<SectionHeading>Frontmatter</SectionHeading>
|
||||
<ContentViewer
|
||||
block={{
|
||||
type: "text",
|
||||
text: JSON.stringify(selected.frontmatter, null, 2),
|
||||
}}
|
||||
mimeType="application/json"
|
||||
copyable
|
||||
/>
|
||||
</Stack>
|
||||
</DetailStack>
|
||||
</DetailScroll>
|
||||
)}
|
||||
</DetailCard>
|
||||
</ScreenLayout>
|
||||
);
|
||||
}
|
||||
Loading…
Reference in a new issue