PAIML MCP Agent Toolkit

PMAT

为任意代码库零配置生成 AI 上下文

---

目录

• 什么是 PMAT？
• 安装
• MCP 服务
• 用法
• 功能
• 架构

什么是 PMAT？

PMAT（实用多语言 Agent 工具包）提供代码质量分析和生成适用于 AI 的上下文所需的一切：

• 上下文生成 - 为 Claude、GPT 和其他大模型进行深度分析
• 技术债务评级 - 使用 6 项正交指标进行 A+ 到 F 级评分
• 变异测试 - 验证测试套件质量（杀死率达 85%+）
• 代码库评分 - 定量评估健康状况（0-289 分，涵盖 11 个类别）
• Git 历史 RAG - 使用 RRF 融合，在提交历史中进行语义搜索
• 语义搜索 - 通过自然语言发现代码
• 合规治理 - 在代码质量、最佳实践和可复现性方面执行 157 项检查
• 契约式设计 - 提供 Toyota Way 契约配置文件，支持检查点验证和恢复协议
• 自主 Kaizen - 通过自动修复和提交，实现 Toyota Way 持续改进
• MCP 集成 - 为 Claude Code、Cline 和 AI Agent 提供 20 个工具，通过 stdio 和 HTTP 使用（功能完全一致），并已针对并发多 Agent（ultracode）工作流进行端到端验证 — 请参阅 MCP 服务
• 质量门禁 - 提供提交前钩子、CI/CD 集成和 .pmat-gates.toml 配置
• 20+ 种语言 - Rust、TypeScript、Python、Go、Java、C/C++、Lua、Lean 等

作为 PAIML Stack 的一部分，遵循 Toyota Way 质量原则（Jidoka、Genchi Genbutsu、Kaizen）。

带注释的代码搜索

每个结果均包含 TDG 评级、Big-O 复杂度、git 变更频率、代码克隆、模式多样性、故障注释、调用图和语法高亮源码。

安装

# Install from crates.io
cargo install pmat

macOS 用户须知： 如果通过 rustup 安装时遇到问题，建议在运行 cargo install pmat 之前使用 Homebrew 安装或更新 Rust：brew install rust。

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

MCP 服务

PMAT 首先是 MCP 服务，其次才是 CLI。一个二进制文件提供 三个接口，它们共用一个工具注册表——你选择的是接口，而不是功能集。

接口	启动方式	适用场景
CLI	pmat analyze complexity --path .	人类或 shell 脚本读取输出。
通过 stdio 使用 MCP	pmat --mode mcp	MCP 客户端将 pmat 本身作为子进程启动——Claude Code、Claude Desktop、Cline。一个客户端，一个进程，无需端口，无需令牌。
通过 HTTP 使用 MCP	pmat serve --transport http --port 8765	一个长期运行的服务，供多个客户端——或另一台机器——连接。可流式传输的 HTTP、Bearer 身份验证。

3.32.0 的新增内容： mcp-http 已移入默认功能集。现在运行 cargo install pmat 即可获得 HTTP 传输；以前的 --features mcp-http 操作已不再需要。编译时加入该传输不会打开套接字——只有 pmat serve 才会绑定套接字。

快速入门 — stdio

Claude Code 会将 pmat 作为子进程启动。无需保持运行，也无需进行身份验证。

cargo install pmat
claude mcp add --scope user pmat -- pmat --mode mcp
claude mcp list
# pmat: pmat --mode mcp - ✔ Connected

Claude Desktop 使用相同的命令，但以 JSON 格式写入其自己的 claude_desktop_config.json：

{
  "mcpServers": {
    "pmat": { "command": "pmat", "args": ["--mode", "mcp"] }
  }
}

对于无法传递标志的客户端，运行 MCP_VERSION=1 pmat 会启动相同的服务。无需任何客户端即可对 stdio 接口进行冒烟测试：

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | pmat --mode mcp 2>/dev/null | jq -r '.result.tools | length'
# 19

快速入门 — HTTP

一个服务，多个客户端。复制并粘贴整个代码块：

cargo install pmat

export PMAT_MCP_HTTP_TOKEN='pmat-mcp-demo-token-0123456789'   # >= 16 chars; use your own
pmat serve --transport http --port 8765 &
#   pmat MCP (streamable HTTP) listening on http://127.0.0.1:8765/
#     auth: Bearer, from PMAT_MCP_HTTP_TOKEN; unauthenticated requests get 401
#     tools: 20
sleep 2

