Skip to content
Back to search

paiml-mcp-agent-toolkit

Pragmatic AI Labs MCP Agent Toolkit - An MCP Server designed to make code with agents more deterministic

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/paiml/paiml-mcp-agent-toolkit with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/paiml/paiml-mcp-agent-toolkit'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/paiml--paiml-mcp-agent-toolkit/badge.svg)](/listings/paiml--paiml-mcp-agent-toolkit)

HTML

<a href="/listings/paiml--paiml-mcp-agent-toolkit"><img src="/api/listings/paiml--paiml-mcp-agent-toolkit/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# Install from crates.io
cargo install pmat

> **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`.

# Or from source (latest)
git clone https://github.com/paiml/paiml-mcp-agent-toolkit
cd paiml-mcp-agent-toolkit && cargo install --path .

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 659 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <h1 align="center">PMAT</h1>
  2. <p align="center">
  3. <img src="docs/images/pmat-logo.svg" alt="PMAT" width="500">
  4. </p>
  5. <p align="center">
  6. <strong>Zero-configuration AI context generation for any codebase</strong>
  7. </p>
  8. <div align="center">
  9. [![Crates.io](https://img.shields.io/crates/v/pmat.svg)](https://crates.io/crates/pmat)
  10. [![Documentation](https://docs.rs/pmat/badge.svg)](https://docs.rs/pmat)
  11. [![Tests](https://img.shields.io/badge/tests-21600%2B%20passing-brightgreen)](https://github.com/paiml/paiml-mcp-agent-toolkit)
  12. [![Coverage](https://img.shields.io/badge/coverage-99.66%25-brightgreen)](https://github.com/paiml/paiml-mcp-agent-toolkit)
  13. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
  14. [![MSRV](https://img.shields.io/badge/MSRV-1.91-orange.svg)](https://www.rust-lang.org)
  15. [![CHANGELOG](https://img.shields.io/badge/changelog-Keep%20a%20Changelog-blue)](CHANGELOG.md)
  16. [Installation](#installation) | [MCP Server](#mcp-server) | [Usage](#usage) | [Features](#features) | [Examples](#examples) | [Documentation](https://paiml.github.io/pmat-book/)
  17. </div>
  18. ---
  19. ## Table of Contents
  20. - [What is PMAT?](#what-is-pmat)
  21. - [Installation](#installation)
  22. - [MCP Server](#mcp-server)
  23. - [Usage](#usage)
  24. - [Features](#features)
  25. - [Architecture](#architecture)
  26. ## What is PMAT?
  27. **PMAT** (Pragmatic Multi-language Agent Toolkit) provides everything needed to analyze code quality and generate AI-ready context:
  28. - **Context Generation** - Deep analysis for Claude, GPT, and other LLMs
  29. - **Technical Debt Grading** - A+ through F scoring with 6 orthogonal metrics
  30. - **Mutation Testing** - Test suite quality validation (85%+ kill rate)
  31. - **Repository Scoring** - Quantitative health assessment (0-289 scale, 11 categories)
  32. - **Git History RAG** - Semantic search across commit history with RRF fusion
  33. - **Semantic Search** - Natural language code discovery
  34. - **Compliance Governance** - 157 checks across code quality, best practices, and reproducibility
  35. - **Design by Contract** - Toyota Way contract profiles with checkpoint validation and rescue protocols
  36. - **Autonomous Kaizen** - Toyota Way continuous improvement with auto-fix and commit
  37. - **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](#mcp-server)
  38. - **Quality Gates** - Pre-commit hooks, CI/CD integration, `.pmat-gates.toml` config
  39. - **20+ Languages** - Rust, TypeScript, Python, Go, Java, C/C++, Lua, Lean, and more
  40. Part of the [PAIML Stack](https://github.com/paiml), following Toyota Way quality principles (Jidoka, Genchi Genbutsu, Kaizen).
  41. ### Annotated Code Search
  42. <div align="center">
  43. <img src="docs/images/pmat-query-screenshot.png" alt="pmat query annotated output" width="800">
  44. <p><em><code>pmat query "cache invalidation" --churn --duplicates --entropy --faults</code></em></p>
  45. </div>
  46. Every result includes TDG grade, Big-O complexity, git churn, code clones, pattern diversity, fault annotations, call graph, and syntax-highlighted source.
  47. ## Installation
  48. ```bash
  49. # Install from crates.io
  50. cargo install pmat
  51. ```
  52. > **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`.
  53. ```bash
  54. # Or from source (latest)
  55. git clone https://github.com/paiml/paiml-mcp-agent-toolkit
  56. cd paiml-mcp-agent-toolkit && cargo install --path .
  57. ```
  58. ## MCP Server
  59. PMAT is an MCP server first and a CLI second. One binary serves **three surfaces**, and
  60. they share one tool registry — you pick a surface, not a feature set.
  61. | Surface | Start it with | Use it when |
  62. |---------|---------------|-------------|
  63. | **CLI** | `pmat analyze complexity --path .` | A human or a shell script reads the output. |
  64. | **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. |
  65. | **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. |
  66. > **New in 3.32.0:** `mcp-http` moved into the **default** feature set. `cargo install pmat`
  67. > now gives you the HTTP transport; the old `--features mcp-http` dance is gone. Compiling
  68. > the transport in does not open a socket — only `pmat serve` binds one.
  69. ### Quickstart — stdio
  70. Claude Code launches pmat as a subprocess. Nothing to keep running, nothing to authenticate.
  71. ```bash
  72. cargo install pmat
  73. claude mcp add --scope user pmat -- pmat --mode mcp
  74. claude mcp list
  75. # pmat: pmat --mode mcp - ✔ Connected
  76. ```
  77. Claude Desktop takes the same command as JSON, in its own `claude_desktop_config.json`:
  78. ```json
  79. {
  80. "mcpServers": {
  81. "pmat": { "command": "pmat", "args": ["--mode", "mcp"] }
  82. }
  83. }
  84. ```
  85. For clients that cannot pass flags, `MCP_VERSION=1 pmat` starts the identical server.
  86. Smoke-test the stdio surface without any client at all:
  87. ```bash
  88. printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  89. | pmat --mode mcp 2>/dev/null | jq -r '.result.tools | length'
  90. # 19
  91. ```
  92. ### Quickstart — HTTP
  93. One server, many clients. Copy-paste the whole block:
  94. ```bash
  95. cargo install pmat
  96. export PMAT_MCP_HTTP_TOKEN='pmat-mcp-demo-token-0123456789' # >= 16 chars; use your own
  97. pmat serve --transport http --port 8765 &
  98. # pmat MCP (streamable HTTP) listening on http://127.0.0.1:8765/
  99. # auth: Bearer, from PMAT_MCP_HTTP_TOKEN; unauthenticated requests get 401
  100. # tools: 20
  101. sleep 2
  102. claude mcp add --scope user --transport http pmat http://127.0.0.1:8765/ \
  103. --header "Authorization: Bearer $PMAT_MCP_HTTP_TOKEN"
  104. claude mcp list
  105. # pmat: http://127.0.0.1:8765/ (HTTP) - ✔ Connected
  106. ```
  107. The server binds `127.0.0.1` unless you pass `--host`. To reach it from another machine, bind an
  108. externally routable address and treat `PMAT_MCP_HTTP_TOKEN` as a real secret — the tool
  109. surface can read and analyse any path the server process can read.
  110. ### Four gotchas that cost an hour each
  111. **1. MCP is served at the root path `/`, not `/mcp`.** There is no path prefix.
  112. ```bash
  113. for p in / /mcp /health; do
  114. printf '%-7s %s\n' "$p" "$(curl -s -o /dev/null -w '%{http_code}' -X POST "http://127.0.0.1:8765$p" \
  115. -H "Authorization: Bearer $PMAT_MCP_HTTP_TOKEN" \
  116. -H "Content-Type: application/json" \
  117. -H "Accept: application/json, text/event-stream" \
  118. -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}')"
  119. done
  120. # / 200
  121. # /mcp 404
  122. # /health 404
  123. ```
  124. **2. `PMAT_MCP_HTTP_TOKEN` is mandatory and must be at least 16 characters.** Below that
  125. the server refuses to start rather than falling back to serving unauthenticated — the
  126. underlying pmcp transport answers every request when no auth provider is wired, so "no
  127. token" has to mean "no server". Requests with no token, or a wrong one, get `401`.
  128. ```bash
  129. PMAT_MCP_HTTP_TOKEN=too-short-123 pmat serve --transport http --port 8765
  130. # Error: PMAT_MCP_HTTP_TOKEN must be at least 16 characters; got 13
  131. ```
  132. **3. Hand-rolled clients must send `Accept: application/json, text/event-stream`.** The
  133. streamable transport rejects the request without it, and `curl -f` turns that into an
  134. empty string with no message — so probe with plain `curl -s` while debugging.
  135. ```bash
  136. curl -s -w '\n-> HTTP %{http_code}\n' -X POST http://127.0.0.1:8765/ \
  137. -H "Authorization: Bearer $PMAT_MCP_HTTP_TOKEN" \
  138. -H "Content-Type: application/json" \
  139. -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
  140. # {"jsonrpc":"2.0","error":{"code":-32700,"message":"Accept header must include application/json or text/event-stream"},"id":null}
  141. # -> HTTP 406
  142. ```
  143. **4. There is no `/health` endpoint.** `GET /health` is a `404`, so a `curl -f
  144. .../health` readiness loop never turns green and never says why. Probe with a real
  145. `tools/list` call instead:
  146. ```bash
  147. curl -s -X POST http://127.0.0.1:8765/ \
  148. -H "Authorization: Bearer $PMAT_MCP_HTTP_TOKEN" \
  149. -H "Content-Type: application/json" \
  150. -H "Accept: application/json, text/event-stream" \
  151. -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  152. | jq -r '.result.tools | length'
  153. # 19
  154. ```
  155. No MCP session id is involved: `initialize` returns no `Mcp-Session-Id` header, and
  156. `tools/call` works directly — with or without a preceding `initialize`.
  157. ### HTTP is not a reduced surface
  158. Both transports are built from the same registry, so HTTP serves **all 20 tools, not a
  159. subset**. The `tools/list` payloads are byte-identical:
  160. ```bash
  161. printf '%s\n%s\n' \
  162. '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"p","version":"1"}}}' \
  163. '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  164. | pmat --mode mcp 2>/dev/null \
  165. | jq -Sc 'select(.id==2)|.result.tools|sort_by(.name)' > /tmp/pmat-stdio-tools.json
  166. curl -s -X POST http://127.0.0.1:8765/ \
  167. -H "Authorization: Bearer $PMAT_MCP_HTTP_TOKEN" \
  168. -H "Content-Type: application/json" \
  169. -H "Accept: application/json, text/event-stream" \
  170. -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  171. | jq -Sc '.result.tools|sort_by(.name)' > /tmp/pmat-http-tools.json
  172. cmp /tmp/pmat-stdio-tools.json /tmp/pmat-http-tools.json && echo "identical"
  173. # identical
  174. ```
  175. The 19: `analyze_complexity`, `analyze_satd`, `analyze_dead_code`, `analyze_dag`,
  176. `analyze_deep_context`, `analyze_big_o`, `analyze_reachability`,
  177. `analyze_hardcoded_paths`, `analyze_vacuous_tests`, `quality_gate`, `quality_proxy`,
  178. `generate_context`, `scaffold_project`, `git_operation`, `pmat_query_code`,
  179. `pmat_get_function`, `pmat_find_similar`, `pmat_index_stats`,
  180. `pdmt_deterministic_todos`. Names and descriptions are also committed as the machine-checked
  181. manifest [`mcp.json`](mcp.json) at the repository root, regenerated from the server's own
  182. registrations — so it cannot drift from what the two transports actually serve.
  183. ### Transports that are not implemented
  184. `--transport` also accepts `web-socket`, `http-sse`, `both` and `all`. None of them are
  185. implemented; each exits `2` with a message saying so. `http` is the only value that
  186. serves.
  187. ```bash
  188. pmat serve --transport web-socket --port 8765
  189. # error: pmat serve --transport websocket is not yet implemented
  190. ```
  191. There is no `stdio` value for `--transport` — passing one is a clap error. Stdio is
  192. `pmat --mode mcp`.
  193. ## Usage
  194. ```bash
  195. # Generate AI-ready context
  196. pmat context --output context.md --format llm-optimized
  197. # Analyze code complexity
  198. pmat analyze complexity
  199. # Grade technical debt (A+ through F)
  200. pmat analyze tdg
  201. # Score repository health
  202. pmat repo-score .
  203. # Pre-flight verify before committing (CI-faithful: fmt + complexity + satd + clippy + tests)
  204. pmat verify --format json
  205. # Run mutation testing
  206. pmat mutate --target src/
  207. # Start the MCP server over stdio, for Claude Code, Cline, etc. (see "MCP Server" above)
  208. pmat --mode mcp
  209. ```
  210. ### Autonomous-agent pre-flight (`pmat verify`)
  211. `pmat verify` runs the exact gate set CI enforces — **format, complexity, satd, clippy, tests** — fail-fast, with machine-readable output, so an agent gets *"green here ⇒ green in CI"* before committing. The canonical loop: `edit → pmat verify --format json → fix on red → commit on green`. See [`docs/agent-instructions/autonomous-verify-loop.md`](docs/agent-instructions/autonomous-verify-loop.md).
  212. ### Ultracode validated
  213. PMAT releases are dogfooded with **ultracode** — Claude Code's multi-agent
  214. dynamic-workflow orchestration — as both the test harness and the target
  215. workload:
  216. - **Full CLI sweep**: 111 commands exercised by parallel agent fleets per release
  217. - **MCP surface**: all 20 tools validated over stdio JSON-RPC — per-tool calls
  218. with schema-derived arguments, 8-way concurrent server sessions against one
  219. working tree (zero lock errors, zero scratch leftovers), and byte-level
  220. framing checks (stdout is exclusively JSON-RPC) — plus a transport-parity
  221. check that the HTTP `tools/list` payload is byte-identical to the stdio one
  222. - **Determinism**: TDG baselines and penalty attributions serialize
  223. byte-identically across runs, so independent agents converge instead of
  224. diverging on ordering noise
  225. - **Concurrency-safe caches**: PID-unique scratch files with atomic
  226. rename-into-place and stale-orphan sweeping; advisory-locked metric recording
  227. Findings from each sweep are adversarially re-verified by skeptic agents
  228. before they drive fixes — see the release case studies in the
  229. [pmat book](https://paiml.github.io/pmat-book/).
  230. ## Features
  231. ### Context Generation
  232. Generate comprehensive context for AI assistants:
  233. ```bash
  234. pmat context # Basic analysis
  235. pmat context --format llm-optimized # AI-optimized output
  236. pmat context --include-large-files # Include files >500KB normally skipped
  237. ```
  238. ### Technical Debt Grading (TDG)
  239. Six orthogonal metrics for accurate quality assessment:
  240. ```bash
  241. pmat analyze tdg # Project-wide grade
  242. pmat analyze tdg --include-components # Per-component breakdown
  243. pmat tdg baseline create # Create quality baseline
  244. pmat tdg check-regression # Detect quality degradation
  245. ```
  246. **Grading Scale:**
  247. - **A+/A**: Excellent quality, minimal debt
  248. - **B+/B**: Good quality, manageable debt
  249. - **C+/C**: Needs improvement
  250. - **D/F**: Significant technical debt
  251. ### Mutation Testing
  252. Validate test suite effectiveness:
  253. ```bash
  254. pmat mutate --target src/lib.rs # Single file
  255. pmat mutate --target src/ --threshold 85 # Quality gate
  256. pmat mutate --failures-only # CI optimization
  257. ```
  258. **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)
  259. ### Repository Health Scoring
  260. Evidence-based quality metrics (0-289 scale, 11 categories):
  261. ```bash
  262. pmat rust-project-score # Fast mode (~3 min)
  263. pmat rust-project-score --full # Comprehensive (~10-15 min)
  264. pmat repo-score . --deep # Full git history
  265. ```
  266. ### Workflow Prompts
  267. Pre-configured AI prompts enforcing EXTREME TDD:
  268. ```bash
  269. pmat prompt --list # Available prompts
  270. pmat prompt code-coverage # 85%+ coverage enforcement
  271. pmat prompt debug # Five Whys analysis
  272. pmat prompt quality-enforcement # All quality gates
  273. ```
  274. ### Git History RAG
  275. Search git history by intent using TF-IDF semantic embeddings:
  276. ```bash
  277. # Fuse git history into code search
  278. pmat query "fix memory leak" -G
  279. # Search with churn, clones, entropy, faults
  280. pmat query "error handling" --churn --duplicates --entropy --faults
  281. ```
  282. ```bash
  283. # Run the example
  284. cargo run --example git_history_demo
  285. ```
  286. ### Git Hooks
  287. Automatic quality enforcement:
  288. ```bash
  289. pmat hooks install # Install pre-commit hooks
  290. pmat hooks install --tdg-enforcement # With TDG quality gates
  291. pmat hooks status # Check hook status
  292. ```
  293. ### Compliance Governance (`pmat comply`)
  294. 162 automated checks across code quality, best practices, and governance:
  295. ```bash
  296. pmat comply check # Run all compliance checks
  297. pmat comply check --strict # Exit non-zero on failure
  298. pmat comply check --format json # Machine-readable output
  299. pmat comply migrate # Update to latest version
  300. ```
  301. **Key Checks:**
  302. - **CB-200**: TDG Grade Gate — blocks on definitions below the minimum grade (default `A`). Reads the index `pmat query` built; it never builds or rewrites one, and reports Skip / "Not measured" when `.pmat/context.db` is absent
  303. - **CB-304**: Dead code percentage enforcement
  304. - **CB-400**: Shell/Makefile quality via bashrs
  305. - **CB-500**: Rust best practices (30+ patterns)
  306. - **CB-600**: Lua best practices
  307. - **CB-900**: Markdown link validation
  308. - **CB-1000**: MLOps model quality
  309. **Provable-Contracts Enforcement (CB-1200..1210):**
  310. - **CB-1208**: Binding existence — verifies `binding.yaml` functions exist in `src/`, detects ghost bindings (L0-L3 enforcement levels)
  311. - **CB-1209**: Contract trait enforcement — checks `tests/contract_traits.rs` for compiler-verified trait impls (13 kernel traits)
  312. - **CB-1210**: Precondition quality — flags mass-generated boilerplate and missing postconditions
  313. Configure via `.pmat.yaml`:
  314. ```yaml
  315. comply:
  316. thresholds:
  317. min_tdg_grade: "A" # CB-200 floor; `.pmat-gates.toml` [tdg] min_grade overrides this
  318. pv_lint_is_error: true # CB-1201: FAIL on pv lint failure
  319. min_binding_existence: 95 # CB-1208: 95% binding verification
  320. require_all_traits: true # CB-1209: 13/13 traits required
  321. min_kani_coverage: 20 # CB-1206: minimum Kani proof %
  322. ```
  323. ### Infrastructure Score (`pmat infra-score`)
  324. CI/CD quality scoring (0-100 + 10 bonus for provable-contracts):
  325. ```bash
  326. pmat infra-score # Text output
  327. pmat infra-score --format json # Machine-readable
  328. pmat infra-score -v --failures-only # Show only failing checks
  329. ```
  330. **Categories:** Workflow Architecture (25pts), Build Reliability (25pts),
  331. Quality Pipeline (20pts), Deployment & Release (15pts), Supply Chain (15pts),
  332. Provable Contracts bonus (10pts).
  333. ### Document Search (`pmat query --docs`)
  334. Search documentation files (Markdown, text, YAML) alongside code:
  335. ```bash
  336. pmat query "authentication" --docs # Code + docs results
  337. pmat query "deployment" --docs-only # Only documentation
  338. pmat query "API endpoints" --no-docs # Exclude docs (default)
  339. ```
  340. ### Autonomous Kaizen (`pmat kaizen`)
  341. Toyota Way continuous improvement — scan, auto-fix, commit:
  342. ```bash
  343. pmat kaizen --dry-run # Scan only (no changes)
  344. pmat kaizen # Apply safe auto-fixes
  345. pmat kaizen --push # Fix, commit, and push (use --no-commit to skip)
  346. pmat kaizen --format json -o report.json # CI/CD integration
  347. # Cross-stack mode: scan all batuta stack crates in one invocation
  348. pmat kaizen --cross-stack --dry-run # Scan all crates
  349. pmat kaizen --cross-stack # Fix and commit per-crate
  350. pmat kaizen --cross-stack -f json # Grouped JSON report
  351. ```
  352. ### Function Extraction (`pmat extract`)
  353. Extract function boundaries with metadata:
  354. ```bash
  355. pmat extract --list src/lib.rs # Function/struct/enum/trait boundaries, as JSON
  356. ```
  357. ## Examples
  358. ### Generate Context for AI
  359. ```bash
  360. # For Claude Code
  361. pmat context --output context.md --format llm-optimized
  362. # With semantic search
  363. pmat embed sync --path ./src
  364. pmat semantic search "error handling patterns"
  365. ```
  366. ### CI/CD Integration
  367. ```yaml
  368. # Add to your CI pipeline
  369. steps:
  370. - uses: actions/checkout@v4
  371. - run: cargo install pmat
  372. - run: pmat analyze tdg --fail-on-violation --min-grade B
  373. - run: pmat mutate --target src/ --threshold 80
  374. ```
  375. ### Quality Baseline Workflow
  376. ```bash
  377. # 1. Create baseline
  378. pmat tdg baseline create --output .pmat/baseline.json
  379. # 2. Check for regressions
  380. pmat tdg check-regression \
  381. --baseline .pmat/baseline.json \
  382. --max-score-drop 5.0 \
  383. --fail-on-regression
  384. ```
  385. ## Architecture
  386. ```
  387. pmat/
  388. ├── src/
  389. │ ├── cli/ Command handlers and dispatchers
  390. │ ├── services/ Analysis engines (TDG, SATD, complexity, agent context)
  391. │ ├── mcp_server/ MCP protocol server
  392. │ ├── mcp_pmcp/ PMCP protocol integration
  393. │ └── models/ Configuration and data models
  394. ├── examples/ 113 runnable examples
  395. └── docs/
  396. └── specifications/ Technical specs
  397. ```
  398. ## Quality
  399. | Metric | Value |
  400. |--------|-------|
  401. | Tests | 21,200+ passing |
  402. | Coverage | 99.66% |
  403. | Mutation Score | >80% |
  404. | Languages | 20 supported + MLOps model formats |
  405. | MCP Tools | 20 available |
  406. ### Falsifiable Quality Commitments
  407. Per [Popper's demarcation criterion](https://en.wikipedia.org/wiki/Demarcation_problem), all claims are measurable and testable:
  408. | Commitment | Threshold | Verification Method |
  409. |------------|-----------|---------------------|
  410. | **Context Generation** | < 5 seconds for 10K LOC project | `time pmat context` on test corpus |
  411. | **Memory Usage** | < 500 MB for 100K LOC analysis | Measured via `heaptrack` in CI |
  412. | **Test Coverage** | ≥ 85% line coverage | `cargo llvm-cov` (CI enforced) |
  413. | **Mutation Score** | ≥ 80% killed mutants | `pmat mutate --threshold 80` |
  414. | **Build Time** | < 3 minutes incremental | `cargo build --timings` |
  415. | **CI Pipeline** | < 15 minutes total | GitHub Actions workflow timing |
  416. | **Binary Size** | < 50 MB release binary | `ls -lh target/release/pmat` |
  417. | **Language Parsers** | All 20 languages parse without panic | Fuzz testing in CI |
  418. **How to Verify:**
  419. ```bash
  420. # Run self-assessment with Popper Falsifiability Score
  421. pmat popper-score --verbose
  422. # Individual commitment verification
  423. cargo llvm-cov --html # Coverage ≥85%
  424. pmat mutate --threshold 80 # Mutation ≥80%
  425. cargo build --timings # Build time <3min
  426. ```
  427. **Failure = Regression:** Any commitment violation blocks CI merge.
  428. ### Benchmark Results (Statistical Rigor)
  429. All benchmarks use Criterion.rs with proper statistical methodology:
  430. | Operation | Mean | 95% CI | Std Dev | Sample Size |
  431. |-----------|------|--------|---------|-------------|
  432. | Context (1K LOC) | 127ms | [124, 130] | ±12.3ms | n=1000 runs |
  433. | Context (10K LOC) | 1.84s | [1.79, 1.90] | ±156ms | n=500 runs |
  434. | TDG Scoring | 156ms | [148, 164] | ±18.2ms | n=500 runs |
  435. | Complexity Analysis | 23ms | [22, 24] | ±3.1ms | n=1000 runs |
  436. **Comparison Baselines (vs. Alternatives):**
  437. | Metric | PMAT | ctags | tree-sitter | Effect Size |
  438. |--------|------|-------|-------------|-------------|
  439. | 10K LOC parsing | 1.84s | 0.3s | 0.8s | d=0.72 (medium) |
  440. | Memory (10K LOC) | 287MB | 45MB | 120MB | - |
  441. | Semantic depth | Full | Syntax only | AST only | - |
  442. See [docs/BENCHMARKS.md](docs/BENCHMARKS.md) for complete statistical analysis.
  443. ### ML/AI Reproducibility
  444. PMAT uses ML for semantic search and embeddings. All ML operations are reproducible:
  445. **Random Seed Management:**
  446. - Embedding generation uses fixed seed (SEED=42) for deterministic outputs
  447. - Clustering operations use fixed seed (SEED=12345)
  448. - Seeds documented in [docs/ml/REPRODUCIBILITY.md](docs/ml/REPRODUCIBILITY.md)
  449. **Model Artifacts:**
  450. - Pre-trained models from HuggingFace (all-MiniLM-L6-v2)
  451. - Model versions pinned in Cargo.toml
  452. - Hash verification on download
  453. ## Dataset Sources
  454. PMAT does not train models but uses these data sources for evaluation:
  455. | Dataset | Source | Purpose | Size |
  456. |---------|--------|---------|------|
  457. | CodeSearchNet | GitHub/Microsoft | Semantic search benchmarks | 2M functions |
  458. | PMAT-bench | Internal | Regression testing | 500 queries |
  459. Data provenance and licensing documented in [docs/ml/REPRODUCIBILITY.md](docs/ml/REPRODUCIBILITY.md).
  460. ## Sovereign Stack
  461. PMAT is built on the PAIML Sovereign Stack - pure-Rust, SIMD-accelerated libraries:
  462. | Library | Purpose | Version |
  463. |---------|---------|---------|
  464. | [aprender](https://crates.io/crates/aprender) | ML library (text similarity, clustering, topic modeling) | 0.64 |
  465. | [aprender-graph](https://crates.io/crates/aprender-graph) | CSR graph database (PageRank, Louvain) | 0.64 |
  466. | [aprender-db](https://crates.io/crates/aprender-db) | Columnar analytics database (lib `trueno_db`, optional) | 0.64 |
  467. | [aprender-rag](https://crates.io/crates/aprender-rag) | RAG pipeline with VectorStore | 0.64 |
  468. | [aprender-viz](https://crates.io/crates/aprender-viz) | Terminal graph visualization | 0.64 |
  469. | [aprender-compute](https://crates.io/crates/aprender-compute) | SIMD/GPU compute for matrix operations (lib `trueno`) | 0.64 |
  470. | [aprender-zram-core](https://crates.io/crates/aprender-zram-core) | SIMD LZ4/ZSTD compression (optional) | 0.64 |
  471. | [aprender-contracts](https://crates.io/crates/aprender-contracts) | Provable contracts (with `aprender-contracts-macros`) | 0.64 |
  472. | [pmcp](https://crates.io/crates/pmcp) | MCP protocol SDK (streamable HTTP transport) | 2.17 |
  473. | **pmat** | Code analysis toolkit | 3.40.0 |
  474. **Key Benefits:**
  475. - Pure Rust (no C dependencies, no FFI)
  476. - SIMD-first (AVX2, AVX-512, NEON auto-detection)
  477. - 2-4x speedup on graph algorithms via aprender adapter
  478. ## Documentation
  479. - [PMAT Book](https://paiml.github.io/pmat-book/) - Complete guide
  480. - [API Reference](https://docs.rs/pmat) - Rust API docs
  481. - [MCP Tools](docs/mcp/TOOLS.md) - MCP integration guide
  482. - [Specifications](docs/specifications/) - Technical specs
  483. - 🤖 [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
  484. ## Contributing
  485. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and pull request guidelines.
  486. ## See Also
  487. - [Cookbook](examples/) — 113 runnable examples
  488. ## License
  489. MIT License - see [LICENSE](LICENSE) for details.
  490. ---
  491. <div align="center">
  492. <sub>Built with Extreme TDD | Part of <a href="https://github.com/paiml">PAIML</a></sub>
  493. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.