Introducing a new way to review your PRs.

Read the announcement

mvanhorn / last30days-skill

AI agent skill that researches any topic across Reddit, X, YouTube, HN, Polymarket, and the web - then synthesizes a grounded summary

View on GitHub

21 documents · Updated Nov 20, 2026

docs / mcp-embedded-engine

MCP embedded engine

The MCP embedded engine lets the Go MCP server ship the Last30Days research skill as one package while using the skill's Python runtime. It copies the skill into the package at build time, extracts a versioned runtime cache when needed, and runs the extracted engine as a child process for each request.

System boundary

The engine forms the boundary between the MCP tool layer and the research skill. The MCP server selects the request and returns a result. The Python skill performs the research work. This boundary lets the MCP package expose the skill without duplicating its research behavior.

The package does not provide Python. The host must provide Python 3.12 or newer. The runner normally discovers it through python3, but LAST30DAYS_PYTHON can select a compatible executable. Host credentials and other settings stay outside the embedded files and reach the child process through its environment. See MCP integration for the server view and MCP server and research tools for the client-facing flow.

Research requests deny browser-cookie access by default. A host can explicitly opt in through the MCP environment, while the engine still applies its own cookie consent and configuration checks.

Engine asset lifecycle

Build-time asset synchronization

The build process copies the Python skill's entry script and support library into the Go package's embedded asset area. mcp/…/sync-engine.sh uses skills/last30days/scripts/ as the source of truth. The copied tree is generated build input. Engineers should change the source skill rather than the copied tree.

The sync step removes old generated files and Python cache files before it copies the current entry script and lib/ tree. Go embedding then places that tree in the MCP binary. A packaged server can therefore recover its engine without downloading it.

References: mcp/…/sync-engine.sh• L1-33 mcp/…/embed.go• L1-24

Runtime cache materialization

On first use, the server exposes the embedded tree as a file system and extracts it into a per-user cache. The cache path includes the server version. This keeps installed versions separate and gives the Python process normal files for its script and module imports.

The extractor builds a temporary sibling directory and publishes it only after all files and a version marker exist. A later call reuses the directory when the marker matches. Calls for one cache path coordinate their first extraction within and across processes. A failed extraction can be retried. LAST30DAYS_CACHE_DIR selects another writable cache base when the default user cache is not available.

References: mcp/…/extract.go• L13-68 mcp/…/extract.go• L70-117 mcp/…/extract_test.go• L25-94 mcp/…/extract_test.go• L96-243

Process invocation

Interpreter selection

The runner selects a Python interpreter before it starts the engine. An explicit caller path is trusted for controlled use. Normal requests can use LAST30DAYS_PYTHON; otherwise discovery scans absolute PATH directories, checks candidate names, and accepts only Python 3.12 or newer. Discovery stops at the first valid interpreter and does not fall back when an explicit environment override is invalid.

The version check runs in an isolated probe with a short limit. This keeps host Python settings from changing interpreter selection and lets request cancellation stop a stalled discovery operation.

References: mcp/…/python.go• L16-76 mcp/…/python.go• L90-169 mcp/…/python_test.go• L27-107 mcp/…/python_test.go• L109-175

Child process contract

The runner starts the extracted last30days.py with the selected Python interpreter and passes the tool-specific arguments after the script path. Research and preflight use the same runner. This gives both MCP operations the same extraction, interpreter, and error behavior.

The child receives the MCP host environment. This includes credentials supplied by the bundle configuration. The runner replaces any inherited PYTHONPATH with the extracted cache so the skill can load its support library. It also forwards request-specific environment values and arguments without changing their order.

The tool layer keeps the child-process contract explicit. Research places the topic after an argument separator so topic text cannot become an engine option. It always passes a save directory value, including an empty value when the caller did not request a report. This prevents an unrelated memory-directory setting from turning a non-saving request into a write. Research also supplies the engine-plan permission that is needed when the MCP server must plan the work itself. Preflight uses the same process boundary to report the resolved save location without running research or saving files.

References: mcp/…/run.go• L16-25 mcp/…/run.go• L46-70 mcp/…/run.go• L75-103 mcp/…/run_test.go• L89-205 mcp/…/research.go• L108-123 mcp/…/research.go• L134-142 mcp/…/preflight.go• L37-60 mcp/…/preflight_test.go• L8-35 mcp/…/research_test.go• L102-208

Output and time boundaries

The runner keeps standard output and standard error separate. On success, standard output becomes the MCP tool result. On failure, the tool retains the exit code and error output so it can return a useful client error without exposing the child process itself.

Each invocation has a ten-minute default limit. The request context can stop it sooner. An installation can set LAST30DAYS_MCP_TIMEOUT with a duration or a positive number of seconds when the default does not fit its work. The runner gives the child its own process group, sends a graceful stop on cancellation or timeout, and uses a forced stop as a backstop. Missing Python, a missing script, a failed start, a non-zero exit, cancellation, and a timeout remain separate failure types.

References: mcp/…/run.go• L27-44 mcp/…/run.go• L89-168 mcp/…/run.go• L171-205 mcp/…/run_test.go• L207-283 mcp/…/run_test.go• L452-481 mcp/…/research.go• L148-157

Request execution flow

The request path crosses two synchronization boundaries. Build synchronization keeps the embedded assets aligned with the Python source. Runtime synchronization turns those assets into one complete cache before a child process uses them.

The diagram shows how source assets become a client-visible MCP result.

