{"_id":"@gputw/mcp-server","_rev":"3-f08159080f49662b24990c269344d20f","name":"@gputw/mcp-server","dist-tags":{"latest":"1.2.0"},"versions":{"0.0.0-stage":{"name":"@gputw/mcp-server","version":"0.0.0-stage","_id":"@gputw/mcp-server@0.0.0-stage","stub":true,"maintainers":[{"name":"luketaiwan2019","email":"luketaiwan2019@gmail.com"}],"dist":{"shasum":"f65dc270dc39c66070b1e3fe693fc29b66c1b036","tarball":"https://registry.npmjs.org/@gputw/mcp-server/-/mcp-server-0.0.0-stage.tgz","fileCount":2,"integrity":"sha512-637AdrpQdGNrIQbGRi6xBr0vIEOUo23oF8Ro65+LnRIFe00RtDqWmswMyt8G1lt2xGu4RpM14GX9BrU1u/94sw==","signatures":[{"sig":"MEUCIQCezf2OjvxuUoy2pkYGxJ38Af+HqISGYXaDBKlnu/ybVQIgAJzjxoxLF6VDk6Wu0z+XlXwdjwetvm/RfoXWdf90TgQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":339},"_npmUser":{"name":"luketaiwan2019","email":"luketaiwan2019@gmail.com"},"description":"Temporary package placeholder for staged publishing","directories":{}},"1.1.0":{"name":"@gputw/mcp-server","version":"1.1.0","keywords":["mcp","modelcontextprotocol","gputw","gpu","cloud","taiwan"],"author":{"url":"https://github.com/luke2023","name":"Luke Lin"},"license":"MIT","_id":"@gputw/mcp-server@1.1.0","maintainers":[{"name":"luketaiwan2019","email":"luketaiwan2019@gmail.com"}],"homepage":"https://github.com/GPUtw-ai/GPUtw-Skill","bugs":{"url":"https://github.com/GPUtw-ai/GPUtw-Skill/issues"},"bin":{"gputw-mcp":"dist/stdio.mjs"},"dist":{"shasum":"02b40887dab719cfd0b8d2348a24e593fc2a73a7","tarball":"https://registry.npmjs.org/@gputw/mcp-server/-/mcp-server-1.1.0.tgz","fileCount":3,"integrity":"sha512-BDlH0uiwocYH8CzV41wTEOCSDBb6qF4IM4hZjdIalwQbWG4xZehdVZluJZCRltZzA7aZVZApYXREssgQXfbjpw==","signatures":[{"sig":"MEYCIQDolQ5kAj9AqLSGur87l56IA9/rsES0UePKll0rzsxKSQIhANmG/bSjVPojwcF/aIcXCnA/c4+5g05B49UTXKgUlvfK","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIEd2PlvJk8bp36IQzcsrJrcpt63Bn2xOGG3t2t/ejvgdAiEA3+NyzEJ0OUREdmhhBzrh82kpAYjOs2G37s8kIvLTpY8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":785753},"type":"module","engines":{"node":">=18"},"gitHead":"d3a006faebc2543e38af13ee4d8d815c060c9315","scripts":{"test":"vitest run","build":"tsup","start":"node dist/stdio.mjs","type-check":"tsc --noEmit"},"_npmUser":{"name":"luketaiwan2019","email":"luketaiwan2019@gmail.com"},"repository":{"url":"git+https://github.com/GPUtw-ai/GPUtw-Skill.git","type":"git","directory":"mcp"},"_npmVersion":"10.8.2","description":"Official GPUtw MCP server — manage GPU instances and Vault storage on gputw.ai from any MCP client","directories":{},"_nodeVersion":"20.20.2","dependencies":{"zod":"^3.25.76","@modelcontextprotocol/sdk":"^1.30.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.3.5","vitest":"^2.1.8","typescript":"^5.7.2","@types/node":"^22.10.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-server_1.1.0_1792242715044_0.18901394858639242","host":"s3://npm-registry-packages-npm-production"}},"1.2.0":{"_id":"@gputw/mcp-server@1.2.0","bin":{"gputw-mcp":"dist/stdio.mjs"},"bugs":{"url":"https://github.com/GPUtw-ai/GPUtw-Skill/issues"},"dist":{"shasum":"c14bae5ab5302543c91855eb9204a2d2a45de6d1","tarball":"https://registry.npmjs.org/@gputw/mcp-server/-/mcp-server-1.2.0.tgz","fileCount":3,"integrity":"sha512-JABC/E2eXNT64LggSr9/3YeMA3xlH6TBNt9bxrmPYvNo/9XYwrSCjH/TK0qj2LnzzTSJaZyNVmgyuXQQT34QpQ==","signatures":[{"sig":"MEQCIG6hLEuBOPZReNX1dOHHE7Kgd1XyselpMAHzdOxKjqnFAiA1fBiXQUL0pQsx1WpDDqyQSuj7j/dRGIhj4NgbZXYr2g==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIF+Srwlo1l44fYnfIED5wZv48G5umuwfQagA07JeR4bdAiBNfOpzrzdLdavuYr3urhaurgVLs8JOeXpfA6HlrCQsEQ=="}],"unpackedSize":793324},"name":"@gputw/mcp-server","type":"module","author":{"url":"https://github.com/luke2023","name":"Luke Lin"},"engines":{"node":">=18"},"gitHead":"56d14a4102264d3906cb0d70b99b34b453a349a8","license":"MIT","scripts":{"test":"vitest run","build":"tsup","start":"node dist/stdio.mjs","type-check":"tsc --noEmit"},"version":"1.2.0","_npmUser":{"name":"luketaiwan2019","email":"luketaiwan2019@gmail.com"},"homepage":"https://github.com/GPUtw-ai/GPUtw-Skill","keywords":["mcp","modelcontextprotocol","gputw","gpu","cloud","taiwan"],"repository":{"url":"git+https://github.com/GPUtw-ai/GPUtw-Skill.git","type":"git","directory":"mcp"},"_npmVersion":"11.6.2","description":"Official GPUtw MCP server — manage GPU instances and Vault storage on gputw.ai from any MCP client","directories":{},"maintainers":[{"name":"luketaiwan2019","email":"luketaiwan2019@gmail.com"}],"_nodeVersion":"24.11.1","dependencies":{"zod":"^3.25.76","@modelcontextprotocol/sdk":"^1.30.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.3.5","vitest":"^2.1.8","typescript":"^5.7.2","@types/node":"^22.10.0"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-server_1.2.0_1794425644156_0.5573266334647751"}}},"time":{"created":"2026-10-17T13:10:58.911Z","modified":"2026-11-11T19:34:04.500Z","0.0.0-stage":"2026-10-17T13:10:58.911Z","1.1.0":"2026-10-17T13:11:55.134Z","1.2.0":"2026-11-11T19:34:04.289Z"},"bugs":{"url":"https://github.com/GPUtw-ai/GPUtw-Skill/issues"},"author":{"url":"https://github.com/luke2023","name":"Luke Lin"},"license":"MIT","homepage":"https://github.com/GPUtw-ai/GPUtw-Skill","keywords":["mcp","modelcontextprotocol","gputw","gpu","cloud","taiwan"],"repository":{"url":"git+https://github.com/GPUtw-ai/GPUtw-Skill.git","type":"git","directory":"mcp"},"description":"Official GPUtw MCP server — manage GPU instances and Vault storage on gputw.ai from any MCP client","maintainers":[{"name":"luketaiwan2019","email":"luketaiwan2019@gmail.com"}],"readme":"# @gputw/mcp-server\n\nOfficial [MCP](https://modelcontextprotocol.io) server for the **GPUtw** GPU cloud ([gputw.ai](https://gputw.ai)) — deploy and manage GPU instances, read live utilisation and logs, and move models into `/vault`, from any MCP client.\n\n> **Stable** (`1.2.0`). Ships as part of the [GPUtw Skill](https://github.com/GPUtw-ai/GPUtw-Skill), which also carries the integration guides the tools assume.\n\n## Install\n\n**Claude Code** — the plugin installs this server *and* the knowledge skill, and keeps the API key in secure storage:\n\n```\n/plugin marketplace add GPUtw-ai/GPUtw-Skill\n/plugin install gputw@gputw\n```\n\nOr register the server on its own. The repo ships a pre-built single-file bundle, so a clone plus `node` is all it needs (no `npm install`):\n\n```bash\ngit clone https://github.com/GPUtw-ai/GPUtw-Skill.git ~/.gputw-skill\nclaude mcp add gputw -s user -e GPUTW_API_KEY=gputw_live_xxx -- node ~/.gputw-skill/mcp/dist/stdio.mjs\n\n# or from npm, no clone needed\nclaude mcp add gputw -s user -e GPUTW_API_KEY=gputw_live_xxx -- npx -y @gputw/mcp-server@latest\n```\n\n**Any other client** (Claude Desktop, Cursor, VS Code, Windsurf, Codex, Gemini CLI). From npm; for a clone, use `\"command\": \"node\"` with the absolute path to `mcp/dist/stdio.mjs`:\n\n```json\n{\n  \"mcpServers\": {\n    \"gputw\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@gputw/mcp-server@latest\"],\n      \"env\": { \"GPUTW_API_KEY\": \"gputw_live_xxx\" }\n    }\n  }\n}\n```\n\nGet a key from the GPUtw dashboard → **API Keys**. Use the narrowest preset that fits: `readonly` to look, `deploy` to launch, `operator` to stop/restart, **Upload token** (write-only `vault:write`) for CI uploads.\n\n## Update\n\n- **Claude Code plugin:** run `/plugin marketplace update gputw`, then go to `/plugin` → **Installed** → `gputw` → **Update now** (or run `claude plugin update gputw@gputw` in a shell). Apply it with `/reload-plugins` or a new session. Plugins from GitHub marketplaces don't auto-update unless you turn it on under `/plugin` → **Marketplaces** → `gputw` → **Enable auto-update**.\n- **Clone install (any client):** run `git -C ~/.gputw-skill pull`, then restart the client (in Claude Code, reconnect from `/mcp`). The server runs straight from `mcp/dist/stdio.mjs`, so the pull is the whole update.\n- **npm (`npx -y @gputw/mcp-server@latest`):** restart the client so `npx` launches the server again. If it keeps starting an old version, pin the version explicitly, e.g. `@gputw/mcp-server@1.1.0`, and bump it when you update.\n- **Check the running version:** the `serverInfo.version` in the initialize handshake. Release notes are on [GitHub Releases](https://github.com/GPUtw-ai/GPUtw-Skill/releases).\n\n## Environment\n\n| Variable | Default | Purpose |\n|---|---|---|\n| `GPUTW_API_KEY` | — | Required for everything except the public catalogue |\n| `GPUTW_API_BASE` | `https://api.gputw.ai/api` | Rarely changed |\n| `GPUTW_TRANSFER_BASE` | `https://upload.gputw.ai` | Bulk-transfer host; falls back to the API host if absent |\n| `GPUTW_MCP_ALLOW_EXEC` | unset | Set to `1` to expose `exec-in-instance` |\n\n## Tools\n\n**Catalogue** — `list-gpus`, `list-available-nodes`, `list-templates`, `get-deploy-options`\n**Instances** — `create-instance` (optional `name`, `autoStopHours` / `autoStopAt`), `set-instance-auto-stop`, `rename-instance`, `stop-instance`, `delete-instance`, `delete-stopped-instances`, `restart-instance`\n**Live state** — `get-instance-status`, `get-instance-resources`, `get-instance-metrics`, `get-instance-logs`, `get-instance-events`\n**Vault** — `list-vault`, `get-vault-stats`, `upload-to-vault`, `download-model-to-vault`, `list-vault-downloads`\n**Opt-in** — `exec-in-instance` (root shell; needs `GPUTW_MCP_ALLOW_EXEC=1` *and* the `instances:exec` scope)\n\nDeploy order: `list-gpus` → `list-available-nodes` (with the `catalogId` from the first) → `list-templates` → `create-instance` (with the machine `id` as `nodeId`) → poll `get-instance-status` until `RUNNING`.\n\nNot yet covered (use the REST API): ports and exposures, API-key management, billing, teams, notifications, reservations.\n\n## Notes worth knowing\n\n- **Instances bill while `RUNNING`.** Always finish with `stop-instance` or `delete-instance`, and set `autoStopHours` on create as a safety net.\n- **Prefer `fastVault: true` machines** when a job loads large files from `/vault` on every start.\n- **A server-side download can show `failed` while it retries itself** (`error` mentions retrying / resuming); `download-model-to-vault` keeps waiting through that.\n- **Poll with `get-instance-status`,** not `list-instances` — it is the small, cheap read built for looping.\n- **Read `usage.source` on `get-instance-resources` before trusting a number.** `none` means there is no telemetry and every metric is `null`; that is not the same as an idle GPU.\n- **Responses are projected.** A catalogue record carries ~50 fields; the tools return the decision-relevant subset so the model's context is not spent on marketing copy.\n- **Errors are translated into actions** — which scope is missing, that credit is short, that a machine was taken, or that a non-envelope response means the request never reached the API (usually a missing `User-Agent`).\n- **`stop-instance` and `delete-instance` both destroy `/workspace`.** `/vault` is untouched.\n\n> **`claude plugin details` shows \"MCP servers (0)\".** That count only recognises a `.mcp.json` at the plugin root, and this plugin declares the server inline in `plugin.json` on purpose — a file at the repository root is *also* read as a project-scope MCP config by anyone working in a clone, where `CLAUDE_PLUGIN_ROOT` is undefined. Trust `claude mcp list`: `plugin:gputw:gputw … ✔ Connected` is the working state.\n\n## Security\n\nThe server acts with the full permissions of the key it is given.\n\n- The key is read from the environment, never written to disk by this server, and never logged. Anything matching `gputw_live_…` is redacted from returned text.\n- `exec-in-instance` is not registered unless you opt in. It is a root shell in your container, needs a scope only the `full` preset grants, and every call is written to your account audit trail.\n- In stdio mode the key stays on your machine; no third party is involved.\n\n## Develop\n\n```bash\nnpm install\nnpm run type-check\nnpm test        # 55 offline tests - no network, no API key\nnpm run build\nnode dist/stdio.mjs --help\n```\n\n`dist/stdio.mjs` is a single bundled file and is **committed** to the repository, so the Claude Code plugin runs it with plain `node` straight from a clone. CI rebuilds it and fails if the committed copy is stale.\n\n## License\n\nMIT — see [LICENSE](../LICENSE).\n","readmeFilename":"README.md"}