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.
- humanizer_mcp/__init__.py +7 -0
- humanizer_mcp/__main__.py +6 -0
- humanizer_mcp/server.py +989 -0
- humanizer_mcp-0.1.0.dist-info/METADATA +171 -0
- humanizer_mcp-0.1.0.dist-info/RECORD +8 -0
- humanizer_mcp-0.1.0.dist-info/WHEEL +4 -0
- humanizer_mcp-0.1.0.dist-info/entry_points.txt +2 -0
- humanizer_mcp-0.1.0.dist-info/licenses/LICENSE +21 -0
humanizer_mcp/server.py
ADDED
|
@@ -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
|
+
[](https://pypi.org/project/humanizer-mcp/)
|
|
37
|
+
[](https://www.npmjs.com/package/humanizer-mcp)
|
|
38
|
+
[](https://pypi.org/project/humanizer-mcp/)
|
|
39
|
+
[](LICENSE)
|
|
40
|
+
[](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,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.
|