paiml/paiml-mcp-agent-toolkit

Zero-configuration AI context generation for any codebase
Installation | MCP Server | Usage | Features | Examples | Documentation
---
Table of Contents
- What is PMAT?
- Installation
- MCP Server
- Usage
- Features
- Architecture
What is PMAT?
**PMAT** (Pragmatic Multi-language Agent Toolkit) provides everything needed to analyze code quality and generate AI-ready context:
- **Context Generation** - Deep analysis for Claude, GPT, and other LLMs
- **Technical Debt Grading** - A+ through F scoring with 6 orthogonal metrics
- **Mutation Testing** - Test suite quality validation (85%+ kill rate)
- **Repository Scoring** - Quantitative health assessment (0-289 scale, 11 categories)
- **Git History RAG** - Semantic search across commit history with RRF fusion
- **Semantic Search** - Natural language code discovery
- **Compliance Governance** - 157 checks across code quality, best practices, and reproducibility
- **Design by Contract** - Toyota Way contract profiles with checkpoint validation and rescue protocols
- **Autonomous Kaizen** - Toyota Way continuous improvement with auto-fix and commit
- **MCP Integration** - 20 tools for Claude Code, Cline, and AI agents over **stdio and HTTP** (identical surfaces), validated end-to-end for concurrent multi-agent (ultracode) workflows — see MCP Server
- **Quality Gates** - Pre-commit hooks, CI/CD integration, .pmat-gates.toml config
- **20+ Languages** - Rust, TypeScript, Python, Go, Java, C/C++, Lua, Lean, and more
Part of the PAIML Stack, following Toyota Way quality principles (Jidoka, Genchi Genbutsu, Kaizen).
Annotated Code Search
pmat query "cache invalidation" --churn --duplicates --entropy --faults
Every result includes TDG grade, Big-O complexity, git churn, code clones, pattern diversity, fault annotations, call graph, and syntax-highlighted source.
Installation
> **Note for macOS Users:** If you experience issues installing via rustup, we recommend installing/updating Rust using Homebrew: brew install rust before running cargo install pmat.
MCP Server
PMAT is an MCP server first and a CLI second. One binary serves **three surfaces**, and
they share one tool registry — you pick a surface, not a feature set.
| Surface | Start it with | Use it when |
|---------|---------------|-------------|
| **CLI** | pmat analyze complexity --path . | A human or a shell script reads the output. |
| **MCP over stdio** | pmat --mode mcp | An MCP client launches pmat itself as a subprocess — Claude Code, Claude Desktop, Cline. One client, one process, no port, no token. |
| **MCP over HTTP** | pmat serve --transport http --port 8765 | One long-lived server that several clients — or another machine — talk to. Streamable HTTP, bearer auth. |
> **New in 3.32.0:** mcp-http moved into the **default** feature set. cargo install pmat
> now gives you the HTTP transport; the old --features mcp-http dance is gone. Compiling
> the transport in does not open a socket — only pmat serve binds one.
Quickstart — stdio
Claude Code launches pmat as a subprocess. Nothing to keep running, nothing to authenticate.
Claude Desktop takes the same command as JSON, in its own claude_desktop_config.json:
For clients that cannot pass flags, MCP_VERSION=1 pmat starts the identical server.
Smoke-test the stdio surface without any client at all:
Quickstart — HTTP
One server, many clients. Copy-paste the whole block:
The server binds 127.0.0.1 unless you pass --host. To reach it from another machine, bind an
externally routable address and treat PMAT_MCP_HTTP_TOKEN as a real secret — the tool
surface can read and analyse any path the server process can read.
Four gotchas that cost an hour each
**1. MCP is served at the root path /, not /mcp.** There is no path prefix.
**2. PMAT_MCP_HTTP_TOKEN is mandatory and must be at least 16 characters.** Below that