Research tools with validated requests and responses.

THE WORK

The project.

Research MCP Service exposes Research Workflow Engine through typed tools. A shared registry defines what each call accepts and returns, and a callable service checks both sides before passing work between the protocol and the parent's packages. Clients get a consistent result or a controlled error without taking ownership of research rules or storage.

IMPLEMENTATION

Design choices.

1. One callable service sits behind the protocol and direct tests. Both callers get the same validation and handlers, while protocol tests still check registration and transport behavior that a direct call can't exercise.
2. Output validation makes the tool's promise two-sided. A handler can't silently return a new shape just because its input was valid; the response must still match the versioned schema the client expects.
3. Tool schemas have their own versions, separate from the package version. A change to one operation can be represented without treating every unrelated schema as a new interface.
4. Errors need enough detail to guide a retry without exposing arbitrary exceptions. Controlled categories retain that guidance, while the fixed fallback handles failures the service doesn't recognise.
5. Conflicting retries don't add another failed-write audit event. The service can refuse changed input under a used key without making that refusal look like another original operation.
6. A single local bundle makes distribution straightforward, but SQLite's native binding is still part of what must run. Packaging and lifecycle tests remain necessary alongside handler tests.

HOW IT FITS TOGETHER

Architecture.

• The registry supplies tool versions, strict Zod input and output schemas, and annotations to MCP SDK registration. The same operations are available through a directly callable service, so tests and protocol clients don't need separate implementations.
• The service parses raw input before dispatch, including direct calls that didn't pass through the SDK. It also bounds nested JSON, then delegates research rules and calculations to the parent's domain packages. The shared storage package owns transactions, immutable revisions, retry receipts and audit events.
• A successful handler result goes back through its declared output schema before reaching the client. Known failures map to controlled categories and retry guidance; unexpected exceptions return a fixed internal error. Eligible failed writes are recorded, while an idempotency conflict doesn't add another failure event for the same attempt.
• The server uses STDOUT only for protocol messages and STDERR for lifecycle logs. Those logs identify configuration choices without printing data paths or environment values, keeping diagnostics out of both the protocol stream and the request payload.
• The distributable Node process includes the native SQLite binding and migrations. Startup keeps mutable data away from installed code, and shutdown closes the server and database. This package is part of Research Workflow Engine, not an independently hosted service.

ACCESS & INPUT

Security controls.

• The tools receive browser observations as data. They don't open a browser, acquire a signed-in session or perform external business actions, and accepting an observation doesn't establish that it is accurate.
• Strict schemas reject unknown fields, while size, depth, item-count and string-length limits bound nested JSON before dispatch. Malformed writes stop before a handler runs.
• Unknown exceptions lose their original text in the response. Known errors retain useful messages and remediation, so their constructors still need to avoid including private details; the fallback isn't a sanitizer for every application string.
• MCP frames and logs use different output streams. Lifecycle messages describe how configuration was selected without exposing actual directory paths or environment values.
• A valid write that fails can receive a failure audit record. A conflicting retry skips that extra event, preserving the distinction between a recorded attempt and another request to replay it.
• Startup checks keep mutable data out of protected installation files. Tool annotations describe operations for clients; input checks, domain rules and storage transactions enforce what the operations can do.

CHECKS & RESULTS

What was checked.

A source review shows what the code does. It is not a fresh test of the running app.

1. Code and development records reviewedReviewed11 September 2026

   The code, tests and available development records were checked. Reported test results keep their original scope. No fresh app or live deployment check was run for this write-up.

   Scope of this check

   Code review, not a fresh run of the app