Merge pull request #1925 from dgageot/aqua

Support auto-downloading tools

Author: dgageot

agent-schema.json

@@ -844,6 +844,10 @@
           "items": {
             "type": "string"
           }
+        },
+        "version": {
+          "type": "string",
+          "description": "Package reference for auto-installation of MCP/LSP tool binaries. Format: 'owner/repo' or 'owner/repo@version'. Set to 'false' to disable auto-install for this toolset."
         }
       },
       "additionalProperties": false,

docs/configuration/overview/index.md

@@ -146,6 +146,13 @@ API keys and secrets are read from environment variables — never stored in con
 | `XAI_API_KEY`       | xAI           |
 | `NEBIUS_API_KEY`    | Nebius        |
 
+**Tool Auto-Installation:**
+
+| Variable              | Description                                                     |
+| --------------------- | --------------------------------------------------------------- |
+| `DOCKER_AGENT_AUTO_INSTALL` | Set to `false` to disable automatic tool installation           |
+| `DOCKER_AGENT_TOOLS_DIR`    | Override the base directory for installed tools (default: `~/.cagent/tools/`) |
+
 <div class="callout callout-warning">
 <div class="callout-title">⚠️ Important
 </div>

docs/configuration/tools/index.md

@@ -321,6 +321,7 @@ toolsets:
 | `tools`       | array  | Optional: only expose these tools                     |
 | `env`         | array  | Environment variables (`"KEY=value"` format)          |
 | `instruction` | string | Custom instructions injected into the agent's context |
