Files
rea/src/server/registerEnhancedTools.ts
T

387 lines
12 KiB
TypeScript

import type {
EvidenceWriter,
UnknownRegistryPort,
} from "../application/investigation/InvestigationRecordPort.js";
import type {
CallToolResult,
McpServer,
ServerContext,
} from "@modelcontextprotocol/server";
import type { AnalysisOperationPort } from "../application/AnalysisProvider.js";
import type { BinarySessionPort } from "../application/binary/BinarySessionPort.js";
import {
EnhancedTools,
type ValidatedEnhancedCall,
} from "../application/EnhancedTools.js";
import {
createWorkflowEvidence,
workflowSnapshotRecord,
} from "../application/WorkflowEvidence.js";
import { toolContract, type ToolContract } from "../contracts/toolContracts.js";
import type { AnalysisProfileCommitment } from "../domain/analysisProfile.js";
import type { BinaryTarget } from "../domain/binaryTarget.js";
import { UnknownRegistryError } from "../domain/unknownRegistryError.js";
import type { JsonValue } from "../domain/jsonValue.js";
import type { Logger } from "../logger.js";
import { mcpProgressReporter } from "./mcpProgress.js";
import { logToolExecution } from "./toolLogging.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import { toCallToolResult } from "./toolResult.js";
import { executeFunctionAnalysisEvidence } from "../application/FunctionAnalysisEvidence.js";
/** Optional session services used by enhanced tool registration. */
export interface EnhancedToolRegistration {
readonly logger: Logger;
readonly activeTarget: (() => BinaryTarget | undefined) | undefined;
readonly analysisProfile:
| (() => AnalysisProfileCommitment | undefined)
| undefined;
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
readonly recordUnknown: UnknownRegistryPort["recordUnknown"] | undefined;
readonly allowsSnapshotReplay:
| ((operation: ValidatedEnhancedCall["name"]) => boolean)
| undefined;
readonly recordWorkflowSnapshot:
| ((
input: Parameters<BinarySessionPort["recordWorkflowSnapshot"]>[0],
) => ReturnType<BinarySessionPort["recordWorkflowSnapshot"]>)
| undefined;
}
/** Register composed workflows against the same port as direct bridge tools. */
// oxlint-disable-next-line max-lines-per-function -- direct SDK calls retain each schema-handler type correlation.
export const registerEnhancedTools = (
server: McpServer,
analysis: AnalysisOperationPort,
options: EnhancedToolRegistration,
): void => {
const nativeDispatchMetadata = toolContract(
"inspect_native_dispatch_metadata",
);
const objcClasses = toolContract("get_objc_classes");
const objcProtocols = toolContract("get_objc_protocols");
const batchDecompile = toolContract("batch_decompile");
const callGraph = toolContract("get_call_graph");
const swiftTypes = toolContract("analyze_swift_types");
const xrefsToName = toolContract("find_xrefs_to_name");
const binaryOverview = toolContract("binary_overview");
const analyzeFunction = toolContract("analyze_function");
const inspectNativeApi = toolContract("inspect_native_api");
const traceFeature = toolContract("trace_feature");
const traceCallPath = toolContract("trace_call_path");
const traceNativeUiAction = toolContract("trace_native_ui_action");
const traceNativeValues = toolContract("trace_native_values");
server.registerTool(
traceNativeValues.name,
toolRegistrationOptions(traceNativeValues),
(input, context) =>
executeEnhancedTool(analysis, options, traceNativeValues, {
validatedCall: { name: "trace_native_values", input },
context,
}),
);
server.registerTool(
nativeDispatchMetadata.name,
toolRegistrationOptions(nativeDispatchMetadata),
(input, context) =>
executeEnhancedTool(analysis, options, nativeDispatchMetadata, {
validatedCall: { name: "inspect_native_dispatch_metadata", input },
context,
}),
);
server.registerTool(
objcClasses.name,
toolRegistrationOptions(objcClasses),
(input, context) =>
executeEnhancedTool(analysis, options, objcClasses, {
validatedCall: { name: "get_objc_classes", input },
context,
}),
);
server.registerTool(
objcProtocols.name,
toolRegistrationOptions(objcProtocols),
(input, context) =>
executeEnhancedTool(analysis, options, objcProtocols, {
validatedCall: { name: "get_objc_protocols", input },
context,
}),
);
server.registerTool(
batchDecompile.name,
toolRegistrationOptions(batchDecompile),
(input, context) =>
executeEnhancedTool(analysis, options, batchDecompile, {
validatedCall: { name: "batch_decompile", input },
context,
}),
);
server.registerTool(
callGraph.name,
toolRegistrationOptions(callGraph),
(input, context) =>
executeEnhancedTool(analysis, options, callGraph, {
validatedCall: { name: "get_call_graph", input },
context,
}),
);
server.registerTool(
swiftTypes.name,
toolRegistrationOptions(swiftTypes),
(input, context) =>
executeEnhancedTool(analysis, options, swiftTypes, {
validatedCall: { name: "analyze_swift_types", input },
context,
}),
);
server.registerTool(
xrefsToName.name,
toolRegistrationOptions(xrefsToName),
(input, context) =>
executeEnhancedTool(analysis, options, xrefsToName, {
validatedCall: { name: "find_xrefs_to_name", input },
context,
}),
);
server.registerTool(
binaryOverview.name,
toolRegistrationOptions(binaryOverview),
(input, context) =>
executeEnhancedTool(analysis, options, binaryOverview, {
validatedCall: { name: "binary_overview", input },
context,
}),
);
server.registerTool(
analyzeFunction.name,
toolRegistrationOptions(analyzeFunction),
(input, context) =>
executeEnhancedTool(analysis, options, analyzeFunction, {
validatedCall: { name: "analyze_function", input },
context,
}),
);
server.registerTool(
inspectNativeApi.name,
toolRegistrationOptions(inspectNativeApi),
(input, context) =>
executeEnhancedTool(analysis, options, inspectNativeApi, {
validatedCall: { name: "inspect_native_api", input },
context,
}),
);
server.registerTool(
traceFeature.name,
toolRegistrationOptions(traceFeature),
(input, context) =>
executeEnhancedTool(analysis, options, traceFeature, {
validatedCall: { name: "trace_feature", input },
context,
}),
);
server.registerTool(
traceCallPath.name,
toolRegistrationOptions(traceCallPath),
(input, context) =>
executeEnhancedTool(analysis, options, traceCallPath, {
validatedCall: { name: "trace_call_path", input },
context,
}),
);
server.registerTool(
traceNativeUiAction.name,
toolRegistrationOptions(traceNativeUiAction),
(input, context) =>
executeEnhancedTool(analysis, options, traceNativeUiAction, {
validatedCall: { name: "trace_native_ui_action", input },
context,
}),
);
};
const executeEnhancedTool = async (
analysis: AnalysisOperationPort,
registration: EnhancedToolRegistration,
contract: ToolContract,
request: {
readonly validatedCall: ValidatedEnhancedCall;
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 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 toCallToolResult(snapshot, contract);
}
}
const unknowns = recordWorkflowUnknowns({
name,
result: result.value,
evidenceId: evidence.evidence_id,
recordUnknown: registration.recordUnknown,
});
if (!unknowns.ok) return toCallToolResult(unknowns, contract);
return toCallToolResult({ ok: true, value: evidence }, contract);
}
return toCallToolResult(result, contract);
};
const executeFunctionTool = async (
analysis: AnalysisOperationPort,
registration: EnhancedToolRegistration,
contract: ToolContract,
request: {
readonly context: ServerContext;
readonly parameters: Readonly<Record<string, JsonValue>>;
},
): Promise<CallToolResult> => {
const { context, parameters } = request;
const progress = mcpProgressReporter(context);
const result = await logToolExecution(
registration.logger,
"analyze_function",
() =>
executeFunctionAnalysisEvidence(
analysis,
parameters,
registration.activeTarget?.(),
{
signal: context.mcpReq.signal,
progress,
},
),
);
await progress.report({
phase: "analyze_function",
completed: 1,
total: 1,
message: result.ok ? "completed" : "failed",
terminal: true,
});
if (result.ok) {
const recorded = registration.recordEvidence?.(result.value);
if (recorded !== undefined && !recorded.ok)
return toCallToolResult(recorded, contract);
}
return toCallToolResult(result, contract);
};
const jsonParameters = (
input: Readonly<Record<string, JsonValue | undefined>>,
): Record<string, JsonValue> =>
Object.fromEntries(
Object.entries(input).filter(
(entry): entry is [string, JsonValue] => entry[1] !== undefined,
),
);
interface WorkflowUnknownInput {
readonly name: string;
readonly result: JsonValue;
readonly evidenceId: string;
readonly recordUnknown: UnknownRegistryPort["recordUnknown"] | undefined;
}
const recordWorkflowUnknowns = ({
name,
result,
evidenceId,
recordUnknown,
}: WorkflowUnknownInput):
| ReturnType<UnknownRegistryPort["recordUnknown"]>
| { readonly ok: true; readonly value: null } => {
if (
!["trace_feature", "trace_call_path", "inspect_native_api"].includes(
name,
) ||
recordUnknown === undefined ||
typeof result !== "object" ||
result === null ||
Array.isArray(result) ||
!Array.isArray(result.residual_unknowns)
)
return { ok: true, value: null };
for (const question of result.residual_unknowns) {
if (typeof question !== "string") continue;
const recorded = recordUnknown({
question,
severity: "medium",
domain: name === "inspect_native_api" ? "native-api" : "control-flow",
supporting_evidence_ids: [evidenceId],
contradicting_evidence_ids: [],
required_authority: "shipped-artifact",
required_confidence: "observed",
required_environment: null,
recommended_probes: [
{
operation: name,
rationale:
name === "inspect_native_api"
? "Confirm the unsupported boundary with a capable provider or ABI probe."
: "Continue with a focused query or another available provider.",
},
],
relationships: [],
});
if (
!recorded.ok &&
!(
recorded.error instanceof UnknownRegistryError &&
recorded.error.reason === "already-exists"
)
)
return recorded;
}
return { ok: true, value: null };
};