de en es ja ko ru zh

pyobfus-mcp

Name: pyobfus-mcp
Author: zhurong2020

by zhurong2020

Overview Schema Related Servers Score Discussions

Python

Local

pyobfus — the Python obfuscator

pyobfus (pronounced as "Python obfuscator") is a modern, AST-based python-obfuscator / code-obfuscator with framework-aware presets, reverse stack-trace mapping for AI-assisted debugging, and a machine-readable JSON CLI designed for Claude Code, Cursor, and MCP agents. A transparent, open-source alternative to PyArmor.

PyPI version PyPI downloads Documentation Status License Python Code style: black

A Python code obfuscator built with AST-based transformations. Supports Python 3.8 through 3.14. Provides reliable name mangling, string encoding, control-flow flattening, AES-256 string encryption, and — unique to pyobfus — a reverse-mapping workflow that lets you (or your AI coding assistant) debug obfuscated stack traces without giving up the protection.

🔌 Companion MCP server: `pyobfus-mcp`

This repository ships two installable packages:

Package	What it is	Install
`pyobfus`	The Python obfuscator (CLI + library).	`pip install pyobfus`
`pyobfus-mcp`	A Model Context Protocol (MCP) server that exposes pyobfus's tools to AI coding agents.	`pip install pyobfus-mcp`

The MCP server lives in pyobfus_mcp/ and is built on the official Model Context Protocol Python SDK (FastMCP). It registers five MCP tools so Claude Desktop, Claude Code, Cursor, Windsurf, and Zed can call pyobfus directly from agent conversations — no shelling out:

MCP tool	Implementation	Purpose
`check_obfuscation_risks`	`pyobfus_mcp/tools.py`	Pre-flight risk scan (eval/exec, dynamic attribute, framework reflection)
`generate_pyobfus_config`	`pyobfus_mcp/tools.py`	Auto-detect framework → write a working `pyobfus.yaml`
`unmap_stack_trace`	`pyobfus_mcp/tools.py`	Reverse obfuscated identifiers in a production stack trace
`list_presets`	`pyobfus_mcp/tools.py`	Enumerate community / framework / Pro presets
`explain_preset`	`pyobfus_mcp/tools.py`	Describe what a named preset changes

The server is registered in the official MCP Registry under io.github.zhurong2020/pyobfus-mcp. The transport is stdio. See pyobfus_mcp/README.md for per-client configuration snippets.

🤖 New in v0.4.0 — AI-native features

pyobfus --check src/ — pre-flight risk scan: detects eval/exec, dynamic attribute access, and framework reflection points before you obfuscate. JSON output with an ai_hint telling your AI assistant what to run next.
pyobfus --init src/ — zero-config onboarding: scans the project, detects FastAPI/Django/Pydantic/Click/SQLAlchemy, and writes a ready-to-use pyobfus.yaml.
pyobfus --unmap --trace error.log --mapping mapping.json — reverse obfuscated identifiers in a production stack trace so you can debug (or hand the trace to an AI assistant) without reversing the obfuscation itself.
Framework-aware presets — --preset fastapi | django | flask | pydantic | click | sqlalchemy with built-in exclusions for dispatch methods, decorators, ORM fields, migrations, and dependency-injection parameters.
Global --json — every CLI mode (obfuscate, --check, --unmap, --init) emits the same structured schema with an ai_hint field, ready for Claude Code, Cursor, Windsurf, and MCP servers to consume.

Related MCP server: MCP Python Toolbox

Features

✅ Free Edition

The following features are fully implemented and available in the current version:

🆕 Cross-File Obfuscation (v0.2.0): Consistent name obfuscation across multiple files
- Automatic import statement rewriting
- __all__ list updates with obfuscated names
- Global symbol table with collision detection
- Two-phase obfuscation pipeline (Scan → Transform)
- Preview mode with --dry-run flag
Name Mangling: Rename variables, functions, classes, and class attributes to obfuscated names (I0, I1, I2...)
Comment Removal: Strip comments and docstrings
String Encoding: Base64 encoding for string literals with automatic decoder injection
Parameter Preservation: Preserve function parameter names for keyword argument compatibility (--preserve-param-names)
Multi-file Support: Obfuscate entire projects with preserved import relationships
File Filtering: Exclude files using glob patterns (test files, config files, etc.)
Configuration Files: YAML-based configuration for repeatable builds
Selective Obfuscation: Preserve specific names (builtins, magic methods, custom exclusions)

🔒 Pro Edition (Available Now)

The following advanced features are available with a Pro license:

