# raidcom-mcp: build Hitachi raidcom commands from plain-language requests

A community MCP server that turns a request such as *"present four 100 GB volumes from pool 0 to host esx01 on CL1-A and CL2-A"* into validated `raidcom` commands. It is **build-only**: it never connects to a storage system, never runs a command and holds no credentials. It returns command text (or a shell script) for a person to review and run on a host with CCI installed. That makes it safe to host online for anyone to use.

It is an independent project, not an official Hitachi Vantara product.

## What it does

- **Finds the right command.** `raidcom_list_commands` ranks the 178 commands in the catalogue against a question (BM25 with synonyms and verb intent) and says how confident it is.
- **Builds one command.** `raidcom_build_command` takes a command name and options as structured data, checks them against the manual's syntax and the storage model's limits, and returns the command line.
- **Builds many.** `raidcom_build_script` repeats steps over ranges (`foreach`, `zip`), adds `get command_status` after asynchronous commands, optionally locks the resource group, and returns a script that stops at the first failure.
- **Ready-made workflows.** `raidcom_list_recipes` and `raidcom_build_recipe` cover 14 common jobs: FC, iSCSI and NVMe/TCP provisioning, DP pools, mainframe (3390) pools, extending and deleting volumes, command devices, zero-page reclaim, inventory, copy groups.
- **Checks an existing command.** `raidcom_check_command` parses a pasted command line (never executing it; shell operators are refused) and reports every problem.
- **Knows the model limits.** `raidcom_model_limits` gives the LDEV, LUN, pool, serial and port ranges of VSP One Block 24/26/28, VSP 5000 series and VSP E series.

All eight tools are marked read-only. There is no tool that executes anything.

## How the catalogue is made

`spec/raidcom-catalog.json` is generated by `scripts/generate-catalog.mjs` from the text of the *Command Control Interface Command Reference* (MK-90RD7009). For every command it keeps the name, supported models, a one-line summary, each syntax form (as a small grammar), each option's value shape and a short description, and the command lines of the manual's examples. Hitachi's prose, tables and output samples are not copied. The manuals themselves are not part of this repository; to regenerate the catalogue with your own copy:

```
pdftotext -layout CCI_Command_Reference.pdf cci-reference.txt
npm run generate-catalog -- cci-reference.txt
```

`tests/unit/catalog.test.mjs` replays every example in the manual through the parser and validator (about 96% pass; the rest are places where the manual's syntax line and its examples disagree).

## Validation

- Unknown options, wrong number of values, values outside an option's allowed words, and missing required options (checked against the syntax grammar) are errors with a suggested fix.
- LDEV IDs, LUN IDs, pool IDs, serial numbers and port names (`CL1-A`, `CL3-B-12`) are checked against the model you give, or the widest range of any model.
- Values that a shell could misread (`; | & $ \` > < ' "` and so on) are refused, and names with spaces are quoted.
- Because the manual's syntax lines are occasionally incomplete, `strict: false` turns *missing option* errors into warnings. Unknown options and out-of-range values stay errors.
- Out of scope: the `pair*` commands (paircreate, pairdisplay, ...) from the Quick Reference, and `raidcom -login`/`-logout` lines as commands of their own (scripts can add them with `login: true`, reading `$RAIDCOM_USER` and `$RAIDCOM_PASSWORD` from the shell).

## Setup

You need Node.js 22.19 or later.

```
git clone https://github.com/visubramaniam/raidcom-mcp.git
cd raidcom-mcp
npm ci
npm run build
```

### Claude Code

```
claude mcp add raidcom -- node /path/to/raidcom-mcp/dist/index.js
```

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "raidcom": { "command": "node", "args": ["/path/to/raidcom-mcp/dist/index.js"] }
  }
}
```

### Hosted over HTTP

```
RAIDCOM_TRANSPORT=http RAIDCOM_HTTP_HOST=0.0.0.0 RAIDCOM_HTTP_TOKEN=$(openssl rand -hex 32) \
RAIDCOM_HTTP_BEHIND_TLS_PROXY=true RAIDCOM_HTTP_ALLOWED_HOSTS=raidcom.example.com node dist/index.js
```

The endpoint is `/mcp` (stateless Streamable HTTP); `/healthz` reports liveness. See [INSTALL.md](INSTALL.md) and [README.docker.md](README.docker.md).

## Configuration

| Variable | Default | Meaning |
|---|---|---|
| `RAIDCOM_TRANSPORT` | `stdio` | `stdio` or `http` |
| `RAIDCOM_HTTP_HOST` | `127.0.0.1` | Address to listen on |
| `RAIDCOM_HTTP_PORT` | `8361` | Port (`0` picks a free one) |
| `RAIDCOM_HTTP_TOKEN` | none | Bearer token, at least 32 characters. Required unless `RAIDCOM_HTTP_OPEN=true` |
| `RAIDCOM_HTTP_OPEN` | `false` | Serve anyone who can reach the port, without a token |
| `RAIDCOM_HTTP_TLS_CERT`, `RAIDCOM_HTTP_TLS_KEY` | none | PEM files; the server then speaks HTTPS |
| `RAIDCOM_HTTP_BEHIND_TLS_PROXY` | `false` | A proxy or load balancer ends TLS. Needed for non-loopback addresses without TLS |
| `RAIDCOM_HTTP_ALLOWED_HOSTS` | none | Extra `Host` values to accept (`*` for any) |
| `RAIDCOM_HTTP_ALLOWED_ORIGINS` | none | `Origin` values to accept (`*` for any) |
| `RAIDCOM_HTTP_RATE_LIMIT` | `120` | Requests per minute per client (`0` for none) |
| `RAIDCOM_HTTP_TRUST_PROXY` | `false` | Take the client address from `X-Forwarded-For` |
| `RAIDCOM_CATALOG`, `RAIDCOM_LIMITS`, `RAIDCOM_RECIPES`, `RAIDCOM_EXAMPLES` | bundled | Use another spec file (an empty `RAIDCOM_EXAMPLES` turns the example questions off) |

## Tests

```
npm test
```

runs the unit tests (`tests/unit`) and the search evaluation (`tests/search-eval.mjs`: 40 tuning and 30 held-out requests, each with a minimum top-1 and top-3 score that may only go up).

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Security problems: [SECURITY.md](SECURITY.md).

## License

MIT, see [LICENSE](LICENSE). "Hitachi", "raidcom" and "VSP" are trademarks of their owners; this project is not affiliated with or endorsed by Hitachi.