paiml-mcp-agent-toolkit

paiml-mcp-agent-toolkit

Pragmatic AI Labs MCP Agent Toolkit - An MCP Server designed to make code with agents more deterministic

Stars: 79

Visit
 screenshot

PAIML MCP Agent Toolkit (PMAT) is a zero-configuration AI context generation system with extreme quality enforcement and Toyota Way standards. It allows users to analyze any codebase instantly through CLI, MCP, or HTTP interfaces. The toolkit provides features such as technical debt analysis, advanced monitoring, metrics aggregation, performance profiling, bottleneck detection, alert system, multi-format export, storage flexibility, and more. It also offers AI-powered intelligence for smart recommendations, polyglot analysis, repository showcase, and integration points. PMAT enforces quality standards like complexity โ‰ค20, zero SATD comments, test coverage >80%, no lint warnings, and synchronized documentation with commits. The toolkit follows Toyota Way development principles for iterative improvement, direct AST traversal, automated quality gates, and zero SATD policy.

README:

PAIML MCP Agent Toolkit (pmat)

Crates.io npm Docker Homebrew AUR Chocolatey

Documentation CI/CD Quality Gate Multi-Ecosystem Release

MCP Compatible License: MIT Downloads Rust 1.80+

Zero-configuration AI context generation system with extreme quality enforcement and Toyota Way standards. Analyze any codebase instantly through CLI, MCP, or HTTP interfaces. Built by Pragmatic AI Labs.

๐ŸŽฏ v2.63.0 Release: Advanced Code Similarity Detection System! Industry-leading duplicate and similarity detection:

  • ๐Ÿ” 4 Clone Types: Exact (Type-1), Renamed (Type-2), Modified (Type-3), Semantic (Type-4) detection
  • ๐Ÿ“Š Entropy Analysis: Shannon entropy for complexity measurement and pattern detection
  • ๐Ÿงฎ Advanced Algorithms: Winnowing, TF-IDF, Cosine Similarity, Jaccard Index, Levenshtein Distance
  • ๐Ÿ“„ Multi-Format Output: JSON, Markdown, CSV, SARIF, and Summary formats
  • ๐Ÿš€ Performance: Optimized for 100K+ LOC with parallel processing
  • ๐Ÿ”ง Full Integration: CLI commands, MCP tools, and comprehensive examples

๐Ÿš€ v2.39.0 Release: TDG System with MCP Integration & Advanced Monitoring! Production-ready technical debt analysis:

  • ๐ŸŒ Web Dashboard: Real-time monitoring with Axum-based interface and Server-Sent Events
  • ๐Ÿ› ๏ธ 6 MCP Tools: Enterprise-grade external integration (tdg_analyze_with_storage, tdg_system_diagnostics, etc.)
  • ๐Ÿ“Š Advanced Analytics: Metrics aggregation, performance profiling, bottleneck detection
  • ๐Ÿšจ Alert System: Configurable thresholds with multi-channel notifications
  • ๐Ÿ“ค Multi-format Export: JSON, CSV, SARIF, HTML, Markdown, XML, Prometheus support
  • ๐Ÿ’พ Storage Flexibility: Pluggable backends (Sled, RocksDB, InMemory) with trait abstraction

๐Ÿ”ง v2.14.0 Release: Technical Debt Elimination via TDD! Major fixes using Test-Driven Development:

  • โœ… Language Detection Fixed: Functions now properly detected (was 0, now detects all)
  • ๐Ÿšซ Zero Stub Implementations: All stub code eliminated with real implementations
  • ๐Ÿ“‰ Complexity Reduced: Ruchy parser from 89 to โ‰ค4 cyclomatic complexity (95% reduction)
  • ๐Ÿงช TDD Coverage: 80%+ test coverage on critical language detection paths
  • ๐Ÿญ Toyota Way Applied: ONE implementation principle, zero defect tolerance

