pyobfus-mcp 0.1.0__tar.gz

pyobfus_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: pyobfus-mcp
+Version: 0.1.0
+Summary: Model Context Protocol server for pyobfus — the Python obfuscator. Lets Claude Desktop, Claude Code, Cursor, Windsurf, and Zed call pyobfus tools (preflight risk check, zero-config init, reverse stack-trace mapping) directly from an agent conversation.
+Author-email: Rong Zhu <zhurong0525@gmail.com>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/zhurong2020/pyobfus
+Project-URL: Repository, https://github.com/zhurong2020/pyobfus
+Project-URL: Main Package, https://pypi.org/project/pyobfus/
+Project-URL: AI Integration Guide, https://github.com/zhurong2020/pyobfus/blob/main/docs/AI_INTEGRATION_STRATEGY.md
+Project-URL: MCP Registry, https://github.com/modelcontextprotocol/servers
+Keywords: mcp,mcp-server,model-context-protocol,pyobfus,python-obfuscator,code-obfuscator,claude-code,claude-desktop,cursor,windsurf,zed,llm-tools,ai-agent,anthropic
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pyobfus>=0.4.0
+Requires-Dist: mcp>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+
+# pyobfus-mcp — Model Context Protocol server for pyobfus
+
+**pyobfus-mcp** exposes [pyobfus](https://github.com/zhurong2020/pyobfus) — the Python obfuscator — to any MCP-capable AI coding agent: **Claude Desktop, Claude Code, Cursor, Windsurf, Zed**, and anything else that speaks the [Model Context Protocol](https://modelcontextprotocol.io/).
+
+Once configured, you can say:
+
+> "Check if this FastAPI project is safe to obfuscate, then generate a pyobfus.yaml for it."
+
+and the agent will autonomously call `check_obfuscation_risks` and `generate_pyobfus_config` — no copy/paste of CLI commands, no manual config editing.
+
+## Tools exposed
+
+| Tool | What it does |
+|---|---|
+| `check_obfuscation_risks(path)` | Pre-flight scan for `eval`/`exec`, dynamic attribute access, framework reflection. Returns severity counts, detected frameworks, and a suggested preset. |
+| `generate_pyobfus_config(path, preset_override?, write?)` | Auto-detect framework → generate `pyobfus.yaml`. Returns the YAML text without writing by default; `write=True` persists to disk. |
+| `unmap_stack_trace(trace, mapping_path)` | Reverse obfuscated identifiers in a production stack trace using a `mapping.json`. |
+| `list_presets()` | Enumerate every preset (community / framework-aware / Pro). |
+| `explain_preset(name)` | Describe what a named preset changes: exclusions, docstring handling, parameter preservation. |
+
+All tools return dicts with a `status` field and an `ai_hint` field suggesting the next action.
+
+## Install
+
+```bash
+pip install pyobfus-mcp
+```
+
+This pulls `pyobfus` and the MCP Python SDK automatically.
+
+## Configure
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "pyobfus": {
+      "command": "pyobfus-mcp"
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The pyobfus tools appear in the tool list.
+
+### Cursor
+
+Edit `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "pyobfus": {
+      "command": "pyobfus-mcp"
+    }
+  }
+}
+```
+
+### Windsurf
+
+Edit `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "pyobfus": {
+      "command": "pyobfus-mcp"
+    }
+  }
+}
+```
+
+### Zed
+
+In `~/.config/zed/settings.json`:
+
+```json
+{
+  "context_servers": {
+    "pyobfus": {
+      "command": {
+        "path": "pyobfus-mcp",
+        "args": []
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add pyobfus pyobfus-mcp
+```
+
+## Example session
+
+```
+User:  Can you check whether this Python project is safe to obfuscate?
+       Path: /Users/me/code/my-api
+
+Agent: [invokes check_obfuscation_risks("/Users/me/code/my-api")]
+       I found 2 high-severity and 3 medium-severity patterns. FastAPI is
+       detected, so I'd suggest the `fastapi` preset. Want me to generate
+       the config?
+
+User:  Yes please, write it.
+
+Agent: [invokes generate_pyobfus_config("/Users/me/code/my-api",
+         preset_override="fastapi", write=True)]
+       Wrote pyobfus.yaml. Next: pyobfus /Users/me/code/my-api -o dist/
+       -c pyobfus.yaml
+```
+
+## Debugging obfuscated code with your AI assistant
+
+The killer feature: keep AI-assisted debugging even after you obfuscate.
+
+```
+User:  Here's a crash from prod. Can you help?
+       [pastes traceback full of I0, I1, I2...]
+
+Agent: [invokes unmap_stack_trace(trace, "path/to/mapping.json")]
+       Reversed. The crash is in Calculator.add() called from
+       main() — 'Calculator' object has no attribute 'add_x'. Looks like
+       a typo in the method call site…
+```
+
+## License
+
+Apache-2.0. Same as the main pyobfus package. The pyobfus Pro features remain license-gated; this MCP server only wraps the community-tier tools.
+
+## Links
+
+- **Main package**: https://pypi.org/project/pyobfus/
+- **Source**: https://github.com/zhurong2020/pyobfus
+- **AI integration strategy**: [docs/AI_INTEGRATION_STRATEGY.md](https://github.com/zhurong2020/pyobfus/blob/main/docs/AI_INTEGRATION_STRATEGY.md)
+- **MCP specification**: https://modelcontextprotocol.io/

pyobfus_mcp-0.1.0/README.md

@@ -0,0 +1,142 @@
+# pyobfus-mcp — Model Context Protocol server for pyobfus
+
+**pyobfus-mcp** exposes [pyobfus](https://github.com/zhurong2020/pyobfus) — the Python obfuscator — to any MCP-capable AI coding agent: **Claude Desktop, Claude Code, Cursor, Windsurf, Zed**, and anything else that speaks the [Model Context Protocol](https://modelcontextprotocol.io/).
+
+Once configured, you can say:
+
+> "Check if this FastAPI project is safe to obfuscate, then generate a pyobfus.yaml for it."
+
+and the agent will autonomously call `check_obfuscation_risks` and `generate_pyobfus_config` — no copy/paste of CLI commands, no manual config editing.
+
+## Tools exposed
+
+| Tool | What it does |
+|---|---|
+| `check_obfuscation_risks(path)` | Pre-flight scan for `eval`/`exec`, dynamic attribute access, framework reflection. Returns severity counts, detected frameworks, and a suggested preset. |
+| `generate_pyobfus_config(path, preset_override?, write?)` | Auto-detect framework → generate `pyobfus.yaml`. Returns the YAML text without writing by default; `write=True` persists to disk. |
+| `unmap_stack_trace(trace, mapping_path)` | Reverse obfuscated identifiers in a production stack trace using a `mapping.json`. |
+| `list_presets()` | Enumerate every preset (community / framework-aware / Pro). |
+| `explain_preset(name)` | Describe what a named preset changes: exclusions, docstring handling, parameter preservation. |
+
+All tools return dicts with a `status` field and an `ai_hint` field suggesting the next action.
+
+## Install
+
+```bash
+pip install pyobfus-mcp
+```
+
+This pulls `pyobfus` and the MCP Python SDK automatically.
+
+## Configure
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "pyobfus": {
+      "command": "pyobfus-mcp"
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The pyobfus tools appear in the tool list.
+
+### Cursor
+
+Edit `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "pyobfus": {
+      "command": "pyobfus-mcp"
+    }
+  }
+}
+```
+
+### Windsurf
+
+Edit `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "pyobfus": {
+      "command": "pyobfus-mcp"
+    }
+  }
+}
+```
+
+### Zed
+
+In `~/.config/zed/settings.json`:
+
+```json
+{
+  "context_servers": {
+    "pyobfus": {
+      "command": {
+        "path": "pyobfus-mcp",
+        "args": []
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add pyobfus pyobfus-mcp
+```
+
+## Example session
+
+```
+User:  Can you check whether this Python project is safe to obfuscate?
+       Path: /Users/me/code/my-api
+
+Agent: [invokes check_obfuscation_risks("/Users/me/code/my-api")]
+       I found 2 high-severity and 3 medium-severity patterns. FastAPI is
+       detected, so I'd suggest the `fastapi` preset. Want me to generate
+       the config?
+
+User:  Yes please, write it.
+
+Agent: [invokes generate_pyobfus_config("/Users/me/code/my-api",
+         preset_override="fastapi", write=True)]
+       Wrote pyobfus.yaml. Next: pyobfus /Users/me/code/my-api -o dist/
+       -c pyobfus.yaml
+```
+
+## Debugging obfuscated code with your AI assistant
+
+The killer feature: keep AI-assisted debugging even after you obfuscate.
+
+```
+User:  Here's a crash from prod. Can you help?
+       [pastes traceback full of I0, I1, I2...]
+
+Agent: [invokes unmap_stack_trace(trace, "path/to/mapping.json")]
+       Reversed. The crash is in Calculator.add() called from
+       main() — 'Calculator' object has no attribute 'add_x'. Looks like
+       a typo in the method call site…
+```
+
+## License
+
+Apache-2.0. Same as the main pyobfus package. The pyobfus Pro features remain license-gated; this MCP server only wraps the community-tier tools.
+
+## Links
+
+- **Main package**: https://pypi.org/project/pyobfus/
+- **Source**: https://github.com/zhurong2020/pyobfus
+- **AI integration strategy**: [docs/AI_INTEGRATION_STRATEGY.md](https://github.com/zhurong2020/pyobfus/blob/main/docs/AI_INTEGRATION_STRATEGY.md)
+- **MCP specification**: https://modelcontextprotocol.io/

pyobfus_mcp-0.1.0/pyobfus_mcp/__init__.py

@@ -0,0 +1,26 @@
+"""pyobfus-mcp — Model Context Protocol server for pyobfus.
+
+Exposes pyobfus's core AI-native tools (preflight check, project init,
+unmap, preset listing) to MCP-capable clients: Claude Desktop, Claude
+Code, Cursor, Windsurf, Zed, and anything else that speaks MCP.
+
+See README.md in this directory for install + configuration snippets.
+"""
+
+__version__ = "0.1.0"
+
+from pyobfus_mcp.tools import (
+    check_obfuscation_risks,
+    generate_pyobfus_config,
+    unmap_stack_trace,
+    list_presets,
+    explain_preset,
+)
+
+__all__ = [
+    "check_obfuscation_risks",
+    "generate_pyobfus_config",
+    "unmap_stack_trace",
+    "list_presets",
+    "explain_preset",
+]

pyobfus_mcp-0.1.0/pyobfus_mcp/server.py

@@ -0,0 +1,144 @@
+"""
+MCP server entry point for pyobfus.
+
+Uses the official Model Context Protocol Python SDK
+(https://github.com/modelcontextprotocol/python-sdk). Install with:
+
+    pip install pyobfus-mcp
+
+Registers the pyobfus tools as MCP tool handlers and runs over stdio
+(the transport used by Claude Desktop, Claude Code, Cursor, Windsurf,
+and Zed). The tool implementations are pure Python in
+`pyobfus_mcp.tools` and are independently testable — this module is
+just a thin adapter.
+
+Configure in Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`
+on macOS, `%APPDATA%\\Claude\\claude_desktop_config.json` on Windows):
+
+    {
+      "mcpServers": {
+        "pyobfus": {
+          "command": "pyobfus-mcp"
+        }
+      }
+    }
+
+Equivalent snippets for Cursor (`~/.cursor/mcp.json`), Windsurf, and
+Zed are in `pyobfus_mcp/README.md`.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Any, Dict, Optional
+
+from pyobfus_mcp import __version__
+from pyobfus_mcp.tools import (
+    check_obfuscation_risks,
+    explain_preset,
+    generate_pyobfus_config,
+    list_presets,
+    unmap_stack_trace,
+)
+
+
+def _build_server() -> Any:
+    """Construct and return the MCP Server instance.
+
+    Imported lazily so callers can `from pyobfus_mcp.server import main`
+    even if the `mcp` SDK isn't installed (e.g., during unit tests of
+    tools.py).
+    """
+    try:
+        from mcp.server.fastmcp import FastMCP  # type: ignore[import-not-found]
+    except ImportError as e:  # pragma: no cover — runtime-only
+        raise SystemExit(
+            "The 'mcp' package is required to run the pyobfus-mcp server.\n"
+            "Install it with: pip install mcp\n"
+            f"(Original error: {e})"
+        )
+
+    app = FastMCP(name="pyobfus", version=__version__)
+
+    # Each decorated function becomes a named MCP tool. Descriptions
+    # come from the docstring of the underlying tools.* function.
+    @app.tool(
+        name="check_obfuscation_risks",
+        description=(
+            "Scan a Python project for patterns that may break obfuscation "
+            "(eval/exec, dynamic attribute access, framework reflection). "
+            "Returns severity counts, detected frameworks (FastAPI/Django/"
+            "Flask/Pydantic/Click/SQLAlchemy), and a suggested preset."
+        ),
+    )
+    def _check(path: str) -> Dict[str, Any]:
+        return check_obfuscation_risks(path)
+
+    @app.tool(
+        name="generate_pyobfus_config",
+        description=(
+            "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."
+        ),
+    )
+    def _init(
+        path: str, preset_override: Optional[str] = None, write: bool = False
+    ) -> Dict[str, Any]:
+        return generate_pyobfus_config(path, preset_override=preset_override, write=write)
+
+    @app.tool(
+        name="unmap_stack_trace",
+        description=(
+            "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."
+        ),
+    )
+    def _unmap(trace: str, mapping_path: str) -> Dict[str, Any]:
+        return unmap_stack_trace(trace, mapping_path)
+
+    @app.tool(
+        name="list_presets",
+        description=(
+            "List every pyobfus preset available, grouped by tier "
+            "(community / framework-aware / Pro)."
+        ),
+    )
+    def _list() -> Dict[str, Any]:
+        return list_presets()
+
+    @app.tool(
+        name="explain_preset",
+        description=(
+            "Describe what a named preset changes: exclude names count, "
+            "exclude patterns, preserve_param_names, docstring handling."
+        ),
+    )
+    def _explain(name: str) -> Dict[str, Any]:
+        return explain_preset(name)
+
+    return app
+
+
+def main() -> None:
+    """Entry point invoked by the `pyobfus-mcp` console script."""
+    app = _build_server()
+    # FastMCP.run() defaults to stdio transport, which is what Claude
+    # Desktop / Cursor / Windsurf expect for locally-spawned servers.
+    app.run()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()
+
+
+# Backwards-compat export: some test harnesses look for a `tool_functions`
+# list. Provide one that enumerates the underlying callable implementations.
+tool_functions = [
+    check_obfuscation_risks,
+    generate_pyobfus_config,
+    unmap_stack_trace,
+    list_presets,
+    explain_preset,
+]

pyobfus_mcp-0.1.0/pyobfus_mcp/tools.py

@@ -0,0 +1,238 @@
+"""
+Pure-Python tool implementations for the pyobfus MCP server.
+
+These functions are deliberately MCP-SDK-agnostic: they accept primitive
+types, return dicts, and are independently testable without installing
+the `mcp` package. `server.py` wraps them as MCP tools; external callers
+(tests, CI, custom agent frameworks) can call them directly.
+
+All return dicts follow a stable shape with a `status` field
+("success" | "error") and an `ai_hint` field containing the single next
+command or action the calling agent should take.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+
+def check_obfuscation_risks(path: str) -> Dict[str, Any]:
+    """Scan a Python project for patterns that may break obfuscation.
+
+    Wraps `pyobfus --check`. Returns a structured report with severity
+    counts, detected frameworks, a suggested preset, and an `ai_hint`
+    telling the calling agent the exact command to run next.
+
+    Args:
+        path: Path to a Python file or directory to scan.
+
+    Returns:
+        Dict with keys: status, files_scanned, severity_counts,
+        frameworks, suggested_preset, suggested_excludes, risks,
+        ai_hint, exit_code.
+    """
+    try:
+        from pyobfus.core.preflight import PreflightChecker
+    except ImportError as e:
+        return _error("PyobfusNotInstalled", str(e), "pip install pyobfus")
+
+    target = Path(path)
+    if not target.exists():
+        return _error(
+            "PathNotFound",
+            f"Path does not exist: {path}",
+            f"Double-check the path and try again.",
+        )
+
+    report = PreflightChecker().check_path(target)
+    payload = report.to_dict()
+    payload["status"] = "success" if payload.get("exit_code", 0) == 0 else "warnings"
+    return payload
+
+
+def generate_pyobfus_config(
+    path: str, preset_override: Optional[str] = None, write: bool = False
+) -> Dict[str, Any]:
+    """Generate a pyobfus.yaml configuration for a Python project.
+
+    Wraps `pyobfus --init`. By default this returns the proposed YAML
+    *text* in the response without touching the filesystem, so an AI
+    agent can preview the config before asking the user whether to
+    write it. Set `write=True` to persist to disk at <path>/pyobfus.yaml.
+
+    Args:
+        path: Root of the Python project to scan.
+        preset_override: Optional preset name to force (safe, balanced,
+            aggressive, fastapi, django, flask, pydantic, click,
+            sqlalchemy). Default: auto-detected.
+        write: If True, writes the generated file to disk.
+
+    Returns:
+        Dict with keys: status, config_path, preset, excludes,
+        frameworks_detected, files_scanned, high_risk_findings, yaml,
+        written, ai_hint.
+    """
+    try:
+        from pyobfus.core.init_config import build_init_result
+    except ImportError as e:
+        return _error("PyobfusNotInstalled", str(e), "pip install pyobfus")
+
+    target = Path(path)
+    if not target.exists():
+        return _error(
+            "PathNotFound",
+            f"Path does not exist: {path}",
+            "Pass a valid project directory.",
+        )
+
+    result = build_init_result(target, preset_override=preset_override)
+
+    if write:
+        result.config_path.write_text(result.yaml_text, encoding="utf-8")
+        result.written = True
+
+    payload = result.to_dict()
+    payload["status"] = "success"
+    payload["yaml"] = result.yaml_text
+    payload["ai_hint"] = (
+        f"Review the YAML above. When ready, run "
+        f"'pyobfus {path} -o dist/ -c {result.config_path}'."
+        if not write
+        else f"Wrote {result.config_path}. Next: pyobfus {path} -o dist/ -c {result.config_path}"
+    )
+    return payload
+
+
+def unmap_stack_trace(trace: str, mapping_path: str) -> Dict[str, Any]:
+    """Reverse obfuscated identifiers in a stack trace using a mapping.json.
+
+    Wraps `pyobfus --unmap`. Accepts the trace as a literal string (most
+    useful for agent workflows where the trace is already in the chat
+    buffer); for large logs, callers can pre-read the file and pass
+    its contents.
+
+    Args:
+        trace: Obfuscated stack trace or error log as plain text.
+        mapping_path: Filesystem path to a mapping.json produced by
+            `pyobfus ... --save-mapping PATH`.
+
+    Returns:
+        Dict with keys: status, original_trace, unmapped_trace,
+        mapping_stats, ai_hint.
+    """
+    try:
+        from pyobfus.core.mapping import ObfuscationMapping
+    except ImportError as e:
+        return _error("PyobfusNotInstalled", str(e), "pip install pyobfus")
+
+    mp = Path(mapping_path)
+    if not mp.exists():
+        return _error(
+            "MappingNotFound",
+            f"Mapping file not found: {mapping_path}",
+            "Generate one with: pyobfus src/ -o dist/ --save-mapping mapping.json",
+        )
+
+    try:
+        mapping = ObfuscationMapping.load(mp)
+    except (ValueError, OSError) as e:
+        return _error("InvalidMapping", str(e), "Regenerate the mapping file.")
+
+    unmapped = mapping.unmap_text(trace)
+    return {
+        "status": "success",
+        "original_trace": trace,
+        "unmapped_trace": unmapped,
+        "mapping_stats": mapping.stats(),
+        "ai_hint": (
+            "Names are reversed, but line numbers still point to the obfuscated "
+            "file. Cross-reference with the original source if needed."
+        ),
+    }
+
+
+def list_presets() -> Dict[str, Any]:
+    """List every pyobfus preset available, grouped by tier.
+
+    Returns:
+        Dict with keys: status, community, framework, pro, ai_hint.
+    """
+    try:
+        from pyobfus.config import ObfuscationConfig
+    except ImportError as e:
+        return _error("PyobfusNotInstalled", str(e), "pip install pyobfus")
+
+    framework = sorted(ObfuscationConfig.FRAMEWORK_PRESETS)
+    all_presets = ObfuscationConfig.list_presets()
+    pro = {"trial", "commercial", "library", "maximum"}
+    community = [p for p in all_presets if p not in framework and p not in pro]
+
+    return {
+        "status": "success",
+        "community": community,
+        "framework": framework,
+        "pro": sorted(pro),
+        "ai_hint": (
+            "Framework presets are free and the recommended starting point "
+            "when your project imports fastapi/django/flask/pydantic/click/"
+            "sqlalchemy. Fall back to 'balanced' otherwise."
+        ),
+    }
+
+
+def explain_preset(name: str) -> Dict[str, Any]:
+    """Describe what a named preset changes compared to balanced.
+
+    Returns the concrete exclude_names count, preserve_param_names,
+    remove_docstrings flag, and any framework-specific exclude patterns
+    so an AI agent can explain the preset to the user before applying it.
+
+    Args:
+        name: Preset name (e.g. "fastapi", "pydantic", "safe").
+
+    Returns:
+        Dict with keys: status, preset, level, exclude_names_count,
+        exclude_patterns, preserve_param_names, remove_docstrings,
+        ai_hint.
+    """
+    try:
+        from pyobfus.config import ObfuscationConfig
+    except ImportError as e:
+        return _error("PyobfusNotInstalled", str(e), "pip install pyobfus")
+
+    try:
+        cfg = ObfuscationConfig.get_preset(name)
+    except ValueError as e:
+        return _error("UnknownPreset", str(e), "Call list_presets to see valid names.")
+
+    return {
+        "status": "success",
+        "preset": name.lower(),
+        "level": cfg.level,
+        "exclude_names_count": len(cfg.exclude_names),
+        "exclude_patterns": list(cfg.exclude_patterns),
+        "preserve_param_names": cfg.preserve_param_names,
+        "remove_docstrings": cfg.remove_docstrings,
+        "string_encoding": cfg.string_encoding,
+        "ai_hint": (
+            f"Apply with: pyobfus src/ -o dist/ --preset {name.lower()}"
+            if cfg.level == "community"
+            else f"'{name}' is a Pro preset. Start a free trial: pyobfus-trial start"
+        ),
+    }
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _error(error_type: str, message: str, ai_hint: str) -> Dict[str, Any]:
+    """Build a standard error payload matching the CLI `--json` error shape."""
+    return {
+        "status": "error",
+        "error_type": error_type,
+        "message": message,
+        "ai_hint": ai_hint,
+    }

pyobfus_mcp-0.1.0/pyobfus_mcp.egg-info/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: pyobfus-mcp
+Version: 0.1.0
+Summary: Model Context Protocol server for pyobfus — the Python obfuscator. Lets Claude Desktop, Claude Code, Cursor, Windsurf, and Zed call pyobfus tools (preflight risk check, zero-config init, reverse stack-trace mapping) directly from an agent conversation.
+Author-email: Rong Zhu <zhurong0525@gmail.com>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/zhurong2020/pyobfus
+Project-URL: Repository, https://github.com/zhurong2020/pyobfus
+Project-URL: Main Package, https://pypi.org/project/pyobfus/
+Project-URL: AI Integration Guide, https://github.com/zhurong2020/pyobfus/blob/main/docs/AI_INTEGRATION_STRATEGY.md
+Project-URL: MCP Registry, https://github.com/modelcontextprotocol/servers
+Keywords: mcp,mcp-server,model-context-protocol,pyobfus,python-obfuscator,code-obfuscator,claude-code,claude-desktop,cursor,windsurf,zed,llm-tools,ai-agent,anthropic
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pyobfus>=0.4.0
+Requires-Dist: mcp>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+
+# pyobfus-mcp — Model Context Protocol server for pyobfus
+
+**pyobfus-mcp** exposes [pyobfus](https://github.com/zhurong2020/pyobfus) — the Python obfuscator — to any MCP-capable AI coding agent: **Claude Desktop, Claude Code, Cursor, Windsurf, Zed**, and anything else that speaks the [Model Context Protocol](https://modelcontextprotocol.io/).
+
+Once configured, you can say:
+
+> "Check if this FastAPI project is safe to obfuscate, then generate a pyobfus.yaml for it."
+
+and the agent will autonomously call `check_obfuscation_risks` and `generate_pyobfus_config` — no copy/paste of CLI commands, no manual config editing.
+
+## Tools exposed
+
+| Tool | What it does |
+|---|---|
+| `check_obfuscation_risks(path)` | Pre-flight scan for `eval`/`exec`, dynamic attribute access, framework reflection. Returns severity counts, detected frameworks, and a suggested preset. |
+| `generate_pyobfus_config(path, preset_override?, write?)` | Auto-detect framework → generate `pyobfus.yaml`. Returns the YAML text without writing by default; `write=True` persists to disk. |
+| `unmap_stack_trace(trace, mapping_path)` | Reverse obfuscated identifiers in a production stack trace using a `mapping.json`. |
+| `list_presets()` | Enumerate every preset (community / framework-aware / Pro). |
+| `explain_preset(name)` | Describe what a named preset changes: exclusions, docstring handling, parameter preservation. |
+
+All tools return dicts with a `status` field and an `ai_hint` field suggesting the next action.
+
+## Install
+
+```bash
+pip install pyobfus-mcp
+```
+
+This pulls `pyobfus` and the MCP Python SDK automatically.
+
+## Configure
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "pyobfus": {
+      "command": "pyobfus-mcp"
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The pyobfus tools appear in the tool list.
+
+### Cursor
+
+Edit `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "pyobfus": {
+      "command": "pyobfus-mcp"
+    }
+  }
+}
+```
+
+### Windsurf
+
+Edit `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "pyobfus": {
+      "command": "pyobfus-mcp"
+    }
+  }
+}
+```
+
+### Zed
+
+In `~/.config/zed/settings.json`:
+
+```json
+{
+  "context_servers": {
+    "pyobfus": {
+      "command": {
+        "path": "pyobfus-mcp",
+        "args": []
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add pyobfus pyobfus-mcp
+```
+
+## Example session
+
+```
+User:  Can you check whether this Python project is safe to obfuscate?
+       Path: /Users/me/code/my-api
+
+Agent: [invokes check_obfuscation_risks("/Users/me/code/my-api")]
+       I found 2 high-severity and 3 medium-severity patterns. FastAPI is
+       detected, so I'd suggest the `fastapi` preset. Want me to generate
+       the config?
+
+User:  Yes please, write it.
+
+Agent: [invokes generate_pyobfus_config("/Users/me/code/my-api",
+         preset_override="fastapi", write=True)]
+       Wrote pyobfus.yaml. Next: pyobfus /Users/me/code/my-api -o dist/
+       -c pyobfus.yaml
+```
+
+## Debugging obfuscated code with your AI assistant
+
+The killer feature: keep AI-assisted debugging even after you obfuscate.
+
+```
+User:  Here's a crash from prod. Can you help?
+       [pastes traceback full of I0, I1, I2...]
+
+Agent: [invokes unmap_stack_trace(trace, "path/to/mapping.json")]
+       Reversed. The crash is in Calculator.add() called from
+       main() — 'Calculator' object has no attribute 'add_x'. Looks like
+       a typo in the method call site…
+```
+
+## License
+
+Apache-2.0. Same as the main pyobfus package. The pyobfus Pro features remain license-gated; this MCP server only wraps the community-tier tools.
+
+## Links
+
+- **Main package**: https://pypi.org/project/pyobfus/
+- **Source**: https://github.com/zhurong2020/pyobfus
+- **AI integration strategy**: [docs/AI_INTEGRATION_STRATEGY.md](https://github.com/zhurong2020/pyobfus/blob/main/docs/AI_INTEGRATION_STRATEGY.md)
+- **MCP specification**: https://modelcontextprotocol.io/

pyobfus_mcp-0.1.0/pyobfus_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+pyobfus_mcp/__init__.py
+pyobfus_mcp/server.py
+pyobfus_mcp/tools.py
+pyobfus_mcp.egg-info/PKG-INFO
+pyobfus_mcp.egg-info/SOURCES.txt
+pyobfus_mcp.egg-info/dependency_links.txt
+pyobfus_mcp.egg-info/entry_points.txt
+pyobfus_mcp.egg-info/requires.txt
+pyobfus_mcp.egg-info/top_level.txt
+tests/test_tools.py

pyobfus_mcp-0.1.0/pyobfus_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pyobfus_mcp-0.1.0/pyobfus_mcp.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pyobfus-mcp = pyobfus_mcp.server:main

pyobfus_mcp-0.1.0/pyobfus_mcp.egg-info/requires.txt

@@ -0,0 +1,6 @@
+pyobfus>=0.4.0
+mcp>=1.0.0
+
+[dev]
+pytest>=7.0
+pytest-cov>=4.0

pyobfus_mcp-0.1.0/pyobfus_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+pyobfus_mcp

pyobfus_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pyobfus-mcp"
+version = "0.1.0"
+description = "Model Context Protocol server for pyobfus — the Python obfuscator. Lets Claude Desktop, Claude Code, Cursor, Windsurf, and Zed call pyobfus tools (preflight risk check, zero-config init, reverse stack-trace mapping) directly from an agent conversation."
+readme = {file = "README.md", content-type = "text/markdown"}
+requires-python = ">=3.10"
+license = {text = "Apache-2.0"}
+authors = [
+    {name = "Rong Zhu", email = "zhurong0525@gmail.com"}
+]
+keywords = [
+    "mcp", "mcp-server", "model-context-protocol",
+    "pyobfus", "python-obfuscator", "code-obfuscator",
+    "claude-code", "claude-desktop", "cursor", "windsurf", "zed",
+    "llm-tools", "ai-agent", "anthropic",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Security",
+]
+
+dependencies = [
+    "pyobfus>=0.4.0",
+    "mcp>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/zhurong2020/pyobfus"
+Repository = "https://github.com/zhurong2020/pyobfus"
+"Main Package" = "https://pypi.org/project/pyobfus/"
+"AI Integration Guide" = "https://github.com/zhurong2020/pyobfus/blob/main/docs/AI_INTEGRATION_STRATEGY.md"
+"MCP Registry" = "https://github.com/modelcontextprotocol/servers"
+
+[project.scripts]
+pyobfus-mcp = "pyobfus_mcp.server:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["pyobfus_mcp*"]
+exclude = ["tests*"]

pyobfus_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pyobfus_mcp-0.1.0/tests/test_tools.py

@@ -0,0 +1,225 @@
+"""Tests for pyobfus_mcp.tools — the pure-Python tool implementations.
+
+These do NOT require the `mcp` SDK to be installed. They exercise the
+same functions that `server.py` wraps as MCP tool handlers.
+"""
+
+from __future__ import annotations
+
+import json
+import textwrap
+from pathlib import Path
+
+import yaml
+
+from pyobfus_mcp.tools import (
+    check_obfuscation_risks,
+    explain_preset,
+    generate_pyobfus_config,
+    list_presets,
+    unmap_stack_trace,
+)
+
+
+def _write(tmp_path: Path, name: str, src: str) -> Path:
+    p = tmp_path / name
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(textwrap.dedent(src).lstrip(), encoding="utf-8")
+    return p
+
+
+# ---------------------------------------------------------------------------
+# check_obfuscation_risks
+# ---------------------------------------------------------------------------
+
+
+def test_check_obfuscation_risks_clean_project(tmp_path: Path) -> None:
+    _write(tmp_path, "a.py", "def greet(name): return f'hi {name}'\n")
+    result = check_obfuscation_risks(str(tmp_path))
+    assert result["status"] == "success"
+    assert result["files_scanned"] == 1
+    assert result["exit_code"] == 0
+
+
+def test_check_obfuscation_risks_flags_eval(tmp_path: Path) -> None:
+    _write(tmp_path, "a.py", "eval('x+1')\n")
+    result = check_obfuscation_risks(str(tmp_path))
+    assert result["status"] == "warnings"
+    assert result["severity_counts"]["high"] >= 1
+    assert result["ai_hint"]
+
+
+def test_check_obfuscation_risks_detects_fastapi(tmp_path: Path) -> None:
+    _write(
+        tmp_path,
+        "api.py",
+        """
+        from fastapi import FastAPI
+        app = FastAPI()
+        """,
+    )
+    result = check_obfuscation_risks(str(tmp_path))
+    assert result["suggested_preset"] == "fastapi"
+    assert any(fw["name"] == "FastAPI" for fw in result["frameworks"])
+
+
+def test_check_obfuscation_risks_path_not_found() -> None:
+    result = check_obfuscation_risks("/nonexistent/path/xyz123")
+    assert result["status"] == "error"
+    assert result["error_type"] == "PathNotFound"
+
+
+# ---------------------------------------------------------------------------
+# generate_pyobfus_config
+# ---------------------------------------------------------------------------
+
+
+def test_generate_pyobfus_config_returns_yaml_without_writing(tmp_path: Path) -> None:
+    _write(
+        tmp_path,
+        "m.py",
+        """
+        from pydantic import BaseModel
+        class U(BaseModel): x: int
+        """,
+    )
+    result = generate_pyobfus_config(str(tmp_path))
+    assert result["status"] == "success"
+    assert result["preset"] == "pydantic"
+    assert result["written"] is False
+    assert "yaml" in result
+    # YAML content is parseable
+    parsed = yaml.safe_load(result["yaml"])
+    assert parsed["obfuscation"]["preset"] == "pydantic"
+    # No file written
+    assert not (tmp_path / "pyobfus.yaml").exists()
+
+
+def test_generate_pyobfus_config_writes_when_requested(tmp_path: Path) -> None:
+    _write(tmp_path, "a.py", "x = 1\n")
+    result = generate_pyobfus_config(str(tmp_path), write=True)
+    assert result["status"] == "success"
+    assert result["written"] is True
+    assert Path(result["config_path"]).exists()
+
+
+def test_generate_pyobfus_config_preset_override(tmp_path: Path) -> None:
+    _write(
+        tmp_path,
+        "api.py",
+        """
+        from fastapi import FastAPI
+        app = FastAPI()
+        """,
+    )
+    result = generate_pyobfus_config(str(tmp_path), preset_override="aggressive")
+    assert result["preset"] == "aggressive"
+
+
+def test_generate_pyobfus_config_path_not_found() -> None:
+    result = generate_pyobfus_config("/nonexistent/xyz")
+    assert result["status"] == "error"
+
+
+# ---------------------------------------------------------------------------
+# unmap_stack_trace
+# ---------------------------------------------------------------------------
+
+
+def test_unmap_stack_trace_roundtrip(tmp_path: Path) -> None:
+    mapping_path = tmp_path / "m.json"
+    mapping_path.write_text(
+        json.dumps(
+            {
+                "version": 1,
+                "modules": {"calc": {"Calculator": "I0", "add": "I1"}},
+                "global": {
+                    "I0": {"module": "calc", "original": "Calculator"},
+                    "I1": {"module": "calc", "original": "add"},
+                },
+            }
+        ),
+        encoding="utf-8",
+    )
+    trace = "AttributeError: 'I0' object has no attribute 'I1'"
+    result = unmap_stack_trace(trace, str(mapping_path))
+    assert result["status"] == "success"
+    assert result["unmapped_trace"] == (
+        "AttributeError: 'Calculator' object has no attribute 'add'"
+    )
+    assert result["mapping_stats"]["unique_obfuscated"] == 2
+
+
+def test_unmap_stack_trace_missing_mapping() -> None:
+    result = unmap_stack_trace("foo", "/does/not/exist.json")
+    assert result["status"] == "error"
+    assert result["error_type"] == "MappingNotFound"
+
+
+def test_unmap_stack_trace_invalid_mapping(tmp_path: Path) -> None:
+    bad = tmp_path / "bad.json"
+    bad.write_text(json.dumps({"version": 999}), encoding="utf-8")
+    result = unmap_stack_trace("foo", str(bad))
+    assert result["status"] == "error"
+    assert result["error_type"] == "InvalidMapping"
+
+
+# ---------------------------------------------------------------------------
+# list_presets + explain_preset
+# ---------------------------------------------------------------------------
+
+
+def test_list_presets_groups_correctly() -> None:
+    result = list_presets()
+    assert result["status"] == "success"
+    # Community (non-framework, non-pro)
+    for p in ("safe", "balanced", "aggressive"):
+        assert p in result["community"]
+    # Framework
+    for p in ("fastapi", "django", "flask", "pydantic", "click", "sqlalchemy"):
+        assert p in result["framework"]
+    # Pro
+    for p in ("trial", "commercial", "library", "maximum"):
+        assert p in result["pro"]
+
+
+def test_explain_preset_community() -> None:
+    result = explain_preset("fastapi")
+    assert result["status"] == "success"
+    assert result["preset"] == "fastapi"
+    assert result["level"] == "community"
+    assert result["preserve_param_names"] is True
+    assert result["exclude_names_count"] > 0
+    assert "--preset fastapi" in result["ai_hint"]
+
+
+def test_explain_preset_pro_mentions_trial() -> None:
+    result = explain_preset("commercial")
+    assert result["status"] == "success"
+    assert result["level"] == "pro"
+    assert "trial" in result["ai_hint"].lower()
+
+
+def test_explain_preset_unknown() -> None:
+    result = explain_preset("totally_made_up")
+    assert result["status"] == "error"
+    assert result["error_type"] == "UnknownPreset"
+
+
+# ---------------------------------------------------------------------------
+# Server module is importable without the mcp SDK
+# ---------------------------------------------------------------------------
+
+
+def test_server_module_importable_without_mcp_sdk() -> None:
+    """`pyobfus_mcp.server` must import cleanly even if `mcp` is missing.
+
+    The SDK import happens lazily inside `_build_server()` so tests of
+    tools.py don't require the SDK. This protects the test suite from
+    breaking when the package is not installed in a test env.
+    """
+    import pyobfus_mcp.server as srv
+
+    # tool_functions export is independent of the SDK
+    assert srv.tool_functions
+    assert all(callable(fn) for fn in srv.tool_functions)