From e86358c719e026830ffb157a47d53775b0145b6d Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 28 Apr 2026 21:02:06 +0000 Subject: [PATCH] Add MCP server preflight checks --- app/api/mcp/preflight/route.ts | 45 +++++++++ app/api/mcp/upload/route.ts | 27 +++++- app/components/McpConfigurationPanel.tsx | 69 +++++++++++++- app/lib/mcpPreflight.ts | 113 +++++++++++++++++++++++ tests/mcp-configuration-page-check.mjs | 15 ++- 5 files changed, 265 insertions(+), 4 deletions(-) create mode 100644 app/api/mcp/preflight/route.ts create mode 100644 app/lib/mcpPreflight.ts diff --git a/app/api/mcp/preflight/route.ts b/app/api/mcp/preflight/route.ts new file mode 100644 index 0000000..8c03768 --- /dev/null +++ b/app/api/mcp/preflight/route.ts @@ -0,0 +1,45 @@ +import { NextResponse } from "next/server" +import { preflightMcpServer } from "@/app/lib/mcpPreflight" +import { listMcpServers, type McpServerInstall } from "@/app/lib/mcpServerStore" + +function normalizeServer(body: any, installed?: McpServerInstall | null): McpServerInstall { + const now = new Date().toISOString() + const server = installed || body || {} + return { + id: String(body?.id || server.id || body?.serverId || "preflight-server"), + name: String(body?.name || server.name || body?.id || body?.serverId || "Preflight Server"), + summary: String(body?.summary || server.summary || ""), + websiteUrl: typeof body?.websiteUrl === "string" ? body.websiteUrl : server.websiteUrl, + transport: body?.transport === "http" || server.transport === "http" ? "http" : "stdio", + command: String(body?.command || server.command || ""), + args: Array.isArray(body?.args) ? body.args.map(String) : Array.isArray(server.args) ? server.args.map(String) : [], + env: body?.env && typeof body.env === "object" && !Array.isArray(body.env) ? body.env : server.env || {}, + tags: Array.isArray(body?.tags) ? body.tags.map(String) : Array.isArray(server.tags) ? server.tags.map(String) : ["custom"], + installedAt: server.installedAt || now, + updatedAt: now, + source: body?.source === "catalog" || body?.source === "registry" || body?.source === "custom" ? body.source : server.source || "custom", + enabled: true, + accessMode: "disabled", + allowedSandboxIds: [], + } +} + +export async function POST(request: Request) { + try { + const body = await request.json().catch(() => ({})) + let installed: McpServerInstall | null = null + if (typeof body?.serverId === "string" && body.serverId.trim()) { + const inventory = await listMcpServers() + installed = inventory.servers.find((server) => server.id === body.serverId.trim()) || null + if (!installed) throw new Error("MCP server is not installed") + } + + const server = normalizeServer(body, installed) + if (!server.command) throw new Error("server command is required") + const preflight = await preflightMcpServer(server) + return NextResponse.json({ ok: preflight.ok, serverId: server.id, preflight }) + } catch (error) { + const message = error instanceof Error ? error.message : "Failed to preflight MCP server" + return NextResponse.json({ ok: false, error: message }, { status: /required|installed/.test(message) ? 400 : 500 }) + } +} diff --git a/app/api/mcp/upload/route.ts b/app/api/mcp/upload/route.ts index 5cef51c..c51d096 100644 --- a/app/api/mcp/upload/route.ts +++ b/app/api/mcp/upload/route.ts @@ -4,6 +4,7 @@ import { access, mkdir, mkdtemp, readdir, rm, writeFile } from "node:fs/promises import os from "node:os" import path from "node:path" import { promisify } from "node:util" +import { preflightMcpServer } from "@/app/lib/mcpPreflight" import { installMcpServer, listMcpServers } from "@/app/lib/mcpServerStore" const execFileAsync = promisify(execFile) @@ -310,7 +311,7 @@ export async function POST(request: Request) { const projectRoot = await resolveProjectRoot(root, entrypointPath) const bootstrap = await bootstrapUploadedServer(projectRoot, runtime, entrypoint) const launch = await launchCommandForUpload(projectRoot, bootstrap, entryMode, entrypoint, entrypointPath, parseLines(form.get("args"))) - const server = await installMcpServer({ + const candidate = { id, name, summary, @@ -321,6 +322,29 @@ export async function POST(request: Request) { tags: ["uploaded", "custom"], source: "custom", enabled: true, + } as const satisfies { + id: string + name: string + summary: string + transport: "stdio" + command: string + args: string[] + env: Record + tags: string[] + source: "custom" + enabled: boolean + } + const preflight = await preflightMcpServer({ + ...candidate, + installedAt: new Date().toISOString(), + updatedAt: new Date().toISOString(), + accessMode: "disabled", + allowedSandboxIds: [], + }) + const server = await installMcpServer({ + ...candidate, + enabled: preflight.ok, + tags: preflight.ok ? candidate.tags : [...candidate.tags, "preflight-failed"], }) return NextResponse.json({ @@ -332,6 +356,7 @@ export async function POST(request: Request) { kind: bootstrap.kind, logs: bootstrap.logs, }, + preflight, ...(await listMcpServers()), }) } catch (error) { diff --git a/app/components/McpConfigurationPanel.tsx b/app/components/McpConfigurationPanel.tsx index 7d4a1e3..cae5c2e 100644 --- a/app/components/McpConfigurationPanel.tsx +++ b/app/components/McpConfigurationPanel.tsx @@ -32,6 +32,21 @@ type McpResponse = { error?: string } +type McpPreflightResult = { + ok: boolean + checkedAt: string + toolCount: number + tools: string[] + durationMs: number + error?: string + diagnosis: { + summary: string + likelyCauses: string[] + suggestedFixes: string[] + confidence: "low" | "medium" | "high" + } +} + type McpSandbox = { id: string name: string @@ -92,6 +107,7 @@ export default function McpConfigurationPanel({ sandboxes = [] }: McpConfigurati const [registryLoading, setRegistryLoading] = useState(false) const [registryPage, setRegistryPage] = useState(1) const [lastRegistrySearch, setLastRegistrySearch] = useState("") + const [preflightResults, setPreflightResults] = useState>({}) const [catalogOpen, setCatalogOpen] = useState(false) const [customOpen, setCustomOpen] = useState(false) @@ -293,6 +309,38 @@ export default function McpConfigurationPanel({ sandboxes = [] }: McpConfigurati } } + function summarizePreflight(preflight: McpPreflightResult) { + if (preflight.ok) { + return `${preflight.diagnosis.summary}${preflight.tools.length > 0 ? ` Tools: ${preflight.tools.join(", ")}.` : ""}` + } + const causes = preflight.diagnosis.likelyCauses.length > 0 + ? `\nLikely: ${preflight.diagnosis.likelyCauses.join(" ")}` + : "" + const fixes = preflight.diagnosis.suggestedFixes.length > 0 + ? `\nTry: ${preflight.diagnosis.suggestedFixes.join(" ")}` + : "" + return `${preflight.diagnosis.summary}\n${preflight.error || "MCP tool discovery failed."}${causes}${fixes}` + } + + async function preflightServer(server: McpServerInstall) { + try { + setSaving(true) + const response = await fetch("/api/mcp/preflight", { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ serverId: server.id }), + }) + const data = await response.json() as { preflight?: McpPreflightResult; error?: string } + if (!response.ok || !data.preflight) throw new Error(data.error || "Failed to preflight MCP server") + setPreflightResults((current) => ({ ...current, [server.id]: data.preflight as McpPreflightResult })) + setMessage(`${server.name} preflight ${data.preflight.ok ? "passed" : "failed"}.\n${summarizePreflight(data.preflight)}`) + } catch (error) { + setMessage(error instanceof Error ? error.message : "Failed to preflight MCP server") + } finally { + setSaving(false) + } + } + async function uploadServer() { try { if (!uploadArchive && uploadFiles.length === 0) { @@ -318,17 +366,23 @@ export default function McpConfigurationPanel({ sandboxes = [] }: McpConfigurati }) } const response = await fetch("/api/mcp/upload", { method: "POST", body: form }) - const data = await response.json() as McpResponse & { dependencyInstall?: { kind?: string; logs?: string[] } } + const data = await response.json() as McpResponse & { dependencyInstall?: { kind?: string; logs?: string[] }; preflight?: McpPreflightResult; server?: McpServerInstall } if (!response.ok) throw new Error(data.error || "Failed to upload MCP server") setCatalog(Array.isArray(data.catalog) ? data.catalog : catalog) setServers(Array.isArray(data.servers) ? data.servers : []) setConfig(data.config || { mcpServers: {} }) + if (data.preflight && data.server?.id) { + setPreflightResults((current) => ({ ...current, [data.server!.id]: data.preflight as McpPreflightResult })) + } setUploadFiles([]) setUploadPaths([]) setUploadArchive(null) const installKind = data.dependencyInstall?.kind || "generic" const installLogCount = data.dependencyInstall?.logs?.filter(Boolean).length || 0 - setMessage(`${customName} uploaded. ${installKind === "generic" ? "No dependency bootstrap was needed." : `${installKind} dependencies bootstrapped${installLogCount > 0 ? ` with ${installLogCount} install step${installLogCount === 1 ? "" : "s"}` : ""}.`}`) + const preflightNote = data.preflight + ? `\nPreflight ${data.preflight.ok ? "passed" : "failed; server saved disabled"}.\n${summarizePreflight(data.preflight)}` + : "" + setMessage(`${customName} uploaded. ${installKind === "generic" ? "No dependency bootstrap was needed." : `${installKind} dependencies bootstrapped${installLogCount > 0 ? ` with ${installLogCount} install step${installLogCount === 1 ? "" : "s"}` : ""}.`}${preflightNote}`) } catch (error) { setMessage(error instanceof Error ? error.message : "Failed to upload MCP server") } finally { @@ -785,6 +839,9 @@ export default function McpConfigurationPanel({ sandboxes = [] }: McpConfigurati + @@ -792,6 +849,14 @@ export default function McpConfigurationPanel({ sandboxes = [] }: McpConfigurati Remove + {preflightResults[server.id] && ( +
+
+ Preflight {preflightResults[server.id].ok ? "passed" : "failed"} / {preflightResults[server.id].durationMs} ms +
+