String Encryption (v0.1.6+)
- AES-256 encryption for strings
- Runtime decryption with injected decoder
- Automatic key generation
Anti-Debugging (v0.1.6+)
- Debugger detection checks injected into functions
- Multiple detection methods (sys.gettrace, sys.settrace)
- Configurable behavior
Control Flow Flattening (v0.3.0+)
- State machine transformation for if/else/elif
- For/while loop flattening
- Nested structure support
- CLI: --control-flow
Dead Code Injection (v0.3.0+)
- Insertion of unreachable code paths
- Four strategies: after-return, false branches, opaque predicates, decoy functions
- CLI: --dead-code
License Embedding (v0.3.0+)
- Embed expiration dates: --expire 2025-12-31
- Machine binding: --bind-machine
- Run count limits: --max-runs 100
- Offline verification - no external dependencies
Configuration Presets (v0.3.0+)
- --preset trial - 30-day time-limited version
- --preset commercial - Maximum protection with machine binding
- --preset library - For pip-distributable libraries
- --preset maximum - Highest security with all protections
- --list-presets - View all presets

See ROADMAP.md for the full feature timeline.

Try Pro Features FREE

Try all Pro features for 5 days - no registration or credit card required!

# Start your free trial
pyobfus-trial start

# Check trial status
pyobfus-trial status

# Use Pro features during trial
pyobfus input.py -o output.py --level pro

What's included in the trial:

Control flow flattening (--control-flow)
AES-256 string encryption (--string-encryption)
Anti-debugging protection (--anti-debug)
Dead code injection (--dead-code)
License embedding (--expire, --bind-machine, --max-runs)
Configuration presets (--preset trial/commercial/library/maximum)
Unlimited files and lines of code

After your trial, purchase a license to continue using Pro features.

Purchase Professional Edition

Pro Edition Features:

🔀 Control Flow Flattening (v0.3.0+)
🧩 Dead Code Injection (v0.3.0+)
🔐 AES-256 String Encryption
🛡️ Anti-Debugging Checks
📅 License Embedding (v0.3.0+) - Expiration, machine binding, run limits
⚡ Configuration Presets (v0.3.0+) - One-command setup
🔄 Lifetime Updates
💻 Up to 3 devices per license
📧 Priority Email Support

Price: $45.00 USD (one-time payment)

How to Purchase

Visit our purchase page: pyobfus.github.io/purchase for detailed information and secure checkout.

Quick purchase: 🚀 Buy Now - Direct checkout link (Instant delivery • 30-day money-back guarantee)

3-Step Purchase Process:

Complete Secure Checkout (Stripe)
- Click the buy link above or visit the purchase page
- Enter your email (for license delivery)
- Complete payment securely via Stripe
Receive License Key
- License key delivered to your email within minutes
- Format: PYOB-XXXX-XXXX-XXXX-XXXX
- Check Spam/Junk folder if not in inbox

Activate License

pip install --upgrade pyobfus
pyobfus-license register PYOB-XXXX-XXXX-XXXX-XXXX
pyobfus-license status

Start Using Pro Features

# Quick start with presets
pyobfus src/ -o dist/ --preset commercial   # Maximum protection
pyobfus src/ -o dist/ --preset trial        # 30-day trial version
pyobfus src/ -o dist/ --preset library      # For pip distribution

# Individual features
pyobfus input.py -o output.py --string-encryption
pyobfus input.py -o output.py --anti-debug
pyobfus input.py -o output.py --control-flow
pyobfus input.py -o output.py --dead-code

# License restrictions
pyobfus src/ -o dist/ --expire 2025-12-31 --bind-machine --max-runs 100

# All Pro features
pyobfus input.py -o output.py --string-encryption --anti-debug --control-flow --dead-code

Support: If you encounter any issues, contact zhurong0525@gmail.com with your license key.

Legal & Policies

By purchasing pyobfus Professional Edition, you agree to our:

Terms of Service & EULA - License agreement and usage terms
Refund Policy - 30-day money-back guarantee, no questions asked
Privacy Policy - GDPR compliant, we protect your data

Quick Start

Installation

From PyPI (recommended):

pip install pyobfus

From source (for development):

git clone https://github.com/zhurong2020/pyobfus.git
cd pyobfus
pip install -e .

Basic Usage

# Obfuscate a single file
pyobfus input.py -o output.py

# Obfuscate a directory (cross-file mode - default in v0.2.0+)
pyobfus src/ -o dist/

# Preview obfuscation without writing files (v0.2.0+)
pyobfus src/ -o dist/ --dry-run

# Legacy single-file mode (v0.2.0+)
pyobfus src/ -o dist/ --no-cross-file

# With configuration file
pyobfus src/ -o dist/ --config pyobfus.yaml

