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-server-and-research-tools

MCP server and research tools

The MCP server gives an MCP client a small interface to Last30Days research. It starts as a bundled binary, registers preflight and research tools, and turns each tool call into a request to the embedded research engine. The client receives a complete report, a report with a degraded-coverage status, or a readable tool error over the same connection.

Client connection and startup

The server uses the MCP standard input/output transport so a host can start it as a child process and exchange requests without opening a network port. The command entry point creates the server, registers its tools, and stays available until the host closes the connection.

The bundle manifest is the host-facing startup contract. It points the host to bin/last30days-pp-mcp and maps optional provider credentials to environment values. The settings cover source access for Reddit, X, YouTube, Hacker News, Polymarket, GitHub, TikTok, Instagram, Bluesky, and web search. They also cover creator-focused social search, parallel research, and synthesis providers such as OpenRouter. The manifest supports Claude Desktop on macOS and Linux. No credential is install-blocking because the research engine can use reduced source coverage.

This diagram shows how a host turns an installed bundle into an MCP session.

flowchart LR
    A[Client installs bundle] --> B[Manifest selects binary]
    B --> C[Server starts over stdio]
    C --> D[Tools register]
    D --> E[Client sends tool call]
    E --> F[Tool returns MCP result]

Launch contract

The packaged command is bin/last30days-pp-mcp. The manifest declares the binary server type, the host command, optional provider settings, and supported platforms. Each user setting maps to one environment value so the running server can pass provider access to the research engine. This includes an app-only X bearer token and an alternate OpenRouter synthesis provider.

References: mcp/manifest.json• L28-49 mcp/manifest.json• L51-159 mcp/…/main.go• L16-36 mcp/…/manifest_test.go• L68-209

Tool registration

The server exposes two client-facing tools. preflight describes the planned access and side effects. research runs a topic search and tells the client when source coverage is degraded. Both tools use the same engine bridge and return normal output as MCP content.

References: mcp/…/research.go• L28-84 mcp/…/preflight.go• L14-28 mcp/…/research_exit_test.go• L13-71

Preflight tool contract

The preflight tool lets a client inspect a planned run before it performs research. It asks the engine for a summary of resources it may read, write, execute, or contact. It does not run research, save a report, or read browser cookies.

Inputs and planned scope

The tool accepts one optional format value. The default is concise text; json requests structured details. Any other type or value becomes a client-visible tool error before the engine runs.

InputRequiredValuesPurpose
formatNotext or jsonSelects the preflight response shape

The report includes the configured report directory. It uses LAST30DAYS_MEMORY_DIR when present and otherwise uses ~/Documents/Last30Days. This makes the preflight result match the directory that a later save can use.

References: mcp/…/preflight.go• L18-25 mcp/…/preflight.go• L66-89 mcp/…/preflight_test.go• L32-89 mcp/…/research.go• L245-253

Responses and safety boundary

On success, the tool returns the engine's text or JSON report as MCP text content. On invalid input or a runtime failure, it returns an MCP tool result marked as an error rather than a transport failure. The preflight contract gives a client a readable answer while keeping the session usable for later calls.

References: mcp/…/preflight.go• L30-62 mcp/…/preflight_test.go• L65-89 mcp/…/research_test.go• L228-257

Research tool contract

The research tool is the main client entry point for current-topic research. It sends a topic to the Last30Days engine, which gathers recent material across supported sources and returns evidence for the calling model or client to use. The tool treats that evidence as untrusted research data rather than as instructions.

Inputs and output modes

The topic input is required and must contain a non-empty string. The optional emit input selects the output shape. The optional save input asks the engine to persist a markdown report.

InputRequiredDefaultPurpose
topicYesNonePerson, company, product, event, or general subject to research
emitNocompactUse compact output for model synthesis or html for a shareable brief
saveNofalsePersist the synthesis under the configured Last30Days directory

The MCP path denies browser-cookie use by default. An explicit LAST30DAYS_MCP_ALLOW_BROWSER_COOKIES value of 1, true, yes, or on enables the request to use that engine feature. The engine still applies its own consent and configuration checks. When save is true, the report directory follows the same environment override as preflight. When save is false, the request passes an explicit empty save directory so an environment setting does not cause an unintended write. A complete run returns the engine's compact or HTML report without an extra MCP wrapper. The server removes internal job evidence and report-writing guidance that the MCP client does not receive from the skill context.

The topic is passed after an argument separator. This keeps a topic that starts with a dash from being read as an engine option.

References: mcp/…/research.go• L23-51 mcp/…/research.go• L60-84 mcp/…/research.go• L213-243 mcp/…/research.go• L168-210 mcp/…/research_test.go• L124-226

Request handling

Each request follows a short sequence that keeps input checks separate from engine work:

  1. Validate the topic, output mode, and save flag.
  2. Prepare the embedded engine for the installed server version.
  3. Run the engine with request-specific arguments and internal planning enabled.
  4. Return standard output, a structured degraded report, or an MCP tool error.

This diagram shows the shared path from a client call to its response.

sequenceDiagram
    participant C as MCP client
    participant S as MCP server
    participant E as Research engine
    C->>S: Call preflight or research
    S->>S: Validate arguments
    S->>E: Prepare runtime and run request
    E-->>S: stdout or failure with stderr
    S-->>C: Text result, degraded report, or MCP tool error

References: mcp/…/preflight.go• L30-62 mcp/…/research.go• L87-141 mcp/…/research.go• L245-253 mcp/…/run.go• L64-117

Client-facing failure modes

