# PAIML MCP Agent Toolkit (pmat)
[](https://crates.io/crates/pmat)
[](https://docs.rs/pmat)
[](https://github.com/paiml/paiml-mcp-agent-toolkit/actions/workflows/main.yml)
[](https://github.com/paiml/paiml-mcp-agent-toolkit/actions/workflows/quality-gate-test.yml)
[](https://modelcontextprotocol.io)
[](https://opensource.org/licenses/MIT)
[](https://crates.io/crates/pmat)
[](https://www.rust-lang.org)
**Zero-configuration AI context generation system** that analyzes any codebase instantly through CLI, MCP, or HTTP interfaces. Built by [Pragmatic AI Labs](https://paiml.com) with extreme quality standards and zero tolerance for technical debt.
> **Toyota Way Success**: Achieved 97% complexity reduction in stubs.rs through complete modular refactoring (v0.29.5). Project maintains zero tolerance standards: 0 SATD comments, 0 failing doctests, 0 failing property tests, 72+ comprehensive property tests, and proper separation of concerns across all components. Latest refactoring created dedicated modules (language_analyzer.rs, defect_formatter.rs, dead_code_formatter.rs) eliminating 549 lines of duplicated code while maintaining full functionality β
## π Installation
Install `pmat` using one of the following methods:
- **From Crates.io (Recommended):**
```bash
cargo install pmat
```
- **With the Quick Install Script (Linux only):**
```bash
curl -sSfL https://raw.githubusercontent.com/paiml/paiml-mcp-agent-toolkit/master/scripts/install.sh | sh
```
**macOS users:** Please use `cargo install pmat` instead. Pre-built binaries are only available for Linux.
- **From Source:**
```bash
git clone https://github.com/paiml/paiml-mcp-agent-toolkit
cd paiml-mcp-agent-toolkit
cargo build --release
```
- **From GitHub Releases:**
Pre-built binaries for Linux are available on the [releases page](https://github.com/paiml/paiml-mcp-agent-toolkit/releases). macOS and Windows users should use `cargo install pmat`.
### Requirements
- **Rust:** 1.80.0 or later
- **Git:** For repository analysis
## π Getting Started
### Quick Start
```bash
# Analyze current directory
pmat context
# Get complexity metrics for top 10 files
pmat analyze complexity --top-files 10
# Analyze specific files with include patterns
pmat analyze complexity --include "src/*.rs" --format json
# Test with validated examples (try these!)
cargo run --example complexity_demo
pmat analyze complexity --include "server/examples/complexity_*.rs"
# Find technical debt
pmat analyze satd
# Run comprehensive quality checks
pmat quality-gate --strict
```
### Using as a Library
Add to your `Cargo.toml`:
```toml
[dependencies]
pmat = "0.28.0"
```
Basic usage:
```rust
use pmat::{
services::code_analysis::CodeAnalysisService,
types::ProjectPath,
};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let service = CodeAnalysisService::new();
let path = ProjectPath::new(".");
// Generate context
let context = service.generate_context(path, None).await?;
println!("Project context: {}", context);
// Analyze complexity
let complexity = service.analyze_complexity(path, Some(10)).await?;
println!("Complexity results: {:?}", complexity);
Ok(())
}
```
## Key Features
### π Code Analysis
- **Deep Context Analysis** - Comprehensive AST-based code analysis with defect prediction
- **Complexity Analysis** - Accurate McCabe cyclomatic and cognitive complexity metrics with AST-based precision
- β
**v0.28.6+**: Fixed algorithm accuracy - now provides 100% correct complexity calculations
- Supports nested control flow, match statements, async functions, and complex branching
- Validated against manual calculations with comprehensive test examples
- **Dead Code Detection** - Find unused code across your project
- **Technical Debt Gradient (TDG)** - Quantify and prioritize technical debt
- **SATD Detection** - Find Self-Admitted Technical Debt in comments
- **Code Duplication** - Detect exact, renamed, gapped, and semantic clones
### π οΈ Refactoring Tools
- **AI-Powered Auto Refactoring** - `pmat refactor auto` achieves extreme quality standards
- **Single File Mode** - `pmat refactor auto --single-file-mode --file path/to/file.rs` for targeted refactoring
- **Documentation Cleanup** - `pmat refactor docs` maintains Zero Tolerance Quality Standards
- **Interactive Refactoring** - Step-by-step guided refactoring with explanations
- **Enforcement Mode** - Enforce extreme quality standards using state machines
- **Single File Mode** - `pmat enforce extreme --file path/to/file.rs` for file-specific enforcement
### π Quality Gates & CI/CD Integration
- **Lint Hotspot Analysis** - Find files with highest defect density using EXTREME Clippy standards
- **Single File Mode** - `pmat lint-hotspot --file path/to/file.rs` for targeted analysis
- **Provability Analysis** - Lightweight formal verification with property analysis
- **Defect Prediction** - ML-based prediction of defect-prone code
- **Quality Enforcement** - Exit with error codes for CI/CD integration
- **NEW**: All analyze commands now support `--fail-on-violation` for CI/CD pipelines
- Exit code 0 on success, 1 when violations exceed thresholds
- Perfect for GitHub Actions, GitLab CI, Jenkins, and other CI/CD systems
### π§ Language Support
- **Rust** - Full support with cargo integration
- **TypeScript/JavaScript** - Modern AST-based analysis
- **Python** - Comprehensive Python 3 support
- **Kotlin** - Memory-safe parsing with full language support
- **C/C++** - Tree-sitter based analysis
- **WebAssembly** - WASM binary and text format analysis
- **AssemblyScript** - TypeScript-like syntax for WebAssembly
- **Makefiles** - Specialized linting and analysis
## π Tool Usage
### CLI Interface
```bash
# Zero-configuration context generation
pmat context # Auto-detects language
pmat context --format json # JSON output
pmat context -t rust # Force toolchain
pmat context --skip-expensive-metrics # Fast mode
# Code analysis
pmat analyze complexity --top-files 5 # Complexity analysis
pmat analyze complexity --fail-on-violation # CI/CD mode - exit(1) if violations
pmat analyze churn --days 30 # Git history analysis
pmat analyze dag --target-nodes 25 # Dependency graph
pmat analyze dead-code --format json # Dead code detection
pmat analyze dead-code --fail-on-violation --max-percentage 10 # CI/CD mode
pmat analyze satd --top-files 10 # Technical debt
pmat analyze satd --strict --fail-on-violation # Zero tolerance for debt
pmat analyze deep-context --format json # Comprehensive analysis
pmat analyze deep-context --full # Full detailed report
pmat analyze deep-context --include-pattern "*.rs" # Filter by file pattern
pmat analyze big-o # Big-O complexity analysis
pmat analyze makefile-lint # Makefile quality linting
pmat analyze proof-annotations # Provability analysis
# Analysis commands
pmat analyze graph-metrics # Graph centrality metrics (PageRank, betweenness, closeness)
pmat analyze name-similarity "function_name" # Fuzzy name matching with phonetic support
pmat analyze symbol-table # Symbol extraction with cross-references
pmat analyze duplicates --min-lines 10 # Code duplication detection
pmat quality-gate --fail-on-violation # Comprehensive quality enforcement
pmat diagnose --verbose # Self-diagnostics and health checks
# WebAssembly Support
pmat analyze assemblyscript --wasm-complexity # AssemblyScript analysis with WASM metrics
pmat analyze webassembly --include-binary # WebAssembly binary and text format analysis
# Project scaffolding
pmat scaffold rust --templates makefile,readme,gitignore
pmat list # Available templates
# Refactoring engine
pmat refactor interactive # Interactive refactoring
pmat refactor serve --config refactor.json # Batch refactoring
pmat refactor status # Check refactor progress
pmat refactor resume # Resume from checkpoint
pmat refactor auto # AI-powered automatic refactoring
pmat refactor docs --dry-run # Clean up documentation
# Demo and visualization
pmat demo --format table # CLI demo
pmat demo --web --port 8080 # Web interface
pmat demo --repo https://github.com/user/repo # Analyze GitHub repo
# Quality enforcement
pmat quality-gate --fail-on-violation # CI/CD quality gate
pmat quality-gate --checks complexity,satd,security # Specific checks
pmat quality-gate --format human # Human-readable output
pmat enforce extreme # Enforce extreme quality standards
```
<details>
<summary><i>π« See CLI usage in action</i></summary>
<br>
<b>Context and code analysis:</b>
<img src="https://github.com/paiml/paiml-mcp-agent-toolkit/blob/master/assets/demo2.gif" width=875>
<br><br>
<b>Running demos/visualization:</b>
<img src="https://github.com/paiml/paiml-mcp-agent-toolkit/blob/master/assets/demo3.gif" width=875>
</details>
### MCP Integration
#### Using with Claude Code
```bash
# Add to Claude Code
claude mcp add pmat ~/.local/bin/pmat
```
<details>
<summary><i>π« See Claude Code usage in action</i></summary>
<br>
<img src="https://github.com/paiml/paiml-mcp-agent-toolkit/blob/master/assets/demo1.gif" width=875>
</details>
#### Using the pmcp Rust SDK (NEW)
The MCP server can now be run using the [pmcp](https://github.com/paiml/pmcp) Rust SDK for better type safety and async support:
```rust
// Run the MCP server with pmcp SDK
cargo run --example mcp_server_pmcp
// Or use as a library
use pmat::mcp_pmcp::{handlers::*, PmcpServer};
use pmcp::{Server, ServerBuilder};
let server = ServerBuilder::new("pmat-mcp", "1.0.0")
.with_tool("analyze_complexity", "Analyze code complexity",
Box::new(AnalyzeComplexityTool))
.with_tool("analyze_satd", "Detect technical debt",
Box::new(AnalyzeSatdTool))
// ... add more tools
.build();
// Handle connections
server.handle_connection(stream).await?;
```
The pmcp SDK provides:
- Type-safe tool definitions with proper async handling
- Built-in JSON-RPC 2.0 protocol implementation
- Automatic request/response serialization
- Connection lifecycle management
- Error handling and logging
Available MCP tools:
- `generate_template` - Generate project files from templates
- `scaffold_project` - Generate complete project structure
- `analyze_complexity` - Code complexity metrics **with tool composition**
- `analyze_code_churn` - Git history analysis
- `analyze_dag` - Dependency graph generation
- `analyze_dead_code` - Dead code detection
- `analyze_deep_context` - Comprehensive analysis **with tool composition**
- `generate_context` - Zero-config context generation
- `analyze_big_o` - Big-O complexity analysis with confidence scores
- `analyze_makefile_lint` - Lint Makefiles with 50+ quality rules
- `analyze_proof_annotations` - Lightweight formal verification
- `analyze_graph_metrics` - Graph centrality and PageRank analysis
- `refactor_interactive` - Interactive refactoring with explanations
#### π MCP Tool Composition (NEW)
AI agents can now chain analysis tools using the `--files` parameter:
```bash
# Step 1: Find complexity hotspots
pmat analyze complexity --top-files 5 --format json
# Step 2: Deep analyze those specific files (MCP composition)
pmat analyze comprehensive --files src/complex.rs,src/legacy.rs
# Step 3: Target refactoring on problematic files
pmat refactor auto --files src/complex.rs
```
**MCP Agent Workflow Example:**
```javascript
// AI agent discovers hotspots
const hotspots = await callTool("pmat_analyze_complexity", {
top_files: 5,
format: "json"
});
// Agent extracts file paths and performs deep analysis
const detailed = await callTool("pmat_analyze_comprehensive", {
files: hotspots.files.map(f => f.path)
});
// Agent generates targeted refactoring plan
const refactor = await callTool("pmat_refactor_auto", {
files: detailed.high_risk_files
});
```
### HTTP API
```bash
# Start server
pmat serve --port 8080 --cors
# API endpoints
curl "http://localhost:8080/health"
curl "http://localhost:8080/api/v1/analyze/complexity?top_files=5"
curl "http://localhost:8080/api/v1/templates"
# POST analysis
curl -X POST "http://localhost:8080/api/v1/analyze/deep-context" \
-H "Content-Type: application/json" \
-d '{"project_path":"./","include":["ast","complexity","churn"]}'
```
## π CI/CD Integration
All analyze commands now support `--fail-on-violation` for seamless CI/CD integration:
### GitHub Actions Example
```yaml
name: Code Quality
on: [push, pull_request]
jobs:
quality:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: dtolnay/rust-toolchain@stable
- name: Install pmat
run: cargo install pmat
- name: Check Complexity
run: |
pmat analyze complexity \
--max-cyclomatic 15 \
--max-cognitive 10 \
--fail-on-violation
- name: Check Technical Debt
run: pmat analyze satd --strict --fail-on-violation
- name: Check Dead Code
run: |
pmat analyze dead-code \
--max-percentage 10.0 \
--fail-on-violation
- name: Run Quality Gate
run: pmat quality-gate --fail-on-violation
```
### Configurable Thresholds
- **Complexity**: `--max-cyclomatic` (default: 20), `--max-cognitive` (default: 15)
- **Dead Code**: `--max-percentage` (default: 15.0%)
- **SATD**: Fails on ANY technical debt when using `--fail-on-violation`
### Exit Codes
- **0**: Success - no violations found or within thresholds
- **1**: Failure - violations exceed configured thresholds
See `examples/ci_integration.rs` for more CI/CD patterns including GitLab CI, Jenkins, and pre-commit hooks.
## Recent Updates
### π v0.29.6 - Critical Bug Fixes
- **Fixed Quality Gate Bug**: Quality gate dead code detection now correctly analyzes code instead of always reporting violations
- **Fixed Include Patterns**: `--include` patterns now properly work with test directories (e.g., `--include "tests/**/*.rs"`)
- **Fixed Clippy Warning**: Replaced deprecated `map_or` with `is_some_and` for cleaner code
### π v0.28.14 - Toyota Way Kaizen Success
- **Massive Complexity Reduction**: Core `handle_refactor_auto` function complexity reduced from 136 β 21 (84% reduction)
- **Zero Quality Violations**: Project now maintains 0 lint violations, 0 max complexity, 0 SATD comments
- **Toyota Way Implementation**: Applied Kaizen (continuous improvement), Genchi Genbutsu (go and see), Jidoka (quality at source), and Poka-Yoke (error-proofing) principles
- **Code Size Optimization**: Net reduction of 3,401 lines while improving functionality and maintainability
- **Comprehensive Testing**: Added extensive property tests, doctests, and unit tests for all refactored components
- **Zero Compromise**: No hacks, shortcuts, or technical debt introduced during refactoring
### π¦ v0.28.9 - CI/CD Integration & Exit Codes
- **CI/CD Support**: All analyze commands now support `--fail-on-violation` flag
- **Exit Codes**: Commands exit with code 1 when violations exceed thresholds
- **Configurable Thresholds**: Added `--max-percentage` for dead-code analysis
- **Examples**: Added comprehensive CI/CD examples for GitHub Actions, GitLab CI, Jenkins
- **Documentation**: Updated all documentation with CI/CD integration patterns
### π v0.28.3 - Enhanced Single-File Analysis
- **Single File Analysis**: Added `--file` flag to `pmat analyze comprehensive` for analyzing individual files.
- **Bug Fix**: Fixed "No such file or directory" error in single-file refactor mode by using dynamic executable path detection.
- **Test Improvements**: Fixed stack overflow issues in CLI tests by using wildcard pattern matching.
- **Documentation**: Updated CLI reference with new single-file analysis capabilities.
### π¦ v0.28.2 - Quality Gate Improvements
- **Quality Gate Tests**: Added comprehensive integration tests for CI/CD quality gates.
- **Public API**: Made quality gate structs public for better testing support.
- **Doctests**: Added doctests for quality gate and DAG generation functions.
- **Bug Fixes**: Fixed mermaid test failures and unused import warnings.
### π v0.26.3 - Quality Uplift
- **SATD Elimination**: Removed all TODO/FIXME/HACK comments from implementation.
- **Complexity Reduction**: All functions now below a cyclomatic complexity of 20.
- **Extreme Linting**: `make lint` passes with pedantic and nursery standards.
- **Single File Mode**: Enhanced support for targeted quality improvements.
### π§Ή v0.26.1 - Documentation Cleanup (`pmat refactor docs`)
- AI-assisted documentation cleanup to maintain Zero Tolerance Quality Standards.
- Identifies and removes temporary files, outdated reports, and build artifacts.
- Interactive mode for reviewing files before removal with automatic backups.
### π₯ v0.26.0 - New Analysis Commands
- **Graph Metrics**: `pmat analyze graph-metrics` for centrality analysis.
- **Name Similarity**: `pmat analyze name-similarity` for fuzzy name matching.
- **Symbol Table**: `pmat analyze symbol-table` for symbol extraction.
- **Code Duplication**: `pmat analyze duplicates` for detecting duplicate code.
## Toyota Way Quality Standards
This project exemplifies the Toyota Way philosophy through disciplined quality practices:
### **Kaizen (ζΉε) - Continuous Improvement**
- **84% Complexity Reduction**: Achieved through systematic refactoring
- **Zero Quality Violations**: Maintained through iterative improvement
- **Net -3,401 Lines**: Simplified while enhancing functionality
### **Genchi Genbutsu (ηΎε°ηΎη©) - Go and See**
- **Data-Driven Decisions**: Used actual metrics to identify complexity hotspots
- **Root Cause Analysis**: Fixed underlying architectural issues, not symptoms
- **Measurement-Based**: Every improvement verified through quantitative analysis
### **Jidoka (θͺεε) - Quality at Source**
- **ZERO SATD**: No TODO, FIXME, HACK, or placeholder implementations
- **ZERO High Complexity**: No function exceeds cyclomatic complexity of 20
- **ZERO Known Defects**: All code must be fully functional
- **ZERO Incomplete Features**: Only complete, tested features are merged
### **Poka-Yoke (γγ«γ¨γ±) - Error Prevention**
- **Comprehensive Testing**: Property tests, doctests, and unit tests prevent regressions
- **Automated Quality Gates**: CI/CD integration prevents quality degradation
- **Type Safety**: Rust's type system eliminates entire categories of errors
## π Output Formats
- **JSON** - Structured data for tools and APIs
- **Markdown** - Human-readable reports
- **SARIF** - Static analysis format for IDEs
- **Mermaid** - Dependency graphs and diagrams
## π― Use Cases
### For AI Agents
- **Context Generation**: Give AI perfect project understanding
- **Code Analysis**: Deterministic metrics and facts
- **Template Generation**: Scaffolding with best practices
### For Developers
- **Code Reviews**: Automated complexity and quality analysis
- **Technical Debt**: SATD detection and prioritization
- **Onboarding**: Quick project understanding
- **CI/CD**: Integrate quality gates and analysis
### For Teams
- **Documentation**: Auto-generated project overviews
- **Quality Gates**: Automated quality scoring
- **Dependency Analysis**: Visual dependency graphs
- **Project Health**: Comprehensive health metrics
## π¦ CI/CD Quality Gates
### GitHub Actions Integration
```yaml
# .github/workflows/quality.yml
- name: Run Quality Gate
run: |
pmat quality-gate \
--checks complexity,satd,security,dead-code \
--max-complexity-p99 20 \
--fail-on-violation
```
### Available Quality Checks
- **complexity** - Cyclomatic complexity thresholds
- **satd** - Self-admitted technical debt (TODO/FIXME/HACK)
- **security** - Hardcoded passwords and API keys
- **dead-code** - Unused functions and variables
- **entropy** - Code diversity metrics
- **duplicates** - Code duplication detection
- **coverage** - Test coverage thresholds
- **sections** - Required documentation sections
- **provability** - Formal verification readiness
## π Documentation
Explore our comprehensive documentation to get the most out of `pmat`.
### Getting Started
- **[Architecture](https://github.com/paiml/paiml-mcp-agent-toolkit/blob/master/docs/architecture/ARCHITECTURE.md)**: Understand the system design and principles.
- **[CLI Reference](https://github.com/paiml/paiml-mcp-agent-toolkit/blob/master/docs/cli-reference.md)**: View the full command-line interface guide.
- **[API Documentation](https://docs.rs/pmat)**: Browse the complete Rust API documentation on docs.rs.
### Usage Guides
- **[Feature Overview](https://github.com/paiml/paiml-mcp-agent-toolkit/blob/master/docs/features/README.md)**: Discover all available features.
- **[MCP Integration](https://github.com/paiml/paiml-mcp-agent-toolkit/blob/master/docs/features/mcp-protocol.md)**: Learn how to integrate `pmat` with AI agents.
- **[CI/CD Integration](https://github.com/paiml/paiml-mcp-agent-toolkit/blob/master/docs/integrations/ci-cd-integration.md)**: Set up quality gates in your CI/CD pipeline.
### Development
- **[Contributing Guide](https://github.com/paiml/paiml-mcp-agent-toolkit/blob/master/CONTRIBUTING.md)**: Read our guidelines for contributing to the project.
- **[Release Process](https://github.com/paiml/paiml-mcp-agent-toolkit/blob/master/docs/release-process.md)**: Follow our step-by-step release workflow.
## π οΈ System Operations
### Memory Management
For systems with low swap space, we provide a configuration tool:
```bash
make config-swap # Configure 8GB swap (requires sudo)
make clear-swap # Clear swap memory between heavy operations
```
## π§ͺ Testing
The project uses a distributed test architecture for fast feedback:
```bash
# Run specific test suites
make test-unit # <10s - Core logic tests
make test-services # <30s - Service integration
make test-protocols # <45s - Protocol validation
make test-e2e # <120s - Full system tests
make test-performance # Performance regression
# Run all tests in parallel
make test-all
# Coverage analysis
make coverage-stratified
```
## π€ Contributing
We welcome contributions! Please see our [Contributing Guide](https://github.com/paiml/paiml-mcp-agent-toolkit/blob/master/CONTRIBUTING.md) for details.
### Quick Start for Contributors
```bash
# Clone and setup
git clone https://github.com/paiml/paiml-mcp-agent-toolkit
cd paiml-mcp-agent-toolkit
# Install dependencies
make install-deps
# Run tests
make test-fast # Quick validation
make test-all # Complete test suite
# Check code quality
make lint # Run extreme quality lints
make coverage # Generate coverage report
```
### Development Workflow
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes following our Zero Tolerance Quality Standards
4. Run quality checks before committing:
```bash
make lint # Check code quality
make test # Run all tests (fast, doctests, property tests, examples)
```
5. Submit a pull request with a clear description of changes
**Note**: The `make test` command runs comprehensive testing including:
- β‘ Fast unit and integration tests
- π Documentation tests (doctests)
- π² Property-based tests
- π All cargo examples
See [CONTRIBUTING.md](https://github.com/paiml/paiml-mcp-agent-toolkit/blob/master/CONTRIBUTING.md) for detailed guidelines.
## π License
Licensed under either of:
- Apache License, Version 2.0 ([LICENSE-APACHE](https://github.com/paiml/paiml-mcp-agent-toolkit/blob/master/LICENSE-APACHE))
- MIT license ([LICENSE-MIT](https://github.com/paiml/paiml-mcp-agent-toolkit/blob/master/LICENSE-MIT))
at your option.
---
**Built with β€οΈ by [Pragmatic AI Labs](https://paiml.com)**