feat: flag unportable tool schemas in all three clients

Closes #1005

A tool schema can be perfectly legal JSON Schema and still be rejected by
the client the server is meant to run against — Go's `jsonschema` emits a
bare `true` for `interface{}`, which the SDK accepts and Claude Code
refuses with an opaque "Invalid input". The Inspector passed it through
silently.

Adds `core/json/schemaLint.ts`, a portability lint over a tool's
inputSchema/outputSchema, and surfaces one shared verdict everywhere:
the CLI's `--strict` report (exit 6 on an error-severity finding), the
TUI's tool list marker + detail pane, and the web Tools sidebar flag +
detail section.

Deliberately not a JSON Schema validator: a census of 617 public servers
found zero that fail the SDK's own parse, so a conformance check would
report nothing on real servers. Each rule is instead a construct that is
legal JSON Schema and known to be refused or mishandled by a shipping
client — a bare boolean in a schema position, an array-form `type`, a
remote `$ref`, a schema with no validation keyword, a non-object root.

`test-servers/configs/unportable-schemas-http.json` exercises every rule,
via a new `rawToolSchemas` override — the Zod-built presets cannot emit
any of these shapes, which is the same reason a real server only hits
this when its schemas come from another generator.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UL9retfvAXRgvi6EWk4SY4
Signed-off-by: cliffhall <cliff@futurescale.com>
This commit is contained in:
cliffhall 2026-08-25 01:18:53 -04:00
commit 2f9e0901c1

View file

@ -1,9 +1,43 @@
import React, { useState, useEffect, useRef } from "react";
import React, { useState, useEffect, useMemo, useRef } from "react";
import { Box, Text, useInput, type Key } from "ink";
import { ScrollView, type ScrollViewRef } from "ink-scroll-view";
import type { Tool } from "@modelcontextprotocol/client";
import {
describeSchemaPath,
lintToolSchemas,
type SchemaFinding,
} from "@inspector/core/json/schemaLint.js";
import { useSelectableList } from "../hooks/useSelectableList.js";
/**
* How each severity renders in the terminal (#1005). One table, read by both
* the list row's flag and the detail block's heading, so the two can never
* disagree about what a severity looks like.
*/
const SEVERITY_MARKER = {
error: { glyph: "!", color: "red" },
warning: { glyph: "?", color: "yellow" },
} as const satisfies Record<
SchemaFinding["severity"],
{ glyph: string; color: string }
>;
/**
* The one-glyph flag a tool row carries when its schemas have portability
* findings: `!` in red when something is refused outright by a real client,
* `?` in yellow when it is merely handled unevenly. `undefined` — no glyph at
* all — for a clean tool, which is the overwhelming majority, so the list
* stays quiet unless there is something to say.
*/
export function schemaMarker(
findings: readonly SchemaFinding[] | undefined,
): { glyph: string; color: string } | undefined {
if (!findings || findings.length === 0) return undefined;
return findings.some((f) => f.severity === "error")
? SEVERITY_MARKER.error
: SEVERITY_MARKER.warning;
}
interface ToolsTabProps {
tools: Tool[];
isConnected: boolean;
@ -33,6 +67,13 @@ export function ToolsTab({
{ resetWhen: tools },
);
const [error] = useState<string | null>(null);
// Tool-schema portability findings, one entry per tool, same order (#1005).
// Pure walk over data already in memory, so it is recomputed only when the
// list itself changes rather than on every keypress.
const findingsByTool = useMemo(
() => tools.map((tool) => lintToolSchemas(tool)),
[tools],
);
const scrollViewRef = useRef<ScrollViewRef>(null);
const listWidth = Math.floor(width * 0.4);
const detailWidth = width - listWidth;
@ -90,6 +131,7 @@ export function ToolsTab({
}, [selectedIndex]);
const selectedTool = tools[selectedIndex] || null;
const selectedFindings = findingsByTool[selectedIndex] ?? [];
return (
<Box flexDirection="row" width={width} height={height}>
@ -133,11 +175,15 @@ export function ToolsTab({
.map((tool, i) => {
const index = firstVisible + i;
const isSelected = index === selectedIndex;
const marker = schemaMarker(findingsByTool[index]);
return (
<Box key={tool.name || index} paddingY={0} flexShrink={0}>
<Text>
{isSelected ? "▶ " : " "}
{tool.name || `Tool ${index + 1}`}
{marker && (
<Text color={marker.color}> {marker.glyph}</Text>
)}
</Text>
</Box>
);
@ -200,6 +246,36 @@ export function ToolsTab({
</>
)}
{/* Schema portability findings (#1005) */}
{selectedFindings.length > 0 && (
<>
<Box marginTop={1} flexShrink={0}>
<Text bold color="yellow">
Schema Portability ({selectedFindings.length}):
</Text>
</Box>
{selectedFindings.map((finding, idx) => {
const marker = SEVERITY_MARKER[finding.severity];
return (
<Box
key={`finding-${finding.schema}-${finding.path}-${finding.rule}-${idx}`}
flexDirection="column"
paddingLeft={2}
marginTop={1}
flexShrink={0}
>
<Text color={marker.color}>
{marker.glyph}{" "}
{describeSchemaPath(finding.schema, finding.path)}
</Text>
<Text dimColor>{finding.issue}</Text>
<Text dimColor>Fix: {finding.suggestion}</Text>
</Box>
);
})}
</>
)}
{/* Input Schema */}
{selectedTool.inputSchema && (
<>