๐ŸŽฏ v2.13.0: Technical Debt Grading (TDG) System! Complete code quality scoring with 6 orthogonal metrics:

  • ๐Ÿ“Š Comprehensive Scoring: Structural complexity, semantic complexity, code duplication, coupling analysis
  • ๐Ÿ“š Documentation Coverage: Language-specific documentation pattern detection and scoring
  • ๐ŸŽจ Consistency Analysis: Naming conventions, indentation patterns, and code style consistency
  • ๐Ÿ† Grade Classification: A+ through F grading system with detailed component breakdowns
  • ๐ŸŒ Multi-Language Support: 10+ languages including Rust, Python, JavaScript, TypeScript, Go, Java, C/C++
  • ๐Ÿ› ๏ธ CLI & MCP Integration: pmat analyze tdg command and MCP tools for programmatic access
  • ๐Ÿ“ˆ Project Analysis: Directory-level analysis with language distribution and aggregated scoring

๐Ÿš€ v2.10.0: Claude Code Agent Mode - "Always Working" Achievement! Transform PMAT into a persistent background quality agent:

  • ๐Ÿค– Claude Code Integration: Native MCP server for seamless Claude Code integration
  • ๐Ÿ’พ Persistent State: Monitoring state maintained across restarts with auto-save
  • โš™๏ธ Production Ready: Environment-specific configs for dev, prod, and CI/CD
  • ๐Ÿ“Š Real-time Monitoring: Continuous quality tracking with file system watching
  • ๐Ÿ—๏ธ Service Architecture: Systemd deployment with health checks and auto-restart

๐ŸŽฏ v2.9.0: Universal Demo "Just Works" Achievement! Complete AI-powered repository intelligence with multi-language analysis:

  • ๐Ÿค– AI-Powered Recommendations: Framework-aware repository recommendations with complexity-based learning tiers
  • ๐ŸŒ Multi-Language Intelligence: Advanced polyglot analysis with cross-language dependency detection
  • ๐Ÿ›๏ธ Architecture Pattern Recognition: Microservices, Layered, Event-driven pattern detection with confidence scoring
  • ๐Ÿ“š Repository Showcase Gallery: Curated collection of 8+ repositories across languages and complexity levels
  • โšก Universal Demo: Any GitHub repository URL โ†’ Complete analysis with AI recommendations
  • ๐ŸŒ Enhanced Web Demo: Interactive visualizations with 3 new API endpoints (/api/recommendations, /api/polyglot, /api/showcase)
  • Toyota Way Excellence: Zero compilation defects maintained throughout development

๐Ÿš€ Quick Start

Installation

Choose your preferred installation method - PMAT is available across all major package ecosystems:

๐Ÿฆ€ Rust (Recommended)

cargo install pmat

๐Ÿ“ฆ Package Managers

# macOS/Linux - Homebrew
brew install pmat

# Windows - Chocolatey  
choco install pmat

# Ubuntu/Debian - APT
sudo apt install pmat                    # (via PPA - coming soon)

# Arch Linux - AUR
yay -S pmat

# Node.js - npm (global)
npm install -g pmat-agent

๐Ÿณ Docker

# Latest version
docker run --rm -v $(pwd):/workspace paiml/pmat:latest pmat --version

# Interactive analysis
docker run --rm -v $(pwd):/workspace -w /workspace paiml/pmat:latest pmat context

๐Ÿ”ง From Source

git clone https://github.com/paiml/paiml-mcp-agent-toolkit
cd paiml-mcp-agent-toolkit
make build

๐Ÿ“ฅ Direct Download

# Linux/macOS Quick Install
curl -sSfL https://raw.githubusercontent.com/paiml/paiml-mcp-agent-toolkit/master/scripts/install.sh | sh

# Windows PowerShell
# Download from: https://github.com/paiml/paiml-mcp-agent-toolkit/releases

Basic Usage

# Analyze current directory
pmat context

# Technical Debt Grading (TDG) - v2.39.0!
pmat tdg . --include-components

# Start TDG web dashboard
pmat tdg dashboard --port 8081 --open

