Metadata-Version: 2.4
Name: travis234-evidence-mcp
Version: 0.3.0
Summary: Optional local evidence research MCP server for Travis234.
License-Expression: MIT
Requires-Python: <3.14,>=3.13
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27
Requires-Dist: mcp<3,>=2
Requires-Dist: selectolax<1,>=0.3
Requires-Dist: travis234-mcp-adapter<0.5,>=0.4
Provides-Extra: browser
Requires-Dist: playwright>=1.59; extra == "browser"
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: pytest-asyncio>=1; extra == "test"

# 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:

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

Activation is explicit and process-local:

```console
travis234 --research
```

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

```console
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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```console
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`:

```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`:

```json
{"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:

```text
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.
