nasport

Name: nasport
Author: CloudCorpRecords

本地服务

github.com/CloudCorpRecords云与基础设施02 周前更新

代码仓库

关于 nasport

nasport 是用于路由 Unraid 服务器操作的 MCP 服务与命令行工具，通过 GraphQL 端点执行请求。它在本地校验操作组合，并要求破坏性操作先确认。

主要功能

01单一工具路由操作及子操作
02本地校验操作目录
03破坏性操作确认门槛
04报告 GraphQL 错误
05命令行与 stdio 服务模式

适用场景

01检查 Unraid 系统与健康状态
02管理阵列、Docker 和虚拟机
03在破坏性操作检查下执行服务器任务

MCP 相关

它通过单个 MCP 工具 `unraid` 提供 Unraid 操作，并将操作及子操作路由到服务器的 GraphQL 端点。破坏性子操作需要 `confirm: true`；服务使用 stdio 传输。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "cloudcorprecords-nasport": {
      "command": "npx",
      "args": [
        "-y",
        "@reneturcios/nasport"
      ]
    }
  }
}

启动命令npx -y @reneturcios/nasport

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@reneturcios/nasport0.1.0stdio

ocighcr.io/cloudcorprecords/nasport:0.1.0stdio

工具

收录的工具列表 · 更新于 1 周前

参数	类型	必填	说明
action	string	是	操作组：system、health、array、disk、docker、vm、notification、key、plugin、rclone、setting、connect、customization、subscriptions 或 help。
params	object	否	子操作的参数（在各组文档中命名），例如 container_id、vm_id、disk_id。
confirm	boolean	否	运行破坏性子操作时必须为 true。
subaction	string	是	操作组中的操作，例如 overview、list、start、stop。

详细介绍

nasport

nasport 通过单个工具为 Unraid 服务路由操作。调用方无需使用数十个单独的工具，只需指定一个操作组及其中的子操作——docker / list、system / overview、 vm / start——nasport 就会根据本地目录验证这组操作，对破坏性操作应用确认门控，并将其他所有请求转发到服务的 GraphQL 端点。

安装

npx @reneturcios/nasport help

或者运行容器映像：

docker run -i ghcr.io/cloudcorprecords/nasport

容器默认启动 MCP 服务。传入 CLI 参数即可将其用作 CLI。

配置

使用两个环境变量配置上游连接：

UNRAID_API_URL — Unraid GraphQL 端点 URL（优先检查）
UNRAID_API_KEY — API 密钥，通过 x-api-key 标头发送

需要连接上游的调用如果缺少变量，会报错并指出缺失的变量。 help 操作和所有目录验证在未设置任何环境变量时也能正常工作。

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 --version

退出码：成功时为 0，工具错误时为 1（未知操作、破坏性操作门控、缺少环境变量、上游或 GraphQL 错误），用法错误时为 2。

MCP 服务

npx -y @reneturcios/nasport mcp

MCP 客户端配置：

{
  "mcpServers": {
    "nasport": {
      "command": "npx",
      "args": ["-y", "@reneturcios/nasport", "mcp"],
      "env": {
        "UNRAID_API_URL": "http://your-unraid.local/graphql",
        "UNRAID_API_KEY": "your-api-key"
      }
    }
  }
}

工具

工具	输入	功能
`unraid`	`action`（字符串，必填）、`subaction`（字符串，必填）、`params`（对象，可选）、`confirm`（布尔值，可选）	路由到指定操作。未知的操作组合会报错并列出有效选项。未提供 `confirm: true` 时，破坏性子操作会被拒绝。`action=help` 会在本地返回目录。

操作组：system（25 个子操作）、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 个），以及 subscriptions 和 help。

破坏性子操作包括 array/stop_array、 docker/remove_container、vm/force_stop、vm/reset、 key/delete、plugin/remove、plugin/install、 rclone/delete_remote、notification/delete，以及 connect 登录／远程访问操作。完整列表及标记出的破坏性操作会由 nasport help 打印。

GraphQL 请求构造与已知限制

本次重建所依据的源文档未发布上游 GraphQL 字段架构，因此请求构造是根据文档在本地重建的：请求体为 { "query": "query NasportOp { <action>_<subaction> }", "variables": <params> }，操作名称采用 PascalCase，由操作和子操作组成。响应中的 GraphQL errors 数组会将首条消息作为工具错误返回；data 会作为 JSON 文本返回。与在线服务的字段差异是首次在线冒烟测试时需要检查的内容。

尚未实现 WebSocket 订阅：subscriptions 操作会明确返回“尚未实现”错误。
未复现原版的 OAuth／HTTP 传输身份验证；本次重建仅支持 stdio，并使用上述环境变量密钥模式。

开发

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 tsx