Skip to content
Back to search

text-barrier-detector

Offline plain-language checker for English & Spanish docs. An MCP server + skill for Claude Code, Cursor and Claude Desktop that finds passive voice, long sentences and complex words, and scores readability (Flesch / Fernández-Huerta) with a CEFR-inspired band. No API key, no network.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mcontrerasmalpar-pixel--text-barrier-detector/badge.svg)](/listings/mcontrerasmalpar-pixel--text-barrier-detector)

HTML

<a href="/listings/mcontrerasmalpar-pixel--text-barrier-detector"><img src="/api/listings/mcontrerasmalpar-pixel--text-barrier-detector/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Core Library (`@makitaki/text-barrier-core`)

npm install @makitaki/text-barrier-core
import {
  analyze,
  findBarriers,
  AnalysisError,
  SUPPORTED_LANGUAGES,
  MAX_INPUT_CHARS,
} from '@makitaki/text-barrier-core';

const result = analyze(
  'The report was written by the team. She is turned on.',
  { lang: 'en' }
);
const issues = findBarriers(
  'The report was written by the team. She is turned on.',
  { lang: 'en' }
);

console.log(result.overallScore); // 77
console.log(result.passiveCount); // 1 ("She is turned on" is ignored)
console.log(issues);
// [
//   {
//     type: 'passive',
//     start: 11,
//     end: 22,
//     sentenceIndex: 0,
//     reason: 'Passive voice construction detected; consider rewriting in active voice.',
//     lang: 'en',
//     text: 'was written'
//   }
// ]

2. MCP Server (`@makitaki/text-barrier-mcp`)

Run directly via `npx`:

npx -y @makitaki/text-barrier-mcp

Claude Desktop (`claude_desktop_config.json`) & Cursor (`.cursor/mcp.json`)

{
  "mcpServers": {
    "text-barrier": {
      "command": "npx",
      "args": ["-y", "@makitaki/text-barrier-mcp"]
    }
  }
}

Claude Code

claude mcp add text-barrier -- npx -y @makitaki/text-barrier-mcp

MCP Tools

| Tool | Arguments | Returns | |------|-----------|---------| | `analyze_text` | `{ text: string, lang?: "en" \| "es", markdown?: boolean }` | Full `AnalysisResult` (scores, Readability Band A1–C2, sentence metrics, suggestions). | | `find_barriers` | `{ text: string, lang?: "en" \| "es", markdown?: boolean }` | `{ lang, count, issues: BarrierIssue[] }` (`passive`, `long_sentence`, `complex_word` with `start`/`end` offsets). | | `check_file` | `{ path: string, lang?: "en" \| "es" }` | Reads a local `.md` or `.txt` file on the user's disk (up to `1,000,000` chars / `4 MB`) and returns `{ path, lang, analysis, issues, markdown }`. `.md` files are analyzed as prose only (code, tables, badges and URLs are ignored). |

> **Security note on `check_file`:** Because `@makitaki/text-barrier-mcp` runs as a local `stdio` child process with your OS user permissions, `check_file` can read any `.md` or `.txt` file on your local disk that your user account can access. Only `.md` and `.txt` extensions are allowed, and file contents are never logged or sent over the network. See [`SECURITY.md`](./SECURITY.md).

Example prompt in your MCP client: > `"Check the clarity of README.md"`

Full MCP server documentation and JSON examples: [`packages/mcp/README.md`](./packages/mcp/README.md).

3. CLI (`scripts/analyze.mjs`)

