Introducing a new way to review your PRs.

Read the announcement

morluto / rea

Reverse engineer anything with agents, from app behavior down to native binaries.

View on GitHub

27 documents · Updated Nov 20, 2026

docs / mcp-tool-registration

MCP tool registration

MCP tool registration turns REA product operations into one discoverable server surface for MCP clients. It groups tools by user capability, gives each tool a shared contract, and connects each contract to the analysis or session service that can fulfill it.

Registration model

Server assembly

The server assembly creates the MCP server, prepares the services that support optional capabilities, and invokes the registration modules. A session source adds target lifecycle and evidence tools; a fixed analysis source keeps the server useful for direct analysis without session state. Advertised tool families and provider availability control which capabilities appear and which optional providers can be used at call time.

The registration modules receive a common server context. This context carries the active target, evidence access, logging, analysis admission, provider services, and the set of advertised families. This keeps product operations separate from the MCP transport while still giving each tool the state it needs.

flowchart TD
    S[Server source] --> A[Server assembly]
    A --> C[Shared server context]
    C --> R[Capability registration modules]
    R --> T[Registered MCP tools]
    T --> M[MCP client]
    C --> P[Analysis and provider services]
    T --> P
    C --> V[Capability and provider availability]
    V --> T

References: src/…/createServer.ts• L280-341 src/…/createServer.ts• L409-438 src/…/createServer.ts• L809-862 src/…/registerSessionStatusTool.ts• L98-187

Capability modules

Each registration module represents a product capability rather than a transport concern. The module selects the contracts it owns and maps them to the service or workflow that provides the capability. Recent groups also keep provider-specific tools visible when the provider is optional, then report provider availability when a caller uses the tool.

Capability groupProduct purpose
Analysis settingsInspect or update runtime analysis choices without an active target.
Official analysisDirect analysis operations exposed as named product actions.
Enhanced analysisComposed workflows that answer higher-level investigation questions.
Evidence providersNative, artifact, managed-code, firmware, browser, runtime, Android, and other provider-backed observations.
Specialized inspectionsFocused binary, package, database, packet, firmware, language-runtime, and model-artifact inspections that use the shared evidence path.
Application workflowsProvider-neutral application tracing, comparison, reconstruction, coverage, environment-bundle, graph, and guided-workflow operations.
Guidance accessProvider-free search and retrieval of the installed guide bundle.
Comparisons and investigation workflowsCross-target comparisons and evidence-backed conclusions about changed behavior, call paths, runtime correlation, and reconstruction.
Session operationsTarget selection, lifecycle, evidence bundles, unknowns, context, and process capture.
External analysis toolsDebuggers, instrumentation, browser automation, and other optional analysis engines.
Reverse-engineering toolsObjdump inspection and Rizin command execution against an analysis target.

The contract inventory defines the public capability order. Optional providers can still register their public tools while reporting that a provider is unavailable when a caller invokes one. Runtime settings, guidance access, and provider-free guided workflow access remain available when no target or healthy provider exists.

Specialized modules bind named inspection contracts to their owning services. They do not create a separate public contract model. They reuse the shared evidence handler so their observations enter the same session evidence ledger as other provider results. This includes Android, native, managed, artifact, binary-diagnostic, language-runtime, WASM, and platform-specific inspections.

Application registration groups higher-level operations that work from existing evidence or application inputs. These tools trace features and JavaScript semantics, compare versions and source to bundles, compare export shapes, build reconstruction obligations, evaluate coverage, export environments, project mobile application graphs, and expose guidance and guided workflows. Shared application registration options provide artifact resources, logging, analysis admission, and optional evidence readers and writers so derived answers can stay linked to investigation records.

Persistent external tools need more than a single analysis call. Frida registration covers device discovery and instrumentation sessions. GDB and Rizin registration covers debugger sessions, commands, status, and cleanup. Reverse-engineering registration covers objdump and Rizin, including extra admission and cleanup rules for commands that can change the target.