# Preserve parameter names for keyword arguments (v0.1.6+)
pyobfus src/ -o dist/ --preserve-param-names

# Verbose output with progress indicators (v0.2.0+)
pyobfus src/ -o dist/ --verbose

Example

Before obfuscation:

def calculate_risk(age, score):
    """Calculate risk factor."""
    risk_factor = 0.1
    if score > 100:
        risk_factor = 0.5
    return age * risk_factor

patient_age = 55
patient_score = 150
risk = calculate_risk(patient_age, patient_score)
print(f"Risk score: {risk}")

After obfuscation:

def I0(I1, I2):
    I3 = 0.1
    if I2 > 100:
        I3 = 0.5
    return I1 * I3
I4 = 55
I5 = 150
I6 = I0(I4, I5)
print(f'Risk score: {I6}')

Note: Variable names (I0, I1, etc.) may vary slightly depending on code structure, but functionality is preserved.

Configuration

Quick Start with Templates

Generate a configuration template for your project type:

# For Django projects
pyobfus --init-config django

# For Flask projects
pyobfus --init-config flask

# For Python libraries
pyobfus --init-config library

# For general projects
pyobfus --init-config general

This creates a pyobfus.yaml file with sensible defaults for your project type.

Validate Configuration

Check your configuration file for errors before use:

pyobfus --validate-config pyobfus.yaml

The validator checks for:

YAML syntax errors
Invalid configuration options
Common typos (e.g., exclude_pattern -> exclude_patterns)
Pro features used with community level

Auto-Discovery

When you run pyobfus without -c, it automatically searches for:

pyobfus.yaml
pyobfus.yml
.pyobfus.yaml
.pyobfus.yml

Manual Configuration

Create pyobfus.yaml:

obfuscation:
  level: community
  exclude_patterns:
    - "test_*.py"
    - "**/tests/**"
    - "__init__.py"
  exclude_names:
    - "logger"
    - "config"
    - "main"
  remove_docstrings: true
  remove_comments: true

exclude_names Behavior

The exclude_names option preserves specified names from being renamed during obfuscation:

obfuscation:
  exclude_names:
    - MyPublicClass      # Name preserved, but strings inside are still encoded
    - exported_function  # Name preserved for external callers

Important: exclude_names only affects name obfuscation, not string encoding:

# Original
SECRET_KEY = "admin-password-123"

# With exclude_names: [SECRET_KEY] and string_encoding: true
SECRET_KEY = _decode_str('YWRtaW4tcGFzc3dvcmQtMTIz')
# ✅ Name 'SECRET_KEY' is preserved
# ✅ String content is still encoded (Base64)

Use cases:

Preserve names for public APIs that external code imports
Keep class/function names for debugging while still protecting string content
Maintain compatibility with external frameworks expecting specific names

File Filtering

Exclude patterns support glob syntax:

test_*.py - Exclude files starting with "test_"
**/tests/** - Exclude all files in "tests" directories
**/__init__.py - Exclude all __init__.py files
setup.py - Exclude specific files

See pyobfus.yaml.example for more configuration examples.

Architecture

pyobfus uses Python's ast module for syntax-aware transformations:

Parser: Parse Python source to AST
Analyzer: Build symbol table with scope analysis
Transformers: Apply obfuscation techniques (name mangling, string encoding, etc.)
Generator: Generate obfuscated Python code

This approach ensures:

Syntactically correct output
Proper handling of Python scoping rules
Support for modern Python features (f-strings, walrus operator, etc.)

Development

Setup

git clone https://github.com/zhurong2020/pyobfus.git
cd pyobfus
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -e ".[dev]"

Testing

# Run unit tests
pytest tests/ -v

# With coverage
pytest tests/ -v --cov=pyobfus --cov-report=html

# Run integration tests
pytest integration_tests/ -v

Integration Testing Framework (v0.1.6+): Test pyobfus on real-world code without uploading to PyPI. See INTEGRATION_TESTING.md for details.

Code Quality

# Format code
black pyobfus/

# Type checking
mypy pyobfus/

# Linting
ruff check pyobfus/

Use Cases

Protecting Proprietary Algorithms

Obfuscate sensitive business logic before distributing Python applications.

Educational Purposes

Demonstrate code protection concepts and obfuscation techniques.

Intellectual Property Protection

Add an additional layer of protection for commercial Python software.

Limitations

Current Limitations

