# ScholarWright MCP — v5.14.20

An MCP (Model Context Protocol) server exposing an academic-integrity and
manuscript-preparation system as tools for any MCP-capable client — Claude
Desktop, Claude Code, and others.

**196 tools · 17 layers · runs entirely on your machine.**

`sw_status` is the authoritative source for version, layer count and the tool
list. It derives the catalogue from the server's own source at call time, so it
cannot go stale. If this README and `sw_status` disagree, **`sw_status` is right
and this file needs updating.**

---

## What it does

**Auditing** — inspects a manuscript the author already wrote and flags integrity
problems: implausible statistics, unverifiable or unsupported citations,
publication-ethics issues, formatting violations, figure-resolution failures.

**Assisting** — searches the literature, positions the work against the published
evidence base, formats to a journal's exact specification, builds the submission
package.

**Gating** — refuses to let weak work proceed cheaply. `validate_hypothesis` gates
writing, `build_argument_skeleton` gates drafting, and `assess_novelty_position`
surfaces the crowding problem before submission rather than after rejection.

**Learning** — the loop is closed. Every audit reads accumulated discipline and
journal profiles before flagging, and writes its surviving findings back
afterwards. Pass `discipline` to `generate_flag_table` and
`generate_final_audit_report` on every run, or nothing accumulates.

**Reporting (v5.14.20)** — `generate_final_audit_report` now produces **two
structured DOCX reports by default** alongside the weighted readiness score:

| Report | File | Contents |
|--------|------|----------|
| Auto-corrections | `<slug>_SW_Auto_Corrections.docx` | Every flag SW resolved automatically — location, original text, correction applied. Author should verify. |
| Author actions | `<slug>_Author_Actions_Required.docx` | Every flag still needing author intervention, grouped CRITICAL → HIGH → MEDIUM → LOW with action instructions. |

Pass `split_reports=False` to suppress the split. Pass `project_slug` to control
the filename prefix (derived from `manuscript_title` if omitted).

---

## Install

```
pip install -r requirements.txt
```

Register in your client's MCP config — exactly one entry:

```json
{
  "mcpServers": {
    "scholarwright": {
      "command": "<path-to-python>",
      "args": ["C:/scholarwright_mcp/scholarwright_mcp.py"],
      "env": {
        "SCHOLARWRIGHT_MAILTO": "you@example.org",
        "SCHOLARWRIGHT_MAX_CALLS": "5000",
        "SCHOLARWRIGHT_RATE_PER_MIN": "600"
      }
    }
  }
}
```

A ready-to-edit `claude_desktop_config.json` is included — copy the
`scholarwright` block into your Claude Desktop `claude_desktop_config.json`
and adjust the Python path and mailto address.

Restart the client afterwards — environment variables are read only at server
startup. This is not a Claude extension; the `.mcpb` format is dead and
ScholarWright must not be packaged as one.

### Environment variables

| Variable | Default | Purpose |
|---|---|---|
| `SCHOLARWRIGHT_MAILTO` | `scholarwright@example.org` | Crossref/OpenAlex polite pool. Set it to a real address. |
| `SCHOLARWRIGHT_MAX_CALLS` | `5000` | Session call cap. `0` disables. |
| `SCHOLARWRIGHT_RATE_PER_MIN` | `600` | Global ceiling only — per-host limits do the real work. |
| `SCHOLARWRIGHT_CIRCUIT_THRESHOLD` | `5` | Consecutive failures before a host's circuit opens. |
| `SCHOLARWRIGHT_CIRCUIT_COOLDOWN` | `60` | Seconds the circuit stays open. |
| `SCHOLARWRIGHT_STARTUP_DIAG` | unset | Set to `1` to write `startup_diagnostic.json` on start. |

### Rate limiting

Four brakes, in order: session cap → global ceiling → **per-host** per-minute
and per-second → per-host circuit breaker.

