What is Paiml Mcp Agent Toolkit

The PAIML MCP Agent Toolkit is a stateless Model Context Protocol (MCP) server developed by Pragmatic AI Labs, designed to facilitate intelligent project scaffolding by generating production-ready Makefiles, README files, and .gitignore configurations for various programming languages.

Use cases

Use cases include automating the setup of new projects, ensuring consistency in project configurations, and enhancing productivity for developers by reducing the manual effort required to create essential project files.

How to use

To use the PAIML MCP Agent Toolkit, users can either install a pre-built binary or build from source. After installation, the toolkit can be added to Claude Code for seamless integration, allowing users to generate necessary project files effortlessly.

Key features

Key features include the ability to generate Makefiles, README files, and .gitignore files optimized for Rust, Deno, and Python development, along with compatibility with MCP clients and a focus on deterministic code generation.

Where to use

The toolkit is applicable in software development environments where project scaffolding is needed, particularly for teams working with Rust, Deno, and Python, as well as in educational settings for teaching coding practices.

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

# New in v0.26.0
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

# 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
• Kotlin - Full AST parsing for classes, functions, interfaces, and more

📚 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

🌐 Language Support

• Rust - Complete AST analysis with native syn parser
• TypeScript/JavaScript - Full parsing support via SWC
• Python - AST analysis with rustpython-parser
• C/C++ - Tree-sitter based parsing with comprehensive coverage
• Kotlin - Full AST support via tree-sitter-kotlin (v0.26.0)
• Go, Java, Ruby - Basic support via unified AST

All parsers include memory safety protections and iterative processing to handle large codebases efficiently.

🎯 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

🛠️ System Operations

Memory Management

For systems with low swap space, we provide a configuration tool:

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:

# 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