agents/mcp/salt_test/README.md
Model Context Protocol (MCP) server for Salt testing tools.
This MCP server exposes Salt testing capabilities to AI agents, enabling:
pytest_runRun pytest directly with a test path.
Parameters:
test_path (required): Test file, directory, or specific testvenv_path (optional): Path to virtual environment (defaults to ./venv310)extra_args (optional): Additional pytest argumentsExample:
{
"test_path": "tests/pytests/unit/test_loader.py::test_load_modules",
"extra_args": ["-v", "-x"]
}
pytest_last_failedRe-run only tests that failed in the last run.
Parameters:
venv_path (optional): Path to virtual environmentextra_args (optional): Additional pytest argumentspytest_patternRun tests matching a pattern (uses pytest -k).
Parameters:
pattern (required): Test name patterntest_path (optional): Path to search withinvenv_path (optional): Virtual environment pathextra_args (optional): Additional argumentsExample:
{
"pattern": "auth",
"extra_args": ["-v"]
}
pytest_listList test files matching a glob pattern.
Parameters:
pattern (optional): Glob pattern (defaults to "test_*.py")path (optional): Base path to searchci_pr_failuresGet all failing tests from a PR's CI runs.
Parameters:
pr_number (required): Pull request numberrepository (optional): Repository (defaults to "saltstack/salt")json_output (optional): Return as JSONExample:
{
"pr_number": 68562
}
ci_run_failuresGet failing tests from a specific CI run.
Parameters:
run_id (required): Workflow run IDrepository (optional): Repositoryjson_output (optional): Return as JSONci_failure_summaryGet a human-readable summary of PR failures.
Parameters:
pr_number (required): Pull request numberrepository (optional): Repositoryci_setup_containerSetup a container for testing (decompress dependencies, create relenv symlink).
Parameters:
container_name (required): Name of container to setuparch (optional): Architecture (x86_64 or arm64, defaults to x86_64)python_version (optional): Python version (e.g., "3.11") - determines if relenv symlink is neededExample:
{
"container_name": "salt-test-debian-11",
"arch": "x86_64",
"python_version": "3.11"
}
ci_run_testRun a test in a CI container.
Parameters:
container_name (required): Container nametest_path (required): Test path to runextra_args (optional): Additional arguments (e.g., ["--run-slow", "-x", "-v"])Example:
{
"container_name": "salt-test-debian-11",
"test_path": "tests/pytests/functional/test_version.py::test_salt_extensions_in_versions_report",
"extra_args": ["--run-slow", "-x", "-v"]
}
ci_cleanupClean up artifacts and/or containers.
Parameters:
artifacts (optional): Clean up downloaded artifactscontainers (optional): Pattern to match container names (e.g., "salt-test-*")Example:
{
"artifacts": true,
"containers": "salt-test-*"
}
ci_list_platformsList available CI container platforms.
Parameters: None
1. ci_pr_failures(pr_number=68562)
→ Returns list of failing tests by platform
2. Analyze results to identify common failures
1. ci_pr_failures(pr_number=68562)
→ Get run_id and failing test
2. Download artifacts (use existing tools container create/ts setup)
3. ci_setup_container(container_name="salt-test-debian-11", python_version="3.11")
4. ci_run_test(
container_name="salt-test-debian-11",
test_path="tests/pytests/functional/test_version.py::test_failure",
extra_args=["--run-slow", "-x", "-v"]
)
1. pytest_run(
test_path="tests/pytests/unit/test_loader.py",
extra_args=["-v", "-x"]
)
2. If failures, analyze and fix
3. pytest_last_failed()
→ Re-run only failed tests
Install MCP Python SDK:
pip install mcp
Configure Claude Code to use this server (see ../mcp-config.json)
The server will automatically use the Salt repository's tools infrastructure
Once configured, you can ask Claude:
pip install mcp)GITHUB_TOKEN or configure gh CLI)The Salt repository requires two virtual environments:
Setup venv310 (Python 3.10) - For Testing:
cd /path/to/salt/repo
python3.10 -m venv venv310
source venv310/bin/activate
pip install --upgrade pip setuptools wheel
# Install platform-specific dependencies (choose your OS):
pip install -r requirements/static/pkg/py3.10/linux.txt # Linux
pip install -r requirements/static/pkg/py3.10/darwin.txt # macOS
pip install -r requirements/static/pkg/py3.10/windows.txt # Windows
# Install pytest and tools requirements:
pip install -r requirements/pytest.txt
pip install -r requirements/static/ci/py3.10/tools.txt
# Install pre-commit and python-tools-scripts:
pip install pre-commit python-tools-scripts
# Install Salt in editable mode:
pip install -e .
deactivate
Setup venv311 (Python 3.11) - For Master Branch Testing & Pre-commit:
python3.11 -m venv venv311
source venv311/bin/activate
pip install --upgrade pip setuptools wheel
# Install platform-specific dependencies (choose your OS):
pip install -r requirements/static/pkg/py3.11/linux.txt # Linux
pip install -r requirements/static/pkg/py3.11/darwin.txt # macOS
pip install -r requirements/static/pkg/py3.11/windows.txt # Windows
# Install pytest and tools requirements:
pip install -r requirements/pytest.txt
pip install -r requirements/static/ci/py3.11/tools.txt
# Install pre-commit and python-tools-scripts:
pip install pre-commit python-tools-scripts
# Install Salt in editable mode:
pip install -e .
# Install pre-commit hooks:
pre-commit install
deactivate
Environment Usage:
Verify setup:
./venv310/bin/python -c "import salt.version; print(salt.version.__version__)"
./venv310/bin/pytest tests/pytests/unit/test_loader.py -v
./venv310/bin/python -m tools --help
CRITICAL: The MCP server uses the tools/ infrastructure which requires these virtual environments to be set up. Without them, the pytest and tools commands will fail.
The MCP server is a thin wrapper around the existing tools/ CLI infrastructure:
tools/testsuite/pytest.py - Direct pytest executiontools/testsuite/ci_failure.py - CI failure discoverytools/testsuite/container_test.py - Container testingThis ensures consistency between CLI and MCP usage.