+| `version`     | string | Package reference for [auto-installing](#auto-installing-tools) the command binary |
 
 ### Remote MCP (SSE / Streamable HTTP)
 
@@ -343,6 +344,81 @@ toolsets:
 | `remote.transport_type` | string | `sse` or `streamable`             |
 | `remote.headers`        | object | HTTP headers (typically for auth) |
 
+## Auto-Installing Tools
+
+When configuring MCP or LSP tools that require a binary command, cagent can **automatically download and install** the command if it's not already available on your system. This uses the [aqua registry](https://github.com/aquaproj/aqua-registry) — a curated index of CLI tool packages.
+
+### How It Works
+
+1. When a toolset with a `command` is loaded, cagent checks if the command is available in your `PATH`
+2. If not found, it checks the cagent tools directory (`~/.cagent/tools/bin/`)
+3. If still not found, it looks up the command in the aqua registry and installs it automatically
+
+### Explicit Package Reference
+
+Use the `version` property to specify exactly which package to install:
+
+```yaml
+toolsets:
+  - type: mcp
+    command: gopls
+    version: "golang/tools@v0.25.0"
+    args: ["mcp"]
+  - type: lsp
+    command: rust-analyzer
+    version: "rust-lang/rust-analyzer@2024-01-01"
+    file_types: [".rs"]
+```
+
+The format is `owner/repo` or `owner/repo@version`. When a version is omitted, the latest release is used.
+
+### Automatic Detection
+
+If the `version` property is not set, cagent tries to auto-detect the package from the command name by searching the aqua registry:
+
+```yaml
+toolsets:
+  - type: mcp
+    command: gopls  # auto-detected as golang/tools
+    args: ["mcp"]
+```
+
+### Disabling Auto-Install
+
+You can disable auto-installation in two ways:
+
+**Per toolset** — set `version` to `"false"` or `"off"`:
+
+```yaml
+toolsets:
+  - type: mcp
+    command: my-custom-server
+    version: "false"
+```
+
+**Globally** — set the `DOCKER_AGENT_AUTO_INSTALL` environment variable:
+
+```bash
+export DOCKER_AGENT_AUTO_INSTALL=false
+```
+
+### Environment Variables
+
+| Variable              | Default                | Description                                      |
+| --------------------- | ---------------------- | ------------------------------------------------ |
+| `DOCKER_AGENT_AUTO_INSTALL` | (enabled)              | Set to `false` to disable all auto-installation  |
+| `DOCKER_AGENT_TOOLS_DIR`    | `~/.cagent/tools/`     | Base directory for installed tools               |
+| `GITHUB_TOKEN`        | —                      | GitHub token to raise API rate limits (optional) |
+
+Installed binaries are placed in `~/.cagent/tools/bin/` and cached so they are only downloaded once.
+
+<div class="callout callout-tip">
+<div class="callout-title">💡 Tip
+</div>
+  <p>Auto-install supports both Go packages (via <code>go install</code>) and GitHub release binaries (via archive download). The aqua registry metadata determines which method is used.</p>
+
+</div>
+
 ## Tool Filtering
 
 Toolsets may expose many tools. Use the `tools` property to whitelist only the ones your agent needs. This works for any toolset type — not just MCP:

docs/tools/lsp/index.md

@@ -44,6 +44,7 @@ agents:
 | `args`       | array  | ✗        | Command-line arguments for the LSP server                  |
 | `env`        | object | ✗        | Environment variables for the LSP process                  |
 | `file_types` | array  | ✗        | File extensions this LSP handles (e.g., `[".go", ".mod"]`) |
+| `version`    | string | ✗        | Package reference for [auto-installing](/configuration/tools/#auto-installing-tools) the command binary (e.g., `"golang/tools@v0.25.0"`) |
 
 ## Available Tools
 
@@ -77,6 +78,7 @@ Here are configurations for popular languages:
 toolsets:
   - type: lsp
     command: gopls
+    version: "golang/tools@v0.25.0" # optional: auto-install if not in PATH
     file_types: [".go"]
 ```
 
@@ -196,9 +198,9 @@ All LSP tools use **1-based** line and character positions:
 }
 ```
 
-<div class="callout callout-warning">
-<div class="callout-title">⚠️ Server Installation
+<div class="callout callout-tip">
+<div class="callout-title">💡 Auto-Installation
 </div>
-  <p>The LSP server must be installed and available in the system PATH. docker-agent does not install LSP servers automatically. Install them using your language's package manager (e.g., <code>go install golang.org/x/tools/gopls@latest</code>).</p>
+  <p>docker-agent can automatically download and install LSP servers if they are not found in your PATH. Use the <code>version</code> property to specify a package, or let docker-agent auto-detect it from the command name. See <a href="/configuration/tools/#auto-installing-tools">Auto-Installing Tools</a> for details.</p>
 
 </div>

examples/elicitation/demo.yaml

@@ -37,5 +37,6 @@ agents:
     toolsets:
       - type: mcp
         command: uvx
+        version: "astral-sh/uv"
         args:
           ["--with", "mcp[cli]", "mcp", "run", "examples/elicitation/server.py"]

examples/finance.yaml

@@ -50,6 +50,7 @@ agents:
     toolsets:
       - type: mcp
         command: uvx
+        version: "astral-sh/uv"
         args: ["yfmcp"]
 
   web_search_agent:

examples/gopher.yaml

@@ -65,6 +65,7 @@ agents:
       - type: todo
       - type: mcp
         command: gopls
+        version: "golang/tools@v0.25.0"
         args: ["mcp"]
     commands:
       fix-lint:
@@ -164,6 +165,7 @@ agents:
       - type: shell
       - type: mcp
         command: gopls
+        version: "golang/tools@v0.25.0"
         args: ["mcp"]
 
   librarian:

examples/modernize-go-tests.yaml

@@ -87,6 +87,7 @@ agents:
       - type: todo
       - type: mcp
         command: gopls
+        version: "golang/tools@v0.25.0"
         args: ["mcp"]
         tools:
           [

pkg/config/latest/types.go

@@ -542,6 +542,12 @@ type Toolset struct {
 	Remote  Remote   `json:"remote"`
 	Config  any      `json:"config,omitempty"`
 
+	// For `mcp` and `lsp` tools - version/package reference for auto-installation.
+	// Format: "owner/repo" or "owner/repo@version"
+	// When empty and auto-install is enabled, cagent auto-detects from the command name.
+	// Set to "false" or "off" to disable auto-install for this toolset.
+	Version string `json:"version,omitempty"`
+
 	// For the `a2a` and `openapi` tools
 	Name    string            `json:"name,omitempty"`
 	URL     string            `json:"url,omitempty"`

pkg/config/latest/validate.go

@@ -82,6 +82,9 @@ func (t *Toolset) validate() error {
 	if t.Shared && t.Type != "todo" {
 		return errors.New("shared can only be used with type 'todo'")
 	}
+	if t.Version != "" && t.Type != "mcp" && t.Type != "lsp" {
+		return errors.New("version can only be used with type 'mcp' or 'lsp'")
+	}
 	if t.Command != "" && t.Type != "mcp" && t.Type != "lsp" {
 		return errors.New("command can only be used with type 'mcp' or 'lsp'")
 	}