Tarn
Guide 04

Keep the agent on a small, typed tool surface.

tarn-mcp exposes Tarn as structured tools so the assistant can list suites, validate YAML, run tests, and generate a fix plan without scraping CLI output.

Portable project setup

Drop a .mcp.json at the repository root. This is the preferred setup because it is portable across every MCP-compatible client — Claude Code, Cursor, Windsurf, and anything else that reads the standard project-level file — without an editor-specific settings file.

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

Commit this file and every contributor on the project picks up the same tool surface automatically.

Available tools

  • tarn_list: enumerate files and steps.
  • tarn_validate: catch syntax and config issues before execution.
  • tarn_run: execute tests and return structured report JSON.
  • tarn_fix_plan: prioritize failed steps and suggest next actions from the report. Shares its engine with the quick-fix code action in tarn-lsp, so CLI agents and editor agents get the same remediation graph.

tarn_run

Execute tests and return structured JSON results.

ParameterTypeRequiredDefaultDescription
pathstringNoworkspacePath to .tarn.yaml file or directory
tagstringNo-Filter by tag (comma-separated, AND)
envstringNo-Environment name (loads tarn.env.{name}.yaml)
varsobjectNo-Variable overrides as key-value pairs

tarn_validate

Validate .tarn.yaml files without executing.

ParameterTypeRequiredDefaultDescription
pathstringYes-Path to .tarn.yaml file or directory

tarn_list

List all available tests.

ParameterTypeRequiredDefaultDescription
pathstringNoworkspacePath to directory

tarn_fix_plan

Analyze a failed report and return prioritized remediation.

ParameterTypeRequiredDefaultDescription
pathstringNo-Run tests first, then plan
tagstringNo-Tag filter when path is provided
envstringNo-Environment name when path is provided
varsobjectNo-Variable overrides when path is provided
reportobjectNo-Pass a report directly
max_itemsintegerNoallLimit failing steps in the plan

Portable project setup

See the section above for the portable .mcp.json approach. The following editor-specific configurations are fallbacks for clients that do not yet read the project-level file — use the same mcpServers block in each client's settings.

Claude Code

# Install tarn-mcp
cargo install tarn-mcp

Add to .claude/settings.json:

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

Cursor

Add to ~/.cursor/mcp.json:

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

Windsurf

Same .mcp.json configuration in the project root.

opencode

opencode does not read .mcp.json. Use its native opencode.jsonc at the repo root — note the different schema shape (mcp instead of mcpServers, type: "local" for stdio, and a command array).

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "tarn": {
      "type": "local",
      "command": ["tarn-mcp"],
      "enabled": true
    }
  }
}

This repo commits a working opencode.jsonc at its root alongside a .opencode/skills/tarn-api-testing/ symlink, so agents running opencode inside the Tarn repo get the full MCP + LSP + skill surface with no extra setup. See editors/opencode/README.md for the full install flow.

Recommended loop

  1. Call tarn_list to get the suite shape.
  2. Edit or generate the Tarn YAML.
  3. Call tarn_validate.
  4. Call tarn_run.
  5. Call tarn_fix_plan if the run failed and you want a prioritized debugging plan.

Failures-first agent loop

1. tarn_list → discover tests
2. Generate/edit YAML
3. tarn_validate → catch syntax/config issues
4. tarn_run → execute, inspect failure_category
5. Check response body in failures to fix assertions
6. tarn_fix_plan → structured remediation
7. Fix and rerun until PASSED

Why it beats shelling out

  • No stdout scraping or fragile regex around human output.
  • Shared contract with the JSON report schema.
  • Smaller prompt footprint because the tool result is already structured.