flowchart LR
    A[Python skill source] --> B[Build sync]
    B --> C[Embedded engine in MCP binary]
    C --> D[Versioned user cache]
    D --> E[Python child process]
    F[MCP request and host environment] --> G[Interpreter selection]
    G --> E
    E --> H[stdout or structured error]
    H --> I[MCP response]

For each request, the server resolves the embedded source and ensures the versioned cache. It then selects a compatible interpreter and starts the Python entry point with the requested mode and safety flags. Research may resolve a report directory first, while preflight resolves one to describe the possible file boundary without writing. The MCP layer returns the engine output or maps the runner error and standard error into a tool error.

References: mcp/…/research.go• L75-104 mcp/…/preflight.go• L37-60 mcp/…/embed.go• L21-25 mcp/…/extract.go• L27-117 mcp/…/python.go• L23-76 mcp/…/run.go• L75-168

Synchronization boundaries

Source and bundle boundary

The Python skill files are authoritative. The embedded mirror is disposable generated data. A skill change reaches an MCP release only after the sync step refreshes the embedded tree before the Go build. This boundary prevents the server from running an older engine than the source tree describes.

References: mcp/…/sync-engine.sh• L5-16 mcp/…/embed.go• L1-24

Cache and process boundary

The cache is the stable handoff from the Go server to the Python process. The version marker and atomic publication make a cache either complete for one engine version or unsuitable for reuse. The process reads the cache and receives request data through arguments and the environment. It does not change the embedded binary.

References: mcp/…/extract.go• L27-117 mcp/…/run.go• L60-68

Host and engine boundary

The host supplies the interpreter, credentials, and writable storage. The MCP runner supplies the script location, module path, request arguments, and execution limit. This keeps host setup outside the bundled source while making missing prerequisites visible at the tool boundary.

The MCP layer also supplies safety defaults at this boundary. Research blocks browser cookies unless the host opts in, forces an explicit save destination, and separates the topic from engine options. These choices keep request intent stable when the host has unrelated environment settings.

References: mcp/…/sync-engine.sh• L5-16 mcp/…/extract.go• L27-35 mcp/…/python.go• L27-76 mcp/…/run.go• L60-68 mcp/…/research.go• L108-132 mcp/manifest.json• L28-49 mcp/README.md• L30-36

Change checklist

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

  • Changes under skills/last30days/scripts/ require a fresh mcp/internal/engine/vendored/ sync before the MCP binary is built or packaged.
  • Changes to the engine version stamp must preserve the versioned cache namespace so old and new engines do not share runtime assets.
  • Changes to the Python module layout must preserve the extracted root and PYTHONPATH contract used by the child process.
  • Changes to Python discovery or the LAST30DAYS_PYTHON override must preserve the Python 3.12 minimum and the no-fallback behavior for an invalid explicit override.
  • Changes to MCP bundle environment mappings must preserve credential flow into the Python child without placing secrets in embedded files.
  • Changes to output modes or process flags must stay aligned between MCP tool arguments and the Python engine command-line contract.
  • Changes to research argument construction must preserve the topic separator, explicit empty save directory, browser-cookie default deny, and engine-plan permission.
  • Changes to preflight or research save-directory handling must keep both tools aligned with the engine's configured destination without allowing a non-saving request to write.
  • Changes to extraction coordination must preserve safe publication for concurrent processes and permit retry after a failed extraction.
  • Changes to timeout or process-group handling must preserve cancellation of descendant work and the distinction between cancellation, timeout, start, and exit errors.

Important failure modes

TriggerConsequenceGuard
The build skips engine synchronizationThe binary can contain stale or empty engine assetsRun mcp/…/sync-engine.sh before the Go build and package step
The default user cache is not writableExtraction fails before research startsSet LAST30DAYS_CACHE_DIR to a writable directory
LAST30DAYS_PYTHON names a missing, relative, or old interpreterThe runner fails instead of selecting another interpreterSet it to an absolute Python 3.12+ executable or unset it to use PATH discovery
No compatible Python is on an absolute PATH entryThe MCP tool cannot start the research engineInstall Python 3.12+ or provide a valid LAST30DAYS_PYTHON path
A process uses an inherited PYTHONPATHPython can import the wrong support modules or fail to find the bundled onesReplace the inherited value with the extracted cache path
The engine exceeds its execution limitThe child and its process group stop and the tool returns a timeout errorSet an appropriate request or LAST30DAYS_MCP_TIMEOUT limit
Extraction stops before publicationA partial tree is not accepted as a usable cacheExtract to a temporary sibling and publish only after completion
A topic is passed as an option or save directory is omittedThe engine can misread the topic or save because of an unrelated memory-directory settingKeep the topic after -- and pass an explicit --save-dir value
Browser-cookie opt-in is enabled without valid engine consent or configurationThe engine still refuses cookie accessTreat the MCP opt-in as permission to remove only the MCP default-deny flag

Key files

FileWhy to read it
mcp/…/sync-engine.shDefines the build-time source and generated-asset boundary.
mcp/…/embed.goShows how the engine becomes part of the MCP binary.
mcp/…/extract.goDefines versioned cache materialization and safe publication.
mcp/…/python.goDefines Python interpreter selection, version checks, and cancellation during discovery.
mcp/…/run.goDefines environment setup, process invocation, timeout behavior, and process results.
mcp/…/research.goShows how a research request reaches extraction and execution, including safety defaults and save control.
mcp/…/preflight.goShows how preflight uses the same engine boundary without running research.
mcp/manifest.jsonDefines host environment injection and the bundled server entry point.
mcp/README.mdGives package-level runtime requirements and the build sequence.