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

MCP integration

MCP integration gives MCP clients a supported way to use Last30Days research through a Go server. The server accepts tool calls over standard input and output, prepares the bundled Python skill runtime, and returns research or safety information as client-readable MCP results. It keeps the client contract small while the skill runtime remains responsible for source access, ranking, and synthesis.

Integration boundary

The integration has three connected parts: an MCP client starts the bundled server, the Go server translates tool calls, and the Last30Days skill runtime performs the work. The server is a bridge rather than a second research system. This lets desktop clients use the same research behavior as other skill hosts without importing the Python pipeline directly.

The main boundary is:

BoundaryResponsibilityResult
MCP client to Go serverStart a session and send tool requestsValidated MCP calls
Go server to skill runtimePrepare the engine and pass request settingsA bounded engine run
Skill runtime to Go serverGather current evidence and render outputStandard output or failure detail
Go server to MCP clientReturn text content or a tool errorA usable client response

The client-facing details are covered in MCP server and research tools. The asset and process handoff is covered in MCP embedded engine.

This diagram shows the request path from a host to the research result.

sequenceDiagram
    participant C as MCP client
    participant S as Go MCP server
    participant R as Last30Days runtime
    participant O as Client response
    C->>S: Start stdio session
    C->>S: Call preflight or research
    S->>S: Validate request
    S->>R: Prepare and run skill
    R-->>S: Output or failure details
    S-->>O: MCP text or tool error

References: mcp/…/main.go• L26-38 mcp/…/research.go• L50-85 mcp/…/preflight.go• L30-56 mcp/…/run.go• L82-176

Client connection

The server uses the MCP standard input and output transport. A host can start the packaged command as a child process and exchange requests without opening a network port. The server stays active for the session and writes process-level failures to standard error.

The bundle manifest tells the host which binary to start and which optional user settings to pass into its environment. Claude Desktop is the packaged host for this integration on macOS and Linux. The Go module uses the MCP Go library to provide this server boundary. See distribution and host integrations for the wider host model.

References: mcp/…/main.go• L1-4 mcp/…/main.go• L26-38 mcp/manifest.json• L28-49 mcp/manifest.json• L152-158 mcp/go.mod• L1-8

Runtime handoff

The Go layer owns the MCP session and request shape. The Python Last30Days runtime owns research behavior. For each request, the server makes the embedded engine available in a user cache, finds and checks a Python 3.12 or newer interpreter, and passes the host environment and request arguments to that process. An explicit LAST30DAYS_PYTHON choice is checked on its own and does not fall back to another interpreter. The research tool also allows the engine to create its own plan because MCP does not provide a separate query-plan input.

The handoff uses the extracted cache as the child's only Python module path. It forwards configured credentials and other host settings while removing any inherited PYTHONPATH that could point the child at unrelated code. The server can use LAST30DAYS_PYTHON for an explicit interpreter and otherwise resolves an absolute python3 path. See research skill execution for the engine's research lifecycle and runtime configuration and safety for its privacy and source rules.

References: mcp/…/embed.go• L1-24 mcp/…/run.go• L74-109 mcp/…/run.go• L178-212 mcp/…/run.go• L230-248 mcp/…/python.go• L16-76 mcp/…/python.go• L147-169 mcp/…/research.go• L87-120 mcp/README.md• L30-36

Tool surface

The server exposes two tools with different purposes. preflight gives the client a safe view of planned access and side effects. research runs current-topic research and returns output that the client or its model can synthesize into an answer or a shareable brief.

Preflight tool

The preflight tool lets a client inspect a planned run before research starts. It asks the runtime to describe what the run may read, write, execute, or contact. It does not run research, save a report, or read browser cookies. Its first use can still initialize the local engine cache, so read-only preflight applies to research work and report output rather than to engine setup.

The optional format value selects concise text or structured JSON. The report-directory query uses the same configuration as a later saved research call, but the preflight run passes an empty save target so the inspection does not write a report. This keeps the safety view tied to the action that the client may perform next.

InputRequiredValuesPurpose
formatNotext or jsonSelects the preflight response shape

References: mcp/…/preflight.go• L14-27 mcp/…/preflight.go• L30-71 mcp/…/preflight_test.go• L8-63 mcp/README.md• L36-40

Research tool

The research tool is the main MCP entry point for recent-topic research. A client gives it a non-empty topic. The runtime then gathers and ranks current evidence across its supported source lanes before returning compact output for model synthesis or an HTML result for a shareable brief. A client sets save to request persistence; the server passes the selected report directory only for that request and passes an explicit empty directory when saving is disabled.

The default save=false mode returns the requested output without research persistence. It skips report export and the research caches for the run, while engine installation and source diagnostics can still use local caches. save=true enables the engine's configured persistence and report export. This keeps a request that only needs an inline answer from creating local research records.

