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.
| Input | Required | Values | Purpose |
|---|---|---|---|
format | No | text or json | Selects 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.
| Input | Required | Default | Purpose |
|---|---|---|---|
topic | Yes | None | Person, company, product, event, or general subject to research |
emit | No | compact | Use compact output for model synthesis or html for a shareable brief |
save | No | false | Persist 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:
- Validate the topic, output mode, and save flag.
- Prepare the embedded engine for the installed server version.
- Run the engine with request-specific arguments and internal planning enabled.
- 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
preflightandresearchdirectory 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, orsavecan 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
| Trigger | Consequence | Guard |
|---|---|---|
| The manifest entry point does not match the packaged binary | The host cannot start the server | Manifest structure checks and release packaging alignment |
| A manifest environment reference names no declared user setting | A provider credential is absent while the server appears healthy | Cross-reference checks for every environment mapping |
topic is missing, blank, or not a string | No research starts and the client receives a readable tool error | Required non-empty string validation |
emit or format uses an unsupported value | The request is rejected before engine work | Closed value sets with MCP error results |
| A topic starts with an engine option marker and no separator protects it | The engine may parse user input as a control flag | Place the topic after -- |
save is false while the memory directory environment is set and no empty directory is passed | The engine may write a report even though the client declined to save | Pass an explicit empty save directory |
| The engine reports degraded sources without a complete rendered report | A partial or clarification response may be presented as research | Require 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 response | The client may treat skill-only guidance or raw role text as research evidence | Remove those sections from the client-facing output |
LAST30DAYS_PYTHON is empty or does not resolve to an executable | The engine does not start and the client receives setup guidance | Explicit override validation and a clear Python install path |
Python 3.12+ is not available as python3 on PATH | The tool cannot start the research engine | Startup error names the required interpreter and install URL |
| Cache preparation cannot write to its location | Both tools fail before the engine runs | Set LAST30DAYS_CACHE_DIR to a writable location |
| Browser-cookie access is requested without the explicit MCP opt-in | The research run proceeds without browser cookies | Default-deny argument construction |
| The engine exits or exceeds its time limit | The client receives an error instead of research output | Include exit or timeout cause and engine standard-error text |
Key files
| File | Why to read it |
|---|---|
| mcp/…/main.go | Shows the server entry point, stdio transport, and startup registration |
| mcp/manifest.json | Defines host launch, optional provider credential wiring, supported platforms, and declared research coverage |
| mcp/…/manifest_test.go | Defines the manifest and release-matrix checks that protect install correctness |
| mcp/…/research.go | Defines research registration, request validation, safety options, degraded results, and client-facing output |
| mcp/…/preflight.go | Defines the read-only planning contract and report formats |
| mcp/…/run.go | Explains the boundary between MCP requests and engine process results |
| mcp/…/research_exit_test.go | Shows the distinction between complete, degraded, and failed research responses |
| mcp/…/research_test.go | Shows the client-facing argument, safety, output, and error contracts |
| mcp/…/preflight_test.go | Shows the shared safety rules for preflight and research |
| mcp/README.md | Gives the bundle lifecycle and runtime prerequisites |
| MCP integration | Places the server in the wider MCP bridge |
| MCP embedded engine | Explains engine embedding, extraction, and process execution |