npm run build:core
node scripts/analyze.mjs path/to/file.txt
node scripts/analyze.mjs --lang=es path/to/archivo.txt
node scripts/analyze.mjs --markdown README.md   # ignore code, tables, badges and URLs
echo "Se registró el usuario. Se me olvidó." | node scripts/analyze.mjs --lang=es -

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 396 lines
  1. # Text Barrier Detector
  2. Deterministic readability and plain-language barrier detector for **English (`en`)** and **Spanish (`es`)** product docs, support copy, PR descriptions, and MCP / CLI workflows.
  3. **Live web app:** [text-barrier-detector.vercel.app](https://text-barrier-detector.vercel.app)
  4. **Packages:** [`@makitaki/text-barrier-core`](./packages/core) · [`@makitaki/text-barrier-mcp`](./packages/mcp)
  5. **Author:** [Maria Contreras](https://github.com/mcontrerasmalpar-pixel)
  6. **License:** [MIT](./LICENSE)
  7. ---
  8. ## Packages in this Monorepo
  9. | Package | Path | Version | Description |
  10. |---------|------|---------|-------------|
  11. | [`@makitaki/text-barrier-core`](./packages/core) | `packages/core` | `0.1.1` | Pure TypeScript readability & barrier detector (`analyze`, `findBarriers`). Zero runtime dependencies, no DOM, no network calls. |
  12. | [`@makitaki/text-barrier-mcp`](./packages/mcp) | `packages/mcp` | `0.1.1` | Official Model Context Protocol (`stdio`) server exposing `analyze_text`, `find_barriers`, and `check_file` for Claude Desktop, Cursor, and Claude Code. |
  13. | Web UI | `src/` | `1.0.0` | React + Vite web application importing `@makitaki/text-barrier-core`. |
  14. ---
  15. ## Features
  16. - **Single TypeScript source of truth (`@makitaki/text-barrier-core`)** shared across the React web app, the MCP server (`@makitaki/text-barrier-mcp`), the CLI (`scripts/analyze.mjs`), and the GitHub Action.
  17. - **Zero runtime dependencies** in `@makitaki/text-barrier-core`.
  18. - **Deterministic issue locator (`findBarriers`):** returns `passive`, `long_sentence`, and `complex_word` issues with exact `start`/`end` character offsets, `sentenceIndex`, localized `reason`, and `lang`—so a host LLM or editor can rewrite unclear passages without a second LLM call.
  19. - **Bilingual heuristics (`en` | `es`)** behind a `LanguagePack` interface:
  20. - **English (`en`):** Flesch Reading Ease, Flesch–Kincaid Grade Level, syllable counter, passive-voice detector with irregular participle list and phrasal-verb / adjectival / raising-verb false-positive exclusions (*"is turned on"*, *"said to be"*).
  21. - **Spanish (`es`):** Fernández-Huerta reading ease (`206.84 - 1.02*P - 0.60*S`), diphthong/hiatus syllable counter, analytic (*ser* + participle) and *se*-passive/impersonal detection with reflexive/accidental clitic exclusions (*"Se me olvidó"*).
  22. - **Density-aware structure scoring:** rewards real paragraph layout, lists, and headings relative to word count so empty formatting cannot game a 100/100 score.
  23. - **Readability Band (A1–C2):** a **CEFR-inspired** heuristic composite (not a certified language exam or official CEFR certification) with target audience and actionable tips.
  24. - **Strict input validation** with localized (`en` / `es`) `AnalysisError` messages and machine-readable error codes.
  25. ---
  26. ## Installation & Usage
  27. ### 1. Core Library (`@makitaki/text-barrier-core`)
  28. ```bash
  29. npm install @makitaki/text-barrier-core
  30. ```
  31. ```ts
  32. import {
  33. analyze,
  34. findBarriers,
  35. AnalysisError,
  36. SUPPORTED_LANGUAGES,
  37. MAX_INPUT_CHARS,
  38. } from '@makitaki/text-barrier-core';
  39. const result = analyze(
  40. 'The report was written by the team. She is turned on.',
  41. { lang: 'en' }
  42. );
  43. const issues = findBarriers(
  44. 'The report was written by the team. She is turned on.',
  45. { lang: 'en' }
  46. );
  47. console.log(result.overallScore); // 77
  48. console.log(result.passiveCount); // 1 ("She is turned on" is ignored)
  49. console.log(issues);
  50. // [
  51. // {
  52. // type: 'passive',
  53. // start: 11,
  54. // end: 22,
  55. // sentenceIndex: 0,
  56. // reason: 'Passive voice construction detected; consider rewriting in active voice.',
  57. // lang: 'en',
  58. // text: 'was written'
  59. // }
  60. // ]
  61. ```
  62. ### 2. MCP Server (`@makitaki/text-barrier-mcp`)
  63. Run directly via `npx`:
  64. ```bash
  65. npx -y @makitaki/text-barrier-mcp
  66. ```
  67. #### Claude Desktop (`claude_desktop_config.json`) & Cursor (`.cursor/mcp.json`)
  68. ```json
  69. {
  70. "mcpServers": {
  71. "text-barrier": {
  72. "command": "npx",
  73. "args": ["-y", "@makitaki/text-barrier-mcp"]
  74. }
  75. }
  76. }
  77. ```
  78. #### Claude Code
  79. ```bash
  80. claude mcp add text-barrier -- npx -y @makitaki/text-barrier-mcp
  81. ```
  82. #### MCP Tools
  83. | Tool | Arguments | Returns |
  84. |------|-----------|---------|
  85. | `analyze_text` | `{ text: string, lang?: "en" \| "es", markdown?: boolean }` | Full `AnalysisResult` (scores, Readability Band A1–C2, sentence metrics, suggestions). |
  86. | `find_barriers` | `{ text: string, lang?: "en" \| "es", markdown?: boolean }` | `{ lang, count, issues: BarrierIssue[] }` (`passive`, `long_sentence`, `complex_word` with `start`/`end` offsets). |
  87. | `check_file` | `{ path: string, lang?: "en" \| "es" }` | Reads a local `.md` or `.txt` file on the user's disk (up to `1,000,000` chars / `4 MB`) and returns `{ path, lang, analysis, issues, markdown }`. `.md` files are analyzed as prose only (code, tables, badges and URLs are ignored). |
  88. > **Security note on `check_file`:** Because `@makitaki/text-barrier-mcp` runs as a local `stdio` child process with your OS user permissions, `check_file` can read any `.md` or `.txt` file on your local disk that your user account can access. Only `.md` and `.txt` extensions are allowed, and file contents are never logged or sent over the network. See [`SECURITY.md`](./SECURITY.md).
  89. Example prompt in your MCP client:
  90. > `"Check the clarity of README.md"`
  91. Full MCP server documentation and JSON examples: [`packages/mcp/README.md`](./packages/mcp/README.md).
  92. ### 3. CLI (`scripts/analyze.mjs`)
  93. ```bash
  94. npm run build:core
  95. node scripts/analyze.mjs path/to/file.txt
  96. node scripts/analyze.mjs --lang=es path/to/archivo.txt
  97. node scripts/analyze.mjs --markdown README.md # ignore code, tables, badges and URLs
  98. echo "Se registró el usuario. Se me olvidó." | node scripts/analyze.mjs --lang=es -
  99. ```
  100. ---
  101. ## Core API Reference (`@makitaki/text-barrier-core`)
  102. ### `analyze(text: string, options?: { lang?: 'en' | 'es' }): AnalysisResult`
  103. ### `findBarriers(text: string, options?: { lang?: 'en' | 'es' }): BarrierIssue[]`
  104. #### Input Constraints
  105. | Parameter | Type | Default | Constraints |
  106. |-----------|------|---------|-------------|
  107. | `text` | `string` | *(required)* | Non-empty after trimming; length `<= 1,000,000` UTF-16 code units (`MAX_INPUT_CHARS`). Normalized to Unicode `NFC`. |
  108. | `options.lang` | `'en' \| 'es'` | `'en'` | Must be one of `SUPPORTED_LANGUAGES` (`['en', 'es']`). |
  109. #### Output Types (`AnalysisResult` & `BarrierIssue`)
  110. ```ts
  111. export type AnalysisLanguage = 'en' | 'es';
  112. export type FormulaName = 'Flesch' | 'Fernández-Huerta';
  113. export type TextLevel = 'A1' | 'A2' | 'B1' | 'B2' | 'C1' | 'C2';
  114. export type BarrierType = 'passive' | 'long_sentence' | 'complex_word';
  115. export interface BarrierIssue {
  116. type: BarrierType;
  117. start: number; // inclusive offset in normalized text
  118. end: number; // exclusive offset in normalized text
  119. sentenceIndex: number; // 0-based sentence index
  120. reason: string; // deterministic explanation (EN or ES)
  121. lang: AnalysisLanguage;
  122. text: string; // exact substring text.slice(start, end)
  123. }
  124. export interface SentenceAnalysis {
  125. text: string;
  126. wordCount: number;
  127. isLong: boolean; // true when wordCount > 20
  128. hasPassiveVoice: boolean; // language-specific passive heuristic
  129. complexWords: string[]; // >= 4 syllables, excluding common technical allow-list
  130. index: number;
  131. }
  132. export interface LevelResult {
  133. level: TextLevel; // 'A1' | 'A2' | 'B1' | 'B2' | 'C1' | 'C2'
  134. label: string; // 'Very Easy' | 'Easy' | 'Standard' | 'Moderately Complex' | 'Complex' | 'Very Complex'
  135. description: string;
  136. audience: string;
  137. score: number; // 0–100 weighted composite
  138. disclaimer: string; // Always states CEFR-inspired heuristic, not a certification
  139. dimensions: LevelDimensions;
  140. tips: string[]; // Up to 3 actionable suggestions
  141. }
  142. export interface AnalysisResult {
  143. sentences: SentenceAnalysis[];
  144. fleschScore: number; // 0–100 (Flesch for 'en', Fernández-Huerta for 'es')
  145. fleschLabel: string; // 'Very easy' | 'Easy' | 'Moderate' | 'Difficult' | 'Very difficult'
  146. gradeLevel: number; // >= 0
  147. avgSentenceLength: number; // words per sentence
  148. passiveCount: number; // sentences flagged for passive voice
  149. complexWordCount: number; // total complex words across sentences
  150. structureScore: number; // 0–100 density-aware structure score
  151. overallScore: number; // 0–100 weighted composite
  152. totalWords: number;
  153. totalSentences: number;
  154. totalSyllables: number;
  155. suggestions: string[]; // Top 3 overall suggestions
  156. level: LevelResult; // Readability Band (A1–C2), CEFR-inspired
  157. language: AnalysisLanguage; // 'en' | 'es'
  158. formulaName: FormulaName; // 'Flesch' | 'Fernández-Huerta'
  159. }
  160. ```
  161. ---
  162. ## JSON Examples
  163. ### English Example (`lang: 'en'`)
  164. ```ts
  165. analyze('The report was written by the team. She is turned on.', { lang: 'en' });
  166. ```
  167. ```json
  168. {
  169. "sentences": [
  170. {
  171. "text": "The report was written by the team.",
  172. "wordCount": 7,
  173. "isLong": false,
  174. "hasPassiveVoice": true,
  175. "complexWords": [],
  176. "index": 0
  177. },
  178. {
  179. "text": "She is turned on.",
  180. "wordCount": 4,
  181. "isLong": false,
  182. "hasPassiveVoice": false,
  183. "complexWords": [],
  184. "index": 1
  185. }
  186. ],
  187. "fleschScore": 93.6,
  188. "fleschLabel": "Very easy",
  189. "gradeLevel": 1.6,
  190. "avgSentenceLength": 5.5,
  191. "passiveCount": 1,
  192. "complexWordCount": 0,
  193. "structureScore": 15,
  194. "overallScore": 77,
  195. "totalWords": 11,
  196. "totalSentences": 2,
  197. "totalSyllables": 13,
  198. "suggestions": [
  199. "Convert passive voice to active voice for clarity.",
  200. "Add paragraph breaks, headings, or lists to improve structure."
  201. ],
  202. "language": "en",
  203. "formulaName": "Flesch",
  204. "level": {
  205. "level": "A2",
  206. "label": "Easy",
  207. "description": "Simple text. Common everyday vocabulary, mostly short sentences.",
  208. "audience": "General public, non-native speakers, readers with limited education.",
  209. "score": 70,
  210. "disclaimer": "CEFR-inspired readability heuristic, not a CEFR assessment or certification.",
  211. "dimensions": {
  212. "readabilityScore": 93.6,
  213. "gradeLevelScore": 100,
  214. "sentenceLengthScore": 100,
  215. "passiveVoiceScore": 0,
  216. "complexityScore": 100,
  217. "structureScore": 15
  218. },
  219. "tips": [
  220. "Rewrite passive-voice sentences in active voice (e.g. \"The report was written by Ana\" → \"Ana wrote the report\").",
  221. "Add headings, bullet lists, or paragraph breaks to improve visual structure."
  222. ]
  223. }
  224. }
  225. ```
  226. ### Spanish Example (`lang: 'es'`)
  227. ```ts
  228. analyze('Se registró el usuario. Se me olvidó la contraseña.', { lang: 'es' });
  229. ```
  230. ```json
  231. {
  232. "sentences": [
  233. {
  234. "text": "Se registró el usuario.",
  235. "wordCount": 4,
  236. "isLong": false,
  237. "hasPassiveVoice": true,
  238. "complexWords": [],
  239. "index": 0
  240. },
  241. {
  242. "text": "Se me olvidó la contraseña.",
  243. "wordCount": 5,
  244. "isLong": false,
  245. "hasPassiveVoice": false,
  246. "complexWords": [
  247. "contraseña"
  248. ],
  249. "index": 1
  250. }
  251. ],
  252. "fleschScore": 100,
  253. "fleschLabel": "Very easy",
  254. "gradeLevel": 9.8,
  255. "avgSentenceLength": 4.5,
  256. "passiveCount": 1,
  257. "complexWordCount": 1,
  258. "structureScore": 15,
  259. "overallScore": 76,
  260. "totalWords": 9,
  261. "totalSentences": 2,
  262. "totalSyllables": 18,
  263. "suggestions": [
  264. "Convert passive voice to active voice for clarity.",
  265. "Add paragraph breaks, headings, or lists to improve structure."
  266. ],
  267. "language": "es",
  268. "formulaName": "Fernández-Huerta",
  269. "level": {
  270. "level": "B1",
  271. "label": "Standard",
  272. "description": "Accessible text. Mix of simple and moderate complexity. Some technical terms.",
  273. "audience": "Most adults, general audience, plain-language standard.",
  274. "score": 64,
  275. "disclaimer": "CEFR-inspired readability heuristic, not a CEFR assessment or certification.",
  276. "dimensions": {
  277. "readabilityScore": 100,
  278. "gradeLevelScore": 51.67,
  279. "sentenceLengthScore": 100,
  280. "passiveVoiceScore": 0,
  281. "complexityScore": 44.44,
  282. "structureScore": 15
  283. },
  284. "tips": [
  285. "Rewrite passive-voice sentences in active voice (e.g. \"The report was written by Ana\" → \"Ana wrote the report\").",
  286. "Replace polysyllabic words with simpler synonyms (e.g. \"utilise\" → \"use\", \"demonstrate\" → \"show\").",
  287. "Add headings, bullet lists, or paragraph breaks to improve visual structure."
  288. ]
  289. }
  290. }
  291. ```
  292. ---
  293. ## Expected Errors (`AnalysisError`)
  294. Invalid inputs throw an `AnalysisError` (subclass of `Error`) with:
  295. - `code`: `'INVALID_TYPE' | 'EMPTY_TEXT' | 'TEXT_TOO_LONG' | 'UNSUPPORTED_LANGUAGE'`
  296. - `message`: localized human-readable message (`en` or `es`)
  297. - `details`: structured metadata object
  298. | Code | Trigger | Example Message (`en`) | Example Message (`es`) | `details` |
  299. |------|---------|------------------------|------------------------|-----------|
  300. | `INVALID_TYPE` | `typeof text !== 'string'` (e.g. `null`, `undefined`, number, array, object) | `Input text must be a string, but received number.` | `El texto de entrada debe ser una cadena (string), pero se recibió number.` | `{ type: 'number' }` |
  301. | `EMPTY_TEXT` | `text.trim().length === 0` (`""`, `" \n\t "`) | `Input text is empty. Provide at least one word to analyze.` | `El texto de entrada está vacío. Proporcione al menos una palabra para analizar.` | `{}` |
  302. | `TEXT_TOO_LONG` | `text.length > 1_000_000` (`MAX_INPUT_CHARS`) | `Input text is too long: 1000001 characters (maximum 1000000). Split it into smaller parts.` | `El texto de entrada es demasiado largo: 1000001 caracteres (máximo 1000000). Divídalo en partes más pequeñas.` | `{ length: 1000001, max: 1000000 }` |
  303. | `UNSUPPORTED_LANGUAGE` | `lang` is not `'en'` or `'es'` | `Unsupported language "fr". Supported languages: en, es.` | `Idioma no admitido "fr". Idiomas admitidos: en, es.` | `{ lang: 'fr', supported: 'en, es' }` |
  304. ---
  305. ## Scoring & Readability Band (Honest Notes)
  306. **Overall score & Readability Band composite weights:**
  307. ```text
  308. Ease score (Flesch or Fernández-Huerta) × 0.35
  309. Sentence length × 0.20
  310. Passive voice × 0.15
  311. Complex-word density × 0.15
  312. Structure (density-aware) × 0.15
  313. ```
  314. - **Readability Band (A1–C2):** The **Readability Band (A1–C2)** is **CEFR-inspired**: it borrows the A1–C2 codes (`A1 Very Easy`, `A2 Easy`, `B1 Standard`, `B2 Moderately Complex`, `C1 Complex`, `C2 Very Complex`) for familiarity, but it is a heuristic composite of the metrics above, **not a CEFR assessment or certification**.
  315. - **Structure density:** Headings require body text beneath them (`>= 15` body words per heading), lists require `>= 2` items with real words, over-fragmented text (`elements / totalWords > 0.5`) is capped at `40`, and short snippets (`< 20` words) are capped at `30`.
  316. Full contract: [`specs/product.md`](./specs/product.md) and [`specs/constitution.md`](./specs/constitution.md).
  317. ---
  318. ## Development Scripts
  319. ```bash
  320. npm install
  321. npm run dev # Start Vite dev server on http://localhost:8080
  322. npm test # Run Vitest unit + MCP stdio integration suite
  323. npx playwright test # Run Playwright e2e test
  324. npm run build:core # Build @makitaki/text-barrier-core (packages/core/dist/)
  325. npm run build:mcp # Build @makitaki/text-barrier-core and @makitaki/text-barrier-mcp
  326. npm run build # Build web application
  327. npm run typecheck # TypeScript check
  328. npm run lint # ESLint
  329. ```
  330. ---
  331. ## License
  332. [MIT](./LICENSE) © 2026 Maria Contreras

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.