References: src/…/toolContracts.ts• L47-94 src/…/registerAnalysisSettingsTools.ts• L8-32 src/…/registerApplicationTools.ts• L16-31 src/…/types.ts• L10-20 src/…/registerGuidanceTools.ts• L11-45 src/…/registerAndroidTools.ts• L17-132 src/…/registerManagedTools.ts• L13-60 src/…/registerNativeTools.ts• L7-12 src/…/registerOfficialTools.ts• L6-12 src/…/registerPrompts.ts• L24-57 src/…/registerGuidedWorkflowTool.ts• L7-19 src/…/registerReverseEngineeringTools.ts• L25-46 src/…/guidedWorkflowsTool.test.ts• L1-20

Artifact delivery

Artifact registration adapts the shared evidence flow for inspections that can return a retained summary. Delivery detail is a caller-facing choice, so it is removed before execution and evidence identity. Artifact extraction also receives a controlled output destination rather than a caller-selected execution path.

The same delivery choice applies to binary diagnostics, browser analysis, Electron analysis, BEAM and Python inspections, packet captures, WASM artifacts, and other focused inspections. WASM interface comparison and artifact inspection use the same evidence and delivery model. A summary is a view of retained evidence; it does not become a different analysis operation.

References: src/…/registerArtifactTools.ts• L8-19 src/…/registerBinaryDiagnosticsTools.ts• L17-75 src/…/registerByteEntropyTool.ts• L12-33 src/…/registerBrowserTools.ts• L80-109 src/…/registerElectronTools.ts• L93-129 src/…/registerErlangTools.ts• L11-33 src/…/registerPythonPycTool.ts• L11-33 src/…/registerWebNetworkCaptureTool.ts• L16-64 src/…/registerPcapTools.ts• L17-51 src/…/registerWasmTools.ts• L21-65

Shared registration contracts

Tool contract

A tool contract is the single public description of one MCP operation. It names the tool, states its purpose, defines input and output schemas, identifies its adapter family, records effects, marks target-derived content, and provides caller examples.

The contract inventory groups these descriptions into capability families and resolves a contract by its public name. Registration uses the same contract that catalog and verification tools use. This prevents the advertised tool surface from drifting away from the operation that handles the call.

Direct analysis contracts use the official contract family. Each contract has a strict input schema and a required output schema. The family includes read operations, navigation and metadata operations, and analyst edits that bridge directly to an analysis provider without extra application composition.

References: src/…/toolContractTypes.ts• L20-69 src/…/toolContracts.ts• L47-112 src/…/officialToolContracts.ts• L21-35 src/…/officialToolContracts.ts• L38-240

Contract binding registry

The contract binding registry maps each named public contract to the kind of product operation that can fulfill it. A binding can run an evidence operation, return a value, read admitted analysis, derive a result from session evidence, run an application workflow, call a provider operation, perform an external mutation, or retain a complete result behind a selected view.

The registry chooses the matching shared handler and registers the contract with the MCP server. It distinguishes SDK admission from application admission, so an application workflow can validate the raw request and shape its own input errors. It also rejects bindings for missing contracts and rejects provider bindings whose operation name does not match the contract. These checks keep the public contract list, execution path, and server surface joined at startup instead of relying on separate name-based wiring.

Provider bindings require analysis admission. A value binding can instead run without analysis for provider-free guidance, discovery, and status reads, while an explicitly admitted value binding uses the analysis gate. This lets the same registry express both lightweight server reads and analysis-backed operations.

References: src/…/contractToolBindings.ts• L83-219 src/…/contractToolBindings.ts• L238-368 src/…/contractToolBindings.ts• L389-408 src/…/contractToolBindings.ts• L499-668

Wire registration

The shared registration options project a contract into the MCP SDK. The projection preserves the public title, description, input schema, output schema, and execution hints. The server can change how schemas are presented to clients without changing the canonical parser or the product contract.

Input metadata gives clients usable property descriptions and examples. Output schemas can carry stable identities. Application workflows may accept raw input at the SDK boundary so they can return the same field-aware errors as the product service; their canonical contract still defines the advertised shape. Value tools can also apply a final presentation step when a response must hide caller-provided secrets or handles.

References: src/…/toolRegistrationOptions.ts• L8-40 src/…/toolSchemaMetadata.ts• L59-127 src/…/EvidenceMcpServer.ts• L134-178 src/…/contractToolBindings.ts• L153-160 src/…/environmentBundle.ts• L14-50

Effect and safety metadata

