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 group | Product purpose |
|---|---|
| Direct and enhanced analysis | Inspect artifacts and run higher-level reverse-engineering workflows |
| Native, artifact, and managed analysis | Analyze common binary, file, and managed-code forms |
| Runtime observation | Inspect browsers, JavaScript runtimes, Electron, and captured behavior |
| Specialized analysis | Support Android, firmware, WebAssembly, packet, database, and format-focused work |
| Application workflows | Compare, trace, reconstruct, and inspect application behavior |
| Session workflows | Open targets, manage evidence, compare observations, and report status |
| Desktop environments | Run and inspect reproducible build environments |
| Guided prompts | Help 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
| Trigger | Consequence | Guard |
|---|---|---|
| Deferred catalog and runtime registrations do not match | Runtime materialization fails before the connection can use the affected surface | Verify every recorded tool and prompt has one canonical runtime binding. |
| Deferred runtime startup fails after acquiring resources | The client receives a generic startup failure and partial resources must still close | Register runtime cleanup before materialization and retain partial cleanup for close. |
| A request is cancelled while the shared runtime is loading | The cancelled request must not run the target handler | Check the request signal before and after runtime loading. |
| A client calls a tool outside the connection's family scope | The call fails instead of reaching an unavailable provider | Disable out-of-scope tools and omit them from advertised guidance and listings. |
| A non-loopback HTTP bind has no allowed-host policy | The listener refuses to serve the endpoint | Require an explicit host allowlist and reject foreign host or origin headers. |
| A new HTTP initialize request races with session replacement | The old session can receive requests after it should have ended | Admit one replacement and close the old transport before the new session becomes active. |
| A provider or response cleanup fails | The server remains partly open and a later close must finish the work | Keep failed owners pending, aggregate cleanup errors, and retry unfinished stages. |
Key files
| File | Why to read it |
|---|---|
| src/main.ts | Process-level MCP startup and analysis-session creation |
| src/…/transport.ts | Transport ownership, server creation, provider sharing, and startup cleanup |
| src/…/createServer.ts | Composition root for analysis sources, providers, family scope, registration, and ownership |
| src/…/EvidenceMcpServer.ts | Protocol identity and family-scoped tool behavior |
| src/…/DeferredEvidenceMcpServer.ts | Deferred catalog use, runtime materialization, cancellation, and retryable cleanup |
| src/…/serviceToolBindings.ts | Shared mapping from product contracts to service-backed tools |
| src/…/serverInstructions.ts | Client guidance for target-free and session-backed connections |
| src/…/serveStreamableHttp.test.ts | Observable HTTP session, request-admission, and cleanup rules |
| src/…/registerSessionStatusTool.ts | Reported target and provider availability |
| src/…/toolResult.ts | Common result delivery and response-size recovery |