Metadata-Version: 2.4
Name: travis234-evidence-mcp
Version: 0.1.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.4,>=0.3
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.1.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, 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:

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

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