The MCP path treats research output as untrusted data rather than an instruction set. The server's tool description tells the client or model to synthesize ranked evidence, preserve uncertainty and coverage limits, and cite source URLs. The server asks the runtime to omit its jobs and patent digests and its report-writing checklist. It also removes a jobs digest or checklist if an engine version still emits one, so the client receives evidence and canonical output instead of internal presentation guidance.

The MCP path denies browser-cookie use by default. A host can explicitly opt in with LAST30DAYS_MCP_ALLOW_BROWSER_COOKIES, but the engine still applies its own consent and configuration rules. A client can also ask the runtime to save the result as a report. The save location uses the engine's resolved configuration, including LAST30DAYS_MEMORY_DIR when set and otherwise the default report location.

InputRequiredDefaultPurpose
topicYesNonePerson, company, product, event, or general subject to research
emitNocompactSelects compact model input or an HTML brief
saveNofalseRequests a saved report and research persistence

References: mcp/…/research.go• L23-28 mcp/…/research.go• L60-84 mcp/…/research.go• L87-142 mcp/…/research.go• L213-243 mcp/…/research_test.go• L18-35 mcp/…/research_test.go• L124-226 mcp/…/research_test.go• L275-335 mcp/…/research_test.go• L340-436 mcp/README.md• L34-40

Response contract

Successful tool calls return MCP text content. Research text is returned after MCP-specific presentation filtering. Invalid arguments and ordinary runtime failures return an MCP result marked as an error. A completed report with known source degradation is the exception: when the runtime provides a complete report and its degraded-source receipt, the server returns a structured degraded result so the client can use the report while preserving the coverage warning.

The server includes runtime standard-error text when a run fails. An incomplete report, an unrelated exit, or a canceled or timed-out run remains an error. The client can therefore see useful cause information without reaching into the child process or a local log.

References: mcp/…/research.go• L87-142 mcp/…/research.go• L145-165 mcp/…/research.go• L299-309 mcp/…/preflight.go• L31-63 mcp/…/research_exit_test.go• L13-73 mcp/…/research_test.go• L228-273

Engine bridge

The engine bridge turns build-time skill assets into a runnable local process. The bundle contains a generated copy of the Python engine. On first use, the server extracts that copy into a versioned user cache and then runs it with the requested arguments.

The cache gives the child process ordinary files and a module search path. Version names keep installed releases separate, while a completed cache can be reused on later calls. Concurrent processes use a publication lock and private staging directories so one process cannot observe or remove another process's incomplete cache. The bridge does not download or reimplement the research engine.

This diagram shows the asset and request handoff through the bridge.

flowchart LR
    A[Python skill source] --> B[Build-time embedded copy]
    B --> C[Go MCP bundle]
    C --> D[Versioned user cache]
    E[MCP tool request] --> F[Python 3.12+ process]
    D --> F
    E --> F
    F --> G[Runtime output]
    G --> H[MCP response]

References: mcp/…/embed.go• L13-25 mcp/…/extract.go• L27-68 mcp/…/cache_staging.go• L11-40 mcp/…/run.go• L74-109 mcp/…/research.go• L105-141

Asset lifecycle

The Python skill tree is the source of truth for the embedded runtime. A build sync copies that tree into the Go package before the binary is built. The binary can then restore the tree locally without a separate engine download.

At run time, extraction uses a temporary location and promotes it only after the full tree is ready. A version marker controls reuse. A cross-process lock protects publication, and abandoned staging data can be reclaimed after its owner exits. If the normal user cache is not writable, LAST30DAYS_CACHE_DIR provides the cache base override.

References: mcp/README.md• L7-25 mcp/…/embed.go• L13-24 mcp/…/extract.go• L27-117 mcp/…/cache_staging.go• L43-81 mcp/…/cache_lock.go• L9-49

Process limits

The bridge starts one bounded Python subprocess for each tool request. It resolves python3 from PATH or uses an explicit interpreter path. A path found through PATH must be absolute. The bridge forwards the MCP host environment so configured credentials can reach the runtime, but removes any inherited PYTHONPATH before setting the cache as the child's only module path.

The default limit for one run is ten minutes. A request context can stop the run sooner. On Unix, the engine runs in its own process group, receives a termination signal first, and then receives a forced kill if it does not stop. This bounds cleanup for child processes as well as the direct Python process. Windows can stop the direct child, but does not provide the same descendant cleanup guarantee. An installation can set LAST30DAYS_MCP_TIMEOUT to change the limit with a duration or a positive number of seconds.

Interpreter discovery scans absolute PATH directories in order. It prefers python3, then compatible versioned names, and checks each candidate's reported version before use. Discovery stops when it finds a valid interpreter and can stop during a stalled file or version check when the request context is canceled.

