PAIML MCP Agent Toolkit

Zero-configuration AI context generation system that analyzes any codebase instantly through CLI, MCP, or HTTP interfaces. Built by Pragmatic AI Labs.

🚀 Installation

curl -sSfL https://raw.githubusercontent.com/paiml/paiml-mcp-agent-toolkit/master/scripts/install.sh | sh

📋 Tool Usage

CLI Interface

# 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
pmat analyze graph-metrics                    # Graph centrality metrics
pmat analyze name-similarity "function_name"  # Semantic name search

# 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

# 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

💫 See CLI usage in action

Context and code analysis:

Running demos/visualization:

MCP Integration (Claude Code)

# Add to Claude Code
claude mcp add paiml-toolkit ~/.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
• analyze_code_churn - Git history analysis
• analyze_dag - Dependency graph generation
• analyze_dead_code - Dead code detection
• analyze_deep_context - Comprehensive analysis
• 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

HTTP API

# 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"]}'

🔧 Supported Languages

• Rust - Complete AST analysis, complexity metrics
• TypeScript/JavaScript - Full parsing and analysis
• Python - AST analysis and code metrics
• C/C++ - Goto tracking, macro analysis, memory safety indicators
• Cython - Hybrid Python/C analysis

📚 Documentation

Feature Documentation

• Feature Overview - Complete feature index
• Makefile Linter - 50+ rules for Makefile quality
• Emit-Refactor Engine - Real-time defect detection & refactoring
• Excellence Tracker - Code quality metrics tracking
• Technical Debt Gradient - Quantitative debt measurement
• MCP Protocol - AI agent integration guide

Additional Features

• Code Quality Tools

  • pmat analyze makefile-lint - Lint Makefiles with 50+ quality rules
  • pmat excellence-tracker - Track code quality metrics over time
  • pmat refactor serve - Batch refactoring with checkpoints
  • pmat refactor interactive - Interactive refactoring with explanations

• Advanced Analysis

  • pmat analyze tdg - Calculate Technical Debt Gradient
  • pmat analyze proof-annotations - Lightweight formal verification
  • pmat analyze defect-prediction - ML-based defect prediction
  • pmat analyze name-similarity - Semantic name search with embeddings
  • pmat analyze big-o - Big-O complexity with confidence scores
  • pmat analyze graph-metrics - PageRank and centrality metrics
  • pmat analyze incremental-coverage - Coverage changes since base branch

📊 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

📚 Documentation

• CLI Reference
• MCP Protocol
• HTTP API
• Architecture
• Distributed Testing

🧪 Testing

The project uses a distributed test architecture for fast feedback:

# 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

1. Fork the repository
2. Create a feature branch
3. Run make test-fast for validation
4. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

---

Built with ❤️ by Pragmatic AI Labs