# Vultr Codex Plugin

A Codex plugin for managing Vultr with explicit safety guards. The first
version focuses on small VPS workflows: inspect account state, preview instance
creation, then perform selected mutations only after exact confirmation.

The plugin's tools are implemented through a local MCP server, but the
user-facing product is a Codex plugin.

## Features

- List Vultr account, instances, plans, regions, OS images, SSH keys, and
  firewall groups.
- Check whether `vultr-cli` is available locally for optional manual workflows.
- Preview instance creation before spending money.
- Restrict instance creation by plan, region, and monthly cost.
- Require exact confirmation strings for create, reboot, snapshot, and delete.
- Read the Vultr token only from `VULTR_API_KEY`.

## Quick Start

```bash
npm install
npm run verify
export VULTR_API_KEY="your-vultr-api-key"
```

The Codex plugin manifest is in `.codex-plugin/plugin.json`; the MCP
configuration is in `.mcp.json`. The bundled server entrypoint is
`mcp/server.mjs`.

## Codex Plugin Install

During local development, keep the repository under:

```text
/Users/zeyuwang/Documents/project/vultr-codex-plugin
```

Then install the plugin from a local marketplace entry or copy/symlink the
repository into your personal plugin marketplace. The plugin does not need the
Vultr token at install time, but Vultr API tools require `VULTR_API_KEY` in the
environment where Codex launches the MCP server.

If you only want to smoke-test the MCP server without installing the plugin:

```bash
printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0.0.0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  | node ./mcp/server.mjs
```

## Safety Policy

By default, create operations are limited to:

- Plans: `vc2-1c-1gb`, `vc2-1c-2gb`, `vc2-2c-2gb`
- Regions: `nrt`, `itm`, `sgp`, `icn`, `lax`, `sjc`, `sea`
- Maximum monthly cost: `$20`

Override these with environment variables:

```bash
VULTR_ALLOWED_PLANS=vc2-1c-1gb,vc2-1c-2gb
VULTR_ALLOWED_REGIONS=nrt,sgp,lax
VULTR_MAX_MONTHLY_COST_USD=10
```

## Confirmation Strings

Mutation tools reject calls unless the `confirm` field exactly matches the
expected string returned by preview or described by the tool:

```text
create:<label>:<plan>:<region>
reboot:<instance_id>
snapshot:<instance_id>
delete:<instance_id>:<label>
```

For deletion, the server first fetches the instance and checks that the Vultr
label matches the provided `label`.

## Tools

- `get_policy`
- `get_account`
- `get_vultr_cli_status`
- `list_instances`
- `get_instance`
- `list_regions`
- `list_plans`
- `list_os`
- `list_ssh_keys`
- `list_firewall_groups`
- `create_instance_preview`
- `create_instance`
- `reboot_instance`
- `create_snapshot`
- `delete_instance`

## Development

```bash
npm install
npm run check
npm test
npm run build
```

The source lives under `src/`. `npm run build` bundles it into
`mcp/server.mjs`, which is what Codex launches.

## Local Context

For this machine, the preferred code repository root is:

```text
/Users/zeyuwang/Documents/project
```