# NVM MCP Server for Antigravity

An MCP server that wraps [NVM (Node Version Manager)](https://github.com/nvm-sh/nvm),
giving Antigravity agents full control over Node.js versions — without needing Node
or npm to already be on `$PATH`.

## Why this exists

Antigravity agents run in a non-interactive subprocess and never source your shell's
`.zshrc` / `.bashrc`. Because NVM adds Node to `$PATH` only in interactive shells,
agents can't find `node` or `npm`. This server sources `nvm.sh` directly before every
command, completely bypassing the `$PATH` problem.

---

## Requirements

- Python 3.10+
- NVM installed at `~/.nvm` (or set `NVM_DIR` in the config)
- `pip install mcp` (or `pip install -r requirements.txt`)

---

## Installation

```bash
# 1. Clone / copy this folder somewhere permanent
cp -r nvm-mcp-server ~/.nvm-mcp-server

# 2. Install the one dependency
pip install -r ~/.nvm-mcp-server/requirements.txt
# Or, if you prefer a venv:
python3 -m venv ~/.nvm-mcp-server/.venv
~/.nvm-mcp-server/.venv/bin/pip install mcp
```

---

## Antigravity Configuration

Open (or create) `~/.gemini/antigravity/mcp_config.json` and add:

```json
{
  "mcpServers": {
    "nvm-manager": {
      "command": "python3",
      "args": ["/Users/YOUR_USERNAME/.nvm-mcp-server/nvm_server.py"],
      "env": {
        "NVM_DIR": "/Users/YOUR_USERNAME/.nvm"
      }
    }
  }
}
```

> **Venv users:** replace `"python3"` with the absolute path to the venv Python,
> e.g. `"/Users/YOUR_USERNAME/.nvm-mcp-server/.venv/bin/python3"`.

Restart Antigravity after saving the config. The **nvm-manager** server will appear
under MCP Servers.

---

## Available Tools

| Tool | What it does |
|---|---|
| `nvm_list` | List all locally installed Node versions |
| `nvm_list_remote` | List versions available to install (accepts filter: `'lts'`, `'22'`, etc.) |
| `nvm_install` | Download and install a version (`'22'`, `'lts'`, `'lts/iron'`, `'20.11.0'`) |
| `nvm_use` | Switch the **session-active** version — persists for all subsequent calls |
| `nvm_current` | Show which version is currently active in the session |
| `nvm_alias` | Set an NVM alias, e.g. point `default` at a new version |
| `node_run` | Run `node <args>` with the active (or a specified) version |
| `npm_run` | Run `npm <args>` with the active (or a specified) version |
| `npx_run` | Run `npx <args>` with the active (or a specified) version |

All three runner tools accept an optional `version` field that overrides the
session-active version for that one call, and an optional `cwd` field.

---

## Example agent workflow

```
Agent: nvm_list           → sees v20.11.0 and v22.3.0 installed
Agent: nvm_use "22"       → session set to Node 22
Agent: npm_run "install"  → runs npm install under Node 22
Agent: node_run "index.js" → runs the script under Node 22

# Need a version that isn't installed yet?
Agent: nvm_install "lts"  → downloads latest LTS
Agent: nvm_use "lts"      → switches to it
Agent: nvm_alias "default" "lts"  → makes it the permanent default
```

---

## Custom NVM location

If NVM is installed somewhere other than `~/.nvm`, set `NVM_DIR` in the
`env` block of `mcp_config.json`:

```json
"env": {
  "NVM_DIR": "/opt/homebrew/opt/nvm"
}
```

---

## Troubleshooting

| Symptom | Fix |
|---|---|
| `nvm.sh not found` | Verify `NVM_DIR` in the `env` block points to your NVM root |
| `nvm_install` times out | Increase the subprocess timeout in `nvm_server.py` (default 300 s) |
| Version not found | Run `nvm_list_remote` to check the exact version string |
| Server not appearing | Check Antigravity → `...` → MCP Servers for error messages |