@kirrosh/apitool

Point your AI agent at an OpenAPI spec. Get working tests in minutes. No config, no cloud, no Postman.

Install

# Option 1: via npx (recommended — works everywhere with Node.js)
npx -y @kirrosh/apitool --version

# Option 2: Binary (no Node.js required)
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/kirrosh/apitool/master/install.sh | sh

# Windows
iwr https://raw.githubusercontent.com/kirrosh/apitool/master/install.ps1 | iex

All releases (Linux x64, macOS ARM, Windows x64)

MCP Setup (Cursor / Claude Code / Windsurf)

Click the badge above, or add manually:

{
  "mcpServers": {
    "apitool": {
      "command": "npx",
      "args": [
        "-y",
        "@kirrosh/apitool@latest",
        "mcp",
        "--dir",
        "${workspaceFolder}"
      ]
    }
  }
}

@latest ensures npx always pulls the newest version on each restart — no manual update needed.

Where to put this:

| Editor | Config file | | ----------- | ----------------------------------------------------- | | Cursor | Settings > MCP, or .cursor/mcp.json in project root | | Claude Code | .mcp.json in project root | | Windsurf | .windsurfrules/mcp.json or settings |

Main Flow (5 steps)

Once MCP is connected, ask your AI agent to cover your API with tests:

1. Register your API

setup_api(name: "myapi", specPath: "openapi.json")

2. Generate a test guide (agent reads OpenAPI + gets instructions)

generate_and_save(specPath: "openapi.json")

For large APIs (>30 endpoints), auto-chunks by tags and returns a plan. Call with tag for each chunk.

3. Save test suites (agent writes YAML based on the guide)

save_test_suite(filePath: "apis/myapi/tests/smoke.yaml", content: "...")

4. Run tests

run_tests(testPath: "apis/myapi/tests/", safe: true)

5. Diagnose failures

query_db(action: "diagnose_failure", runId: 42)

Or just say: "Safely cover the API from openapi.json with tests" — the agent will do all 5 steps.

CLI

apitool run <path>           Run tests (--env, --safe, --tag, --dry-run, --env-var, --report)
apitool add-api <name>       Register API (--spec <openapi>)
apitool coverage             API test coverage (--spec, --tests, --fail-on-coverage)
apitool compare <runA> <runB> Compare two test runs
apitool serve                Web dashboard (--port 8080)
apitool mcp                  Start MCP server
apitool chat                 AI chat agent (--provider ollama|openai|anthropic)
apitool doctor               Diagnostics

Documentation

• APITOOL.md — full CLI and MCP tools reference
• docs/mcp-guide.md — MCP agent workflow guide
• docs/ci.md — CI/CD integration

License

MIT