Add MCP server preflight checks

This commit is contained in:
Codex
2026-04-28 21:02:12 +00:00
parent da015fb73a
commit 99bcd63e4e
5 changed files with 265 additions and 4 deletions
+45
View File
@@ -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 })
}
}
+26 -1
View File
@@ -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<string, string>
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) {
+67 -2
View File
@@ -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<Record<string, McpPreflightResult>>({})
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
<button onClick={() => startEditingServer(server)} disabled={saving} className="action-button flex-1 px-3 py-2">
Edit
</button>
<button onClick={() => preflightServer(server)} disabled={saving} className="action-button flex-1 px-3 py-2">
Preflight
</button>
<button onClick={() => setServerEnabled(server, !server.enabled)} disabled={saving} className="action-button flex-1 px-3 py-2">
{server.enabled ? "Disable" : "Enable"}
</button>
@@ -792,6 +849,14 @@ export default function McpConfigurationPanel({ sandboxes = [] }: McpConfigurati
Remove
</button>
</div>
{preflightResults[server.id] && (
<div className={`mt-4 rounded-sm border p-3 text-xs ${preflightResults[server.id].ok ? "border-[var(--status-running)] bg-[var(--status-running-bg)] text-[var(--status-running)]" : "border-[var(--status-error)] bg-[var(--status-error-bg)] text-[var(--status-error)]"}`}>
<div className="font-mono uppercase tracking-wider">
Preflight {preflightResults[server.id].ok ? "passed" : "failed"} / {preflightResults[server.id].durationMs} ms
</div>
<p className="mt-2 whitespace-pre-wrap text-[11px] leading-5">{summarizePreflight(preflightResults[server.id])}</p>
</div>
)}
{editingServerId === server.id && (
<div className="mt-4 border-t border-[var(--border-subtle)] pt-4">
<div className="flex items-center justify-between gap-3">
+113
View File
@@ -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<McpServerInstall, "command" | "args">) {
return [server.command, ...(server.args || [])].filter(Boolean).join(" ")
}
function diagnoseFailure(server: Pick<McpServerInstall, "command" | "args" | "transport">, 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<McpPreflightResult> {
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),
}
}
}
+14 -1
View File
@@ -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')