claude mcp add --scope user --transport http pmat http://127.0.0.1:8765/ \
  --header "Authorization: Bearer $PMAT_MCP_HTTP_TOKEN"
claude mcp list
# pmat: http://127.0.0.1:8765/ (HTTP) - ✔ Connected

除非传入 --host，否则服务会绑定到 127.0.0.1。若要从另一台机器访问，请绑定到可从外部路由的地址，并将 PMAT_MCP_HTTP_TOKEN 视为真正的机密——工具接口可以读取和分析服务进程能够读取的任何路径。

四个每次都会浪费一小时的易错点

1. MCP 服务位于根路径 /，而不是 /mcp。 没有路径前缀。

for p in / /mcp /health; do
  printf '%-7s %s\n' "$p" "$(curl -s -o /dev/null -w '%{http_code}' -X POST "http://127.0.0.1:8765$p" \
    -H "Authorization: Bearer $PMAT_MCP_HTTP_TOKEN" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json, text/event-stream" \
    -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}')"
done
# /       200
# /mcp    404
# /health 404

2. PMAT_MCP_HTTP_TOKEN 是必需的，且长度至少为 16 个字符。 若长度不足，服务会拒绝启动，而不会退回到未经过身份验证的服务模式——底层 pmcp 传输在未配置身份验证提供程序时会响应每个请求，因此“没有令牌”必须意味着“没有服务”。未提供令牌或令牌错误的请求会收到 401。

PMAT_MCP_HTTP_TOKEN=too-short-123 pmat serve --transport http --port 8765
# Error: PMAT_MCP_HTTP_TOKEN must be at least 16 characters; got 13

3. 手动编写的客户端必须发送 Accept: application/json, text/event-stream。 可流式传输的传输层会拒绝缺少此标头的请求，而 curl -f 会将其变成没有任何提示的空字符串——因此调试时请使用普通的 curl -s 进行探测。

curl -s -w '\n-> HTTP %{http_code}\n' -X POST http://127.0.0.1:8765/ \
  -H "Authorization: Bearer $PMAT_MCP_HTTP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
# {"jsonrpc":"2.0","error":{"code":-32700,"message":"Accept header must include application/json or text/event-stream"},"id":null}
# -> HTTP 406

4. 没有 /health 端点。 GET /health 会返回 404，因此 curl -f .../health 就绪循环永远不会变绿，也不会说明原因。请改用真实的 tools/list 调用进行探测：

curl -s -X POST http://127.0.0.1:8765/ \
  -H "Authorization: Bearer $PMAT_MCP_HTTP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | jq -r '.result.tools | length'
# 19

这里不涉及 MCP 会话 ID：initialize 不会返回 Mcp-Session-Id 标头，而且 tools/call 可以直接使用——无论之前是否调用过 initialize。

HTTP 并非精简接口

两种传输都基于同一个注册表构建，因此 HTTP 提供全部 20 个工具，而非其中一部分。tools/list 的载荷逐字节相同：

printf '%s\n%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"p","version":"1"}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  | pmat --mode mcp 2>/dev/null \
  | jq -Sc 'select(.id==2)|.result.tools|sort_by(.name)' > /tmp/pmat-stdio-tools.json

curl -s -X POST http://127.0.0.1:8765/ \
  -H "Authorization: Bearer $PMAT_MCP_HTTP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | jq -Sc '.result.tools|sort_by(.name)' > /tmp/pmat-http-tools.json

cmp /tmp/pmat-stdio-tools.json /tmp/pmat-http-tools.json && echo "identical"
# identical

这 19 个工具是：analyze_complexity、analyze_satd、analyze_dead_code、analyze_dag、analyze_deep_context、analyze_big_o、analyze_reachability、analyze_hardcoded_paths、analyze_vacuous_tests、quality_gate、quality_proxy、generate_context、scaffold_project、git_operation、pmat_query_code、pmat_get_function、pmat_find_similar、pmat_index_stats、pdmt_deterministic_todos。名称和描述也作为经过机器校验的清单 mcp.json 提交在仓库根目录中，该清单由服务自身的注册信息重新生成，因此不会与两种传输实际提供的内容发生偏差。

尚未实现的传输方式

--transport 也接受 web-socket、http-sse、both 和 all。这些方式均未实现；每种方式都会以退出码 2 退出并说明原因。只有 http 能提供服务。

pmat serve --transport web-socket --port 8765
# error: pmat serve --transport websocket is not yet implemented

--transport 没有 stdio 选项——传入该值会导致 clap 错误。stdio 的启动方式是 pmat --mode mcp。

用法

