humanizer-mcp 0.1.0__tar.gz

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,42 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *$py.class
5
+ *.egg-info/
6
+ *.egg
7
+ dist/
8
+ build/
9
+ .venv/
10
+ venv/
11
+ env/
12
+ .eggs/
13
+ .pytest_cache/
14
+ .ruff_cache/
15
+ .mypy_cache/
16
+ .coverage
17
+ htmlcov/
18
+ .tox/
19
+ .python-version
20
+ pip-wheel-metadata/
21
+
22
+ # Node
23
+ node_modules/
24
+ npm-debug.log*
25
+ yarn-debug.log*
26
+ yarn-error.log*
27
+ .pnpm-debug.log*
28
+
29
+ # Editors
30
+ .vscode/
31
+ .idea/
32
+ *.swp
33
+ *.swo
34
+ *~
35
+
36
+ # OS
37
+ .DS_Store
38
+ Thumbs.db
39
+
40
+ # Environment
41
+ .env
42
+ .env.local
@@ -0,0 +1,21 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [Unreleased]
9
+
10
+ ## [0.1.0] — 2026-04-24
11
+
12
+ ### Added
13
+
14
+ - Initial release.
15
+ - Five MCP tools: `humanizer_analyze_ai_tells`, `humanizer_quick_vocab_scan`, `humanizer_get_rewrite_instructions`, `humanizer_compare_before_after`, `humanizer_get_banned_words`.
16
+ - Stdio and streamable-HTTP transports.
17
+ - `--version` and `--help` flags on the CLI.
18
+ - npm launcher (`humanizer-mcp`) that delegates to `uvx`, `pipx run`, or `python3 -m humanizer_mcp`.
19
+
20
+ [Unreleased]: https://github.com/aousabdo/humanizer-mcp/compare/v0.1.0...HEAD
21
+ [0.1.0]: https://github.com/aousabdo/humanizer-mcp/releases/tag/v0.1.0
@@ -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.
@@ -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,138 @@
1
+ # humanizer-mcp
2
+
3
+ [![PyPI version](https://img.shields.io/pypi/v/humanizer-mcp.svg)](https://pypi.org/project/humanizer-mcp/)
4
+ [![npm version](https://img.shields.io/npm/v/humanizer-mcp.svg)](https://www.npmjs.com/package/humanizer-mcp)
5
+ [![Python versions](https://img.shields.io/pypi/pyversions/humanizer-mcp.svg)](https://pypi.org/project/humanizer-mcp/)
6
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
7
+ [![CI](https://github.com/aousabdo/humanizer-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/aousabdo/humanizer-mcp/actions/workflows/ci.yml)
8
+
9
+ 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.
10
+
11
+ 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.
12
+
13
+ ## Tools
14
+
15
+ | Tool | What it does |
16
+ |---|---|
17
+ | `humanizer_analyze_ai_tells` | Full analysis with risk score and fix recommendations. |
18
+ | `humanizer_quick_vocab_scan` | Fast word- and phrase-level scan with replacement suggestions. |
19
+ | `humanizer_get_rewrite_instructions` | Step-by-step rewrite plan, tailored to text type (blog / business / academic / email / general). |
20
+ | `humanizer_compare_before_after` | Side-by-side metrics for an original and a rewrite, with a PASS / IMPROVED / NEEDS MORE WORK verdict. |
21
+ | `humanizer_get_banned_words` | The full vocabulary and phrase ban list, for reference. |
22
+
23
+ ## Installation
24
+
25
+ ### With `uvx` (recommended — no install step)
26
+
27
+ ```bash
28
+ uvx humanizer-mcp
29
+ ```
30
+
31
+ ### With `pip`
32
+
33
+ ```bash
34
+ pip install humanizer-mcp
35
+ humanizer-mcp
36
+ ```
37
+
38
+ ### With `npx`
39
+
40
+ ```bash
41
+ npx humanizer-mcp
42
+ ```
43
+
44
+ The npm package is a thin launcher that delegates to `uvx`, `pipx run`, or `python3 -m humanizer_mcp` — whichever is available on the host.
45
+
46
+ ## Configure your MCP client
47
+
48
+ ### Claude Code
49
+
50
+ ```bash
51
+ claude mcp add humanizer -- uvx humanizer-mcp
52
+ ```
53
+
54
+ ### Claude Desktop
55
+
56
+ Add to `claude_desktop_config.json`:
57
+
58
+ ```json
59
+ {
60
+ "mcpServers": {
61
+ "humanizer": {
62
+ "command": "uvx",
63
+ "args": ["humanizer-mcp"]
64
+ }
65
+ }
66
+ }
67
+ ```
68
+
69
+ Config location:
70
+ - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
71
+ - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
72
+ - Linux: `~/.config/Claude/claude_desktop_config.json`
73
+
74
+ ### Generic MCP client (stdio)
75
+
76
+ ```json
77
+ {
78
+ "command": "uvx",
79
+ "args": ["humanizer-mcp"]
80
+ }
81
+ ```
82
+
83
+ ### HTTP transport
84
+
85
+ For remote access, run the server on a port and point your client at it:
86
+
87
+ ```bash
88
+ humanizer-mcp --http --port 8000
89
+ ```
90
+
91
+ ## Try it with the MCP Inspector
92
+
93
+ Poke at the tools without configuring a client:
94
+
95
+ ```bash
96
+ npx @modelcontextprotocol/inspector uvx humanizer-mcp
97
+ ```
98
+
99
+ ## Example prompts
100
+
101
+ With the server connected to Claude, you can say things like:
102
+
103
+ - *"Analyze this blog post for AI tells and tell me what to change."*
104
+ - *"Run a quick vocab scan on this paragraph."*
105
+ - *"Give me rewrite instructions for this academic abstract — keep it formal but fix the burstiness."*
106
+ - *"Compare these two drafts. Did my edit actually lower the detection risk?"*
107
+
108
+ Claude picks the right tool automatically.
109
+
110
+ ## How the risk score works
111
+
112
+ The 0–100 score combines eight signals:
113
+
114
+ 1. **AI vocabulary hits** — words statistically overrepresented in LLM output (`delve`, `crucial`, `leverage`, `myriad`, …).
115
+ 2. **AI phrase hits** — cliché structural tells (`it's important to note`, `in the ever-evolving`, `at the end of the day`, …).
116
+ 3. **Burstiness** — coefficient of variation of sentence lengths. AI writing clusters around a single length; humans mix short fragments and long digressions.
117
+ 4. **Contractions** — expanded forms (*it is*, *do not*) read as AI-formal; contractions read as conversational.
118
+ 5. **Paragraph uniformity** — AI tends to produce paragraphs of similar size.
119
+ 6. **Rhetorical questions** — near-absent in AI prose above 200 words.
120
+ 7. **First-person voice** — AI avoids *I*, *we*, *my*, *our* unless prompted.
121
+ 8. **Em dashes** — a ChatGPT signature; heavy use is a strong signal.
122
+
123
+ Each signal adds to the score independently; the total is clamped to 100 and bucketed into LOW (≤ 20), MEDIUM (21–50), or HIGH (51+).
124
+
125
+ ## Development
126
+
127
+ ```bash
128
+ git clone https://github.com/aousabdo/humanizer-mcp
129
+ cd humanizer-mcp
130
+ pip install -e ".[dev]"
131
+ pytest
132
+ ```
133
+
134
+ See [CONTRIBUTING.md](CONTRIBUTING.md) for more.
135
+
136
+ ## License
137
+
138
+ MIT — see [LICENSE](LICENSE).
@@ -0,0 +1,100 @@
1
+ [build-system]
2
+ requires = ["hatchling>=1.21.0"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "humanizer-mcp"
7
+ dynamic = ["version"]
8
+ description = "MCP server for analyzing and humanizing AI-generated text to bypass AI detection."
9
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ license = { text = "MIT" }
12
+ authors = [
13
+ { name = "Aous Abdo", email = "aousabdo@gmail.com" },
14
+ ]
15
+ keywords = [
16
+ "mcp",
17
+ "model-context-protocol",
18
+ "ai-detection",
19
+ "humanizer",
20
+ "claude",
21
+ "anthropic",
22
+ "llm",
23
+ "text-analysis",
24
+ "fastmcp",
25
+ ]
26
+ classifiers = [
27
+ "Development Status :: 4 - Beta",
28
+ "Intended Audience :: Developers",
29
+ "Intended Audience :: End Users/Desktop",
30
+ "License :: OSI Approved :: MIT License",
31
+ "Operating System :: OS Independent",
32
+ "Programming Language :: Python :: 3",
33
+ "Programming Language :: Python :: 3.10",
34
+ "Programming Language :: Python :: 3.11",
35
+ "Programming Language :: Python :: 3.12",
36
+ "Programming Language :: Python :: 3.13",
37
+ "Topic :: Scientific/Engineering :: Artificial Intelligence",
38
+ "Topic :: Text Processing :: Linguistic",
39
+ "Topic :: Software Development :: Libraries :: Python Modules",
40
+ ]
41
+ dependencies = [
42
+ "mcp>=1.2.0",
43
+ "pydantic>=2.0.0",
44
+ ]
45
+
46
+ [project.optional-dependencies]
47
+ dev = [
48
+ "pytest>=7.0",
49
+ "ruff>=0.5.0",
50
+ ]
51
+
52
+ [project.scripts]
53
+ humanizer-mcp = "humanizer_mcp.server:main"
54
+
55
+ [project.urls]
56
+ Homepage = "https://github.com/aousabdo/humanizer-mcp"
57
+ Repository = "https://github.com/aousabdo/humanizer-mcp"
58
+ Issues = "https://github.com/aousabdo/humanizer-mcp/issues"
59
+ Changelog = "https://github.com/aousabdo/humanizer-mcp/blob/main/CHANGELOG.md"
60
+
61
+ [tool.hatch.version]
62
+ path = "src/humanizer_mcp/__init__.py"
63
+
64
+ [tool.hatch.build.targets.wheel]
65
+ packages = ["src/humanizer_mcp"]
66
+
67
+ [tool.hatch.build.targets.sdist]
68
+ include = [
69
+ "/src",
70
+ "/tests",
71
+ "/README.md",
72
+ "/LICENSE",
73
+ "/CHANGELOG.md",
74
+ "/pyproject.toml",
75
+ ]
76
+
77
+ [tool.ruff]
78
+ line-length = 100
79
+ target-version = "py310"
80
+
81
+ [tool.ruff.lint]
82
+ select = [
83
+ "E", # pycodestyle errors
84
+ "F", # pyflakes
85
+ "I", # isort
86
+ "UP", # pyupgrade
87
+ "B", # flake8-bugbear
88
+ ]
89
+ ignore = [
90
+ "E501", # line too long (handled by formatter where reasonable)
91
+ ]
92
+
93
+ [tool.ruff.format]
94
+ quote-style = "double"
95
+ indent-style = "space"
96
+
97
+ [tool.pytest.ini_options]
98
+ testpaths = ["tests"]
99
+ python_files = "test_*.py"
100
+ addopts = "-ra"
@@ -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()