References: mcp/…/python.go• L16-76 mcp/…/python.go• L90-169 mcp/…/python.go• L172-193 mcp/…/run.go• L27-47 mcp/…/run.go• L75-168 mcp/…/proc_group_unix.go• L10-38 mcp/…/proc_group_windows.go• L9-33 mcp/…/run_test.go• L231-253 mcp/…/python_test.go• L27-45 mcp/…/python_test.go• L109-125 mcp/…/python_test.go• L136-195

Host configuration

The MCP bundle presents optional provider settings as host configuration. The host maps those settings to environment values for the Python runtime. No one provider key is required by the bundle because source coverage can vary with the settings available on the user's machine.

The host supplies four classes of runtime input:

  • Interpreter: Python 3.12 or newer found in an absolute PATH directory, or an explicit LAST30DAYS_PYTHON path.
  • Credentials: Optional keys and tokens for source retrieval and synthesis providers.
  • Storage and limits: Optional report and cache directory overrides plus the MCP run timeout.
  • Browser access: An explicit LAST30DAYS_MCP_ALLOW_BROWSER_COOKIES opt-in when the user and engine policy allow cookie use.

The manifest identifies release 4.4.0. It declares the binary entry point and supports Claude Desktop version 1.0.0 or newer on macOS and Linux. It maps optional provider settings for OpenAI, xAI, web search, Google and Gemini, social sources, parallel research, and synthesis gateways into the server environment. It also exposes separate settings for official X access and creator-focused social providers. The runtime still applies its own source and privacy rules after it receives these values. In particular, the MCP research and preflight handlers deny browser-cookie use unless the explicit opt-in is truthy, and preflight reports planned access without reading cookie values. See runtime configuration and safety for the common policy.

The Go module pins the MCP protocol library and YAML support. Its lock data records the direct and indirect packages used to build the server, so dependency changes can affect the supported Go build even when the client-facing contract stays the same.

References: mcp/manifest.json• L1-6 mcp/manifest.json• L28-49 mcp/manifest.json• L52-150 mcp/manifest.json• L152-158 mcp/…/research.go• L23-28 mcp/…/research.go• L233-253 mcp/…/run.go• L178-212 mcp/go.mod• L1-17 mcp/go.sum• L1-39

Change checklist

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

  • Keep the manifest binary path, packaged entry point, and supported platform list aligned. A mismatch can install a bundle that the host cannot start.
  • Keep every host environment substitution paired with a declared user setting. A name mismatch silently removes a provider credential from the runtime.
  • Keep the preflight report directory and the research save directory derived from the same engine rule. Otherwise the safety view can describe a different write target.
  • Keep MCP input values aligned with the Python command-line modes. A change to emit, format, save handling, or cookie flags can break clients without changing the transport.
  • Keep the research argument order and -- separator intact. A topic that starts with - must remain a positional topic rather than an engine option.
  • Keep the explicit empty --save-dir and --no-research-persistence when save is false. Removing either can enable an unintended report write or research cache update.
  • Keep the engine-plan environment override with the research request. The MCP tool has no query-plan argument and must allow the engine to plan inside the child process.
  • Keep the research lane suppression and output filtering rules aligned with the runtime's canonical boundary. A change can trigger unwanted patent or jobs access, expose internal report guidance, or remove evidence that clients need to synthesize a result.
  • Treat a degraded exit as usable only when the runtime returns a complete canonical report and its degraded-source receipt. Other nonzero exits must remain tool errors.
  • Sync the embedded Python engine after skill changes and before packaging. Otherwise the desktop bundle can run an older engine than other skill hosts.
  • Preserve the cache version namespace when changing the embedded engine. Shared cache paths can mix incompatible runtime files.
  • Preserve the publication lock and staging cleanup contract when changing extraction. Concurrent callers must not see partial files or remove an active stage.
  • Keep request failures as MCP tool errors when the session should remain usable. Only process-level server failure should end the MCP session.
  • Keep Python discovery, process-group shutdown, and cache validation errors actionable. The bridge needs a usable interpreter, bounded child cleanup, and a staged last30days.py before it can start a request.
  • Keep interpreter selection fail-closed. An invalid or empty LAST30DAYS_PYTHON value must report its own error rather than silently selecting another interpreter, while PATH discovery must ignore relative directories and non-Python helper names.
  • Keep the Go version and direct MCP library version compatible with the build and server APIs. A module update can change the build contract without changing the manifest.
  • Keep the manifest version aligned with the embedded runtime and released bundle. A stale version can make hosts or caches use the wrong package identity.

Important failure modes

