# Globus MCP Server

> **⚠️ Beta Software** — This project is under active development and has not
> reached a stable v1.0.0 release. APIs, tool signatures, and behavior may
> change without notice. Use with caution in production workflows.

Globus MCP Server gives AI agents federated data transfer and remote code
execution across research storage systems at institutions worldwide.

It wraps the [Globus CLI](https://docs.globus.org/cli/) for data transfer and
the [Globus Compute SDK](https://globus-compute.readthedocs.io/) for remote
Python execution on HPC endpoints.

## Prerequisites

1. **Globus Connect Personal** (optional): For transfers to/from your local machine

## Quick Start

For MCP-enabled applications like Claude Desktop, Cursor, or Warp, add this
server to your MCP configuration:

```json
{
  "mcpServers": {
    "globus": {
      "command": "uvx",
      "args": ["git+https://github.com/purduercac/globus-mcp"]
    }
  }
}
```

The `uvx` invocation handles installation automatically. On first use, the
server's `globus_login()` and `compute_login()` tools will walk users through
authentication via the browser.

## Common Workflows

### Find and Browse Endpoints
```
endpoint_search("purdue")  # Returns list with UUIDs
ls("endpoint-uuid", "/path/to/dir")
```

### Transfer Data
```
task_id = transfer(
    source_endpoint="src-uuid",
    source_path="/data/file.tar",
    dest_endpoint="dst-uuid",
    dest_path="/scratch/file.tar"
)
task_wait(task_id)
```

### Consent Recovery

Some Globus Connect Server v5 collections require endpoint-specific consent.
If an operation fails with `ConsentRequired`, the server returns a structured
error with the required scopes. Agents call `session_consent(scopes)` to open
the browser, then retry the original operation.

### Remote Code Execution (Globus Compute)
```
# Submit a Python function to run on a remote HPC endpoint
compute_submit(
    endpoint_id="compute-endpoint-uuid",
    function_source="def analyze(n):\n    import numpy as np\n    return np.random.rand(n).mean()",
    function_name="analyze",
    requirements="numpy",
    args=[10000],
)

# Check results later
compute_result("task-uuid", timeout=300)
```

When `requirements` is provided, the server automatically provisions a cached
virtual environment on the remote endpoint using `uv`.

## Available Tools

### Identity & Auth
- `whoami()` — Show logged-in identity
- `globus_login()` — Initiate Globus CLI OAuth login
- `session_consent(scopes)` — Grant endpoint-specific data access consent

### Endpoints
- `endpoint_search(query)` — Find Transfer endpoints by name
- `endpoint_show(endpoint_id)` — Get endpoint details
- `endpoint_local_id()` — Get local GCP endpoint UUID

### Filesystem
- `ls(endpoint_id, path)` — List directory contents
- `stat(endpoint_id, path)` — Get file/directory metadata
- `mkdir(endpoint_id, path)` — Create directory
- `rename(endpoint_id, source_path, dest_path)` — Rename or move
- `rm(endpoint_id, path)` — Delete (synchronous)
- `delete(endpoint_id, path)` — Delete (async task)

### Transfers
- `transfer(...)` — Submit async transfer task
- `transfer_batch(...)` — Batch transfer (multiple file pairs)
- `task_list()` — List recent tasks
- `task_show(task_id)` — Get task details
- `task_wait(task_id)` — Wait for task completion
- `task_cancel(task_id)` — Cancel a running task
- `task_event_list(task_id)` — Get task events

### Compute (Remote Code Execution)
- `compute_login()` — Authenticate with Globus Compute
- `compute_endpoint_list()` — List accessible Compute endpoints
- `compute_endpoint_status(endpoint_id)` — Check endpoint availability
- `compute_submit(...)` — Submit a Python function for remote execution
- `compute_batch_submit(...)` — Submit multiple functions as a batch
- `compute_status(task_ids)` — Check task status (non-blocking)
- `compute_result(task_id)` — Get task result (optionally wait)

## Development

```bash
uv sync
uv run globus-mcp --help
uv run pytest -q
```

Contributors — human or agent — should start with [`AGENTS.md`](AGENTS.md), the repository's
operating manual: architecture, the load-bearing invariants, and the process rules.

Non-trivial work flows through the spec-driven **software factory** under
[`.agents/`](.agents/) — `/globus-feature` → `/globus-plan` → `/globus-build` → `/globus-review` →
`/globus-publish`, each cycle on its own branch with its design record retained under `spec/{slug}/`.
See [`.agents/factory/methodology.md`](.agents/factory/methodology.md) for the why, and
[`ROADMAP.md`](ROADMAP.md) for what is queued.

One rule is worth repeating outside that documentation, because it is easy to violate by reflex:
**no test, verify command, or review drive may call a tool that mutates remote state** — `transfer`,
`rm`, `delete`, `compute_submit` and friends act on production research infrastructure. Drive the
server hermetically instead:

```bash
uv run python .agents/factory/bin/mcp_probe.py          # in-memory MCP round-trip, no network
.agents/factory/bin/temp_home.sh uv run pytest -q        # …with Globus credentials unreachable
```

Known defects reproduced on `main` are listed in [`AGENTS.md`](AGENTS.md) § *Known defects*, each
with a seed under [`issues/`](issues/).

## License

MIT