Keyword Arguments (✅ Resolved in v0.1.6): By default, parameter names are obfuscated, which breaks keyword arguments. Solution: Use the --preserve-param-names flag to preserve parameter names while still obfuscating function bodies.
Example:
```
# Before obfuscation
def process(data_path, output_dir):
    temp_file = data_path + ".tmp"
    return temp_file

result = process(data_path='./data', output_dir='./output')  # ✅ Works

# After obfuscation (default behavior)
def I0(I1, I2):
    I3 = I1 + ".tmp"
    return I3

result = process(data_path='./data', output_dir='./output')  # ❌ TypeError!

# After obfuscation (with --preserve-param-names)
def I0(data_path, output_dir):
    I3 = data_path + ".tmp"
    return I3

result = I0(data_path='./data', output_dir='./output')  # ✅ Works!
```
When to use --preserve-param-names:
- Public API functions/libraries where keyword arguments are used by clients
- Functions with many parameters where keyword arguments improve readability
- Code that relies heavily on keyword-only arguments (def func(*, kwonly))
Trade-off: Parameter names reveal some information about the function's interface, but function bodies and local variables are still fully obfuscated.
Cross-file imports: ✅ Resolved in v0.2.0 with full cross-file obfuscation support
Dynamic code: eval(), exec() with obfuscated code may require adjustments
Debugging: Obfuscated code is harder to debug (by design)
Performance: Some obfuscation techniques may impact runtime performance

Recommendations

Test obfuscated code thoroughly before deployment
Keep original source in version control
Use configuration files for reproducible builds
For public APIs, use --preserve-param-names to maintain keyword argument compatibility
Consider combining with other protection methods (compilation, etc.)

Technical Details

Python Support: 3.8, 3.9, 3.10, 3.11, 3.12, 3.13, 3.14
Naming Scheme: Index-based (I0, I1, I2...) - simple and effective
Architecture: Modular transformer pipeline with two-phase cross-file obfuscation
Testing: 302 tests, 69% coverage, multi-OS CI/CD

Frequently Asked Questions

Is pyobfus Right for Me?

Use pyobfus if you:

Need to protect proprietary algorithms before distributing Python applications
Want a tool that "just works" without DLL conflicts or native dependencies
Prefer transparent pricing without hidden trial limitations
Support open-source software with optional paid features

How do I obfuscate Python code?

# Install
pip install pyobfus

# Obfuscate a single file
pyobfus script.py -o script_obf.py

# Obfuscate an entire project
pyobfus src/ -o dist/

# Preview without writing files
pyobfus src/ -o dist/ --dry-run

Will my code still work after obfuscation?

Yes, pyobfus guarantees 100% functional equivalence. The obfuscated code produces identical outputs to your original code. We use Python's AST (Abstract Syntax Tree) for syntax-aware transformations, ensuring syntactically correct output.

Does obfuscated code run slower?

Minimal impact:

Name mangling: Zero runtime cost (just renamed identifiers)
String encoding (Base64): ~0.1ms per string at startup
String encryption (AES-256, Pro): ~0.5ms per string at startup

Can I obfuscate Django/Flask projects?

Yes! Use our built-in templates:

# Django
pyobfus --init-config django

# Flask
pyobfus --init-config flask

# Then run obfuscation
pyobfus src/ -o dist/ -c pyobfus.yaml

What Python versions are supported?

pyobfus supports Python 3.8 through 3.14. Generated code is compatible with all these versions regardless of which version you use to run pyobfus.

PyArmor vs pyobfus: Which should I choose?

Feature	pyobfus	PyArmor
Price	$45 (Pro)	$89 (Pro)
Free tier	Clear limits (5 files/1000 LOC)	Vague "trial" limitations
Open source	Yes (Core: Apache 2.0, Pro: Proprietary)	No
Native dependencies	None (pure Python output)	Requires runtime library
Python 3.12 support	Yes	Yes

Choose pyobfus if: You want transparent pricing, open-source trust, and simpler deployment without native dependencies.

See our detailed comparison for more information.

What if obfuscation breaks my code?

Use --dry-run to preview changes before writing files
Use --preserve-param-names if you rely on keyword arguments
Add exclusions in pyobfus.yaml for names that must stay unchanged
Report issues on GitHub - we fix bugs quickly!

Can obfuscated code be reversed?

Name mangling is irreversible - original variable names cannot be recovered. However, code logic remains intact (this is true for all obfuscators). For stronger protection, use Pro features:

AES-256 encryption for strings
Anti-debugging checks to prevent analysis

Security Note: String Encryption Limitations

Important: String encryption (AES-256) is designed as a deterrent against casual reverse engineering, not as cryptographic security.

Because obfuscated code must decrypt strings at runtime, the encryption key is necessarily embedded in the output. A determined attacker with access to the obfuscated code can:

Locate the embedded key
Extract and decrypt all strings

