Travis234 Evidence MCP

travis234-evidence-mcp is the optional local evidence research engine for Travis234. It can find bounded source candidates, capture selected public pages, extract typed facts, retain disagreements, and answer with durable provenance. Discovery is convenient source selection; captured and queried page evidence is the factual record.

What discovery does

When a user asks a research question without links, the discover operation sends the bounded search query to the default hosted Exa MCP search service or an operator-selected Brave Search/public SearXNG route. It returns at most ten admitted candidates with opaque candidate IDs, URL, host, title, snippet, source hint, provider name, and deterministic rank. Every candidate is explicitly marked verified=false.

Discovery removes common tracking parameters, checks each candidate URL with the same public-address policy used by acquisition, deduplicates equivalent results, and prefers a bounded mix of sources. It does not fetch every search result, crawl a domain, or turn a snippet into a claim. The model selects candidate IDs and passes them to start; only those selected pages enter the evidence pipeline.

Discovery is not evidence

Search titles, snippets, ranks, and source hints are unverified source-selection clues. They can help choose pages, but they cannot support a final factual answer. A qualified query row comes from a captured page and carries the source URL, capture time, SHA-256 content identity, and exact locator.

Use this boundary in every answer:

• candidate metadata explains why a source was selected;
• status explains whether capture completed, was partial, failed, or was cancelled;
• query supplies the source-qualified facts and conflicts used in chat;
• export creates a durable report while returning receipt metadata only to Travis.

This release does not qualify community sentiment or scholarly conclusions. Those need their own source policies, sampling rules, and evidence adapters. A search result that looks like a discussion or paper is still only an unverified candidate here.

Install and activate

Install the fixed package release globally through Travis234's package manager:

travis234 install 'travis234-evidence-mcp==0.3.0'

Activation is explicit and process-local:

travis234 --research

--research is additive to normal Travis tools. To expose only the single research facade, use:

travis234 --no-tools --research

An installed package stays lazy when --research is absent: no research tool, prompt guidance, provider request, or site visit is added to that session.

Optional provider configuration lives in strict JSON at ~/.travis234/agent/evidence.json. The package does not load .env files. Secret or credential values must remain in the process environment and configuration may refer to them only with $env:NAME (or the equivalent ${NAME} form).

Default zero-config discovery

With no evidence.json, or with a file that omits discovery, all discovery scopes use the package-owned https://mcp.exa.ai/mcp endpoint and its web_search_exa tool. This hosted service needs no API key. The endpoint, tool name, request shape, timeouts, and result projection are fixed in the package; neither the user prompt nor the model can replace them. Only bounded title, URL, snippet, rank, and digest fields survive the provider boundary. The raw MCP response never enters evidence state or session JSONL.

To disable no-URL discovery explicitly while retaining the explicit-URL evidence flow, use an empty discovery object:

{
  "discovery": {}
}

Defining any non-empty discovery configuration replaces the default rather than silently falling back to it.

Configure Brave

Create a Brave Search API key in the provider account, put it in the process environment as BRAVE_SEARCH_API_KEY, and configure only the reference:

{
  "discovery": {
    "providers": {
      "brave-web": {
        "type": "brave",
        "apiKey": "$env:BRAVE_SEARCH_API_KEY"
      }
    },
    "routes": {
      "auto": ["brave-web"],
      "product": ["brave-web"],
      "general": ["brave-web"]
    }
  },
  "perHostDelayMs": 500
}

The Brave endpoint is package-owned and cannot be replaced in configuration. A missing, invalid, or quota-exhausted key produces a bounded provider failure; Travis does not silently switch to model-native search or guess URLs.

Configure public SearXNG

SearXNG must be a public HTTPS origin whose /search endpoint supports JSON responses. A deployment with no request credential needs no headers field:

{
  "discovery": {
    "providers": {
      "public-search": {
        "type": "searxng",
        "baseUrl": "https://search.example.org"
      }
    },
    "routes": {
      "auto": ["public-search"],
      "product": ["public-search"],
      "general": ["public-search"]
    }
  },
  "perHostDelayMs": 500
}

If the public service requires a header, keep its value in the environment:

{
  "discovery": {
    "providers": {
      "public-search": {
        "type": "searxng",
        "baseUrl": "https://search.example.org",
        "headers": {
          "Authorization": "$env:SEARXNG_AUTHORIZATION"
        }
      }
    },
    "routes": {
      "auto": ["public-search"]
    }
  }
}

