Metadata-Version: 2.4
Name: mustel
Version: 0.3.0
Summary: Non-AI static analysis layer for AI IDEs and coding agents - bug detection, security scanning, and CVE checking via MCP
Project-URL: Homepage, https://mustel.netlify.app
Project-URL: Documentation, https://mustel.netlify.app
Project-URL: Repository, https://github.com/mustel-py/mustel
Project-URL: Issues, https://github.com/mustel-py/mustel/issues
Project-URL: Changelog, https://github.com/mustel-py/mustel/blob/main/CHANGELOG.md
Author-email: Ameya Kulkarni <acclaptop47@gmail.com>, Raunak Nayak <acclaptop47@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Ameya Kulkarni, Raunak Nayak
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: ai-agent,ai-coding,bandit,bug-detection,claude,code-review,cursor,devtools,ide,linter,mcp,mcp-server,pip-audit,python,ruff,security,static-analysis,vulnerability-scanner,windsurf
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
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: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: bandit>=1.7.0
Requires-Dist: click>=8.0.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pip-audit>=2.6.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: ruff>=0.4.0
Requires-Dist: watchdog>=3.0.0
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: twine>=4.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# mustel (0.3.0)

**The Agent-Native Linter & Guardrail for AI IDEs and Coding Agents.**

mustel is a high-speed, zero-config static analysis and context layer built specifically to make AI coding agents (Cursor, Windsurf, Claude Code, Claude Desktop) cheaper, faster, and hallucination-free. 

By integrating locally into your file save loops and git hooks, mustel gives AI agents deterministic ground truth and API structures in token-optimized formats.

```text
Your Code -> mustel (Dev/Audit) -> Token-Saved JSON/Text -> AI Agent -> Instant Fixes
```

[![PyPI version](https://img.shields.io/pypi/v/mustel.svg)](https://pypi.org/project/mustel/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## ⚡ Key Innovations in v0.3.0

### 1. Adaptive Execution Modes (Zero CLI Config)
*   **Dev Mode (Default)**: Automatically triggered on editor file saves or MCP reviews. Runs only local checks (Ruff, Oxlint, custom patterns) and skips all network operations/npm registry calls. Latency is **< 30ms** via stat-based file caching (`mtime` + `size`).
*   **Audit Mode**: Triggered automatically in Git hooks (`pre-commit`) or CI pipelines (detecting `CI` or `GITHUB_ACTIONS`). Runs deep security (Bandit) and package vulnerability scans (pip-audit).

### 2. Repository Mapping (`get_code_map` / `mustel map`)
A dedicated tool that serves a compact, token-dense skeleton (classes, method signatures, arguments, and docstrings) of your codebase. Instead of the AI reading raw source code files to understand your repository (which costs 10,000+ tokens), it reads the map once (**saving up to 95% input tokens**).

### 3. Save Loop Guardrails
On file saves, the editor triggers `review_file`. mustel instantly scans the code for syntax or import errors. If found, it appends a high-priority `=== MUSTEL GUARDRAIL ALERT ===` block in the tool output, directing the AI agent to resolve compile/syntax errors in 1 turn before notifying the user.

### 4. Multi-Language & Jupyter Support
*   **JS/TS Support**: Integrated `oxlint` engine for lightning-fast frontend checking.
*   **Jupyter Notebooks (`.ipynb`)**: Extract and parse code cells JSON, running all custom Python patterns against data science notebooks.
*   **Cloud & Data Science Rule Sets**: Added optimized patterns for `pandas`, `numpy`, `streamlit`, `google_cloud`, `azure`, and `boto3`.

### 5. Zero-Config Global IDE Bootstrapping
When first run (or via `mustel bootstrap`), mustel automatically registers its MCP server globally across:
*   **Cursor**: `%USERPROFILE%\.cursor\mcp.json`
*   **Windsurf**: `~/.codeium/windsurf/mcp_config.json`
*   **Claude Code**: `~/.claude.json`
*   **Claude Desktop**: OS-specific AppData configs
It also automatically injects guardrail rules into `.cursorrules` / `.windsurfrules` and installs git pre-commit hooks.

---

## 🚀 Quick Start

### Install

```bash
pip install mustel
```

### Auto-Configure (Bootstrap)

```bash
mustel bootstrap          # Setup current project local rules and git hooks
mustel bootstrap --global # Register MCP server globally across Cursor, Windsurf, Claude
```

### Scan Your Project

```bash
mustel review             # Runs Dev Mode (fast incremental lint)
mustel review --audit     # Force deep security/CVE Audit Mode
mustel review --file x.py # Scan a single file
mustel map                # Print the codebase skeleton mapping (Text)
```

---

## 🛠️ MCP Server Tools

AI IDEs connect via stdio transport using `mustel serve`. The server exposes these tools:

| MCP Tool | Arguments | Output | Description |
| :--- | :--- | :--- | :--- |
| `review` | `path`, `skip_packages`, `compact`, `audit` | Compact JSON | Concurrently scans workspace files. |
| `review_file` | `file_path`, `compact` | JSON + Alert | Local scan for active save loops (triggers guardrails). |
| `get_code_map` | `path` | Tree Text | Compact AST/regex code mapping skeleton. |
| `env` | - | JSON | Current Python environment snapshot. |
| `bootstrap` | `global_install` | Text | Re-configures IDE settings and hooks. |

---

## 📊 Empirical Benchmarks

Tested on real open-source targets (`requests`, `click`, `watchdog`, `bandit`, `mcp`):

*   **Recall**: **100%** on standard vulnerability checks.
*   **Incremental Latency**: **26 - 32 ms** for typical projects; **79 - 114 ms** for repos with 100+ files.
*   **Token Overhead**: Compressed `agent_prompt` summary fits under **191 characters** (under 50 tokens).
*   **Token Reduction**: **34.4% net savings** in AI-agent review workflows (empirical tiktoken measurement).

---

## 📂 Codebase Layout

```text
mustel/
├── mustel/
│   ├── cli.py         # CLI entrypoints (review, serve, bootstrap, map)
│   ├── runner.py      # ThreadPool-parallel orchestrator with caching checks
│   ├── cache.py       # Stat-based (mtime + size) high-speed cache
│   ├── code_map.py    # AST & regex repository map generator
│   ├── normalizer.py  # Deduplicates findings, assigns IDs, generates prompts
│   ├── schema.py      # TypedDict specifications and compact serializers
│   ├── bootstrap.py   # Global IDE config injector & git hook installer
│   └── patterns/      # YAML rules for 22 Python libraries & ipynb extraction
```

---

## 📄 License

MIT License - Copyright (c) 2026 Ameya K, Raunak N. See [LICENSE](LICENSE) for details.