This is a fundamental limitation of ALL client-side obfuscators (including PyArmor, Nuitka, etc.) - true cryptographic security would require server-side decryption, which is impractical for most use cases.

What string encryption DOES provide:

✅ Prevents casual strings or grep searches from revealing sensitive text
✅ Increases effort required for reverse engineering
✅ Deters non-technical users from extracting information
✅ Adds a layer of protection combined with other techniques

What string encryption does NOT provide:

❌ Protection against determined reverse engineers
❌ Cryptographic security for secrets (use environment variables or secret management instead)
❌ DRM-level protection

Recommendation: For sensitive credentials (API keys, passwords), use environment variables or external secret management systems rather than embedding them in code.

How is pyobfus different from Cython/Nuitka?

Tool	Approach	Output
pyobfus	AST transformation	`.py` files (pure Python)
Cython	Compile to C	`.so`/`.pyd` (platform-specific)
Nuitka	Compile to executable	Binary (platform-specific)

Choose pyobfus if: You need cross-platform .py files without compilation overhead.

Documentation

For Users

Installation & Quick Start - Get started in minutes
Configuration Guide - YAML configuration and file filtering
Examples - Working code examples demonstrating features
Use Cases - Real-world application scenarios

For Developers

Project Structure - Codebase architecture and development workflow
Contributing Guide - How to contribute code and documentation
Development Roadmap - Planned features and timeline
Changelog - Version history and release notes

Community & Support

GitHub Issues - Bug reports and feature requests
GitHub Discussions - Questions, ideas, and community help
Security Policy - How to report security vulnerabilities

Legal & License

Dual License Model:
- pyobfus (Core): Apache 2.0 - Free and open source
- pyobfus_pro (Pro): Proprietary - Requires paid license

Support the Project

If you find pyobfus helpful, consider supporting its development:

Buy Me A Coffee

Your support helps maintain and improve pyobfus. Thank you!

Acknowledgments

Inspired by Opy's AST-based approach
Clean room implementation - no code copying

Available Tools

8 tools

check_obfuscation_risksA

Scan a Python project for patterns that may break obfuscation (eval/exec, dynamic attribute access, framework reflection, unsafe model loading). Returns severity counts, detected frameworks (FastAPI/Django/Flask/Pydantic/Click/SQLAlchemy/ML), and a suggested preset. Also locates requirements*.txt / pyproject.toml and, only if verify_dependencies_online=true, checks each declared dependency against public PyPI to flag AI-hallucinated ('slopsquatting') package names -- off by default, this tool makes no outbound network calls unless you opt in.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`verify_dependencies_online`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden, and it does well by explicitly warning that the tool makes no outbound network calls unless verify_dependencies_online=true and that the dependency check is off by default. It also discloses the kinds of results and analysis performed. It does not explicitly state that it does not modify the project, but 'Scan' and the return-oriented language strongly imply a read-only operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but every clause earns its place: the scan subject, the checks performed, the outputs, and the network-call policy. The most important facts are front-loaded and the opt-in network caveat closes the description effectively without verbosity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers what the tool scans, what results it returns, where dependency files are found, and the optional network-check condition. Combined with the provided output schema and simple two-parameter input schema, nothing necessary for an agent to select and invoke the tool correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. The verify_dependencies_online parameter is clearly explained, including its default and network implications, while path is implied as the target Python project path. This is enough to call the tool correctly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Scan a Python project' and immediately lists concrete risk patterns (eval/exec, dynamic attribute access, framework reflection, unsafe model loading). It goes on to state the exact outputs and is clearly distinct from its siblings, which protect, generate configs, or handle stack traces rather than analyze obfuscation risk.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description makes clear this is a project-scanning/risk-assessment tool and explains when the optional dependency verification applies. It does not explicitly name alternatives or spell out when not to use it, but the context and sibling names make the intended use reasonably clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

explain_presetA

Describe what a named preset changes: exclude names count, exclude patterns, preserve_param_names, docstring handling. For Pro presets, returns full pro_unlock metadata (trial command, checkout URL, price, money-back guarantee).

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden of behavioral disclosure. It adds useful context by specifying that Pro presets return 'full pro_unlock metadata (trial command, checkout URL, price, money-back guarantee)', which goes beyond the bare tool name. It does not explicitly state read-only behavior, but the term 'explain' and the nature of the described outputs make non-mutation apparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no filler. The first sentence front-loads the primary purpose and key covered aspects, while the second adds a meaningful conditional detail about Pro presets. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the core purpose, key features, and special behavior for Pro presets, which is sufficient given a single simple parameter and the presence of an output schema. It could mention a usage workflow (e.g., 'use after list_presets') but is not incomplete without it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It implicitly identifies the sole 'name' parameter as a preset name through the phrase 'named preset' and adds meaning by distinguishing Pro presets. However, it does not provide explicit parameter documentation, such as example names or format, leaving some room for interpretation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Describe' and the resource 'a named preset', and lists specific aspects ('exclude names count, exclude patterns, preserve_param_names, docstring handling') that differentiate it from siblings like list_presets. It is immediately clear what this tool accomplishes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides enough context to infer the tool is used for explaining preset details, and the presence of list_presets implies an alternative for listing. However, there is no explicit 'when to use' or 'when not to use' guidance, nor a direct reference to sibling tools, leaving it to the agent to infer.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_pyobfus_configA

