# PlainGrade

> English readability scores (Flesch Reading Ease, Flesch-Kincaid, Gunning Fog, SMOG, Coleman-Liau, ARI, consensus grade) plus text statistics and long sentences, for writers, editors and developers. Public JSON API plus a remote MCP server for AI agents. Submitted text is scored in memory and never stored or logged.

## For AI agents

- [MCP server](https://plaingrade-api.mike-tusa.workers.dev/mcp): remote MCP over Streamable HTTP (POST only, stateless, JSON responses). Protocol versions: 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05. Tool `score_readability` (text, optional lang, long_sentence_words, include_raw). Read-only. Client config (most MCP clients accept this; some use a different format, for example VS Code uses a `servers` key): `{"mcpServers":{"plaingrade-api":{"type":"http","url":"https://plaingrade-api.mike-tusa.workers.dev/mcp"}}}`
- [OpenAPI 3.1 spec](https://plaingrade-api.mike-tusa.workers.dev/openapi.json): machine-readable description of the JSON API

## JSON API

- `POST https://plaingrade-api.mike-tusa.workers.dev/v1/score` with JSON `{"text": "...", "lang": "en", "long_sentence_words": 25}`: text up to 20,480 bytes (UTF-8), English only, long_sentence_words 5–200. Returns scores, interpretation, stats, long_sentences and notes. Optional header `X-API-Key`.
- `POST https://plaingrade-api.mike-tusa.workers.dev/v1/keys` with `{}`: issues a free API key (shown once). `GET https://plaingrade-api.mike-tusa.workers.dev/v1/usage` with `X-API-Key`: today's usage. `GET https://plaingrade-api.mike-tusa.workers.dev/health`: status and version.
- Errors: `{"ok": false, "error": {"code", "message"}}` with HTTP 400, 401, 403, 404, 405, 413, 415, 422, 429, 500 or 503. Codes: invalid_json, missing_text, invalid_lang, invalid_long_sentence_words, invalid_api_key, unsupported_media_type, body_too_large, text_too_large, unsupported_language, rate_limited, ip_daily_quota, key_quota_exceeded, issuer_quota_exceeded, daily_cap_reached, internal_error, not_configured, cross_origin_forbidden, key_issue_limit, unavailable, missing_api_key.

## Limits, keys and pricing

- Anonymous: about 10/min and 50/day per IP (IPv6: per /64). Free API key: 100 requests/day and 30/min, commercial use allowed; at most 3 new keys per IP per day. Paid tiers: not available yet. The service has a global daily soft cap (HTTP 429 daily_cap_reached until 00:00 UTC).
- The MCP endpoint uses the same keys and counters (send the key as `Authorization: Bearer <key>` or `X-Api-Key`): each `tools/call` counts as one /v1/score request. Other MCP messages (initialize, tools/list, ping, server/discover) don't count against the API quota, but are capped at about 120/min per IP (HTTP 429 + Retry-After). Max 65,536 bytes per MCP request, batches of up to 10 messages with at most one tools/call.

## Optional

- [Privacy](https://plaingrade-api.mike-tusa.workers.dev/privacy)
- [API docs](https://plaingrade-api.mike-tusa.workers.dev/docs)
- Contact: digitalpromohub.support@gmail.com