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.1.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, and source-selection state.
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 eight tools map directly to the facade: research_recent, research_discover, research_start, research_status, 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 solve CAPTCHA challenges, apply stealth or fingerprint evasion, bypass Turnstile, robots, access controls, or authentication, create accounts, make purchases, submit forms, or perform publishing. A denial, challenge, or unsupported page is evidence of a boundary, not permission to evade it. The engine does not promise exhaustive web coverage or automatically validate community sentiment, scholarly claims, or long-term product reliability.

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.