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:

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

Related MCP server: article-mcp

Install

pip install -r requirements.txt

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

{
  "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

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)