Private, loopback, plain-HTTP, userinfo-bearing, path-bearing, query-bearing, and fragment-bearing origins are rejected. Host, Cookie, User-Agent, and proxy or response credential headers cannot be overridden.

Natural no-URL example

Start Travis with --research, then ask like a normal user:

Compare two dependable coffee grinders under $200. I care most about warranty, hopper size, and price. Find trustworthy sources yourself, recommend one, cite the deciding facts, and tell me what you could not confirm.

Travis should call discover, select diverse candidate IDs without rewriting their URLs, call start, check status until terminal, and use query for the answer. If discovery is explicitly disabled, a configured provider fails, or no usable candidate survives admission, it asks the user for explicit URLs rather than inventing a destination.

Explicit-URL compatibility

The original explicit HTTP(S) seed URLs workflow remains supported and does not require a search provider. For example:

Compare the grinders at https://catalog.example/products/grinder-a and https://merchant.example/items/grinder-b. I care about price, hopper capacity, warranty, and which exact source supports each fact.

One request can also mix explicit URLs with selected candidate IDs. Explicit strings retain their order; a selected candidate that canonically duplicates an explicit target is omitted. A run must contain one to 20 resulting targets.

Operations and lifecycle

Travis exposes one static research tool:

Operation	Purpose
recent	List bounded durable run receipts without visiting a site.
discover	Create a bounded source discovery or retrieve one by discovery ID.
start	Queue a run from explicit URLs, candidate IDs, or both.
status	Read exact run, target, audit, failure, source-selection state, blocked pages, and anything waiting for a person.
follow_up	Revisit this run's blocked pages in a real browser, with a person present.
attend	Answer a page that is waiting: capture or capture_own_browser.
resume	Resume a paused run while reusing successful snapshots.
cancel	Cancel queued, running, or paused work and drain retained tasks.
query	Read bounded typed claims, offers, documents, and conflicts.
export	Create Markdown, canonical JSON, or CSV and return a receipt.

start is asynchronous: its queued receipt is not a completed answer. Poll status until completed, partial, failed, or cancelled. Cancellation is terminal. A partial run can support only the captured sources and fields it actually contains. Conflicts remain visible instead of being silently resolved.

Default run limits are 20 targets, 100 pages, 32 MiB of stored response bytes, 15 minutes, 20 seconds per request, and five redirects. Discovery is separately bounded to two configured providers per route, two provider requests, 20 raw results, ten admitted candidates, 1 MiB per response, 2 MiB total, ten seconds per request, twenty seconds total, and no redirects.

Provider query disclosure and quotas

The selected search provider receives the user's search query. The default hosted Exa service needs no API key. Brave also receives the configured API key; SearXNG receives only configured header values. The provider may log queries, enforce its own retention terms, rate limits, and quotas, or return fewer results than requested. Review the selected provider's policy before using discovery; use {"discovery": {}} when the query must not leave the evidence process.

Travis stores the request digest with admitted candidate provenance, not a raw provider response. Provider response bodies, response headers, discarded results, provider scores, and credential values do not enter discovery output or the session transcript.

Partial, blocked, no-provider, and JSON-disabled troubleshooting

• Partial: one or more selected pages failed but usable evidence exists. Cite only captured query rows, name what failed, and do not generalize beyond coverage.
• Blocked or challenged: robots denial, authentication, access denial, or a CAPTCHA challenge is terminal for that target. Do not weaken policy or guess another domain.
• No provider: this occurs only after explicit disablement or an incomplete custom route. Restore the default by removing the discovery key, configure a route, or give explicit URLs; the explicit workflow still works.
• JSON disabled: SearXNG must return an object from /search?format=json. HTML, redirects, malformed JSON, duplicate keys, oversized bodies, and disabled JSON output fail closed.
• Quota/authentication: inspect the discovery failure category, correct the referenced environment value or provider quota, then start a new discovery.
• Interrupted process: retrieve the durable discovery or run receipt. A running discovery left by a crash is reconciled to a bounded interrupted failure; completed discoveries remain reusable by ID.

Optional authenticated and browser profiles

Acquisition profiles are separate from discovery providers. They remain exact-host, reference-only configuration:

