From d6bcfc10eafa3c0893c7cbd5f3dc6a90359be022 Mon Sep 17 00:00:00 2001 From: Ysopwnable <161784452+N0zoM1z0@users.noreply.github.com> Date: Mon, 16 Nov 2026 09:46:46 +0100 Subject: [PATCH] refactor(mcp): bind Electron tools through shared contracts Move the last six bespoke Electron MCP registrations to named shared bindings, preserving admission, provider isolation, selected settings, Evidence and cleanup behavior. Remove the obsolete family module, redundant dependency bundle and final counted registration baseline. Refs #11682 (D7). Co-authored-by: gensokyo-dev <342580529+gensokyo-dev@users.noreply.github.com> --- .../bespoke-mcp-tool-registration.json | 3 - src/server/createServer.ts | 41 ++-- src/server/registerElectronTools.ts | 197 ------------------ src/server/serviceToolBindings.ts | 110 ++++++++++ 4 files changed, 132 insertions(+), 219 deletions(-) delete mode 100644 scripts/verify/baselines/bespoke-mcp-tool-registration.json delete mode 100644 src/server/registerElectronTools.ts diff --git a/scripts/verify/baselines/bespoke-mcp-tool-registration.json b/scripts/verify/baselines/bespoke-mcp-tool-registration.json deleted file mode 100644 index f9a02a7319..0000000000 --- a/scripts/verify/baselines/bespoke-mcp-tool-registration.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "src/server/registerElectronTools.ts": 6 -} diff --git a/src/server/createServer.ts b/src/server/createServer.ts index 0dc0bf1344..3a8845469c 100644 --- a/src/server/createServer.ts +++ b/src/server/createServer.ts @@ -38,7 +38,6 @@ import { PRODUCT_IDENTITY } from "../identity.js"; import { silentLogger } from "../logger.js"; import type { Logger } from "pino"; import { JavaScriptRecoveryService } from "../application/javascript/JavaScriptRecoveryService.js"; -import { registerElectronTools } from "./registerElectronTools.js"; import { AndroidAnalysisService } from "../application/android/AndroidAnalysisService.js"; import { JebAnalysisService } from "../application/jeb/JebAnalysisService.js"; import { PcapAnalysisService } from "../application/pcap/PcapAnalysisService.js"; @@ -321,11 +320,6 @@ export const createServer = ( if (failures.length > 1) throw new AggregateError(failures, "REA server cleanup failed"); }; - const common = { - logger: toolLogger, - recordEvidence, - withAdmittedAnalysis: analysisAdmission, - }; const contractTools = { logger: toolLogger, recordEvidence, @@ -539,19 +533,28 @@ export const createServer = ( ); }, electron: () => - registerElectronTools(server, { - ...common, - artifactResources, - environment, - evidenceById, - electron: options.electronObservation, - electronActive: options.electronActiveObservation, - electronFuses, - observationLoadFailure: - options.optionalProviderLoadFailures?.electronObservation, - activeLoadFailure: - options.optionalProviderLoadFailures?.electronActiveObservation, - }), + registerServiceTools( + server, + { + electronFuses, + electronObservation: { + provider: options.electronObservation, + loadFailure: + options.optionalProviderLoadFailures?.electronObservation, + }, + electronScenario: { + provider: options.electronActiveObservation, + loadFailure: + options.optionalProviderLoadFailures?.electronActiveObservation, + }, + javascriptApplication: { + resources: artifactResources, + environment, + settings: analysisSettings.read, + }, + }, + contractTools, + ), "javascript-runtime": () => registerServiceTools( server, diff --git a/src/server/registerElectronTools.ts b/src/server/registerElectronTools.ts deleted file mode 100644 index bb34b50f99..0000000000 --- a/src/server/registerElectronTools.ts +++ /dev/null @@ -1,197 +0,0 @@ -import type { EvidenceMcpServer } from "./EvidenceMcpServer.js"; -import { - projectRetainedAnalysis, - requireAnalysisViewRetention, -} from "../application/analysisView/AnalysisViewService.js"; -import type { EvidenceLookup } from "../application/EvidenceInputResolver.js"; -import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js"; -import type { OptionalProviderLoadFailure } from "../ports/OptionalObservationProviders.js"; - -import type { ElectronActiveObservationPort } from "../ports/javascript/ElectronActiveObservationPort.js"; -import { captureElectronScenario } from "../application/javascript/ElectronActiveObservationService.js"; -import type { ElectronObservationPort } from "../ports/javascript/ElectronObservationPort.js"; -import { - inspectElectronPage, - listElectronTargets, -} from "../application/javascript/ElectronObservationService.js"; -import { analyzeJavaScriptApplicationValidated } from "../application/javascript/JavaScriptApplicationService.js"; -import { javascriptSourceAnalysis } from "../composition/javascriptSourceAnalysis.js"; -import type { ArtifactResourceScope } from "../resources/index.js"; -import { reconcileJavaScriptRuntimeEvidence } from "../application/javascript/JavaScriptRuntimeReconciliationService.js"; -import { recordEvidenceSources } from "../application/investigation/recordEvidenceSources.js"; -import type { ElectronFuseService } from "../application/electron/ElectronFuseService.js"; -import { toolContract } from "../contracts/toolContracts.js"; -import type { Logger } from "pino"; -import { - applicationToolRegistrationOptions, - toolRegistrationOptions, -} from "./toolRegistrationOptions.js"; -import type { WithAdmittedAnalysis } from "./analysisAdmission.js"; -import { - createEvidenceToolHandler, - runEvidenceToolOperation, -} from "./contractToolHandler.js"; - -interface ElectronToolRegistration { - readonly artifactResources: ArtifactResourceScope; - /** The server's selected environment; JavaScript analysis reads its admission settings. */ - readonly environment: Readonly>; - readonly logger: Logger; - readonly observationLoadFailure?: OptionalProviderLoadFailure | undefined; - readonly activeLoadFailure?: OptionalProviderLoadFailure | undefined; - readonly electron: ElectronObservationPort | undefined; - readonly electronActive: ElectronActiveObservationPort | undefined; - readonly electronFuses: ElectronFuseService; - readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined; - readonly evidenceById: EvidenceLookup | undefined; - readonly withAdmittedAnalysis?: WithAdmittedAnalysis; -} - -/** Register Electron tools even when a provider is absent. */ -// oxlint-disable-next-line max-lines-per-function -- direct SDK calls retain each schema-handler type correlation. -export const registerElectronTools = ( - server: EvidenceMcpServer, - options: ElectronToolRegistration, -): void => { - const registration = { ...options, server }; - registerElectronFuseTool(server, options); - const listContract = toolContract("list_electron_targets"); - const inspectContract = toolContract("inspect_electron_page"); - const analyzeContract = toolContract("analyze_javascript_application"); - const reconcileContract = toolContract("reconcile_javascript_runtime"); - const activeContract = toolContract("capture_electron_scenario"); - - server.registerTool( - listContract.name, - toolRegistrationOptions(listContract), - (input, context) => - runEvidenceToolOperation( - registration, - listContract, - options.observationLoadFailure, - { input, context }, - (parsed, { signal }) => - listElectronTargets(options.electron, parsed, { - signal, - }), - ), - ); - server.registerTool( - inspectContract.name, - toolRegistrationOptions(inspectContract), - (input, context) => - runEvidenceToolOperation( - registration, - inspectContract, - options.observationLoadFailure, - { input, context }, - (parsed, { signal, progress }) => - inspectElectronPage(options.electron, parsed, { - signal, - progress, - }), - ), - ); - server.registerTool( - analyzeContract.name, - toolRegistrationOptions(analyzeContract), - (input, context) => - runEvidenceToolOperation( - registration, - analyzeContract, - undefined, - { input, context }, - async ({ detail, view, ...request }, { signal, progress }) => { - if (detail === "summary") { - const ready = requireAnalysisViewRetention( - analyzeContract.name, - options, - ); - if (!ready.ok) return ready; - } - const analyzed = await analyzeJavaScriptApplicationValidated( - request, - options.artifactResources, - { - sourceAnalysis: javascriptSourceAnalysis, - signal, - progress, - environment: options.environment, - ...(server.analysisSettings === undefined - ? {} - : { settings: server.analysisSettings.read }), - }, - ); - return detail === "summary" && analyzed.ok - ? projectRetainedAnalysis( - analyzed.value, - options, - view ?? { kind: "summary" }, - ) - : analyzed; - }, - ), - ); - server.registerTool( - reconcileContract.name, - toolRegistrationOptions(reconcileContract), - (input, context) => - runEvidenceToolOperation( - registration, - reconcileContract, - undefined, - { input, context }, - async (parsed, { signal }) => { - const result = reconcileJavaScriptRuntimeEvidence( - parsed, - options.evidenceById, - { signal }, - ); - if (!result.ok) return result; - const recorded = recordEvidenceSources( - options.recordEvidence, - result.value.sources, - { evidence: result.value.evidence }, - ); - return recorded.ok - ? { ok: true, value: result.value.evidence } - : recorded; - }, - ), - ); - server.registerTool( - activeContract.name, - toolRegistrationOptions(activeContract), - (input, context) => - runEvidenceToolOperation( - registration, - activeContract, - options.activeLoadFailure, - { input, context }, - (parsed, { signal, progress }) => - captureElectronScenario(options.electronActive, parsed, { - signal, - progress, - }), - ), - ); -}; - -const registerElectronFuseTool = ( - server: EvidenceMcpServer, - options: ElectronToolRegistration, -): void => { - const contract = toolContract("inspect_electron_fuses"); - const handler = createEvidenceToolHandler( - server, - (input, execution) => options.electronFuses.inspect(input, execution), - options.logger, - options.recordEvidence, - options.withAdmittedAnalysis, - ); - server.registerTool( - contract.name, - applicationToolRegistrationOptions(contract), - handler(contract), - ); -}; diff --git a/src/server/serviceToolBindings.ts b/src/server/serviceToolBindings.ts index 1a30053c0e..2042c5bfa3 100644 --- a/src/server/serviceToolBindings.ts +++ b/src/server/serviceToolBindings.ts @@ -1,5 +1,17 @@ import type { AdbDeviceAnalysisService } from "../application/adb/AdbDeviceAnalysisService.js"; import type { AnalysisSettings } from "../application/AnalysisSettings.js"; +import type { AnalysisSettingsReader } from "../domain/analysisSettings.js"; +import type { ElectronFuseService } from "../application/electron/ElectronFuseService.js"; +import type { ElectronObservationPort } from "../ports/javascript/ElectronObservationPort.js"; +import type { ElectronActiveObservationPort } from "../ports/javascript/ElectronActiveObservationPort.js"; +import { + inspectElectronPage, + listElectronTargets, +} from "../application/javascript/ElectronObservationService.js"; +import { captureElectronScenario } from "../application/javascript/ElectronActiveObservationService.js"; +import { analyzeJavaScriptApplicationValidated } from "../application/javascript/JavaScriptApplicationService.js"; +import { reconcileJavaScriptRuntimeEvidence } from "../application/javascript/JavaScriptRuntimeReconciliationService.js"; +import { javascriptSourceAnalysis } from "../composition/javascriptSourceAnalysis.js"; import { analysisSettingsConstraints } from "./analysisSettingsConstraints.js"; import type { ToolResultDelivery } from "./ToolResultDelivery.js"; import type { AndroidAnalysisService } from "../application/android/AndroidAnalysisService.js"; @@ -336,6 +348,25 @@ export interface BrowserObservationToolOptions { readonly loadFailure?: OptionalProviderLoadFailure | undefined; } +/** Passive Electron observation is independent of active scenario capture. */ +interface ElectronObservationToolOptions { + readonly provider: ElectronObservationPort | undefined; + readonly loadFailure?: OptionalProviderLoadFailure | undefined; +} + +/** Existing owned Electron scenario execution and its independent load failure. */ +interface ElectronScenarioToolOptions { + readonly provider: ElectronActiveObservationPort | undefined; + readonly loadFailure?: OptionalProviderLoadFailure | undefined; +} + +/** Static JavaScript analysis needs local artifacts, never an Electron runtime. */ +interface JavaScriptApplicationToolOptions { + readonly resources: ArtifactResourceScope; + readonly environment: Readonly>; + readonly settings?: AnalysisSettingsReader; +} + /** The session native matching reads, and its allowance for each accepted call. */ export interface NativeFunctionMatchingToolOptions { readonly session: BinarySessionPort; @@ -1562,6 +1593,85 @@ const SERVICE_TOOL_BINDINGS = { }, }; }) satisfies Bind, + electronFuses: ((service) => ({ + inspect_electron_fuses: { + admission: "application", + run: (input, options) => service.inspect(input, options), + }, + })) satisfies Bind>, + electronObservation: (({ provider, loadFailure }) => ({ + list_electron_targets: { + admission: "sdk", + unavailable: loadFailure, + run: (input, options) => listElectronTargets(provider, input, options), + }, + inspect_electron_page: { + admission: "sdk", + unavailable: loadFailure, + run: (input, options) => inspectElectronPage(provider, input, options), + }, + })) satisfies Bind, + // Keep active capture separate from passive observation and static analysis. + // Its existing service owns execution admission, effects and cleanup. + electronScenario: (({ provider, loadFailure }) => ({ + capture_electron_scenario: { + admission: "sdk", + unavailable: loadFailure, + run: (input, options) => + captureElectronScenario(provider, input, options), + }, + })) satisfies Bind, + javascriptApplication: (( + { resources, environment, settings }, + retention, + ) => ({ + analyze_javascript_application: { + admission: "sdk", + run: async ({ detail, view, ...request }, options) => { + if (detail === "summary") { + const ready = requireAnalysisViewRetention( + "analyze_javascript_application", + retention, + ); + if (!ready.ok) return ready; + } + const analyzed = await analyzeJavaScriptApplicationValidated( + request, + resources, + { + ...options, + sourceAnalysis: javascriptSourceAnalysis, + environment, + ...(settings === undefined ? {} : { settings }), + }, + ); + return detail === "summary" && analyzed.ok + ? projectRetainedAnalysis( + analyzed.value, + retention, + view ?? { kind: "summary" }, + ) + : analyzed; + }, + }, + reconcile_javascript_runtime: { + admission: "sdk", + run: async (input, options) => { + const result = reconcileJavaScriptRuntimeEvidence( + input, + retention.evidenceById, + options, + ); + if (!result.ok) return result; + const recorded = recordEvidenceSources( + retention.recordEvidence, + result.value.sources, + { evidence: result.value.evidence }, + ); + return recorded.ok ? ok(result.value.evidence) : recorded; + }, + }, + })) satisfies Bind, // Frida sessions instrument a live process the caller selects, not the // session's target; compose them without analysis admission. frida: ((service, retention) => ({