humanizer-mcp 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,7 @@
1
+ """humanizer_mcp — MCP server for analyzing and humanizing AI-generated text."""
2
+
3
+ __version__ = "0.1.0"
4
+
5
+ from humanizer_mcp.server import main
6
+
7
+ __all__ = ["__version__", "main"]
@@ -0,0 +1,6 @@
1
+ """Enable `python -m humanizer_mcp`."""
2
+
3
+ from humanizer_mcp.server import main
4
+
5
+ if __name__ == "__main__":
6
+ main()
@@ -0,0 +1,989 @@
1
+ """
2
+ humanizer_mcp.server — FastMCP server implementation.
3
+
4
+ Provides tools for analyzing AI tells in text, humanizing AI-generated content,
5
+ and checking text against detection patterns. Works with Claude.ai, Claude Code,
6
+ and any MCP-compatible client.
7
+
8
+ Usage (stdio, local):
9
+ humanizer-mcp
10
+
11
+ Usage (HTTP, remote):
12
+ humanizer-mcp --http --port 8000
13
+ """
14
+
15
+ from __future__ import annotations
16
+
17
+ import argparse
18
+ import json
19
+ import math
20
+ import re
21
+ from enum import Enum
22
+ from typing import Any
23
+
24
+ from mcp.server.fastmcp import FastMCP
25
+ from pydantic import BaseModel, ConfigDict, Field
26
+
27
+ # ─────────────────────────────────────────────────────────────────────
28
+ # Constants
29
+ # ─────────────────────────────────────────────────────────────────────
30
+
31
+ SERVER_NAME = "humanizer_mcp"
32
+
33
+ # Words statistically overrepresented in AI-generated text
34
+ AI_VOCABULARY: dict[str, list[str]] = {
35
+ "delve": ["dig into", "explore", "look at", "examine"],
36
+ "crucial": ["important", "key", "big", "necessary"],
37
+ "landscape": ["field", "space", "world", "scene"],
38
+ "leverage": ["use", "apply", "tap into", "lean on"],
39
+ "multifaceted": ["complex", "layered", "varied"],
40
+ "comprehensive": ["thorough", "full", "complete", "detailed"],
41
+ "facilitate": ["help", "enable", "make possible", "let"],
42
+ "streamline": ["simplify", "speed up", "cut down"],
43
+ "moreover": [""], # delete entirely
44
+ "furthermore": [""],
45
+ "additionally": ["also", "plus", "and"],
46
+ "harness": ["use", "tap", "put to work"],
47
+ "underscore": ["highlight", "show", "prove", "point to"],
48
+ "navigate": ["handle", "work through", "deal with"],
49
+ "illuminate": ["show", "reveal", "clarify", "explain"],
50
+ "embark": ["start", "begin", "kick off"],
51
+ "foster": ["build", "grow", "support", "encourage"],
52
+ "endeavor": ["effort", "attempt", "try", "project"],
53
+ "tapestry": ["mix", "blend", "web", "collection"],
54
+ "showcase": ["show", "display", "demonstrate"],
55
+ "pivotal": ["key", "turning-point", "defining"],
56
+ "bolster": ["strengthen", "support", "boost", "back up"],
57
+ "nuanced": ["subtle", "detailed", "fine-grained"],
58
+ "robust": ["strong", "solid", "reliable"],
59
+ "paradigm": ["model", "framework", "approach", "way"],
60
+ "synergy": ["teamwork", "combined effect", "collaboration"],
61
+ "holistic": ["complete", "full-picture", "overall"],
62
+ "myriad": ["many", "a range of", "lots of", "plenty of"],
63
+ "plethora": ["many", "a lot of", "plenty of"],
64
+ "juxtaposition": ["contrast", "comparison", "side-by-side"],
65
+ "arguably": [""], # delete — take a position instead
66
+ }
67
+
68
+ # Phrases that are AI structural tells
69
+ AI_PHRASES: list[str] = [
70
+ "it's important to note",
71
+ "it's worth noting",
72
+ "it is important to note",
73
+ "it is worth noting",
74
+ "in conclusion",
75
+ "in today's rapidly evolving",
76
+ "in today's fast-paced",
77
+ "in the ever-evolving",
78
+ "in the realm of",
79
+ "at its core",
80
+ "plays a crucial role",
81
+ "plays a pivotal role",
82
+ "it's not just",
83
+ "it is not just",
84
+ "stands as a testament",
85
+ "serves as a reminder",
86
+ "remains to be seen",
87
+ "only time will tell",
88
+ "the question remains",
89
+ "as we move forward",
90
+ "looking ahead",
91
+ "going forward",
92
+ "the bottom line is",
93
+ "when it comes to",
94
+ "at the end of the day",
95
+ "whether you're a",
96
+ "from seasoned professionals to",
97
+ "both seasoned and",
98
+ "let's dive in",
99
+ "without further ado",
100
+ "buckle up",
101
+ ]
102
+
103
+ # ─────────────────────────────────────────────────────────────────────
104
+ # Server Setup
105
+ # ─────────────────────────────────────────────────────────────────────
106
+
107
+ mcp = FastMCP(SERVER_NAME)
108
+
109
+ # ─────────────────────────────────────────────────────────────────────
110
+ # Shared Utilities
111
+ # ─────────────────────────────────────────────────────────────────────
112
+
113
+
114
+ def split_sentences(text: str) -> list[str]:
115
+ """Split text into sentences, handling common abbreviations."""
116
+ text = re.sub(r"(Mr|Mrs|Ms|Dr|Prof|Sr|Jr|St|vs|etc|e\.g|i\.e)\.", r"\1<PERIOD>", text)
117
+ sentences = re.split(r"(?<=[.!?])\s+", text)
118
+ return [s.replace("<PERIOD>", ".").strip() for s in sentences if s.strip()]
119
+
120
+
121
+ def count_words(text: str) -> int:
122
+ """Count words in text."""
123
+ return len(text.split())
124
+
125
+
126
+ def sentence_lengths(text: str) -> list[int]:
127
+ """Get word count for each sentence."""
128
+ return [count_words(s) for s in split_sentences(text)]
129
+
130
+
131
+ def calculate_burstiness(lengths: list[int]) -> float:
132
+ """Calculate burstiness as coefficient of variation of sentence lengths.
133
+
134
+ Higher = more human-like variation. AI typically < 0.3, humans > 0.5.
135
+ """
136
+ if len(lengths) < 2:
137
+ return 0.0
138
+ mean = sum(lengths) / len(lengths)
139
+ if mean == 0:
140
+ return 0.0
141
+ variance = sum((x - mean) ** 2 for x in lengths) / len(lengths)
142
+ std_dev = math.sqrt(variance)
143
+ return round(std_dev / mean, 3)
144
+
145
+
146
+ def find_ai_vocabulary(text: str) -> list[dict[str, Any]]:
147
+ """Find AI-associated words in text with positions and suggestions."""
148
+ findings: list[dict[str, Any]] = []
149
+ text_lower = text.lower()
150
+ for word, replacements in AI_VOCABULARY.items():
151
+ pattern = r"\b" + re.escape(word) + r"\b"
152
+ for match in re.finditer(pattern, text_lower):
153
+ findings.append(
154
+ {
155
+ "word": word,
156
+ "position": match.start(),
157
+ "context": text[max(0, match.start() - 30) : match.end() + 30],
158
+ "replacements": [r for r in replacements if r],
159
+ }
160
+ )
161
+ return findings
162
+
163
+
164
+ def find_ai_phrases(text: str) -> list[dict[str, Any]]:
165
+ """Find AI-associated phrases in text."""
166
+ findings: list[dict[str, Any]] = []
167
+ text_lower = text.lower()
168
+ for phrase in AI_PHRASES:
169
+ idx = text_lower.find(phrase)
170
+ while idx != -1:
171
+ findings.append(
172
+ {
173
+ "phrase": phrase,
174
+ "position": idx,
175
+ "context": text[max(0, idx - 20) : idx + len(phrase) + 20],
176
+ }
177
+ )
178
+ idx = text_lower.find(phrase, idx + 1)
179
+ return findings
180
+
181
+
182
+ def count_em_dashes(text: str) -> int:
183
+ """Count em dashes (— and --)."""
184
+ return text.count("—") + text.count(" -- ") + text.count(" - ")
185
+
186
+
187
+ def check_contraction_usage(text: str) -> dict[str, Any]:
188
+ """Check if text uses contractions (human) or expanded forms (AI)."""
189
+ contractions = [
190
+ "don't",
191
+ "doesn't",
192
+ "won't",
193
+ "can't",
194
+ "isn't",
195
+ "aren't",
196
+ "wasn't",
197
+ "weren't",
198
+ "hasn't",
199
+ "haven't",
200
+ "hadn't",
201
+ "wouldn't",
202
+ "couldn't",
203
+ "shouldn't",
204
+ "it's",
205
+ "that's",
206
+ "there's",
207
+ "here's",
208
+ "what's",
209
+ "who's",
210
+ "let's",
211
+ "we're",
212
+ "they're",
213
+ "you're",
214
+ "I'm",
215
+ "he's",
216
+ "she's",
217
+ "we've",
218
+ "they've",
219
+ "you've",
220
+ "I've",
221
+ "we'd",
222
+ "they'd",
223
+ "you'd",
224
+ "I'd",
225
+ "he'd",
226
+ "she'd",
227
+ "we'll",
228
+ "they'll",
229
+ "you'll",
230
+ "I'll",
231
+ "he'll",
232
+ "she'll",
233
+ ]
234
+
235
+ expanded = [
236
+ "do not",
237
+ "does not",
238
+ "will not",
239
+ "cannot",
240
+ "is not",
241
+ "are not",
242
+ "was not",
243
+ "were not",
244
+ "has not",
245
+ "have not",
246
+ "had not",
247
+ "would not",
248
+ "could not",
249
+ "should not",
250
+ "it is",
251
+ "that is",
252
+ "there is",
253
+ "here is",
254
+ "what is",
255
+ "who is",
256
+ "let us",
257
+ "we are",
258
+ "they are",
259
+ "you are",
260
+ "I am",
261
+ "he is",
262
+ "she is",
263
+ "we have",
264
+ "they have",
265
+ "you have",
266
+ "I have",
267
+ "we would",
268
+ "they would",
269
+ "you would",
270
+ "I would",
271
+ "he would",
272
+ "she would",
273
+ "we will",
274
+ "they will",
275
+ "you will",
276
+ "I will",
277
+ "he will",
278
+ "she will",
279
+ ]
280
+
281
+ text_lower = text.lower()
282
+ contraction_count = sum(1 for c in contractions if c in text_lower)
283
+ expanded_count = sum(1 for e in expanded if f" {e} " in f" {text_lower} ")
284
+
285
+ return {
286
+ "contractions_found": contraction_count,
287
+ "expanded_forms_found": expanded_count,
288
+ "ratio": round(contraction_count / max(expanded_count, 1), 2),
289
+ "assessment": "human-like"
290
+ if contraction_count > expanded_count
291
+ else "AI-like (too formal)",
292
+ }
293
+
294
+
295
+ def check_paragraph_uniformity(text: str) -> dict[str, Any]:
296
+ """Analyze paragraph length variation."""
297
+ paragraphs = [p.strip() for p in text.split("\n\n") if p.strip()]
298
+ if len(paragraphs) < 2:
299
+ return {"paragraph_count": len(paragraphs), "uniformity": "insufficient data"}
300
+
301
+ lengths = [count_words(p) for p in paragraphs]
302
+ mean = sum(lengths) / len(lengths)
303
+ variance = sum((x - mean) ** 2 for x in lengths) / len(lengths)
304
+ cv = math.sqrt(variance) / mean if mean > 0 else 0
305
+
306
+ return {
307
+ "paragraph_count": len(paragraphs),
308
+ "lengths": lengths,
309
+ "mean_length": round(mean, 1),
310
+ "coefficient_of_variation": round(cv, 3),
311
+ "assessment": "good variation" if cv > 0.4 else "too uniform (AI-like)",
312
+ }
313
+
314
+
315
+ def check_rhetorical_questions(text: str) -> int:
316
+ """Count rhetorical questions (sentences ending with ?)."""
317
+ sentences = split_sentences(text)
318
+ return sum(1 for s in sentences if s.strip().endswith("?"))
319
+
320
+
321
+ def check_first_person(text: str) -> dict[str, Any]:
322
+ """Check for first-person usage which signals human authorship."""
323
+ first_person = [
324
+ "I ",
325
+ "I'm",
326
+ "I've",
327
+ "I'd",
328
+ "my ",
329
+ "mine ",
330
+ "me ",
331
+ "we ",
332
+ "we're",
333
+ "we've",
334
+ "we'd",
335
+ "our ",
336
+ "ours ",
337
+ "us ",
338
+ ]
339
+ text_check = f" {text} "
340
+ found = [fp.strip() for fp in first_person if fp in text_check]
341
+ count = sum(text_check.lower().count(fp.lower()) for fp in first_person)
342
+ return {
343
+ "first_person_markers": found,
344
+ "total_occurrences": count,
345
+ "assessment": "good - human voice present"
346
+ if count >= 3
347
+ else "weak - add personal perspective",
348
+ }
349
+
350
+
351
+ def compute_risk_score(analysis: dict[str, Any]) -> dict[str, Any]:
352
+ """Compute an overall AI detection risk score from analysis results."""
353
+ score = 0 # 0 = no risk, 100 = definitely flagged
354
+ reasons: list[str] = []
355
+
356
+ vocab_count = analysis.get("ai_vocabulary_count", 0)
357
+ if vocab_count >= 5:
358
+ score += 25
359
+ reasons.append(f"{vocab_count} AI-associated words found")
360
+ elif vocab_count >= 2:
361
+ score += 10
362
+ reasons.append(f"{vocab_count} AI-associated words found")
363
+
364
+ phrase_count = analysis.get("ai_phrase_count", 0)
365
+ if phrase_count >= 3:
366
+ score += 20
367
+ reasons.append(f"{phrase_count} AI-associated phrases found")
368
+ elif phrase_count >= 1:
369
+ score += 10
370
+ reasons.append(f"{phrase_count} AI-associated phrases found")
371
+
372
+ burstiness = analysis.get("burstiness", 0)
373
+ if burstiness < 0.25:
374
+ score += 20
375
+ reasons.append(f"Low burstiness ({burstiness}) — sentences too uniform")
376
+ elif burstiness < 0.35:
377
+ score += 10
378
+ reasons.append(f"Moderate burstiness ({burstiness}) — could use more variation")
379
+
380
+ contraction_data = analysis.get("contractions", {})
381
+ if contraction_data.get("assessment") == "AI-like (too formal)":
382
+ score += 10
383
+ reasons.append("Too few contractions — reads formal/AI-like")
384
+
385
+ para_data = analysis.get("paragraph_uniformity", {})
386
+ if para_data.get("assessment") == "too uniform (AI-like)":
387
+ score += 10
388
+ reasons.append("Paragraph lengths too uniform")
389
+
390
+ rq_count = analysis.get("rhetorical_questions", 0)
391
+ word_count = analysis.get("word_count", 0)
392
+ if word_count > 200 and rq_count == 0:
393
+ score += 5
394
+ reasons.append("No rhetorical questions in a long piece")
395
+
396
+ fp_data = analysis.get("first_person", {})
397
+ if "weak" in fp_data.get("assessment", ""):
398
+ score += 5
399
+ reasons.append("Little first-person voice")
400
+
401
+ em_dash_count = analysis.get("em_dash_count", 0)
402
+ if em_dash_count >= 5:
403
+ score += 5
404
+ reasons.append(f"{em_dash_count} em dashes — ChatGPT signature")
405
+
406
+ score = min(score, 100)
407
+
408
+ if score <= 20:
409
+ risk_level = "LOW"
410
+ elif score <= 50:
411
+ risk_level = "MEDIUM"
412
+ else:
413
+ risk_level = "HIGH"
414
+
415
+ return {
416
+ "risk_score": score,
417
+ "risk_level": risk_level,
418
+ "factors": reasons,
419
+ }
420
+
421
+
422
+ # ─────────────────────────────────────────────────────────────────────
423
+ # Input Models
424
+ # ─────────────────────────────────────────────────────────────────────
425
+
426
+
427
+ class AnalyzeTextInput(BaseModel):
428
+ """Input for analyzing text for AI tells."""
429
+
430
+ model_config = ConfigDict(str_strip_whitespace=True, extra="forbid")
431
+
432
+ text: str = Field(
433
+ ...,
434
+ description="The text to analyze for AI-generated patterns. Paste the full content.",
435
+ min_length=20,
436
+ max_length=50000,
437
+ )
438
+
439
+
440
+ class TextType(str, Enum):
441
+ """Type of text being humanized, affects rewriting aggressiveness."""
442
+
443
+ BLOG = "blog"
444
+ BUSINESS = "business"
445
+ ACADEMIC = "academic"
446
+ EMAIL = "email"
447
+ GENERAL = "general"
448
+
449
+
450
+ class HumanizeTextInput(BaseModel):
451
+ """Input for humanizing AI-generated text."""
452
+
453
+ model_config = ConfigDict(str_strip_whitespace=True, extra="forbid")
454
+
455
+ text: str = Field(
456
+ ...,
457
+ description="The AI-generated text to humanize.",
458
+ min_length=20,
459
+ max_length=50000,
460
+ )
461
+ text_type: TextType = Field(
462
+ default=TextType.GENERAL,
463
+ description="Type of text: 'blog', 'business', 'academic', 'email', or 'general'. Affects rewriting intensity.",
464
+ )
465
+ preserve_meaning: bool = Field(
466
+ default=True,
467
+ description="If true, preserve the core meaning and facts. If false, allow more creative liberties.",
468
+ )
469
+ voice_notes: str | None = Field(
470
+ default=None,
471
+ description="Optional notes about desired voice/style, e.g. 'conversational and slightly sarcastic' or 'authoritative but accessible'.",
472
+ max_length=500,
473
+ )
474
+
475
+
476
+ class VocabCheckInput(BaseModel):
477
+ """Input for quick vocabulary-only scan."""
478
+
479
+ model_config = ConfigDict(str_strip_whitespace=True, extra="forbid")
480
+
481
+ text: str = Field(
482
+ ...,
483
+ description="Text to scan for AI-associated vocabulary.",
484
+ min_length=10,
485
+ max_length=50000,
486
+ )
487
+
488
+
489
+ class RewriteSectionInput(BaseModel):
490
+ """Input for rewriting a specific section/paragraph."""
491
+
492
+ model_config = ConfigDict(str_strip_whitespace=True, extra="forbid")
493
+
494
+ text: str = Field(
495
+ ...,
496
+ description="The specific paragraph or section to rewrite.",
497
+ min_length=10,
498
+ max_length=10000,
499
+ )
500
+ context: str | None = Field(
501
+ default=None,
502
+ description="Surrounding context (what comes before/after) to maintain coherence.",
503
+ max_length=5000,
504
+ )
505
+ instruction: str | None = Field(
506
+ default=None,
507
+ description="Specific rewriting instruction, e.g. 'make more conversational' or 'add a personal anecdote'.",
508
+ max_length=500,
509
+ )
510
+
511
+
512
+ # ─────────────────────────────────────────────────────────────────────
513
+ # Tools
514
+ # ─────────────────────────────────────────────────────────────────────
515
+
516
+
517
+ @mcp.tool(
518
+ name="humanizer_analyze_ai_tells",
519
+ annotations={
520
+ "title": "Analyze Text for AI Tells",
521
+ "readOnlyHint": True,
522
+ "destructiveHint": False,
523
+ "idempotentHint": True,
524
+ "openWorldHint": False,
525
+ },
526
+ )
527
+ async def analyze_ai_tells(params: AnalyzeTextInput) -> str:
528
+ """Analyze text for AI-generated patterns and compute a detection risk score.
529
+
530
+ Scans for AI-associated vocabulary, structural patterns, burstiness,
531
+ contraction usage, paragraph uniformity, rhetorical questions, first-person
532
+ voice, and em dash frequency. Returns a comprehensive report with a 0–100
533
+ risk score and specific recommendations.
534
+
535
+ Args:
536
+ params (AnalyzeTextInput): Contains the text to analyze.
537
+
538
+ Returns:
539
+ str: JSON report with risk score, detected patterns, and fix recommendations.
540
+ """
541
+ text = params.text
542
+
543
+ vocab_findings = find_ai_vocabulary(text)
544
+ phrase_findings = find_ai_phrases(text)
545
+ sent_lengths = sentence_lengths(text)
546
+ burstiness = calculate_burstiness(sent_lengths)
547
+ contractions = check_contraction_usage(text)
548
+ para_uniformity = check_paragraph_uniformity(text)
549
+ rq_count = check_rhetorical_questions(text)
550
+ first_person = check_first_person(text)
551
+ em_dashes = count_em_dashes(text)
552
+ word_count = count_words(text)
553
+
554
+ analysis: dict[str, Any] = {
555
+ "word_count": word_count,
556
+ "sentence_count": len(sent_lengths),
557
+ "ai_vocabulary_count": len(vocab_findings),
558
+ "ai_vocabulary": vocab_findings[:20],
559
+ "ai_phrase_count": len(phrase_findings),
560
+ "ai_phrases": phrase_findings[:10],
561
+ "sentence_lengths": sent_lengths,
562
+ "burstiness": burstiness,
563
+ "contractions": contractions,
564
+ "paragraph_uniformity": para_uniformity,
565
+ "rhetorical_questions": rq_count,
566
+ "first_person": first_person,
567
+ "em_dash_count": em_dashes,
568
+ }
569
+
570
+ risk = compute_risk_score(analysis)
571
+ analysis["risk_assessment"] = risk
572
+
573
+ recommendations: list[str] = []
574
+ if len(vocab_findings) > 0:
575
+ top_words = list({v["word"] for v in vocab_findings})[:5]
576
+ recommendations.append(f"Replace AI vocabulary: {', '.join(top_words)}")
577
+ if len(phrase_findings) > 0:
578
+ recommendations.append("Remove or rephrase AI-associated phrases")
579
+ if burstiness < 0.35:
580
+ recommendations.append(
581
+ "Vary sentence lengths more aggressively (mix 4-word and 30-word sentences)"
582
+ )
583
+ if contractions.get("assessment") == "AI-like (too formal)":
584
+ recommendations.append("Add contractions (don't, it's, we've, etc.)")
585
+ if para_uniformity.get("assessment") == "too uniform (AI-like)":
586
+ recommendations.append("Create paragraph length asymmetry (1-sentence + 8-sentence mix)")
587
+ if word_count > 200 and rq_count == 0:
588
+ recommendations.append("Add 1-2 rhetorical questions")
589
+ if "weak" in first_person.get("assessment", ""):
590
+ recommendations.append("Add first-person perspective (I, we, my, our)")
591
+ if em_dashes >= 5:
592
+ recommendations.append(
593
+ f"Reduce em dashes from {em_dashes} to 1-2 (replace with commas/periods)"
594
+ )
595
+
596
+ analysis["recommendations"] = recommendations
597
+
598
+ return json.dumps(analysis, indent=2)
599
+
600
+
601
+ @mcp.tool(
602
+ name="humanizer_quick_vocab_scan",
603
+ annotations={
604
+ "title": "Quick AI Vocabulary Scan",
605
+ "readOnlyHint": True,
606
+ "destructiveHint": False,
607
+ "idempotentHint": True,
608
+ "openWorldHint": False,
609
+ },
610
+ )
611
+ async def quick_vocab_scan(params: VocabCheckInput) -> str:
612
+ """Fast scan for AI-associated vocabulary only — no structural analysis.
613
+
614
+ Use this for a quick check when you just want to find and replace AI words
615
+ without running the full analysis pipeline.
616
+
617
+ Args:
618
+ params (VocabCheckInput): Contains the text to scan.
619
+
620
+ Returns:
621
+ str: JSON with found AI words, their positions, and replacement suggestions.
622
+ """
623
+ text = params.text
624
+ vocab = find_ai_vocabulary(text)
625
+ phrases = find_ai_phrases(text)
626
+
627
+ return json.dumps(
628
+ {
629
+ "ai_words_found": len(vocab),
630
+ "ai_words": vocab,
631
+ "ai_phrases_found": len(phrases),
632
+ "ai_phrases": phrases,
633
+ "quick_fix_map": {
634
+ v["word"]: AI_VOCABULARY[v["word"]][0]
635
+ if AI_VOCABULARY[v["word"]][0]
636
+ else "(delete)"
637
+ for v in vocab
638
+ },
639
+ },
640
+ indent=2,
641
+ )
642
+
643
+
644
+ @mcp.tool(
645
+ name="humanizer_get_rewrite_instructions",
646
+ annotations={
647
+ "title": "Get Humanization Rewrite Instructions",
648
+ "readOnlyHint": True,
649
+ "destructiveHint": False,
650
+ "idempotentHint": True,
651
+ "openWorldHint": False,
652
+ },
653
+ )
654
+ async def get_rewrite_instructions(params: HumanizeTextInput) -> str:
655
+ """Analyze AI text and return detailed, step-by-step rewrite instructions.
656
+
657
+ This tool does NOT rewrite the text itself — it provides a structured
658
+ action plan that an LLM or human editor can follow to humanize the text.
659
+ The instructions are tailored to the text type and specific patterns found.
660
+
661
+ Args:
662
+ params (HumanizeTextInput): Contains text, text type, and voice preferences.
663
+
664
+ Returns:
665
+ str: JSON with analysis results and step-by-step rewrite instructions.
666
+ """
667
+ text = params.text
668
+ text_type = params.text_type
669
+
670
+ vocab = find_ai_vocabulary(text)
671
+ phrases = find_ai_phrases(text)
672
+ sent_lengths = sentence_lengths(text)
673
+ burstiness_val = calculate_burstiness(sent_lengths)
674
+ contractions = check_contraction_usage(text)
675
+ para_uni = check_paragraph_uniformity(text)
676
+ rq = check_rhetorical_questions(text)
677
+ fp = check_first_person(text)
678
+ em = count_em_dashes(text)
679
+ wc = count_words(text)
680
+
681
+ analysis = {
682
+ "word_count": wc,
683
+ "ai_vocabulary_count": len(vocab),
684
+ "ai_phrase_count": len(phrases),
685
+ "burstiness": burstiness_val,
686
+ "em_dash_count": em,
687
+ }
688
+
689
+ risk = compute_risk_score(
690
+ {
691
+ "word_count": wc,
692
+ "ai_vocabulary_count": len(vocab),
693
+ "ai_phrase_count": len(phrases),
694
+ "burstiness": burstiness_val,
695
+ "contractions": contractions,
696
+ "paragraph_uniformity": para_uni,
697
+ "rhetorical_questions": rq,
698
+ "first_person": fp,
699
+ "em_dash_count": em,
700
+ }
701
+ )
702
+
703
+ instructions: list[dict[str, Any]] = []
704
+
705
+ instructions.append(
706
+ {
707
+ "step": 1,
708
+ "action": "REWRITE INTRODUCTION",
709
+ "detail": "Delete the first 2-3 sentences entirely. Write a new opening that starts with a specific detail, bold claim, or anecdote. No preambles.",
710
+ "priority": "critical",
711
+ }
712
+ )
713
+
714
+ if vocab:
715
+ swap_map: dict[str, str] = {}
716
+ for v in vocab:
717
+ w = v["word"]
718
+ if w not in swap_map:
719
+ replacements = AI_VOCABULARY.get(w, [])
720
+ swap_map[w] = replacements[0] if replacements and replacements[0] else "(delete)"
721
+ instructions.append(
722
+ {
723
+ "step": 2,
724
+ "action": "REPLACE AI VOCABULARY",
725
+ "detail": f"Find and replace these {len(swap_map)} AI-associated words",
726
+ "swaps": swap_map,
727
+ "priority": "critical",
728
+ }
729
+ )
730
+
731
+ if phrases:
732
+ instructions.append(
733
+ {
734
+ "step": 3,
735
+ "action": "REMOVE AI PHRASES",
736
+ "detail": "Delete or completely rephrase these cliché AI constructions",
737
+ "phrases_to_kill": list({p["phrase"] for p in phrases}),
738
+ "priority": "high",
739
+ }
740
+ )
741
+
742
+ if burstiness_val < 0.35:
743
+ instructions.append(
744
+ {
745
+ "step": 4,
746
+ "action": "INCREASE SENTENCE LENGTH VARIATION",
747
+ "detail": f"Current burstiness: {burstiness_val} (target: >0.45). Current lengths: {sent_lengths[:10]}... Mix in 3-5 word sentences after long ones. Add sentence fragments. Break up any run of similar-length sentences.",
748
+ "priority": "high",
749
+ }
750
+ )
751
+
752
+ if contractions.get("assessment") == "AI-like (too formal)":
753
+ if text_type in [TextType.BLOG, TextType.EMAIL]:
754
+ contraction_level = "heavy"
755
+ frequency = "use them everywhere"
756
+ elif text_type == TextType.GENERAL:
757
+ contraction_level = "moderate"
758
+ frequency = "use them selectively and inconsistently"
759
+ else:
760
+ contraction_level = "light and inconsistent"
761
+ frequency = "use them selectively and inconsistently"
762
+ instructions.append(
763
+ {
764
+ "step": 5,
765
+ "action": "ADD CONTRACTIONS",
766
+ "detail": f"Use {contraction_level} contractions. Change 'it is' → 'it's', 'do not' → 'don't', 'we have' → 'we've'. For {text_type.value} text, {frequency}.",
767
+ "priority": "medium",
768
+ }
769
+ )
770
+
771
+ if para_uni.get("assessment") == "too uniform (AI-like)":
772
+ instructions.append(
773
+ {
774
+ "step": 6,
775
+ "action": "CREATE PARAGRAPH ASYMMETRY",
776
+ "detail": f"Current paragraph lengths: {para_uni.get('lengths', [])}. Mix one-sentence paragraphs with dense 6-8 sentence paragraphs. No two consecutive paragraphs should be similar length.",
777
+ "priority": "medium",
778
+ }
779
+ )
780
+
781
+ if em >= 3:
782
+ instructions.append(
783
+ {
784
+ "step": 7,
785
+ "action": "REDUCE EM DASHES",
786
+ "detail": f"Found {em} em dashes. Replace all but 1-2 with commas, periods, or parentheses. This is a known ChatGPT signature.",
787
+ "priority": "medium",
788
+ }
789
+ )
790
+
791
+ voice_instruction = params.voice_notes or "natural, conversational"
792
+ instructions.append(
793
+ {
794
+ "step": len(instructions) + 1,
795
+ "action": "INJECT HUMAN VOICE",
796
+ "detail": f"Target voice: {voice_instruction}. Add: (1) at least one first-person claim per major section, (2) 1-2 rhetorical questions, (3) specific proper nouns/dates/tool names, (4) at least one opinion or subjective judgment, (5) at least one admission of limitation or uncertainty.",
797
+ "priority": "high" if "weak" in fp.get("assessment", "") else "medium",
798
+ }
799
+ )
800
+
801
+ instructions.append(
802
+ {
803
+ "step": len(instructions) + 1,
804
+ "action": "FINAL READ-ALOUD PASS",
805
+ "detail": "Read the entire piece aloud (or mentally). Mark anything that sounds metronomic, robotic, or that you would never say in conversation. Fix those spots.",
806
+ "priority": "required",
807
+ }
808
+ )
809
+
810
+ return json.dumps(
811
+ {
812
+ "analysis_summary": analysis,
813
+ "risk_assessment": risk,
814
+ "text_type": text_type.value,
815
+ "preserve_meaning": params.preserve_meaning,
816
+ "rewrite_instructions": instructions,
817
+ "instruction_count": len(instructions),
818
+ },
819
+ indent=2,
820
+ )
821
+
822
+
823
+ @mcp.tool(
824
+ name="humanizer_compare_before_after",
825
+ annotations={
826
+ "title": "Compare Before/After Detection Metrics",
827
+ "readOnlyHint": True,
828
+ "destructiveHint": False,
829
+ "idempotentHint": True,
830
+ "openWorldHint": False,
831
+ },
832
+ )
833
+ async def compare_before_after(original: str, rewritten: str) -> str:
834
+ """Compare detection metrics between original and rewritten text.
835
+
836
+ Use after humanizing to verify improvement. Shows side-by-side
837
+ metrics for burstiness, vocabulary tells, structure, and risk scores.
838
+
839
+ Args:
840
+ original (str): The original AI-generated text.
841
+ rewritten (str): The humanized version.
842
+
843
+ Returns:
844
+ str: JSON comparison of detection metrics for both versions.
845
+ """
846
+
847
+ def quick_analysis(text: str) -> dict[str, Any]:
848
+ vocab = find_ai_vocabulary(text)
849
+ phrases = find_ai_phrases(text)
850
+ sl = sentence_lengths(text)
851
+ burst = calculate_burstiness(sl)
852
+ contr = check_contraction_usage(text)
853
+ para = check_paragraph_uniformity(text)
854
+ rq = check_rhetorical_questions(text)
855
+ fp = check_first_person(text)
856
+ em = count_em_dashes(text)
857
+ wc = count_words(text)
858
+
859
+ risk = compute_risk_score(
860
+ {
861
+ "word_count": wc,
862
+ "ai_vocabulary_count": len(vocab),
863
+ "ai_phrase_count": len(phrases),
864
+ "burstiness": burst,
865
+ "contractions": contr,
866
+ "paragraph_uniformity": para,
867
+ "rhetorical_questions": rq,
868
+ "first_person": fp,
869
+ "em_dash_count": em,
870
+ }
871
+ )
872
+
873
+ return {
874
+ "word_count": wc,
875
+ "sentence_count": len(sl),
876
+ "ai_vocabulary_count": len(vocab),
877
+ "ai_phrase_count": len(phrases),
878
+ "burstiness": burst,
879
+ "contraction_assessment": contr.get("assessment"),
880
+ "paragraph_uniformity": para.get("assessment"),
881
+ "rhetorical_questions": rq,
882
+ "first_person_count": fp.get("total_occurrences", 0),
883
+ "em_dash_count": em,
884
+ "risk_score": risk["risk_score"],
885
+ "risk_level": risk["risk_level"],
886
+ }
887
+
888
+ orig = quick_analysis(original)
889
+ rewr = quick_analysis(rewritten)
890
+
891
+ improvements: dict[str, str] = {}
892
+ for key in ["ai_vocabulary_count", "ai_phrase_count", "risk_score", "em_dash_count"]:
893
+ diff = orig.get(key, 0) - rewr.get(key, 0)
894
+ improvements[key] = (
895
+ f"{'improved' if diff > 0 else 'unchanged' if diff == 0 else 'worsened'} (Δ{diff:+d})"
896
+ )
897
+
898
+ burst_diff = rewr.get("burstiness", 0) - orig.get("burstiness", 0)
899
+ improvements["burstiness"] = (
900
+ f"{'improved' if burst_diff > 0 else 'unchanged' if burst_diff == 0 else 'worsened'} (Δ{burst_diff:+.3f})"
901
+ )
902
+
903
+ if rewr["risk_score"] <= 20:
904
+ verdict = "PASS — likely undetectable"
905
+ elif rewr["risk_score"] < orig["risk_score"]:
906
+ verdict = "IMPROVED but still risky"
907
+ else:
908
+ verdict = "NEEDS MORE WORK"
909
+
910
+ return json.dumps(
911
+ {
912
+ "original": orig,
913
+ "rewritten": rewr,
914
+ "improvements": improvements,
915
+ "overall_verdict": verdict,
916
+ },
917
+ indent=2,
918
+ )
919
+
920
+
921
+ @mcp.tool(
922
+ name="humanizer_get_banned_words",
923
+ annotations={
924
+ "title": "Get Full AI Vocabulary Ban List",
925
+ "readOnlyHint": True,
926
+ "destructiveHint": False,
927
+ "idempotentHint": True,
928
+ "openWorldHint": False,
929
+ },
930
+ )
931
+ async def get_banned_words() -> str:
932
+ """Return the complete list of AI-associated words and their human replacements.
933
+
934
+ Use as a reference when manually editing text. Includes both single words
935
+ and multi-word phrases that trigger AI detection.
936
+
937
+ Returns:
938
+ str: JSON with vocabulary ban list and phrase ban list.
939
+ """
940
+ return json.dumps(
941
+ {
942
+ "vocabulary_ban_list": dict(AI_VOCABULARY),
943
+ "phrase_ban_list": AI_PHRASES,
944
+ "vocabulary_count": len(AI_VOCABULARY),
945
+ "phrase_count": len(AI_PHRASES),
946
+ },
947
+ indent=2,
948
+ )
949
+
950
+
951
+ # ─────────────────────────────────────────────────────────────────────
952
+ # Entry Point
953
+ # ─────────────────────────────────────────────────────────────────────
954
+
955
+
956
+ def main() -> None:
957
+ """CLI entry point registered in pyproject.toml as `humanizer-mcp`."""
958
+ from humanizer_mcp import __version__
959
+
960
+ parser = argparse.ArgumentParser(
961
+ prog="humanizer-mcp",
962
+ description="MCP server for analyzing and humanizing AI-generated text.",
963
+ )
964
+ parser.add_argument(
965
+ "--version",
966
+ action="version",
967
+ version=f"humanizer-mcp {__version__}",
968
+ )
969
+ parser.add_argument(
970
+ "--http",
971
+ action="store_true",
972
+ help="Run as streamable-HTTP server instead of stdio (default).",
973
+ )
974
+ parser.add_argument(
975
+ "--port",
976
+ type=int,
977
+ default=8000,
978
+ help="Port for HTTP transport (default: 8000).",
979
+ )
980
+ args = parser.parse_args()
981
+
982
+ if args.http:
983
+ mcp.run(transport="streamable_http", port=args.port)
984
+ else:
985
+ mcp.run()
986
+
987
+
988
+ if __name__ == "__main__":
989
+ main()
@@ -0,0 +1,171 @@
1
+ Metadata-Version: 2.4
2
+ Name: humanizer-mcp
3
+ Version: 0.1.0
4
+ Summary: MCP server for analyzing and humanizing AI-generated text to bypass AI detection.
5
+ Project-URL: Homepage, https://github.com/aousabdo/humanizer-mcp
6
+ Project-URL: Repository, https://github.com/aousabdo/humanizer-mcp
7
+ Project-URL: Issues, https://github.com/aousabdo/humanizer-mcp/issues
8
+ Project-URL: Changelog, https://github.com/aousabdo/humanizer-mcp/blob/main/CHANGELOG.md
9
+ Author-email: Aous Abdo <aousabdo@gmail.com>
10
+ License: MIT
11
+ License-File: LICENSE
12
+ Keywords: ai-detection,anthropic,claude,fastmcp,humanizer,llm,mcp,model-context-protocol,text-analysis
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Intended Audience :: End Users/Desktop
16
+ Classifier: License :: OSI Approved :: MIT License
17
+ Classifier: Operating System :: OS Independent
18
+ Classifier: Programming Language :: Python :: 3
19
+ Classifier: Programming Language :: Python :: 3.10
20
+ Classifier: Programming Language :: Python :: 3.11
21
+ Classifier: Programming Language :: Python :: 3.12
22
+ Classifier: Programming Language :: Python :: 3.13
23
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
24
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
25
+ Classifier: Topic :: Text Processing :: Linguistic
26
+ Requires-Python: >=3.10
27
+ Requires-Dist: mcp>=1.2.0
28
+ Requires-Dist: pydantic>=2.0.0
29
+ Provides-Extra: dev
30
+ Requires-Dist: pytest>=7.0; extra == 'dev'
31
+ Requires-Dist: ruff>=0.5.0; extra == 'dev'
32
+ Description-Content-Type: text/markdown
33
+
34
+ # humanizer-mcp
35
+
36
+ [![PyPI version](https://img.shields.io/pypi/v/humanizer-mcp.svg)](https://pypi.org/project/humanizer-mcp/)
37
+ [![npm version](https://img.shields.io/npm/v/humanizer-mcp.svg)](https://www.npmjs.com/package/humanizer-mcp)
38
+ [![Python versions](https://img.shields.io/pypi/pyversions/humanizer-mcp.svg)](https://pypi.org/project/humanizer-mcp/)
39
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
40
+ [![CI](https://github.com/aousabdo/humanizer-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/aousabdo/humanizer-mcp/actions/workflows/ci.yml)
41
+
42
+ An MCP (Model Context Protocol) server that measures AI-detection risk in a piece of text and tells you — line by line — what to change. Works with Claude Code, Claude Desktop, and any MCP-compatible client.
43
+
44
+ Rather than running your prose through a black-box "humanizer," this server analyzes it against known detection signals (vocabulary, burstiness, contraction usage, paragraph uniformity, em dashes, first-person voice) and returns a structured report with a 0–100 risk score and a concrete rewrite plan. The actual rewriting is left to the LLM that's driving the conversation — which is the point: a planner, not a laundering service.
45
+
46
+ ## Tools
47
+
48
+ | Tool | What it does |
49
+ |---|---|
50
+ | `humanizer_analyze_ai_tells` | Full analysis with risk score and fix recommendations. |
51
+ | `humanizer_quick_vocab_scan` | Fast word- and phrase-level scan with replacement suggestions. |
52
+ | `humanizer_get_rewrite_instructions` | Step-by-step rewrite plan, tailored to text type (blog / business / academic / email / general). |
53
+ | `humanizer_compare_before_after` | Side-by-side metrics for an original and a rewrite, with a PASS / IMPROVED / NEEDS MORE WORK verdict. |
54
+ | `humanizer_get_banned_words` | The full vocabulary and phrase ban list, for reference. |
55
+
56
+ ## Installation
57
+
58
+ ### With `uvx` (recommended — no install step)
59
+
60
+ ```bash
61
+ uvx humanizer-mcp
62
+ ```
63
+
64
+ ### With `pip`
65
+
66
+ ```bash
67
+ pip install humanizer-mcp
68
+ humanizer-mcp
69
+ ```
70
+
71
+ ### With `npx`
72
+
73
+ ```bash
74
+ npx humanizer-mcp
75
+ ```
76
+
77
+ The npm package is a thin launcher that delegates to `uvx`, `pipx run`, or `python3 -m humanizer_mcp` — whichever is available on the host.
78
+
79
+ ## Configure your MCP client
80
+
81
+ ### Claude Code
82
+
83
+ ```bash
84
+ claude mcp add humanizer -- uvx humanizer-mcp
85
+ ```
86
+
87
+ ### Claude Desktop
88
+
89
+ Add to `claude_desktop_config.json`:
90
+
91
+ ```json
92
+ {
93
+ "mcpServers": {
94
+ "humanizer": {
95
+ "command": "uvx",
96
+ "args": ["humanizer-mcp"]
97
+ }
98
+ }
99
+ }
100
+ ```
101
+
102
+ Config location:
103
+ - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
104
+ - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
105
+ - Linux: `~/.config/Claude/claude_desktop_config.json`
106
+
107
+ ### Generic MCP client (stdio)
108
+
109
+ ```json
110
+ {
111
+ "command": "uvx",
112
+ "args": ["humanizer-mcp"]
113
+ }
114
+ ```
115
+
116
+ ### HTTP transport
117
+
118
+ For remote access, run the server on a port and point your client at it:
119
+
120
+ ```bash
121
+ humanizer-mcp --http --port 8000
122
+ ```
123
+
124
+ ## Try it with the MCP Inspector
125
+
126
+ Poke at the tools without configuring a client:
127
+
128
+ ```bash
129
+ npx @modelcontextprotocol/inspector uvx humanizer-mcp
130
+ ```
131
+
132
+ ## Example prompts
133
+
134
+ With the server connected to Claude, you can say things like:
135
+
136
+ - *"Analyze this blog post for AI tells and tell me what to change."*
137
+ - *"Run a quick vocab scan on this paragraph."*
138
+ - *"Give me rewrite instructions for this academic abstract — keep it formal but fix the burstiness."*
139
+ - *"Compare these two drafts. Did my edit actually lower the detection risk?"*
140
+
141
+ Claude picks the right tool automatically.
142
+
143
+ ## How the risk score works
144
+
145
+ The 0–100 score combines eight signals:
146
+
147
+ 1. **AI vocabulary hits** — words statistically overrepresented in LLM output (`delve`, `crucial`, `leverage`, `myriad`, …).
148
+ 2. **AI phrase hits** — cliché structural tells (`it's important to note`, `in the ever-evolving`, `at the end of the day`, …).
149
+ 3. **Burstiness** — coefficient of variation of sentence lengths. AI writing clusters around a single length; humans mix short fragments and long digressions.
150
+ 4. **Contractions** — expanded forms (*it is*, *do not*) read as AI-formal; contractions read as conversational.
151
+ 5. **Paragraph uniformity** — AI tends to produce paragraphs of similar size.
152
+ 6. **Rhetorical questions** — near-absent in AI prose above 200 words.
153
+ 7. **First-person voice** — AI avoids *I*, *we*, *my*, *our* unless prompted.
154
+ 8. **Em dashes** — a ChatGPT signature; heavy use is a strong signal.
155
+
156
+ Each signal adds to the score independently; the total is clamped to 100 and bucketed into LOW (≤ 20), MEDIUM (21–50), or HIGH (51+).
157
+
158
+ ## Development
159
+
160
+ ```bash
161
+ git clone https://github.com/aousabdo/humanizer-mcp
162
+ cd humanizer-mcp
163
+ pip install -e ".[dev]"
164
+ pytest
165
+ ```
166
+
167
+ See [CONTRIBUTING.md](CONTRIBUTING.md) for more.
168
+
169
+ ## License
170
+
171
+ MIT — see [LICENSE](LICENSE).
@@ -0,0 +1,8 @@
1
+ humanizer_mcp/__init__.py,sha256=bNVSGF9_fvgzTlU7yO0Khj9VzXODjGCCRd1Ae5DBUhs,180
2
+ humanizer_mcp/__main__.py,sha256=iXm0nt2-S6yCplsVgiCx7PdRtSZ91gov5OrCkvt8Pno,118
3
+ humanizer_mcp/server.py,sha256=vpBKtQVh39jiT02D8MhsaACYAx8_1rcMwSZ1Ebaj9Mk,33549
4
+ humanizer_mcp-0.1.0.dist-info/METADATA,sha256=JanzN-wad6Fep-A0eBlbdLFBfZBaOCIXSOLsJIo4yzw,6320
5
+ humanizer_mcp-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
6
+ humanizer_mcp-0.1.0.dist-info/entry_points.txt,sha256=x2qMMY5Hjw3G3KkOhZ1KejdVaHtXDQUqoxYcnUDaToM,60
7
+ humanizer_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=UY93uoQRWSB3JLOgbnyg0yVSkxTjG7HzdfbgxUqqJZg,1066
8
+ humanizer_mcp-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.29.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ humanizer-mcp = humanizer_mcp.server:main
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Aous Abdo
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.