Each public tool has an explicit effect audit. The audit records whether an operation can change the target or session, write files, launch processes, use the network, change UI state, discard data, execute foreign code, or change an attached device. It also records whether the operation is idempotent.

MCP annotations are derived only from this effect metadata. The result marks a tool as read-only only when none of the audited effects apply. It marks destructive behavior for data loss, foreign-code execution, or device changes, and marks open-world behavior for process or network access.

Tools that can return target, provider, launcher, or device content also carry that fact into result delivery. Only a small audited set is content-free. Unknown tool names remain marked as content-producing until they are audited, which tells clients to treat strings, code, logs, captures, diagnostics, and file content as untrusted data rather than instructions.

The effect audit covers analysis settings, application workflows, guidance access, guided workflows, specialized inspections, browser tools, Android operations, and external-tool groups as well as core analysis tools. This makes a new registration module incomplete until its public names also have effect metadata and content-provenance behavior.

References: src/…/toolEffects.ts• L1-30 src/…/toolEffects.ts• L32-54 src/…/toolEffects.ts• L693-756 src/…/toolEffects.ts• L758-831

Product operation flow

Contract-backed execution

Most product operations follow one path from MCP request to an evidence-backed or value response. The contract binding registry selects the shared handler, which admits the operation when needed, validates the contract input, runs the product service with cancellation and progress, records evidence when the operation produces an observation, and converts the result into the contract output.

The exact path differs by capability. Direct analysis tools call a named analysis operation. Enhanced tools run a composed workflow. Provider-backed tools use the shared evidence registration path. Session tools call long-lived session services for lifecycle or investigation state. Application tools derive evidence from application inputs or earlier evidence. Query tools read the analysis granted to the call and return a value. Summary or selected-view requests change delivery after the complete result is retained; they do not change the product operation.

sequenceDiagram
    participant Client as MCP client
    participant Tool as Registered tool
    participant Gate as Analysis admission
    participant Service as Product operation
    participant Ledger as Evidence or session record
    Client->>Tool: Call with contract input
    Tool->>Gate: Admit operation
    Gate->>Service: Run with signal and progress
    Service-->>Tool: Result or typed error
    Tool->>Ledger: Record evidence or session change
    Tool-->>Client: Contract-shaped result

Shared handlers also preserve partial evidence on some failures and use the tool's target-content flag when they encode errors. This gives clients a stable response shape while keeping the evidence record useful for later work.

References: src/…/contractToolHandler.ts• L15-91 src/…/contractToolBindings.ts• L547-652 src/…/providerOperationToolHandler.ts• L72-177 src/…/registerOfficialTools.ts• L6-12 src/…/registerEnhancedTools.ts• L236-359 src/…/compareSourceToBundle.ts• L23-123

Session-scoped operations

Session registration adds operations that need a long-lived investigation context. These tools open and close targets, report session status, manage evidence bundles and residual unknowns, provide analysis context, and run comparisons, derived investigations, or process captures.

The session is also the main place where tool results become durable investigation state. Process capture records typed evidence and turns residual gaps into unknowns for later work. Evidence bundle tools move that state across sessions, while unknown tools let clients list, add, update, and verify unresolved questions. Artifact comparisons and other derived investigations resolve retained evidence records, record those sources, and create derived records; a changed, truncated, or unknown result can also create a residual unknown with a recommended follow-up inspection. Session registration owns process-capture cleanup when the server closes, so temporary resources do not outlive the session.

References: src/…/registerSessionTools.ts• L46-149 src/…/registerSessionTools.ts• L299-456 src/…/registerSessionRecordTools.ts• L35-293 src/…/registerSessionStatusTool.ts• L98-187 src/…/registerArtifactComparisonTool.ts• L19-119 src/…/registerBundleComparisonTool.ts• L16-95 src/…/registerInvestigationTools.ts• L30-196 src/…/registerCloseLifecycleTool.ts• L30-126

Provider-backed observations

Provider-backed registration turns a family of analysis services into evidence-producing MCP tools. The shared provider handler performs input and delivery preflight, analysis admission, progress reporting, operation logging, source recording, evidence creation, evidence projection, and delivery handling without repeating the same policy for every provider.