# TDG analysis with storage
pmat tdg server/src/tdg/analyzer_ast.rs --storage-backend sled

# Get complexity metrics
pmat analyze complexity --top-files 10

# Find technical debt
pmat analyze satd

# Code similarity detection - v2.63.0! ๐Ÿ”
pmat analyze duplicates --detection-type all     # Find all types of duplicates
pmat analyze duplicates --format sarif           # Export to SARIF format
pmat analyze duplicates --detection-type semantic --threshold 0.7

# Analysis with timeout control - NEW! ๐Ÿ”ง
pmat analyze complexity --timeout 30    # 30-second timeout
pmat analyze dead-code --timeout 60     # 60-second timeout  
pmat analyze satd --timeout 45          # 45-second timeout

# Run quality gates
pmat quality-gate --strict

# Start MCP server
pmat mcp

Universal Demo - "Just Works" Analysis

# Analyze any GitHub repository with AI recommendations
cargo run --example analyze_github_repo -- --url https://github.com/rust-lang/rust-clippy

# Compare multiple repositories across languages
cargo run --example compare_repos

# Run quality gates on GitHub repositories
cargo run --example quality_gate_github -- https://github.com/owner/repo

# Start interactive web demo
pmat demo --serve
# Then visit http://localhost:8080 for:
# โ€ข AI-powered repository recommendations
# โ€ข Multi-language project intelligence
# โ€ข Repository showcase gallery
# โ€ข Interactive analysis visualizations

Toyota Way Development (NEW)

# Setup quality enforcement (one-time)
make setup-quality

# Start development with quality checks
make dev

# Create quality-enforced commit
make commit

# Verify sprint quality
make sprint-close

๐ŸŽฏ Core Capabilities

Analysis Engine

  • Technical Debt Grading (TDG): 6-metric orthogonal code quality scoring with A+ through F grading
  • Real-time Dashboard: Web-based monitoring with live metrics and performance tracking
  • Advanced Analytics: Metrics aggregation, trend detection, bottleneck analysis
  • Performance Profiling: Flame graph generation, CPU/I/O/Memory analysis
  • Alert Management: Configurable thresholds with notification channels
  • Multi-format Export: 8 export formats (JSON, CSV, SARIF, HTML, Markdown, XML, Prometheus)
  • Storage Flexibility: Pluggable backends with tiered Hot/Warm/Cold architecture
  • MCP Integration: 6 enterprise tools for external system integration
  • Complexity Analysis: McCabe cyclomatic & cognitive complexity with AST precision
  • Dead Code Detection: Graph-based reachability analysis across 30+ languages
  • SATD Detection: Self-admitted technical debt with severity classification
  • Documentation Coverage: Language-specific pattern detection with scoring algorithms
  • Consistency Analysis: Naming conventions and code style consistency measurement
  • Deep Context Generation: Multi-dimensional analysis optimized for AI agents

๐Ÿค– AI-Powered Intelligence (NEW)

  • Smart Recommendations: Framework-aware repository suggestions with complexity matching
  • Polyglot Analysis: Cross-language dependency detection and architecture pattern recognition
  • Repository Showcase: Curated gallery with learning pathways from beginner to expert
  • Integration Points: Risk assessment of multi-language project coupling with mitigation strategies

Quality Systems

  • Quality Gates: Zero-tolerance enforcement (complexity โ‰ค20, SATD=0, coverage >80%)
  • Quality Proxy: AI code interceptor with 7-stage validation pipeline
  • PDMT Integration: Deterministic todo generation with embedded quality requirements
  • Refactoring Engine: State machine-based code transformation with ACID snapshots

Integration Protocols

  • MCP Protocol: 24 tools via unified pmcp SDK 1.3.0 server (includes 6 new TDG enterprise tools)
  • TDG Web Dashboard: Axum-based real-time interface with SSE streaming
  • HTTP API: RESTful with Server-Sent Events streaming
  • CLI Interface: 50+ commands with POSIX-compliant exit semantics

