Skip to main content
Glama
Second Read

Second Read

README.md
# Second Read

<!-- mcp-name: io.github.sbanthia92/second-read -->

Second Read reviews a draft the way a careful editor would, and shows its
sources. You give it an article, a blog post or a design doc. It returns one
report:

- **Facts checked against the web.** Each claim is looked up, and every
  "this is wrong" comes with the page that says so.
- **The strongest counter-case.** A devil's advocate builds the best argument
  against your piece from sources it retrieves.
- **Copy edits.** Grammar and clarity fixes that keep your voice.
- **Originality notes.** Sentences that closely match text found online.

It runs as an [MCP](https://modelcontextprotocol.io) server with one tool,
`review_document`, so you can ask for a review from Claude Code or Claude
Desktop. It also has a command-line tool. It runs on your machine with **your
own API keys**; nothing is sent to the author of this project.

A finding looks like this:

> **Factual error** — "Mjällby clinched the title on 20 October 2025 by winning
> 2-0 at IFK Göteborg, with two games to spare"
>
> The date, the 2-0 score and the opponent are confirmed. ESPN and Flashscore
> both say three rounds were left (27 of 30 played), so "two games to spare" is
> wrong.

## What you need

- [uv](https://docs.astral.sh/uv/) (it installs Python 3.12 for you).
- An [Anthropic](https://platform.claude.com) API key: `ANTHROPIC_API_KEY`.
- A [Tavily](https://tavily.com) search key: `TAVILY_API_KEY`.

### Getting your keys

You need two keys. Each takes a couple of minutes: sign up, create a key, copy
it.

| Key | Where to get it |
| --- | --- |
| `ANTHROPIC_API_KEY` | Sign in at <https://platform.claude.com>, add credit under Billing, then create a key under **API keys** (<https://platform.claude.com/settings/keys>) |
| `TAVILY_API_KEY` | Sign up at <https://app.tavily.com>; the key is shown on the dashboard |

The Anthropic key is pay-as-you-go: reviews fail with a clear message if the
account has no credit. Keep keys out of chats and out of version control; put
them in the MCP client's `env` block or in a `.env` file as shown below.

A review of a 700-word article takes about two minutes and uses roughly
150,000–180,000 tokens on your model key (about $0.60–$1.20 at Anthropic's
list prices in October 2026) plus about 30 searches.

## Install: Claude Code

```sh
claude mcp add second-read \
  -e ANTHROPIC_API_KEY=your-key \
  -e TAVILY_API_KEY=your-key \
  -- uvx second-read
```

Start Claude Code with a longer tool timeout, because a review takes minutes:

```sh
MCP_TOOL_TIMEOUT=600000 claude
```

Then ask: "Use second-read to review this draft", and paste the text or give a
public URL.

## Install: Claude Desktop

Add this to `claude_desktop_config.json` (on macOS:
`~/Library/Application Support/Claude/claude_desktop_config.json`), then restart
the app. If Claude Desktop cannot find `uvx`, use its full path (`which uvx`).

```json
{
  "mcpServers": {
    "second-read": {
      "command": "uvx",
      "args": ["second-read"],
      "env": {
        "ANTHROPIC_API_KEY": "your-key",
        "TAVILY_API_KEY": "your-key"
      }
    }
  }
}
```

To try it without keys, replace the `env` block with
`{"SECONDREAD_FAKE": "1"}`. Demo mode returns placeholder findings and makes
no model calls.

## Install: other MCP clients

Any client that runs local (stdio) MCP servers can use the same command. For
Cursor, VS Code and similar, add a server named `second-read` that runs
`uvx second-read` with `ANTHROPIC_API_KEY` and `TAVILY_API_KEY` in its
environment, as in the Claude Desktop example above.

Second Read is listed in the [official MCP Registry](https://registry.modelcontextprotocol.io)
as `io.github.sbanthia92/second-read`, so clients and directories that read the
registry can find it.

ChatGPT and claude.ai on the web connect only to remote (hosted) MCP servers,
so they cannot run Second Read yet. A hosted version is on the
[roadmap](ROADMAP.md).

## Command line

```sh
export ANTHROPIC_API_KEY=your-key TAVILY_API_KEY=your-key
uvx --from second-read secondread review path/to/draft.md --profile opinion > report.md
```

Or keep the keys in a `.env` file and pass it with `--env-file path/to/.env`.

Progress prints to the terminal; the report goes to `report.md`. Use
`--profile design_doc` for technical design docs, or leave the profile out to
let the tool decide. A URL works in place of a file path.

## The tool

`review_document` takes:

| Argument | Required | Notes |
| --- | --- | --- |
| `content` | one of `content` / `url` | The draft as text or markdown (up to 20,000 words) |
| `url` | one of `content` / `url` | A public web page to fetch and review |
| `profile` | no | `auto` (default), `opinion` or `design_doc` |
| `focus` | no | A steer, e.g. "check the financial figures" |

It returns the report as markdown and sends progress updates while it works.

The report has these sections: a verdict line; **Must fix** (factual errors and
claims the sources do not back); **Could not verify** (claims it found no
adequate source for, which is not the same as wrong); **Strongest
counter-case**; **Should fix** (structure); **Polish** (copy edits);
**Originality notes**; and an appendix listing every claim with its verdict and
sources.

## Settings

Set these in the MCP client's `env` block, in the environment, or in a `.env`
file (the server reads `.env` from its working directory, or the file named by
`SECONDREAD_ENV_FILE`).

| Variable | Purpose |
| --- | --- |
| `ANTHROPIC_API_KEY` | Anthropic model key |
| `TAVILY_API_KEY` | Web search key |
| `SECONDREAD_MODEL_CHEAP`, `_MID`, `_STRONG` | Override the model used for each tier |
| `SECONDREAD_MAX_WORDS` | Document size cap (default 20000) |
| `SECONDREAD_FAKE=1` | Demo mode: no keys, no model calls |

## Privacy

Second Read runs on your machine. The project's author runs no server and
receives no data.

- **What it collects.** Nothing is collected by the project. To do a review the
  tool handles the document you give it and the web pages it retrieves.
- **What leaves your machine, and where.**
  - Your document goes to Anthropic, under your key and their terms.
  - Search queries built from your document's claims, and up to eight sentences
    quoted exactly for the originality check, go to Tavily, under your key and
    their terms.
  - Web pages named in search results are fetched directly from your machine.
    The fetcher refuses private and local network addresses.
- **Storage and retention.** Nothing is stored after the review finishes. The
  report is returned to your client and is not kept by Second Read. Logs go to
  your terminal and never contain keys or document text.
- **Sharing.** Nothing is shared with anyone else. The only third parties are
  the model and search providers above, which you choose by supplying their keys.
- **Keys.** Read from your environment or a `.env` file you control, and never
  logged.
- **Contact.** Questions or concerns: open an issue at
  <https://github.com/sbanthia92/second-read/issues>. For security problems see
  [`SECURITY.md`](SECURITY.md).

## How well it works

**What was tested.** Four articles written for the test, each with errors
planted in it that cannot be settled from memory (recent results, exact
figures): 19 planted wrong facts in all. Every planted error has an answer key
recording the exact sentence and the true value. Each article was reviewed once
by two setups:

- **Single prompt:** one request to the model Second Read uses for its
  strongest tier, "review this and argue the other side". No web search, so it
  cannot look anything up or cite a page.
- **Second Read:** the full review described below, with web search.

**What "caught" means.** The report has a factual-error finding on the
sentence that holds the planted error. A "could not verify" note does not
count, so a careful miss scores as a miss. "Rebutted" means a counter-argument
was written against a deliberately weak argument; "caught" for borrowed
sentences means an originality note on the copied sentence.

| | Single prompt | Second Read |
| --- | --- | --- |
| Planted wrong facts caught (of 19) | 7 | 13 |
| ...of those, with a cited source | 0 | 13 |
| Weak arguments rebutted (of 4) | 2 | 4 |
| Borrowed sentences caught (of 3) | 3 | 1 |
| Tokens per article | about 5,000 | about 136,000 |

**Reading the result.** Second Read earns its cost on claims that need looking
up: recent events, exact figures, and details a model cannot know from memory.
The gain appears to come mainly from searching and reading sources, though
this test did not separate that from the other design choices. Every finding
names its source so you can check it in one click. It is slower, uses about 27
times the tokens, and did worse on borrowed sentences.

**Limits of this test.** It is small: 19 errors, one run each, so each error
is worth about five points and the exact percentages are rough. It does not
measure false alarms (true facts wrongly called wrong) for either setup. It
does not say which of the six misses were careful "could not verify" results
and which were missed outright. A larger run (all 40 documents, three runs
each) is on the [roadmap](ROADMAP.md).

Getting the most from it:

- Open the cited source before acting on a "factual error". The report links
  the page and quotes the passage it relied on.
- Search results change, so two runs on the same draft can differ slightly.
- The originality check is a heuristic: it flags close matches found online.
- Sources are web pages; PDFs are not read.

## How it works

An orchestrator runs specialist agents and settles their disagreements:

1. A **claim extractor** splits the document into its thesis, supporting
   claims and checkable facts.
2. In parallel: a **fact-checker** researches each fact in a bounded loop
   (search, fetch, read, assess; at most three rounds per claim); a **devil's
   advocate** gathers counter-evidence; a **copy editor**; for articles, an
   **originality checker**; and, for design docs, a **structure reviewer**.
3. A reaction round: a verified fact the devil's advocate disputes is
   re-checked, and the two argue once over the most important disagreements.
4. Fixed rules settle what is left (for example, a grammar fix on a sentence
   flagged as wrong is dropped), findings are ranked, and the report is written.

`ARCHITECTURE.md` describes how the system is built, the decisions behind it and their trade-offs, the planned hosted service, and the shared types.

## Development

```sh
uv sync
uv run ruff check . && uv run ruff format --check . && uv run mypy && uv run pytest
```

Tests run offline with fakes. Tests that call real providers are marked `live`
and skipped by default (`uv run pytest -m live`). The evaluation harness and
its 40 seeded documents are in `eval/` (see `eval/README.md`); running it
against real providers spends money on your keys.

## Status

The local MCP server and command-line tool work. A hosted version (sign in,
add a key once, get the report by email) is designed in `ARCHITECTURE.md` but not
built. `ROADMAP.md` lists what comes next.

## License

MIT. See `LICENSE`.

TDQS

A4.4/5.0

Scored across 1 tool

Disambiguation5/5

With a single tool there is no possibility of misselection; the tool's purpose (multi-perspective document review) is stated explicitly and unambiguously. The input contract (exactly one of `content` or `url`) and the report shape are spelled out, leaving no room for a competing interpretation.

Naming Consistency5/5

`review_document` follows a clean verb_noun snake_case pattern that describes exactly what it does. There are no other names to clash with or deviate from.

Tool Count3/5

A one-tool server is inherently thin against the 3-15 sweet spot, even though the single tool internally bundles several specialist reviewers. It works as a focused capability, but there is no granularity — you cannot invoke just the fact-checker or just the copy editor.

Completeness4/5

The tool covers the core end-to-end review workflow (fact-check, counter-case, structure, copy edit, originality) and returns a structured markdown report, so the primary job is done. Minor gaps exist: no way to re-run a targeted subset of reviewers, iterate on a revised draft, compare versions, or retrieve a past report.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues