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-server

MCP server composition

The Model Context Protocol (MCP) server is REA's client-facing entry point for reverse-engineering work. It joins a protocol connection to an analysis source, presents the available product capabilities, and keeps target state, evidence, provider access, and cleanup within clear session boundaries.

System boundary

Product role

REA gives a client one capability surface for local artifact and runtime analysis. The client can inspect targets, run analysis, use captured observations, and follow guided workflows without choosing the provider behind each operation. The server instructions also tell the client to treat target-derived text as data rather than as instructions.

The surface changes with the kind of analysis source and the tool families admitted to a connection. A live session includes target lifecycle operations. A fixed analysis source can expose analysis without allowing the client to open or close a target.

References: src/…/createServer.ts• L128-166 src/…/serverInstructions.ts• L4-35

Process boundary

The rea mcp command owns the MCP process and its transport. The normal CLI runtime remains outside this boundary, while diagnostic commands use their own path. This keeps protocol traffic and its cleanup lifecycle together.

References: scripts/rea.mjs• L7-16 scripts/rea.mjs• L39-65

Startup and session establishment

Startup sequence

Startup turns process configuration into a usable MCP connection. It validates configuration, creates or receives an analysis source, loads optional providers, and then admits protocol traffic. A startup error prevents the client from using a partial capability surface.

This diagram shows the high-level path from process start to a usable session.

flowchart TD
    A[Start MCP process] --> B[Read and validate configuration]
    B --> C[Create analysis session or source]
    C --> D[Open configured initial target]
    D --> E[Load optional providers]
    E --> F[Create or attach MCP server]
    F --> G[Serve tools and prompts]
    G --> H[Close transport, providers, and session]

An invalid configuration or an unreadable initial target stops startup. An optional provider can fail without stopping unrelated capabilities. Its failure becomes part of the reported availability state.

References: src/main.ts• L44-80 src/…/transport.ts• L53-72 src/…/createServer.ts• L140-173

Deferred session runtime

The server can publish a recorded catalog before it creates the live analysis runtime. This lets a client inspect tools and prompts without starting expensive analysis work. The first admitted tool call, prompt request, or completion loads one shared runtime for the connection.

The recorded catalog remains the client-facing contract. When the runtime loads, its canonical validators and handlers attach to the already advertised entries. Concurrent requests join the same load, and a cancelled request cannot execute the handler after loading completes.

References: src/…/DeferredEvidenceMcpServer.ts• L46-107 src/…/DeferredEvidenceMcpServer.ts• L110-223 src/…/DeferredEvidenceMcpServer.ts• L265-344 src/…/DeferredEvidenceMcpServer.test.ts• L184-249 src/…/DeferredEvidenceMcpServer.test.ts• L271-376 src/…/DeferredEvidenceMcpServer.test.ts• L388-472

HTTP session

Streamable HTTP exposes the same MCP surface at /mcp. One server instance can keep serving after a client ends its session. A new initialize request replaces the current live session, while an explicit session termination ends only that session. The listener closes only when its owning HTTP server closes.

The HTTP boundary also protects the session from requests with invalid protocol headers, foreign hosts, or foreign origins. It does not announce a listener until startup succeeds, and it waits for active request and response cleanup before provider shutdown.

References: src/…/serveStreamableHttp.test.ts• L206-250 src/…/serveStreamableHttp.test.ts• L252-274 src/…/serveStreamableHttp.test.ts• L300-322 src/…/serveStreamableHttp.test.ts• L458-494 src/…/serveStreamableHttp.test.ts• L1373-1415

Server composition

Composition root

src/…/createServer.ts is the composition root for one MCP server. It selects the analysis source, host rules, schema presentation, response limits, tool-family scope, result delivery, and capability services. It can build a new protocol server or attach the runtime to an existing deferred server.

The composition root gives registration groups the shared services that define a consistent product behavior: target access, analysis admission, evidence recording, result delivery, logging, and provider availability. It also installs provider cleanup on both protocol-driven and explicit close paths.