๐Ÿ“– Documentation

Core Documentation

Quality & Development

Integration Guides

๐Ÿ—๏ธ Architecture

PMAT implements Toyota Production System principles through rigorous static analysis:

  • Kaizen (ๆ”นๅ–„): Iterative file-by-file improvement with measurable ฮ”Q metrics
  • Genchi Genbutsu (็พๅœฐ็พ็‰ฉ): Direct AST traversal, no heuristics
  • Jidoka (่‡ชๅƒๅŒ–): Automated quality gates with fail-fast semantics
  • Zero SATD Policy: Compile-time enforcement of zero technical debt

Service Architecture

// Unified service layer with dependency injection
pub trait Service: Send + Sync {
    type Input: Serialize + DeserializeOwned;
    type Output: Serialize + DeserializeOwned;
    
    async fn process(&self, input: Self::Input) -> Result<Self::Output, Self::Error>;
}

// All protocols use unified request/response
#[derive(Serialize, Deserialize)]
pub struct UnifiedRequest {
    pub operation: Operation,
    pub params: Value,
    pub context: RequestContext,
}

Performance Characteristics

  • Startup: 4ms hot, 127ms cold (mmap'd grammar cache)
  • Analysis: 487K LOC/s single-thread, 3.9M LOC/s multi-core
  • Memory: 47MB base + 312KB per KLOC
  • SIMD: 43% vectorized paths, 2.7x AVX2 speedup

๐Ÿ› ๏ธ Development

Requirements

  • Rust 1.80.0+
  • Git (for repository analysis)

Build from Source

git clone https://github.com/paiml/paiml-mcp-agent-toolkit
cd paiml-mcp-agent-toolkit

# Setup Toyota Way quality enforcement
make setup-quality

# Build and test
make build
make validate

# Run examples
make examples

Library Usage

[dependencies]
pmat = "2.39.0"
use pmat::services::code_analysis::CodeAnalysisService;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let service = CodeAnalysisService::new();
    
    // Generate AI-optimized context
    let context = service.generate_context(".", None).await?;
    
    // Analyze complexity with Toyota Way standards
    let complexity = service.analyze_complexity(".", Some(10)).await?;
    
    Ok(())
}

๐Ÿ” Language Support

  • Rust: Full cargo integration with syn AST
  • TypeScript/JavaScript: SWC-based parsing
  • Python: RustPython AST analysis
  • C/C++: Tree-sitter with goto tracking
  • Ruchy: v1.5.0 support with advanced analysis
    • Full AST parsing with 35+ token types
    • Halstead metrics (volume, difficulty, effort, time, bugs)
    • Dead code detection (unused functions/variables)
    • Type inference for literals and binary operations
    • Actor message flow analysis with deadlock detection
    • Enhanced pattern matching complexity scoring
    • Import/export dependency tracking
  • Kotlin: Tree-sitter based analysis
  • 30+ Languages: Via tree-sitter grammar support

๐Ÿค– MCP Integration

PMAT provides 18 MCP tools via unified pmcp SDK server:

# Start MCP server (auto-detects transport)
pmat mcp

# Test with Claude Code
cargo run --example mcp_server_pmcp
cargo run --example test_pmcp_server

Available Tools

  • analyze_tdg - Technical Debt Grading with 6-metric scoring
  • analyze_tdg_compare - Compare TDG scores between files/projects
  • tdg_analyze_with_storage - NEW v2.39.0! TDG analysis with configurable storage backends
  • tdg_system_diagnostics - NEW v2.39.0! Comprehensive system health monitoring
  • tdg_storage_management - NEW v2.39.0! Storage operations and management
  • tdg_performance_profiling - NEW v2.39.0! Performance analysis with flame graphs
  • tdg_alert_management - NEW v2.39.0! Alert configuration and monitoring
  • tdg_export_data - NEW v2.39.0! Multi-format data export (8 formats)
  • analyze_complexity - Complexity metrics
  • analyze_satd - Technical debt detection
  • analyze_dead_code - Unused code analysis
  • quality_gate - Comprehensive quality validation
  • refactor_start - Begin refactoring workflow
  • pdmt_deterministic_todos - Generate quality todos
  • github_create_issue - Create GitHub issues
  • AI recommendation tools for intelligent repository analysis
  • And 10 more...