Generate a pyobfus.yaml for a Python project. Auto-detects frameworks and applies the matching preset. By default returns the YAML text without writing to disk; set write=true to persist.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`write`	No
`preset_override`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

It discloses that it auto-detects frameworks and the default vs. write behavior, which is important for a generation tool, though it doesn't specify error handling or file overwrite policy.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two concise sentences, front-loading the purpose and then providing key behavioral details without unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

While the description covers the main action and default behavior, it omits details on the 'preset_override' parameter and error scenarios, making it adequate but not thorough for a tool with auto-detection logic.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description only explains the 'write' parameter; 'path' and 'preset_override' are not described despite 0% schema coverage, leaving the agent unclear on expected values and semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool generates a pyobfus.yaml for a Python project, which is specific and distinguishes it from siblings like protect_project or recommend_tier.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains the default behavior (returns YAML text) and when to use the write parameter, but does not explicitly state when not to use it or alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_presetsA

List every pyobfus preset available, grouped by tier (community / framework-aware / Pro).

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the burden. It discloses the listing behavior and the grouping structure via 'grouped by tier'. The verb 'List' implies a read-only operation, and since an output schema exists, the return format need not be detailed further.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that front-loads the verb 'List' and directly states the scope and grouping. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool with no params and an output schema, the description fully answers what the tool does. It covers the listing and the grouping, and there are no preconditions or side effects to mention.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters, so schema coverage is trivially 100%. The description adds no parameter information because none is needed; the baseline for 0 params is 4, and there is nothing to compensate for.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists every pyobfus preset and groups them by tier (community / framework-aware / Pro). This is a specific verb+resource+scope, and it differentiates from siblings like explain_preset and recommend_tier.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the use case of discovering all available presets, which is clear enough from 'List every'. It does not explicitly name alternatives or exclusions, but the context of sibling tools (e.g., explain_preset) makes it obvious when this tool is the right choice.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

protect_projectA

One call to protect a Python project end-to-end AND verify it still works: scans risks, picks a framework-aware preset, obfuscates, then byte-compiles + import-smoke-tests the output in isolated subprocesses and returns verified:true/false. Writes a private de-obfuscation mapping alongside (not inside) the output. Use this when the user wants to 'protect/obfuscate before shipping' and expects a green check, not just a transform.

ParametersJSON Schema

Name	Required	Default
`path`	Yes
`preset`	No
`verify`	No
`timeout`	No
`output_dir`	No	dist
`verify_cmd`	No
`save_mapping`	No
`trace_marker`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It details the entire workflow: scans risks, picks a preset, obfuscates, byte-compiles, runs import-smoke-tests in isolated subprocesses, and returns verified:true/false. It also mentions writing a private de-obfuscation mapping alongside the output. It does not specify permissions or failure modes, which is a minor gap, but overall it provides substantial behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences long with no filler. The first sentence is a dense, front-loaded summary of the entire workflow. The second adds a key behavioral detail (mapping placement). The third provides concise usage guidance. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (8 params, 1 required, output schema present) and 0% schema coverage, the description covers the core workflow and usage well. It explains the main steps and expected outcome. It does not detail the output schema or all parameter behaviors, but the output schema likely handles return value documentation. Slight gap in parameter descriptions, but overall complete enough for an AI to determine appropriate invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate. It provides high-level context for some parameters (e.g., 'path' as project path, 'preset' as framework-aware, 'verify' as the verification step, 'save_mapping' for the mapping file), but it does not explicitly detail all 8 parameters. For example, 'timeout', 'output_dir', 'verify_cmd', and 'trace_marker' are only briefly implied. This is minimally adequate but not thorough.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'protect a Python project end-to-end AND verify it still works'. It distinguishes itself from sibling tools by emphasizing it is a combined protect+verify operation that 'returns verified:true/false', not just a transform. The context of sibling tools like check_obfuscation_risks and generate_pyobfus_config reinforces that this is a higher-level, end-to-end tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly advises when to use: 'Use this when the user wants to protect/obfuscate before shipping and expects a green check, not just a transform.' While it doesn't name specific alternatives, the sibling list implies that other tools are for more granular steps (e.g., risk scanning or preset generation). The guidance is clear but could be more explicit about when not to use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

