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:
| Boundary | Responsibility | Result |
|---|---|---|
| MCP client to Go server | Start a session and send tool requests | Validated MCP calls |
| Go server to skill runtime | Prepare the engine and pass request settings | A bounded engine run |
| Skill runtime to Go server | Gather current evidence and render output | Standard output or failure detail |
| Go server to MCP client | Return text content or a tool error | A 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.
| Input | Required | Values | Purpose |
|---|---|---|---|
format | No | text or json | Selects 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.
| Input | Required | Default | Purpose |
|---|---|---|---|
topic | Yes | None | Person, company, product, event, or general subject to research |
emit | No | compact | Selects compact model input or an HTML brief |
save | No | false | Requests 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
PATHdirectory, or an explicitLAST30DAYS_PYTHONpath. - 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_COOKIESopt-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
preflightreport directory and theresearchsave 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-dirand--no-research-persistencewhensaveis 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_PYTHONvalue must report its own error rather than silently selecting another interpreter, whilePATHdiscovery 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
| Trigger | Consequence | Guard |
|---|---|---|
The host cannot find a compatible Python 3.12 or newer executable in its absolute PATH directories | Tool calls cannot start the research runtime | Install the required interpreter or set LAST30DAYS_PYTHON to a valid executable |
LAST30DAYS_PYTHON is empty, relative, missing, or reports an incompatible version | Discovery fails without falling back to another interpreter | Set the override to an existing absolute Python 3.12+ executable or remove it to use PATH discovery |
| The user cache is not writable | Both tools fail before research or preflight output | Set LAST30DAYS_CACHE_DIR to a writable location |
| Two processes contend for cache publication beyond the lock wait limit | Extraction fails without publishing an incomplete cache | Let the active extractor finish, then retry the request |
| The embedded engine is stale or missing | The bundle runs old behavior or cannot prepare the runtime | Sync the skill tree before the Go build |
| The extracted cache lacks last30days.py | The child process is not started | Complete extraction before invoking the engine |
| A research process exits or exceeds its limit | The client receives no research result and sees the failure cause | Preserve exit, timeout, and standard-error details at the tool boundary |
| A degraded exit lacks a complete report or its degraded-source receipt | The client receives a tool error instead of an incomplete result presented as usable | Treat only a complete canonical report with the strict-exit receipt as degraded success |
| A Unix engine timeout leaves a descendant outside the managed group | A helper process can outlive the request and hold output pipes open | Use the process-group and termination path; Windows has a weaker descendant guarantee |
| A client sends a blank topic or unsupported output value | The request is rejected with an MCP tool error | Validate required strings and closed value sets |
| A client sends an unsupported preflight format | The inspection request is rejected with an MCP tool error | Use text or json |
| A topic is passed before the option separator | A dash-prefixed topic can be read as an engine option | Keep -- immediately before the topic |
| A save-disabled request omits its empty save directory or persistence flag | LAST30DAYS_MEMORY_DIR or default engine behavior can cause unintended research writes | Pass an explicit empty --save-dir and disable research persistence when save is false |
| Browser-cookie opt-in is absent or false | Cookie-backed source access stays disabled | Set LAST30DAYS_MCP_ALLOW_BROWSER_COOKIES only for an intentional, policy-approved opt-in |
| A manifest credential mapping has no matching user setting | A source or synthesis provider is unavailable | Check manifest environment mappings against declared settings |
| The Go toolchain or MCP library version is incompatible with the module | The server cannot build or its protocol boundary can change unexpectedly | Keep go.mod and go.sum in sync with the supported build toolchain |
| The manifest version does not match the packaged runtime | Hosts or caches can treat the bundle as the wrong release | Update the release metadata with the embedded runtime |
| Runtime output changes its canonical boundary or its jobs or patent suppression behavior | MCP clients may receive engine presentation guidance or lose research evidence, and the runtime may make an unwanted source request | Keep the suppression flags, output filters, and runtime output contract covered together |
Key files
| File | Why to read it |
|---|---|
| mcp/…/main.go | Shows the server startup, stdio transport, and tool registration boundary |
| mcp/manifest.json | Defines host launch, optional credential wiring, version, and platform support |
mcp/go.mod | Defines the Go toolchain and direct server dependencies |
mcp/go.sum | Records the dependency versions used for reproducible Go builds |
| mcp/…/research.go | Defines the research request, privacy default, save behavior, degraded-result policy, output policy, argument boundary, and response path |
| mcp/…/research_test.go | Protects research metadata, argument validation, privacy defaults, save-directory behavior, topic separation, engine planning, and output filtering |
| mcp/…/research_exit_test.go | Protects the boundary between degraded completed reports and ordinary runtime errors |
| mcp/…/preflight.go | Defines the safe inspection request, report formats, and no-write research boundary |
| mcp/…/preflight_test.go | Protects preflight format validation, shared cookie policy, and the no-write report argument contract |
| mcp/…/embed.go | Shows how the skill runtime becomes part of the bundle |
| mcp/…/extract.go | Defines versioned cache preparation and safe promotion |
| mcp/…/cache_staging.go | Explains private extraction stages, publication locking, and abandoned-stage cleanup |
| mcp/…/run.go | Defines interpreter discovery, environment handoff, output capture, process shutdown, and time limits |
| mcp/…/python.go | Defines safe Python candidate discovery, version checks, and cancellation during discovery |
| mcp/…/proc_group_unix.go | Shows how Unix timeouts stop the engine and its managed descendants |
| mcp/…/proc_group_windows.go | Shows the Windows direct-child timeout boundary |
| mcp/…/sync_contract_test.go | Protects the match between the embedded engine and its Python source tree |
| mcp/…/run_test.go | Shows the process, environment, interpreter, timeout, and failure contracts protected by the engine tests |
| mcp/…/python_test.go | Protects interpreter selection, version checks, path rules, and discovery cancellation |
| mcp/README.md | Summarizes the bundle lifecycle, runtime requirements, persistence behavior, and release path |
| skills/…/last30days.py | Defines the command-line modes consumed by the MCP bridge |
| MCP server and research tools | Explains the client-facing tool contract |
| MCP embedded engine | Explains the asset cache and process bridge |
| Research skill execution | Explains the research lifecycle behind the MCP request |
| Runtime configuration and safety | Explains shared credential, privacy, source, and execution rules |
| Distribution and host integrations | Explains how the MCP bundle fits the wider host and release model |
| Evaluation and regression suite | Explains the checks that protect the MCP and runtime contracts |