# Alire MCP

A Python [Model Context Protocol](https://modelcontextprotocol.io/) server for
[Alire](https://alire.ada.dev/), the Ada package manager.

The server exposes a curated set of Alire operations to MCP clients. It does
not expose an unrestricted shell or arbitrary `alr` argument execution.

## Features

- Search for and inspect crates in the Alire index
- Inspect project dependency solutions and trees
- Build Alire projects
- Add, remove, and update dependencies
- Initialize new executable or library crates
- Fetch published crate sources
- Non-interactive subprocess execution with no shell
- Optional workspace-root confinement
- Configurable time and output limits
- Read-only and destructive MCP tool annotations

## Requirements

- Python 3.10 or later
- Alire (`alr`) installed and available on `PATH`

Verify Alire before starting the server:

```console
alr --version
```

## Installation

Install from a source checkout:

```console
python3 -m pip install .
```

For an isolated development environment:

```console
python3 -m venv .venv
```

```console
.venv/bin/python -m pip install -e '.[dev]'
```

Run the stdio server:

```console
alire-mcp
```

The server communicates using MCP messages on standard input and standard
output. Diagnostic output from Alire is captured and returned by each tool,
not written into the MCP transport stream.

## MCP client configuration

A typical MCP client configuration is:

```json
{
  "mcpServers": {
    "alire": {
      "command": "alire-mcp",
      "args": [],
      "env": {
        "ALIRE_MCP_WORKSPACE_ROOT": "/absolute/path/to/ada/workspaces"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

If the executable is installed in a virtual environment, use its absolute
path for `command`:

```json
{
  "mcpServers": {
    "alire": {
      "command": "/absolute/path/to/alire-mcp/.venv/bin/alire-mcp",
      "args": [],
      "env": {
        "ALIRE_MCP_WORKSPACE_ROOT": "/absolute/path/to/ada/workspaces"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

Restart or reload the MCP client after changing its configuration.

## Tools

| Tool | Effect |
| --- | --- |
| `alire_version` | Show detailed Alire version and environment information |
| `search_crates` | Search crate names and descriptions |
| `show_crate` | Show metadata for a crate or exact release |
| `project_dependencies` | Inspect direct, solved, tree, graph, or version dependency views |
| `build_project` | Build a project |
| `update_dependencies` | Update all or selected dependencies |
| `add_dependency` | Add a dependency constraint to a manifest |
| `remove_dependency` | Remove a dependency from a manifest |
| `initialize_crate` | Create an executable or library crate |
| `fetch_crate` | Fetch a crate release |

Every tool result contains:

- `command`: the exact argument vector used
- `cwd`: the effective working directory
- `exit_code`: Alire's process exit status
- `success`: whether the exit status was zero
- `stdout` and `stderr`: captured output
- `stdout_truncated` and `stderr_truncated`: output-limit indicators

A nonzero Alire exit code is returned as command data so an MCP client can
inspect Alire's diagnostic text. Server-level failures, such as an invalid
workspace path or timeout, are reported as tool errors.

## Configuration

The server is configured through environment variables:

| Variable | Default | Description |
| --- | --- | --- |
| `ALIRE_MCP_ALR` | `alr` | Alire executable name or path |
| `ALIRE_MCP_WORKSPACE_ROOT` | unset | Restrict project directories to this directory tree |
| `ALIRE_MCP_TIMEOUT` | `300` | Per-command timeout in seconds |
| `ALIRE_MCP_MAX_OUTPUT_BYTES` | `1000000` | Maximum captured bytes for each output stream |

When `ALIRE_MCP_WORKSPACE_ROOT` is configured:

- omitted tool directories use the workspace root;
- relative directories resolve below the workspace root;
- absolute directories outside the root are rejected;
- symlink resolution cannot escape the root.

Without a workspace root, omitted directories inherit the MCP server process
working directory and explicitly supplied paths may point to any accessible
directory.

## Security

Alire MCP applies the following boundaries:

- Commands are launched with `asyncio.create_subprocess_exec`; no shell is
  involved.
- Global `--non-interactive`, `--no-color`, and `--no-tty` options are always
  used.
- Standard input is disabled for child processes.
- Tool parameters are validated and map to a fixed set of Alire commands.
- Commands have a timeout and bounded captured output.
- MCP annotations identify read-only and potentially destructive operations.

Alire itself may download, compile, and execute code from package sources.
Treat third-party crates as untrusted and review requested mutating operations.
For stronger isolation, run this server in a container or restricted user
account and configure `ALIRE_MCP_WORKSPACE_ROOT`.

## Development

Install development dependencies:

```console
python3 -m pip install -e '.[dev]'
```

Run tests:

```console
pytest
```

Run linting and formatting checks:

```console
ruff check .
```

```console
ruff format --check .
```

Run type checking:

```console
mypy
```

Build distribution artifacts:

```console
python3 -m build
```

## License

Alire MCP is distributed under the [MIT License](LICENSE).