# Generate AI-ready context
pmat context --output context.md --format llm-optimized

# Analyze code complexity
pmat analyze complexity

# Grade technical debt (A+ through F)
pmat analyze tdg

# Score repository health
pmat repo-score .

# Pre-flight verify before committing (CI-faithful: fmt + complexity + satd + clippy + tests)
pmat verify --format json

# Run mutation testing
pmat mutate --target src/

# Start the MCP server over stdio, for Claude Code, Cline, etc. (see "MCP Server" above)
pmat --mode mcp

自主 Agent 提交前检查（pmat verify）

pmat verify 会快速失败地运行 CI 强制执行的完整门禁集——format、complexity、satd、clippy、tests，并生成机器可读的输出，让 Agent 在提交前就能确认 “本地通过 ⇒ CI 通过”。标准循环：edit → pmat verify --format json → fix on red → commit on green。请参阅 docs/agent-instructions/autonomous-verify-loop.md。

经 Ultracode 验证

PMAT 版本通过 ultracode 进行自测。ultracode 是 Claude Code 的多 Agent 动态工作流编排工具，同时用作测试框架和目标工作负载：

• 完整 CLI 扫描：每个版本都由并行 Agent 集群执行 111 条命令
• MCP 接口：通过 stdio JSON-RPC 验证全部 20 个工具——使用根据架构生成的参数逐一调用工具，通过 8 路并发服务会话操作同一工作树（零锁错误，零残留临时文件），并进行字节级分帧检查（stdout 仅包含 JSON-RPC）——另外还会检查传输一致性，确保 HTTP tools/list 负载与 stdio 负载逐字节相同
• 确定性：TDG 基线和惩罚归因在多次运行中序列化后逐字节相同，因此独立 Agent 会达成一致，不会因排序噪声而产生分歧
• 并发安全缓存：使用 PID 唯一的临时文件，通过原子重命名到位并清理过期孤立文件；记录指标时使用咨询锁

每次扫描发现的问题都会由持怀疑态度的 Agent 进行对抗式复核，确认后才会据此修复——请参阅 pmat book 中的版本案例研究。

功能

上下文生成

为 AI 助手生成全面的上下文：

pmat context                           # Basic analysis
pmat context --format llm-optimized    # AI-optimized output
pmat context --include-large-files     # Include files >500KB normally skipped

技术债务评级（TDG）

使用六项正交指标准确评估质量：

pmat analyze tdg                       # Project-wide grade
pmat analyze tdg --include-components  # Per-component breakdown
pmat tdg baseline create               # Create quality baseline
pmat tdg check-regression              # Detect quality degradation

评级标准：

• A+/A：质量卓越，债务极少
• B+/B：质量良好，债务可控
• C+/C：需要改进
• D/F：技术债务严重

变异测试

验证测试套件的有效性：

pmat mutate --target src/lib.rs        # Single file
pmat mutate --target src/ --threshold 85  # Quality gate
pmat mutate --failures-only            # CI optimization

**支持的语言：**Rust、Python、TypeScript、JavaScript、Go、C/C++、C#、Lua、Lean、Java、Kotlin、Ruby、Swift、PHP、Bash、SQL、Scala、YAML、Markdown，以及 MLOps 模型格式（GGUF、SafeTensors、APR）

仓库健康评分

基于证据的质量指标（0-289 分，11 个类别）：

pmat rust-project-score                # Fast mode (~3 min)
pmat rust-project-score --full         # Comprehensive (~10-15 min)
pmat repo-score . --deep               # Full git history

工作流提示词

预配置的 AI 提示词，强制执行极限 TDD：

pmat prompt --list                     # Available prompts
pmat prompt code-coverage              # 85%+ coverage enforcement
pmat prompt debug                      # Five Whys analysis
pmat prompt quality-enforcement        # All quality gates

Git 历史 RAG

使用 TF-IDF 语义嵌入，按意图搜索 Git 历史：

# Fuse git history into code search
pmat query "fix memory leak" -G

# Search with churn, clones, entropy, faults
pmat query "error handling" --churn --duplicates --entropy --faults

# Run the example
cargo run --example git_history_demo

Git 钩子

自动执行质量要求：

pmat hooks install                     # Install pre-commit hooks
pmat hooks install --tdg-enforcement   # With TDG quality gates
pmat hooks status                      # Check hook status

合规治理（pmat comply）

针对代码质量、最佳实践和治理的 162 项自动检查：

pmat comply check                      # Run all compliance checks
pmat comply check --strict             # Exit non-zero on failure
pmat comply check --format json        # Machine-readable output
pmat comply migrate                    # Update to latest version

