Unswell MCP server

Unswell

A linter for lean English, built to reduce AI-sounding prose.

Unswell's main motivation is to keep formulaic AI-style wording from leaking into source code and documentation. AI-assisted work often leaves behind conversational preambles, generic claims of importance, inflated modifiers and repeated setup. Unswell finds these patterns in prose and explains what to revise before the text reaches a commit or a published document.

The checks apply to text regardless of its author. They enforce a chosen editorial policy through concrete findings and explainable scores. Unswell runs locally as a Go library and CLI, without sending source text to an AI service.

Unswell is not an authorship detector. A clean scan of a generated text is a correct result, and a finding on a human-written text is a finding about the wording. No score is a probability that a tool wrote the text; see ADR 0037 for the goal and its non-goals.

Development alpha. The published release is v0.1.0-alpha.3. Stage 2 features include custom rules, baselines, and checks of changed code. Go tools can train, calibrate, and load models.

Rules and defaults remain experimental. No editorial model has met the criteria for use in the product. See the acceptance audit for features, release evidence, and work still open. Revision probability is unavailable until a labeled corpus and compatible calibration model meet the later acceptance criteria.

Quick start

Build with the minimum Go version declared in go.mod:

go build -o bin/unswell ./cmd/unswell
bin/unswell config init --profile technical
bin/unswell check README.md docs/

Install the published alpha without Go through the Homebrew tap:

brew install stokaro/unswell/unswell

A separate GitHub Action runs pinned release archives and writes JSON/SARIF reports. See installation and release verification for availability and platform checks.

For example, this introduction:

It is important to note that the client retries a request only after a connection failure.

produces filler.announced-importance. A direct version preserves the condition:

The client retries a request only after a connection failure.

Use the strict profile to make the introductory phrase a hard policy violation:

printf '%s\n' 'It is important to note that the client may retry.' |
  bin/unswell check --stdin --filename draft.md --profile strict

Reports and gate

One analysis can write all five reports:

bin/unswell check README.md docs/ \
  --report text:- \
  --report json:artifacts/unswell.json \
  --report sarif:artifacts/unswell.sarif \
  --report html:artifacts/unswell.html \
  --report markdown:artifacts/unswell.md

Add --include-source to retain snippets and highlighted paragraphs in saved reports. Source text is omitted by default. Reports can contain internal prose; choose artifact access accordingly.

bin/unswell report artifacts/unswell.json --format html --output artifacts/review.html
bin/unswell explain README.md --at 3:1
bin/unswell rules list
bin/unswell rules show repetition.near-sentence
bin/unswell rules test
bin/unswell config validate
bin/unswell config explain --file README.md
bin/unswell doctor

Exit codes: 0 for a complete pass, 1 for a complete policy failure, 2 for operational errors or incomplete analysis, and 130 for cancellation. An empty scan fails unless explicitly allowed. --no-gate permits advisory checks while preserving operational errors. Display filtering never changes the gate. A rule that exhausts its candidate budget abstains on that document with the reason budget_exhausted; the report lists the abstention and the other rules' findings stay.

Shortened. The full README is on GitHub.