fix(mcp): admit composed analysis through result bookkeeping

This commit is contained in:
morluto
2026-10-10 00:35:17 +08:00
parent e64678e8f9
commit e11f4d371a
80 changed files with 774 additions and 471 deletions
+29
View File
@@ -0,0 +1,29 @@
import type { AnalysisOperationPort } from "../application/AnalysisProvider.js";
import type { BinarySessionPort } from "../application/binary/BinarySessionPort.js";
import type { AnalysisError } from "../domain/analysisErrorBase.js";
import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
import { err, ok, type Result } from "../domain/result.js";
/** Run a provider-backed tool while its target binding stays admitted. */
export type WithAdmittedAnalysis = <Value>(
operationName: string,
signal: AbortSignal | undefined,
operation: (analysis: AnalysisOperationPort) => Promise<Value>,
) => Promise<Result<Value, AnalysisError>>;
/** Select exactly one owner for a server's analysis operation binding. */
export type ServerAnalysisSource =
| { readonly kind: "session"; readonly session: BinarySessionPort }
| { readonly kind: "fixed"; readonly analysis: AnalysisOperationPort };
/** Run against the source's explicit owner, admitting session-scoped work. */
export const withAdmittedAnalysis = (
source: ServerAnalysisSource,
): WithAdmittedAnalysis =>
source.kind === "session"
? (operationName, signal, operation) =>
source.session.withAdmittedAnalysis(operationName, signal, operation)
: async (operationName, signal, operation) =>
signal?.aborted === true
? err(new AnalysisCancelledError(operationName))
: ok(await operation(source.analysis));
+26 -25
View File
@@ -17,7 +17,6 @@ import {
import { parseMcpResponseBudget } from "../config/mcpResponseBudget.js";
import { isAbsolute } from "node:path";
import type { AnalysisOperationPort } from "../application/AnalysisProvider.js";
import type { BinarySessionPort } from "../application/binary/BinarySessionPort.js";
import type { BrowserObservationPort } from "../application/BrowserObservationPort.js";
import type { BrowserScenarioCapturePort } from "../application/BrowserScenarioCapturePort.js";
@@ -68,6 +67,11 @@ import { registerGuidedPrompts } from "./registerPrompts.js";
import { registerSessionTools } from "./registerSessionTools.js";
import type { AvailabilityPolicy } from "../application/CapabilityInventory.js";
import { sessionAvailabilityPolicy } from "./sessionAvailabilityPolicy.js";
import {
withAdmittedAnalysis,
type ServerAnalysisSource,
} from "./analysisAdmission.js";
import type { WithAdmittedAnalysis } from "./analysisAdmission.js";
const TARGET_FREE_INSTRUCTIONS =
"REA provides reverse-engineering tools for local artifacts, native binaries, managed code, browser pages, and runtimes. Use the tool that directly answers the question; discover targets or inspect inventory only when needed. Tool results include inline Evidence and report their coverage and limitations.";
@@ -168,10 +172,11 @@ const createMcpServer = (
* fixed-target seam used by focused tests and embedders.
*/
export const createServer = (
analysis: AnalysisOperationPort,
session?: BinarySessionPort,
source: ServerAnalysisSource,
options: CreateServerOptions = {},
): EvidenceMcpServer => {
const session = source.kind === "session" ? source.session : undefined;
const analysis = source.kind === "session" ? source.session : source.analysis;
const environment = snapshotEnvironment(options.environment ?? process.env);
const delivery = selectToolResultDelivery(environment, options.delivery);
const selectedOptions = { ...options, environment, delivery };
@@ -194,7 +199,6 @@ export const createServer = (
} = createSessionRecorders(server, session);
const toolContext: ServerToolContext = {
server,
analysis,
session,
options: selectedOptions,
environment,
@@ -203,6 +207,7 @@ export const createServer = (
activeTarget,
recordEvidence,
recordEvidenceWithUnknown,
withAdmittedAnalysis: withAdmittedAnalysis(source),
};
registerBinaryAnalysisTools(toolContext);
const previousOnclose = server.server.onclose;
@@ -344,39 +349,34 @@ const createSessionRecorders = (
recordEvidence:
session === undefined
? undefined
: (evidence: Parameters<typeof session.recordEvidence>[0]) => {
const recorded = session.recordEvidence(evidence);
return recorded;
},
: (evidence: Parameters<typeof session.recordEvidence>[0]) =>
session.recordEvidence(evidence),
recordEvidenceWithUnknown:
session === undefined
? undefined
: (
evidence: Parameters<typeof session.recordEvidenceWithUnknown>[0],
input: Parameters<typeof session.recordEvidenceWithUnknown>[1],
) => {
const recorded = session.recordEvidenceWithUnknown(evidence, input);
return recorded;
},
) => session.recordEvidenceWithUnknown(evidence, input),
});
interface ServerToolContext extends ReturnType<typeof createSessionRecorders> {
readonly server: EvidenceMcpServer;
readonly analysis: AnalysisOperationPort;
readonly session: BinarySessionPort | undefined;
readonly options: CreateServerOptions;
readonly environment: Readonly<NodeJS.ProcessEnv>;
readonly logger: Logger;
readonly withAdmittedAnalysis: WithAdmittedAnalysis;
}
const registerBinaryAnalysisTools = ({
server,
analysis,
session,
logger,
activeTarget,
recordEvidence,
recordEvidenceWithUnknown,
withAdmittedAnalysis,
}: ServerToolContext): void => {
const recordUnknown =
session === undefined
@@ -388,9 +388,10 @@ const registerBinaryAnalysisTools = ({
activeTarget,
recordEvidence,
recordUnknown,
withAdmittedAnalysis,
};
registerOfficialTools(server, analysis, analysisOptions);
registerEnhancedTools(server, analysis, {
registerOfficialTools(server, analysisOptions);
registerEnhancedTools(server, {
...analysisOptions,
analysisProfile:
session === undefined ? undefined : () => session.analysisProfile(),
@@ -403,15 +404,15 @@ const registerBinaryAnalysisTools = ({
? undefined
: (input) => session.recordWorkflowSnapshot(input),
});
const evidenceOptions = { logger, activeTarget, recordEvidence };
registerNativeTools(server, analysis, evidenceOptions);
registerArtifactTools(server, analysis, {
...evidenceOptions,
});
registerManagedTools(server, analysis, {
...evidenceOptions,
session,
});
const evidenceOptions = {
logger,
activeTarget,
recordEvidence,
withAdmittedAnalysis,
};
registerNativeTools(server, evidenceOptions);
registerArtifactTools(server, evidenceOptions);
registerManagedTools(server, evidenceOptions);
if (session !== undefined)
registerManagedWorkflowTools(server, {
logger,
+2 -3
View File
@@ -1,7 +1,6 @@
import type { EvidenceMcpServer } from "./EvidenceMcpServer.js";
import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
import type { AnalysisOperationPort } from "../application/AnalysisProvider.js";
import { ARTIFACT_TOOL_CONTRACTS } from "../contracts/artifactToolContracts.js";
import type { BinaryTarget } from "../domain/binaryTargetTypes.js";
import type { Logger } from "pino";
@@ -11,14 +10,14 @@ import { artifactInspectionResultSchema } from "../domain/artifactInspection.js"
/** Register deterministic artifact inventory and safe extraction operations. */
export const registerArtifactTools = (
server: EvidenceMcpServer,
analysis: AnalysisOperationPort,
options: {
readonly logger: Logger;
readonly activeTarget: (() => BinaryTarget | undefined) | undefined;
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
readonly withAdmittedAnalysis: import("./analysisAdmission.js").WithAdmittedAnalysis;
},
): void => {
registerEvidenceTools(server, analysis, ARTIFACT_TOOL_CONTRACTS, {
registerEvidenceTools(server, ARTIFACT_TOOL_CONTRACTS, {
...options,
sourceEvidence: (operation, result) =>
operation === "inspect_artifact"
+9 -7
View File
@@ -22,23 +22,25 @@ export const registerCloseLifecycleTool = ({
const progress = mcpProgressReporter(context);
const snapshotPath = input.snapshot_path;
if (snapshotPath === undefined) {
await reportLifecycleStart(progress, closeContract.name);
const closed = await logToolExecution(logger, closeContract.name, () =>
// Enqueue the lifecycle transition before awaiting progress transport so
// a later open request cannot overtake this close.
const closing = logToolExecution(logger, closeContract.name, () =>
session.close({ progress }),
);
await reportLifecycleStart(progress, closeContract.name);
const closed = await closing;
await reportLifecycleEnd(progress, closeContract.name, closed.ok);
return server.delivery.toCallToolResult(closed, closeContract);
}
const closing = logToolExecution(logger, closeContract.name, () =>
session.closeWithSnapshot(snapshotPath, input.overwrite, { progress }),
);
await reportLifecycleStart(
progress,
closeContract.name,
"saving snapshot; closing provider",
);
const closed = await logToolExecution(logger, closeContract.name, () =>
session.closeWithSnapshot(snapshotPath, input.overwrite, {
progress,
}),
);
const closed = await closing;
await reportLifecycleEnd(progress, closeContract.name, closed.ok);
return server.delivery.toCallToolResult(
closed.ok ? ok({ ...closed.value }) : closed,
+95 -85
View File
@@ -28,9 +28,11 @@ import { mcpProgressReporter } from "./mcpProgress.js";
import { logToolExecution } from "./toolLogging.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import { executeFunctionAnalysisEvidence } from "../application/FunctionAnalysisEvidence.js";
import type { WithAdmittedAnalysis } from "./analysisAdmission.js";
/** Optional session services used by enhanced tool registration. */
export interface EnhancedToolRegistration {
readonly withAdmittedAnalysis: WithAdmittedAnalysis;
readonly logger: Logger;
readonly activeTarget: (() => BinaryTarget | undefined) | undefined;
readonly analysisProfile:
@@ -52,7 +54,6 @@ export interface EnhancedToolRegistration {
// oxlint-disable-next-line max-lines-per-function -- direct SDK calls retain each schema-handler type correlation.
export const registerEnhancedTools = (
server: EvidenceMcpServer,
analysis: AnalysisOperationPort,
options: EnhancedToolRegistration,
): void => {
const registration = { ...options, delivery: server.delivery };
@@ -76,7 +77,7 @@ export const registerEnhancedTools = (
traceNativeValues.name,
toolRegistrationOptions(traceNativeValues),
(input, context) =>
executeEnhancedTool(analysis, registration, traceNativeValues, {
executeEnhancedTool(registration, traceNativeValues, {
validatedCall: { name: "trace_native_values", input },
context,
}),
@@ -85,7 +86,7 @@ export const registerEnhancedTools = (
nativeDispatchMetadata.name,
toolRegistrationOptions(nativeDispatchMetadata),
(input, context) =>
executeEnhancedTool(analysis, registration, nativeDispatchMetadata, {
executeEnhancedTool(registration, nativeDispatchMetadata, {
validatedCall: { name: "inspect_native_dispatch_metadata", input },
context,
}),
@@ -94,7 +95,7 @@ export const registerEnhancedTools = (
objcClasses.name,
toolRegistrationOptions(objcClasses),
(input, context) =>
executeEnhancedTool(analysis, registration, objcClasses, {
executeEnhancedTool(registration, objcClasses, {
validatedCall: { name: "get_objc_classes", input },
context,
}),
@@ -103,7 +104,7 @@ export const registerEnhancedTools = (
objcProtocols.name,
toolRegistrationOptions(objcProtocols),
(input, context) =>
executeEnhancedTool(analysis, registration, objcProtocols, {
executeEnhancedTool(registration, objcProtocols, {
validatedCall: { name: "get_objc_protocols", input },
context,
}),
@@ -112,7 +113,7 @@ export const registerEnhancedTools = (
batchDecompile.name,
toolRegistrationOptions(batchDecompile),
(input, context) =>
executeEnhancedTool(analysis, registration, batchDecompile, {
executeEnhancedTool(registration, batchDecompile, {
validatedCall: { name: "batch_decompile", input },
context,
}),
@@ -121,7 +122,7 @@ export const registerEnhancedTools = (
callGraph.name,
toolRegistrationOptions(callGraph),
(input, context) =>
executeEnhancedTool(analysis, registration, callGraph, {
executeEnhancedTool(registration, callGraph, {
validatedCall: { name: "get_call_graph", input },
context,
}),
@@ -130,7 +131,7 @@ export const registerEnhancedTools = (
swiftTypes.name,
toolRegistrationOptions(swiftTypes),
(input, context) =>
executeEnhancedTool(analysis, registration, swiftTypes, {
executeEnhancedTool(registration, swiftTypes, {
validatedCall: { name: "analyze_swift_types", input },
context,
}),
@@ -139,7 +140,7 @@ export const registerEnhancedTools = (
xrefsToName.name,
toolRegistrationOptions(xrefsToName),
(input, context) =>
executeEnhancedTool(analysis, registration, xrefsToName, {
executeEnhancedTool(registration, xrefsToName, {
validatedCall: { name: "find_xrefs_to_name", input },
context,
}),
@@ -148,7 +149,7 @@ export const registerEnhancedTools = (
binaryOverview.name,
toolRegistrationOptions(binaryOverview),
(input, context) =>
executeEnhancedTool(analysis, registration, binaryOverview, {
executeEnhancedTool(registration, binaryOverview, {
validatedCall: { name: "binary_overview", input },
context,
}),
@@ -157,7 +158,7 @@ export const registerEnhancedTools = (
analyzeFunction.name,
toolRegistrationOptions(analyzeFunction),
(input, context) =>
executeEnhancedTool(analysis, registration, analyzeFunction, {
executeEnhancedTool(registration, analyzeFunction, {
validatedCall: { name: "analyze_function", input },
context,
}),
@@ -166,7 +167,7 @@ export const registerEnhancedTools = (
inspectNativeApi.name,
toolRegistrationOptions(inspectNativeApi),
(input, context) =>
executeEnhancedTool(analysis, registration, inspectNativeApi, {
executeEnhancedTool(registration, inspectNativeApi, {
validatedCall: { name: "inspect_native_api", input },
context,
}),
@@ -175,7 +176,7 @@ export const registerEnhancedTools = (
traceFeature.name,
toolRegistrationOptions(traceFeature),
(input, context) =>
executeEnhancedTool(analysis, registration, traceFeature, {
executeEnhancedTool(registration, traceFeature, {
validatedCall: { name: "trace_feature", input },
context,
}),
@@ -184,7 +185,7 @@ export const registerEnhancedTools = (
traceCallPath.name,
toolRegistrationOptions(traceCallPath),
(input, context) =>
executeEnhancedTool(analysis, registration, traceCallPath, {
executeEnhancedTool(registration, traceCallPath, {
validatedCall: { name: "trace_call_path", input },
context,
}),
@@ -193,7 +194,7 @@ export const registerEnhancedTools = (
traceNativeUiAction.name,
toolRegistrationOptions(traceNativeUiAction),
(input, context) =>
executeEnhancedTool(analysis, registration, traceNativeUiAction, {
executeEnhancedTool(registration, traceNativeUiAction, {
validatedCall: { name: "trace_native_ui_action", input },
context,
}),
@@ -201,7 +202,6 @@ export const registerEnhancedTools = (
};
const executeEnhancedTool = async (
analysis: AnalysisOperationPort,
registration: EnhancedToolRegistration & {
readonly delivery: ToolResultDelivery;
},
@@ -211,76 +211,86 @@ const executeEnhancedTool = async (
readonly context: ServerContext;
},
): Promise<CallToolResult> => {
const { validatedCall, context } = request;
const name = validatedCall.name;
const progress = mcpProgressReporter(context);
await progress.report({
phase: name,
completed: 0,
total: 1,
message: "started",
});
const parsedInput = validatedCall.input;
const parameters = jsonParameters(parsedInput);
if (name === "analyze_function")
return executeFunctionTool(analysis, registration, contract, {
context,
parameters,
});
const services = new EnhancedTools({
execute: (operation, operationParameters, executionOptions) =>
analysis.execute(operation, operationParameters, {
...executionOptions,
progress,
}),
});
const result = await logToolExecution(registration.logger, name, () =>
services.executeValidated(validatedCall, context.mcpReq.signal),
);
await progress.report({
phase: name,
completed: 1,
total: 1,
message: result.ok ? "completed" : "failed",
terminal: true,
});
if (result.ok) {
const evidence = createWorkflowEvidence({
target: registration.activeTarget?.(),
operation: name,
parameters,
result: result.value,
upstreamProfile: registration.analysisProfile?.(),
});
const recorded = registration.recordEvidence?.(evidence);
if (recorded !== undefined && !recorded.ok)
return registration.delivery.toCallToolResult(recorded, contract);
if (
name !== "trace_native_ui_action" &&
registration.allowsSnapshotReplay?.(name) === true
) {
const workflowRecord = workflowSnapshotRecord(evidence, name);
if (workflowRecord !== undefined) {
const snapshot = registration.recordWorkflowSnapshot?.(workflowRecord);
if (snapshot !== undefined && !snapshot.ok)
return registration.delivery.toCallToolResult(snapshot, contract);
const admitted = await registration.withAdmittedAnalysis(
request.validatedCall.name,
request.context.mcpReq.signal,
async (admittedAnalysis) => {
const { validatedCall, context } = request;
const name = validatedCall.name;
const progress = mcpProgressReporter(context);
await progress.report({
phase: name,
completed: 0,
total: 1,
message: "started",
});
const parsedInput = validatedCall.input;
const parameters = jsonParameters(parsedInput);
if (name === "analyze_function")
return executeFunctionTool(admittedAnalysis, registration, contract, {
context,
parameters,
});
const services = new EnhancedTools({
execute: (operation, operationParameters, executionOptions) =>
admittedAnalysis.execute(operation, operationParameters, {
...executionOptions,
progress,
}),
});
const result = await logToolExecution(registration.logger, name, () =>
services.executeValidated(validatedCall, context.mcpReq.signal),
);
await progress.report({
phase: name,
completed: 1,
total: 1,
message: result.ok ? "completed" : "failed",
terminal: true,
});
if (result.ok) {
const evidence = createWorkflowEvidence({
target: registration.activeTarget?.(),
operation: name,
parameters,
result: result.value,
upstreamProfile: registration.analysisProfile?.(),
});
const recorded = registration.recordEvidence?.(evidence);
if (recorded !== undefined && !recorded.ok)
return registration.delivery.toCallToolResult(recorded, contract);
if (
name !== "trace_native_ui_action" &&
registration.allowsSnapshotReplay?.(name) === true
) {
const workflowRecord = workflowSnapshotRecord(evidence, name);
if (workflowRecord !== undefined) {
const snapshot =
registration.recordWorkflowSnapshot?.(workflowRecord);
if (snapshot !== undefined && !snapshot.ok)
return registration.delivery.toCallToolResult(snapshot, contract);
}
}
const unknowns = recordWorkflowUnknowns({
name,
result: result.value,
evidenceId: evidence.evidence_id,
recordUnknown: registration.recordUnknown,
});
if (!unknowns.ok)
return registration.delivery.toCallToolResult(unknowns, contract);
return registration.delivery.toEvidenceToolResult(
evidence,
contract,
recorded,
);
}
}
const unknowns = recordWorkflowUnknowns({
name,
result: result.value,
evidenceId: evidence.evidence_id,
recordUnknown: registration.recordUnknown,
});
if (!unknowns.ok)
return registration.delivery.toCallToolResult(unknowns, contract);
return registration.delivery.toEvidenceToolResult(
evidence,
contract,
recorded,
);
}
return registration.delivery.toCallToolResult(result, contract);
return registration.delivery.toCallToolResult(result, contract);
},
);
return admitted.ok
? admitted.value
: registration.delivery.toCallToolResult(admitted, contract);
};
const executeFunctionTool = async (
+80 -60
View File
@@ -14,11 +14,16 @@ import { mcpProgressReporter } from "./mcpProgress.js";
import { logToolExecution } from "./toolLogging.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import { createArtifactExtractionDestination } from "../application/artifacts/ArtifactExtractionDestination.js";
import type { WithAdmittedAnalysis } from "./analysisAdmission.js";
interface EvidenceToolRegistration {
readonly logger: Logger;
readonly activeTarget: (() => BinaryTarget | undefined) | undefined;
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
readonly withAdmittedAnalysis: WithAdmittedAnalysis;
readonly analysisForAdmission?: (
analysis: AnalysisOperationPort,
) => AnalysisOperationPort;
readonly sourceEvidence?: (
operation: Exclude<AnalysisOperation, "health">,
result: import("../domain/jsonValue.js").JsonValue,
@@ -28,7 +33,6 @@ interface EvidenceToolRegistration {
/** Register provider-backed contracts that return atomic Evidence observations. */
export const registerEvidenceTools = (
server: EvidenceMcpServer,
analysis: AnalysisOperationPort,
contracts: readonly ToolContract<Exclude<AnalysisOperation, "health">>[],
options: EvidenceToolRegistration,
): void => {
@@ -37,68 +41,84 @@ export const registerEvidenceTools = (
contract.name,
toolRegistrationOptions(contract),
async (input, context) => {
const progress = mcpProgressReporter(context);
await progress.report({
phase: contract.name,
completed: 0,
total: 1,
message: "started",
});
const parameters = jsonObjectSchema.parse(input);
const executionParameters =
contract.name === "extract_artifact"
? {
...parameters,
output_root: createArtifactExtractionDestination(),
}
: parameters;
const execution = await logToolExecution(
options.logger,
const admitted = await options.withAdmittedAnalysis(
contract.name,
() =>
analysis.execute(contract.name, executionParameters, {
signal: context.mcpReq.signal,
progress,
}),
);
await progress.report({
phase: contract.name,
completed: 1,
total: 1,
message: execution.ok ? "completed" : "failed",
terminal: true,
});
if (!execution.ok)
return server.delivery.toCallToolResult(execution, contract);
const sourceEvidence =
options.sourceEvidence?.(contract.name, execution.value.result) ?? [];
const evidence = createEvidence(
execution.value.subject ?? options.activeTarget?.(),
execution.value.provider,
{
operation: contract.name,
parameters,
result: execution.value.result,
...(execution.value.analysisProfile === undefined
? {}
: { analysisProfile: execution.value.analysisProfile }),
rawResult: execution.value.rawResult,
limitations: execution.value.limitations,
locations: execution.value.locations,
evidenceLinks: sourceEvidence.map(({ evidence_id: id }) => id),
context.mcpReq.signal,
async (admittedAnalysis) => {
const analysis =
options.analysisForAdmission?.(admittedAnalysis) ??
admittedAnalysis;
const progress = mcpProgressReporter(context);
await progress.report({
phase: contract.name,
completed: 0,
total: 1,
message: "started",
});
const parameters = jsonObjectSchema.parse(input);
const executionParameters =
contract.name === "extract_artifact"
? {
...parameters,
output_root: createArtifactExtractionDestination(),
}
: parameters;
const execution = await logToolExecution(
options.logger,
contract.name,
() =>
analysis.execute(contract.name, executionParameters, {
signal: context.mcpReq.signal,
progress,
}),
);
await progress.report({
phase: contract.name,
completed: 1,
total: 1,
message: execution.ok ? "completed" : "failed",
terminal: true,
});
if (!execution.ok)
return server.delivery.toCallToolResult(execution, contract);
const sourceEvidence =
options.sourceEvidence?.(contract.name, execution.value.result) ??
[];
const evidence = createEvidence(
execution.value.subject ?? options.activeTarget?.(),
execution.value.provider,
{
operation: contract.name,
parameters,
result: execution.value.result,
...(execution.value.analysisProfile === undefined
? {}
: { analysisProfile: execution.value.analysisProfile }),
rawResult: execution.value.rawResult,
limitations: execution.value.limitations,
locations: execution.value.locations,
evidenceLinks: sourceEvidence.map(({ evidence_id: id }) => id),
},
);
for (const source of sourceEvidence) {
const sourceRecorded = options.recordEvidence?.(source);
if (sourceRecorded !== undefined && !sourceRecorded.ok)
return server.delivery.toCallToolResult(
sourceRecorded,
contract,
);
}
const recorded = options.recordEvidence?.(evidence);
return server.delivery.toEvidenceToolResult(
evidence,
contract,
recorded,
);
},
);
for (const source of sourceEvidence) {
const sourceRecorded = options.recordEvidence?.(source);
if (sourceRecorded !== undefined && !sourceRecorded.ok)
return server.delivery.toCallToolResult(sourceRecorded, contract);
}
const recorded = options.recordEvidence?.(evidence);
return server.delivery.toEvidenceToolResult(
evidence,
contract,
recorded,
);
return admitted.ok
? admitted.value
: server.delivery.toCallToolResult(admitted, contract);
},
);
}
+9 -11
View File
@@ -2,7 +2,6 @@ import type { EvidenceMcpServer } from "./EvidenceMcpServer.js";
import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
import type { AnalysisOperationPort } from "../application/AnalysisProvider.js";
import type { BinarySessionPort } from "../application/binary/BinarySessionPort.js";
import { MANAGED_TOOL_CONTRACTS } from "../contracts/managed/managedToolContracts.js";
import type { BinaryTarget } from "../domain/binaryTargetTypes.js";
import { AnalysisInputError } from "../domain/analysisErrorCore.js";
@@ -15,16 +14,17 @@ import { isManagedToolName } from "../contracts/managed/managedToolContracts.js"
/** Register execution-free managed PE/CLI inspection. */
export const registerManagedTools = (
server: EvidenceMcpServer,
analysis: AnalysisOperationPort,
options: {
readonly logger: Logger;
readonly activeTarget: (() => BinaryTarget | undefined) | undefined;
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
readonly session: BinarySessionPort | undefined;
readonly withAdmittedAnalysis: import("./analysisAdmission.js").WithAdmittedAnalysis;
},
): void => {
let selectedManagedPath: string | undefined;
const managedAnalysis: AnalysisOperationPort = {
const analysisForAdmission = (
analysis: AnalysisOperationPort,
): AnalysisOperationPort => ({
execute: async (operation, parameters, executionOptions) => {
if (!isManagedToolName(operation))
return analysis.execute(operation, parameters, executionOptions);
@@ -57,11 +57,9 @@ export const registerManagedTools = (
selectedManagedPath = requestedPath;
return execution;
},
};
registerEvidenceTools(
server,
managedAnalysis,
MANAGED_TOOL_CONTRACTS,
options,
);
});
registerEvidenceTools(server, MANAGED_TOOL_CONTRACTS, {
...options,
analysisForAdmission,
});
};
+5 -5
View File
@@ -1,7 +1,6 @@
import type { EvidenceMcpServer } from "./EvidenceMcpServer.js";
import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
import type { AnalysisOperationPort } from "../application/AnalysisProvider.js";
import { NATIVE_TOOL_CONTRACTS } from "../contracts/native/nativeToolContracts.js";
import type { BinaryTarget } from "../domain/binaryTargetTypes.js";
import type { Logger } from "pino";
@@ -10,12 +9,13 @@ import { registerEvidenceTools } from "./registerEvidenceTools.js";
/** Register provider-neutral static inspection operations. */
export const registerNativeTools = (
server: EvidenceMcpServer,
analysis: AnalysisOperationPort,
options: {
readonly logger: Logger;
readonly activeTarget: (() => BinaryTarget | undefined) | undefined;
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
readonly withAdmittedAnalysis: import("./analysisAdmission.js").WithAdmittedAnalysis;
},
): void => {
registerEvidenceTools(server, analysis, NATIVE_TOOL_CONTRACTS, options);
};
): void =>
registerEvidenceTools(server, NATIVE_TOOL_CONTRACTS, {
...options,
});
+50 -35
View File
@@ -17,77 +17,92 @@ import type { Logger } from "pino";
import { mcpProgressReporter } from "./mcpProgress.js";
import { logToolExecution } from "./toolLogging.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import type { WithAdmittedAnalysis } from "./analysisAdmission.js";
/** Optional session services used by direct tool registration. */
export interface OfficialToolRegistration {
readonly logger: Logger;
readonly activeTarget: (() => BinaryTarget | undefined) | undefined;
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
readonly withAdmittedAnalysis: WithAdmittedAnalysis;
}
/** Register direct bridge proxies, preserving MCP cancellation and typed errors. */
export const registerOfficialTools = (
server: EvidenceMcpServer,
analysis: AnalysisOperationPort,
options: OfficialToolRegistration,
): void => {
for (const contract of OFFICIAL_TOOL_CONTRACTS) {
registerOfficialTool(server, analysis, contract, {
registerOfficialTool(server, contract, {
logger: options.logger,
activeTarget: options.activeTarget,
recordEvidence: options.recordEvidence,
withAdmittedAnalysis: options.withAdmittedAnalysis,
});
}
};
const registerOfficialTool = (
server: EvidenceMcpServer,
analysis: AnalysisOperationPort,
contract: (typeof OFFICIAL_TOOL_CONTRACTS)[number],
registration: {
readonly logger: Logger;
readonly activeTarget: (() => BinaryTarget | undefined) | undefined;
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
readonly withAdmittedAnalysis: WithAdmittedAnalysis;
},
): void => {
server.registerTool(
contract.name,
toolRegistrationOptions(contract),
async (input: unknown, context: ServerContext) => {
const arguments_ = jsonObjectSchema.parse(
contract.inputSchema.parse(input),
);
const progress = mcpProgressReporter(context);
const result = await runOfficialOperation(
analysis,
contract,
arguments_,
{
logger: registration.logger,
signal: context.mcpReq.signal,
progress,
const admitted = await registration.withAdmittedAnalysis(
contract.name,
context.mcpReq.signal,
async (admittedAnalysis) => {
const arguments_ = jsonObjectSchema.parse(
contract.inputSchema.parse(input),
);
const progress = mcpProgressReporter(context);
const result = await runOfficialOperation(
admittedAnalysis,
contract,
arguments_,
{
logger: registration.logger,
signal: context.mcpReq.signal,
progress,
},
);
if (!result.ok) {
return server.delivery.toCallToolResult(result, contract);
}
const evidence = createEvidence(
result.value.subject ?? registration.activeTarget?.(),
result.value.provider,
{
operation: contract.name,
parameters: arguments_,
result: result.value.result,
...(result.value.analysisProfile === undefined
? {}
: { analysisProfile: result.value.analysisProfile }),
rawResult: result.value.rawResult,
limitations: result.value.limitations,
locations: result.value.locations,
},
);
const recorded = registration.recordEvidence?.(evidence);
return server.delivery.toEvidenceToolResult(
evidence,
contract,
recorded,
);
},
);
if (!result.ok) {
return server.delivery.toCallToolResult(result, contract);
}
const evidence = createEvidence(
result.value.subject ?? registration.activeTarget?.(),
result.value.provider,
{
operation: contract.name,
parameters: arguments_,
result: result.value.result,
...(result.value.analysisProfile === undefined
? {}
: { analysisProfile: result.value.analysisProfile }),
rawResult: result.value.rawResult,
limitations: result.value.limitations,
locations: result.value.locations,
},
);
const recorded = registration.recordEvidence?.(evidence);
return server.delivery.toEvidenceToolResult(evidence, contract, recorded);
return admitted.ok
? admitted.value
: server.delivery.toCallToolResult(admitted, contract);
},
);
};
+22 -6
View File
@@ -232,20 +232,36 @@ const registerContextTools = (
navigationContract.name,
toolRegistrationOptions(navigationContract),
async (input, context) => {
return server.delivery.toCallToolResult(
await getNavigationContext(session, input, context.mcpReq.signal),
navigationContract,
const admitted = await session.withAdmittedAnalysis(
navigationContract.name,
context.mcpReq.signal,
async (analysis) =>
server.delivery.toCallToolResult(
await getNavigationContext(analysis, input, context.mcpReq.signal),
navigationContract,
),
);
return admitted.ok
? admitted.value
: server.delivery.toCallToolResult(admitted, navigationContract);
},
);
server.registerTool(
addressContract.name,
toolRegistrationOptions(addressContract),
async (input, context) => {
return server.delivery.toCallToolResult(
await inspectAddressContext(session, input, context.mcpReq.signal),
addressContract,
const admitted = await session.withAdmittedAnalysis(
addressContract.name,
context.mcpReq.signal,
async (analysis) =>
server.delivery.toCallToolResult(
await inspectAddressContext(analysis, input, context.mcpReq.signal),
addressContract,
),
);
return admitted.ok
? admitted.value
: server.delivery.toCallToolResult(admitted, addressContract);
},
);
};