GitHub - paiml/paiml-mcp-agent-toolkit: Pragmatic AI Labs MCP Agent Toolkit - An MCP Server designed to make code with agents more deterministic (original) (raw)

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