@reneturcios/nasport
v0.1.0
Published
Unified router for Unraid server operations: system inspection, array, Docker, VM, notifications and more, with destructive actions gated by explicit confirmation. One bin serves a small CLI and a stdio MCP server.
Readme
nasport
nasport routes operations for an Unraid server through a single tool.
Instead of dozens of separate tools, a caller names an action group
and a subaction inside it — docker / list, system / overview,
vm / start — and nasport validates the pair against a local
catalogue, applies a confirmation gate to destructive operations, and
forwards everything else to the server's GraphQL endpoint.
Install
npx @reneturcios/nasport helpOr run the container image:
docker run -i ghcr.io/cloudcorprecords/nasportThe container defaults to the MCP server. Pass CLI arguments to use it as a CLI instead.
Configuration
Two environment variables configure the upstream connection:
UNRAID_API_URL— the Unraid GraphQL endpoint URL (checked first)UNRAID_API_KEY— the API key, sent as thex-api-keyheader
Calls that need the upstream fail with an error naming the missing
variable. The help action and all catalogue validation work with
no environment set at all.
CLI
# Print the full local catalogue (no upstream call)
nasport help
# Run one routed operation
nasport call system overview
nasport call docker list
nasport call docker logs --params '{"container_id":"abc"}'
# Destructive operations need the explicit flag
nasport call vm force_stop --params '{"vm_id":"win11"}' --confirm
nasport --versionExit codes: 0 on success, 1 on a tool error (unknown action,
destructive gate, missing env, upstream or GraphQL error), 2 for
usage errors.
MCP server
npx -y @reneturcios/nasport mcpMCP client configuration:
{
"mcpServers": {
"nasport": {
"command": "npx",
"args": ["-y", "@reneturcios/nasport", "mcp"],
"env": {
"UNRAID_API_URL": "http://your-unraid.local/graphql",
"UNRAID_API_KEY": "your-api-key"
}
}
}
}Tool
| Tool | Input | What it does |
| --- | --- | --- |
| unraid | action (string, required), subaction (string, required), params (object, optional), confirm (boolean, optional) | Routes to the named operation. Unknown pairs are errors listing valid options. Destructive subactions refuse without confirm: true. action=help returns the catalogue locally. |
Action groups: system (25 subactions), health (check,
test_connection, diagnose, setup), array (14), disk (6),
docker (27), vm (9), notification (13), key (13),
plugin (8), rclone (4), setting (6), connect (8),
customization (7), plus subscriptions and help.
Destructive subactions include array/stop_array,
docker/remove_container, vm/force_stop, vm/reset,
key/delete, plugin/remove, plugin/install,
rclone/delete_remote, notification/delete, and the connect
sign-in / remote-access operations. The full list, with destructive
entries marked, is what nasport help prints.
GraphQL shaping and known gaps
The upstream GraphQL field schema is not published in the source
documentation this rebuild is based on, so the request shaping is a
documented local reconstruction: the body is
{ "query": "query NasportOp { <action>_<subaction> }", "variables": <params> }
and the operation name is the action and subaction in PascalCase.
A GraphQL errors array in the response is surfaced as a tool error
with its first message; data is returned as JSON text. Field-level
drift against a live server is the first live-smoke check.
- WebSocket subscriptions are not implemented: the
subscriptionsaction returns an explicit not-implemented error. - The original's OAuth / HTTP-transport authentication is not reproduced; this rebuild is stdio-only with the env-key model above.
Development
npm install
npm run build # tsc -> dist/
npm test # node test runner over test/*.test.ts, no network
npm run dev # run the CLI from source via tsxLicense
MIT — see LICENSE.
