Metadata-Version: 2.4
Name: mage-agent
Version: 0.1.0
Summary: Mage Agent unified MCP/CLI tooling
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.32.0
Provides-Extra: dev
Requires-Dist: flake8; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Dynamic: license-file

# mage-agent

## Phase 1 status

Implemented:

- Python package scaffold with `mage-agent` entrypoint
- MCP stdio runtime (`mage-agent mcp`)
- Shared core config/auth/http/error modules
- Tools layer (Python API wrappers) for pipeline CRUD, block operations, run trigger, and log retrieval

### Local setup

```bash
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -e ".[dev]"
```

### Configure credentials (recommended)

Use interactive login:

```bash
mage-agent login
```

Or provide values non-interactively:

```bash
mage-agent login \
  --cluster-url https://your-mage-url \
  --email YOUR_EMAIL \
  --password YOUR_PASSWORD \
```

`login` authenticates with the cluster URL using username/password, then writes
`~/.mage-agent/config.json` with your `cluster_url` and `oauth_token`.
The agent uses a built-in default API key for requests.

Authentication gates runtime functionality: MCP tool calls require valid auth credentials.

### Configure credentials (manual option)

Create `~/.mage-agent/config.json`:

```json
{
  "cluster_url": "https://your-mage-url",
  "oauth_token": "RAW_OAUTH_TOKEN"
}
```

### Optional developer tooling

Dev tooling (`flake8`, `pre-commit`) is defined in `pyproject.toml` under
optional dependency group `dev`. If you installed with `pip install -e ".[dev]"`,
run local checks with:

```bash
flake8 src
pre-commit run --all-files
```

### Run MCP server

```bash
mage-agent mcp
```

### Install and connect from IDEs

After installing `mage-agent` and running `mage-agent login`, configure your
IDE/agent client to launch the MCP server with:

- command: `mage-agent`
- args: `["mcp"]`

If `mage-agent` is not on PATH in the client runtime, use the absolute path
to the executable.

### Sync project to local files

```bash
mage-agent sync-project-to-local --local-project-dir .mage-agent/local_sync
```

If `--local-project-dir` is not provided, the CLI prompts for it.

### Connect Cursor to MCP

1. Open Cursor settings and go to MCP servers.
2. Add a new server named `mage-agent`.
3. Use this command configuration:

```json
{
  "mcpServers": {
    "mage-agent": {
      "command": "mage-agent",
      "args": ["mcp"]
    }
  }
}
```

If `mage-agent` is not on your PATH in Cursor, use the full executable path instead:

```json
{
  "mcpServers": {
    "mage-agent": {
      "command": "/absolute/path/to/mage-agent",
      "args": ["mcp"]
    }
  }
}
```

After saving the config, reload Cursor and confirm the `mage-agent` MCP tools are available.

### Connect Codex CLI to MCP

Add `mage-agent` to Codex MCP config (for example in your Codex config file):

```json
{
  "mcpServers": {
    "mage-agent": {
      "command": "mage-agent",
      "args": ["mcp"]
    }
  }
}
```

Then restart Codex CLI and verify tools/resources are visible.

### Connect Claude Code to MCP

Configure MCP servers in Claude Code with the same command:

```json
{
  "mcpServers": {
    "mage-agent": {
      "command": "mage-agent",
      "args": ["mcp"]
    }
  }
}
```

Restart Claude Code after saving config, then run a simple MCP call (for
example `pipeline_list`) to verify connectivity.