The server reports failures at the tool boundary so the client can show the cause in context. Validation failures name the bad field. Setup failures explain that the engine could not be prepared. Engine failures include available standard-error text. A run that produces a complete report but loses some sources is not treated as a hard failure.

The key distinction is between a tool error and a broken MCP session. A bad request or failed research run becomes an error result with readable text. A valid report with a strict degraded-source exit becomes structured content with status: degraded. Only failure of the stdio server itself ends the process and breaks the session.

Runtime prerequisites

The host needs Python 3.12 or newer. By default the server resolves python3 on PATH; LAST30DAYS_PYTHON can select another executable when it resolves to a valid path. The server applies a five-minute default limit to one engine run. Operators can change that limit with LAST30DAYS_MCP_TIMEOUT using a duration such as 750ms or a positive integer number of seconds.

References: mcp/README.md• L30-36 mcp/…/run.go• L17-41 mcp/…/run.go• L86-117 mcp/…/run.go• L120-169

Error responses

The server returns an MCP error result for missing or invalid arguments, unavailable embedded source, cache preparation failures, a missing research script, missing Python, hard engine exits, and timeouts. A strict exit with a valid rendered report and a degraded-source receipt returns structured content with status: degraded instead. When the engine produces standard-error text, the response appends it so the client can diagnose a hard failure without reading a local log.

References: mcp/…/preflight.go• L32-60 mcp/…/research.go• L87-141 mcp/…/research.go• L145-166 mcp/…/research.go• L299-308 mcp/…/research_exit_test.go• L13-71 mcp/…/run.go• L72-117

Change checklist

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

  • Keep the manifest binary path, package entry point, and release artifact name aligned. A mismatch can install a bundle that the host cannot start.
  • Keep every manifest environment substitution paired with one declared user setting. A typo silently prevents a credential from reaching the engine.
  • Keep preflight and research directory rules aligned. A client should not receive a preflight report for a different save location than the later research call uses.
  • Keep accepted tool values aligned with the arguments sent to the engine. Changes to emit, format, or save can break clients without changing the MCP transport.
  • Keep the degraded-report check aligned with the engine's exit code, receipt, and complete-output markers. A partial report must not become either a hidden success or a hard error.
  • Keep response cleanup aligned with the client-facing research contract. Internal job evidence and report-writing guidance must not leak back into the MCP result.
  • Keep browser-cookie access denied unless the MCP opt-in and the engine consent rules both allow it. A change at only one layer can weaken or falsely advertise the safety boundary.
  • Keep the topic separator and explicit empty save directory in the request contract. Removing either can turn user input into an engine option or cause an unwanted report write.
  • Keep Python selection and timeout override rules aligned with their error messages. Invalid overrides must not silently select a different interpreter or limit.
  • Keep tool failures as MCP result errors when the client needs to continue the session. Returning a Go error instead can turn a request problem into a transport-level fault.
  • Keep each new manifest credential mapping paired with its user setting and the provider capability it enables. A declared key that is not wired to the expected environment name can appear configurable while having no effect.

Important failure modes

TriggerConsequenceGuard
The manifest entry point does not match the packaged binaryThe host cannot start the serverManifest structure checks and release packaging alignment
A manifest environment reference names no declared user settingA provider credential is absent while the server appears healthyCross-reference checks for every environment mapping
topic is missing, blank, or not a stringNo research starts and the client receives a readable tool errorRequired non-empty string validation
emit or format uses an unsupported valueThe request is rejected before engine workClosed value sets with MCP error results
A topic starts with an engine option marker and no separator protects itThe engine may parse user input as a control flagPlace the topic after --
save is false while the memory directory environment is set and no empty directory is passedThe engine may write a report even though the client declined to savePass an explicit empty save directory
The engine reports degraded sources without a complete rendered reportA partial or clarification response may be presented as researchRequire the strict-exit receipt and the compact or HTML completion marker before returning degraded content
Internal job evidence or the report checklist reaches the MCP responseThe client may treat skill-only guidance or raw role text as research evidenceRemove those sections from the client-facing output
LAST30DAYS_PYTHON is empty or does not resolve to an executableThe engine does not start and the client receives setup guidanceExplicit override validation and a clear Python install path
Python 3.12+ is not available as python3 on PATHThe tool cannot start the research engineStartup error names the required interpreter and install URL
Cache preparation cannot write to its locationBoth tools fail before the engine runsSet LAST30DAYS_CACHE_DIR to a writable location
Browser-cookie access is requested without the explicit MCP opt-inThe research run proceeds without browser cookiesDefault-deny argument construction
The engine exits or exceeds its time limitThe client receives an error instead of research outputInclude exit or timeout cause and engine standard-error text

Key files

FileWhy to read it
mcp/…/main.goShows the server entry point, stdio transport, and startup registration
mcp/manifest.jsonDefines host launch, optional provider credential wiring, supported platforms, and declared research coverage
mcp/…/manifest_test.goDefines the manifest and release-matrix checks that protect install correctness
mcp/…/research.goDefines research registration, request validation, safety options, degraded results, and client-facing output
mcp/…/preflight.goDefines the read-only planning contract and report formats
mcp/…/run.goExplains the boundary between MCP requests and engine process results
mcp/…/research_exit_test.goShows the distinction between complete, degraded, and failed research responses
mcp/…/research_test.goShows the client-facing argument, safety, output, and error contracts
mcp/…/preflight_test.goShows the shared safety rules for preflight and research
mcp/README.mdGives the bundle lifecycle and runtime prerequisites
MCP integrationPlaces the server in the wider MCP bridge
MCP embedded engineExplains engine embedding, extraction, and process execution