recommend_tierB

Analyze a Python project and recommend pyobfus tier (community vs Pro) with reasons. Combines a preflight scan with a sensitive-string-literal heuristic. Returns free_action and pro_action with concrete next-step commands.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses it combines a preflight scan with a sensitive-string-literal heuristic and returns concrete actions. No annotations exist, so description carries the burden; it could mention if it modifies anything or prerequisites.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise sentences, front-loaded with purpose, method, and output. Efficient but could be more structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers purpose, method, and output types (free_action, pro_action), but lacks usage guidelines and parameter details. Adequate for a simple tool with one parameter.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The sole parameter 'path' has no description in the schema (0% coverage) and the tool description only implies it's the project path without explicit semantics or format details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it analyzes a Python project and recommends a tier (community vs Pro) with reasons, using a heuristic. However, it does not explicitly differentiate from sibling tools like check_obfuscation_risks.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies usage when a tier recommendation is needed, but no explicit when-not or alternatives to sibling tools are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

start_pro_trialA

Return structured guidance for starting the 5-day pyobfus Pro trial. Does NOT invoke the side effect — the user runs pyobfus-trial start in their shell. Detects whether a trial is already active and surfaces the appropriate next step plus post-trial purchase URL.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully conveys behavioral traits: it returns structured guidance, does not invoke side effects, detects active trials, and surfaces next steps plus purchase URL. This is transparent and leaves no ambiguity about what the tool does or does not do.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no wasted words. The first sentence states purpose and critical side-effect disclaimer; the second adds behavioral detail. Highly efficient and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given zero parameters, no annotations, and the presence of an output schema, the description is complete. It covers purpose, non-side-effect nature, detection capability, and what guidance is returned. No missing information for an agent to correctly select and invoke this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and schema coverage is 100%, so baseline is 4. The description does not need to add parameter information; it implicitly covers the lack of parameters by describing the tool's function without mentioning inputs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: return structured guidance for starting the 5-day Pro trial. It specifies the resource ('pyobfus Pro trial') and action ('return structured guidance'), and distinguishes itself from sibling tools by noting it does not invoke the side effect.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-use guidance: it is for guidance only, not for actual trial activation, as the user must run `pyobfus-trial start` in their shell. It also mentions detecting active trial status, which helps an agent decide whether to call this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

unmap_stack_traceA

Reverse obfuscated identifiers in a stack trace using a pyobfus mapping.json. Accepts the trace as plain text and the path to a mapping file produced by --save-mapping.

ParametersJSON Schema

Name	Required	Description	Default
`trace`	Yes
`mapping_path`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.8/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full burden for behavioral transparency. It does not disclose whether the tool is read-only, requires any permissions, has side effects, or error handling behavior. The description only states the action and inputs, leaving gaps about what happens internally or under failure conditions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, consisting of two sentences that deliver all necessary information without fluff. It is front-loaded with the action and efficiently explains inputs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has two simple parameters and an output schema, the description is fairly complete. It explains the purpose, inputs, and the origin of the mapping file. It could briefly mention what the output looks like (e.g., unmapped trace), but the output schema handles that. Overall, it provides sufficient context for a tool of this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description effectively compensates by naming both parameters and providing context: 'trace' is described as 'plain text', and 'mapping_path' is described as 'the path to a mapping file produced by --save-mapping.' This adds meaningful usage guidance beyond the bare schema titles.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Reverse obfuscated identifiers in a stack trace using a pyobfus mapping.json.' It specifies the verb (reverse), resource (stack trace), and method (mapping file), which distinguishes it from sibling tools like check_obfuscation_risks and generate_pyobfus_config.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by stating what it does and what inputs are needed (trace as plain text, mapping file path). However, it does not explicitly state when to use this tool versus alternatives, nor does it provide exclusions or when-not-to-use guidance. Given the sibling tools, usage context is implied but not explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

1 tool updatev0.5.14Aug 24, 2026
- Changedcheck_obfuscation_risks1 field changed
  - addedInput schema / properties / verify_dependencies_online
