# Quickstart

From zero to a working Ansible-backed MCP tool in three steps. This guide uses localhost; the same steps apply to any remote host by editing the inventory.

Prerequisites: Python 3.12+, and SSH access to the hosts you want to automate (localhost works out of the box via the local connection).
1

## Install

    pip install rocannon

This installs `ansible-core` and `ansible-runner` alongside Rocannon. Verify the environment:

    rocannon doctor

You should see all binaries (`ansible-doc`, `ansible-inventory`, `ansible-runner`) marked `[ ok ]`.

2

## Scaffold a profile

    rocannon quickstart

This writes two files under `.rocannon/`:

`.rocannon/quickstart.yml` | Profile declaring localhost inventory and a handful of builtin modules
`.rocannon/inventory.ini` | Inventory pinning localhost to the same Python interpreter Rocannon uses

Confirm the tools registered:

    rocannon mcp doctor --profile .rocannon/quickstart.yml

Output shows the tool count, resource count, and prompt count for the server as your MCP client will see it.

3

## Wire your MCP client

Claude Code (recommended for first use):

    claude mcp add rocannon -- rocannon mcp serve --profile /absolute/path/to/.rocannon/quickstart.yml

Or add to `.mcp.json` (Claude Code, Cursor, any client that reads it):

    {
      "mcpServers": {
        "rocannon": {
          "command": "rocannon",
          "args": ["mcp", "serve", "--profile", "/absolute/path/to/.rocannon/quickstart.yml"]
        }
      }
    }

Use an absolute path. MCP clients launch the server from their own CWD, not yours.

## First conversation

In Claude Code (or whichever client you wired), try:

> Gather facts from localhost and tell me the OS and kernel version.

Rocannon runs `ansible.builtin.setup` against localhost and returns the structured fact output. The assistant can then answer in plain English.

## Without an LLM

The REPL drives the same server in-process, no MCP client needed:

    rocannon repl --profile .rocannon/quickstart.yml

    rocannon> setup target=localhost
    rocannon> .save my-first-session "gather facts from localhost"

The `.save` command writes the session to `.rocannon/playbooks/my-first-session.yml`, a standard Ansible playbook that runs without Rocannon.

## Next steps

- Add more modules: edit the profile's `modules:` list to include collections like `community.docker` or `amazon.aws`. Profile reference →
- Point at real hosts: replace the localhost inventory with your actual SSH inventory.
- Add multiple profiles for different environments (dev/staging/prod) and switch at runtime with `rocannon_use_profile`.
- Use `check=true` on any module call to preview what would change before applying it.