主要检查项：

• CB-200：TDG 评级门禁——定义的评级低于最低要求（默认 A）时阻止操作。读取由 pmat query 构建的索引；不会构建或重写索引；如果 .pmat/context.db 不存在，则报告跳过 /“未测量”
• CB-304：死代码比例执行
• CB-400：通过 bashrs 检查 Shell/Makefile 质量
• CB-500：Rust 最佳实践（30 多种模式）
• CB-600：Lua 最佳实践
• CB-900：Markdown 链接验证
• CB-1000：MLOps 模型质量

可证明契约执行（CB-1200..1210）：

• CB-1208：绑定存在性——验证 binding.yaml 中的函数是否存在于 src/，并检测虚假绑定（L0-L3 执行级别）
• CB-1209：契约 Trait 执行——检查 tests/contract_traits.rs 中经编译器验证的 Trait 实现（13 个内核 Trait）
• CB-1210：前置条件质量——标记批量生成的样板代码和缺失的后置条件

通过 .pmat.yaml 配置：

comply:
  thresholds:
    min_tdg_grade: "A"          # CB-200 floor; `.pmat-gates.toml` [tdg] min_grade overrides this
    pv_lint_is_error: true        # CB-1201: FAIL on pv lint failure
    min_binding_existence: 95     # CB-1208: 95% binding verification
    require_all_traits: true      # CB-1209: 13/13 traits required
    min_kani_coverage: 20         # CB-1206: minimum Kani proof %

基础设施评分（pmat infra-score）

CI/CD 质量评分（0–100 分，provable-contracts 额外加 10 分）：

pmat infra-score                       # Text output
pmat infra-score --format json         # Machine-readable
pmat infra-score -v --failures-only    # Show only failing checks

**类别：**工作流架构（25 分）、构建可靠性（25 分）、 质量流水线（20 分）、部署与发布（15 分）、供应链（15 分）、 可证明契约加分（10 分）。

文档搜索（pmat query --docs）

在代码之外搜索文档文件（Markdown、文本、YAML）：

pmat query "authentication" --docs          # Code + docs results
pmat query "deployment" --docs-only         # Only documentation
pmat query "API endpoints" --no-docs        # Exclude docs (default)

自主 Kaizen（pmat kaizen）

丰田之道的持续改进——扫描、自动修复、提交：

pmat kaizen --dry-run                  # Scan only (no changes)
pmat kaizen                            # Apply safe auto-fixes
pmat kaizen --push                     # Fix, commit, and push (use --no-commit to skip)
pmat kaizen --format json -o report.json  # CI/CD integration

# Cross-stack mode: scan all batuta stack crates in one invocation
pmat kaizen --cross-stack --dry-run    # Scan all crates
pmat kaizen --cross-stack              # Fix and commit per-crate
pmat kaizen --cross-stack -f json      # Grouped JSON report

函数提取（pmat extract）

提取函数边界及元数据：

pmat extract --list src/lib.rs         # Function/struct/enum/trait boundaries, as JSON

示例

为 AI 生成上下文

# For Claude Code
pmat context --output context.md --format llm-optimized

# With semantic search
pmat embed sync --path ./src
pmat semantic search "error handling patterns"

CI/CD 集成

# Add to your CI pipeline
steps:
  - uses: actions/checkout@v4
  - run: cargo install pmat
  - run: pmat analyze tdg --fail-on-violation --min-grade B
  - run: pmat mutate --target src/ --threshold 80

质量基线工作流

# 1. Create baseline
pmat tdg baseline create --output .pmat/baseline.json

# 2. Check for regressions
pmat tdg check-regression \
  --baseline .pmat/baseline.json \
  --max-score-drop 5.0 \
  --fail-on-regression

架构

pmat/
├── src/
│   ├── cli/          Command handlers and dispatchers
│   ├── services/     Analysis engines (TDG, SATD, complexity, agent context)
│   ├── mcp_server/   MCP protocol server
│   ├── mcp_pmcp/     PMCP protocol integration
│   └── models/       Configuration and data models
├── examples/         113 runnable examples
└── docs/
    └── specifications/  Technical specs

质量

指标	值
测试	21,200+ 项通过
覆盖率	99.66%
变异分数	>80%
语言	支持 20 种语言及 MLOps 模型格式
MCP 工具	提供 20 个

可证伪的质量承诺

根据 Popper 的划界标准，所有声明都可测量、可测试：

