refactor(mcp): make analysis states unrepresentable (#468)

* refactor(config): parse capability settings into exact states

* refactor(runtime): encode replay and process outcomes exactly

* refactor: make analysis states unrepresentable

* refactor(mcp): register canonical schemas with SDK

* fix: preserve capability and catalog invariants

* fix(build): remove stale compiled modules

* fix(replay): update real verifier policy dependency

* fix(package): verify the complete MCP catalog

* fix(test): supply complete replay reload policy

* refactor(contracts): centralize output schema lookup

* refactor(mcp): delegate protocol boundaries to SDK

* fix(browser): approve real source capture

* fix(mcp): preserve catalog guidance
This commit is contained in:
morluto
2026-08-10 02:28:11 +08:00
committed by GitHub
parent 6901edc05d
commit b8a9da0c0f
271 changed files with 5970 additions and 5699 deletions
-98
View File
@@ -1,98 +0,0 @@
import type { McpServer, RegisteredTool } from "@modelcontextprotocol/server";
import {
buildCapabilityInventory,
type AvailabilityPolicy,
} from "../application/CapabilityInventory.js";
import type { BinarySessionPort } from "../application/BinarySession.js";
import type { ClientFeatureAvailability } from "../contracts/toolOutputSchemaPrimitives.js";
interface ToolAvailabilityController {
/** Apply current session, policy, host, provider, and client availability. */
synchronize(): boolean;
}
/**
* Track public SDK tool handles and keep their visible state synchronized with
* the same availability projection returned by `binary_session`.
*/
export const installDynamicToolAvailability = (
server: McpServer,
session: BinarySessionPort,
policy: () => AvailabilityPolicy,
): ToolAvailabilityController => {
const tools = new Map<string, RegisteredTool>();
const originalRegisterTool = server.registerTool.bind(server);
const originalSendToolListChanged = server.sendToolListChanged.bind(server);
let synchronizing = false;
const controller: ToolAvailabilityController = {
synchronize: () => {
if (synchronizing) return false;
synchronizing = true;
try {
const availability = new Map<string, boolean>(
buildCapabilityInventory(
session.status(),
policy(),
clientFeatures(server),
).map((item) => [item.name, item.available]),
);
let changed = false;
for (const [name, tool] of tools) {
const enabled = availability.get(name) === true;
if (tool.enabled === enabled) continue;
changed = true;
if (enabled) tool.enable();
else tool.disable();
}
return changed;
} finally {
synchronizing = false;
}
},
};
const wrappedRegisterTool = (...args: unknown[]): unknown => {
const name = args[0];
if (typeof name !== "string")
throw new TypeError("MCP tool registration requires a string name");
const registered: unknown = Reflect.apply(
originalRegisterTool,
server,
args,
);
if (!isRegisteredTool(registered))
throw new TypeError(`MCP SDK did not return a tool handle for ${name}`);
tools.set(name, registered);
return registered;
};
if (!Reflect.set(server, "registerTool", wrappedRegisterTool))
throw new TypeError("Unable to install dynamic MCP tool registration");
if (
!Reflect.set(server, "sendToolListChanged", () => {
if (controller.synchronize()) originalSendToolListChanged();
})
)
throw new TypeError("Unable to install dynamic MCP tool notifications");
return controller;
};
const clientFeatures = (server: McpServer): ClientFeatureAvailability => {
const capabilities = server.server.getClientCapabilities();
return {
elicitation_form: capabilities?.elicitation?.form !== undefined,
elicitation_url: capabilities?.elicitation?.url !== undefined,
roots: capabilities?.roots !== undefined,
sampling: capabilities?.sampling !== undefined,
};
};
const isRegisteredTool = (value: unknown): value is RegisteredTool => {
if (typeof value !== "object" || value === null) return false;
return (
typeof Reflect.get(value, "enabled") === "boolean" &&
typeof Reflect.get(value, "enable") === "function" &&
typeof Reflect.get(value, "disable") === "function"
);
};
-181
View File
@@ -1,181 +0,0 @@
import type {
AnyToolHandler,
JsonSchemaValidator,
jsonSchemaValidator,
McpServer,
RegisteredTool,
StandardSchemaWithJSON,
} from "@modelcontextprotocol/server";
import {
fromJsonSchema,
isCallToolResult,
isInputRequiredResult,
} from "@modelcontextprotocol/server";
import { GENERATED_MCP_TOOL_CATALOG } from "../generatedMcpToolCatalog.js";
import type { ToolKind } from "../contracts/toolContractTypes.js";
type HydrateToolRegistrations = (kind: ToolKind) => Promise<void>;
/**
* Advertise the generated MCP catalog immediately and hydrate its callbacks
* through the existing registrars on first execution.
*/
export class LazyToolCatalog {
readonly #server: McpServer;
readonly #hydrateRegistrations: HydrateToolRegistrations;
readonly #includeSessionTools: boolean;
readonly #tools = new Map<string, RegisteredTool>();
readonly #hydrations = new Map<ToolKind, Promise<void>>();
#hydrationQueue: Promise<void> = Promise.resolve();
#closed = false;
constructor(
server: McpServer,
hydrateRegistrations: HydrateToolRegistrations,
includeSessionTools = true,
) {
this.#server = server;
this.#hydrateRegistrations = hydrateRegistrations;
this.#includeSessionTools = includeSessionTools;
}
/** Register every generated tool with a lazy callback. */
register(): void {
for (const contract of GENERATED_MCP_TOOL_CATALOG) {
if (contract.requiresSession && !this.#includeSessionTools) continue;
const inputSchema = advertisedSchema(contract.inputSchema);
const outputSchema = advertisedSchema(contract.outputSchema);
let registered: RegisteredTool | undefined;
const callback: AnyToolHandler<StandardSchemaWithJSON> = async (
input,
context,
) => {
await this.#hydrate(contract.kind);
const handler = registered?.handler;
if (handler === undefined || handler === callback)
throw new Error(`MCP tool ${contract.name} was not hydrated`);
const result: unknown = await Reflect.apply(handler, undefined, [
input,
context,
]);
if (isCallToolResult(result) || isInputRequiredResult(result))
return result;
throw new TypeError(
`MCP tool ${contract.name} returned an invalid result`,
);
};
registered = this.#server.registerTool(
contract.name,
{
title: contract.title,
description: contract.description,
inputSchema,
outputSchema,
annotations: contract.annotations,
},
callback,
);
this.#tools.set(contract.name, registered);
}
}
/** Wait for in-flight hydration and reject future first-use loading. */
async close(): Promise<void> {
this.#closed = true;
await Promise.allSettled(this.#hydrations.values());
}
async #hydrate(kind: ToolKind): Promise<void> {
if (this.#closed) throw new Error("MCP tool catalog is closed");
const existing = this.#hydrations.get(kind);
if (existing !== undefined) {
await existing;
return;
}
const hydration = this.#hydrationQueue
.catch(() => undefined)
.then(() => this.#runHydration(kind));
this.#hydrationQueue = hydration;
this.#hydrations.set(kind, hydration);
try {
await hydration;
} catch (cause: unknown) {
if (this.#hydrations.get(kind) === hydration)
this.#hydrations.delete(kind);
throw cause;
}
}
async #runHydration(kind: ToolKind): Promise<void> {
if (this.#closed) throw new Error("MCP tool catalog is closed");
const expected = GENERATED_MCP_TOOL_CATALOG.filter(
(contract) =>
contract.kind === kind &&
(this.#includeSessionTools || !contract.requiresSession),
).map((contract) => contract.name);
const expectedNames = new Set(expected);
const hydrated = new Set<string>();
const originalRegisterTool = this.#server.registerTool;
const hydrationRegisterTool = (...args: unknown[]): unknown => {
const [name, config, callback] = args;
if (
typeof name !== "string" ||
!isRecord(config) ||
typeof callback !== "function"
)
throw new TypeError("Invalid lazy MCP tool registration");
const registered = this.#tools.get(name);
if (registered === undefined || !expectedNames.has(name))
throw new TypeError(
`MCP tool ${name} is not in the ${kind} catalog family`,
);
if (hydrated.has(name))
throw new TypeError(`MCP tool ${name} was hydrated more than once`);
hydrated.add(name);
Reflect.apply(registered.update, registered, [
{
title: config.title,
description: config.description,
paramsSchema: config.inputSchema,
outputSchema: config.outputSchema,
annotations: config.annotations,
callback,
},
]);
return registered;
};
if (!Reflect.set(this.#server, "registerTool", hydrationRegisterTool))
throw new TypeError("Unable to install lazy MCP tool hydration");
try {
await this.#hydrateRegistrations(kind);
} finally {
Reflect.set(this.#server, "registerTool", originalRegisterTool);
}
const missing = expected.filter((name) => !hydrated.has(name));
if (missing.length > 0)
throw new TypeError(
`Generated MCP tools were not hydrated: ${missing.join(", ")}`,
);
}
}
const advertisedSchema = (
jsonSchema: Readonly<Record<string, unknown>>,
): StandardSchemaWithJSON =>
fromJsonSchema(jsonSchema, DEFERRED_VALIDATION_PROVIDER);
class DeferredValidationProvider implements jsonSchemaValidator {
getValidator<T>(): JsonSchemaValidator<T> {
return (input: unknown) => ({
valid: true,
data: input as T,
errorMessage: undefined,
});
}
}
const DEFERRED_VALIDATION_PROVIDER = new DeferredValidationProvider();
const isRecord = (value: unknown): value is Readonly<Record<string, unknown>> =>
typeof value === "object" && value !== null && !Array.isArray(value);
+6 -4
View File
@@ -6,6 +6,7 @@ import {
inputResponse,
type InputRequiredResult,
type RequestStateCodec,
type ServerContext,
} from "@modelcontextprotocol/server";
import { z } from "zod";
@@ -65,10 +66,11 @@ export interface ProcessCaptureElicitation {
}
interface ProcessCaptureElicitationContext {
readonly mcpReq: {
readonly envelope?: Readonly<Record<string, unknown>>;
readonly inputResponses?: Record<string, unknown>;
readonly requestState: () => unknown;
readonly mcpReq: Pick<
ServerContext["mcpReq"],
"envelope" | "inputResponses"
> & {
readonly requestState: () => ProcessCaptureElicitationState | undefined;
};
}
+184 -151
View File
@@ -5,50 +5,65 @@ import {
createRequestStateCodec,
McpServer,
PROTOCOL_VERSION_META_KEY,
type ServerContext,
} from "@modelcontextprotocol/server";
import type { AnalysisOperationPort } from "../application/AnalysisProvider.js";
import type { BinarySessionPort } from "../application/BinarySession.js";
import { PRODUCT_IDENTITY } from "../identity.js";
import { silentLogger, type Logger } from "../logger.js";
import type { ProcessExecutionPolicy } from "../domain/processCapture.js";
import type { EvidenceFilePolicy } from "../domain/evidenceBundle.js";
import { registerGuidedPrompts } from "./registerPrompts.js";
import { registerEvidenceResources } from "./registerEvidenceResources.js";
import type { PermissionAuthority } from "../application/PermissionAuthority.js";
import type { BrowserObservationPort } from "../application/BrowserObservationPort.js";
import type { BrowserScenarioCapturePort } from "../application/BrowserScenarioCapturePort.js";
import type { ElectronObservationPort } from "../application/ElectronObservationPort.js";
import type { ElectronActiveObservationPort } from "../application/ElectronActiveObservationPort.js";
import type { ElectronObservationPort } from "../application/ElectronObservationPort.js";
import type {
JavaScriptReplayHost,
JavaScriptReplayPolicy,
JavaScriptReplayRunner,
} from "../application/JavaScriptReplayPlanning.js";
import type { JavaScriptRuntimeObservationPort } from "../application/JavaScriptRuntimeObservationPort.js";
import type { ManagedRuntimePolicy } from "../application/ManagedRuntimeCorrelationService.js";
import { MANAGED_RUNTIME_DISABLED } from "../application/ManagedRuntimeCorrelationService.js";
import type { PermissionAuthority } from "../application/PermissionAuthority.js";
import type { EvidenceFilePolicy } from "../domain/evidenceBundle.js";
import type { ProcessExecutionPolicy } from "../domain/processCapture.js";
import { PRODUCT_IDENTITY } from "../identity.js";
import { silentLogger, type Logger } from "../logger.js";
import { LinuxJavaScriptReplayRunner } from "../replay/LinuxJavaScriptReplayRunner.js";
import { SystemJavaScriptReplayHost } from "../replay/SystemJavaScriptReplayHost.js";
import { mcpClientMetadata, mcpEnvelopeValue } from "./mcpClientMetadata.js";
import {
PROCESS_CAPTURE_ELICITATION_POLICY,
type ProcessCaptureElicitationState,
} from "./ProcessCaptureElicitation.js";
import { registerApplicationTools } from "./registerApplicationTools.js";
import { registerArtifactTools } from "./registerArtifactTools.js";
import { registerBrowserScenarioTool } from "./registerBrowserScenarioTool.js";
import { registerBrowserTools } from "./registerBrowserTools.js";
import { registerElectronTools } from "./registerElectronTools.js";
import { registerEnhancedTools } from "./registerEnhancedTools.js";
import { registerEvidenceResources } from "./registerEvidenceResources.js";
import { registerJavaScriptRuntimeObservationTools } from "./registerJavaScriptRuntimeObservationTools.js";
import { registerManagedTools } from "./registerManagedTools.js";
import { registerManagedWorkflowTools } from "./registerManagedWorkflowTools.js";
import { registerNativeTools } from "./registerNativeTools.js";
import { registerOfficialTools } from "./registerOfficialTools.js";
import { registerGuidedPrompts } from "./registerPrompts.js";
import { registerSessionTools } from "./registerSessionTools.js";
import type { SessionAvailability } from "./sessionAvailabilityPolicy.js";
import { sessionAvailabilityPolicy } from "./sessionAvailabilityPolicy.js";
import {
DENY_EVIDENCE_FILE_POLICY,
DENY_PROCESS_POLICY,
} from "./sessionToolPolicies.js";
import { installDynamicToolAvailability } from "./DynamicToolAvailability.js";
const TARGET_FREE_INSTRUCTIONS =
"ASAR/JavaScript -> analyze_javascript_application; archive/package -> open_binary(path), then inspect_artifact/inventory_artifact (active target); managed PE/CLI -> inspect_managed_artifact; browser/Electron -> list_browser_targets/list_electron_targets; approved -> capture_browser_scenario/capture_electron_scenario; Node/Electron Inspector -> list_javascript_runtime_targets; native binary/database -> open_binary, then binary_overview. Start with binary_session; use tools/list; capabilities via binary_session. Use summaries, cite Evidence IDs; Never repeat identical analysis or read full Evidence.";
const ACTIVE_TARGET_INSTRUCTIONS =
"REA analyzes the active reverse-engineering target. Start native analysis with binary_overview, then narrow with analyze_function, literal search, callers, callees, and xrefs. Prefer summary views, never repeat an identical call, and read full Evidence only when the task requires it.";
import type {
JavaScriptReplayHost,
JavaScriptReplayPolicy,
JavaScriptReplayRunner,
} from "../application/JavaScriptReplayPlanning.js";
import type { ManagedRuntimePolicy } from "../application/ManagedRuntimeCorrelationService.js";
import {
PROCESS_CAPTURE_ELICITATION_POLICY,
type ProcessCaptureElicitationState,
} from "./ProcessCaptureElicitation.js";
import { LazyToolCatalog } from "./LazyToolCatalog.js";
export interface CreateServerOptions {
readonly logger?: Logger;
readonly processPolicy?: ProcessExecutionPolicy;
readonly processPolicy?: () => ProcessExecutionPolicy;
readonly evidenceFilePolicy?: EvidenceFilePolicy;
readonly investigationInputRoots?: readonly string[];
readonly analysisSnapshotFilePolicy?: EvidenceFilePolicy;
@@ -59,18 +74,11 @@ export interface CreateServerOptions {
readonly electronActiveObservation?: ElectronActiveObservationPort;
readonly javascriptRuntimeObservation?: JavaScriptRuntimeObservationPort;
readonly artifactIntegrityContinueEnabled?: () => boolean;
readonly javascriptReplayPolicy?: JavaScriptReplayPolicy;
readonly javascriptReplayPolicy?: () => JavaScriptReplayPolicy;
readonly javascriptReplayHost?: JavaScriptReplayHost;
readonly javascriptReplayRunner?: JavaScriptReplayRunner;
readonly managedRuntimePolicy?: ManagedRuntimePolicy;
readonly managedRuntimePolicy?: () => ManagedRuntimePolicy;
readonly availabilityPolicy?: () => SessionAvailability;
readonly loadOptionalProviders?: () => Promise<{
readonly browserObservation: BrowserObservationPort;
readonly browserScenarioCapture: BrowserScenarioCapturePort;
readonly electronObservation: ElectronObservationPort;
readonly electronActiveObservation: ElectronActiveObservationPort;
readonly javascriptRuntimeObservation: JavaScriptRuntimeObservationPort;
}>;
}
const installSessionToolAvailability = (
@@ -80,7 +88,7 @@ const installSessionToolAvailability = (
) => {
if (session === undefined) return undefined;
const policy = sessionAvailabilityPolicy(options.availabilityPolicy, {
processPolicy: options.processPolicy ?? DENY_PROCESS_POLICY,
processPolicy: options.processPolicy?.() ?? DENY_PROCESS_POLICY,
evidenceFilePolicy: options.evidenceFilePolicy ?? DENY_EVIDENCE_FILE_POLICY,
investigationInputRoots: options.investigationInputRoots ?? [],
optionalFeatures: {
@@ -92,13 +100,14 @@ const installSessionToolAvailability = (
options.permissionAuthority !== undefined,
v8InspectorObservationEnabled:
options.javascriptRuntimeObservation !== undefined,
javascriptReplayEnabled: options.javascriptReplayPolicy?.enabled ?? false,
managedRuntimeEnabled: options.managedRuntimePolicy?.enabled ?? false,
javascriptReplayEnabled:
options.javascriptReplayPolicy?.().status === "enabled",
managedRuntimeEnabled:
options.managedRuntimePolicy?.().status === "enabled",
},
});
return {
policy,
controller: installDynamicToolAvailability(server, session, policy),
};
};
@@ -107,9 +116,7 @@ type ProcessCaptureElicitation = {
typeof createRequestStateCodec<ProcessCaptureElicitationState>
>;
readonly supported: (context: {
readonly mcpReq: {
readonly envelope?: Readonly<Record<string, unknown>>;
};
readonly mcpReq: Pick<ServerContext["mcpReq"], "envelope">;
}) => boolean;
readonly now: typeof Date.now;
readonly consumedNonces: Map<string, number>;
@@ -121,8 +128,11 @@ const createProcessCaptureElicitation = (
stateCodec,
supported: (context) => {
const envelope = context.mcpReq.envelope;
const version = envelope?.[PROTOCOL_VERSION_META_KEY];
const capabilities = envelope?.[CLIENT_CAPABILITIES_META_KEY];
const version = mcpEnvelopeValue(envelope, PROTOCOL_VERSION_META_KEY);
const capabilities = mcpEnvelopeValue(
envelope,
CLIENT_CAPABILITIES_META_KEY,
);
return (
typeof version === "string" &&
PROCESS_CAPTURE_ELICITATION_POLICY.protocolVersions.some(
@@ -137,93 +147,6 @@ const createProcessCaptureElicitation = (
consumedNonces: new Map<string, number>(),
});
const createOptionalProviderLoader = (options: CreateServerOptions) => {
let optionalProviders:
| ReturnType<NonNullable<CreateServerOptions["loadOptionalProviders"]>>
| undefined;
return () => {
optionalProviders ??= options
.loadOptionalProviders?.()
.catch((cause: unknown) => {
optionalProviders = undefined;
throw cause;
});
return optionalProviders;
};
};
const createLazyToolCatalog = ({
server,
analysis,
session,
options,
toolLogger,
permissionAuthority,
activeTarget,
recordEvidence,
recordEvidenceWithUnknown,
availabilityPolicy,
startedAt,
processCaptureElicitation,
}: {
readonly server: McpServer;
readonly analysis: AnalysisOperationPort;
readonly session: BinarySessionPort | undefined;
readonly options: CreateServerOptions;
readonly toolLogger: Logger;
readonly permissionAuthority: PermissionAuthority | undefined;
readonly activeTarget: ReturnType<
typeof createSessionRecorders
>["activeTarget"];
readonly recordEvidence: ReturnType<
typeof createSessionRecorders
>["recordEvidence"];
readonly recordEvidenceWithUnknown: ReturnType<
typeof createSessionRecorders
>["recordEvidenceWithUnknown"];
readonly availabilityPolicy: CreateServerOptions["availabilityPolicy"];
readonly startedAt: string;
readonly processCaptureElicitation: ProcessCaptureElicitation;
}): LazyToolCatalog => {
const loadOptionalProviders = createOptionalProviderLoader(options);
return new LazyToolCatalog(
server,
async (kind) => {
const needsObservationProviders =
kind === "browser-provider" ||
kind === "electron-provider" ||
kind === "runtime-provider";
const [{ hydrateServerToolFamily }, loadedOptionalProviders] =
await Promise.all([
import("./hydrateServerTools.js"),
needsObservationProviders ? loadOptionalProviders() : undefined,
]);
const hydratedOptions =
loadedOptionalProviders === undefined
? options
: { ...options, ...loadedOptionalProviders };
await hydrateServerToolFamily({
kind,
server,
analysis,
session,
options: hydratedOptions,
context: {
logger: toolLogger,
permissionAuthority,
activeTarget,
recordEvidence,
recordEvidenceWithUnknown,
availabilityPolicy,
startedAt,
processCaptureElicitation,
},
});
},
session !== undefined,
);
};
const createMcpServer = (
processCaptureStateCodec: ProcessCaptureElicitation["stateCodec"],
session: BinarySessionPort | undefined,
@@ -235,8 +158,7 @@ const createMcpServer = (
},
{
capabilities: {
tools: { listChanged: true },
resources: { listChanged: true, subscribe: true },
resources: { subscribe: true },
},
inputRequired: {
maxRounds: 3,
@@ -270,13 +192,10 @@ export const createServer = (
ttlSeconds: PROCESS_CAPTURE_ELICITATION_POLICY.stateTtlSeconds,
});
const server = createMcpServer(processCaptureStateCodec, session);
const dynamicTools = installSessionToolAvailability(server, session, options);
const availability = installSessionToolAvailability(server, session, options);
server.server.onclose = () => {
permissionAuthority?.clearSessionGrants();
};
if (dynamicTools !== undefined)
server.server.oninitialized = () => server.sendToolListChanged();
session?.onAvailabilityChanged?.(() => server.sendToolListChanged());
registerServerIdentityResource(server, startedAt);
const toolLogger = logger.child({ layer: "server" });
const { activeTarget, recordEvidence, recordEvidenceWithUnknown } =
@@ -284,34 +203,38 @@ export const createServer = (
const processCaptureElicitation = createProcessCaptureElicitation(
processCaptureStateCodec,
);
const lazyTools = createLazyToolCatalog({
const toolContext: ServerToolContext = {
server,
analysis,
session,
options,
toolLogger,
logger: toolLogger,
permissionAuthority,
activeTarget,
recordEvidence,
recordEvidenceWithUnknown,
availabilityPolicy: dynamicTools?.policy,
startedAt,
processCaptureElicitation,
});
lazyTools.register();
};
registerBinaryAnalysisTools(toolContext);
registerObservationTools(toolContext);
registerGuidedPrompts(server, analysis, session);
if (session !== undefined) {
registerEvidenceResources(server, session);
registerSessionTools(server, session, toolLogger, {
...options,
...(availability === undefined
? {}
: { availabilityPolicy: availability.policy }),
...(permissionAuthority === undefined ? {} : { permissionAuthority }),
startedAt,
processCaptureElicitation,
});
}
dynamicTools?.controller.synchronize();
const close = server.close.bind(server);
server.close = async () => {
await lazyTools.close();
await close();
};
return server;
};
const isRecord = (value: unknown): value is Record<string, unknown> =>
typeof value === "object" && value !== null && !Array.isArray(value);
const createSessionRecorders = (
server: McpServer,
session: BinarySessionPort | undefined,
@@ -337,6 +260,120 @@ const createSessionRecorders = (
},
});
interface ServerToolContext extends ReturnType<typeof createSessionRecorders> {
readonly server: McpServer;
readonly analysis: AnalysisOperationPort;
readonly session: BinarySessionPort | undefined;
readonly options: CreateServerOptions;
readonly logger: Logger;
readonly permissionAuthority: PermissionAuthority | undefined;
}
const registerBinaryAnalysisTools = ({
server,
analysis,
session,
options,
logger,
permissionAuthority,
activeTarget,
recordEvidence,
recordEvidenceWithUnknown,
}: ServerToolContext): void => {
const recordUnknown =
session === undefined
? undefined
: (input: Parameters<typeof session.recordUnknown>[0]) =>
session.recordUnknown(input);
const analysisOptions = {
logger,
activeTarget,
recordEvidence,
recordUnknown,
};
registerOfficialTools(server, analysis, analysisOptions);
registerEnhancedTools(server, analysis, {
...analysisOptions,
analysisProfile:
session === undefined ? undefined : () => session.analysisProfile(),
});
const evidenceOptions = { logger, activeTarget, recordEvidence };
registerNativeTools(server, analysis, evidenceOptions);
registerArtifactTools(server, analysis, {
...evidenceOptions,
...(permissionAuthority === undefined ? {} : { permissionAuthority }),
});
registerManagedTools(server, analysis, {
...evidenceOptions,
session,
});
if (session !== undefined)
registerManagedWorkflowTools(server, {
logger,
recordEvidence,
recordEvidenceWithUnknown,
session,
runtime: {
policy:
options.managedRuntimePolicy ?? (() => MANAGED_RUNTIME_DISABLED),
authority: permissionAuthority,
},
});
};
const registerObservationTools = ({
server,
session,
options,
logger,
permissionAuthority,
recordEvidence,
recordEvidenceWithUnknown,
}: ServerToolContext): void => {
const common = { logger, permissionAuthority, recordEvidence };
registerBrowserTools(server, {
...common,
browser: options.browserObservation,
});
registerBrowserScenarioTool(server, {
...common,
provider: options.browserScenarioCapture,
});
registerElectronTools(server, {
...common,
electron: options.electronObservation,
electronActive: options.electronActiveObservation,
});
registerJavaScriptRuntimeObservationTools(server, {
...common,
runtime: options.javascriptRuntimeObservation,
});
registerApplicationTools(server, {
logger,
recordEvidence,
recordEvidenceWithUnknown,
evidenceLookup:
session === undefined
? undefined
: (evidenceId) => session.evidenceById(evidenceId),
evidenceFilePolicy: options.evidenceFilePolicy ?? DENY_EVIDENCE_FILE_POLICY,
permissionAuthority,
retainCoverageWorkspace:
session === undefined
? undefined
: (workspace) =>
session.retainReconstructionCoverageWorkspace(workspace),
replay: {
policy:
options.javascriptReplayPolicy ?? (() => ({ status: "disabled" })),
host: options.javascriptReplayHost ?? new SystemJavaScriptReplayHost(),
runner:
options.javascriptReplayRunner ?? new LinuxJavaScriptReplayRunner(),
authority: permissionAuthority,
},
});
};
const registerServerIdentityResource = (
server: McpServer,
startedAt: string,
@@ -349,10 +386,9 @@ const registerServerIdentityResource = (
description: "Live package, SDK, protocol, and catalog identity.",
mimeType: "application/json",
},
async (uri) => {
async (uri, context) => {
const { createServerIdentity } = await import("../serverIdentity.js");
const client = server.server.getClientVersion();
const protocolVersion = server.server.getNegotiatedProtocolVersion();
const { client, protocolVersion } = mcpClientMetadata(context);
return {
contents: [
{
@@ -373,6 +409,3 @@ const registerServerIdentityResource = (
},
);
};
const isRecord = (value: unknown): value is Record<string, unknown> =>
typeof value === "object" && value !== null && !Array.isArray(value);
-298
View File
@@ -1,298 +0,0 @@
import type { McpServer } from "@modelcontextprotocol/server";
import type { AnalysisOperationPort } from "../application/AnalysisProvider.js";
import type { BinarySessionPort } from "../application/BinarySession.js";
import type { PermissionAuthority } from "../application/PermissionAuthority.js";
import type { BinaryTarget } from "../domain/binaryTarget.js";
import type { Logger } from "../logger.js";
import type { ToolKind } from "../contracts/toolContractTypes.js";
import type { CreateServerOptions } from "./createServer.js";
import type { ProcessCaptureElicitation } from "./ProcessCaptureElicitation.js";
import type { SessionAvailability } from "./sessionAvailabilityPolicy.js";
interface HydratedToolContext {
readonly logger: Logger;
readonly permissionAuthority: PermissionAuthority | undefined;
readonly activeTarget: (() => BinaryTarget | undefined) | undefined;
readonly recordEvidence: BinarySessionPort["recordEvidence"] | undefined;
readonly recordEvidenceWithUnknown:
| BinarySessionPort["recordEvidenceWithUnknown"]
| undefined;
readonly availabilityPolicy: (() => SessionAvailability) | undefined;
readonly startedAt: string;
readonly processCaptureElicitation: ProcessCaptureElicitation;
}
export interface HydrateServerToolFamilyInput {
readonly kind: ToolKind;
readonly server: McpServer;
readonly analysis: AnalysisOperationPort;
readonly session: BinarySessionPort | undefined;
readonly options: CreateServerOptions;
readonly context: HydratedToolContext;
}
/**
* Install production callbacks on generated lazy tool registrations.
*/
export const hydrateServerToolFamily = async ({
kind,
server,
analysis,
session,
options,
context,
}: HydrateServerToolFamilyInput): Promise<void> => {
const toolContext = {
server,
analysis,
session,
options,
logger: context.logger,
permissionAuthority: context.permissionAuthority,
activeTarget: context.activeTarget,
recordEvidence: context.recordEvidence,
recordEvidenceWithUnknown: context.recordEvidenceWithUnknown,
};
switch (kind) {
case "official-proxy": {
const { registerOfficialTools } = await import(
"./registerOfficialTools.js"
);
registerOfficialTools(server, analysis, analysisOptions(toolContext));
return;
}
case "enhanced": {
const { registerEnhancedTools } = await import(
"./registerEnhancedTools.js"
);
registerEnhancedTools(server, analysis, enhancedOptions(toolContext));
return;
}
case "native-provider": {
const { registerNativeTools } = await import("./registerNativeTools.js");
registerNativeTools(server, analysis, evidenceOptions(toolContext));
return;
}
case "artifact-provider": {
const { registerArtifactTools } = await import(
"./registerArtifactTools.js"
);
registerArtifactTools(server, analysis, {
...evidenceOptions(toolContext),
...(context.permissionAuthority === undefined
? {}
: { permissionAuthority: context.permissionAuthority }),
});
return;
}
case "managed-provider": {
const { registerManagedTools } = await import(
"./registerManagedTools.js"
);
registerManagedTools(server, analysis, {
...evidenceOptions(toolContext),
session,
});
return;
}
case "application":
await registerApplicationFamily(toolContext);
return;
case "browser-provider":
case "electron-provider":
case "runtime-provider": {
await hydrateObservationFamily(kind, toolContext);
return;
}
case "session": {
if (session === undefined)
throw new TypeError("Session tools require a binary session");
const { registerSessionTools } = await import(
"./registerSessionTools.js"
);
registerSessionTools(server, session, context.logger, {
...options,
...(context.availabilityPolicy === undefined
? {}
: { availabilityPolicy: context.availabilityPolicy }),
...(context.permissionAuthority === undefined
? {}
: { permissionAuthority: context.permissionAuthority }),
startedAt: context.startedAt,
processCaptureElicitation: context.processCaptureElicitation,
});
}
}
};
const hydrateObservationFamily = async (
kind: "browser-provider" | "electron-provider" | "runtime-provider",
context: ServerToolContext,
): Promise<void> => {
const common = {
logger: context.logger,
permissionAuthority: context.permissionAuthority,
recordEvidence: context.recordEvidence,
};
if (kind === "browser-provider") {
const [{ registerBrowserTools }, { registerBrowserScenarioTool }] =
await Promise.all([
import("./registerBrowserTools.js"),
import("./registerBrowserScenarioTool.js"),
]);
registerBrowserTools(context.server, {
...common,
browser: context.options.browserObservation,
});
registerBrowserScenarioTool(context.server, {
...common,
provider: context.options.browserScenarioCapture,
});
return;
}
if (kind === "electron-provider") {
const { registerElectronTools } = await import(
"./registerElectronTools.js"
);
registerElectronTools(context.server, {
...common,
electron: context.options.electronObservation,
electronActive: context.options.electronActiveObservation,
});
return;
}
const { registerJavaScriptRuntimeObservationTools } = await import(
"./registerJavaScriptRuntimeObservationTools.js"
);
registerJavaScriptRuntimeObservationTools(context.server, {
...common,
runtime: context.options.javascriptRuntimeObservation,
});
};
interface ServerToolContext {
readonly server: McpServer;
readonly analysis: AnalysisOperationPort;
readonly session: BinarySessionPort | undefined;
readonly options: CreateServerOptions;
readonly logger: Logger;
readonly permissionAuthority: PermissionAuthority | undefined;
readonly activeTarget: (() => BinaryTarget | undefined) | undefined;
readonly recordEvidence: BinarySessionPort["recordEvidence"] | undefined;
readonly recordEvidenceWithUnknown:
| BinarySessionPort["recordEvidenceWithUnknown"]
| undefined;
}
const analysisOptions = ({
logger,
activeTarget,
recordEvidence,
session,
}: ServerToolContext) => {
const recordUnknown =
session === undefined
? undefined
: (input: Parameters<typeof session.recordUnknown>[0]) =>
session.recordUnknown(input);
return {
logger,
activeTarget,
recordEvidence,
recordUnknown,
};
};
const enhancedOptions = (context: ServerToolContext) => ({
...analysisOptions(context),
analysisProfile:
context.session === undefined
? undefined
: () => context.session?.analysisProfile(),
});
const evidenceOptions = ({
logger,
activeTarget,
recordEvidence,
}: ServerToolContext) => ({
logger,
activeTarget,
recordEvidence,
});
const registerApplicationFamily = async ({
server,
session,
options,
logger,
permissionAuthority,
recordEvidence,
recordEvidenceWithUnknown,
}: ServerToolContext): Promise<void> => {
const [
{ registerApplicationTools },
{ registerManagedWorkflowTools },
{ LinuxJavaScriptReplayRunner },
{ SystemJavaScriptReplayHost },
] = await Promise.all([
import("./registerApplicationTools.js"),
import("./registerManagedWorkflowTools.js"),
import("../replay/LinuxJavaScriptReplayRunner.js"),
import("../replay/SystemJavaScriptReplayHost.js"),
]);
if (session !== undefined)
registerManagedWorkflowTools(server, {
logger,
recordEvidence,
recordEvidenceWithUnknown,
session,
runtime: {
policy: options.managedRuntimePolicy ?? {
enabled: false,
roots: [],
executablePath: "/usr/bin/dotnet",
},
authority: permissionAuthority,
},
});
registerApplicationTools(server, {
logger,
recordEvidence,
recordEvidenceWithUnknown,
evidenceLookup:
session === undefined
? undefined
: (evidenceId) => session.evidenceById(evidenceId),
evidenceFilePolicy: options.evidenceFilePolicy ?? {
roots: [],
maxBytes: 1,
maxDepth: 1,
maxStringLength: 1,
maxNodes: 1,
},
permissionAuthority,
retainCoverageWorkspace:
session === undefined
? undefined
: (workspace) => {
return session.retainReconstructionCoverageWorkspace(workspace);
},
replay: {
policy: options.javascriptReplayPolicy ?? {
enabled: false,
roots: [],
nodePath: process.execPath,
bubblewrapPath: "/usr/bin/bwrap",
systemdRunPath: "/usr/bin/systemd-run",
systemctlPath: "/usr/bin/systemctl",
shellPath: "/usr/bin/bash",
},
host: options.javascriptReplayHost ?? new SystemJavaScriptReplayHost(),
runner:
options.javascriptReplayRunner ?? new LinuxJavaScriptReplayRunner(),
authority: permissionAuthority,
},
});
};
+56
View File
@@ -0,0 +1,56 @@
import {
CLIENT_CAPABILITIES_META_KEY,
CLIENT_INFO_META_KEY,
PROTOCOL_VERSION_META_KEY,
type ServerContext,
} from "@modelcontextprotocol/server";
import type { ClientFeatureAvailability } from "../contracts/toolOutputSchemaPrimitives.js";
import type { ConnectedClientIdentity } from "../serverIdentity.js";
/** Client metadata bound to the current SDK request rather than server-global state. */
export const mcpClientMetadata = (context: {
readonly mcpReq: Pick<ServerContext["mcpReq"], "envelope">;
}) => {
const envelope = context.mcpReq.envelope;
const client = implementation(
mcpEnvelopeValue(envelope, CLIENT_INFO_META_KEY),
);
const protocolVersion = mcpEnvelopeValue(envelope, PROTOCOL_VERSION_META_KEY);
return {
...(client === undefined ? {} : { client }),
clientFeatures: capabilityFeatures(
mcpEnvelopeValue(envelope, CLIENT_CAPABILITIES_META_KEY),
),
...(typeof protocolVersion === "string" ? { protocolVersion } : {}),
};
};
/** Read an SDK-defined metadata key from the SDK's currently opaque envelope type. */
export const mcpEnvelopeValue = (
envelope: ServerContext["mcpReq"]["envelope"],
key: string,
): unknown => (envelope === undefined ? undefined : Reflect.get(envelope, key));
const implementation = (value: unknown): ConnectedClientIdentity | undefined =>
isRecord(value) &&
typeof value.name === "string" &&
typeof value.version === "string"
? { name: value.name, version: value.version }
: undefined;
const capabilityFeatures = (value: unknown): ClientFeatureAvailability => {
const capabilities = isRecord(value) ? value : {};
const elicitation = isRecord(capabilities.elicitation)
? capabilities.elicitation
: {};
return {
elicitation_form: elicitation.form !== undefined,
elicitation_url: elicitation.url !== undefined,
roots: capabilities.roots !== undefined,
sampling: capabilities.sampling !== undefined,
};
};
const isRecord = (value: unknown): value is Record<string, unknown> =>
typeof value === "object" && value !== null && !Array.isArray(value);
+3 -13
View File
@@ -1,22 +1,12 @@
import type { ServerContext } from "@modelcontextprotocol/server";
import type { ProgressReporter } from "../application/ProgressReporter.js";
import {
createProgressReporter,
silentProgressReporter,
} from "../application/ProgressReporter.js";
interface McpProgressContext {
readonly mcpReq: {
readonly _meta?: { readonly progressToken?: string | number | undefined };
notify(notification: {
readonly method: "notifications/progress";
readonly params: {
readonly progressToken: string | number;
readonly progress: number;
readonly total?: number;
readonly message?: string;
};
}): Promise<void>;
};
export interface McpProgressContext {
readonly mcpReq: Pick<ServerContext["mcpReq"], "_meta" | "notify">;
}
/** Adapt the request's negotiated MCP progress token to application progress. */
@@ -5,18 +5,15 @@ import {
prepareNodeCharacterization,
} from "../../application/NodeRuntimeCharacterizationService.js";
import { applicationToolContract } from "../../contracts/applicationToolContracts.js";
import { parseEvidence } from "../../domain/evidence.js";
import {
nodeCharacterizationExecutionInputSchema,
nodeCharacterizationExecutionOutputSchema,
nodeCharacterizationPreparationInputSchema,
nodeCharacterizationPreparationOutputSchema,
} from "../../domain/nodeRuntimeCharacterization.js";
import { parseEvidence } from "../../domain/evidence.js";
import { logToolExecution } from "../toolLogging.js";
import { toCallToolResult } from "../toolResult.js";
import { toolRegistrationOptions } from "../toolRegistrationOptions.js";
import { safeParseToolInput } from "../toolInputValidation.js";
import { mcpProgressReporter } from "../mcpProgress.js";
import { logToolExecution } from "../toolLogging.js";
import { toolRegistrationOptions } from "../toolRegistrationOptions.js";
import { toCallToolResult } from "../toolResult.js";
import { recordSources } from "./helpers.js";
import type { ApplicationToolRegistration } from "./types.js";
@@ -36,17 +33,11 @@ export const registerCharacterizationTools = (
prepareContract.name,
toolRegistrationOptions(prepareContract),
async (input, context) => {
const parsed = safeParseToolInput(
nodeCharacterizationPreparationInputSchema,
input,
prepareContract.name,
);
if (!parsed.ok) return toCallToolResult(parsed, prepareContract);
const result = await logToolExecution(
options.logger,
prepareContract.name,
() =>
prepareNodeCharacterization(options.replay, parsed.value, {
prepareNodeCharacterization(options.replay, input, {
signal: context.mcpReq.signal,
progress: mcpProgressReporter(context),
}),
@@ -69,17 +60,11 @@ export const registerCharacterizationTools = (
executeContract.name,
toolRegistrationOptions(executeContract),
async (input, context) => {
const parsed = safeParseToolInput(
nodeCharacterizationExecutionInputSchema,
input,
executeContract.name,
);
if (!parsed.ok) return toCallToolResult(parsed, executeContract);
const result = await logToolExecution(
options.logger,
executeContract.name,
() =>
executeNodeCharacterization(options.replay, parsed.value, {
executeNodeCharacterization(options.replay, input, {
signal: context.mcpReq.signal,
progress: mcpProgressReporter(context),
}),
@@ -91,7 +76,7 @@ export const registerCharacterizationTools = (
const sources = [
output.transformation_evidence,
...output.replay.source_evidence,
...(output.replay.evidence === null ? [] : [output.replay.evidence]),
output.replay.evidence,
output.evidence,
].map((item) => parseEvidence(item));
const recorded = recordSources(options.recordEvidence, sources);
@@ -3,12 +3,10 @@ import type { McpServer } from "@modelcontextprotocol/server";
import { resolveCompareJavaScriptExportShapesRequestValidated } from "../../application/ApplicationWorkflowEvidenceResolver.js";
import { compareJavaScriptExportShapesEvidenceValidated } from "../../application/JavaScriptApplicationWorkflowService.js";
import { applicationToolContract } from "../../contracts/applicationToolContracts.js";
import { compareJavaScriptExportShapesRequestSchema } from "../../contracts/applicationWorkflowInputContracts.js";
import { javaScriptExportShapeComparisonResultSchema } from "../../domain/javascriptExportShapeComparisonSchemas.js";
import { safeParseToolInput } from "../toolInputValidation.js";
import { logToolExecution } from "../toolLogging.js";
import { toCallToolResult } from "../toolResult.js";
import { toolRegistrationOptions } from "../toolRegistrationOptions.js";
import { toCallToolResult } from "../toolResult.js";
import { recordResult, recordSources } from "./helpers.js";
import type { ApplicationToolRegistration } from "./types.js";
@@ -23,14 +21,8 @@ export const registerCompareJavaScriptExportShapesTool = (
contract.name,
toolRegistrationOptions(contract),
async (input) => {
const parsedInput = safeParseToolInput(
compareJavaScriptExportShapesRequestSchema,
input,
contract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, contract);
const resolved = resolveCompareJavaScriptExportShapesRequestValidated(
parsedInput.value,
input,
options.evidenceLookup,
);
if (!resolved.ok) return toCallToolResult(resolved, contract);
@@ -1,12 +1,10 @@
import type { McpServer } from "@modelcontextprotocol/server";
import { compareSourceToBundleEvidenceValidated } from "../../application/JavaScriptApplicationWorkflowService.js";
import { resolveCompareSourceToBundleRequestValidated } from "../../application/ApplicationWorkflowEvidenceResolver.js";
import { compareSourceToBundleEvidenceValidated } from "../../application/JavaScriptApplicationWorkflowService.js";
import { applicationToolContract } from "../../contracts/applicationToolContracts.js";
import { compareSourceToBundleRequestSchema } from "../../contracts/applicationWorkflowInputContracts.js";
import { sourceToBundleComparisonResultSchema } from "../../domain/sourceToBundleComparisonSchemas.js";
import { logToolExecution } from "../toolLogging.js";
import { safeParseToolInput } from "../toolInputValidation.js";
import { toolRegistrationOptions } from "../toolRegistrationOptions.js";
import { toCallToolResult } from "../toolResult.js";
import { recordResult, recordSources } from "./helpers.js";
@@ -23,14 +21,8 @@ export const registerCompareSourceToBundleTool = (
contract.name,
toolRegistrationOptions(contract),
async (input) => {
const parsedInput = safeParseToolInput(
compareSourceToBundleRequestSchema,
input,
contract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, contract);
const resolved = resolveCompareSourceToBundleRequestValidated(
parsedInput.value,
input,
options.evidenceLookup,
);
if (!resolved.ok) return toCallToolResult(resolved, contract);
@@ -1,14 +1,12 @@
import type { McpServer } from "@modelcontextprotocol/server";
import { compareApplicationVersionsEvidenceValidated } from "../../application/JavaScriptApplicationWorkflowService.js";
import { resolveCompareApplicationVersionsRequestValidated } from "../../application/ApplicationWorkflowEvidenceResolver.js";
import { compareApplicationVersionsEvidenceValidated } from "../../application/JavaScriptApplicationWorkflowService.js";
import { applicationToolContract } from "../../contracts/applicationToolContracts.js";
import { compareApplicationVersionsRequestSchema } from "../../contracts/applicationWorkflowInputContracts.js";
import { applicationVersionComparisonResultSchema } from "../../domain/javascriptApplicationVersionComparisonSchemas.js";
import { logToolExecution } from "../toolLogging.js";
import { toCallToolResult } from "../toolResult.js";
import { toolRegistrationOptions } from "../toolRegistrationOptions.js";
import { safeParseToolInput } from "../toolInputValidation.js";
import { toCallToolResult } from "../toolResult.js";
import { recordResult, recordSources } from "./helpers.js";
import type { ApplicationToolRegistration } from "./types.js";
@@ -23,15 +21,8 @@ export const registerCompareApplicationVersionsTool = (
compareContract.name,
toolRegistrationOptions(compareContract),
async (input) => {
const parsedInput = safeParseToolInput(
compareApplicationVersionsRequestSchema,
input,
compareContract.name,
);
if (!parsedInput.ok)
return toCallToolResult(parsedInput, compareContract);
const resolved = resolveCompareApplicationVersionsRequestValidated(
parsedInput.value,
input,
options.evidenceLookup,
);
if (!resolved.ok) return toCallToolResult(resolved, compareContract);
@@ -2,16 +2,12 @@ import type { McpServer } from "@modelcontextprotocol/server";
import { runControlledReplayValidated } from "../../application/JavaScriptReplayService.js";
import { applicationToolContract } from "../../contracts/applicationToolContracts.js";
import {
controlledReplayInputSchema,
controlledReplayOutputSchema,
} from "../../domain/javascriptReplay.js";
import { parseEvidence } from "../../domain/evidence.js";
import { logToolExecution } from "../toolLogging.js";
import { toCallToolResult } from "../toolResult.js";
import { toolRegistrationOptions } from "../toolRegistrationOptions.js";
import { safeParseToolInput } from "../toolInputValidation.js";
import { controlledReplayOutputSchema } from "../../domain/javascriptReplay.js";
import { mcpProgressReporter } from "../mcpProgress.js";
import { logToolExecution } from "../toolLogging.js";
import { toolRegistrationOptions } from "../toolRegistrationOptions.js";
import { toCallToolResult } from "../toolResult.js";
import { recordSources } from "./helpers.js";
import type { ApplicationToolRegistration } from "./types.js";
@@ -26,25 +22,18 @@ export const registerControlledReplayTool = (
replayContract.name,
toolRegistrationOptions(replayContract),
async (input, context) => {
const parsedInput = safeParseToolInput(
controlledReplayInputSchema,
input,
replayContract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, replayContract);
const parsed = parsedInput.value;
const result = await logToolExecution(
options.logger,
replayContract.name,
() =>
runControlledReplayValidated(options.replay, parsed, {
runControlledReplayValidated(options.replay, input, {
signal: context.mcpReq.signal,
progress: mcpProgressReporter(context),
}),
);
if (!result.ok) return toCallToolResult(result, replayContract);
const output = controlledReplayOutputSchema.parse(result.value);
if (output.evidence !== null) {
if (output.phase === "execute") {
const sourcesRecorded = recordSources(
options.recordEvidence,
output.source_evidence.map((item) => parseEvidence(item)),
@@ -59,7 +48,7 @@ export const registerControlledReplayTool = (
}
return toCallToolResult(result, replayContract, {
evidenceResourcesAvailable:
output.evidence !== null && options.recordEvidence !== undefined,
output.phase === "execute" && options.recordEvidence !== undefined,
});
},
);
+16 -35
View File
@@ -1,29 +1,24 @@
import type { McpServer } from "@modelcontextprotocol/server";
import {
authorizeFileReadWithDeferredWrite,
authorizeRootPermission,
} from "../../application/DeferredFileAuthorization.js";
import {
commitReconstructionCoverage,
queryReconstructionCoverage,
} from "../../application/ReconstructionCoverageService.js";
import { readReconstructionCoverageWorkspace } from "../../application/ReconstructionCoverageWorkspaceStore.js";
import {
authorizeFileReadWithDeferredWrite,
authorizeRootPermission,
} from "../../application/DeferredFileAuthorization.js";
import { applicationToolContract } from "../../contracts/applicationToolContracts.js";
import {
reconstructionCoverageCommitInputSchema,
reconstructionCoverageQueryInputSchema,
} from "../../application/ReconstructionCoverageService.js";
import { reconstructionClosureResultSchema } from "../../domain/reconstructionCoverage.js";
import {
AnalysisCapabilityUnavailableError,
EvidenceIntegrityError,
} from "../../domain/errors.js";
import { reconstructionClosureResultSchema } from "../../domain/reconstructionCoverage.js";
import { err } from "../../domain/result.js";
import { logToolExecution } from "../toolLogging.js";
import { toCallToolResult } from "../toolResult.js";
import { toolRegistrationOptions } from "../toolRegistrationOptions.js";
import { safeParseToolInput } from "../toolInputValidation.js";
import { toCallToolResult } from "../toolResult.js";
import { coverageWorkspaceUri } from "./helpers.js";
import type { ApplicationToolRegistration } from "./types.js";
@@ -49,12 +44,6 @@ const registerCommitTool = (
commitContract.name,
toolRegistrationOptions(commitContract),
async (input, context) => {
const parsed = safeParseToolInput(
reconstructionCoverageCommitInputSchema,
input,
commitContract.name,
);
if (!parsed.ok) return toCallToolResult(parsed, commitContract);
if (options.permissionAuthority === undefined)
return toCallToolResult(
err(
@@ -69,7 +58,7 @@ const registerCommitTool = (
const authorization = await authorizeFileReadWithDeferredWrite(
options.permissionAuthority,
{
path: parsed.value.workspace_path,
path: input.workspace_path,
readCapability: "investigation_workspace_read",
writeCapability: "investigation_workspace_write",
operation: commitContract.name,
@@ -83,22 +72,20 @@ const registerCommitTool = (
options.logger,
commitContract.name,
() =>
commitReconstructionCoverage(
parsed.value,
options.evidenceFilePolicy,
{ signal: context.mcpReq.signal },
),
commitReconstructionCoverage(input, options.evidenceFilePolicy, {
signal: context.mcpReq.signal,
}),
);
if (!result.ok) return toCallToolResult(result, commitContract);
options.retainCoverageWorkspace?.(parsed.value.workspace);
options.retainCoverageWorkspace?.(input.workspace);
return toCallToolResult(result, commitContract, {
resourceLinks:
options.retainCoverageWorkspace === undefined
? []
: [
{
uri: coverageWorkspaceUri(parsed.value.workspace),
name: parsed.value.workspace.workspace_id,
uri: coverageWorkspaceUri(input.workspace),
name: input.workspace.workspace_id,
description:
"Session-retained reconstruction coverage workspace revision",
},
@@ -116,12 +103,6 @@ const registerQueryTool = (
queryContract.name,
toolRegistrationOptions(queryContract),
async (input, context) => {
const parsed = safeParseToolInput(
reconstructionCoverageQueryInputSchema,
input,
queryContract.name,
);
if (!parsed.ok) return toCallToolResult(parsed, queryContract);
if (options.permissionAuthority === undefined)
return toCallToolResult(
err(
@@ -137,7 +118,7 @@ const registerQueryTool = (
options.permissionAuthority,
{
capability: "investigation_workspace_read",
roots: [parsed.value.workspace_path],
roots: [input.workspace_path],
access: "read",
operation: queryContract.name,
},
@@ -148,7 +129,7 @@ const registerQueryTool = (
queryContract.name,
() =>
queryReconstructionCoverage(
parsed.value,
input,
options.evidenceFilePolicy,
Date.now(),
{ signal: context.mcpReq.signal },
@@ -157,7 +138,7 @@ const registerQueryTool = (
if (result.ok && options.retainCoverageWorkspace !== undefined) {
const closure = reconstructionClosureResultSchema.parse(result.value);
const loaded = await readReconstructionCoverageWorkspace(
parsed.value.workspace_path,
input.workspace_path,
options.evidenceFilePolicy,
);
if (!loaded.ok) return toCallToolResult(loaded, queryContract);
@@ -5,9 +5,7 @@ import {
resolveReconstructionObligationLedgerRequest,
} from "../../application/ReconstructionObligationLedgerService.js";
import { applicationToolContract } from "../../contracts/applicationToolContracts.js";
import { reconstructionObligationLedgerInputSchema } from "../../domain/reconstructionObligationLedgerSchemas.js";
import { logToolExecution } from "../toolLogging.js";
import { safeParseToolInput } from "../toolInputValidation.js";
import { toolRegistrationOptions } from "../toolRegistrationOptions.js";
import { toCallToolResult } from "../toolResult.js";
import { recordResult, recordSources } from "./helpers.js";
@@ -26,15 +24,7 @@ export const registerReconstructionObligationLedgerTool = (
contract.name,
toolRegistrationOptions(contract),
async (input) => {
const parsed = safeParseToolInput(
reconstructionObligationLedgerInputSchema,
input,
contract.name,
);
if (!parsed.ok) return toCallToolResult(parsed, contract);
const resolved = resolveReconstructionObligationLedgerRequest(
parsed.value,
);
const resolved = resolveReconstructionObligationLedgerRequest(input);
if (!resolved.ok) return toCallToolResult(resolved, contract);
const result = await logToolExecution(options.logger, contract.name, () =>
Promise.resolve(
@@ -5,10 +5,8 @@ import {
resolveReconstructionReadinessRequest,
} from "../../application/ReconstructionReadinessService.js";
import { applicationToolContract } from "../../contracts/applicationToolContracts.js";
import { reconstructionReadinessInputSchema } from "../../domain/reconstructionReadinessSchemas.js";
import { reconstructionReadinessReportSchema } from "../../domain/reconstructionReadinessSchemas.js";
import { logToolExecution } from "../toolLogging.js";
import { safeParseToolInput } from "../toolInputValidation.js";
import { toolRegistrationOptions } from "../toolRegistrationOptions.js";
import { toCallToolResult } from "../toolResult.js";
import { recordSources } from "./helpers.js";
@@ -25,13 +23,7 @@ export const registerReconstructionReadinessTool = (
contract.name,
toolRegistrationOptions(contract),
async (input) => {
const parsed = safeParseToolInput(
reconstructionReadinessInputSchema,
input,
contract.name,
);
if (!parsed.ok) return toCallToolResult(parsed, contract);
const resolved = resolveReconstructionReadinessRequest(parsed.value);
const resolved = resolveReconstructionReadinessRequest(input);
if (!resolved.ok) return toCallToolResult(resolved, contract);
const result = await logToolExecution(options.logger, contract.name, () =>
Promise.resolve(
@@ -1,13 +1,11 @@
import type { McpServer } from "@modelcontextprotocol/server";
import { traceApplicationFeatureEvidenceValidated } from "../../application/JavaScriptApplicationWorkflowService.js";
import { resolveTraceApplicationFeatureRequestValidated } from "../../application/ApplicationWorkflowEvidenceResolver.js";
import { traceApplicationFeatureEvidenceValidated } from "../../application/JavaScriptApplicationWorkflowService.js";
import { applicationToolContract } from "../../contracts/applicationToolContracts.js";
import { traceApplicationFeatureRequestSchema } from "../../contracts/applicationWorkflowInputContracts.js";
import { logToolExecution } from "../toolLogging.js";
import { toCallToolResult } from "../toolResult.js";
import { toolRegistrationOptions } from "../toolRegistrationOptions.js";
import { safeParseToolInput } from "../toolInputValidation.js";
import { toCallToolResult } from "../toolResult.js";
import { recordResult, recordSources } from "./helpers.js";
import type { ApplicationToolRegistration } from "./types.js";
@@ -22,14 +20,8 @@ export const registerTraceFeatureTool = (
traceContract.name,
toolRegistrationOptions(traceContract),
async (input) => {
const parsedInput = safeParseToolInput(
traceApplicationFeatureRequestSchema,
input,
traceContract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, traceContract);
const resolved = resolveTraceApplicationFeatureRequestValidated(
parsedInput.value,
input,
options.evidenceLookup,
);
if (!resolved.ok) return toCallToolResult(resolved, traceContract);
@@ -3,8 +3,6 @@ import type { McpServer } from "@modelcontextprotocol/server";
import { resolveTraceJavaScriptSemanticsRequestValidated } from "../../application/ApplicationWorkflowEvidenceResolver.js";
import { traceJavaScriptSemanticsEvidenceValidated } from "../../application/JavaScriptSemanticTraceService.js";
import { applicationToolContract } from "../../contracts/applicationToolContracts.js";
import { traceJavaScriptSemanticsRequestSchema } from "../../contracts/applicationWorkflowInputContracts.js";
import { safeParseToolInput } from "../toolInputValidation.js";
import { logToolExecution } from "../toolLogging.js";
import { toolRegistrationOptions } from "../toolRegistrationOptions.js";
import { toCallToolResult } from "../toolResult.js";
@@ -22,14 +20,8 @@ export const registerTraceJavaScriptSemanticsTool = (
contract.name,
toolRegistrationOptions(contract),
async (input) => {
const parsedInput = safeParseToolInput(
traceJavaScriptSemanticsRequestSchema,
input,
contract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, contract);
const resolved = resolveTraceJavaScriptSemanticsRequestValidated(
parsedInput.value,
input,
options.evidenceLookup,
);
if (!resolved.ok) return toCallToolResult(resolved, contract);
+13 -24
View File
@@ -1,70 +1,59 @@
import type { McpServer } from "@modelcontextprotocol/server";
import type { BinarySessionPort } from "../application/BinarySession.js";
import type { ToolContract } from "../contracts/toolContracts.js";
import {
artifactComparisonInputSchema,
compareArtifacts,
} from "../domain/artifactComparison.js";
import { SESSION_TOOL_CONTRACTS } from "../contracts/toolContracts.js";
import { compareArtifacts } from "../domain/artifactComparison.js";
import { createEvidence } from "../domain/evidence.js";
import { jsonValueSchema } from "../domain/jsonValue.js";
import type { RecordUnknownInput } from "../domain/residualUnknown.js";
import { recordDerivedEvidence } from "./recordDerivedEvidence.js";
import { runDerivedOperation } from "./runDerivedOperation.js";
import { resolveSessionEvidenceIds } from "./sessionEvidence.js";
import { ARTIFACT_COMPARISON_PROVIDER } from "./sessionToolPolicies.js";
import { toCallToolResult } from "./toolResult.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import { runDerivedOperation } from "./runDerivedOperation.js";
import { safeParseToolInput } from "./toolInputValidation.js";
import { toCallToolResult } from "./toolResult.js";
/** Register Evidence-backed deterministic artifact comparison. */
export const registerArtifactComparisonTool = (
server: McpServer,
session: BinarySessionPort,
contract: ToolContract<"compare_artifacts">,
contract: (typeof SESSION_TOOL_CONTRACTS)[7],
): void => {
server.registerTool(
contract.name,
toolRegistrationOptions(contract),
async (input, context) => {
const parsedInput = safeParseToolInput(
artifactComparisonInputSchema,
input,
contract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, contract);
const parsed = parsedInput.value;
const expected = {
operation: "inventory_artifact",
predicate: "rea.analysis/v2",
};
const left = resolveSessionEvidenceIds(
session,
parsed.left_evidence_ids,
input.left_evidence_ids,
expected,
);
if (!left.ok) return toCallToolResult(left, contract);
const right = resolveSessionEvidenceIds(
session,
parsed.right_evidence_ids,
input.right_evidence_ids,
expected,
);
if (!right.ok) return toCallToolResult(right, contract);
const computed = await runDerivedOperation(context, contract.name, () =>
compareArtifacts(left.value, right.value, parsed.offset, parsed.limit),
compareArtifacts(left.value, right.value, input.offset, input.limit),
);
if (!computed.ok) return toCallToolResult(computed, contract);
const comparison = computed.value;
const leftEvidenceIds = parsed.left_evidence_ids;
const rightEvidenceIds = parsed.right_evidence_ids;
const leftEvidenceIds = input.left_evidence_ids;
const rightEvidenceIds = input.right_evidence_ids;
const evidence = createEvidence(undefined, ARTIFACT_COMPARISON_PROVIDER, {
predicateType: "rea.artifact-comparison/v1",
operation: contract.name,
parameters: {
left_evidence_ids: leftEvidenceIds,
right_evidence_ids: rightEvidenceIds,
offset: parsed.offset,
limit: parsed.limit,
offset: input.offset,
limit: input.limit,
},
result: jsonValueSchema.parse(comparison),
confidence: "derived",
@@ -76,7 +65,7 @@ export const registerArtifactComparisonTool = (
recordDerivedEvidence(
session,
evidence,
artifactUnknownInput(parsed, comparison.status),
artifactUnknownInput(input, comparison.status),
),
contract,
);
+1 -9
View File
@@ -5,10 +5,8 @@ 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 { safeParseToolInput } from "./toolInputValidation.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import { toCallToolResult } from "./toolResult.js";
@@ -29,17 +27,11 @@ export const registerBrowserScenarioTool = (
contract.name,
toolRegistrationOptions(contract),
async (input, context) => {
const parsed = safeParseToolInput(
browserScenarioSchema,
input,
contract.name,
);
if (!parsed.ok) return toCallToolResult(parsed, contract);
const result = await logToolExecution(options.logger, contract.name, () =>
captureBrowserScenario(
options.provider,
options.permissionAuthority,
parsed.value,
input,
{ signal: context.mcpReq.signal },
),
);
+162 -133
View File
@@ -1,9 +1,7 @@
import type { McpServer } from "@modelcontextprotocol/server";
import type { z } from "zod";
import type { McpServer, ServerContext } from "@modelcontextprotocol/server";
import type { BrowserObservationPort } from "../application/BrowserObservationPort.js";
import type { BinarySessionPort } from "../application/BinarySession.js";
import type { PermissionAuthority } from "../application/PermissionAuthority.js";
import type { BrowserObservationPort } from "../application/BrowserObservationPort.js";
import {
analyzeWebBundle,
captureWebScreenshot,
@@ -14,30 +12,18 @@ import {
listBrowserTargets,
observeWebSession,
} from "../application/BrowserObservationService.js";
import { BROWSER_TOOL_CONTRACTS } from "../contracts/browserToolContracts.js";
import {
inspectWebPageInputSchema,
listBrowserTargetsInputSchema,
} from "../domain/browserObservation.js";
import { analyzeWebBundleInputSchema } from "../domain/webBundleAnalysis.js";
import { observeWebSessionInputSchema } from "../domain/browserSession.js";
import { discoverWebMcpToolsInputSchema } from "../domain/webMcpDiscovery.js";
import { browserCaptureComparisonInputSchema } from "../domain/browserCaptureComparison.js";
import {
captureWebScreenshotInputSchema,
compareWebScreenshotsInputSchema,
} from "../domain/webScreenshot.js";
import type { Logger } from "../logger.js";
import { logToolExecution } from "./toolLogging.js";
import { toCallToolResult } from "./toolResult.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import { safeParseToolInput } from "./toolInputValidation.js";
import { mcpProgressReporter } from "./mcpProgress.js";
import type { PermissionAuthority } from "../application/PermissionAuthority.js";
import type { ProgressReporter } from "../application/ProgressReporter.js";
import { BROWSER_TOOL_CONTRACTS } from "../contracts/browserToolContracts.js";
import type { ToolContract } from "../contracts/toolContracts.js";
import type { AnalysisError } from "../domain/errors.js";
import type { Evidence } from "../domain/evidence.js";
import type { Result } from "../domain/result.js";
import type { AnalysisError } from "../domain/errors.js";
import type { ToolContract } from "../contracts/toolContracts.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";
interface BrowserToolRegistration {
readonly logger: Logger;
@@ -51,16 +37,8 @@ interface BrowserToolContext {
readonly progress: ProgressReporter;
}
interface BrowserToolSpec<Schema extends z.ZodType> {
readonly contract: ToolContract;
readonly schema: Schema;
readonly execute: (
parsed: z.output<Schema>,
context: BrowserToolContext,
) => Promise<Result<Evidence, AnalysisError>>;
}
/** Register browser tools even when policy/provider availability denies execution. */
// oxlint-disable-next-line max-lines-per-function -- direct SDK calls retain each schema-handler type correlation.
export const registerBrowserTools = (
server: McpServer,
options: BrowserToolRegistration,
@@ -76,111 +54,162 @@ export const registerBrowserTools = (
screenshotDiffContract,
] = BROWSER_TOOL_CONTRACTS;
registerBrowserTool(server, options, {
contract: listContract,
schema: listBrowserTargetsInputSchema,
execute: (parsed, { signal }) =>
listBrowserTargets(options.browser, options.permissionAuthority, parsed, {
signal,
}),
});
registerBrowserTool(server, options, {
contract: inspectContract,
schema: inspectWebPageInputSchema,
execute: (parsed, { signal, progress }) =>
inspectWebPage(options.browser, options.permissionAuthority, parsed, {
signal,
progress,
}),
});
registerBrowserTool(server, options, {
contract: analyzeContract,
schema: analyzeWebBundleInputSchema,
execute: (parsed, { signal, progress }) =>
analyzeWebBundle(options.browser, options.permissionAuthority, parsed, {
signal,
progress,
}),
});
registerBrowserTool(server, options, {
contract: sessionContract,
schema: observeWebSessionInputSchema,
execute: (parsed, { signal, progress }) =>
observeWebSession(options.browser, options.permissionAuthority, parsed, {
signal,
progress,
}),
});
registerBrowserTool(server, options, {
contract: webMcpContract,
schema: discoverWebMcpToolsInputSchema,
execute: (parsed, { signal, progress }) =>
discoverWebMcpTools(
options.browser,
options.permissionAuthority,
parsed,
{
signal,
progress,
},
server.registerTool(
listContract.name,
toolRegistrationOptions(listContract),
(input, context) =>
runBrowserTool(
options,
listContract,
{ input, context },
(parsed, { signal }) =>
listBrowserTargets(
options.browser,
options.permissionAuthority,
parsed,
{
signal,
},
),
),
});
registerBrowserTool(server, options, {
contract: captureDiffContract,
schema: browserCaptureComparisonInputSchema,
execute: (parsed, _context) =>
compareWebCaptureEvidence(options.browser, parsed),
});
registerBrowserTool(server, options, {
contract: screenshotContract,
schema: captureWebScreenshotInputSchema,
execute: (parsed, { signal, progress }) =>
captureWebScreenshot(
options.browser,
options.permissionAuthority,
parsed,
{
signal,
progress,
},
);
server.registerTool(
inspectContract.name,
toolRegistrationOptions(inspectContract),
(input, context) =>
runBrowserTool(
options,
inspectContract,
{ input, context },
(parsed, { signal, progress }) =>
inspectWebPage(options.browser, options.permissionAuthority, parsed, {
signal,
progress,
}),
),
});
registerBrowserTool(server, options, {
contract: screenshotDiffContract,
schema: compareWebScreenshotsInputSchema,
execute: (parsed, _context) =>
compareWebScreenshotEvidence(options.browser, parsed),
});
);
server.registerTool(
analyzeContract.name,
toolRegistrationOptions(analyzeContract),
(input, context) =>
runBrowserTool(
options,
analyzeContract,
{ input, context },
(parsed, { signal, progress }) =>
analyzeWebBundle(
options.browser,
options.permissionAuthority,
parsed,
{
signal,
progress,
},
),
),
);
server.registerTool(
sessionContract.name,
toolRegistrationOptions(sessionContract),
(input, context) =>
runBrowserTool(
options,
sessionContract,
{ input, context },
(parsed, { signal, progress }) =>
observeWebSession(
options.browser,
options.permissionAuthority,
parsed,
{
signal,
progress,
},
),
),
);
server.registerTool(
webMcpContract.name,
toolRegistrationOptions(webMcpContract),
(input, context) =>
runBrowserTool(
options,
webMcpContract,
{ input, context },
(parsed, { signal, progress }) =>
discoverWebMcpTools(
options.browser,
options.permissionAuthority,
parsed,
{
signal,
progress,
},
),
),
);
server.registerTool(
captureDiffContract.name,
toolRegistrationOptions(captureDiffContract),
(input, context) =>
runBrowserTool(
options,
captureDiffContract,
{ input, context },
(parsed) => compareWebCaptureEvidence(options.browser, parsed),
),
);
server.registerTool(
screenshotContract.name,
toolRegistrationOptions(screenshotContract),
(input, context) =>
runBrowserTool(
options,
screenshotContract,
{ input, context },
(parsed, { signal, progress }) =>
captureWebScreenshot(
options.browser,
options.permissionAuthority,
parsed,
{
signal,
progress,
},
),
),
);
server.registerTool(
screenshotDiffContract.name,
toolRegistrationOptions(screenshotDiffContract),
(input, context) =>
runBrowserTool(
options,
screenshotDiffContract,
{ input, context },
(parsed) => compareWebScreenshotEvidence(options.browser, parsed),
),
);
};
const registerBrowserTool = <Schema extends z.ZodType>(
server: McpServer,
const runBrowserTool = async <Input>(
options: BrowserToolRegistration,
spec: BrowserToolSpec<Schema>,
): void => {
server.registerTool(
spec.contract.name,
toolRegistrationOptions(spec.contract),
async (input, context) => {
const parsedInput = safeParseToolInput(
spec.schema,
input,
spec.contract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, spec.contract);
const result = await logToolExecution(
options.logger,
spec.contract.name,
() =>
spec.execute(parsedInput.value, {
signal: context.mcpReq.signal,
progress: mcpProgressReporter(context),
}),
);
if (!result.ok) return toCallToolResult(result, spec.contract);
return evidenceResult(options, spec.contract, result.value);
},
contract: ToolContract,
request: { readonly input: Input; readonly context: ServerContext },
execute: (
input: Input,
context: BrowserToolContext,
) => Promise<Result<Evidence, AnalysisError>>,
) => {
const { input, context } = request;
const result = await logToolExecution(options.logger, contract.name, () =>
execute(input, {
signal: context.mcpReq.signal,
progress: mcpProgressReporter(context),
}),
);
if (!result.ok) return toCallToolResult(result, contract);
return evidenceResult(options, contract, result.value);
};
const evidenceResult = (
+15 -26
View File
@@ -2,42 +2,31 @@ import type { McpServer } from "@modelcontextprotocol/server";
import type { BinarySessionPort } from "../application/BinarySession.js";
import { readEvidenceBundle } from "../application/EvidenceBundleFiles.js";
import type { ToolContract } from "../contracts/toolContracts.js";
import {
bundleComparisonInputSchema,
compareBundles,
} from "../domain/bundleComparison.js";
import { SESSION_TOOL_CONTRACTS } from "../contracts/toolContracts.js";
import { compareBundles } from "../domain/bundleComparison.js";
import { createEvidence } from "../domain/evidence.js";
import type { EvidenceFilePolicy } from "../domain/evidenceBundle.js";
import { jsonValueSchema } from "../domain/jsonValue.js";
import { ok } from "../domain/result.js";
import type { EvidenceFilePolicy } from "../domain/evidenceBundle.js";
import { BUNDLE_COMPARISON_PROVIDER } from "./sessionToolPolicies.js";
import { toCallToolResult } from "./toolResult.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import { runDerivedOperation } from "./runDerivedOperation.js";
import { safeParseToolInput } from "./toolInputValidation.js";
import { BUNDLE_COMPARISON_PROVIDER } from "./sessionToolPolicies.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import { toCallToolResult } from "./toolResult.js";
/** Register canonical Evidence bundle comparison. */
export const registerBundleComparisonTool = (
server: McpServer,
session: BinarySessionPort,
contract: ToolContract<"compare_bundles">,
contract: (typeof SESSION_TOOL_CONTRACTS)[9],
evidenceFilePolicy: EvidenceFilePolicy,
): void => {
server.registerTool(
contract.name,
toolRegistrationOptions(contract),
async (input, context) => {
const parsedInput = safeParseToolInput(
bundleComparisonInputSchema,
input,
contract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, contract);
const parsed = parsedInput.value;
const [left, right] = await Promise.all([
readEvidenceBundle(parsed.left_bundle_path, evidenceFilePolicy),
readEvidenceBundle(parsed.right_bundle_path, evidenceFilePolicy),
readEvidenceBundle(input.left_bundle_path, evidenceFilePolicy),
readEvidenceBundle(input.right_bundle_path, evidenceFilePolicy),
]);
if (!left.ok) return toCallToolResult(left, contract);
if (!right.ok) return toCallToolResult(right, contract);
@@ -45,9 +34,9 @@ export const registerBundleComparisonTool = (
compareBundles(
left.value,
right.value,
parsed.record_pairs,
parsed.offset,
parsed.limit,
input.record_pairs,
input.offset,
input.limit,
),
);
if (!computed.ok) return toCallToolResult(computed, contract);
@@ -58,9 +47,9 @@ export const registerBundleComparisonTool = (
parameters: {
left_bundle_sha256: comparison.left_bundle_sha256,
right_bundle_sha256: comparison.right_bundle_sha256,
record_pairs: parsed.record_pairs,
offset: parsed.offset,
limit: parsed.limit,
record_pairs: input.record_pairs,
offset: input.offset,
limit: input.limit,
},
result: jsonValueSchema.parse(comparison),
confidence: "derived",
+7 -18
View File
@@ -1,17 +1,15 @@
import { writeAnalysisSnapshot } from "../application/AnalysisSnapshotFiles.js";
import { closeBinaryInputSchema } from "../contracts/sessionLifecycleInputs.js";
import { ok } from "../domain/result.js";
import {
reportLifecycleEnd,
reportLifecycleStart,
} from "./lifecycleProgress.js";
import { logToolExecution } from "./toolLogging.js";
import { toCallToolResult } from "./toolResult.js";
import { mcpProgressReporter } from "./mcpProgress.js";
import { permissionFailure } from "./permissionFailure.js";
import type { LifecycleToolRegistration } from "./registerSessionTools.js";
import { safeParseToolInput } from "./toolInputValidation.js";
import { logToolExecution } from "./toolLogging.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import { toCallToolResult } from "./toolResult.js";
/** Register provider cleanup and optional pre-close snapshot persistence. */
export const registerCloseLifecycleTool = ({
@@ -26,33 +24,25 @@ export const registerCloseLifecycleTool = ({
closeContract.name,
toolRegistrationOptions(closeContract),
async (input, context) => {
const parsedInput = safeParseToolInput(
closeBinaryInputSchema,
input,
closeContract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, closeContract);
const parsed = parsedInput.value;
const progress = mcpProgressReporter(context);
if (parsed.snapshot_path === undefined) {
if (input.snapshot_path === undefined) {
await reportLifecycleStart(progress, closeContract.name);
const closed = await logToolExecution(logger, closeContract.name, () =>
session.close({ progress }),
);
await reportLifecycleEnd(progress, closeContract.name, closed.ok);
server.sendToolListChanged();
return toCallToolResult(closed, closeContract);
}
if (permissionAuthority !== undefined) {
const authorized = await permissionAuthority.authorize(
{
capability: "snapshot_write",
roots: [parsed.snapshot_path],
roots: [input.snapshot_path],
executables: [],
environment_names: [],
network: "none",
mount: false,
operation_identity: `close_binary:snapshot:${parsed.snapshot_path}`,
operation_identity: `close_binary:snapshot:${input.snapshot_path}`,
},
"write",
);
@@ -63,8 +53,8 @@ export const registerCloseLifecycleTool = ({
if (!snapshot.ok) return toCallToolResult(snapshot, closeContract);
const written = await writeAnalysisSnapshot(
snapshot.value,
parsed.snapshot_path,
parsed.overwrite,
input.snapshot_path,
input.overwrite,
snapshotFilePolicy,
);
if (!written.ok) return toCallToolResult(written, closeContract);
@@ -77,7 +67,6 @@ export const registerCloseLifecycleTool = ({
session.close({ progress }),
);
await reportLifecycleEnd(progress, closeContract.name, closed.ok);
server.sendToolListChanged();
return closed.ok
? toCallToolResult(
ok({
+130 -126
View File
@@ -1,40 +1,29 @@
import type { McpServer } from "@modelcontextprotocol/server";
import type { z } from "zod";
import type { McpServer, ServerContext } from "@modelcontextprotocol/server";
import type { BinarySessionPort } from "../application/BinarySession.js";
import type { ElectronObservationPort } from "../application/ElectronObservationPort.js";
import type { ElectronActiveObservationPort } from "../application/ElectronActiveObservationPort.js";
import { captureElectronScenario } from "../application/ElectronActiveObservationService.js";
import { analyzeJavaScriptApplicationValidated } from "../application/JavaScriptApplicationService.js";
import { reconcileJavaScriptRuntimeEvidenceValidated } from "../application/JavaScriptRuntimeReconciliationService.js";
import type { ElectronObservationPort } from "../application/ElectronObservationPort.js";
import {
inspectElectronPage,
listElectronTargets,
} from "../application/ElectronObservationService.js";
import { analyzeJavaScriptApplicationValidated } from "../application/JavaScriptApplicationService.js";
import { reconcileJavaScriptRuntimeEvidenceValidated } from "../application/JavaScriptRuntimeReconciliationService.js";
import type { PermissionAuthority } from "../application/PermissionAuthority.js";
import {
analyzeJavaScriptApplicationToolInputSchema,
ELECTRON_TOOL_CONTRACTS,
} from "../contracts/electronToolContracts.js";
import {
inspectElectronPageInputSchema,
listElectronTargetsInputSchema,
} from "../domain/electronObservation.js";
import { electronActiveObservationInputSchema } from "../domain/electronActiveObservation.js";
import { reconcileJavaScriptRuntimeInputSchema } from "../domain/javascriptRuntimeReconciliationSchemas.js";
import type { Logger } from "../logger.js";
import { logToolExecution } from "./toolLogging.js";
import { toCallToolResult } from "./toolResult.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import { safeParseToolInput } from "./toolInputValidation.js";
import { mcpProgressReporter } from "./mcpProgress.js";
import type { ProgressReporter } from "../application/ProgressReporter.js";
import type { Evidence } from "../domain/evidence.js";
import type { Result } from "../domain/result.js";
import type { AnalysisError } from "../domain/errors.js";
import { ELECTRON_TOOL_CONTRACTS } from "../contracts/electronToolContracts.js";
import type { ToolContract } from "../contracts/toolContracts.js";
import type { AnalysisError } from "../domain/errors.js";
import type { Evidence } from "../domain/evidence.js";
import type { JsonValue } from "../domain/jsonValue.js";
import type { Result } from "../domain/result.js";
import type { Logger } from "../logger.js";
import { summarizeJavaScriptApplicationEvidence } from "./javascriptApplicationResult.js";
import { mcpProgressReporter } from "./mcpProgress.js";
import { logToolExecution } from "./toolLogging.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import { toCallToolResult } from "./toolResult.js";
interface ElectronToolRegistration {
readonly logger: Logger;
@@ -49,23 +38,8 @@ interface ElectronToolContext {
readonly progress: ProgressReporter;
}
interface ElectronToolSpec<Schema extends z.ZodType> {
readonly contract: ToolContract;
readonly schema: Schema;
readonly execute: (
parsed: z.output<Schema>,
context: ElectronToolContext,
) => Promise<Result<Evidence, AnalysisError>>;
readonly projectEvidence?: (
evidence: Evidence,
parsed: z.output<Schema>,
) => {
readonly structured: JsonValue;
readonly text?: JsonValue;
};
}
/** Register Electron tools even when provider or permission policy is absent. */
// oxlint-disable-next-line max-lines-per-function -- direct SDK calls retain each schema-handler type correlation.
export const registerElectronTools = (
server: McpServer,
options: ElectronToolRegistration,
@@ -78,100 +52,130 @@ export const registerElectronTools = (
activeContract,
] = ELECTRON_TOOL_CONTRACTS;
registerElectronTool(server, options, {
contract: listContract,
schema: listElectronTargetsInputSchema,
execute: (parsed, { signal }) =>
listElectronTargets(
options.electron,
options.permissionAuthority,
parsed,
server.registerTool(
listContract.name,
toolRegistrationOptions(listContract),
(input, context) =>
runElectronTool(
options,
listContract,
{ input, context },
(parsed, { signal }) =>
listElectronTargets(
options.electron,
options.permissionAuthority,
parsed,
{
signal,
},
),
),
);
server.registerTool(
inspectContract.name,
toolRegistrationOptions(inspectContract),
(input, context) =>
runElectronTool(
options,
inspectContract,
{ input, context },
(parsed, { signal, progress }) =>
inspectElectronPage(
options.electron,
options.permissionAuthority,
parsed,
{
signal,
progress,
},
),
),
);
server.registerTool(
analyzeContract.name,
toolRegistrationOptions(analyzeContract),
(input, context) =>
runElectronTool(
options,
analyzeContract,
{
signal,
input,
context,
projectEvidence: (evidence, parsed) => {
const summary = summarizeJavaScriptApplicationEvidence(evidence);
return parsed.detail === "full"
? { structured: evidence.normalized_result, text: summary }
: { structured: summary };
},
},
(parsed, { signal, progress }) =>
analyzeJavaScriptApplicationValidated(
options.permissionAuthority,
parsed,
{ signal, progress },
),
),
});
registerElectronTool(server, options, {
contract: inspectContract,
schema: inspectElectronPageInputSchema,
execute: (parsed, { signal, progress }) =>
inspectElectronPage(
options.electron,
options.permissionAuthority,
parsed,
{
signal,
progress,
},
);
server.registerTool(
reconcileContract.name,
toolRegistrationOptions(reconcileContract),
(input, context) =>
runElectronTool(
options,
reconcileContract,
{ input, context },
(parsed) =>
Promise.resolve(reconcileJavaScriptRuntimeEvidenceValidated(parsed)),
),
});
registerElectronTool(server, options, {
contract: analyzeContract,
schema: analyzeJavaScriptApplicationToolInputSchema,
execute: (parsed, { signal, progress }) =>
analyzeJavaScriptApplicationValidated(
options.permissionAuthority,
parsed,
{ signal, progress },
);
server.registerTool(
activeContract.name,
toolRegistrationOptions(activeContract),
(input, context) =>
runElectronTool(
options,
activeContract,
{ input, context },
(parsed, { signal, progress }) =>
captureElectronScenario(
options.electronActive,
options.permissionAuthority,
parsed,
{ signal, progress },
),
),
projectEvidence: (evidence, parsed) => {
const summary = summarizeJavaScriptApplicationEvidence(evidence);
return parsed.detail === "full"
? { structured: evidence.normalized_result, text: summary }
: { structured: summary };
},
});
registerElectronTool(server, options, {
contract: reconcileContract,
schema: reconcileJavaScriptRuntimeInputSchema,
execute: (parsed, _context) =>
Promise.resolve(reconcileJavaScriptRuntimeEvidenceValidated(parsed)),
});
registerElectronTool(server, options, {
contract: activeContract,
schema: electronActiveObservationInputSchema,
execute: (parsed, { signal, progress }) =>
captureElectronScenario(
options.electronActive,
options.permissionAuthority,
parsed,
{ signal, progress },
),
});
);
};
const registerElectronTool = <Schema extends z.ZodType>(
server: McpServer,
const runElectronTool = async <Input>(
options: ElectronToolRegistration,
spec: ElectronToolSpec<Schema>,
): void => {
server.registerTool(
spec.contract.name,
toolRegistrationOptions(spec.contract),
async (input, context) => {
const parsedInput = safeParseToolInput(
spec.schema,
input,
spec.contract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, spec.contract);
const result = await logToolExecution(
options.logger,
spec.contract.name,
() =>
spec.execute(parsedInput.value, {
signal: context.mcpReq.signal,
progress: mcpProgressReporter(context),
}),
);
if (!result.ok) return toCallToolResult(result, spec.contract);
return evidenceResult(
options,
spec.contract,
result.value,
spec.projectEvidence?.(result.value, parsedInput.value),
);
},
contract: ToolContract,
request: {
readonly input: Input;
readonly context: ServerContext;
readonly projectEvidence?: (
evidence: Evidence,
input: Input,
) => { readonly structured: JsonValue; readonly text?: JsonValue };
},
execute: (
input: Input,
context: ElectronToolContext,
) => Promise<Result<Evidence, AnalysisError>>,
) => {
const { input, context, projectEvidence } = request;
const result = await logToolExecution(options.logger, contract.name, () =>
execute(input, {
signal: context.mcpReq.signal,
progress: mcpProgressReporter(context),
}),
);
if (!result.ok) return toCallToolResult(result, contract);
return evidenceResult(
options,
contract,
result.value,
projectEvidence?.(result.value, input),
);
};
+222 -285
View File
@@ -1,36 +1,33 @@
import type { McpServer } from "@modelcontextprotocol/server";
import type { z } from "zod";
import type {
CallToolResult,
McpServer,
ServerContext,
} from "@modelcontextprotocol/server";
import type { AnalysisOperationPort } from "../application/AnalysisProvider.js";
import type { BinarySessionPort } from "../application/BinarySession.js";
import {
EnhancedTools,
type ValidatedEnhancedCall,
} from "../application/EnhancedTools.js";
import type { AnalysisOperationPort } from "../application/AnalysisProvider.js";
import type { BinarySessionPort } from "../application/BinarySession.js";
import {
enhancedInputSchemas,
enhancedToolNameSchema,
} from "../contracts/enhancedInputs.js";
import {
ENHANCED_TOOL_CONTRACTS,
type ToolContract,
} from "../contracts/toolContracts.js";
import { toCallToolResult } from "./toolResult.js";
import type { Logger } from "../logger.js";
import { logToolExecution } from "./toolLogging.js";
import type { BinaryTarget } from "../domain/binaryTarget.js";
import { createEvidence } from "../domain/evidence.js";
import type { JsonValue } from "../domain/jsonValue.js";
import { AnalysisInputError, UnknownRegistryError } from "../domain/errors.js";
import { ok, type Result } from "../domain/result.js";
import { mcpProgressReporter } from "./mcpProgress.js";
import type { AnalysisProfileCommitment } from "../domain/analysisProfile.js";
import {
REA_WORKFLOW_PROVIDER,
workflowAnalysisProfile,
} from "../application/InvestigationProviders.js";
import {
ENHANCED_TOOL_CONTRACTS,
type ToolContract,
} from "../contracts/toolContracts.js";
import type { AnalysisProfileCommitment } from "../domain/analysisProfile.js";
import type { BinaryTarget } from "../domain/binaryTarget.js";
import { UnknownRegistryError } from "../domain/errors.js";
import { createEvidence } from "../domain/evidence.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 { safeParseToolInput } from "./toolInputValidation.js";
import { toCallToolResult } from "./toolResult.js";
/** Optional session services used by enhanced tool registration. */
export interface EnhancedToolRegistration {
@@ -44,107 +41,219 @@ export interface EnhancedToolRegistration {
}
/** 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 => {
for (const contract of ENHANCED_TOOL_CONTRACTS) {
registerEnhancedTool(server, analysis, contract, {
logger: options.logger,
activeTarget: options.activeTarget,
analysisProfile: options.analysisProfile,
recordEvidence: options.recordEvidence,
recordUnknown: options.recordUnknown,
});
}
const [
swiftClasses,
objcClasses,
objcProtocols,
batchDecompile,
callGraph,
swiftTypes,
xrefsToName,
binaryOverview,
analyzeFunction,
inspectNativeApi,
traceFeature,
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),
(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(
codeForString.name,
toolRegistrationOptions(codeForString),
(input, context) =>
executeEnhancedTool(analysis, options, codeForString, {
validatedCall: { name: "find_code_for_string", input },
context,
}),
);
server.registerTool(
traceCallPath.name,
toolRegistrationOptions(traceCallPath),
(input, context) =>
executeEnhancedTool(analysis, options, traceCallPath, {
validatedCall: { name: "trace_call_path", input },
context,
}),
);
};
const registerEnhancedTool = (
server: McpServer,
const executeEnhancedTool = async (
analysis: AnalysisOperationPort,
registration: EnhancedToolRegistration,
contract: ToolContract,
registration: {
readonly logger: Logger;
readonly activeTarget: (() => BinaryTarget | undefined) | undefined;
readonly analysisProfile:
| (() => AnalysisProfileCommitment | undefined)
| undefined;
readonly recordEvidence: BinarySessionPort["recordEvidence"] | undefined;
readonly recordUnknown: BinarySessionPort["recordUnknown"] | undefined;
request: {
readonly validatedCall: ValidatedEnhancedCall;
readonly context: ServerContext;
},
): void => {
const name = enhancedToolNameSchema.parse(contract.name);
server.registerTool(
name,
toolRegistrationOptions(contract),
async (input, context) => {
const progress = mcpProgressReporter(context);
await progress.report({
phase: name,
completed: 0,
total: 1,
message: "started",
});
const validatedCall = parseEnhancedCall(name, input);
if (!validatedCall.ok) return toCallToolResult(validatedCall, contract);
const parsedInput = validatedCall.value.input;
const parameters = jsonParameters(parsedInput);
const services = new EnhancedTools({
execute: (operation, operationParameters, executionOptions) =>
analysis.execute(operation, operationParameters, {
...executionOptions,
progress,
}),
});
const result = await logToolExecution(registration.logger, name, () =>
services.executeValidated(validatedCall.value, context.mcpReq.signal),
);
await progress.report({
phase: name,
completed: 1,
total: 1,
message: result.ok ? "completed" : "failed",
terminal: true,
});
if (result.ok) {
const upstreamProfile = registration.analysisProfile?.();
const evidence = createEvidence(
registration.activeTarget?.(),
REA_WORKFLOW_PROVIDER,
{
operation: name,
parameters,
result: result.value,
...(upstreamProfile === undefined
? {}
: {
analysisProfile: workflowAnalysisProfile(upstreamProfile),
}),
confidence: "derived",
limitations: [
"Derived by an REA workflow from one or more provider observations.",
],
},
);
const recorded = registration.recordEvidence?.(evidence);
if (recorded !== undefined && !recorded.ok)
return toCallToolResult(recorded, contract);
const unknowns = recordWorkflowUnknowns({
name,
input: parameters,
result: result.value,
evidenceId: evidence.evidence_id,
recordUnknown: registration.recordUnknown,
});
if (!unknowns.ok) return toCallToolResult(unknowns, contract);
return toCallToolResult({ ok: true, value: evidence }, contract, {
evidenceResourcesAvailable: recorded !== undefined,
});
}
return toCallToolResult(result, contract);
},
): 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);
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 upstreamProfile = registration.analysisProfile?.();
const evidence = createEvidence(
registration.activeTarget?.(),
REA_WORKFLOW_PROVIDER,
{
operation: name,
parameters,
result: result.value,
...(upstreamProfile === undefined
? {}
: {
analysisProfile: workflowAnalysisProfile(upstreamProfile),
}),
confidence: "derived",
limitations: [
"Derived by an REA workflow from one or more provider observations.",
],
},
);
const recorded = registration.recordEvidence?.(evidence);
if (recorded !== undefined && !recorded.ok)
return toCallToolResult(recorded, contract);
const unknowns = recordWorkflowUnknowns({
name,
input: parameters,
result: result.value,
evidenceId: evidence.evidence_id,
recordUnknown: registration.recordUnknown,
});
if (!unknowns.ok) return toCallToolResult(unknowns, contract);
return toCallToolResult({ ok: true, value: evidence }, contract, {
evidenceResourcesAvailable: recorded !== undefined,
});
}
return toCallToolResult(result, contract);
};
const jsonParameters = (
@@ -156,178 +265,6 @@ const jsonParameters = (
),
);
type EnhancedToolName = ValidatedEnhancedCall["name"];
type EnhancedInputOf<Name extends EnhancedToolName> = z.output<
(typeof enhancedInputSchemas)[Name]
>;
type EnhancedInputParser<Name extends EnhancedToolName> = (
input: unknown,
) => Result<EnhancedInputOf<Name>, AnalysisInputError>;
const ENHANCED_INPUT_PARSERS: {
[Name in EnhancedToolName]: EnhancedInputParser<Name>;
} = {
swift_classes: (input) =>
safeParseToolInput(
enhancedInputSchemas.swift_classes,
input,
"swift_classes",
),
get_objc_classes: (input) =>
safeParseToolInput(
enhancedInputSchemas.get_objc_classes,
input,
"get_objc_classes",
),
get_objc_protocols: (input) =>
safeParseToolInput(
enhancedInputSchemas.get_objc_protocols,
input,
"get_objc_protocols",
),
batch_decompile: (input) =>
safeParseToolInput(
enhancedInputSchemas.batch_decompile,
input,
"batch_decompile",
),
get_call_graph: (input) =>
safeParseToolInput(
enhancedInputSchemas.get_call_graph,
input,
"get_call_graph",
),
analyze_swift_types: (input) =>
safeParseToolInput(
enhancedInputSchemas.analyze_swift_types,
input,
"analyze_swift_types",
),
find_xrefs_to_name: (input) =>
safeParseToolInput(
enhancedInputSchemas.find_xrefs_to_name,
input,
"find_xrefs_to_name",
),
binary_overview: (input) =>
safeParseToolInput(
enhancedInputSchemas.binary_overview,
input,
"binary_overview",
),
analyze_function: (input) =>
safeParseToolInput(
enhancedInputSchemas.analyze_function,
input,
"analyze_function",
),
inspect_native_api: (input) =>
safeParseToolInput(
enhancedInputSchemas.inspect_native_api,
input,
"inspect_native_api",
),
trace_feature: (input) =>
safeParseToolInput(
enhancedInputSchemas.trace_feature,
input,
"trace_feature",
),
find_code_for_string: (input) =>
safeParseToolInput(
enhancedInputSchemas.find_code_for_string,
input,
"find_code_for_string",
),
trace_call_path: (input) =>
safeParseToolInput(
enhancedInputSchemas.trace_call_path,
input,
"trace_call_path",
),
};
const parseEnhancedCall = (
name: ValidatedEnhancedCall["name"],
input: unknown,
): Result<ValidatedEnhancedCall, AnalysisInputError> => {
switch (name) {
case "swift_classes":
return mapEnhancedCall(
ENHANCED_INPUT_PARSERS.swift_classes(input),
(value) => ({ name, input: value }),
);
case "get_objc_classes":
return mapEnhancedCall(
ENHANCED_INPUT_PARSERS.get_objc_classes(input),
(value) => ({ name, input: value }),
);
case "get_objc_protocols":
return mapEnhancedCall(
ENHANCED_INPUT_PARSERS.get_objc_protocols(input),
(value) => ({ name, input: value }),
);
case "batch_decompile":
return mapEnhancedCall(
ENHANCED_INPUT_PARSERS.batch_decompile(input),
(value) => ({ name, input: value }),
);
case "get_call_graph":
return mapEnhancedCall(
ENHANCED_INPUT_PARSERS.get_call_graph(input),
(value) => ({ name, input: value }),
);
case "analyze_swift_types":
return mapEnhancedCall(
ENHANCED_INPUT_PARSERS.analyze_swift_types(input),
(value) => ({ name, input: value }),
);
case "find_xrefs_to_name":
return mapEnhancedCall(
ENHANCED_INPUT_PARSERS.find_xrefs_to_name(input),
(value) => ({ name, input: value }),
);
case "binary_overview":
return mapEnhancedCall(
ENHANCED_INPUT_PARSERS.binary_overview(input),
(value) => ({ name, input: value }),
);
case "analyze_function":
return mapEnhancedCall(
ENHANCED_INPUT_PARSERS.analyze_function(input),
(value) => ({ name, input: value }),
);
case "inspect_native_api":
return mapEnhancedCall(
ENHANCED_INPUT_PARSERS.inspect_native_api(input),
(value) => ({ name, input: value }),
);
case "trace_feature":
return mapEnhancedCall(
ENHANCED_INPUT_PARSERS.trace_feature(input),
(value) => ({ name, input: value }),
);
case "find_code_for_string":
return mapEnhancedCall(
ENHANCED_INPUT_PARSERS.find_code_for_string(input),
(value) => ({ name, input: value }),
);
case "trace_call_path":
return mapEnhancedCall(
ENHANCED_INPUT_PARSERS.trace_call_path(input),
(value) => ({ name, input: value }),
);
}
};
const mapEnhancedCall = <Input, Call extends ValidatedEnhancedCall>(
parsed: Result<Input, AnalysisInputError>,
project: (input: Input) => Call,
): Result<Call, AnalysisInputError> =>
parsed.ok ? ok(project(parsed.value)) : parsed;
interface WorkflowUnknownInput {
readonly name: string;
readonly input: Readonly<Record<string, JsonValue>>;
+9 -16
View File
@@ -5,22 +5,21 @@ import type {
AnalysisOperationPort,
} from "../application/AnalysisProvider.js";
import type { BinarySessionPort } from "../application/BinarySession.js";
import type { PermissionAuthority } from "../application/PermissionAuthority.js";
import type { ToolContract } from "../contracts/toolContracts.js";
import type { BinaryTarget } from "../domain/binaryTarget.js";
import { createEvidence, type Evidence } from "../domain/evidence.js";
import { jsonObjectSchema } from "../domain/jsonValue.js";
import type { Logger } from "../logger.js";
import { logToolExecution } from "./toolLogging.js";
import { toCallToolResult } from "./toolResult.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import { mcpProgressReporter } from "./mcpProgress.js";
import { safeParseToolInput } from "./toolInputValidation.js";
import type { PermissionAuthority } from "../application/PermissionAuthority.js";
import {
AnalysisProtocolError,
PermissionRequiredError,
} from "../domain/errors.js";
import { createEvidence, type Evidence } from "../domain/evidence.js";
import { jsonObjectSchema } from "../domain/jsonValue.js";
import { err } from "../domain/result.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";
interface EvidenceToolRegistration {
readonly logger: Logger;
@@ -52,13 +51,7 @@ export const registerEvidenceTools = (
total: 1,
message: "started",
});
const parsedInput = safeParseToolInput(
contract.inputSchema,
input,
contract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, contract);
const parameters = jsonObjectSchema.parse(parsedInput.value);
const parameters = jsonObjectSchema.parse(input);
if (options.permissionAuthority !== undefined) {
const request = permissionRequest(contract.name, parameters);
if (request !== undefined) {
+13 -24
View File
@@ -1,59 +1,48 @@
import type { McpServer } from "@modelcontextprotocol/server";
import type { BinarySessionPort } from "../application/BinarySession.js";
import type { ToolContract } from "../contracts/toolContracts.js";
import {
compareFunctions,
functionComparisonInputSchema,
} from "../domain/functionComparison.js";
import { SESSION_TOOL_CONTRACTS } from "../contracts/toolContracts.js";
import { createEvidence } from "../domain/evidence.js";
import { compareFunctions } from "../domain/functionComparison.js";
import { jsonValueSchema } from "../domain/jsonValue.js";
import type { RecordUnknownInput } from "../domain/residualUnknown.js";
import { FUNCTION_COMPARISON_PROVIDER } from "./sessionToolPolicies.js";
import { toCallToolResult } from "./toolResult.js";
import { recordDerivedEvidence } from "./recordDerivedEvidence.js";
import { resolveSessionEvidenceIds } from "./sessionEvidence.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import { runDerivedOperation } from "./runDerivedOperation.js";
import { safeParseToolInput } from "./toolInputValidation.js";
import { resolveSessionEvidenceIds } from "./sessionEvidence.js";
import { FUNCTION_COMPARISON_PROVIDER } from "./sessionToolPolicies.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import { toCallToolResult } from "./toolResult.js";
/** Register explicit Evidence-backed function comparison. */
export const registerFunctionComparisonTool = (
server: McpServer,
session: BinarySessionPort,
contract: ToolContract<"compare_functions">,
contract: (typeof SESSION_TOOL_CONTRACTS)[8],
): void => {
server.registerTool(
contract.name,
toolRegistrationOptions(contract),
async (input, context) => {
const parsedInput = safeParseToolInput(
functionComparisonInputSchema,
input,
contract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, contract);
const parsed = parsedInput.value;
const expected = {
operation: "analyze_function",
predicate: "rea.analysis/v2",
};
const left = resolveSessionEvidenceIds(
session,
parsed.left_evidence_ids,
input.left_evidence_ids,
expected,
);
if (!left.ok) return toCallToolResult(left, contract);
const right = resolveSessionEvidenceIds(
session,
parsed.right_evidence_ids,
input.right_evidence_ids,
expected,
);
if (!right.ok) return toCallToolResult(right, contract);
const leftIds = left.value.map(({ evidence_id: id }) => id);
const rightIds = right.value.map(({ evidence_id: id }) => id);
const computed = await runDerivedOperation(context, contract.name, () =>
compareFunctions(left.value, right.value, parsed.offset, parsed.limit),
compareFunctions(left.value, right.value, input.offset, input.limit),
);
if (!computed.ok) return toCallToolResult(computed, contract);
const comparison = computed.value;
@@ -63,8 +52,8 @@ export const registerFunctionComparisonTool = (
parameters: {
left_evidence_ids: leftIds,
right_evidence_ids: rightIds,
offset: parsed.offset,
limit: parsed.limit,
offset: input.offset,
limit: input.limit,
},
result: jsonValueSchema.parse(comparison),
confidence: "derived",
@@ -76,7 +65,7 @@ export const registerFunctionComparisonTool = (
session,
evidence,
functionUnknownInput({
approved: parsed.unknown_registry_approved,
approved: input.unknown_registry_approved,
status: comparison.status,
leftIds,
rightIds,
+67 -102
View File
@@ -3,44 +3,25 @@ import type { z } from "zod";
import type { BinarySessionPort } from "../application/BinarySession.js";
import { runCrossVersionInvestigationValidated } from "../application/CrossVersionInvestigation.js";
import type { ToolContract } from "../contracts/toolContracts.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import { safeParseToolInput } from "./toolInputValidation.js";
import { buildCallPath, callPathInputSchema } from "../domain/callPath.js";
import {
correlateStaticAndRuntime,
staticRuntimeCorrelationInputSchema,
} from "../domain/staticRuntimeCorrelation.js";
import {
reconstructionVerificationInputSchema,
verifyReconstruction,
} from "../domain/reconstructionVerification.js";
import {
changedBehaviorResultSchema,
changedBehaviorInputSchema,
findChangedBehavior,
} from "../domain/changedBehavior.js";
import { createEvidence } from "../domain/evidence.js";
import { type AnalysisError } from "../domain/errors.js";
import { jsonValueSchema } from "../domain/jsonValue.js";
import type { Result } from "../domain/result.js";
import {
CALL_PATH_PROVIDER,
CHANGED_BEHAVIOR_PROVIDER,
RECONSTRUCTION_PROVIDER,
STATIC_RUNTIME_PROVIDER,
} from "./sessionToolPolicies.js";
import { toCallToolResult } from "./toolResult.js";
import { mcpProgressReporter } from "./mcpProgress.js";
import {
runDerivedOperation,
type DerivedOperationContext,
} from "./runDerivedOperation.js";
import {
authorizeFileReadWithDeferredWrite,
authorizeRootPermission,
type DeferredFileWriteAuthorization,
} from "../application/DeferredFileAuthorization.js";
import { SESSION_TOOL_CONTRACTS } from "../contracts/toolContracts.js";
import { buildCallPath } from "../domain/callPath.js";
import {
changedBehaviorInputSchema,
changedBehaviorResultSchema,
findChangedBehavior,
} from "../domain/changedBehavior.js";
import { type AnalysisError } from "../domain/errors.js";
import { createEvidence } from "../domain/evidence.js";
import { jsonValueSchema } from "../domain/jsonValue.js";
import { verifyReconstruction } from "../domain/reconstructionVerification.js";
import type { Result } from "../domain/result.js";
import { correlateStaticAndRuntime } from "../domain/staticRuntimeCorrelation.js";
import { mcpProgressReporter } from "./mcpProgress.js";
import {
comparisonClosure,
evidenceClosure,
@@ -51,16 +32,28 @@ import {
verifyCoverageReadiness,
} from "./registerInvestigationTools/helpers.js";
import type { InvestigationToolPolicies } from "./registerInvestigationTools/types.js";
import {
runDerivedOperation,
type DerivedOperationContext,
} from "./runDerivedOperation.js";
import {
CALL_PATH_PROVIDER,
CHANGED_BEHAVIOR_PROVIDER,
RECONSTRUCTION_PROVIDER,
STATIC_RUNTIME_PROVIDER,
} from "./sessionToolPolicies.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import { toCallToolResult } from "./toolResult.js";
/** Register Evidence-composed differential investigation workflows. */
export const registerInvestigationTools = (
server: McpServer,
session: BinarySessionPort,
contracts: readonly [
ToolContract<"find_changed_behavior">,
ToolContract<"build_call_path">,
ToolContract<"correlate_static_and_runtime">,
ToolContract<"verify_reconstruction">,
(typeof SESSION_TOOL_CONTRACTS)[10],
(typeof SESSION_TOOL_CONTRACTS)[11],
(typeof SESSION_TOOL_CONTRACTS)[12],
(typeof SESSION_TOOL_CONTRACTS)[13],
],
policies: InvestigationToolPolicies,
): void => {
@@ -73,21 +66,14 @@ export const registerInvestigationTools = (
const registerChangedBehavior = (
server: McpServer,
session: BinarySessionPort,
contract: ToolContract<"find_changed_behavior">,
contract: (typeof SESSION_TOOL_CONTRACTS)[10],
policies: InvestigationToolPolicies,
): void => {
server.registerTool(
contract.name,
contractOptions(contract),
async (input, context) => {
const parsedInput = safeParseToolInput(
changedBehaviorInputSchema,
input,
contract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, contract);
const parsed = parsedInput.value;
const investigationRun = parsed.investigation_run;
const investigationRun = input.investigation_run;
if (investigationRun !== undefined)
return runAutomaticInvestigation({
server,
@@ -95,17 +81,17 @@ const registerChangedBehavior = (
contract,
policies,
investigationRun,
unknownRegistryApproved: parsed.unknown_registry_approved,
unknownRegistryApproved: input.unknown_registry_approved,
context,
});
const closure = evidenceClosure(
session,
comparisonClosure(parsed.comparisons),
comparisonClosure(input.comparisons),
);
if (!closure.ok) return toCallToolResult(closure, contract);
const links = closure.value;
const computed = await runDerivedOperation(context, contract.name, () =>
findChangedBehavior(parsed.comparisons, parsed.offset, parsed.limit),
findChangedBehavior(input.comparisons, input.offset, input.limit),
);
if (!computed.ok) return toCallToolResult(computed, contract);
const result = computed.value;
@@ -113,11 +99,11 @@ const registerChangedBehavior = (
predicateType: "rea.changed-behavior/v1",
operation: contract.name,
parameters: {
comparison_evidence_ids: parsed.comparisons.map(
comparison_evidence_ids: input.comparisons.map(
({ evidence_id: id }) => id,
),
offset: parsed.offset,
limit: parsed.limit,
offset: input.offset,
limit: input.limit,
},
result: jsonValueSchema.parse(result),
confidence: "derived",
@@ -128,7 +114,7 @@ const registerChangedBehavior = (
const recorded = recordWorkflowEvidence(
session,
evidence,
parsed.unknown_registry_approved,
input.unknown_registry_approved,
isIncomplete(result.behavior_status),
{
question:
@@ -153,7 +139,7 @@ const registerChangedBehavior = (
const runAutomaticInvestigation = async (input: {
readonly server: McpServer;
readonly session: BinarySessionPort;
readonly contract: ToolContract<"find_changed_behavior">;
readonly contract: (typeof SESSION_TOOL_CONTRACTS)[10];
readonly policies: InvestigationToolPolicies;
readonly investigationRun: NonNullable<
z.output<typeof changedBehaviorInputSchema>["investigation_run"]
@@ -253,27 +239,20 @@ const runAutomaticInvestigation = async (input: {
const registerCallPath = (
server: McpServer,
session: BinarySessionPort,
contract: ToolContract<"build_call_path">,
contract: (typeof SESSION_TOOL_CONTRACTS)[11],
): void => {
server.registerTool(
contract.name,
contractOptions(contract),
async (input, context) => {
const parsedInput = safeParseToolInput(
callPathInputSchema,
input,
contract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, contract);
const parsed = parsedInput.value;
const closure = evidenceClosure(
session,
functionEvidenceIds(parsed.functions),
functionEvidenceIds(input.functions),
);
if (!closure.ok) return toCallToolResult(closure, contract);
const links = closure.value;
const computed = await runDerivedOperation(context, contract.name, () =>
buildCallPath(parsed),
buildCallPath(input),
);
if (!computed.ok) return toCallToolResult(computed, contract);
const result = computed.value;
@@ -281,12 +260,12 @@ const registerCallPath = (
predicateType: "rea.call-path/v1",
operation: contract.name,
parameters: {
start: parsed.start.address,
goal: parsed.goal.address,
max_depth: parsed.max_depth,
max_paths: parsed.max_paths,
offset: parsed.offset,
limit: parsed.limit,
start: input.start.address,
goal: input.goal.address,
max_depth: input.max_depth,
max_paths: input.max_paths,
offset: input.offset,
limit: input.limit,
},
result: jsonValueSchema.parse(result),
confidence: "derived",
@@ -297,7 +276,7 @@ const registerCallPath = (
const recorded = recordWorkflowEvidence(
session,
evidence,
parsed.unknown_registry_approved,
input.unknown_registry_approved,
result.status === "unknown" || result.status === "truncated",
{
question:
@@ -322,30 +301,23 @@ const registerCallPath = (
const registerStaticRuntime = (
server: McpServer,
session: BinarySessionPort,
contract: ToolContract<"correlate_static_and_runtime">,
contract: (typeof SESSION_TOOL_CONTRACTS)[12],
): void => {
server.registerTool(
contract.name,
contractOptions(contract),
async (input, context) => {
const parsedInput = safeParseToolInput(
staticRuntimeCorrelationInputSchema,
input,
contract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, contract);
const parsed = parsedInput.value;
const closure = evidenceClosure(
session,
comparisonClosure([
...parsed.static_comparisons,
...parsed.runtime_comparisons,
...input.static_comparisons,
...input.runtime_comparisons,
]),
);
if (!closure.ok) return toCallToolResult(closure, contract);
const links = closure.value;
const computed = await runDerivedOperation(context, contract.name, () =>
correlateStaticAndRuntime(parsed),
correlateStaticAndRuntime(input),
);
if (!computed.ok) return toCallToolResult(computed, contract);
const result = computed.value;
@@ -353,9 +325,9 @@ const registerStaticRuntime = (
predicateType: "rea.static-runtime-correlation/v1",
operation: contract.name,
parameters: {
mapping_count: parsed.mappings.length,
offset: parsed.offset,
limit: parsed.limit,
mapping_count: input.mappings.length,
offset: input.offset,
limit: input.limit,
},
result: jsonValueSchema.parse(result),
confidence: "inferred",
@@ -367,7 +339,7 @@ const registerStaticRuntime = (
recordWorkflowEvidence(
session,
evidence,
parsed.unknown_registry_approved,
input.unknown_registry_approved,
result.status === "unknown" || result.status === "truncated",
{
question:
@@ -393,28 +365,21 @@ const registerStaticRuntime = (
const registerReconstruction = (
server: McpServer,
session: BinarySessionPort,
contract: ToolContract<"verify_reconstruction">,
contract: (typeof SESSION_TOOL_CONTRACTS)[13],
): void => {
server.registerTool(
contract.name,
contractOptions(contract),
async (input, context) => {
const parsedInput = safeParseToolInput(
reconstructionVerificationInputSchema,
input,
contract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, contract);
const parsed = parsedInput.value;
const coverage = verifyCoverageReadiness(session, parsed.coverage);
const coverage = verifyCoverageReadiness(session, input.coverage);
if (!coverage.ok) return toCallToolResult(coverage, contract);
const owned = session.exportEvidenceBundle();
const computed = await runDerivedOperation(context, contract.name, () =>
verifyReconstruction(
parsed.specification,
input.specification,
owned,
parsed.offset,
parsed.limit,
input.offset,
input.limit,
),
);
if (!computed.ok) return toCallToolResult(computed, contract);
@@ -427,9 +392,9 @@ const registerReconstruction = (
operation: contract.name,
parameters: {
specification_sha256: result.specification_sha256,
claim_ids: parsed.specification.claims.map(({ claim_id: id }) => id),
offset: parsed.offset,
limit: parsed.limit,
claim_ids: input.specification.claims.map(({ claim_id: id }) => id),
offset: input.offset,
limit: input.limit,
},
result: jsonValueSchema.parse(result),
confidence: "derived",
@@ -441,7 +406,7 @@ const registerReconstruction = (
recordWorkflowEvidence(
session,
evidence,
parsed.unknown_registry_approved,
input.unknown_registry_approved,
result.status === "unknown",
{
question: "Does the reconstruction satisfy every declared claim?",
@@ -1,5 +1,4 @@
import type { McpServer } from "@modelcontextprotocol/server";
import type { z } from "zod";
import type { McpServer, ServerContext } from "@modelcontextprotocol/server";
import type { BinarySessionPort } from "../application/BinarySession.js";
import type { JavaScriptRuntimeObservationPort } from "../application/JavaScriptRuntimeObservationPort.js";
@@ -12,14 +11,9 @@ import { JAVASCRIPT_RUNTIME_OBSERVATION_TOOL_CONTRACTS } from "../contracts/java
import type { ToolContract } from "../contracts/toolContracts.js";
import type { AnalysisError } from "../domain/errors.js";
import type { Evidence } from "../domain/evidence.js";
import {
listJavaScriptRuntimeTargetsInputSchema,
observeJavaScriptRuntimeInputSchema,
} from "../domain/javascriptRuntimeObservation.js";
import type { Result } from "../domain/result.js";
import type { Logger } from "../logger.js";
import { logToolExecution } from "./toolLogging.js";
import { safeParseToolInput } from "./toolInputValidation.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import { toCallToolResult } from "./toolResult.js";
@@ -30,15 +24,6 @@ interface RuntimeToolRegistration {
readonly recordEvidence: BinarySessionPort["recordEvidence"] | undefined;
}
interface RuntimeToolSpec<Schema extends z.ZodType> {
readonly contract: ToolContract;
readonly schema: Schema;
readonly execute: (
parsed: z.output<Schema>,
signal: AbortSignal,
) => Promise<Result<Evidence, AnalysisError>>;
}
/** Register passive Inspector tools even when policy keeps them unavailable. */
export const registerJavaScriptRuntimeObservationTools = (
server: McpServer,
@@ -46,53 +31,60 @@ export const registerJavaScriptRuntimeObservationTools = (
): void => {
const [listContract, observeContract] =
JAVASCRIPT_RUNTIME_OBSERVATION_TOOL_CONTRACTS;
registerRuntimeTool(server, options, {
contract: listContract,
schema: listJavaScriptRuntimeTargetsInputSchema,
execute: (parsed, signal) =>
listJavaScriptRuntimeTargets(
options.runtime,
options.permissionAuthority,
parsed,
{ signal },
),
});
registerRuntimeTool(server, options, {
contract: observeContract,
schema: observeJavaScriptRuntimeInputSchema,
execute: (parsed, signal) =>
observeJavaScriptRuntime(
options.runtime,
options.permissionAuthority,
parsed,
{ signal },
),
});
};
const registerRuntimeTool = <Schema extends z.ZodType>(
server: McpServer,
options: RuntimeToolRegistration,
spec: RuntimeToolSpec<Schema>,
): void => {
server.registerTool(
spec.contract.name,
toolRegistrationOptions(spec.contract),
async (input, context) => {
const parsed = safeParseToolInput(spec.schema, input, spec.contract.name);
if (!parsed.ok) return toCallToolResult(parsed, spec.contract);
const result = await logToolExecution(
options.logger,
spec.contract.name,
() => spec.execute(parsed.value, context.mcpReq.signal),
);
if (!result.ok) return toCallToolResult(result, spec.contract);
const recorded = options.recordEvidence?.(result.value);
return recorded !== undefined && !recorded.ok
? toCallToolResult(recorded, spec.contract)
: toCallToolResult({ ok: true, value: result.value }, spec.contract, {
evidenceResourcesAvailable: recorded !== undefined,
});
},
listContract.name,
toolRegistrationOptions(listContract),
(input, context) =>
runRuntimeTool(
options,
listContract,
{ input, context },
(parsed, signal) =>
listJavaScriptRuntimeTargets(
options.runtime,
options.permissionAuthority,
parsed,
{ signal },
),
),
);
server.registerTool(
observeContract.name,
toolRegistrationOptions(observeContract),
(input, context) =>
runRuntimeTool(
options,
observeContract,
{ input, context },
(parsed, signal) =>
observeJavaScriptRuntime(
options.runtime,
options.permissionAuthority,
parsed,
{ signal },
),
),
);
};
const runRuntimeTool = async <Input>(
options: RuntimeToolRegistration,
contract: ToolContract,
request: { readonly input: Input; readonly context: ServerContext },
execute: (
input: Input,
signal: AbortSignal,
) => Promise<Result<Evidence, AnalysisError>>,
) => {
const { input, context } = request;
const result = await logToolExecution(options.logger, contract.name, () =>
execute(input, context.mcpReq.signal),
);
if (!result.ok) return toCallToolResult(result, contract);
const recorded = options.recordEvidence?.(result.value);
return recorded !== undefined && !recorded.ok
? toCallToolResult(recorded, contract)
: toCallToolResult({ ok: true, value: result.value }, contract, {
evidenceResourcesAvailable: recorded !== undefined,
});
};
@@ -1,12 +1,10 @@
import type { McpServer } from "@modelcontextprotocol/server";
import { compareManagedMembersEvidenceValidated } from "../../application/ManagedMemberComparisonService.js";
import { compareManagedMembersReferenceInputSchema } from "../../contracts/managedWorkflowToolContracts.js";
import { managedMemberComparisonResultSchema } from "../../domain/managedMemberComparison.js";
import { logToolExecution } from "../toolLogging.js";
import { toCallToolResult } from "../toolResult.js";
import { toolRegistrationOptions } from "../toolRegistrationOptions.js";
import { safeParseToolInput } from "../toolInputValidation.js";
import { toCallToolResult } from "../toolResult.js";
import { managedWorkflowContract } from "./contract.js";
import { recordManagedSources, resolveManagedEvidence } from "./evidence.js";
import type { ManagedWorkflowToolRegistration } from "./types.js";
@@ -22,16 +20,9 @@ export const registerCompareManagedMembers = (
compareContract.name,
toolRegistrationOptions(compareContract),
async (input) => {
const parsedInput = safeParseToolInput(
compareManagedMembersReferenceInputSchema,
input,
compareContract.name,
);
if (!parsedInput.ok)
return toCallToolResult(parsedInput, compareContract);
const resolved = resolveManagedEvidence(options.session, [
parsedInput.value.left_evidence_id,
parsedInput.value.right_evidence_id,
input.left_evidence_id,
input.right_evidence_id,
]);
if (!resolved.ok) return toCallToolResult(resolved, compareContract);
const [left, right] = resolved.value;
@@ -41,7 +32,7 @@ export const registerCompareManagedMembers = (
left_evidence_id: _leftEvidenceId,
right_evidence_id: _rightEvidenceId,
...referencedInput
} = parsedInput.value;
} = input;
const parsed = { ...referencedInput, left, right };
const result = await logToolExecution(
options.logger,
@@ -1,12 +1,27 @@
import { MANAGED_WORKFLOW_TOOL_CONTRACTS } from "../../contracts/managedWorkflowToolContracts.js";
/** Locate one managed workflow tool contract by exact name. */
export const managedWorkflowContract = (
export function managedWorkflowContract(
name: "compare_managed_members",
): (typeof MANAGED_WORKFLOW_TOOL_CONTRACTS)[0];
export function managedWorkflowContract(
name: "verify_managed_native_boundaries",
): (typeof MANAGED_WORKFLOW_TOOL_CONTRACTS)[1];
export function managedWorkflowContract(
name: "import_managed_reconstruction",
): (typeof MANAGED_WORKFLOW_TOOL_CONTRACTS)[2];
export function managedWorkflowContract(
name: "plan_managed_runtime_correlation",
): (typeof MANAGED_WORKFLOW_TOOL_CONTRACTS)[3];
export function managedWorkflowContract(
name: "project_managed_application_graph",
): (typeof MANAGED_WORKFLOW_TOOL_CONTRACTS)[4];
export function managedWorkflowContract(
name: (typeof MANAGED_WORKFLOW_TOOL_CONTRACTS)[number]["name"],
) => {
) {
const found = MANAGED_WORKFLOW_TOOL_CONTRACTS.find(
(candidate) => candidate.name === name,
);
if (found === undefined) throw new Error(`Missing ${name} contract`);
return found;
};
}
@@ -1,11 +1,9 @@
import type { McpServer } from "@modelcontextprotocol/server";
import { importManagedReconstructionEvidenceValidated } from "../../application/ManagedReconstructionService.js";
import { managedReconstructionReferenceInputSchema } from "../../contracts/managedWorkflowToolContracts.js";
import { logToolExecution } from "../toolLogging.js";
import { toCallToolResult } from "../toolResult.js";
import { toolRegistrationOptions } from "../toolRegistrationOptions.js";
import { safeParseToolInput } from "../toolInputValidation.js";
import { toCallToolResult } from "../toolResult.js";
import { managedWorkflowContract } from "./contract.js";
import { resolveManagedEvidence } from "./evidence.js";
import type { ManagedWorkflowToolRegistration } from "./types.js";
@@ -23,15 +21,8 @@ export const registerImportManagedReconstruction = (
reconstructionContract.name,
toolRegistrationOptions(reconstructionContract),
async (input) => {
const parsedInput = safeParseToolInput(
managedReconstructionReferenceInputSchema,
input,
reconstructionContract.name,
);
if (!parsedInput.ok)
return toCallToolResult(parsedInput, reconstructionContract);
const resolved = resolveManagedEvidence(options.session, [
parsedInput.value.static_members_evidence_id,
input.static_members_evidence_id,
]);
if (!resolved.ok)
return toCallToolResult(resolved, reconstructionContract);
@@ -43,7 +34,7 @@ export const registerImportManagedReconstruction = (
const {
static_members_evidence_id: _staticMembersEvidenceId,
...referencedInput
} = parsedInput.value;
} = input;
const parsed = { ...referencedInput, static_members: staticMembers };
const result = await logToolExecution(
options.logger,
@@ -1,11 +1,9 @@
import type { McpServer } from "@modelcontextprotocol/server";
import { planManagedRuntimeCorrelationEvidenceValidated } from "../../application/ManagedRuntimeCorrelationService.js";
import { managedRuntimeCorrelationReferenceInputSchema } from "../../contracts/managedWorkflowToolContracts.js";
import { logToolExecution } from "../toolLogging.js";
import { toCallToolResult } from "../toolResult.js";
import { toolRegistrationOptions } from "../toolRegistrationOptions.js";
import { safeParseToolInput } from "../toolInputValidation.js";
import { toCallToolResult } from "../toolResult.js";
import { managedWorkflowContract } from "./contract.js";
import { resolveManagedEvidence } from "./evidence.js";
import type { ManagedWorkflowToolRegistration } from "./types.js";
@@ -23,15 +21,8 @@ export const registerPlanManagedRuntimeCorrelation = (
runtimeContract.name,
toolRegistrationOptions(runtimeContract),
async (input) => {
const parsedInput = safeParseToolInput(
managedRuntimeCorrelationReferenceInputSchema,
input,
runtimeContract.name,
);
if (!parsedInput.ok)
return toCallToolResult(parsedInput, runtimeContract);
const resolved = resolveManagedEvidence(options.session, [
parsedInput.value.static_members_evidence_id,
input.static_members_evidence_id,
]);
if (!resolved.ok) return toCallToolResult(resolved, runtimeContract);
const staticMembers = resolved.value[0];
@@ -40,7 +31,7 @@ export const registerPlanManagedRuntimeCorrelation = (
const {
static_members_evidence_id: _staticMembersEvidenceId,
...referencedInput
} = parsedInput.value;
} = input;
const parsed = { ...referencedInput, static_members: staticMembers };
const result = await logToolExecution(
options.logger,
@@ -1,11 +1,9 @@
import type { McpServer } from "@modelcontextprotocol/server";
import { projectManagedApplicationGraphEvidence } from "../../application/ManagedApplicationGraphService.js";
import { managedApplicationGraphReferenceInputSchema } from "../../contracts/managedWorkflowToolContracts.js";
import { logToolExecution } from "../toolLogging.js";
import { toCallToolResult } from "../toolResult.js";
import { toolRegistrationOptions } from "../toolRegistrationOptions.js";
import { safeParseToolInput } from "../toolInputValidation.js";
import { toCallToolResult } from "../toolResult.js";
import { managedWorkflowContract } from "./contract.js";
import {
recordManagedSources,
@@ -29,40 +27,34 @@ export const registerProjectManagedApplicationGraph = (
graphContract.name,
toolRegistrationOptions(graphContract),
async (input) => {
const parsedInput = safeParseToolInput(
managedApplicationGraphReferenceInputSchema,
input,
graphContract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, graphContract);
const managedArtifact =
parsedInput.value.managed_artifact_evidence_id === undefined
input.managed_artifact_evidence_id === undefined
? undefined
: resolveManagedArtifactEvidence(
options.session,
parsedInput.value.managed_artifact_evidence_id,
input.managed_artifact_evidence_id,
);
if (managedArtifact !== undefined && !managedArtifact.ok)
return toCallToolResult(managedArtifact, graphContract);
const managedMembers =
parsedInput.value.managed_members_evidence_id === undefined
input.managed_members_evidence_id === undefined
? undefined
: resolveManagedEvidence(options.session, [
parsedInput.value.managed_members_evidence_id,
input.managed_members_evidence_id,
]);
if (managedMembers !== undefined && !managedMembers.ok)
return toCallToolResult(managedMembers, graphContract);
const managedBoundaries =
parsedInput.value.managed_native_boundaries_evidence_id === undefined
input.managed_native_boundaries_evidence_id === undefined
? undefined
: resolveManagedBoundaryEvidence(
options.session,
parsedInput.value.managed_native_boundaries_evidence_id,
input.managed_native_boundaries_evidence_id,
);
if (managedBoundaries !== undefined && !managedBoundaries.ok)
return toCallToolResult(managedBoundaries, graphContract);
const parsed = {
limits: parsedInput.value.limits,
limits: input.limits,
managed_artifact: managedArtifact?.value[0],
managed_members: managedMembers?.value[0],
managed_native_boundaries: managedBoundaries?.value[0],
@@ -1,12 +1,10 @@
import type { McpServer } from "@modelcontextprotocol/server";
import { verifyManagedNativeBoundariesEvidence } from "../../application/ManagedNativeVerificationService.js";
import { managedNativeVerificationReferenceInputSchema } from "../../contracts/managedWorkflowToolContracts.js";
import { managedNativeVerificationResultSchema } from "../../domain/managedNativeVerification.js";
import { logToolExecution } from "../toolLogging.js";
import { toCallToolResult } from "../toolResult.js";
import { toolRegistrationOptions } from "../toolRegistrationOptions.js";
import { safeParseToolInput } from "../toolInputValidation.js";
import { toCallToolResult } from "../toolResult.js";
import { managedWorkflowContract } from "./contract.js";
import {
recordManagedSources,
@@ -28,22 +26,15 @@ export const registerVerifyManagedNativeBoundaries = (
nativeVerificationContract.name,
toolRegistrationOptions(nativeVerificationContract),
async (input) => {
const parsedInput = safeParseToolInput(
managedNativeVerificationReferenceInputSchema,
input,
nativeVerificationContract.name,
);
if (!parsedInput.ok)
return toCallToolResult(parsedInput, nativeVerificationContract);
const managedBoundaries = resolveManagedBoundaryEvidence(
options.session,
parsedInput.value.managed_boundaries_evidence_id,
input.managed_boundaries_evidence_id,
);
if (!managedBoundaries.ok)
return toCallToolResult(managedBoundaries, nativeVerificationContract);
const nativeObservations = resolveNativeEvidence(
options.session,
parsedInput.value.native_observation_evidence_ids,
input.native_observation_evidence_ids,
);
if (!nativeObservations.ok)
return toCallToolResult(nativeObservations, nativeVerificationContract);
@@ -54,7 +45,7 @@ export const registerVerifyManagedNativeBoundaries = (
managed_boundaries_evidence_id: _managedBoundariesEvidenceId,
native_observation_evidence_ids: _nativeObservationEvidenceIds,
...referencedInput
} = parsedInput.value;
} = input;
const parsed = {
...referencedInput,
managed_boundaries: managedBoundary,
+24 -24
View File
@@ -1,30 +1,32 @@
import type { McpServer } from "@modelcontextprotocol/server";
import { z } from "zod";
import type { AnalysisOperationPort } from "../application/AnalysisProvider.js";
import type { AnalysisExecution } from "../application/AnalysisProvider.js";
import type {
AnalysisExecution,
AnalysisOperationPort,
} from "../application/AnalysisProvider.js";
import type { BinarySessionPort } from "../application/BinarySession.js";
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 { createEvidence } from "../domain/evidence.js";
import {
jsonObjectSchema,
jsonValueSchema,
type JsonValue,
} from "../domain/jsonValue.js";
import { toCallToolResult } from "./toolResult.js";
import type { Logger } from "../logger.js";
import { logToolExecution } from "./toolLogging.js";
import type { BinaryTarget } from "../domain/binaryTarget.js";
import { createEvidence } from "../domain/evidence.js";
import {
AnalysisCapabilityUnavailableError,
type AnalysisError,
UnknownRegistryError,
} from "../domain/errors.js";
import { mcpProgressReporter } from "./mcpProgress.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import { safeParseToolInput } from "./toolInputValidation.js";
import type { ToolContract } from "../contracts/toolContracts.js";
import type { Result } from "../domain/result.js";
import type { ProgressReporter } from "../application/ProgressReporter.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";
/** Optional session services used by direct tool registration. */
export interface OfficialToolRegistration {
@@ -65,13 +67,7 @@ const registerOfficialTool = (
contract.name,
toolRegistrationOptions(contract),
async (input, context) => {
const parsedInput = safeParseToolInput(
contract.inputSchema,
input,
contract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, contract);
const arguments_ = projectOfficialArguments(contract, parsedInput.value);
const arguments_ = projectOfficialArguments(contract, input);
const progress = mcpProgressReporter(context);
const result = await runOfficialOperation(
analysis,
@@ -198,6 +194,10 @@ const projectOfficialArguments = (
input: unknown,
): Readonly<Record<string, JsonValue>> => {
const parsed = jsonObjectSchema.parse(input);
if (!(contract.inputSchema instanceof z.ZodObject))
throw new TypeError(
"Official tool input contract must be an object schema",
);
const projected: Record<string, JsonValue> = {};
for (const key of Object.keys(contract.inputSchema.shape)) {
+20 -31
View File
@@ -1,26 +1,22 @@
import type { McpServer } from "@modelcontextprotocol/server";
import type { BinarySessionPort } from "../application/BinarySession.js";
import {
processComparisonInputSchema,
SESSION_TOOL_CONTRACTS,
} from "../contracts/toolContracts.js";
import { createEvidence, type EvidenceLocation } from "../domain/evidence.js";
import { SESSION_TOOL_CONTRACTS } from "../contracts/toolContracts.js";
import { EvidenceIntegrityError } from "../domain/errors.js";
import { createEvidence, type EvidenceLocation } from "../domain/evidence.js";
import { jsonValueSchema } from "../domain/jsonValue.js";
import type { RecordUnknownInput } from "../domain/residualUnknown.js";
import {
compareProcessCaptures,
parseProcessCapture,
} from "../domain/processCapture.js";
import { recordDerivedEvidence } from "./recordDerivedEvidence.js";
import type { RecordUnknownInput } from "../domain/residualUnknown.js";
import { err } from "../domain/result.js";
import { PROCESS_PROVIDER } from "./sessionToolPolicies.js";
import { toCallToolResult } from "./toolResult.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import { recordDerivedEvidence } from "./recordDerivedEvidence.js";
import { runDerivedOperation } from "./runDerivedOperation.js";
import { safeParseToolInput } from "./toolInputValidation.js";
import { resolveSessionEvidenceIds } from "./sessionEvidence.js";
import { PROCESS_PROVIDER } from "./sessionToolPolicies.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import { toCallToolResult } from "./toolResult.js";
const PROCESS_CAPTURE_EVIDENCE = {
operation: "capture_process_scenario",
@@ -43,22 +39,15 @@ export const registerProcessComparisonTool = (
contract.name,
toolRegistrationOptions(contract),
async (input, context) => {
const parsedInput = safeParseToolInput(
processComparisonInputSchema,
input,
contract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, contract);
const parsed = parsedInput.value;
const leftRecord = resolveSessionEvidenceIds(
session,
[parsed.left_evidence_id],
[input.left_evidence_id],
PROCESS_CAPTURE_EVIDENCE,
);
if (!leftRecord.ok) return toCallToolResult(leftRecord, contract);
const rightRecord = resolveSessionEvidenceIds(
session,
[parsed.right_evidence_id],
[input.right_evidence_id],
PROCESS_CAPTURE_EVIDENCE,
);
if (!rightRecord.ok) return toCallToolResult(rightRecord, contract);
@@ -74,12 +63,12 @@ export const registerProcessComparisonTool = (
);
const computed = await runDerivedOperation(context, contract.name, () =>
compareProcessCaptures(leftCapture, rightCapture, {
...(parsed.max_capture_age_ms === undefined
...(input.max_capture_age_ms === undefined
? {}
: { maxCaptureAgeMs: parsed.max_capture_age_ms }),
...(parsed.trace_spec === undefined
: { maxCaptureAgeMs: input.max_capture_age_ms }),
...(input.trace_spec === undefined
? {}
: { traceSpecification: parsed.trace_spec }),
: { traceSpecification: input.trace_spec }),
now,
}),
);
@@ -99,18 +88,18 @@ export const registerProcessComparisonTool = (
}
const evidence = createEvidence(undefined, PROCESS_PROVIDER, {
predicateType:
parsed.trace_spec === undefined
input.trace_spec === undefined
? "rea.process-comparison/v3"
: "rea.process-comparison/v4",
operation: contract.name,
parameters: {
left_evidence_id: parsed.left_evidence_id,
right_evidence_id: parsed.right_evidence_id,
left_evidence_id: input.left_evidence_id,
right_evidence_id: input.right_evidence_id,
left_normalization: leftCapture.normalization,
right_normalization: rightCapture.normalization,
...(parsed.trace_spec === undefined
...(input.trace_spec === undefined
? {}
: { trace_spec: jsonValueSchema.parse(parsed.trace_spec) }),
: { trace_spec: jsonValueSchema.parse(input.trace_spec) }),
},
result: jsonValueSchema.parse(comparison),
confidence: "derived",
@@ -120,13 +109,13 @@ export const registerProcessComparisonTool = (
leftRecord.value[0]?.locations,
rightRecord.value[0]?.locations,
),
evidenceLinks: [parsed.left_evidence_id, parsed.right_evidence_id],
evidenceLinks: [input.left_evidence_id, input.right_evidence_id],
});
return toCallToolResult(
recordDerivedEvidence(
session,
evidence,
comparisonUnknownInput(parsed, comparison),
comparisonUnknownInput(input, comparison),
),
contract,
);
+4 -18
View File
@@ -1,22 +1,14 @@
import type { McpServer } from "@modelcontextprotocol/server";
import { SESSION_TOOL_CONTRACTS } from "../contracts/toolContracts.js";
import {
replayMachineRunInputSchema,
runReplayMachine,
} from "../domain/replayMachineRun.js";
import { runReplayMachine } from "../domain/replayMachineRun.js";
import { ok } from "../domain/result.js";
import type { Logger } from "../logger.js";
import { safeParseToolInput } from "./toolInputValidation.js";
import { logToolExecution } from "./toolLogging.js";
import { toCallToolResult } from "./toolResult.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import { toCallToolResult } from "./toolResult.js";
const contract = SESSION_TOOL_CONTRACTS.find(
({ name }) => name === "run_replay_machine",
);
if (contract === undefined)
throw new TypeError("Missing run_replay_machine tool contract");
const contract = SESSION_TOOL_CONTRACTS[18];
/** Register direct execution-free finite replay-machine evaluation. */
export const registerReplayMachineTool = (
@@ -27,14 +19,8 @@ export const registerReplayMachineTool = (
contract.name,
toolRegistrationOptions(contract),
async (input) => {
const parsed = safeParseToolInput(
replayMachineRunInputSchema,
input,
contract.name,
);
if (!parsed.ok) return toCallToolResult(parsed, contract);
const result = await logToolExecution(logger, contract.name, () =>
Promise.resolve(ok(runReplayMachine(parsed.value))),
Promise.resolve(ok(runReplayMachine(input))),
);
return toCallToolResult(result, contract);
},
+24 -90
View File
@@ -1,35 +1,22 @@
import type { McpServer } from "@modelcontextprotocol/server";
import type { BinarySessionPort } from "../application/BinarySession.js";
import type { PermissionAuthority } from "../application/PermissionAuthority.js";
import {
readEvidenceBundle,
writeEvidenceBundle,
} from "../application/EvidenceBundleFiles.js";
import {
exportEvidenceBundleInputSchema,
importEvidenceBundleInputSchema,
listUnknownsInputSchema,
releaseEvidenceBundleInputSchema,
snapshotEvidenceBundleInputSchema,
SESSION_TOOL_CONTRACTS,
verifyUnknownResolutionInputSchema,
} from "../contracts/toolContracts.js";
import type {
EvidenceBundle,
EvidenceFilePolicy,
} from "../domain/evidenceBundle.js";
import type { PermissionAuthority } from "../application/PermissionAuthority.js";
import { SESSION_TOOL_CONTRACTS } from "../contracts/toolContracts.js";
import {
AnalysisProtocolError,
PermissionRequiredError,
type AnalysisError,
} from "../domain/errors.js";
import {
recordUnknownInputSchema,
updateUnknownInputSchema,
} from "../domain/residualUnknown.js";
import type {
EvidenceBundle,
EvidenceFilePolicy,
} from "../domain/evidenceBundle.js";
import { err, ok, type Result } from "../domain/result.js";
import { safeParseToolInput } from "./toolInputValidation.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import { toCallToolResult } from "./toolResult.js";
@@ -64,30 +51,22 @@ const registerReleaseEvidenceTool = ({
releaseContract.name,
toolRegistrationOptions(releaseContract),
async (input) => {
const parsed = safeParseToolInput(
releaseEvidenceBundleInputSchema,
input,
releaseContract.name,
);
if (!parsed.ok) return toCallToolResult(parsed, releaseContract);
const denied = await authorizeEvidenceWrite({
authority: permissionAuthority,
operationIdentity: `release_evidence:${parsed.value.bundle_digest}`,
operationIdentity: `release_evidence:${input.bundle_digest}`,
});
if (denied !== undefined)
return toCallToolResult(denied, releaseContract);
const released = session.releaseEvidenceBundle(
parsed.value.bundle_digest,
);
const released = session.releaseEvidenceBundle(input.bundle_digest);
if (released)
void server.server
.sendResourceUpdated({
uri: `rea://evidence-bundle/${parsed.value.bundle_digest}`,
uri: `rea://evidence-bundle/${input.bundle_digest}`,
})
.catch(() => undefined);
return toCallToolResult(
ok({
bundle_digest: parsed.value.bundle_digest,
bundle_digest: input.bundle_digest,
released,
}),
releaseContract,
@@ -130,26 +109,19 @@ const registerExportEvidenceTool = ({
exportContract.name,
toolRegistrationOptions(exportContract),
async (input) => {
const parsedInput = safeParseToolInput(
exportEvidenceBundleInputSchema,
input,
exportContract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, exportContract);
const parsed = parsedInput.value;
const bundle = session.exportEvidenceBundle();
const denied = await authorizeEvidencePath({
authority: permissionAuthority,
capability: "evidence_write",
path: parsed.path,
path: input.path,
access: "write",
operationIdentity: `export_evidence:${parsed.path}`,
operationIdentity: `export_evidence:${input.path}`,
});
if (denied !== undefined) return toCallToolResult(denied, exportContract);
const written = await writeEvidenceBundle(
bundle,
parsed.path,
parsed.overwrite,
input.path,
input.overwrite,
filePolicy,
);
return written.ok
@@ -175,13 +147,7 @@ const registerSnapshotEvidenceTool = ({
server.registerTool(
snapshotContract.name,
toolRegistrationOptions(snapshotContract),
(input) => {
const parsed = safeParseToolInput(
snapshotEvidenceBundleInputSchema,
input,
snapshotContract.name,
);
if (!parsed.ok) return toCallToolResult(parsed, snapshotContract);
() => {
const snapshot = session.snapshotEvidenceBundle();
if (!snapshot.ok) return toCallToolResult(snapshot, snapshotContract);
const value = {
@@ -218,13 +184,7 @@ const registerImportEvidenceTool = ({
importContract.name,
toolRegistrationOptions(importContract),
async (input) => {
const parsedInput = safeParseToolInput(
importEvidenceBundleInputSchema,
input,
importContract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, importContract);
const path = parsedInput.value.path;
const path = input.path;
const denied = await authorizeEvidencePath({
authority: permissionAuthority,
capability: "evidence_read",
@@ -306,13 +266,7 @@ const registerListUnknownsTool = ({
listContract.name,
toolRegistrationOptions(listContract),
(input) => {
const parsed = safeParseToolInput(
listUnknownsInputSchema,
input,
listContract.name,
);
if (!parsed.ok) return toCallToolResult(parsed, listContract);
const filters = parsed.value;
const filters = input;
const all = session.listUnknowns({
...(filters.status === undefined ? {} : { status: filters.status }),
...(filters.severity === undefined
@@ -362,13 +316,7 @@ const registerRecordUnknownTool = ({
recordContract.name,
toolRegistrationOptions(recordContract),
(input) => {
const parsed = safeParseToolInput(
recordUnknownInputSchema,
input,
recordContract.name,
);
if (!parsed.ok) return toCallToolResult(parsed, recordContract);
const result = session.recordUnknown(parsed.value);
const result = session.recordUnknown(input);
return result.ok
? toCallToolResult(result, recordContract, {
resourceLinks: [
@@ -394,13 +342,7 @@ const registerUpdateUnknownTool = ({
updateContract.name,
toolRegistrationOptions(updateContract),
(input) => {
const parsed = safeParseToolInput(
updateUnknownInputSchema,
input,
updateContract.name,
);
if (!parsed.ok) return toCallToolResult(parsed, updateContract);
const result = session.updateUnknown(parsed.value);
const result = session.updateUnknown(input);
if (result.ok)
void server.server
.sendResourceUpdated({
@@ -431,19 +373,11 @@ const registerVerifyUnknownTool = ({
server.registerTool(
verifyContract.name,
toolRegistrationOptions(verifyContract),
(input) => {
const parsed = safeParseToolInput(
verifyUnknownResolutionInputSchema,
input,
verifyContract.name,
);
return parsed.ok
? toCallToolResult(
session.verifyUnknownResolution(parsed.value.unknown_id),
verifyContract,
)
: toCallToolResult(parsed, verifyContract);
},
(input) =>
toCallToolResult(
session.verifyUnknownResolution(input.unknown_id),
verifyContract,
),
);
};
+16 -33
View File
@@ -2,18 +2,18 @@ import type { McpServer } from "@modelcontextprotocol/server";
import type { z } from "zod";
import type { BinarySessionPort } from "../application/BinarySession.js";
import { buildCapabilityInventory } from "../application/CapabilityInventory.js";
import {
binarySessionInputSchema,
SESSION_TOOL_CONTRACTS,
} from "../contracts/toolContracts.js";
import { toCallToolResult } from "./toolResult.js";
import type { ClientFeatureAvailability } from "../contracts/toolOutputSchemaPrimitives.js";
import { jsonObjectSchema } from "../domain/jsonValue.js";
import { createServerIdentity } from "../serverIdentity.js";
import { buildCapabilityInventory } from "../application/CapabilityInventory.js";
import type { ClientFeatureAvailability } from "../contracts/toolOutputSchemaPrimitives.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import { safeParseToolInput } from "./toolInputValidation.js";
import { mcpClientMetadata } from "./mcpClientMetadata.js";
import type { SessionAvailability } from "./sessionAvailabilityPolicy.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import { toCallToolResult } from "./toolResult.js";
type BinarySessionInput = z.output<typeof binarySessionInputSchema>;
type ToolAvailability = ReturnType<typeof buildCapabilityInventory>[number];
@@ -35,22 +35,9 @@ export const registerSessionStatusTool = (
server.registerTool(
contract.name,
toolRegistrationOptions(contract),
(input) => {
const parsedInput = safeParseToolInput(
binarySessionInputSchema,
input,
contract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, contract);
const parsed = parsedInput.value;
const client = server.server.getClientVersion();
const clientCapabilities = server.server.getClientCapabilities();
const clientFeatures: ClientFeatureAvailability = {
elicitation_form: clientCapabilities?.elicitation?.form !== undefined,
elicitation_url: clientCapabilities?.elicitation?.url !== undefined,
roots: clientCapabilities?.roots !== undefined,
sampling: clientCapabilities?.sampling !== undefined,
};
(input, context) => {
const { client, clientFeatures, protocolVersion } =
mcpClientMetadata(context);
const status = session.status();
const statusObject = jsonObjectSchema.parse(status);
const toolAvailability = buildCapabilityInventory(
@@ -61,28 +48,24 @@ export const registerSessionStatusTool = (
const serverIdentity = createServerIdentity({
startedAt,
expected: {
...(parsed.expected_package_version === undefined
...(input.expected_package_version === undefined
? {}
: { package_version: parsed.expected_package_version }),
...(parsed.expected_catalog_digest === undefined
: { package_version: input.expected_package_version }),
...(input.expected_catalog_digest === undefined
? {}
: { catalog_digest: parsed.expected_catalog_digest }),
...(parsed.expected_server_path === undefined
: { catalog_digest: input.expected_catalog_digest }),
...(input.expected_server_path === undefined
? {}
: { server_path: parsed.expected_server_path }),
: { server_path: input.expected_server_path }),
},
...(client === undefined ? {} : { client }),
...(server.server.getNegotiatedProtocolVersion() === undefined
? {}
: {
protocolVersion: server.server.getNegotiatedProtocolVersion(),
}),
...(protocolVersion === undefined ? {} : { protocolVersion }),
});
return toCallToolResult(
{
ok: true,
value: projectSessionStatus({
input: parsed,
input: input,
status: statusObject,
toolAvailability,
serverIdentity,
+47 -89
View File
@@ -1,65 +1,58 @@
import type { McpServer } from "@modelcontextprotocol/server";
import { z } from "zod";
import type { BinarySessionPort } from "../application/BinarySession.js";
import { isInputRequiredResult } from "@modelcontextprotocol/server";
import {
addressContextInputSchema,
navigationContextInputSchema,
SESSION_TOOL_CONTRACTS,
} from "../contracts/toolContracts.js";
import { toCallToolResult } from "./toolResult.js";
import type { Logger } from "../logger.js";
import { logToolExecution } from "./toolLogging.js";
import { ok, type Result } from "../domain/result.js";
getNavigationContext,
inspectAddressContext,
} from "../application/AnalysisContextQueries.js";
import { readAnalysisSnapshot } from "../application/AnalysisSnapshotFiles.js";
import type { BinarySessionPort } from "../application/BinarySession.js";
import type { PermissionAuthority } from "../application/PermissionAuthority.js";
import { processCapturePermissionRequest } from "../application/ProcessCapturePermission.js";
import { createProcessCaptureEvidence } from "../application/ProcessEvidence.js";
import { captureProcessScenario } from "../application/ProcessHarness.js";
import { SESSION_TOOL_CONTRACTS } from "../contracts/toolContracts.js";
import type { AnalysisSnapshot } from "../domain/analysisSnapshot.js";
import { UnknownRegistryError, type AnalysisError } from "../domain/errors.js";
import type { Evidence } from "../domain/evidence.js";
import type { EvidenceFilePolicy } from "../domain/evidenceBundle.js";
import type {
ProcessCapture,
ProcessExecutionPolicy,
ProcessScenario,
} from "../domain/processCapture.js";
import { processScenarioSchema } from "../domain/processCapture.js";
import { captureProcessScenario } from "../application/ProcessHarness.js";
import { processCapturePermissionRequest } from "../application/ProcessCapturePermission.js";
import type { Evidence } from "../domain/evidence.js";
import type { AnalysisSnapshot } from "../domain/analysisSnapshot.js";
import type { EvidenceFilePolicy } from "../domain/evidenceBundle.js";
import { readAnalysisSnapshot } from "../application/AnalysisSnapshotFiles.js";
import { UnknownRegistryError, type AnalysisError } from "../domain/errors.js";
import {
DENY_EVIDENCE_FILE_POLICY,
DENY_PROCESS_POLICY,
} from "./sessionToolPolicies.js";
import { createProcessCaptureEvidence } from "../application/ProcessEvidence.js";
import { registerProcessComparisonTool } from "./registerProcessComparisonTool.js";
import { registerArtifactComparisonTool } from "./registerArtifactComparisonTool.js";
import { registerFunctionComparisonTool } from "./registerFunctionComparisonTool.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import { safeParseToolInput } from "./toolInputValidation.js";
import { registerBundleComparisonTool } from "./registerBundleComparisonTool.js";
import { registerInvestigationTools } from "./registerInvestigationTools.js";
import { openBinaryInputSchema } from "../contracts/sessionLifecycleInputs.js";
import { registerSessionStatusTool } from "./registerSessionStatusTool.js";
import type { PermissionAuthority } from "../application/PermissionAuthority.js";
import { ok, type Result } from "../domain/result.js";
import type { Logger } from "../logger.js";
import { mcpProgressReporter } from "./mcpProgress.js";
import { permissionFailure } from "./permissionFailure.js";
import {
authorizeProcessCaptureWithElicitation,
type ProcessCaptureElicitation,
} from "./ProcessCaptureElicitation.js";
import { isInputRequiredResult } from "@modelcontextprotocol/server";
import { registerArtifactComparisonTool } from "./registerArtifactComparisonTool.js";
import { registerBundleComparisonTool } from "./registerBundleComparisonTool.js";
import { registerCloseLifecycleTool } from "./registerCloseLifecycleTool.js";
import { registerFunctionComparisonTool } from "./registerFunctionComparisonTool.js";
import { registerInvestigationTools } from "./registerInvestigationTools.js";
import { registerProcessComparisonTool } from "./registerProcessComparisonTool.js";
import { registerReplayMachineTool } from "./registerReplayMachineTool.js";
import {
registerEvidenceTools,
registerUnknownTools,
} from "./registerSessionRecordTools.js";
import { registerReplayMachineTool } from "./registerReplayMachineTool.js";
import { registerSessionStatusTool } from "./registerSessionStatusTool.js";
import {
sessionAvailabilityPolicy,
type SessionAvailability,
} from "./sessionAvailabilityPolicy.js";
import { permissionFailure } from "./permissionFailure.js";
import { registerCloseLifecycleTool } from "./registerCloseLifecycleTool.js";
import {
getNavigationContext,
inspectAddressContext,
} from "../application/AnalysisContextQueries.js";
DENY_EVIDENCE_FILE_POLICY,
DENY_PROCESS_POLICY,
} from "./sessionToolPolicies.js";
import { logToolExecution } from "./toolLogging.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import { toCallToolResult } from "./toolResult.js";
const recordProcessResidualUnknowns = (
session: BinarySessionPort,
@@ -104,7 +97,7 @@ interface ProcessToolRegistration {
readonly server: McpServer;
readonly session: BinarySessionPort;
readonly logger: Logger;
readonly processPolicy: ProcessExecutionPolicy;
readonly processPolicy: () => ProcessExecutionPolicy;
readonly captureContract: (typeof SESSION_TOOL_CONTRACTS)[5];
readonly permissionAuthority?: PermissionAuthority;
readonly processCaptureElicitation?: ProcessCaptureElicitation;
@@ -123,14 +116,7 @@ const registerProcessTools = ({
captureContract.name,
toolRegistrationOptions(captureContract),
async (input, context) => {
const parsedInput = safeParseToolInput(
processScenarioSchema,
input,
captureContract.name,
);
if (!parsedInput.ok)
return toCallToolResult(parsedInput, captureContract);
const scenario = parsedInput.value;
const scenario = input;
if (permissionAuthority !== undefined) {
const request = processCapturePermissionRequest(scenario);
const authorized =
@@ -162,7 +148,7 @@ const registerProcessTools = ({
() =>
captureProcessScenario(
scenario,
processPolicy,
processPolicy(),
context.mcpReq.signal,
),
);
@@ -232,25 +218,18 @@ const registerOpenLifecycleTool = ({
openContract.name,
toolRegistrationOptions(openContract),
async (input, context) => {
const parsedInput = safeParseToolInput(
openBinaryInputSchema,
input,
openContract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, openContract);
const parsed = parsedInput.value;
let snapshot: AnalysisSnapshot | undefined;
if (parsed.snapshot_path !== undefined) {
if (input.snapshot_path !== undefined) {
if (permissionAuthority !== undefined) {
const authorized = await permissionAuthority.authorize(
{
capability: "snapshot_read",
roots: [parsed.snapshot_path],
roots: [input.snapshot_path],
executables: [],
environment_names: [],
network: "none",
mount: false,
operation_identity: `open_binary:snapshot:${parsed.snapshot_path}`,
operation_identity: `open_binary:snapshot:${input.snapshot_path}`,
},
"read",
);
@@ -261,22 +240,21 @@ const registerOpenLifecycleTool = ({
);
}
const loaded = await readAnalysisSnapshot(
parsed.snapshot_path,
input.snapshot_path,
snapshotFilePolicy,
);
if (!loaded.ok) return toCallToolResult(loaded, openContract);
snapshot = loaded.value;
}
const opened = await logToolExecution(logger, openContract.name, () =>
session.open(parsed.path, {
session.open(input.path, {
signal: context.mcpReq.signal,
...(parsed.provider_id === undefined
...(input.provider_id === undefined
? {}
: { providerId: parsed.provider_id }),
: { providerId: input.provider_id }),
...(snapshot === undefined ? {} : { snapshot }),
}),
);
if (opened.ok) server.sendToolListChanged();
return opened.ok
? toCallToolResult(
{
@@ -301,7 +279,7 @@ const registerOpenLifecycleTool = ({
/** Register MCP-only target lifecycle operations on a long-lived session. */
export interface SessionToolOptions {
readonly processPolicy?: ProcessExecutionPolicy;
readonly processPolicy?: () => ProcessExecutionPolicy;
readonly evidenceFilePolicy?: EvidenceFilePolicy;
readonly investigationInputRoots?: readonly string[];
readonly analysisSnapshotFilePolicy?: EvidenceFilePolicy;
@@ -335,18 +313,8 @@ const registerContextTools = (
navigationContract.name,
toolRegistrationOptions(navigationContract),
async (input, context) => {
const parsed = safeParseToolInput(
navigationContextInputSchema,
input,
navigationContract.name,
);
if (!parsed.ok) return toCallToolResult(parsed, navigationContract);
return toCallToolResult(
await getNavigationContext(
session,
parsed.value,
context.mcpReq.signal,
),
await getNavigationContext(session, input, context.mcpReq.signal),
navigationContract,
);
},
@@ -355,18 +323,8 @@ const registerContextTools = (
addressContract.name,
toolRegistrationOptions(addressContract),
async (input, context) => {
const parsed = safeParseToolInput(
addressContextInputSchema,
input,
addressContract.name,
);
if (!parsed.ok) return toCallToolResult(parsed, addressContract);
return toCallToolResult(
await inspectAddressContext(
session,
parsed.value,
context.mcpReq.signal,
),
await inspectAddressContext(session, input, context.mcpReq.signal),
addressContract,
);
},
@@ -379,7 +337,7 @@ export const registerSessionTools = (
logger: Logger,
options: SessionToolOptions = {},
): void => {
const processPolicy = options.processPolicy ?? DENY_PROCESS_POLICY;
const processPolicy = options.processPolicy ?? (() => DENY_PROCESS_POLICY);
const evidenceFilePolicy =
options.evidenceFilePolicy ?? DENY_EVIDENCE_FILE_POLICY;
const analysisSnapshotFilePolicy =
@@ -410,7 +368,7 @@ export const registerSessionTools = (
snapshotFilePolicy: analysisSnapshotFilePolicy,
startedAt: options.startedAt ?? new Date().toISOString(),
availabilityPolicy: sessionAvailabilityPolicy(options.availabilityPolicy, {
processPolicy,
processPolicy: processPolicy(),
evidenceFilePolicy,
investigationInputRoots: options.investigationInputRoots ?? [],
}),
+5 -15
View File
@@ -1,3 +1,4 @@
import type { ServerContext } from "@modelcontextprotocol/server";
import { setImmediate } from "node:timers/promises";
import {
@@ -5,22 +6,11 @@ import {
AnalysisInputError,
} from "../domain/errors.js";
import { err, ok, type Result } from "../domain/result.js";
import { mcpProgressReporter } from "./mcpProgress.js";
import { mcpProgressReporter, type McpProgressContext } from "./mcpProgress.js";
export interface DerivedOperationContext {
readonly mcpReq: {
readonly signal: AbortSignal;
readonly _meta?: { readonly progressToken?: string | number | undefined };
notify(notification: {
readonly method: "notifications/progress";
readonly params: {
readonly progressToken: string | number;
readonly progress: number;
readonly total?: number;
readonly message?: string;
};
}): Promise<void>;
};
export interface DerivedOperationContext extends McpProgressContext {
readonly mcpReq: McpProgressContext["mcpReq"] &
Pick<ServerContext["mcpReq"], "signal">;
}
/** Run synchronous derived work with transport yields and a publication guard. */
+1 -1
View File
@@ -27,7 +27,7 @@ export const sessionAvailabilityPolicy = (
): (() => SessionAvailability) =>
configured ??
(() => ({
processCaptureEnabled: defaults.processPolicy.enabled,
processCaptureEnabled: defaults.processPolicy.status === "enabled",
evidenceFileRoots: defaults.evidenceFilePolicy.roots.length,
investigationInputRoots: defaults.investigationInputRoots.length,
browserObservationEnabled:
+1 -5
View File
@@ -3,11 +3,7 @@ import type { ProcessExecutionPolicy } from "../domain/processCapture.js";
/** Fail-closed process policy used when operator configuration is absent. */
export const DENY_PROCESS_POLICY: ProcessExecutionPolicy = {
enabled: false,
executableRoots: [],
workingRoots: [],
allowedEnvironment: [],
allowExternalNetwork: false,
status: "disabled",
};
/** Fail-closed evidence filesystem policy used without approved roots. */
-129
View File
@@ -1,129 +0,0 @@
import { z } from "zod";
import {
AnalysisInputError,
type AnalysisInputIssue,
} from "../domain/errors.js";
import { projectInputIssues } from "../domain/inputIssueProjection.js";
import { err, ok, type Result } from "../domain/result.js";
import { closeObjectSchemas } from "./toolRegistrationOptions.js";
/** Parse one MCP request exactly once and retain only schema-owned correction data. */
export const safeParseToolInput = <Schema extends z.ZodType>(
schema: Schema,
input: unknown,
operation: string,
): Result<z.output<Schema>, AnalysisInputError> => {
const unknownIssues = unknownArgumentIssues(schema, input);
if (unknownIssues.length > 0)
return err(new AnalysisInputError(operation, undefined, unknownIssues));
const parsed = schema.safeParse(input);
return parsed.success
? ok(parsed.data)
: err(
new AnalysisInputError(
operation,
undefined,
projectInputIssues(parsed.error.issues, input),
),
);
};
const schemaCache = new WeakMap<z.ZodType, Readonly<Record<string, unknown>>>();
const unknownArgumentIssues = (
schema: z.ZodType,
input: unknown,
): readonly AnalysisInputIssue[] => {
let jsonSchema = schemaCache.get(schema);
if (jsonSchema === undefined) {
const converter = schema["~standard"].jsonSchema?.input;
if (converter === undefined)
throw new TypeError(
"Tool input schema does not expose Standard JSON Schema",
);
jsonSchema = closeObjectSchemas(converter({ target: "draft-2020-12" }));
schemaCache.set(schema, jsonSchema);
}
return scanUnknownArguments(input, jsonSchema, jsonSchema, []);
};
const scanUnknownArguments = (
value: unknown,
schema: Readonly<Record<string, unknown>>,
root: Readonly<Record<string, unknown>>,
path: readonly (string | number)[],
): AnalysisInputIssue[] => {
const resolved = resolveSchema(schema, root);
if (Array.isArray(value)) {
const items = objectValue(resolved.items);
return items === undefined
? []
: value.flatMap((item, index) =>
scanUnknownArguments(item, items, root, [...path, index]),
);
}
if (!isObject(value)) return [];
const variants = schemaVariants(resolved, root);
const properties = Object.fromEntries(
variants.flatMap((variant) =>
Object.entries(objectValue(variant.properties) ?? {}),
),
);
const closed =
variants.length > 0 &&
variants.every(
(variant) =>
variant.additionalProperties !== true &&
!isObject(variant.additionalProperties),
);
const issues: AnalysisInputIssue[] = [];
for (const [key, child] of Object.entries(value)) {
const propertySchema = objectValue(properties[key]);
if (propertySchema === undefined) {
if (closed)
issues.push({ path: [...path, key], reason: "unknown_argument" });
continue;
}
issues.push(
...scanUnknownArguments(child, propertySchema, root, [...path, key]),
);
}
return issues;
};
const schemaVariants = (
schema: Readonly<Record<string, unknown>>,
root: Readonly<Record<string, unknown>>,
): readonly Readonly<Record<string, unknown>>[] => {
const resolved = resolveSchema(schema, root);
const variants = [resolved.oneOf, resolved.anyOf, resolved.allOf]
.flatMap((value) => (Array.isArray(value) ? value : []))
.flatMap((value) => {
const object = objectValue(value);
return object === undefined ? [] : schemaVariants(object, root);
});
if (variants.length > 0) return variants;
return resolved.type === "object" || isObject(resolved.properties)
? [resolved]
: [];
};
const resolveSchema = (
schema: Readonly<Record<string, unknown>>,
root: Readonly<Record<string, unknown>>,
): Readonly<Record<string, unknown>> => {
const reference = schema.$ref;
if (typeof reference !== "string" || !reference.startsWith("#/$defs/"))
return schema;
const definition = objectValue(objectValue(root.$defs)?.[reference.slice(8)]);
return definition === undefined ? schema : definition;
};
const isObject = (value: unknown): value is Readonly<Record<string, unknown>> =>
typeof value === "object" && value !== null && !Array.isArray(value);
const objectValue = (
value: unknown,
): Readonly<Record<string, unknown>> | undefined =>
isObject(value) ? value : undefined;
+13 -257
View File
@@ -1,263 +1,19 @@
import { z } from "zod";
import type { ToolContract } from "../contracts/toolContracts.js";
import { applyToolInputJsonSchemaOverride } from "../contracts/toolSchemaJsonOverrides.js";
import { toolInputSchemaWithMetadata } from "../contracts/toolSchemaMetadata.js";
const ADVERTISED_INPUT_SCHEMAS = new WeakMap<
z.ZodObject,
Readonly<Record<string, unknown>>
>();
const ADVERTISED_OUTPUT_SCHEMAS = new WeakMap<
z.ZodObject,
Readonly<Record<string, unknown>>
>();
/** Project the public contract fields accepted by MCP tool registration. */
export const toolRegistrationOptions = (contract: ToolContract) => ({
/** Project the canonical Zod contracts directly into SDK registration. */
export const toolRegistrationOptions = <Contract extends ToolContract>(
contract: Contract,
): {
readonly title: Contract["title"];
readonly description: Contract["description"];
readonly inputSchema: Contract["inputSchema"];
readonly outputSchema: Contract["outputSchema"];
readonly annotations: Contract["annotations"];
} => ({
title: contract.title,
description: contract.description,
inputSchema: advertisedInputSchema(contract),
outputSchema: advertisedOutputSchema(contract.outputSchema),
inputSchema: toolInputSchemaWithMetadata(contract),
outputSchema: contract.outputSchema,
annotations: contract.annotations,
});
/**
* Advertise the exact Zod contract while leaving validation to REA's adapter.
* The SDK otherwise converts validation failures to text-only JSON-RPC errors
* before REA can return its stable structured error envelope.
*/
const advertisedInputSchema = (contract: ToolContract) => ({
"~standard": {
version: 1 as const,
vendor: "rea",
validate: (input: unknown) => ({ value: input }),
jsonSchema: {
input: () => advertisedInputJsonSchema(contract),
output: () => advertisedInputJsonSchema(contract),
},
},
});
const advertisedOutputSchema = (schema: z.ZodObject) => {
const standard = schema["~standard"];
const converter = standard.jsonSchema?.output;
if (converter === undefined)
throw new TypeError(
"Tool output schema does not expose Standard JSON Schema",
);
return {
"~standard": {
...standard,
jsonSchema: {
input: () => advertisedOutputJsonSchema(schema, converter),
output: () => advertisedOutputJsonSchema(schema, converter),
},
},
};
};
const advertisedInputJsonSchema = (
contract: ToolContract,
): Readonly<Record<string, unknown>> =>
cachedJsonSchema(ADVERTISED_INPUT_SCHEMAS, contract.inputSchema, () => ({
...describeProperties(
applyToolInputJsonSchemaOverride(
contract.name,
closeObjectSchemas(inputJsonSchema(contract.inputSchema)),
),
),
examples: contract.examples.map(({ input }) => input),
}));
const advertisedOutputJsonSchema = (
schema: z.ZodObject,
converter: NonNullable<z.ZodObject["~standard"]["jsonSchema"]>["output"],
): Readonly<Record<string, unknown>> =>
cachedJsonSchema(ADVERTISED_OUTPUT_SCHEMAS, schema, () =>
describeRootProperties(
closeObjectSchemas(converter({ target: "draft-2020-12" })),
),
);
const cachedJsonSchema = (
cache: WeakMap<z.ZodObject, Readonly<Record<string, unknown>>>,
schema: z.ZodObject,
create: () => Record<string, unknown>,
): Readonly<Record<string, unknown>> => {
const cached = cache.get(schema);
if (cached !== undefined) return cached;
const created = create();
cache.set(schema, created);
return created;
};
const inputJsonSchema = (schema: z.ZodObject): Record<string, unknown> => {
const converter = schema["~standard"].jsonSchema?.input;
if (converter === undefined)
throw new TypeError(
"Tool input schema does not expose Standard JSON Schema",
);
return converter({ target: "draft-2020-12" });
};
/** Close fixed-shape JSON Schema objects while preserving explicit maps. */
export const closeObjectSchemas = (
value: Readonly<Record<string, unknown>>,
): Record<string, unknown> => {
const closed = Object.fromEntries(
Object.entries(value).map(([key, child]) => [key, closeSchemaValue(child)]),
);
return value.type === "object" &&
isObject(value.properties) &&
value.additionalProperties === undefined
? { ...closed, additionalProperties: false }
: closed;
};
const closeSchemaValue = (value: unknown): unknown => {
if (Array.isArray(value)) return value.map(closeSchemaValue);
if (!isObject(value)) return value;
return closeObjectSchemas(value);
};
const describeProperties = (
value: Readonly<Record<string, unknown>>,
): Record<string, unknown> =>
Object.fromEntries(
Object.entries(value).map(([key, child]) => {
if (key !== "properties" || typeof child !== "object" || child === null)
return [key, describeValue(child)];
return [
key,
Object.fromEntries(
Object.entries(child).map(([property, schema]) => [
property,
isObject(schema) && typeof schema.description !== "string"
? {
...describeProperties(schema),
description: fallbackPropertyDescription(property),
}
: describeValue(schema),
]),
),
];
}),
);
const describeValue = (value: unknown): unknown => {
if (Array.isArray(value)) return value.map(describeValue);
return isObject(value) ? describeProperties(value) : value;
};
const describeRootProperties = (
value: Readonly<Record<string, unknown>>,
): Record<string, unknown> => {
const properties = value.properties;
if (!isObject(properties)) return { ...value };
return {
...value,
properties: Object.fromEntries(
Object.entries(properties).map(([property, schema]) => [
property,
isObject(schema) && typeof schema.description !== "string"
? {
...schema,
description: fallbackPropertyDescription(property),
}
: schema,
]),
),
};
};
const PROPERTY_DESCRIPTIONS: Readonly<Record<string, string>> = {
addresses: "Ordered provider-normalized procedure addresses to analyze.",
approved: "Explicit operator approval to perform this operation.",
after: "The later or right-hand observation to compare.",
before: "The earlier or left-hand observation to compare.",
boundary_id: "Exact reconstruction boundary identifier to evaluate.",
case_sensitive:
"Whether text matching distinguishes uppercase and lowercase.",
cdp_endpoint: "Approved literal loopback Chrome DevTools Protocol endpoint.",
comment: "Exact analyst comment text to write.",
comparisons: "Validated comparison Evidence records to aggregate.",
coverage: "Exact reconstruction-coverage commitment to verify.",
detail: "Requested response detail level.",
direction: "Direction in which to traverse or compare relationships.",
document: "Exact provider document or program identity.",
error: "Structured, caller-actionable error when the operation fails.",
evidence: "Evidence v2 record produced by this operation.",
evidence_id: "Stable identifier of the recorded Evidence v2 observation.",
evidence_uri:
"Session resource URI for the recorded Evidence v2 observation.",
executable: "Approved absolute path of the executable to run.",
format: "Declared input artifact format.",
name: "Exact name used by this operation.",
pattern: "Text or bounded pattern used to filter matching results.",
phase: "Current plan or execution phase of the operation.",
plan: "Content-bound execution plan and its approval commitment.",
query: "Non-empty feature or text query to investigate.",
question: "Concrete unresolved question to retain for later investigation.",
result: "Primary structured result returned by this operation.",
left: "Left-hand input used for comparison or differential execution.",
limit: "Maximum number of results to return in this page.",
limits:
"Bounded resource-consumption and result-size limits for this operation.",
mode: "Operation mode that selects the requested behavior.",
offset: "Zero-based index of the first result to return.",
overwrite: "Whether an existing destination may be replaced.",
path: "Local filesystem path used by this operation.",
provider_id:
"Exact deep-analysis provider ID, or automatic selection when omitted.",
right: "Right-hand input used for comparison or differential execution.",
schema_version: "Version of this structured result schema.",
source_evidence:
"Evidence records supporting the prepared source transformation.",
status: "Current lifecycle or verification status.",
summary: "Concise evidence-backed summary of the result.",
symbols: "Ordered bounded Swift symbols to demangle.",
target_id: "Exact authorized CDP target identifier.",
unknown_id: "Exact residual-unknown identifier.",
unknown_registry_approved:
"Explicit approval to record bounded residual uncertainty in the session registry.",
workspace_path:
"Approved local path of the persistent investigation workspace.",
};
const fallbackPropertyDescription = (property: string): string => {
const explicit = PROPERTY_DESCRIPTIONS[property];
if (explicit !== undefined) return explicit;
const words = property.replaceAll("_", " ");
if (property.endsWith("_approved"))
return `Explicit operator approval for ${words.slice(0, -9)}.`;
if (property.endsWith("_offset"))
return `Zero-based index of the first ${words.slice(0, -7)} to return.`;
if (property.endsWith("_limit"))
return `Maximum number of ${words.slice(0, -6)} entries to return.`;
if (property.startsWith("max_"))
return `Maximum permitted ${words.slice(4)} for this operation.`;
if (property.startsWith("include_"))
return `Whether to include ${words.slice(8)} in the result.`;
if (property.startsWith("expected_"))
return `Expected ${words.slice(9)} used to reject stale or mismatched input.`;
if (property.endsWith("_sha256"))
return `Exact SHA-256 digest of ${words.slice(0, -7)}.`;
if (property.endsWith("_evidence_id"))
return `Exact Evidence v2 identifier for the ${words.slice(0, -12)} observation.`;
if (property.endsWith("_evidence_ids"))
return `Ordered Evidence v2 identifiers for the ${words.slice(0, -13)} observations.`;
if (property.endsWith("_path"))
return `Local filesystem path for ${words.slice(0, -5)}.`;
if (property.endsWith("_uri"))
return `Canonical URI for ${words.slice(0, -4)}.`;
if (property.endsWith("_bytes"))
return `Bounded byte count for ${words.slice(0, -6)}.`;
if (property.endsWith("_root") || property.endsWith("_roots"))
return `Approved canonical filesystem ${words}.`;
if (property.startsWith("is_") || property.startsWith("has_"))
return `Whether ${words}.`;
return `Value for ${words}.`;
};
const isObject = (value: unknown): value is Readonly<Record<string, unknown>> =>
typeof value === "object" && value !== null && !Array.isArray(value);
+4 -29
View File
@@ -1,13 +1,9 @@
import type { CallToolResult } from "@modelcontextprotocol/server";
import {
AnalysisOutputError,
projectAnalysisError,
type AnalysisError,
} from "../domain/errors.js";
import type { Result } from "../domain/result.js";
import type { JsonValue } from "../domain/jsonValue.js";
import type { ToolContract } from "../contracts/toolContracts.js";
import { projectAnalysisError, type AnalysisError } from "../domain/errors.js";
import type { JsonValue } from "../domain/jsonValue.js";
import type { Result } from "../domain/result.js";
interface ToolResultOptions {
readonly evidenceResourcesAvailable?: boolean;
@@ -57,34 +53,13 @@ const successResult = (
const candidate =
compactEvidence(value, options.evidenceResultProjection) ??
(contract.kind === "session" ? { result: value } : value);
const parsed = contract.outputSchema.safeParse(candidate);
if (!parsed.success) {
const structuredContent = {
error: projectAnalysisError(
new AnalysisOutputError(
contract.name,
"output does not match the tool contract",
),
),
};
return {
content: [
{
type: "text",
text: JSON.stringify(structuredContent),
},
],
structuredContent,
isError: true,
};
}
return {
content: [
{
type: "text",
text: JSON.stringify(
options.evidenceTextProjection === undefined
? parsed.data
? candidate
: (compactEvidence(value, options.evidenceTextProjection) ??
options.evidenceTextProjection),
),