๐Ÿค– Claude Code Agent Mode (NEW v2.10.0)

Transform PMAT into a persistent background quality agent that continuously monitors your codebase:

Quick Start with Claude Code

# Start agent as MCP server for Claude Code
pmat agent mcp-server

# Configure in Claude Code settings.json:
{
  "mcpServers": {
    "pmat": {
      "command": "pmat",
      "args": ["agent", "mcp-server"],
      "env": {}
    }
  }
}

Background Daemon Mode

# Start monitoring a project
pmat agent start --project-path /path/to/project

# Check monitoring status
pmat agent status

# Stop monitoring
pmat agent stop

Key Features

  • Real-time Monitoring: File system watching with instant quality feedback
  • Persistent State: Maintains metrics across restarts with auto-save
  • Toyota Way Compliance: Enforces โ‰ค20 complexity with zero SATD tolerance
  • Analysis Timeouts: Configurable timeouts prevent infinite hangs (NEW! ๐Ÿ”ง)
  • Production Ready: Systemd service with health checks and auto-restart
  • MCP Native: Seamless Claude Code integration via stdio transport

Available Agent Tools

  • start_quality_monitoring - Begin monitoring a project
  • stop_quality_monitoring - Stop monitoring
  • get_quality_status - Current quality metrics
  • run_quality_gates - Execute quality checks
  • analyze_complexity - Complexity analysis
  • health_check - Agent health status

See Claude Code Agent Guide for detailed setup and deployment instructions.

๐ŸŒ TDG Web Dashboard API Endpoints (NEW v2.39.0)

# Real-time TDG metrics
GET /api/metrics

# System health status
GET /api/health

# Storage statistics
GET /api/storage/stats

# Run TDG analysis
GET /api/analysis?path=src/main.rs

# System diagnostics
GET /api/diagnostics

# Real-time metrics stream (SSE)
GET /api/events

# Storage operations
POST /api/storage/operation

๐ŸŒ Web Demo API Endpoints

# AI-powered repository recommendations
GET /api/recommendations

# Multi-language project intelligence
GET /api/polyglot

# Repository showcase gallery
GET /api/showcase

# Core analysis APIs
GET /api/summary
GET /api/metrics
GET /api/hotspots
GET /api/dag

๐Ÿ“Š Quality Standards

PMAT enforces extreme quality standards:

  • Complexity: โ‰ค20 cyclomatic, โ‰ค15 cognitive
  • Technical Debt: 0 SATD comments allowed
  • Test Coverage: >80% with property-based testing
  • Code Quality: 0 lint warnings, 0 dead code
  • Documentation: Synchronized with every commit

Quality Gates

# Run comprehensive quality analysis
pmat quality-gate --strict

# CI/CD integration
pmat analyze complexity --fail-on-violation
pmat analyze satd --fail-on-violation
pmat quality-gate --strict --fail-on-violation

๐Ÿš€ Contributing

PMAT follows Toyota Way development principles:

  1. Setup quality enforcement: make setup-quality
  2. Start development: make dev
  3. Make changes with documentation updates
  4. Quality-enforced commit: make commit
  5. Sprint verification: make sprint-close

All contributions must meet:

  • Zero SATD comments
  • Complexity โ‰ค20 per function
  • Full test coverage
  • Documentation updates

See CONTRIBUTING.md for detailed guidelines.

๐Ÿ“‹ License

Licensed under the MIT License. See LICENSE for details.

Built with โค๏ธ by Pragmatic AI Labs

For Tasks:

Click tags to check more tools for each tasks

For Jobs:

Alternative AI tools for paiml-mcp-agent-toolkit

Similar Open Source Tools

For similar tasks

For similar jobs