承诺	阈值	验证方法
上下文生成	10K LOC 项目 < 5 秒	在测试语料库上运行 time pmat context
内存用量	分析 100K LOC 时 < 500 MB	在 CI 中通过 heaptrack 测量
测试覆盖率	行覆盖率 ≥ 85%	cargo llvm-cov（由 CI 强制执行）
变异分数	杀死的变异体 ≥ 80%	pmat mutate --threshold 80
构建时间	增量构建 < 3 分钟	cargo build --timings
CI 流水线	总用时 < 15 分钟	GitHub Actions 工作流计时
二进制大小	发布版二进制 < 50 MB	ls -lh target/release/pmat
语言解析器	20 种语言均可解析且不发生 panic	在 CI 中进行模糊测试

验证方法：

# Run self-assessment with Popper Falsifiability Score
pmat popper-score --verbose

# Individual commitment verification
cargo llvm-cov --html        # Coverage ≥85%
pmat mutate --threshold 80   # Mutation ≥80%
cargo build --timings        # Build time <3min

**失败 = 回归：**任何承诺未达标都会阻止 CI 合并。

基准测试结果（严谨的统计方法）

所有基准测试均使用 Criterion.rs，并采用规范的统计方法：

操作	均值	95% 置信区间	标准差	样本量
上下文（1K LOC）	127ms	[124, 130]	±12.3ms	n=1000 次运行
上下文（10K LOC）	1.84s	[1.79, 1.90]	±156ms	n=500 次运行
TDG 评分	156ms	[148, 164]	±18.2ms	n=500 次运行
复杂度分析	23ms	[22, 24]	±3.1ms	n=1000 次运行

对比基线（与替代方案比较）：

指标	PMAT	ctags	tree-sitter	效应量
解析 10K LOC	1.84s	0.3s	0.8s	d=0.72（中等）
内存（10K LOC）	287MB	45MB	120MB	-
语义深度	完整	仅语法	仅 AST	-

完整统计分析请参阅 docs/BENCHMARKS.md。

ML/AI 可复现性

PMAT 使用 ML 进行语义搜索和嵌入。所有 ML 操作均可复现：

随机种子管理：

• 嵌入生成使用固定种子（SEED=42），确保输出具有确定性
• 聚类操作使用固定种子（SEED=12345）
• 种子记录在 docs/ml/REPRODUCIBILITY.md 中

模型制品：

• 使用来自 HuggingFace 的预训练模型（all-MiniLM-L6-v2）
• 在 Cargo.toml 中固定模型版本
• 下载时进行哈希验证

数据集来源

PMAT 不训练模型，但会使用以下数据源进行评估：

数据集	来源	用途	大小
CodeSearchNet	GitHub/Microsoft	语义搜索基准测试	2M 个函数
PMAT-bench	内部	回归测试	500 个查询

数据来源和许可信息记录在 docs/ml/REPRODUCIBILITY.md 中。

主权技术栈

PMAT 基于 PAIML 主权技术栈构建，采用纯 Rust 编写的 SIMD 加速库：

库	用途	版本
aprender	机器学习库（文本相似度、聚类、主题建模）	0.64
aprender-graph	CSR 图数据库（PageRank、Louvain）	0.64
aprender-db	列式分析数据库（库 trueno_db，可选）	0.64
aprender-rag	带有 VectorStore 的 RAG 工作流	0.64
aprender-viz	终端图可视化	0.64
aprender-compute	用于矩阵运算的 SIMD/GPU 计算（库 trueno）	0.64
aprender-zram-core	SIMD LZ4/ZSTD 压缩（可选）	0.64
aprender-contracts	可证明合约（搭配 aprender-contracts-macros）	0.64
pmcp	MCP 协议 SDK（可流式传输的 HTTP 传输）	2.17
pmat	代码分析工具包	3.40.0

主要优势：

• 纯 Rust（无 C 依赖，无 FFI）
• SIMD 优先（自动检测 AVX2、AVX-512、NEON）
• 通过 aprender 适配器，图算法速度提升 2-4 倍

文档

• PMAT 手册 - 完整指南
• API 参考 - Rust API 文档
• MCP 工具 - MCP 集成指南
• 规范 - 技术规范
• 🤖 Coursera Hugging Face AI Development Specialization - 使用纯 Rust 和 Hugging Face 构建生产级 AI 系统

贡献

开发环境设置、测试和拉取请求指南请参阅 CONTRIBUTING.md。

另请参阅

• 示例集 — 113 个可运行示例

许可证

MIT 许可证 - 详情请参阅 LICENSE。

---