Metadata-Version: 2.4
Name: pyobfus-mcp
Version: 0.2.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<2.0.0,>=1.27.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.20.0; extra == "otel"
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "otel"
Requires-Dist: opentelemetry-exporter-otlp>=1.20.0; extra == "otel"

# pyobfus-mcp — Model Context Protocol server for pyobfus

<!-- mcp-name: io.github.zhurong2020/pyobfus-mcp -->

**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/
