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>
This commit is contained in:
Ysopwnableandgensokyo-dev authored and GitHub committed 2026-11-16 16:46:46 +08:00
1 parent 230db70fb4
commit d6bcfc10ea
4 files changed
+132 -219

No files matched your search

@@ -1,3 +0,0 @@
{
"src/server/registerElectronTools.ts": 6
}
+22 -19
View File
@@ -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,
-197
View File
@@ -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<Record<string, string | undefined>>;
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),
);
};
+110
View File
@@ -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<Record<string, string | undefined>>;
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<BrowserObservationToolOptions>,
electronFuses: ((service) => ({
inspect_electron_fuses: {
admission: "application",
run: (input, options) => service.inspect(input, options),
},
})) satisfies Bind<Pick<ElectronFuseService, "inspect">>,
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<ElectronObservationToolOptions>,
// 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<ElectronScenarioToolOptions>,
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<JavaScriptApplicationToolOptions>,
// Frida sessions instrument a live process the caller selects, not the
// session's target; compose them without analysis admission.
frida: ((service, retention) => ({