From 4b014fa9add9389fccc2ed17c6737d02c07b8abf Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Mon, 16 Nov 2026 03:15:41 +0800 Subject: [PATCH] refactor(mcp): bind web network capture and web runtime tools through the shared service binding table (#11385) * refactor(mcp): bind web network capture through the shared service binding table * refactor(mcp): bind web runtime tools through the shared service binding table (#11395) --- scripts/ci/scopes.mjs | 4 +- src/server/contractToolHandler.ts | 7 +- src/server/createServer.ts | 18 +---- src/server/registerWebNetworkCaptureTool.ts | 64 ----------------- src/server/registerWebRuntimeTools.ts | 71 ------------------- src/server/serviceToolBindings.ts | 54 +++++++++++++- .../mcp/compactInputSchemaMcp.test.ts | 2 +- tests/boundary/mcp/webRuntimeMcp.test.ts | 51 +++++++++++++ 8 files changed, 115 insertions(+), 156 deletions(-) delete mode 100644 src/server/registerWebNetworkCaptureTool.ts delete mode 100644 src/server/registerWebRuntimeTools.ts diff --git a/scripts/ci/scopes.mjs b/scripts/ci/scopes.mjs index 172d7649dd..dcbd8946be 100644 --- a/scripts/ci/scopes.mjs +++ b/scripts/ci/scopes.mjs @@ -552,7 +552,7 @@ const PATH_SCOPES = { "src/application/WebNetworkCapture*", "src/composition/webNetworkCaptures.ts", "src/cli/webNetworkCaptureCommands.ts", - "src/server/registerWebNetworkCaptureTool.ts", + "src/server/serviceToolBindings.ts", "src/server/createServer.ts", "src/server/toolRegistrationOptions.ts", "src/cli.ts", @@ -592,7 +592,7 @@ const PATH_SCOPES = { "src/composition/webRuntime.ts", "src/contracts/webRuntimeToolContracts.ts", "src/contracts/toolEffects.ts", - "src/server/registerWebRuntimeTools.ts", + "src/server/serviceToolBindings.ts", "src/server/createServer.ts", "src/cli/webRuntimeCommands.ts", "src/cli/commandCancellation.ts", diff --git a/src/server/contractToolHandler.ts b/src/server/contractToolHandler.ts index c9bdedf869..86921df6c1 100644 --- a/src/server/contractToolHandler.ts +++ b/src/server/contractToolHandler.ts @@ -136,7 +136,10 @@ export const createRetainedSummaryToolHandler = < )(contract); }; -/** Bind a named Evidence-producing operation to shared logging and delivery. */ +/** + * Bind a named Evidence-producing operation to shared logging and delivery. + * The operation receives the request signal and its MCP progress reporter. + */ export const createEvidenceToolHandler = ( server: EvidenceMcpServer, @@ -155,7 +158,7 @@ export const createEvidenceToolHandler = contract, undefined, { input, context }, - (selected, { signal }) => operation(selected, { signal }), + operation, ); /** One owner for optional-provider admission, execution, recording and delivery. */ diff --git a/src/server/createServer.ts b/src/server/createServer.ts index 2fec03b55f..8dd4e01269 100644 --- a/src/server/createServer.ts +++ b/src/server/createServer.ts @@ -45,8 +45,6 @@ import { registerNativeTools } from "./registerNativeTools.js"; import { registerBrowserScenarioTool } from "./registerBrowserScenarioTool.js"; import { registerBrowserTools } from "./registerBrowserTools.js"; import { registerWebScriptTool } from "./registerWebScriptTool.js"; -import { registerWebRuntimeTools } from "./registerWebRuntimeTools.js"; -import { registerWebNetworkCaptureTool } from "./registerWebNetworkCaptureTool.js"; import { JavaScriptRecoveryService } from "../application/javascript/JavaScriptRecoveryService.js"; import { registerElectronTools } from "./registerElectronTools.js"; import { registerEnhancedTools } from "./registerEnhancedTools.js"; @@ -576,20 +574,10 @@ export const createServer = ( loadFailure: options.optionalProviderLoadFailures?.browserScenarioCapture, }); - registerWebRuntimeTools( + registerServiceTools( server, - webRuntime, - toolLogger, - recordEvidence, - analysisAdmission, - ); - registerWebNetworkCaptureTool( - server, - webNetworkCapture, - toolLogger, - recordEvidence, - analysisAdmission, - evidenceById, + { webRuntime, webNetworkCapture }, + contractTools, ); }, electron: () => diff --git a/src/server/registerWebNetworkCaptureTool.ts b/src/server/registerWebNetworkCaptureTool.ts deleted file mode 100644 index 27c130dfd9..0000000000 --- a/src/server/registerWebNetworkCaptureTool.ts +++ /dev/null @@ -1,64 +0,0 @@ -import type { EvidenceMcpServer } from "./EvidenceMcpServer.js"; -import type { EvidenceLookup } from "../application/EvidenceInputResolver.js"; -import { retainedSummaryDelivery } from "./retainedSummaryDelivery.js"; -import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js"; -import { redactExplicitFailure } from "../domain/explicitSensitiveFailure.js"; -import { captureSensitiveValues } from "../domain/webNetworkCapture.js"; -import { err } from "../domain/result.js"; -import type { WebNetworkCaptureService } from "../application/WebNetworkCaptureService.js"; -import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js"; -import { toolContract } from "../contracts/toolContracts.js"; -import type { Logger } from "pino"; -import type { WithAdmittedAnalysis } from "./analysisAdmission.js"; -import { createEvidenceToolHandler } from "./contractToolHandler.js"; -import { applicationToolRegistrationOptions } from "./toolRegistrationOptions.js"; - -/** Bind historical inspection to its named contract and caller-owned Evidence writer. */ -export const registerWebNetworkCaptureTool = ( - server: EvidenceMcpServer, - service: WebNetworkCaptureService, - logger: Logger, - recordEvidence?: EvidenceWriter["recordEvidence"], - withAdmittedAnalysis?: WithAdmittedAnalysis, - evidenceById?: EvidenceLookup, -): void => { - const contract = toolContract("inspect_web_network_capture"); - const delivery = retainedSummaryDelivery(contract.name, { - recordEvidence, - evidenceById, - }); - const registration = applicationToolRegistrationOptions(contract); - // Keep the exact advertised contract; the shared service validates raw input - // before effects so caller-declared sensitivity also covers invalid arguments. - // SDK pre-validation otherwise emits unprojected issue paths as plain text. - const handler = createEvidenceToolHandler( - server, - async (rawInput, options) => { - const parsed = contract.inputSchema.safeParse(rawInput); - if (!parsed.success) - return err( - redactExplicitFailure( - analysisInputErrorFromIssues( - contract.name, - parsed.error.issues, - rawInput, - { cause: parsed.error }, - ), - captureSensitiveValues(rawInput), - ), - ); - const { detail, ...input } = parsed.data; - const parameters = { detail }; - const ready = delivery.preflight(parameters); - if (!ready.ok) return ready; - const inspected = await service.inspect(input, options); - return inspected.ok - ? delivery.projectEvidence(parameters, inspected.value) - : inspected; - }, - logger, - recordEvidence, - withAdmittedAnalysis, - ); - server.registerTool(contract.name, registration, handler(contract)); -}; diff --git a/src/server/registerWebRuntimeTools.ts b/src/server/registerWebRuntimeTools.ts deleted file mode 100644 index a2b6f506a2..0000000000 --- a/src/server/registerWebRuntimeTools.ts +++ /dev/null @@ -1,71 +0,0 @@ -import type { EvidenceMcpServer } from "./EvidenceMcpServer.js"; - -import type { WebRuntimeService } from "../application/WebRuntimeService.js"; -import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js"; -import { toolContract } from "../contracts/toolContracts.js"; -import type { Logger } from "pino"; -import { mcpProgressReporter } from "./mcpProgress.js"; -import { deliverEvidenceResult } from "./contractToolHandler.js"; -import { logToolExecution } from "./toolLogging.js"; -import { toolRegistrationOptions } from "./toolRegistrationOptions.js"; -import type { WithAdmittedAnalysis } from "./analysisAdmission.js"; -import { runAdmittedToolOperation } from "./admittedToolOperation.js"; - -/** Bind distinct runtime operations to named contracts and the session's Evidence owner. */ -export const registerWebRuntimeTools = ( - server: EvidenceMcpServer, - service: WebRuntimeService, - logger: Logger, - recordEvidence?: EvidenceWriter["recordEvidence"], - withAdmittedAnalysis?: WithAdmittedAnalysis, -): void => { - const execution = toolContract("observe_web_execution"); - const listeners = toolContract("inspect_web_event_listeners"); - server.registerTool( - execution.name, - toolRegistrationOptions(execution), - async (input, context) => - runAdmittedToolOperation( - server, - withAdmittedAnalysis, - execution.name, - context.mcpReq.signal, - async () => { - const result = await logToolExecution(logger, execution.name, () => - service.observe(input, { - signal: context.mcpReq.signal, - progress: mcpProgressReporter(context), - }), - ); - return deliverEvidenceResult( - server, - result, - execution, - recordEvidence, - ); - }, - ), - ); - server.registerTool( - listeners.name, - toolRegistrationOptions(listeners), - async (input, context) => - runAdmittedToolOperation( - server, - withAdmittedAnalysis, - listeners.name, - context.mcpReq.signal, - async () => { - const result = await logToolExecution(logger, listeners.name, () => - service.inspect(input, { signal: context.mcpReq.signal }), - ); - return deliverEvidenceResult( - server, - result, - listeners, - recordEvidence, - ); - }, - ), - ); -}; diff --git a/src/server/serviceToolBindings.ts b/src/server/serviceToolBindings.ts index 87e8ff4ca6..8d7a173c15 100644 --- a/src/server/serviceToolBindings.ts +++ b/src/server/serviceToolBindings.ts @@ -43,7 +43,13 @@ import type { WasmArtifactService } from "../application/wasm/WasmArtifactServic import { compareWasmInterfaces } from "../application/wasm/WasmInterfaceComparisonService.js"; import type { WebModuleTraceService } from "../application/WebModuleTraceService.js"; import type { WebSourceLocationService } from "../application/WebSourceLocationService.js"; -import { ok } from "../domain/result.js"; +import { toolContract } from "../contracts/toolContracts.js"; +import { redactExplicitFailure } from "../domain/explicitSensitiveFailure.js"; +import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js"; +import { err, ok } from "../domain/result.js"; +import { captureSensitiveValues } from "../domain/webNetworkCapture.js"; +import type { WebNetworkCaptureService } from "../application/WebNetworkCaptureService.js"; +import type { WebRuntimeService } from "../application/WebRuntimeService.js"; import { contractServiceBindings, registerContractTools, @@ -51,6 +57,7 @@ import { type ContractToolDependencies, } from "./contractToolBindings.js"; import type { EvidenceMcpServer } from "./EvidenceMcpServer.js"; +import { retainedSummaryDelivery } from "./retainedSummaryDelivery.js"; type Bind = ( service: Service, @@ -351,6 +358,51 @@ const SERVICE_TOOL_BINDINGS = { summary: (input, options) => service.trace(input, options), }, })) satisfies Bind, + webNetworkCapture: ((service, retention) => { + const contract = toolContract("inspect_web_network_capture"); + const delivery = retainedSummaryDelivery(contract.name, retention); + return { + inspect_web_network_capture: { + // The workflow admits the raw request so caller-declared sensitivity + // also covers invalid arguments; SDK admission would emit unprojected + // issue paths as plain text. + admission: "application", + run: async (rawInput, options) => { + const parsed = contract.inputSchema.safeParse(rawInput); + if (!parsed.success) + return err( + redactExplicitFailure( + analysisInputErrorFromIssues( + contract.name, + parsed.error.issues, + rawInput, + { cause: parsed.error }, + ), + captureSensitiveValues(rawInput), + ), + ); + const { detail, ...input } = parsed.data; + const parameters = { detail }; + const ready = delivery.preflight(parameters); + if (!ready.ok) return ready; + const inspected = await service.inspect(input, options); + return inspected.ok + ? delivery.projectEvidence(parameters, inspected.value) + : inspected; + }, + }, + }; + }) satisfies Bind, + webRuntime: ((service) => ({ + observe_web_execution: { + admission: "sdk", + run: (input, options) => service.observe(input, options), + }, + inspect_web_event_listeners: { + admission: "sdk", + run: (input, options) => service.inspect(input, options), + }, + })) satisfies Bind, javascriptRecovery: ((service) => ({ recover_javascript_sources: { admission: "sdk", diff --git a/tests/boundary/mcp/compactInputSchemaMcp.test.ts b/tests/boundary/mcp/compactInputSchemaMcp.test.ts index a2b9ed5ce7..1956918a2f 100644 --- a/tests/boundary/mcp/compactInputSchemaMcp.test.ts +++ b/tests/boundary/mcp/compactInputSchemaMcp.test.ts @@ -414,7 +414,7 @@ describe("MCP compact input schema canonical enforcement", () => { }); it("compacts plain standard schemas that are not Zod instances", async () => { - // Mirrors registerWebNetworkCaptureTool: a plain standard schema reusing + // Mirrors the inspect_web_network_capture binding: a plain standard schema reusing // the advertised projection while owning its own permissive validator. const server = compactServer(); const contract = TOOL_CONTRACTS.find( diff --git a/tests/boundary/mcp/webRuntimeMcp.test.ts b/tests/boundary/mcp/webRuntimeMcp.test.ts index 6950edae10..62af955e07 100644 --- a/tests/boundary/mcp/webRuntimeMcp.test.ts +++ b/tests/boundary/mcp/webRuntimeMcp.test.ts @@ -100,6 +100,57 @@ it("advertises actual SDK schemas, instrumentation effects and session-owned inl }); }); +it("reports provider progress for observe_web_execution to the MCP caller", async () => { + const recording = recordingWebRuntimePort(); + const session = createTestBinarySession(() => { + throw new Error("Binary provider must not start"); + }); + const server = createServer( + { kind: "session", session }, + { + webRuntime: new WebRuntimeService({ + ...recording, + observeExecution: async (input, options) => { + await options?.progress?.report({ + phase: "observe", + completed: 1, + total: 2, + message: "observation window open", + }); + return recording.observeExecution(input, options); + }, + }), + }, + ); + const client = new Client({ name: "web-runtime-progress", version: "1" }); + onTestFinished(async () => { + await client.close(); + await server.close(); + await session.close(); + }); + const [clientTransport, serverTransport] = + InMemoryTransport.createLinkedPair(); + await server.connect(serverTransport); + await client.connect(clientTransport); + const progress: unknown[] = []; + const response = await client.callTool( + { + name: "observe_web_execution", + arguments: { + cdp_endpoint: "http://127.0.0.1:9222", + target_id: "allowed-page", + observation_ms: 5, + }, + }, + { onprogress: (update) => progress.push(update) }, + ); + expect(response.isError).not.toBe(true); + expect(progress).toContainEqual({ + progress: 1, + message: "observe: observation window open", + }); +}); + cliTest( "preserves the same reconstructed runtime identity through compiled CLI and MCP evidence", async ({ cli }) => {