The handler can reuse a matching completed observation already held by the session. Otherwise it admits a new analysis and records the completed operation as atomic Evidence. A summary request is checked before analysis; when a contract does not retain complete Evidence, the provider is not called.

Provider operation families can adjust how an admitted analysis reaches a service. Managed operations can use a selected managed file when a call omits its path. Artifact extraction receives a server-created output destination. These adapters keep provider-specific routing and resource limits outside the common evidence flow.

The Android, language, APK-signature, binary-diagnostic, and artifact registration modules use this path to keep product-specific services behind one public behavior. A provider result becomes an observation tied to the active target and session, while the operation name and execution parameters preserve how the observation was made.

Browser, Electron, and JavaScript runtime registration groups web observations behind the same result model. They report an unavailable optional provider at call time, apply analysis admission, carry cancellation and progress into the service, and deliver results as session evidence. Electron tools cover target and page inspection, application analysis, runtime reconciliation, active scenarios, and fuse inspection through this common surface. Local web-script export, application environment export, and other provider-free workflows remain usable without a live browser provider.

Some tools can return a retained summary instead of full detail. That choice affects delivery only; it does not change the analysis operation or the identity of the retained evidence.

References: src/…/providerOperationToolHandler.ts• L32-69 src/…/providerOperationToolHandler.ts• L71-177 src/…/providerOperationFamilies.ts• L12-75 src/…/registerAndroidTools.ts• L17-132 src/…/registerBinaryDiagnosticsTools.ts• L17-75 src/…/registerBrowserTools.ts• L36-183 src/…/registerElectronTools.ts• L49-194 src/…/registerJavaScriptRuntimeObservationTools.ts• L24-58 src/…/registerWebNetworkCaptureTool.ts• L16-64 src/…/registerArtifactTools.ts• L8-19 src/…/registerWasmTools.ts• L21-65

Application workflows

Application registration exposes higher-level questions through workflows that combine application records, retained evidence, and bounded analysis results. These operations support feature tracing, semantic tracing, version and source-to-bundle comparison, export-shape comparison, reconstruction obligations, coverage checks, environment export, and mobile application graph projection.

The workflows record source evidence before they return a derived result. A complete parent result is retained before a caller asks for a smaller view, so the view remains linked to its source. When a comparison or reconstruction result is incomplete, the registration path can add a residual unknown with a follow-up probe. Artifact comparison follows the same rule: it links the compared evidence, stores the derived result, and records an unresolved question when the result does not establish a complete answer.

References: src/…/registerApplicationTools.ts• L16-31 src/…/types.ts• L10-20 src/…/helpers.ts• L19-136 src/…/compareVersions.ts• L14-55 src/…/compareSourceToBundle.ts• L23-65 src/…/compareExportShapes.ts• L12-60 src/…/traceFeature.ts• L12-61 src/…/traceSemantics.ts• L12-55 src/…/projectMobileApplicationGraph.ts• L21-93 src/…/registerArtifactComparisonTool.ts• L38-118 src/…/registerBundleComparisonTool.ts• L44-91

Guided workflow access

Guided workflow access gives clients provider-free entry to the existing guided prompt contracts. It uses the server's advertised tool families so a workflow does not describe calls that are not available in the current server configuration.

The prompt registry uses the same family scope and can update prompt descriptions and argument completion as capabilities change. Guidance search and section retrieval provide direct access to the installed guide bundle without an analysis target; guided workflows use that product knowledge to help a client choose available operations.

References: src/…/registerGuidanceTools.ts• L11-45 src/…/registerGuidedWorkflowTool.ts• L7-19 src/…/registerPrompts.ts• L19-57 src/…/guidedWorkflowsTool.test.ts• L1-20

Composed investigation workflows

Enhanced registration exposes higher-level native analysis questions through workflows that combine lower-level analysis operations. The workflow runner admits the call, reports progress, records the result as typed evidence, and can retain a replayable snapshot or create unknowns when the result remains incomplete.

This keeps a composed answer in the investigation record instead of returning it as an isolated response. The analyze_function path uses the same evidence delivery goal while delegating its analysis-specific work to a dedicated operation.

References: src/…/registerEnhancedTools.ts• L69-230 src/…/registerEnhancedTools.ts• L236-359 src/…/registerEnhancedTools.ts• L361-474 src/…/registerManagedTools.ts• L13-60