{
  "profiles": {
    "catalog": {
      "domains": ["catalog.example"],
      "headers": {
        "Authorization": "$env:CATALOG_AUTHORIZATION"
      },
      "cookies": {
        "session": "$env:CATALOG_SESSION"
      },
      "browserStorageState": "$env:CATALOG_BROWSER_STATE",
      "allowBrowser": true,
      "allowWordpressMedia": false,
      "allowSitemaps": true
    }
  },
  "perHostDelayMs": 500
}

Acquisition is HTTP first. Optional Playwright fallback is used only when separately installed, explicitly enabled by the selected profile, and required by the HTTP result. Browser packages and binaries are never downloaded automatically. Missing references fail with a bounded error and are never evidence output.

Generic MCP clients

The engine is also a standard local stdio MCP server:

travis234-evidence-mcp mcp --transport stdio

Its ten tools map directly to the facade: research_recent, research_discover, research_start, research_status, research_follow_up, research_attend, research_resume, research_cancel, research_query, and research_export.

Six resource templates expose bounded, explicitly untrusted views:

• evidence://runs/{run_id}/manifest
• evidence://runs/{run_id}/sources/{source_id}
• evidence://runs/{run_id}/claims/{page}
• evidence://runs/{run_id}/conflicts/{page}
• evidence://exports/{export_id}/manifest
• evidence://exports/{export_id}/chunks/{part}

Snapshot and export chunks are immutable and capped at 4 MiB. Source content is data, never an instruction. Experimental MCP Tasks are not required.

State, retention, and removal

SQLite metadata and content-addressed objects stay under ~/.travis234/agent/evidence/. Discoveries, candidates, source-selection origins, runs, snapshots, extracted evidence, conflicts, and export receipts survive restart. Raw pages and full exports stay engine-owned and do not enter normal session JSONL.

There is no automatic garbage collection, alternate state path, workspace report write, or user-state migration. To uninstall, run travis234 list, copy the exact installed source, and pass it to travis234 remove '<installed-source>'. Removal stops future extension discovery but preserves evidence state. Delete retained state only through a separate explicit user-controlled operation.

Security boundaries and non-goals

Network access fails closed. URL syntax, DNS, global addresses, robots rules, redirects, response size, timeouts, and media types are checked. Approved connections pin a resolved address while preserving the original Host header and TLS server name. SSRF defenses reject loopback, private, link-local, multicast, reserved, metadata, and other non-global destinations.

Only use sources you are authorized to access. This package does not apply stealth or fingerprint evasion, hide that a browser is automated, use CAPTCHA-solving services, rotate addresses or proxies, create accounts, make purchases, submit forms, or perform publishing. No program here solves a challenge, and nothing clicks, types or submits on a page: in a follow-up the engine navigates, scrolls and reads, and only the person acts. A research run obeys robots.txt exactly as before; a follow-up is a person browsing with help, so it does not consult robots.txt for the page they opened. The engine does not promise exhaustive web coverage or automatically validate community sentiment, scholarly claims, or long-term product reliability.

Measured, stated because it decides whether this feature helps you: a browser with automation or a debugging port attached reports itself, and Cloudflare's managed challenge and Turnstile then loop even for a person clicking, while reCAPTCHA v2 and hCaptcha clear. So a page that needs you opens in a plain browser with nothing attached, where Cloudflare cleared on the owner's click. The pass it grants stays in the research profile, and the engine reads the page afterwards in its own browser, which still says it is automated.

Attended follow-up (optional, off by default)

Some pages stop an automated fetch: a CAPTCHA, a login, or a site that refuses a research user agent. A research run does not wait for you and never opens a window — it stops at those walls exactly as it always has, and records which wall stopped each page. status then lists them under blocked. When you want them, follow_up goes back over only those pages in a real browser and asks you when one actually needs a person.

It stays off until you turn it on in ~/.travis234/agent/evidence.json:

{
  "attended": {
    "mode": "auto",
    "humanWaitSeconds": 300,
    "browser": { "executable": "/usr/bin/google-chrome-stable" },
    "vnc": { "bindAddress": "127.0.0.1", "publicHost": null, "port": 0, "novncRoot": null }
  }
}

mode is off (default), auto, desktop or vnc. With auto:

