{"id":29327725,"url":"https://github.com/paiml/paiml-mcp-agent-toolkit","last_synced_at":"2026-03-14T06:24:25.569Z","repository":{"id":295613430,"uuid":"990219838","full_name":"paiml/paiml-mcp-agent-toolkit","owner":"paiml","description":"Pragmatic AI Labs MCP Agent Toolkit - An MCP Server designed to make code with agents more deterministic","archived":false,"fork":false,"pushed_at":"2026-03-08T17:51:35.000Z","size":101599,"stargazers_count":138,"open_issues_count":1,"forks_count":22,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-03-08T18:08:26.163Z","etag":null,"topics":["agentic","c","deno","kotlin","mcp","mcp-server","paiml","pmcp","python","ruchy","rust","toolkit","typescript"],"latest_commit_sha":null,"homepage":"https://paiml.github.io/pmat-book/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/paiml.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":"CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-25T18:34:04.000Z","updated_at":"2026-03-08T17:51:38.000Z","dependencies_parsed_at":"2026-02-20T09:02:25.401Z","dependency_job_id":null,"html_url":"https://github.com/paiml/paiml-mcp-agent-toolkit","commit_stats":null,"previous_names":["paiml/paiml-mcp-agent-toolkit"],"tags_count":327,"template":false,"template_full_name":null,"purl":"pkg:github/paiml/paiml-mcp-agent-toolkit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paiml%2Fpaiml-mcp-agent-toolkit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paiml%2Fpaiml-mcp-agent-toolkit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paiml%2Fpaiml-mcp-agent-toolkit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paiml%2Fpaiml-mcp-agent-toolkit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/paiml","download_url":"https://codeload.github.com/paiml/paiml-mcp-agent-toolkit/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paiml%2Fpaiml-mcp-agent-toolkit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30286040,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-09T02:57:19.223Z","status":"ssl_error","status_checked_at":"2026-03-09T02:56:26.373Z","response_time":61,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic","c","deno","kotlin","mcp","mcp-server","paiml","pmcp","python","ruchy","rust","toolkit","typescript"],"created_at":"2025-07-07T21:16:37.827Z","updated_at":"2026-03-14T06:24:25.549Z","avatar_url":"https://github.com/paiml.png","language":"Rust","funding_links":[],"categories":["AI Platforms","🤖 AI/ML","📚 Projects (2474 total)"],"sub_categories":["RAG","MCP Servers"],"readme":"# PMAT\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"docs/images/pmat-logo.svg\" alt=\"PMAT\" width=\"500\"\u003e\n\n  \u003cp\u003e\u003cstrong\u003eZero-configuration AI context generation for any codebase\u003c/strong\u003e\u003c/p\u003e\n\n[![Crates.io](https://img.shields.io/crates/v/pmat.svg)](https://crates.io/crates/pmat)\n[![Documentation](https://docs.rs/pmat/badge.svg)](https://docs.rs/pmat)\n[![Tests](https://img.shields.io/badge/tests-21600%2B%20passing-brightgreen)](https://github.com/paiml/paiml-mcp-agent-toolkit)\n[![Coverage](https://img.shields.io/badge/coverage-99.66%25-brightgreen)](https://github.com/paiml/paiml-mcp-agent-toolkit)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Rust](https://img.shields.io/badge/rust-1.80+-orange.svg)](https://www.rust-lang.org)\n[![CHANGELOG](https://img.shields.io/badge/changelog-Keep%20a%20Changelog-blue)](CHANGELOG.md)\n\n[Installation](#installation) | [Usage](#usage) | [Features](#features) | [Examples](#examples) | [Documentation](https://paiml.github.io/pmat-book/)\n\n\u003c/div\u003e\n\n---\n\n## What is PMAT?\n\n**PMAT** (Pragmatic Multi-language Agent Toolkit) provides everything needed to analyze code quality and generate AI-ready context:\n\n- **Context Generation** - Deep analysis for Claude, GPT, and other LLMs\n- **Technical Debt Grading** - A+ through F scoring with 6 orthogonal metrics\n- **Mutation Testing** - Test suite quality validation (85%+ kill rate)\n- **Repository Scoring** - Quantitative health assessment (0-289 scale, 11 categories)\n- **Git History RAG** - Semantic search across commit history with RRF fusion\n- **Semantic Search** - Natural language code discovery\n- **Compliance Governance** - 30+ checks across code quality, best practices, and reproducibility\n- **Design by Contract** - Toyota Way contract profiles with checkpoint validation and rescue protocols\n- **Autonomous Kaizen** - Toyota Way continuous improvement with auto-fix and commit\n- **MCP Integration** - 19 tools for Claude Code, Cline, and AI agents\n- **Quality Gates** - Pre-commit hooks, CI/CD integration, `.pmat-gates.toml` config\n- **20+ Languages** - Rust, TypeScript, Python, Go, Java, C/C++, Lua, Lean, and more\n\nPart of the [PAIML Stack](https://github.com/paiml), following Toyota Way quality principles (Jidoka, Genchi Genbutsu, Kaizen).\n\n### Annotated Code Search\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"docs/images/pmat-query-screenshot.png\" alt=\"pmat query annotated output\" width=\"800\"\u003e\n  \u003cp\u003e\u003cem\u003e\u003ccode\u003epmat query \"cache invalidation\" --churn --duplicates --entropy --faults\u003c/code\u003e\u003c/em\u003e\u003c/p\u003e\n\u003c/div\u003e\n\nEvery result includes TDG grade, Big-O complexity, git churn, code clones, pattern diversity, fault annotations, call graph, and syntax-highlighted source.\n\n## Installation\n\n```bash\n# Install from crates.io\ncargo install pmat\n\n# Or from source (latest)\ngit clone https://github.com/paiml/paiml-mcp-agent-toolkit\ncd paiml-mcp-agent-toolkit \u0026\u0026 cargo install --path .\n```\n\n## Usage\n\n```bash\n# Generate AI-ready context\npmat context --output context.md --format llm-optimized\n\n# Analyze code complexity\npmat analyze complexity\n\n# Grade technical debt (A+ through F)\npmat analyze tdg\n\n# Score repository health\npmat repo-score .\n\n# Run mutation testing\npmat mutate --target src/\n\n# Start MCP server for Claude Code, Cline, etc.\npmat mcp\n```\n\n## Features\n\n### Context Generation\n\nGenerate comprehensive context for AI assistants:\n\n```bash\npmat context                           # Basic analysis\npmat context --format llm-optimized    # AI-optimized output\npmat context --include-tests           # Include test files\n```\n\n### Technical Debt Grading (TDG)\n\nSix orthogonal metrics for accurate quality assessment:\n\n```bash\npmat analyze tdg                       # Project-wide grade\npmat analyze tdg --include-components  # Per-component breakdown\npmat tdg baseline create               # Create quality baseline\npmat tdg check-regression              # Detect quality degradation\n```\n\n**Grading Scale:**\n- **A+/A**: Excellent quality, minimal debt\n- **B+/B**: Good quality, manageable debt\n- **C+/C**: Needs improvement\n- **D/F**: Significant technical debt\n\n### Mutation Testing\n\nValidate test suite effectiveness:\n\n```bash\npmat mutate --target src/lib.rs        # Single file\npmat mutate --target src/ --threshold 85  # Quality gate\npmat mutate --failures-only            # CI optimization\n```\n\n**Supported Languages:** Rust, Python, TypeScript, JavaScript, Go, C/C++, C#, Lua, Lean, Java, Kotlin, Ruby, Swift, PHP, Bash, SQL, Scala, YAML, Markdown + MLOps model formats (GGUF, SafeTensors, APR)\n\n### Repository Health Scoring\n\nEvidence-based quality metrics (0-289 scale, 11 categories):\n\n```bash\npmat rust-project-score                # Fast mode (~3 min)\npmat rust-project-score --full         # Comprehensive (~10-15 min)\npmat repo-score . --deep               # Full git history\n```\n\n### Workflow Prompts\n\nPre-configured AI prompts enforcing EXTREME TDD:\n\n```bash\npmat prompt --list                     # Available prompts\npmat prompt code-coverage              # 85%+ coverage enforcement\npmat prompt debug                      # Five Whys analysis\npmat prompt quality-enforcement        # All quality gates\n```\n\n### Git History RAG\n\nSearch git history by intent using TF-IDF semantic embeddings:\n\n```bash\n# Fuse git history into code search\npmat query \"fix memory leak\" -G\n\n# Search with churn, clones, entropy, faults\npmat query \"error handling\" --churn --duplicates --entropy --faults\n```\n\n```bash\n# Run the example\ncargo run --example git_history_demo\n```\n\n### Git Hooks\n\nAutomatic quality enforcement:\n\n```bash\npmat hooks install                     # Install pre-commit hooks\npmat hooks install --tdg-enforcement   # With TDG quality gates\npmat hooks status                      # Check hook status\n```\n\n### Compliance Governance (`pmat comply`)\n\n30+ automated checks across code quality, best practices, and governance:\n\n```bash\npmat comply check                      # Run all compliance checks\npmat comply check --strict             # Exit non-zero on failure\npmat comply check --format json        # Machine-readable output\npmat comply migrate                    # Update to latest version\n```\n\n**Key Checks:**\n- **CB-200**: TDG Grade Gate — blocks on non-A functions (auto-rebuilds stale index)\n- **CB-304**: Dead code percentage enforcement\n- **CB-400**: Shell/Makefile quality via bashrs\n- **CB-500**: Rust best practices (30+ patterns)\n- **CB-600**: Lua best practices\n- **CB-900**: Markdown link validation\n- **CB-1000**: MLOps model quality\n\nConfigure via `.pmat-gates.toml`:\n\n```toml\n[tdg]\nmin_grade = \"A\"\nexclude = [\"examples/**\", \"scripts/**\"]\n```\n\n### Document Search (`pmat query --docs`)\n\nSearch documentation files (Markdown, text, YAML) alongside code:\n\n```bash\npmat query \"authentication\" --docs          # Code + docs results\npmat query \"deployment\" --docs-only         # Only documentation\npmat query \"API endpoints\" --no-docs        # Exclude docs (default)\n```\n\n### Autonomous Kaizen (`pmat kaizen`)\n\nToyota Way continuous improvement — scan, auto-fix, commit:\n\n```bash\npmat kaizen --dry-run                  # Scan only (no changes)\npmat kaizen                            # Apply safe auto-fixes\npmat kaizen --commit --push            # Fix, commit, and push\npmat kaizen --format json -o report.json  # CI/CD integration\n\n# Cross-stack mode: scan all batuta stack crates in one invocation\npmat kaizen --cross-stack --dry-run    # Scan all crates\npmat kaizen --cross-stack --commit     # Fix and commit per-crate\npmat kaizen --cross-stack -f json      # Grouped JSON report\n```\n\n### Function Extraction (`pmat extract`)\n\nExtract function boundaries with metadata:\n\n```bash\npmat extract src/lib.rs                # Extract functions from file\npmat extract --list src/               # List all functions with imports and visibility\n```\n\n## Examples\n\n### Generate Context for AI\n\n```bash\n# For Claude Code\npmat context --output context.md --format llm-optimized\n\n# With semantic search\npmat embed sync ./src\npmat semantic search \"error handling patterns\"\n```\n\n### CI/CD Integration\n\n```yaml\n# Add to your CI pipeline\nsteps:\n  - uses: actions/checkout@v4\n  - run: cargo install pmat\n  - run: pmat analyze tdg --fail-on-violation --min-grade B\n  - run: pmat mutate --target src/ --threshold 80\n```\n\n### Quality Baseline Workflow\n\n```bash\n# 1. Create baseline\npmat tdg baseline create --output .pmat/baseline.json\n\n# 2. Check for regressions\npmat tdg check-regression \\\n  --baseline .pmat/baseline.json \\\n  --max-score-drop 5.0 \\\n  --fail-on-regression\n```\n\n## Architecture\n\n```\npmat/\n├── src/\n│   ├── cli/          Command handlers and dispatchers\n│   ├── services/     Analysis engines (TDG, SATD, complexity, agent context)\n│   ├── mcp_server/   MCP protocol server\n│   ├── mcp_pmcp/     PMCP protocol integration\n│   └── models/       Configuration and data models\n├── examples/         89 runnable examples\n└── docs/\n    └── specifications/  Technical specs\n```\n\n## Quality\n\n| Metric | Value |\n|--------|-------|\n| Tests | 21,200+ passing |\n| Coverage | 99.66% |\n| Mutation Score | \u003e80% |\n| Languages | 20 supported + MLOps model formats |\n| MCP Tools | 19 available |\n\n### Falsifiable Quality Commitments\n\nPer [Popper's demarcation criterion](https://en.wikipedia.org/wiki/Demarcation_problem), all claims are measurable and testable:\n\n| Commitment | Threshold | Verification Method |\n|------------|-----------|---------------------|\n| **Context Generation** | \u003c 5 seconds for 10K LOC project | `time pmat context` on test corpus |\n| **Memory Usage** | \u003c 500 MB for 100K LOC analysis | Measured via `heaptrack` in CI |\n| **Test Coverage** | ≥ 85% line coverage | `cargo llvm-cov` (CI enforced) |\n| **Mutation Score** | ≥ 80% killed mutants | `pmat mutate --threshold 80` |\n| **Build Time** | \u003c 3 minutes incremental | `cargo build --timings` |\n| **CI Pipeline** | \u003c 15 minutes total | GitHub Actions workflow timing |\n| **Binary Size** | \u003c 50 MB release binary | `ls -lh target/release/pmat` |\n| **Language Parsers** | All 20 languages parse without panic | Fuzz testing in CI |\n\n**How to Verify:**\n\n```bash\n# Run self-assessment with Popper Falsifiability Score\npmat popper-score --verbose\n\n# Individual commitment verification\ncargo llvm-cov --html        # Coverage ≥85%\npmat mutate --threshold 80   # Mutation ≥80%\ncargo build --timings        # Build time \u003c3min\n```\n\n**Failure = Regression:** Any commitment violation blocks CI merge.\n\n### Benchmark Results (Statistical Rigor)\n\nAll benchmarks use Criterion.rs with proper statistical methodology:\n\n| Operation | Mean | 95% CI | Std Dev | Sample Size |\n|-----------|------|--------|---------|-------------|\n| Context (1K LOC) | 127ms | [124, 130] | ±12.3ms | n=1000 runs |\n| Context (10K LOC) | 1.84s | [1.79, 1.90] | ±156ms | n=500 runs |\n| TDG Scoring | 156ms | [148, 164] | ±18.2ms | n=500 runs |\n| Complexity Analysis | 23ms | [22, 24] | ±3.1ms | n=1000 runs |\n\n**Comparison Baselines (vs. Alternatives):**\n\n| Metric | PMAT | ctags | tree-sitter | Effect Size |\n|--------|------|-------|-------------|-------------|\n| 10K LOC parsing | 1.84s | 0.3s | 0.8s | d=0.72 (medium) |\n| Memory (10K LOC) | 287MB | 45MB | 120MB | - |\n| Semantic depth | Full | Syntax only | AST only | - |\n\nSee [docs/BENCHMARKS.md](docs/BENCHMARKS.md) for complete statistical analysis.\n\n### ML/AI Reproducibility\n\nPMAT uses ML for semantic search and embeddings. All ML operations are reproducible:\n\n**Random Seed Management:**\n- Embedding generation uses fixed seed (SEED=42) for deterministic outputs\n- Clustering operations use fixed seed (SEED=12345)\n- Seeds documented in [docs/ml/REPRODUCIBILITY.md](docs/ml/REPRODUCIBILITY.md)\n\n**Model Artifacts:**\n- Pre-trained models from HuggingFace (all-MiniLM-L6-v2)\n- Model versions pinned in Cargo.toml\n- Hash verification on download\n\n## Dataset Sources\n\nPMAT does not train models but uses these data sources for evaluation:\n\n| Dataset | Source | Purpose | Size |\n|---------|--------|---------|------|\n| CodeSearchNet | GitHub/Microsoft | Semantic search benchmarks | 2M functions |\n| PMAT-bench | Internal | Regression testing | 500 queries |\n\nData provenance and licensing documented in [docs/ml/REPRODUCIBILITY.md](docs/ml/REPRODUCIBILITY.md).\n\n## Sovereign Stack\n\nPMAT is built on the PAIML Sovereign Stack - pure-Rust, SIMD-accelerated libraries:\n\n| Library | Purpose | Version |\n|---------|---------|---------|\n| [aprender](https://crates.io/crates/aprender) | ML library (text similarity, clustering, topic modeling) | 0.27.1 |\n| [trueno](https://crates.io/crates/trueno) | SIMD compute library for matrix operations | 0.16.1 |\n| [trueno-graph](https://crates.io/crates/trueno-graph) | GPU-first graph database (PageRank, Louvain, CSR) | 0.1.17 |\n| [trueno-rag](https://crates.io/crates/trueno-rag) | RAG pipeline with VectorStore | 0.2.2 |\n| [trueno-db](https://crates.io/crates/trueno-db) | Embedded analytics database | 0.3.15 |\n| [trueno-viz](https://crates.io/crates/trueno-viz) | Terminal graph visualization | 0.2.1 |\n| [trueno-zram-core](https://crates.io/crates/trueno-zram-core) | SIMD LZ4/ZSTD compression (optional) | 0.3.0 |\n| **pmat** | Code analysis toolkit | 3.7.0 |\n\n**Key Benefits:**\n- Pure Rust (no C dependencies, no FFI)\n- SIMD-first (AVX2, AVX-512, NEON auto-detection)\n- 2-4x speedup on graph algorithms via aprender adapter\n\n## Documentation\n\n- [PMAT Book](https://paiml.github.io/pmat-book/) - Complete guide\n- [API Reference](https://docs.rs/pmat) - Rust API docs\n- [MCP Tools](docs/mcp/TOOLS.md) - MCP integration guide\n- [Specifications](docs/specifications/) - Technical specs\n- 🤖 [Coursera Hugging Face AI Development Specialization](https://www.coursera.org/specializations/hugging-face-ai-development) - Build Production AI systems with Hugging Face in Pure Rust\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and pull request guidelines.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n  \u003csub\u003eBuilt with Extreme TDD | Part of \u003ca href=\"https://github.com/paiml\"\u003ePAIML\u003c/a\u003e\u003c/sub\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaiml%2Fpaiml-mcp-agent-toolkit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpaiml%2Fpaiml-mcp-agent-toolkit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaiml%2Fpaiml-mcp-agent-toolkit/lists"}