```
Added value: +{
+  "default": false,
+  "title": "Verify Dependencies Online",
+  "type": "boolean"
+}
```
2 tool updatesv0.5.7Aug 2, 2026
- Addedexplain_preset
- Addedlist_presets
2 tool updatesv0.5.6Jul 22, 2026
- Addedgenerate_pyobfus_config
- Removedlist_presets
2 tool updatesJul 22, 2026
- Removedexplain_preset
- Removedgenerate_pyobfus_config
1 tool updatev0.5.4Jul 7, 2026
- Addedprotect_project
2 tool updatesv0.4.1Jun 12, 2026
- Addedrecommend_tier
- Addedstart_pro_trial

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.9/5.0

Disambiguation4/5

Most tools have clearly distinct purposes, but check_obfuscation_risks and recommend_tier both analyze a project and could be confused, and generate_pyobfus_config overlaps slightly in framework detection. Detailed descriptions help disambiguate in most cases.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern with lowercase and underscores (e.g., protect_project, list_presets, explain_preset). There are no mixed conventions or vague verbs.

Tool Count5/5

Eight tools is well-scoped for a specialized server. Each tool serves a distinct role in the pyobfus workflow—scanning, configuring, protecting, explaining presets, unmapping traces, and trial guidance—without redundancy.

Completeness4/5

The tool set covers the core lifecycle: risk analysis, config generation, full protection with verification, preset exploration, stack trace unmapping, and trial guidance. However, it lacks a tool to apply a custom generated config directly, and has no standalone verification or mapping management tools, which are minor gaps.

Maintenance

ActivityActive

ResponsivenessWithin a week

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

Sentry AOAuth
dev.sentry.mcp
Enable secure connectivity between Sentry issues and debugging data, and LLM clients, using a Model Context Protocol (MCP) server.
Monitoring Developer Tools Observability
3
hithereiamaliff-mcp-nextcloudOAuth
ai.smithery
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Cloud Storage File Systems Workplace & Productivity
237
Apideck MCP A
dev.apideck.mcp
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
Developer Tools
42
mcp COAuth
com.wix
A Model Context Protocol server for Wix AI tools
Developer Tools Content Management Systems App Automation
216

Related MCP Servers

@kazuph/mcp-fetch
Browser Automation Image & Video Processing
kazuph
A
license
A
quality
C
maintenance
Model Context Protocol server for fetching web content and processing images. This allows Claude Desktop (or any MCP client) to fetch web content and handle images appropriately.
Updated 3 months ago (2026-06-12 13:45 UTC)
1
1,247
41
MIT
MCP Python Toolbox
Code Execution Developer Tools
gianlucamazza
A
license
Not graded
quality
C
maintenance
A Model Context Protocol server that enables AI assistants like Claude to perform Python development tasks through file operations, code analysis, project management, and safe code execution.
Updated 2 months ago (2026-07-14 06:19 UTC)
9
MIT
MCP Tools
Shell Access File Systems
ZbigniewTomanek
A
license
Not graded
quality
D
maintenance
A custom Model Context Protocol server that gives Claude Desktop and other LLMs access to file system operations and command execution capabilities through standardized tool interfaces.
Updated a year ago (2025-04-16 09:10 UTC)
23
Apache 2.0
OpenAI Agents MCP Server
Agent Orchestration Search RAG Systems
lroolle
F
license
B
quality
D
maintenance
A Model Context Protocol server that enables Claude users to access specialized OpenAI agents (web search, file search, computer actions) and a multi-agent orchestrator through the MCP protocol.
Updated a year ago (2025-03-14 16:23 UTC)
4
10
-

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/zhurong2020/pyobfus'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

pyobfus — the Python obfuscator

🔌 Companion MCP server: pyobfus-mcp

🤖 New in v0.4.0 — AI-native features

Features

✅ Free Edition

🔒 Pro Edition (Available Now)

Try Pro Features FREE

Purchase Professional Edition

How to Purchase

Legal & Policies

Quick Start

Installation

Basic Usage

Example

Configuration

Quick Start with Templates

Validate Configuration

Auto-Discovery

Manual Configuration

exclude_names Behavior

File Filtering

Architecture

Development

Setup

Testing

Code Quality

Use Cases

Protecting Proprietary Algorithms

Educational Purposes

Intellectual Property Protection

Limitations

Current Limitations

Recommendations

Technical Details

Frequently Asked Questions

Is pyobfus Right for Me?

How do I obfuscate Python code?

Will my code still work after obfuscation?

Does obfuscated code run slower?

Can I obfuscate Django/Flask projects?

What Python versions are supported?

PyArmor vs pyobfus: Which should I choose?

What if obfuscation breaks my code?

Can obfuscated code be reversed?

Security Note: String Encryption Limitations

How is pyobfus different from Cython/Nuitka?

Documentation

For Users

For Developers

Community & Support

Legal & License

Support the Project

Acknowledgments

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

🔌 Companion MCP server: `pyobfus-mcp`