References: src/…/createServer.ts• L69-125 src/…/createServer.ts• L128-173 src/…/createServer.ts• L234-344

Capability groups

The server exposes related operations as tool families. A family is a product area that can be admitted or withheld as one unit. The broad groups are:

Capability groupProduct purpose
Direct and enhanced analysisInspect artifacts and run higher-level reverse-engineering workflows
Native, artifact, and managed analysisAnalyze common binary, file, and managed-code forms
Runtime observationInspect browsers, JavaScript runtimes, Electron, and captured behavior
Specialized analysisSupport Android, firmware, WebAssembly, packet, database, and format-focused work
Application workflowsCompare, trace, reconstruct, and inspect application behavior
Session workflowsOpen targets, manage evidence, compare observations, and report status
Desktop environmentsRun and inspect reproducible build environments
Guided promptsHelp a client form session-aware investigation requests

The server can expose the full catalog or a scoped set of families. An out-of-scope operation stays known to the server but is not advertised as usable, so status and guidance do not direct the client to a call that must fail.

References: src/…/createServer.ts• L348-644 src/…/EvidenceMcpServer.ts• L22-63 src/…/serverInstructions.ts• L16-35

Service bindings

Service bindings connect product contracts to the services that perform them. One shared binding table is used by production composition and focused MCP tests. This keeps the operation name, admission rule, evidence handling, and service dependency consistent across those paths.

The binding layer is the seam between capability groups and the common tool registration flow. Read MCP tool registration for the contract and registration rules.

References: src/…/serviceToolBindings.ts• L467-470 src/…/serviceToolBindings.ts• L2175-2210 src/…/createServer.ts• L348-642

Protocol presentation

EvidenceMcpServer adapts the MCP protocol boundary to REA's product rules. It presents the selected schemas and instructions, gives each connection the right capability identity, and disables tools outside the selected family scope. Canonical validation still governs the operation when the handler runs.

The deferred server uses the same boundary while preserving the recorded catalog during runtime materialization. This separates what the client sees during discovery from when the underlying provider work starts.

References: src/…/EvidenceMcpServer.ts• L22-63 src/…/DeferredEvidenceMcpServer.ts• L108-165 src/…/DeferredEvidenceMcpServer.ts• L265-325

Capability surface

Tools

Tools are the main operation surface. They cover direct analysis, specialized providers, runtime observation, session work, evidence workflows, and desktop environments. Shared admission and result delivery give these different product areas one request boundary.

The default catalog exposes the available families together. A hot-cold catalog can show a small initial set and discover more tools for that connection. Discovery changes visibility only after the client receives a complete reply, so the client must refresh its tool list before using a newly visible tool.

References: src/…/createServer.ts• L348-644 src/…/serviceToolBindings.ts• L2182-2210 src/…/DeferredEvidenceMcpServer.test.ts• L184-222

Prompts

Prompts provide named investigation starting points beside tools. They can use the active analysis and session to offer valid completion values. A prompt helps the client form a request, but it does not replace the analysis operation that later performs the work.

References: src/…/createServer.ts• L600-642 src/…/DeferredEvidenceMcpServer.ts• L166-207 src/…/DeferredEvidenceMcpServer.test.ts• L357-386

Server guidance

Server instructions give the client a short model of the current capability surface. They differ for target-free and session-backed connections. Guidance names lifecycle or enhanced operations only when the matching family is available, and it includes rules for interpreting evidence and untrusted target content.

References: src/…/serverInstructions.ts• L4-35 src/…/createServer.ts• L101-124

Evidence and results

An evidence record is a retained analysis result with the source and limits needed to use it later. The server records evidence through the session when one exists and delivers results within the configured response boundary. A result that cannot fit is handled as a recoverable condition rather than silently shortened.

Read Session evidence and results for the evidence model and the recovery paths for large or incomplete results.

References: src/…/createServer.ts• L260-344 src/…/createServer.ts• L680-702 src/…/serviceToolBindings.ts• L957-1030

