# english-tutor-mcp

Practice English by just talking to your AI assistant — and get a daily report of your **recurring** grammar patterns, without ever being corrected mid-conversation.

Works with any MCP client that runs local (stdio) servers: **Claude Code, Claude Desktop, Codex CLI, Cursor**, and more.

- **While you chat** — every English message you write is silently logged, verbatim, into a local SQLite database. No corrections, no interruptions: fluency practice stays fluent.
- **When you ask** — `/report` analyzes everything since your last report *as a whole* and saves a markdown report. You get patterns ("drops articles before abstract nouns — 6 times"), not one-off nitpicks.
- **Local-only** — no API key, no account, no hosted server. Everything lives in `~/.english-tutor/` on your machine.

## Quick start (Claude Code)

```bash
claude mcp add english-tutor -s user -- npx -y english-tutor-mcp
```

Then just talk to your assistant in English — anywhere, about anything. Every English message is collected quietly. Whenever you want feedback (tomorrow, or after a few days):

```
/mcp__english-tutor__report
```

It analyzes everything since your last report and saves it to `~/.english-tutor/reports/`. Forgot for three days? It catches up on all three at once.

## Commands

| Prompt | What it does |
|---|---|
| `/report` | Analyzes all conversations not yet analyzed — however many days have piled up — and saves a markdown report. Run it in a fresh session |
| `/report [days]` | Retrospective mode: re-analyzes the last N days as one window (e.g. `7` for a weekly review), surfacing patterns too rare to show up in a single day |
| `/weak-points [days]` | Shows persistent weak points aggregated from saved reports (default 30 days). Read-only |
| `/language [lang]` | Sets the language your feedback is written in, persisted across sessions. By default it is inferred — reports arrive in your native language, quotes stay in English |

## Other clients

<details>
<summary><b>Claude Desktop</b> — <code>claude_desktop_config.json</code></summary>

```json
{
  "mcpServers": {
    "english-tutor": {
      "command": "npx",
      "args": ["-y", "english-tutor-mcp"]
    }
  }
}
```
</details>

<details>
<summary><b>Cursor</b> — <code>.cursor/mcp.json</code></summary>

```json
{
  "mcpServers": {
    "english-tutor": {
      "command": "npx",
      "args": ["-y", "english-tutor-mcp"]
    }
  }
}
```
</details>

<details>
<summary><b>Codex CLI</b> — <code>~/.codex/config.toml</code></summary>

```toml
[mcp_servers.english-tutor]
command = "npx"
args = ["-y", "english-tutor-mcp"]
```
</details>

> **ChatGPT web/desktop app**: not supported yet — ChatGPT connectors only reach *remote* MCP servers over HTTPS, while this server runs locally over stdio to keep your data on your machine. If you use the ChatGPT ecosystem, Codex CLI works today. A remote-capable HTTP mode is under consideration for v2.

## How it works

1. **Capture, don't judge.** During conversation the model only calls `log_utterance`, storing your message exactly as you typed it — the errors *are* the data. Real-time correction would both break fluency practice and destroy the samples.
2. **Patterns, not sentences.** Analysis always runs over a whole day's corpus at once. One sentence shows a missing article; forty sentences show *where* you drop articles. Findings below 3 occurrences are discarded.
3. **The host model does the analysis.** The server is deliberately just SQLite CRUD — that's why no API key is needed and installation is one line. The AI subscription you already have does the thinking.
4. **Nothing is ever missed.** Sessions queue up unanalyzed until your next `/report`, which catches them all up in one pass — skipping days costs you nothing.

## Data

| Path | Contents |
|---|---|
| `~/.english-tutor/db.sqlite` | sessions, verbatim utterances, findings, report index |
| `~/.english-tutor/reports/YYYY-MM-DD.md` | daily markdown reports |

Relocate everything with `ENGLISH_TUTOR_DB=/path/to/db.sqlite`. Delete the directory to erase all data — nothing leaves your machine.

## License

MIT License