{summarizePreflight(preflightResults[server.id])}

+
+ )} {editingServerId === server.id && (
diff --git a/app/lib/mcpPreflight.ts b/app/lib/mcpPreflight.ts new file mode 100644 index 0000000..48b2a37 --- /dev/null +++ b/app/lib/mcpPreflight.ts @@ -0,0 +1,113 @@ +import { listBrokerServerTools } from "./mcpBrokerClient" +import type { McpServerInstall } from "./mcpServerStore" + +export type McpPreflightResult = { + ok: boolean + checkedAt: string + toolCount: number + tools: string[] + durationMs: number + error?: string + diagnosis: { + summary: string + likelyCauses: string[] + suggestedFixes: string[] + confidence: "low" | "medium" | "high" + } +} + +function commandLine(server: Pick) { + return [server.command, ...(server.args || [])].filter(Boolean).join(" ") +} + +function diagnoseFailure(server: Pick, error: string): McpPreflightResult["diagnosis"] { + const joinedArgs = (server.args || []).join(" ") + const command = commandLine(server) + const likelyCauses: string[] = [] + const suggestedFixes: string[] = [] + let confidence: McpPreflightResult["diagnosis"]["confidence"] = "medium" + + if (/attempted relative import with no known parent package/i.test(error)) { + confidence = "high" + likelyCauses.push("The Python server was launched as a raw file even though it uses package-relative imports.") + suggestedFixes.push("Switch the upload launch mode to Python module and use an entrypoint like package_name.server.") + suggestedFixes.push("Alternatively use Console script if pyproject.toml defines a [project.scripts] entry.") + } + + if (/unexpected keyword argument ['\"]description['\"]/i.test(error) || /FastMCP\.__init__\(\).*description/i.test(error)) { + confidence = "high" + likelyCauses.push("The server code targets a different MCP SDK FastMCP constructor than the one installed in the upload environment.") + suggestedFixes.push("Remove the description= argument from FastMCP(...) or pin the mcp dependency to a version that supports it.") + } + + if (/No module named ['\"][^'\"]+['\"]|ModuleNotFoundError/i.test(error)) { + confidence = confidence === "high" ? "high" : "medium" + likelyCauses.push("A Python dependency is missing from requirements.txt or pyproject.toml.") + suggestedFixes.push("Add the missing package to project dependencies, then upload again so the virtualenv is rebuilt.") + } + + if (/command not found|ENOENT|spawn .* ENOENT/i.test(error)) { + confidence = "high" + likelyCauses.push("The configured command is not available on the controller host PATH.") + suggestedFixes.push("Use an installed command, an absolute path, or upload a bundled server so OpenShell Control can create the runtime environment.") + } + + if (/ECONNREFUSED|ENOTFOUND|404 Not Found|fetch failed|connect/i.test(error) && server.transport === "http") { + likelyCauses.push("The remote MCP endpoint did not answer as a streamable HTTP MCP server.") + suggestedFixes.push("Confirm the endpoint URL points at the MCP route, not just the service root.") + } + + if (/^-m\s+\S+/.test(joinedArgs) || joinedArgs.includes(" -m ")) { + suggestedFixes.push("Confirm the Python module path is importable after dependency installation.") + } + + if (likelyCauses.length === 0) { + likelyCauses.push("The server process did not complete MCP initialization and tool discovery.") + suggestedFixes.push("Run the command manually on the controller host and check stderr for startup errors.") + if (/\.py(\s|$)/.test(command)) { + suggestedFixes.push("If this is a Python package, try Python module or Console script launch mode instead of File.") + } + confidence = "low" + } + + return { + summary: `Preflight could not list MCP tools for: ${command}`, + likelyCauses, + suggestedFixes, + confidence, + } +} + +export async function preflightMcpServer(server: McpServerInstall): Promise { + const checkedAt = new Date().toISOString() + const startedAt = Date.now() + try { + const tools = await listBrokerServerTools(server) + return { + ok: true, + checkedAt, + toolCount: tools.length, + tools: tools.slice(0, 12).map((tool) => tool.name), + durationMs: Date.now() - startedAt, + diagnosis: { + summary: tools.length > 0 + ? `Preflight listed ${tools.length} MCP tool${tools.length === 1 ? "" : "s"}.` + : "Preflight connected but the server did not report any tools.", + likelyCauses: [], + suggestedFixes: tools.length > 0 ? [] : ["Confirm this server is expected to expose tools rather than only resources or prompts."], + confidence: "high", + }, + } + } catch (error) { + const message = error instanceof Error ? error.message : "MCP server preflight failed" + return { + ok: false, + checkedAt, + toolCount: 0, + tools: [], + durationMs: Date.now() - startedAt, + error: message, + diagnosis: diagnoseFailure(server, message), + } + } +} diff --git a/tests/mcp-configuration-page-check.mjs b/tests/mcp-configuration-page-check.mjs index eb3c0a1..a349468 100644 --- a/tests/mcp-configuration-page-check.mjs +++ b/tests/mcp-configuration-page-check.mjs @@ -11,12 +11,14 @@ const manifestPath = path.join(root, 'app/lib/sandboxMcpManifest.ts') const privilegedFilesPath = path.join(root, 'app/lib/sandboxPrivilegedFiles.ts') const routePath = path.join(root, 'app/api/mcp/route.ts') const uploadRoutePath = path.join(root, 'app/api/mcp/upload/route.ts') +const preflightRoutePath = path.join(root, 'app/api/mcp/preflight/route.ts') const healthRoutePath = path.join(root, 'app/api/mcp/health/route.ts') const registryRoutePath = path.join(root, 'app/api/mcp/registry/route.ts') const brokerCapabilitiesRoutePath = path.join(root, 'app/api/mcp/broker/capabilities/route.ts') const brokerCallRoutePath = path.join(root, 'app/api/mcp/broker/call/route.ts') const sandboxMcpRoutePath = path.join(root, 'app/api/sandbox/[sandboxId]/mcp/route.ts') const brokerUrlPath = path.join(root, 'app/lib/mcpBrokerUrl.ts') +const preflightLibPath = path.join(root, 'app/lib/mcpPreflight.ts') const middlewarePath = path.join(root, 'middleware.ts') const panelPath = path.join(root, 'app/components/McpConfigurationPanel.tsx') const helpPath = path.join(root, 'app/components/HelpPanel.tsx') @@ -24,7 +26,7 @@ const sidebarPath = path.join(root, 'app/components/Sidebar.tsx') const sandboxListPath = path.join(root, 'app/components/SandboxList.tsx') const pagePath = path.join(root, 'app/page.tsx') -const [storeSource, brokerStoreSource, brokerClientSource, manifestSource, privilegedFilesSource, routeSource, uploadRouteSource, healthRouteSource, registryRouteSource, brokerCapabilitiesRouteSource, brokerCallRouteSource, sandboxMcpRouteSource, brokerUrlSource, middlewareSource, panelSource, helpSource, sidebarSource, sandboxListSource, pageSource] = await Promise.all([ +const [storeSource, brokerStoreSource, brokerClientSource, manifestSource, privilegedFilesSource, routeSource, uploadRouteSource, preflightRouteSource, healthRouteSource, registryRouteSource, brokerCapabilitiesRouteSource, brokerCallRouteSource, sandboxMcpRouteSource, brokerUrlSource, preflightLibSource, middlewareSource, panelSource, helpSource, sidebarSource, sandboxListSource, pageSource] = await Promise.all([ readFile(storePath, 'utf8'), readFile(brokerStorePath, 'utf8'), readFile(brokerClientPath, 'utf8'), @@ -32,12 +34,14 @@ const [storeSource, brokerStoreSource, brokerClientSource, manifestSource, privi readFile(privilegedFilesPath, 'utf8'), readFile(routePath, 'utf8'), readFile(uploadRoutePath, 'utf8'), + readFile(preflightRoutePath, 'utf8'), readFile(healthRoutePath, 'utf8'), readFile(registryRoutePath, 'utf8'), readFile(brokerCapabilitiesRoutePath, 'utf8'), readFile(brokerCallRoutePath, 'utf8'), readFile(sandboxMcpRoutePath, 'utf8'), readFile(brokerUrlPath, 'utf8'), + readFile(preflightLibPath, 'utf8'), readFile(middlewarePath, 'utf8'), readFile(panelPath, 'utf8'), readFile(helpPath, 'utf8'), @@ -103,7 +107,14 @@ assert.match(uploadRouteSource, /entryMode/, 'MCP upload API must support non-fi assert.match(uploadRouteSource, /python-module/, 'MCP upload API must support Python module launch') assert.match(uploadRouteSource, /console-script/, 'MCP upload API must support installed console script launch') assert.match(uploadRouteSource, /resolveProjectRoot/, 'MCP upload API must find project manifests inside uploaded directories') +assert.match(uploadRouteSource, /preflightMcpServer/, 'MCP upload API must preflight uploaded server bundles') +assert.match(uploadRouteSource, /preflight-failed/, 'MCP upload API must mark failed preflight installs') assert.match(uploadRouteSource, /installMcpServer/, 'MCP upload API must install uploaded server bundles') +assert.match(preflightRouteSource, /export async function POST/, 'MCP preflight API must expose a POST check endpoint') +assert.match(preflightRouteSource, /preflightMcpServer/, 'MCP preflight API must call the shared preflight helper') +assert.match(preflightLibSource, /listBrokerServerTools/, 'MCP preflight must validate servers through SDK tool discovery') +assert.match(preflightLibSource, /attempted relative import/, 'MCP preflight assistant must recognize Python package launch failures') +assert.match(preflightLibSource, /FastMCP/, 'MCP preflight assistant must recognize MCP SDK compatibility failures') assert.match(healthRouteSource, /listBrokerServerTools/, 'MCP health API must inspect server tools through the broker client') assert.match(healthRouteSource, /enabledServers/, 'MCP health API must check enabled MCP servers') assert.match(registryRouteSource, /registry\.modelcontextprotocol\.io/, 'MCP registry search should default to the official registry') @@ -121,6 +132,8 @@ assert.match(panelSource, /uploadEntrypoint/, 'MCP custom server upload must col assert.match(panelSource, /uploadEntryMode/, 'MCP custom server upload must collect a launch mode') assert.match(panelSource, /Python module/, 'MCP custom server upload must expose Python module launch mode') assert.match(panelSource, /Console script/, 'MCP custom server upload must expose console script launch mode') +assert.match(panelSource, /preflightServer/, 'MCP page must let operators preflight installed servers') +assert.match(panelSource, /Preflight/, 'MCP page must show preflight controls and results') assert.match(panelSource, /serverPayloadFromJson/, 'MCP page must parse edited server JSON') assert.match(panelSource, /startEditingServer/, 'MCP installed server list must expose edit state') assert.match(panelSource, /Server JSON/, 'MCP installed server editor must render an inline JSON file editor')