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)
This commit is contained in:
morluto authored and GitHub committed 2026-11-16 03:15:41 +08:00
1 parent d810e11241
commit 4b014fa9ad
8 files changed
+115 -156

No files matched your search

+2 -2
View File
@@ -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",
+5 -2
View File
@@ -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. */
+3 -15
View File
@@ -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: () =>
@@ -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));
};
-71
View File
@@ -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,
);
},
),
);
};
+53 -1
View File
@@ -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: Service,
@@ -351,6 +358,51 @@ const SERVICE_TOOL_BINDINGS = {
summary: (input, options) => service.trace(input, options),
},
})) satisfies Bind<WebSourceLocationService>,
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<WebNetworkCaptureService>,
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<WebRuntimeService>,
javascriptRecovery: ((service) => ({
recover_javascript_sources: {
admission: "sdk",
@@ -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(
+51
View File
@@ -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 }) => {