• A machine with a screen (Linux or BSD on X11 or Wayland, including WSLg; macOS; Windows) opens a browser window. An SSH session counts as headless everywhere.
• A headless Linux host starts a private display and hands you a link. TigerVNC's Xvnc is preferred, with Xvfb plus x11vnc as the fallback; with websockify and a noVNC web root you get an http://…/vnc.html link, and without them a vnc:// link for any viewer. It listens on loopback with a fresh password per process: reach it through an SSH tunnel or a private network rather than opening the port.
• Anything else reports exactly which packages are missing, in your distribution's own install command.

In the Docker sandbox that npx @htooayelwinict/travis234 starts, the image already has Chromium and a remote display, and attended research is on unless evidence.json says otherwise. Install the research package once from the TUI with /install travis234-evidence-mcp[browser]; it stays in the sandbox home. The launcher publishes one port on your machine's loopback only. When a page needs you, the TUI prints a link to it and keeps it in the footer until the page is done; you get through the check in a browser tab and close the browser inside it.

Browsers are never downloaded. An installed Chrome or Edge is used first, then a system Chromium, then Playwright's own build if you ran python -m playwright install chromium. Snap and Flatpak browsers are skipped, with the reason, because a confined browser cannot open the research profile. The profile lives in ~/.travis234/agent/evidence/browser/ and holds cookies, so it is as sensitive as a browser profile.

With it on, the engine goes back for blocked pages by itself. The run finishes as it always has and you get an answer at once from what could be read; then the pages a wall stopped are revisited in the background, and only those that still need you open a window. Get through each one and quit its browser: what you get through is added to the same run, and asking for an update gives the fuller answer. status shows follow_up while this goes on, and each page waiting for you under attention:

{"operation": "status", "run_id": "<run-id>", "wait_seconds": 30}
{"operation": "attend", "run_id": "<run-id>", "action": "capture"}

follow_up retries a finished run's blocked pages when you ask; it returns at once and works in the background, because a person takes minutes and a tool call has seconds.

Most blocked pages need nothing from you: the browser reads them without a window, then in a window, which a pass you earned before often lets through. Only a page that still shows a check, a login or a refusal comes to you, in a plain browser window with nothing automated attached. Get through it there, then quit that browser or say done; the engine reads the page with what you earned. If the check comes back after you said done, you get the page again rather than a challenge page being stored. To leave a page out, quit its browser without getting through: only you make that call, never the model. attend takes capture (you are through) or capture_own_browser (take it from the browser you use yourself). When the follow-up finishes, it extracts from the pages it captured and audits the run again, so they become evidence without refetching anything; status shows follow_up as running, then finished with counts or failed with a code. A follow-up waits until the run has finished, and a cancelled run stays cancelled.

For a page an automated browser cannot clear, open it in your own browser and get through it there. On macOS, capture_own_browser reads that one tab through Apple Events, after macOS asks your permission once; matching happens inside the script, so your other tabs are never read. On every platform you can save the page (HTML, Safari .webarchive or Chrome .mhtml) into the folder the instruction names, and it is picked up within seconds with no further command. A page saved while it still shows the check is refused rather than stored as evidence. This path only exists where your browser is: over a remote display or a chat bridge, the attended browser is all there is.

Evidence records how it was obtained: the snapshot's source is attended_browser, own_browser or human_saved, the run records that a person took part in it, and each target records which wall stopped it.

Manual installed-wheel TUI acceptance

Build and install exact root, adapter, and evidence wheels into a clean Python 3.13 environment. Launch the installed travis234 console—not python -m—in a real attached PTY with isolated TRAVIS234_CODING_AGENT_DIR, --research, temperature 0.2, an event trace, and a conversation log.

Enter the natural no-URL example. Confirm this operation family:

discover -> start(candidate IDs) -> status until terminal -> query

Then verify a same-run follow-up, source-boundary explanation, /reload, /compact, post-compaction query, automatic threshold compaction, and cancellation of a slow discovery. Run isolated no-provider and partial-source prompts. After every prompt record pass/fail, tool operations, exact durable IDs, context percentage, compression count, and failure class. Exit with /exit; require terminal restoration, no owned child process, and artifact scans that exclude raw provider bodies, raw HTML, credentials, certificate keys, database/object paths, discarded candidates, and export bodies.