TriggerConsequenceGuard
The host cannot find a compatible Python 3.12 or newer executable in its absolute PATH directoriesTool calls cannot start the research runtimeInstall the required interpreter or set LAST30DAYS_PYTHON to a valid executable
LAST30DAYS_PYTHON is empty, relative, missing, or reports an incompatible versionDiscovery fails without falling back to another interpreterSet the override to an existing absolute Python 3.12+ executable or remove it to use PATH discovery
The user cache is not writableBoth tools fail before research or preflight outputSet LAST30DAYS_CACHE_DIR to a writable location
Two processes contend for cache publication beyond the lock wait limitExtraction fails without publishing an incomplete cacheLet the active extractor finish, then retry the request
The embedded engine is stale or missingThe bundle runs old behavior or cannot prepare the runtimeSync the skill tree before the Go build
The extracted cache lacks last30days.pyThe child process is not startedComplete extraction before invoking the engine
A research process exits or exceeds its limitThe client receives no research result and sees the failure causePreserve exit, timeout, and standard-error details at the tool boundary
A degraded exit lacks a complete report or its degraded-source receiptThe client receives a tool error instead of an incomplete result presented as usableTreat only a complete canonical report with the strict-exit receipt as degraded success
A Unix engine timeout leaves a descendant outside the managed groupA helper process can outlive the request and hold output pipes openUse the process-group and termination path; Windows has a weaker descendant guarantee
A client sends a blank topic or unsupported output valueThe request is rejected with an MCP tool errorValidate required strings and closed value sets
A client sends an unsupported preflight formatThe inspection request is rejected with an MCP tool errorUse text or json
A topic is passed before the option separatorA dash-prefixed topic can be read as an engine optionKeep -- immediately before the topic
A save-disabled request omits its empty save directory or persistence flagLAST30DAYS_MEMORY_DIR or default engine behavior can cause unintended research writesPass an explicit empty --save-dir and disable research persistence when save is false
Browser-cookie opt-in is absent or falseCookie-backed source access stays disabledSet LAST30DAYS_MCP_ALLOW_BROWSER_COOKIES only for an intentional, policy-approved opt-in
A manifest credential mapping has no matching user settingA source or synthesis provider is unavailableCheck manifest environment mappings against declared settings
The Go toolchain or MCP library version is incompatible with the moduleThe server cannot build or its protocol boundary can change unexpectedlyKeep go.mod and go.sum in sync with the supported build toolchain
The manifest version does not match the packaged runtimeHosts or caches can treat the bundle as the wrong releaseUpdate the release metadata with the embedded runtime
Runtime output changes its canonical boundary or its jobs or patent suppression behaviorMCP clients may receive engine presentation guidance or lose research evidence, and the runtime may make an unwanted source requestKeep the suppression flags, output filters, and runtime output contract covered together

Key files

FileWhy to read it
mcp/…/main.goShows the server startup, stdio transport, and tool registration boundary
mcp/manifest.jsonDefines host launch, optional credential wiring, version, and platform support
mcp/go.modDefines the Go toolchain and direct server dependencies
mcp/go.sumRecords the dependency versions used for reproducible Go builds
mcp/…/research.goDefines the research request, privacy default, save behavior, degraded-result policy, output policy, argument boundary, and response path
mcp/…/research_test.goProtects research metadata, argument validation, privacy defaults, save-directory behavior, topic separation, engine planning, and output filtering
mcp/…/research_exit_test.goProtects the boundary between degraded completed reports and ordinary runtime errors
mcp/…/preflight.goDefines the safe inspection request, report formats, and no-write research boundary
mcp/…/preflight_test.goProtects preflight format validation, shared cookie policy, and the no-write report argument contract
mcp/…/embed.goShows how the skill runtime becomes part of the bundle
mcp/…/extract.goDefines versioned cache preparation and safe promotion
mcp/…/cache_staging.goExplains private extraction stages, publication locking, and abandoned-stage cleanup
mcp/…/run.goDefines interpreter discovery, environment handoff, output capture, process shutdown, and time limits
mcp/…/python.goDefines safe Python candidate discovery, version checks, and cancellation during discovery
mcp/…/proc_group_unix.goShows how Unix timeouts stop the engine and its managed descendants
mcp/…/proc_group_windows.goShows the Windows direct-child timeout boundary
mcp/…/sync_contract_test.goProtects the match between the embedded engine and its Python source tree
mcp/…/run_test.goShows the process, environment, interpreter, timeout, and failure contracts protected by the engine tests
mcp/…/python_test.goProtects interpreter selection, version checks, path rules, and discovery cancellation
mcp/README.mdSummarizes the bundle lifecycle, runtime requirements, persistence behavior, and release path
skills/…/last30days.pyDefines the command-line modes consumed by the MCP bridge
MCP server and research toolsExplains the client-facing tool contract
MCP embedded engineExplains the asset cache and process bridge
Research skill executionExplains the research lifecycle behind the MCP request
Runtime configuration and safetyExplains shared credential, privacy, source, and execution rules
Distribution and host integrationsExplains how the MCP bundle fits the wider host and release model
Evaluation and regression suiteExplains the checks that protect the MCP and runtime contracts