Availability and ownership

Capability availability

Availability is part of the product response. The server combines platform limits, configured providers, provider load failures, and command failures into the session's reported capability state. A missing optional provider narrows the usable surface instead of making every operation appear unavailable.

The status view considers the families advertised to that connection. Clients can therefore distinguish an unsupported capability from a failure in an operation that the server did admit.

References: src/…/createServer.ts• L260-305 src/…/sessionAvailabilityPolicy.ts• L5-76 src/…/registerSessionStatusTool.ts• L42-191

Resource ownership

Each server closes the protocol endpoint and the providers it owns. Shared providers created for several connections remain owned by the transport or process boundary. Cleanup reports all failures and keeps unfinished owners available for a later retry.

Deferred runtime cleanup is registered before runtime startup can fail. This prevents a partial materialization from losing the resources it already acquired.

Read Server lifecycle and policy for the wider startup, readiness, shutdown, and retry rules.

References: src/…/createServer.ts• L315-337 src/…/DeferredEvidenceMcpServer.ts• L226-249 src/…/DeferredEvidenceMcpServer.ts• L346-378 src/…/transport.ts• L73-123 src/…/transport.ts• L171-246

Change checklist

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

  • Keep the selected tool families aligned across catalog identity, disabled tools, server guidance, prompts, and session status.
  • Keep the recorded catalog aligned with every canonical tool and prompt registered during deferred materialization.
  • Keep one deferred runtime load shared by concurrent requests, and keep cancellation checks before handler execution.
  • Keep service bindings aligned with the contract name, admission rule, evidence recorder, and provider passed by createServer.
  • Keep HTTP session replacement, session termination, host checks, origin checks, and listener ownership as separate lifecycle actions.
  • Keep provider ownership explicit when a provider is shared across server instances; do not close a shared owner from one instance.
  • Keep protocol close and provider close retryable when one cleanup stage fails.
  • Keep target-free instructions from naming lifecycle tools that are not in scope.

Important failure modes

TriggerConsequenceGuard
Deferred catalog and runtime registrations do not matchRuntime materialization fails before the connection can use the affected surfaceVerify every recorded tool and prompt has one canonical runtime binding.
Deferred runtime startup fails after acquiring resourcesThe client receives a generic startup failure and partial resources must still closeRegister runtime cleanup before materialization and retain partial cleanup for close.
A request is cancelled while the shared runtime is loadingThe cancelled request must not run the target handlerCheck the request signal before and after runtime loading.
A client calls a tool outside the connection's family scopeThe call fails instead of reaching an unavailable providerDisable out-of-scope tools and omit them from advertised guidance and listings.
A non-loopback HTTP bind has no allowed-host policyThe listener refuses to serve the endpointRequire an explicit host allowlist and reject foreign host or origin headers.
A new HTTP initialize request races with session replacementThe old session can receive requests after it should have endedAdmit one replacement and close the old transport before the new session becomes active.
A provider or response cleanup failsThe server remains partly open and a later close must finish the workKeep failed owners pending, aggregate cleanup errors, and retry unfinished stages.

Key files

FileWhy to read it
src/main.tsProcess-level MCP startup and analysis-session creation
src/…/transport.tsTransport ownership, server creation, provider sharing, and startup cleanup
src/…/createServer.tsComposition root for analysis sources, providers, family scope, registration, and ownership
src/…/EvidenceMcpServer.tsProtocol identity and family-scoped tool behavior
src/…/DeferredEvidenceMcpServer.tsDeferred catalog use, runtime materialization, cancellation, and retryable cleanup
src/…/serviceToolBindings.tsShared mapping from product contracts to service-backed tools
src/…/serverInstructions.tsClient guidance for target-free and session-backed connections
src/…/serveStreamableHttp.test.tsObservable HTTP session, request-admission, and cleanup rules
src/…/registerSessionStatusTool.tsReported target and provider availability
src/…/toolResult.tsCommon result delivery and response-size recovery