Per-host limits matter because each upstream differs. NCBI E-utilities allows
about 3 requests/second without an API key **and blocks IPs that exceed it**,
while OpenAlex allows around 10/second with a mailto. The per-second window is
what prevents a ban — a 60-second window alone would permit 180 calls in three
seconds. Limits live in `_HOST_LIMITS`.

Do not raise the NCBI limit to 10/sec until an NCBI API key is actually
transmitted with requests. It currently is not.

---

## Audit report workflow (v5.14.20)

The standard full-audit chain:

```
audit_language_and_style
audit_academic_integrity
audit_doi_and_citation_health
  └─→ generate_flag_table          (discipline="your_field")
        └─→ generate_final_audit_report
              ├─→ <slug>_SW_Auto_Corrections.docx      ← verify SW changes
              ├─→ <slug>_Author_Actions_Required.docx  ← act on these
              └─→ weighted readiness score + markdown report
```

`generate_final_audit_report` defaults: `output_docx=True`, `split_reports=True`.
The two DOCX files land in the same directory as the flag table output.

---

## Design principles

These are load-bearing. Reversing any of them changes what the product is.

- Claim strength may never increase — five-tier scale, no rewrite moves up a tier
- Locked spans are never rewritten: p-values, sample sizes, CIs, effect estimates, DOIs, citations, units
- Never upsample a figure to meet a DPI threshold — re-export from source
- Never cut text to fit a word limit — that is an authorial decision
- Flags are evidence for the author, never verdicts on them
- Corroboration measures indexing, not quality
- A blank "Change made" column means an author decision is required, not missing data
- A high score means no flag was raised, not that the science is sound

---

## Honest limits

- **No plagiarism or text-similarity detection.** That is iThenticate's job. ScholarWright does citation *integrity*.
- **It audits what is written, not the underlying data.** It cannot confirm that a reported p-value came from the test the Methods names.
- **Citation support is often abstract-level only.** Where full text is unavailable, the verdict says so.
- **The readiness score is not validated.** It reports how many outcomes have been recorded against how many are needed.
- **Novelty positioning measures positional overlap only.** It cannot judge whether a contribution matters.
- **Not built:** `generate_results_paper`, image manipulation detection, citation cartel analysis, quotation accuracy.
- **Known broken:** the Scopus no-key fallback. Use `search_with_adaptive_depth` or `pubmed_search`.

---

## Development

```
python smoke_test.py              # offline, ~12s, exercises majority of tools
python smoke_test.py --network    # includes API-calling tools
python backup_to_onedrive.py      # mirror the system folder to OneDrive
```

### Release sequence

1. **Bump `_SW_VERSION` first** and append to `_SW_VERSION_HISTORY`. Both live
   at the top of `scholarwright_mcp.py`; `USER_AGENT` derives from the version,
   and the version is stamped onto generated deliverables.
2. Bump `version` in `pyproject.toml` to match.
3. `python smoke_test.py --network`
4. Regenerate the skill catalogue: `python regen_skill_catalogue.py`
5. Repackage the skill: `python _package_skill.py`
6. `python backup_to_onedrive.py`
7. Commit and push to GitHub.

### Rules learned the hard way

- **The `__main__` guard must be the last statement in the file.** It once sat
  mid-file, so 63 tools below it were never registered while three different
  tool counts appeared from the same source.
- **File order is fixed:** all tools → startup diagnostic → `__main__` guard.
- **Verify by subprocess, never by import.** A direct import skips the guard and
  over-reports.
- **Any tool that persists keyed state must be added to
  `cleanup_test_artefacts()`** in the same change, or smoke runs will pollute
  real data.
- **No capability claim in any spec, deck or page until a test proves it.**

---

## Version history (recent)

| Version | Summary |
|---------|---------|
| v5.14.20 | `generate_final_audit_report` produces two structured DOCX reports by default: auto-corrections and author-action items grouped by severity. `output_docx` default changed to `True`. |
| v5.14.19 | Audit chain stabilisation; DOI verification layer extended. |
| v5.14.x | Language audit, academic integrity, and DOI audit layers hardened. |
| v5.5.0 | Learning loop introduced — discipline and journal profiles accumulate across runs. |