# Robot AI Tools

An MCP server for agentic development with Robot Framework.

## What's Included

- `robot-ai-mcp`: local MCP server exposing Robot Framework operations.

The MCP server provides these tools:

- `robot_list_tests`: discover test cases, tags, source files, and line numbers
  without executing them.
- `robot_list_resources`: discover `.resource` files, keywords, arguments, and
  imports without executing them.
- `robot_create_test`: create a reviewable draft from a natural-language
  requirement using project `.resource` files, libraries, and matched keywords.
- `robot_dry_run`: validate imports, variables, and keyword resolution without
  running test keywords.
- `robot_run`: execute selected suites with optional include/exclude tags and
  return compact results and failure details.
- `robot_parse_results`: summarize a Robot `output.xml` file.

All paths are resolved relative to the workspace and must remain inside it.
Execution uses argument-list subprocesses, bounded responses, and a timeout.

## Trust Boundary

The MCP server is intended for a trusted local workspace. It does not sandbox
Robot Framework, Python libraries, variable files, subprocesses, network access,
or environment variables. A Robot suite can therefore read files, access the
network, start processes, and execute Python code with the same OS permissions
as the MCP server.

Only point the server at repositories and test dependencies that you trust. Do
not expose this local server to untrusted clients or use it as a security
boundary. The server rejects paths outside the workspace, but that check does
not replace operating-system isolation.

By default, execution removes obvious credential-like environment variables
such as tokens, passwords, secrets, and API keys. If a trusted test requires
one of them, list its name in `ROBOT_AI_ENV_ALLOWLIST` as a comma-separated
environment variable. Test output and Robot-generated HTML artifacts can still
contain sensitive data and must be handled accordingly.

## Requirements

- Python 3.10 or newer
- [`uv`](https://docs.astral.sh/uv/)
- Robot Framework 6.1 or newer

## Setup

Install the locked dependencies and run the test suite:

```bash
uv sync --locked --all-groups
uv run --locked --no-sync pytest
uv run --locked --no-sync ruff check src tests
uv run --locked --no-sync mypy src
```

Run the MCP server directly when needed:

```bash
uv run --locked --no-sync robot-ai-mcp
```

The repository does not include client-specific agent configuration. Configure
the MCP server in the client of your choice using the local STDIO transport.

### OpenCode

Add the following entry to your OpenCode configuration, such as the project
`opencode.json` or your user configuration:

```json
{
  "mcp": {
    "robot-framework": {
      "type": "local",
      "command": [
        "uv",
        "--directory",
        "/absolute/path/to/robot-ai-tools",
        "run",
        "--locked",
        "--no-sync",
        "robot-ai-mcp"
      ],
      "enabled": true,
      "timeout": 360000
    }
  }
}
```

Replace `/absolute/path/to/robot-ai-tools` with the repository path. Restart
the client after changing its MCP configuration.

### Kilo Code

Kilo Code supports this MCP through the local STDIO transport. Create a
project-level `kilo.jsonc` in the repository root, or use `.kilo/kilo.jsonc`:

```json
{
  "mcp": {
    "robot-framework": {
      "type": "local",
      "command": [
        "uv",
        "--directory",
        "/absolute/path/to/robot-ai-tools",
        "run",
        "--locked",
        "--no-sync",
        "robot-ai-mcp"
      ],
      "enabled": true,
      "timeout": 360000
    }
  }
}
```

Replace `/absolute/path/to/robot-ai-tools` with the path to this repository.
The `timeout` value is in milliseconds. Kilo Code will then discover
`robot_list_tests`, `robot_list_resources`, `robot_create_test`, `robot_run`,
`robot_dry_run`, and `robot_parse_results`. Approve the tools in Kilo Code when
prompted, or add them to its MCP permissions according to your local policy.

The server is intended for trusted workspaces and is not sandboxed. See
[Trust Boundary](#trust-boundary) before enabling it for a project.

### Other MCP Clients

For another MCP-compatible agent, add a local/STDIO server using the same
command and arguments shown above. Clients that use separate `command` and
`args` fields should configure them as follows:

```text
command: uv
args: --directory /absolute/path/to/robot-ai-tools run --locked --no-sync robot-ai-mcp
```

Use the client's equivalent of `enabled`, configure a timeout of at least five
minutes for long-running Robot suites, and pass `workspace` explicitly when the
client does not start the server from the repository directory.

## Typical Workflow

Use the tools in this order when adding or changing a test:

1. Discover the relevant suite with `robot_list_tests` and existing keywords with `robot_list_resources`.
2. Create a draft with `robot_create_test` when starting from a requirement.
3. Replace the draft's intentional `Fail` placeholder with real keywords and
   assertions.
4. Run `robot_dry_run` after changing imports, variables, or keyword names.
5. Run the smallest relevant scope with `robot_run`.
6. Use `robot_parse_results` to inspect the generated `output.xml`.

Each execution gets a fresh result directory when `output_dir` is omitted.
When an explicit directory is supplied, the server removes only the previous
Robot result artifacts before starting, so an old `output.xml` cannot be
reported as the current execution.

Drafts are tagged `ai-generated` and `draft`, document the requirement,
import project `.resource` files and libraries, and scaffold initial test steps
from matching keywords with argument placeholders. Existing files are protected
unless `overwrite=true` is explicitly supplied.

Example tool calls:

```text
robot_list_tests(workspace=".", path="tests")
robot_list_resources(workspace=".", path="tests")
robot_create_test(
  workspace=".",
  request="A valid user can sign in. Show the account page.",
  target_path="tests/sign_in.robot",
  tags=["auth"]
)
robot_dry_run(workspace=".", paths=["tests/sign_in.robot"])
robot_run(workspace=".", paths=["tests/sign_in.robot"], include_tags=["smoke"])
robot_parse_results(
  workspace=".",
  output_xml=".robot-ai/results/<run>/output.xml"
)
```

## Project Layout

```text
src/robot_ai_tools/       Runner and MCP server implementation
tests/                    Python tests and Robot fixtures
```

## Extending

Keep tool behavior in `src/robot_ai_tools/runner.py` and expose thin MCP
wrappers in `mcp_server.py`. New tools should return structured JSON, enforce
workspace containment, use argument-list subprocesses, and provide bounded or
persisted output. Add agent guidance only for repeatable workflows.