Persistent tool sessions

Debugger and instrumentation groups expose stateful external tools whose operations span several MCP calls. A start operation creates a provider session, later calls address that session, and close operations retire it through the same result and cleanup model.

These tools need stronger safety handling because commands can mutate the target, launch processes, use the network, or execute foreign code. GDB, Rizin, and Cutter commands therefore use external-mutation admission, while Frida also preserves partial observations when a session operation fails after producing useful data.

References: src/…/registerFridaTools.ts• L38-285 src/…/registerGdbTools.ts• L42-153 src/…/registerRizinDebugTools.ts• L35-135 src/…/registerCutterTools.ts• L15-71 src/…/registerReverseEngineeringTools.ts• L25-181

Change checklist

When these files or sections are changed, remember to consider these:

  • Add or remove a public operation in its capability contract family and its contract binding map. Keep any capability registration that supplies the binding aligned with both.
  • Keep the contract's input and output schemas aligned with the handler's result and with any catalog or verification path that reads TOOL_CONTRACTS.
  • Keep each binding's execution shape aligned with its handler. Keep provider operation names exact and keep application admission distinct from SDK admission.
  • Recheck effect flags, target-content marking, and MCP annotations when an operation gains file, process, network, device, or target side effects.
  • Preserve the distinction between delivery-only fields and analysis parameters when adding summary or compact response modes.
  • When a session-only operation changes, check fixed-target registration paths so the tool is not exposed without the state it needs.
  • When an optional provider changes, keep registration, availability reporting, and provider cleanup in agreement.
  • When a specialized inspection is added, connect its named contract to the shared evidence handler and to the owning session evidence ledger.
  • When application workflows change, keep source-evidence links, derived evidence identity, incomplete-result unknowns, and delivery projections aligned.
  • When guidance or guided workflows change, keep guide access, prompt content, and advertised family scope aligned so clients do not receive unavailable operations.
  • When browser, Electron, or runtime operations change, keep provider diagnostics, admission, progress, retained views, and evidence delivery aligned.
  • When debugger or instrumentation support changes, keep session creation, command admission, partial evidence, and cleanup aligned.
  • When reverse-engineering commands change, keep command parsing, external-mutation admission, snapshot invalidation, and retirement handling aligned.
  • When a derived investigation workflow changes, keep its evidence links, derived evidence type, completeness checks, and recommended probes aligned.
  • When a direct analysis operation changes, update its strict input schema, required output schema, effect audit, and provider adapter together.
  • When a provider operation changes, keep preflight reuse, source-evidence recording, execution routing, and retained-result delivery aligned.
  • When managed or artifact routing changes, keep selected-file fallback and server-owned extraction destinations outside the provider's analysis parameters.

Important failure modes

TriggerConsequenceGuard
A contract is absent from the family inventory or contract binding mapThe operation is missing from the MCP surface or from catalog checksKeep the family contract list and binding map aligned with TOOL_CONTRACTS.
Handler input or output changes without a contract changeClients receive a schema that does not describe the real operationUse the canonical contract for registration and delivery.
A binding selects the wrong execution shape or provider operationA call reaches the wrong service or fails after registrationUse the binding type and startup checks to keep each contract matched to its handler and named operation.
A session-only tool is registered without a sessionThe tool cannot resolve target, evidence, or lifecycle stateRegister session tools only when createServer has a session source.
An optional provider cannot loadCalls fail even though the tool is listedReport the provider load failure at call time through the tool's normal result path.
A specialized inspection bypasses the shared provider handlerIts result can use different admission, logging, or evidence rulesBind the service through the common provider evidence path unless it needs a documented stateful flow.
A delivery field reaches analysis or evidence identityEquivalent observations split into different records or unsupported execution input is sentRemove delivery-only fields before execution and evidence creation.
A summary request has no retained complete-result contractThe provider runs without a deliverable complete evidence recordPreflight delivery before analysis and refuse the request when retention is not available.
An application comparison skips source evidence or unknown registrationA derived result loses its audit trail or hides incomplete coverageRecord source evidence first and create a scoped unknown when the result is incomplete.
A persistent external command skips mutation admissionA command can change the target without the session policy or cleanup pathKeep GDB, Rizin, and Cutter command execution behind external-mutation admission.
A derived workflow uses evidence that is not in the sessionThe result cannot be linked to a durable investigation recordResolve the evidence closure before creating workflow evidence.
A direct analysis tool lacks an effect auditMCP safety hints and target-content handling can be wrong or registration can failAdd the public name to TOOL_EFFECTS before creating its contract metadata.
Target-derived content is not marked as untrustedA client may treat analysis data as instructionsKeep returnsTargetContent and result provenance aligned with the operation.
Guided workflow scope includes a disabled tool familyA client receives steps that it cannot executeBuild guided workflow access and prompt registration from the same advertised families.
Guidance tools are registered without the installed guide resource scopeSearch or section reads cannot resolve the guide bundlePass the same artifact resource scope used by application registration.
Artifact comparison does not record both source recordsA comparison result loses its evidence trail or cannot support a follow-up unknownResolve and record both evidence sources before recording the derived comparison.
Rizin command cleanup fails after a mutating callThe active analysis snapshot or target state can no longer be trustedRetain the partial observation and report retirement failure through the external-mutation path.
A provider operation omits its managed path and no server selection existsThe call cannot identify the managed file to inspectRequire an explicit path or select a managed artifact before the dependent operation.
Artifact extraction uses a caller-controlled execution rootExtraction can write outside the server's controlled output areaReplace the requested root with a server-created extraction destination.

