refactor(mcp): simplify tool inputs and inline results

This commit is contained in:
morluto
2026-09-29 11:22:00 +08:00
parent bd0e341572
commit f55c2b9267
70 changed files with 468 additions and 741 deletions
-3
View File
@@ -19,7 +19,6 @@ import {
} from "../domain/permissionPolicy.js";
const RESPONSE_KEY = "process_capture_grant";
const STATE_VERSION = 1;
/** Shared continuation, replay, and round limits for process capture consent. */
export const PROCESS_CAPTURE_ELICITATION_POLICY = {
@@ -41,7 +40,6 @@ Reflect.deleteProperty(grantResponseJsonSchema, "$schema");
Reflect.deleteProperty(grantResponseJsonSchema, "additionalProperties");
const stateSchema = z.strictObject({
version: z.literal(STATE_VERSION),
nonce: z.string().uuid(),
request: z.strictObject({
capability: z.literal("process_capture"),
@@ -130,7 +128,6 @@ export const authorizeProcessCaptureWithElicitation = async (
}
const state = await elicitation.stateCodec.mint({
version: STATE_VERSION,
nonce: randomUUID(),
request: {
capability: "process_capture",
+1 -1
View File
@@ -58,7 +58,7 @@ const TARGET_FREE_INSTRUCTIONS =
"Start with binary_session to see the active target and available providers. For an archive or application package, call open_binary(path), then inspect_artifact for the complete graph and findings; use extract_artifact only for selected files. For standalone JavaScript or ASAR analysis, use analyze_javascript_application. For managed PE/CLI files, use inspect_managed_artifact. For native binaries, open the target and start with binary_overview. For a live page or runtime, discover targets with list_browser_targets, list_electron_targets, or list_javascript_runtime_targets before inspection; scenario capture tools are for controlled interactions.";
const ACTIVE_TARGET_INSTRUCTIONS =
"REA analyzes the active reverse-engineering target. Start native analysis with binary_overview, then use analyze_function, literal search, callers, callees, and xrefs as needed.";
"REA analyzes the active reverse-engineering target. For native binaries, call binary_overview for target metadata and inventory counts, then search_procedures or list_procedures to choose a function and analyze_function with its returned name or address for a complete dossier. Use inspect_native_api when you need to reconstruct a native API boundary, and focused procedure tools when you need only one facet such as assembly, callers, or references.";
export interface CreateServerOptions {
readonly logger?: Logger;
+1 -1
View File
@@ -4,7 +4,7 @@ import type { Evidence } from "../domain/evidence.js";
import type { RecordUnknownInput } from "../domain/residualUnknown.js";
import { ok, type Result } from "../domain/result.js";
/** Atomically record derived Evidence with an optional approved unknown. */
/** Atomically record derived Evidence with an optional supported unknown. */
export const recordDerivedEvidence = (
session: BinarySessionPort,
evidence: Evidence,
@@ -45,9 +45,7 @@ export const registerCompareJavaScriptExportShapesTool = (
options,
contract,
result.value,
parsed.unknown_registry_approved === true && unknown
? "javascript-export-shape"
: undefined,
unknown ? "javascript-export-shape" : undefined,
);
},
);
@@ -42,8 +42,7 @@ export const registerCompareSourceToBundleTool = (
options,
contract,
result.value,
resolved.value.unknown_registry_approved === true &&
comparison.summary.unknown > 0
comparison.summary.unknown > 0
? "source-to-bundle-comparison"
: undefined,
);
@@ -54,9 +54,7 @@ export const registerCompareApplicationVersionsTool = (
options,
compareContract,
result.value,
parsed.unknown_registry_approved === true && unknown
? "application-version-comparison"
: undefined,
unknown ? "application-version-comparison" : undefined,
);
},
);
+4 -2
View File
@@ -75,11 +75,13 @@ const artifactUnknownInput = (
input: {
readonly left_evidence_id: string;
readonly right_evidence_id: string;
readonly unknown_registry_approved?: true | undefined;
},
status: ReturnType<typeof compareArtifacts>["status"],
): RecordUnknownInput | undefined => {
if (input.unknown_registry_approved !== true || status === "unchanged")
if (
status === "unchanged" ||
input.left_evidence_id === input.right_evidence_id
)
return undefined;
return {
question: `Artifact comparison is ${status}`,
+3 -1
View File
@@ -5,6 +5,7 @@ import type { BrowserScenarioCapturePort } from "../application/BrowserScenarioC
import { captureBrowserScenario } from "../application/BrowserScenarioCaptureService.js";
import type { PermissionAuthority } from "../application/PermissionAuthority.js";
import { BROWSER_SCENARIO_TOOL_CONTRACTS } from "../contracts/browserScenarioToolContracts.js";
import { browserScenarioSchema } from "../domain/browserScenario.js";
import type { Logger } from "../logger.js";
import { logToolExecution } from "./toolLogging.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
@@ -27,11 +28,12 @@ export const registerBrowserScenarioTool = (
contract.name,
toolRegistrationOptions(contract),
async (input, context) => {
const scenario = browserScenarioSchema.parse(input);
const result = await logToolExecution(options.logger, contract.name, () =>
captureBrowserScenario(
options.provider,
options.permissionAuthority,
input,
scenario,
{ signal: context.mcpReq.signal },
),
);
-14
View File
@@ -48,7 +48,6 @@ export const registerEnhancedTools = (
options: EnhancedToolRegistration,
): void => {
const [
swiftClasses,
objcClasses,
objcProtocols,
batchDecompile,
@@ -62,15 +61,6 @@ export const registerEnhancedTools = (
codeForString,
traceCallPath,
] = ENHANCED_TOOL_CONTRACTS;
server.registerTool(
swiftClasses.name,
toolRegistrationOptions(swiftClasses),
(input, context) =>
executeEnhancedTool(analysis, options, swiftClasses, {
validatedCall: { name: "swift_classes", input },
context,
}),
);
server.registerTool(
objcClasses.name,
toolRegistrationOptions(objcClasses),
@@ -243,7 +233,6 @@ const executeEnhancedTool = async (
return toCallToolResult(recorded, contract);
const unknowns = recordWorkflowUnknowns({
name,
input: parameters,
result: result.value,
evidenceId: evidence.evidence_id,
recordUnknown: registration.recordUnknown,
@@ -265,7 +254,6 @@ const jsonParameters = (
interface WorkflowUnknownInput {
readonly name: string;
readonly input: Readonly<Record<string, JsonValue>>;
readonly result: JsonValue;
readonly evidenceId: string;
readonly recordUnknown: BinarySessionPort["recordUnknown"] | undefined;
@@ -273,7 +261,6 @@ interface WorkflowUnknownInput {
const recordWorkflowUnknowns = ({
name,
input,
result,
evidenceId,
recordUnknown,
@@ -287,7 +274,6 @@ const recordWorkflowUnknowns = ({
"trace_call_path",
"inspect_native_api",
].includes(name) ||
input.unknown_registry_approved !== true ||
recordUnknown === undefined ||
typeof result !== "object" ||
result === null ||
+1 -4
View File
@@ -67,7 +67,6 @@ export const registerFunctionComparisonTool = (
session,
evidence,
functionUnknownInput({
approved: input.unknown_registry_approved,
status: comparison.status,
leftIds,
rightIds,
@@ -79,17 +78,15 @@ export const registerFunctionComparisonTool = (
};
const functionUnknownInput = ({
approved,
status,
leftIds,
rightIds,
}: {
approved: true | undefined;
status: ReturnType<typeof compareFunctions>["status"];
leftIds: readonly string[];
rightIds: readonly string[];
}): RecordUnknownInput | undefined => {
if (approved !== true || status === "unchanged") return undefined;
if (status === "unchanged") return undefined;
return {
question: `Function comparison is ${status}`,
severity: status === "changed" ? "medium" : "high",
+10 -21
View File
@@ -79,7 +79,6 @@ const registerChangedBehavior = (
const recorded = recordWorkflowEvidence(
session,
evidence,
input.unknown_registry_approved,
isIncomplete(result.behavior_status),
{
question:
@@ -137,7 +136,6 @@ const registerCallPath = (
const recorded = recordWorkflowEvidence(
session,
evidence,
input.unknown_registry_approved,
result.status === "unknown",
{
question:
@@ -198,7 +196,6 @@ const registerStaticRuntime = (
recordWorkflowEvidence(
session,
evidence,
input.unknown_registry_approved,
result.status === "unknown" || result.status === "truncated",
{
question:
@@ -253,24 +250,16 @@ const registerReconstruction = (
evidenceLinks: links,
});
return toCallToolResult(
recordWorkflowEvidence(
session,
evidence,
input.unknown_registry_approved,
result.status === "unknown",
{
question: "Does the reconstruction satisfy every declared claim?",
domain: "reconstruction-verification",
requiredAuthority: null,
requiredConfidence: "derived",
probes: result.recommended_probes.map(
({ operation, rationale }) => ({
operation,
rationale,
}),
),
},
),
recordWorkflowEvidence(session, evidence, result.status === "unknown", {
question: "Does the reconstruction satisfy every declared claim?",
domain: "reconstruction-verification",
requiredAuthority: null,
requiredConfidence: "derived",
probes: result.recommended_probes.map(({ operation, rationale }) => ({
operation,
rationale,
})),
}),
contract,
);
},
@@ -53,15 +53,14 @@ export const evidenceClosure = (
};
export const recordWorkflowEvidence = (
...[session, evidence, approved, unresolved, input]: readonly [
...[session, evidence, unresolved, input]: readonly [
session: BinarySessionPort,
evidence: Evidence,
approved: true | undefined,
unresolved: boolean,
input: WorkflowUnknownInput,
]
): Result<Evidence, AnalysisError> => {
if (approved !== true || !unresolved) {
if (!unresolved) {
return recordDerivedEvidence(session, evidence, undefined);
}
return recordDerivedEvidence(session, evidence, {
@@ -1,4 +1,4 @@
/** Fields used to build an approved residual unknown from a workflow result. */
/** Fields used to build a residual unknown from a workflow result. */
export interface WorkflowUnknownInput {
readonly question: string;
readonly domain: string;
@@ -50,28 +50,27 @@ export const registerCompareManagedMembers = (
result.value.normalized_result,
);
const unknown = comparison.summary.unknown > 0;
const output =
parsed.unknown_registry_approved === true && unknown
? options.recordEvidenceWithUnknown?.(result.value, {
question:
"Which managed members remain unmatched or ambiguous across these versions?",
severity: "medium",
domain: "managed-member-comparison",
supporting_evidence_ids: [result.value.evidence_id],
contradicting_evidence_ids: [],
required_authority: "shipped-artifact",
required_confidence: "observed",
required_environment: null,
recommended_probes: [
{
operation: "inspect_managed_members",
rationale:
"Repeat static member inspection with complete pages and method bodies.",
},
],
relationships: [],
})
: options.recordEvidence?.(result.value);
const output = unknown
? options.recordEvidenceWithUnknown?.(result.value, {
question:
"Which managed members remain unmatched or ambiguous across these versions?",
severity: "medium",
domain: "managed-member-comparison",
supporting_evidence_ids: [result.value.evidence_id],
contradicting_evidence_ids: [],
required_authority: "shipped-artifact",
required_confidence: "observed",
required_environment: null,
recommended_probes: [
{
operation: "inspect_managed_members",
rationale:
"Repeat static member inspection with complete pages and method bodies.",
},
],
relationships: [],
})
: options.recordEvidence?.(result.value);
if (output !== undefined && !output.ok)
return toCallToolResult(output, compareContract);
return toCallToolResult(
@@ -71,33 +71,32 @@ export const registerVerifyManagedNativeBoundaries = (
verification.summary.unresolved > 0 ||
verification.summary.contradicted > 0 ||
verification.summary.native_body_unresolved > 0;
const output =
parsed.unknown_registry_approved === true && unknown
? options.recordEvidenceWithUnknown?.(result.value, {
question:
"Which managed/native boundaries remain unresolved or contradicted by the supplied native Evidence?",
severity: "medium",
domain: "managed-native-verification",
supporting_evidence_ids: [result.value.evidence_id],
contradicting_evidence_ids: [],
required_authority: "shipped-artifact",
required_confidence: "observed",
required_environment: null,
recommended_probes: [
{
operation: "inspect_managed_native_boundaries",
rationale:
"Repeat managed boundary inspection with complete ModuleRef, ImplMap, and native implementation pages.",
},
{
operation: "analyze_function",
rationale:
"Analyze the provider-resolved native function candidate for the declared export.",
},
],
relationships: [],
})
: options.recordEvidence?.(result.value);
const output = unknown
? options.recordEvidenceWithUnknown?.(result.value, {
question:
"Which managed/native boundaries remain unresolved or contradicted by the supplied native Evidence?",
severity: "medium",
domain: "managed-native-verification",
supporting_evidence_ids: [result.value.evidence_id],
contradicting_evidence_ids: [],
required_authority: "shipped-artifact",
required_confidence: "observed",
required_environment: null,
recommended_probes: [
{
operation: "inspect_managed_native_boundaries",
rationale:
"Repeat managed boundary inspection with complete ModuleRef, ImplMap, and native implementation pages.",
},
{
operation: "analyze_function",
rationale:
"Analyze the provider-resolved native function candidate for the declared export.",
},
],
relationships: [],
})
: options.recordEvidence?.(result.value);
if (output !== undefined && !output.ok)
return toCallToolResult(output, nativeVerificationContract);
return toCallToolResult(result, nativeVerificationContract);
+3 -66
View File
@@ -1,4 +1,4 @@
import type { McpServer } from "@modelcontextprotocol/server";
import type { McpServer, ServerContext } from "@modelcontextprotocol/server";
import { z } from "zod";
import type {
@@ -10,11 +10,7 @@ import type { ProgressReporter } from "../application/ProgressReporter.js";
import type { ToolContract } from "../contracts/toolContracts.js";
import { OFFICIAL_TOOL_CONTRACTS } from "../contracts/toolContracts.js";
import type { BinaryTarget } from "../domain/binaryTarget.js";
import {
AnalysisCapabilityUnavailableError,
UnknownRegistryError,
type AnalysisError,
} from "../domain/errors.js";
import type { AnalysisError } from "../domain/errors.js";
import { createEvidence } from "../domain/evidence.js";
import {
jsonObjectSchema,
@@ -33,7 +29,6 @@ export interface OfficialToolRegistration {
readonly logger: Logger;
readonly activeTarget: (() => BinaryTarget | undefined) | undefined;
readonly recordEvidence: BinarySessionPort["recordEvidence"] | undefined;
readonly recordUnknown: BinarySessionPort["recordUnknown"] | undefined;
}
/** Register direct bridge proxies, preserving MCP cancellation and typed errors. */
@@ -47,7 +42,6 @@ export const registerOfficialTools = (
logger: options.logger,
activeTarget: options.activeTarget,
recordEvidence: options.recordEvidence,
recordUnknown: options.recordUnknown,
});
}
};
@@ -60,13 +54,12 @@ const registerOfficialTool = (
readonly logger: Logger;
readonly activeTarget: (() => BinaryTarget | undefined) | undefined;
readonly recordEvidence: BinarySessionPort["recordEvidence"] | undefined;
readonly recordUnknown: BinarySessionPort["recordUnknown"] | undefined;
},
): void => {
server.registerTool(
contract.name,
toolRegistrationOptions(contract),
async (input, context) => {
async (input: unknown, context: ServerContext) => {
const arguments_ = projectOfficialArguments(contract, input);
const progress = mcpProgressReporter(context);
const result = await runOfficialOperation(
@@ -80,14 +73,6 @@ const registerOfficialTool = (
},
);
if (!result.ok) {
const unknownError = recordOfficialUnknown(
input,
result.error,
contract,
registration.recordUnknown,
);
if (unknownError !== undefined)
return toCallToolResult(unknownError, contract);
return toCallToolResult(result, contract);
}
const evidence = createEvidence(
@@ -145,47 +130,6 @@ const runOfficialOperation = async (
return result;
};
const recordOfficialUnknown = (
input: unknown,
error: AnalysisError,
contract: ToolContract,
recordUnknown: BinarySessionPort["recordUnknown"] | undefined,
): Result<never, AnalysisError> | undefined => {
if (
!(error instanceof AnalysisCapabilityUnavailableError) ||
!approvedUnknownTracking(input) ||
recordUnknown === undefined
)
return undefined;
const unknown = recordUnknown({
question: "The requested analysis is unavailable for the current target.",
severity: "medium",
domain: "analysis-capability",
supporting_evidence_ids: [],
contradicting_evidence_ids: [],
required_authority: "shipped-artifact",
required_confidence: "observed",
required_environment: null,
recommended_probes: [
{
operation: contract.name,
rationale:
"Choose another analysis or target that can answer this question.",
},
],
relationships: [],
});
if (
!unknown.ok &&
!(
unknown.error instanceof UnknownRegistryError &&
unknown.error.reason === "already-exists"
)
)
return unknown;
return undefined;
};
const projectOfficialArguments = (
contract: ToolContract,
input: unknown,
@@ -198,14 +142,7 @@ const projectOfficialArguments = (
const projected: Record<string, JsonValue> = {};
for (const key of Object.keys(contract.inputSchema.shape)) {
if (key === "unknown_registry_approved") continue;
projected[key] = jsonValueSchema.parse(parsed[key] ?? null);
}
return projected;
};
const approvedUnknownTracking = (input: unknown): boolean =>
typeof input === "object" &&
input !== null &&
"unknown_registry_approved" in input &&
input.unknown_registry_approved === true;
+1 -6
View File
@@ -124,15 +124,10 @@ const comparisonUnknownInput = (
parsed: {
readonly left_evidence_id: string;
readonly right_evidence_id: string;
readonly unknown_registry_approved?: true | undefined;
},
comparison: ReturnType<typeof compareProcessCaptures>,
): RecordUnknownInput | undefined => {
if (
parsed.unknown_registry_approved !== true ||
comparison.status === "unchanged"
)
return undefined;
if (comparison.status === "unchanged") return undefined;
const differingScopes = [
["terminal", comparison.terminal],
["interaction", comparison.interaction],
-1
View File
@@ -60,7 +60,6 @@ const recordProcessResidualUnknowns = (
evidence: Evidence,
residuals: ProcessCapture["residual_unknowns"],
): Result<null, AnalysisError> => {
if (scenario.unknown_registry_approved !== true) return ok(null);
for (const residual of residuals) {
const unknown = session.recordUnknown({
question: `Was ${residual.scope} behavior fully observed during capture?`,