https://github.com/paiml/paiml-mcp-agent-toolkit
Pragmatic AI Labs MCP Agent Toolkit - An MCP Server designed to make code with agents more deterministic
https://github.com/paiml/paiml-mcp-agent-toolkit
Last synced: 5 months ago
JSON representation
Pragmatic AI Labs MCP Agent Toolkit - An MCP Server designed to make code with agents more deterministic
- Host: GitHub
- URL: https://github.com/paiml/paiml-mcp-agent-toolkit
- Owner: paiml
- Created: 2025-05-25T18:34:04.000Z (6 months ago)
- Default Branch: master
- Last Pushed: 2025-07-01T18:42:25.000Z (5 months ago)
- Last Synced: 2025-07-01T19:20:24.822Z (5 months ago)
- Language: Rust
- Size: 45.6 MB
- Stars: 36
- Watchers: 0
- Forks: 6
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
Awesome Lists containing this project
- awesome-mcp-servers - **paiml-mcp-agent-toolkit** - Pragmatic AI Labs MCP Agent Toolkit - An MCP Server designed to make code with agents more deterministic `rust` `agentic` `c` `deno` `kotlin` `cargo install --git https://github.com/paiml/paiml-mcp-agent-toolkit` (🤖 AI/ML)
README
# 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://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.
> **Latest Quality Improvements**: All clippy lint issues resolved, property tests enhanced, and code quality checks now pass ✅
## 🚀 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> {
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
- **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
### 🔧 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 rust # Force language
# Code analysis
pmat analyze complexity --top-files 5 # Complexity analysis
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 satd --top-files 10 # Technical debt
pmat analyze deep-context --format json # Comprehensive analysis
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 --strict # 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
```
💫 See CLI usage in action
Context and code analysis:
Running demos/visualization:
### MCP Integration (Claude Code)
```bash
# Add to Claude Code
claude mcp add pmat ~/.local/bin/pmat
```
💫 See Claude Code usage in action
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"]}'
```
## Recent Updates
### 🔍 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.
## Zero Tolerance Quality Standards
This project follows strict quality standards:
- **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
## 📊 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 `make lint` and `make test-fast` before committing
5. Submit a pull request with a clear description of changes
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)**