Key files

FileWhy to read it
src/…/createServer.tsShows how the server assembles capability modules, services, session state, and provider policy.
src/…/toolContracts.tsShows the ordered public contract inventory and capability families.
src/…/toolContractTypes.tsDefines the public contract fields shared by every tool.
src/…/toolEffects.tsDefines the effect audit, MCP safety annotations, and target-content default.
src/…/toolRegistrationOptions.tsShows how a product contract becomes MCP registration metadata.
src/…/contractToolBindings.tsShows how named contracts select shared handlers and become MCP tools.
src/…/providerOperationToolHandler.tsShows the common path for provider-backed evidence operations.
src/…/providerOperationFamilies.tsShows provider-specific routing and controlled artifact extraction parameters.
src/…/registerOfficialTools.tsShows how named analysis operations become direct MCP tools.
src/…/registerApplicationTools.tsShows the provider-neutral application workflow group and its registration order.
src/…/types.tsShows the shared services that application workflow registration can use.
src/…/helpers.tsShows source recording, complete-result retention, selected views, and scoped unknowns.
src/…/registerGuidanceTools.tsShows provider-free guide search and section retrieval.
src/…/registerGuidedWorkflowTool.tsShows provider-free guided workflow access and family scoping.
src/…/registerPrompts.tsShows how guided prompts and argument completion follow advertised capabilities.
src/…/registerArtifactTools.tsShows summary delivery and controlled extraction for artifact inspections.
src/…/registerBrowserTools.tsShows grouped browser operations, optional-provider diagnostics, retained views, and evidence delivery.
src/…/registerElectronTools.tsShows Electron inspection, application analysis, runtime reconciliation, active scenarios, and fuse inspection.
src/…/registerEnhancedTools.tsShows how higher-level workflows use the same contract and evidence model.
src/…/registerSessionTools.tsShows the session-only lifecycle, context, comparison, process, and cleanup tool groups.
src/…/registerSessionRecordTools.tsShows evidence bundle and residual-unknown operations.
src/…/registerArtifactComparisonTool.tsShows evidence-backed artifact comparison and incomplete-result unknowns.
src/…/registerInvestigationTools.tsShows evidence-backed derived investigation operations.
src/…/registerWasmTools.tsShows WASM inspection and interface comparison through shared evidence handlers.
src/…/registerReverseEngineeringTools.tsShows objdump and Rizin registration with target-mutation handling.
src/…/registerFridaTools.tsShows device discovery, persistent instrumentation, partial evidence, and session cleanup.
src/…/registerGdbTools.tsShows debugger sessions, retained summaries, mutation admission, and cleanup.
src/…/EvidenceMcpServer.tsShows how registrations keep canonical contracts while adapting the client-facing wire view.

Related pages: MCP server, Session evidence and results, Server lifecycle and policy