Use via MCP

Integrate axm-audit into AI agent workflows through the AXM MCP server.

Setup

The audit tool is served by axm-mcp. If you haven't connected the server yet, see the axm-mcp Quick Start — one command connects the whole toolchain. No per-package install needed.

Usage

From an AI agent

Call the audit MCP tool with the project path:

JSON

{"tool": "audit", "kwargs": {"path": "/path/to/project"}}

The result includes both a structured data dict (via format_agent) and a compact text summary (via format_agent_text) optimised for token count. The text field uses ✓/✗ lines for ~55-60% token savings:

JSON

{
  "data": {
    "score": 85.0,
    "grade": "B",
    "passed": ["QUALITY_LINT: Lint score: 100/100 (0 issues)"],
    "failed": [{"rule_id": "...", "details": {...}, "fix_hint": "..."}]
  },
  "text": "audit | B 85 | 1 pass · 1 fail\n✓ QUALITY_LINT\n✗ ... details ..."
}

One-shot verification

verify is a built-in of the axm-mcp server (not an axm-audit tool) that wraps audit for a combined quality + governance check. Use it instead of audit when you want everything in one call:

JSON

{"tool": "verify", "kwargs": {"path": "/path/to/project"}}

This runs audit + init_check + AST enrichment in a single call.

Structured test runner

Use audit_test for structured, token-efficient test feedback:

JSON

{"tool": "audit_test", "kwargs": {"path": "/path/to/project"}}

Parameter	Type	Default	Description
`path`	`str`	`"."`	Path to project root
`files`	`list[str]`	`None`	Specific test files to run
`markers`	`list[str]`	`None`	Pytest markers to filter
`stop_on_first`	`bool`	`True`	Stop on first failure

The result includes a structured data dict (full TestReport fields) and a compact text summary via format_audit_test_text, optimised for token count (~27 tokens green path, ~240 tokens with failures):

Text Only

audit_test | ✅ 42 passed | 1.2s | cov 95.0%

Failure output adds ✗ blocks and a coverage section for files below 95%:

Text Only

audit_test | ❌ 10 passed · 2 failed | 3.4s | cov 88.0%
✗ test_foo.py::test_bar (foo.py:42)
  AssertionError: expected 5 got 3
    assert 5 == 3
cov< utils.py 80%

Deterministic auto-fix

Use audit_fix to run the deterministic test-suite fix pipeline:

JSON

{"tool": "audit_fix", "kwargs": {"path": "/path/to/project", "apply": false}}

Parameter	Type	Default	Description
`path`	`str`	`"."`	Path to project root
`apply`	`bool`	`False`	If `True`, mutate the tree; otherwise dry-run
`rules`	`list[str]`	`None`	Optional list of rule ids to filter the pipeline

The result includes a structured data dict (planned/applied FileOp entries, unfixable findings, warnings, per-kind counts) and a human-readable text summary via format_report. Use apply=False to preview the plan before mutating files.

Output Format

The MCP tool returns a structured result:

Key	Type	Content
`score`	`float`	Composite quality score (0–100)
`grade`	`str`	Letter grade A–F
`passed`	`list`	Strings or dicts with actionable details
`failed`	`list`	Dicts with `rule_id`, `message`, `details`, `fix_hint`

For scoring details, see Scoring & Grades.