Metadata-Version: 2.4
Name: mustel
Version: 0.3.4
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 <mustel.oss@gmail.com>, Raunak Nayak <mustel.oss@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

<p align="center">
  <a href="https://pypi.org/project/mustel/"><img src="https://img.shields.io/pypi/v/mustel.svg" alt="PyPI version"></a>
  <a href="https://pepy.tech/projects/mustel"><img src="https://static.pepy.tech/personalized-badge/mustel?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=BLUE&left_text=downloads" alt="PyPI Downloads"></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python 3.10+"></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
</p>

Mustel is a static analysis orchestrator designed for AI-assisted development environments (such as Cursor, Windsurf, or Claude Code). It coordinates Ruff, Bandit, Oxlint, Pip-Audit, and custom YAML patterns in parallel, operating in two modes:

*   **Dev Mode (Default)**: Executes only local, non-networked checks (Ruff, Oxlint, and custom rule patterns) during editor save loops. Version 0.3.0 introduces a stat-based (`mtime` + `size`) cache, reducing incremental scan latency from **300ms (in v0.2.0) to under 30ms (in v0.3.0)**, providing a **10x speed improvement** that allows real-time feedback.
*   **Audit Mode**: Triggered inside pre-commit hooks or CI/CD pipelines (when `CI`, `GITHUB_ACTIONS`, or `PRE_COMMIT` variables are present). Enables deep security scans (Bandit) and package audits (pip-audit) to prevent vulnerabilities from being committed.

### The Problem
When AI agents review or edit a codebase, they consume thousands of tokens reading full file contents simply to parse class and method relationships. Additionally, when they write code with syntax or import errors, developers must spend manual chat turns copying and pasting tracebacks to resolve them.

### The Solution
Mustel runs locally to provide:
*   **Repository Mapping**: Exposes a compressed, 1,500-token skeleton (`get_code_map`) of classes, functions, and docstrings so the agent learns your codebase structure without opening raw files.
*   **Save Guardrails**: Catches compile and syntax errors on file save, injecting an immediate `=== MUSTEL GUARDRAIL ALERT ===` block directly into the agent's tool output to enforce correction before user review.

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

---

## ⚡ Key Architecture & Design

### 1. Dual-Execution Modes (Zero Configuration)
Mustel switches its execution profile dynamically based on environmental indicators:
*   **Dev Mode (Default)**: Automatically triggered on editor save events and MCP reviews. Runs only local, non-networked checks (Ruff, Oxlint, local pattern files) and leverages a stat-based cache (checking file modification time and size) to keep incremental latency under 30ms.
*   **Audit Mode**: Triggered inside pre-commit hooks or CI/CD pipelines (when `CI`, `GITHUB_ACTIONS`, or `PRE_COMMIT` variables are present). Enables security checks (Bandit) and package dependency audits (pip-audit).

### 2. Repository Mapping (get_code_map)
Exposes codebase mapping tools via the `get_code_map` MCP tool and `mustel map` CLI command. It parses the project structures using AST parsing for Python/Jupyter and regex-based scanning for JS/TS, producing a highly compressed code skeleton (classes, method signatures, arguments, and docstrings) that fits under 1,500 tokens for average repositories, reducing initial context-loading token consumption by up to 95%.

### 3. Save Loop Guardrails
Mustel intercepts file save events via the editor. If syntax, compile, or import errors are found, it inserts a high-priority `=== MUSTEL GUARDRAIL ALERT ===` block in the tool output, directing the AI agent to resolve compiling issues in 1 turn before presenting the changes to the user.

### 4. Language & Environment Support
*   **Javascript & TypeScript**: Integrated `oxlint` engine to provide sub-millisecond JS/TS checks.
*   **Jupyter Notebooks**: Native parser that extracts Python code cells from `.ipynb` JSON models, running all custom rules against notebooks.
*   **Rule Sets**: Local YAML rule matching engine supporting standard libraries and data frameworks (`pandas`, `numpy`, `streamlit`, `google_cloud`, `azure`, and `boto3`).

### 5. Automated IDE Configuration (bootstrap)
Registers Mustel as a global MCP server across active user directories:
*   **Cursor**: `%USERPROFILE%\.cursor\mcp.json` (Windows) / `~/.cursor/mcp.json` (Mac/Linux)
*   **Windsurf**: `~/.codeium/windsurf/mcp_config.json`
*   **Claude Code**: `~/.claude.json`
*   **Claude Desktop**: OS-specific configuration directories

It also automatically appends required instructions to project `.cursorrules` / `.windsurfrules` and configures git pre-commit hooks.

---

## Quick Start

### Install

```bash
pip install mustel
```

### Configure

```bash
# Register MCP server globally across Cursor, Windsurf, and Claude
mustel bootstrap --global

# Configure local rules and install pre-commit hook in the current workspace
mustel bootstrap
```

### CLI Reference

```bash
# Run local incremental review (Dev Mode)
mustel review

# Force deep security and dependency audits (Audit Mode)
mustel review --audit

# Review a single target file
mustel review --file mustel/runner.py

# Print the repository codebase map
mustel map
```

---

## 🛠️ MCP Server Tools

Mustel runs an MCP server over stdio transport via `mustel serve`. The exposed tools are documented below:

| MCP Tool | Arguments | Output Type | Description |
| :--- | :--- | :--- | :--- |
| `review` | `path` (str), `skip_packages` (bool), `compact` (bool), `audit` (bool) | JSON | Concurrently scans files in the workspace. |
| `review_file` | `file_path` (str), `compact` (bool) | JSON + Text | Scans single file on save (triggers guardrails). |
| `get_code_map` | `path` (str) | Text | Returns a compact AST/regex codebase skeleton. |
| `env` | None | JSON | Returns a snapshot of the Python environment. |
| `bootstrap` | `global_install` (bool) | Text | Re-configures IDE settings and hook scripts. |

---

## 📂 Codebase Layout

```text
mustel/
├── mustel/
│   ├── cli.py         # CLI entrypoints (review, serve, bootstrap, map)
│   ├── runner.py      # Parallel execution engine and thread orchestrator
│   ├── cache.py       # Stat-based (mtime + size) file caching layer
│   ├── code_map.py    # AST & regex repository map generator
│   ├── normalizer.py  # Deduplication, formatting, and prompt serializer
│   ├── schema.py      # TypedDict specifications and compact serializers
│   ├── bootstrap.py   # IDE config injector and pre-commit hook installer
│   └── patterns/      # YAML rules and notebook loader
```

---

## 📄 License

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