vpsnet-mcp 1.0.3 → 1.0.5

package/README.md

@@ -15,6 +15,22 @@
 - Ordering new VPS instances
 - System status & pricing
 
+## Prerequisites
+
+Before installing, ensure you have:
+
+1. **Node.js 18 or newer**
+   - Check: `node --version`
+   - Linux/macOS: [nodejs.org](https://nodejs.org) or your package manager
+   - Windows: `winget install OpenJS.NodeJS.LTS` or download from [nodejs.org](https://nodejs.org)
+   - After installing Node.js, **restart your terminal/editor**
+
+2. **For Claude Code (CLI or VS Code extension) users:**
+   - Claude Code CLI installed globally: `npm install -g @anthropic-ai/claude-code`
+   - Check: `claude --version`
+
+3. **Active [VPSnet.com](https://www.vpsnet.com) account** with an API key (see [Getting an API key](#getting-an-api-key))
+
 ## SSH access workflow
 
 This MCP server manages your VPS infrastructure through the VPSnet.com API, including SSH key provisioning. Once an SSH key is deployed to a VPS, the AI assistant can connect directly using its environment's terminal (e.g. Claude Code's Bash tool, Cline's terminal).
@@ -28,15 +44,38 @@ This MCP server manages your VPS infrastructure through the VPSnet.com API, incl
 
 Most AI coding environments (Claude Code, Cline, Cursor, Codex) have built-in terminal access, so the AI can SSH into your VPS immediately after deploying a key — no extra tools needed.
 
-For environments without native SSH access, consider pairing this with a dedicated SSH MCP server for direct server connectivity.
+For environments without native SSH access, pair this with [mcp-server-ssh](https://github.com/bacarrdy/mcp-server-ssh) for direct server connectivity via MCP tools.
 
-## Requirements
+**Combined config:**
 
-- Node.js 18 or newer
-- A [VPSnet.com](https://www.vpsnet.com) account with an API key
+```json
+{
+  "mcpServers": {
+    "vpsnet": {
+      "command": "npx",
+      "args": ["-y", "vpsnet-mcp"],
+      "env": {
+        "VPSNET_API_KEY": "your_api_key_here"
+      }
+    },
+    "ssh": {
+      "command": "npx",
+      "args": ["-y", "mcp-server-ssh"]
+    }
+  }
+}
+```
 
 ## Getting started
 
+Choose your environment:
+
+- [Claude Code (CLI)](#claude-code) — Terminal-based AI coding
+- [Claude Code for VS Code](#claude-code-for-vs-code-extension) — VS Code extension
+- [Claude Desktop](#claude-desktop) — Desktop app
+- [VS Code with GitHub Copilot](#vs-code-with-github-copilot) — Copilot agent mode
+- [Cline](#cline) / [Cursor](#cursor) / [Windsurf](#windsurf) / [Roo Code](#roo-code) / [Codex](#codex) — Other clients
+
 The standard config works across most MCP clients:
 
 ```json
@@ -68,6 +107,47 @@ export VPSNET_API_KEY="your_api_key_here"
 
 </details>
 
+<details>
+<summary>Claude Code for VS Code Extension</summary>
+
+> This section is for the **Claude Code VS Code extension**, not GitHub Copilot. If you use VS Code with GitHub Copilot, see the [VS Code with GitHub Copilot](#vs-code-with-github-copilot) section instead.
+
+**Step 1:** Install Claude Code CLI globally (required for the extension):
+
+```bash
+npm install -g @anthropic-ai/claude-code
+```
+
+**Step 2:** Add the MCP server via CLI:
+
+```bash
+claude mcp add vpsnet -- npx -y vpsnet-mcp
+```
+
+**Step 3:** Add your API key. Edit `~/.claude.json` (or `C:\Users\<username>\.claude.json` on Windows), find the `vpsnet` server section and add the `env` block:
+
+```json
+"vpsnet": {
+    "type": "stdio",
+    "command": "npx",
+    "args": ["-y", "vpsnet-mcp"],
+    "env": {
+        "VPSNET_API_KEY": "your_api_key_here",
+        "VPSNET_API_URL": "https://api.vpsnet.com"
+    }
+}
+```
+
+**Step 4:** Restart VS Code completely (Ctrl+Shift+P > "Reload Window" or close and reopen).
+
+**Step 5:** Verify by asking Claude: *"Get my VPSnet account info"*
+
+> **Windows users:** Use PowerShell or CMD (not Git Bash) when running `claude mcp add` commands.
+
+> The `code --add-mcp` command does **NOT** work with Claude Code extension — that's for VS Code Copilot only.
+
+</details>
+
 <details>
 <summary>Claude Desktop</summary>
 
@@ -164,7 +244,7 @@ Open Roo Code MCP settings and add to `roo_mcp_settings.json`:
 </details>
 
 <details>
-<summary>VS Code (Copilot)</summary>
+<summary>VS Code with GitHub Copilot</summary>
 
 Install using the VS Code CLI:
 
@@ -174,6 +254,8 @@ code --add-mcp '{"name":"vpsnet","command":"npx","args":["-y","vpsnet-mcp"],"env
 
 Or add to your VS Code MCP config manually using the standard config above.
 
+> This is for **GitHub Copilot** agent mode in VS Code. For the **Claude Code** extension, see the [Claude Code for VS Code Extension](#claude-code-for-vs-code-extension) section.
+
 </details>
 
 <details>
@@ -183,6 +265,14 @@ Follow the [Windsurf MCP documentation](https://docs.windsurf.com/windsurf/mcp).
 
 </details>
 
+## Windows Users
+
+- Use **PowerShell or CMD** (not Git Bash) for `claude mcp add` commands
+- Config file location: `C:\Users\<YourUsername>\.claude.json`
+- Install Node.js: `winget install OpenJS.NodeJS.LTS` or download from [nodejs.org](https://nodejs.org)
+- After installing Node.js, **restart your terminal and VS Code**
+- Environment variables in Claude Code extension must be in the `env` object within `.claude.json`, NOT system environment variables
+
 ## Environment variables
 
 | Variable | Required | Description |
@@ -298,10 +388,51 @@ Follow the [Windsurf MCP documentation](https://docs.windsurf.com/windsurf/mcp).
 1. Log in at [vpsnet.com](https://www.vpsnet.com)
 2. Go to **Account** > **API Keys**
 3. Click **Create API Key**
-4. Set the scope to match your needs and copy the key
+4. Give it a name and copy the key
 
 The key is shown only once — store it securely.
 
+## Troubleshooting
+
+### MCP tools not appearing in Claude Code VS Code extension
+
+1. Install Claude Code CLI: `npm install -g @anthropic-ai/claude-code`
+2. Verify: `claude --version` should show a version number
+3. Add server via CLI: `claude mcp add vpsnet -- npx -y vpsnet-mcp`
+4. **Completely restart VS Code** (not just reload window)
+5. Check `~/.claude.json` for correct configuration
+
+### `claude: command not found`
+
+Install the Claude Code CLI globally:
+
+```bash
+npm install -g @anthropic-ai/claude-code
+```
+
+Verify your PATH includes npm global packages. On Windows, restart your terminal after installing.
+
+### Environment variables not working
+
+For Claude Code extension, environment variables **must** be in the `env` object within `.claude.json`, NOT system environment variables:
+
+```json
+"vpsnet": {
+    "type": "stdio",
+    "command": "npx",
+    "args": ["-y", "vpsnet-mcp"],
+    "env": {
+        "VPSNET_API_KEY": "your_actual_key_here"
+    }
+}
+```
+
+### API key errors
+
+- Verify the key is correct (starts with `vpsnet_`)
+- Keys are shown only once at creation — if lost, create a new one
+- Check that the key hasn't expired (Account > API Keys)
+
 ## License
 
 [MIT](LICENSE)

package/build/index.js

@@ -26,19 +26,32 @@ const server = new McpServer({ name: "vpsnet", version: "1.0.0" }, {
         "Use that terminal to run: ssh -o StrictHostKeyChecking=no root@<vps_ip>",
         "",
         "### Step-by-step SSH key flow:",
-        "1. Read YOUR local machine's public key from ~/.ssh/id_rsa.pub or ~/.ssh/id_ed25519.pub",
-        "2. Upload it via create_ssh_key(name, public_key) — name it descriptively e.g. 'claude-code-key'",
-        "3. Deploy it to the VPS via deploy_ssh_key(orderNo, ssh_key_id) OR pass sshKey when ordering a new VPS",
-        "4. SSH directly using your environment's terminal: ssh -o StrictHostKeyChecking=no root@<vps_ip>",
-        "5. Now you can run any commands inside the VPS (apt install, configure services, deploy apps, etc.)",
+        "1. Check if a local SSH public key exists: try reading ~/.ssh/id_rsa.pub, ~/.ssh/id_ed25519.pub, or ~/.ssh/id_ecdsa.pub",
+        "2. If NO local key exists, you MUST generate one BEFORE proceeding:",
+        "   - If mcp-server-ssh is available: use ssh_keygen(type='ecdsa', bits=256) to generate a key pair, then save the files locally",
+        "   - If a terminal/bash is available: run ssh-keygen -t ed25519 -N '' -f ~/.ssh/id_ed25519",
+        "   - Then read the newly created public key file",
+        "3. Upload the public key via create_ssh_key(name, public_key) — name it descriptively e.g. 'claude-code-key'",
+        "4. Deploy it to the VPS via deploy_ssh_key(orderNo, ssh_key_id) OR pass sshKey when ordering a new VPS",
+        "5. SSH directly using your environment's terminal: ssh -o StrictHostKeyChecking=no root@<vps_ip>",
+        "6. Now you can run any commands inside the VPS (apt install, configure services, deploy apps, etc.)",
         "",
         "### Important SSH notes:",
         "- ALWAYS prefer sshKey over rootPassword — it's more secure and enables direct access.",
         "- NEVER use someone else's SSH key — always read from the local machine where you are running.",
         "- Use -o StrictHostKeyChecking=no when connecting to newly created VPS to avoid host key prompts.",
         "- order_service uses 'sshKey' (camelCase) but deploy_ssh_key uses 'ssh_key' (snake_case) — different field names!",
-        "- Only fall back to rootPassword if the local machine has no SSH key (e.g. Windows without OpenSSH).",
-        "- If your environment has no terminal/bash access at all, consider using a dedicated SSH MCP server for connectivity.",
+        "- Only fall back to rootPassword if key generation is truly impossible (no ssh-keygen, no mcp-server-ssh, no filesystem write).",
+        "",
+        "## Pairing with mcp-server-ssh (npm: mcp-server-ssh)",
+        "If mcp-server-ssh is also installed, you get powerful SSH tools for direct VPS management:",
+        "- ssh_keygen: generate SSH key pairs without needing ssh-keygen binary",
+        "- ssh_connect + ssh_exec: execute commands on VPS via pure JS SSH (no native SSH client needed)",
+        "- sftp_write/sftp_read: transfer files to/from VPS without scp",
+        "Combined workflow: order VPS with vpsnet-mcp → generate key with ssh_keygen → upload with create_ssh_key → connect with ssh_connect → manage with ssh_exec/sftp_*",
+        "Combined config for Claude Desktop:",
+        '  "vpsnet": { "command": "npx", "args": ["-y", "vpsnet-mcp"], "env": { "VPSNET_API_KEY": "..." } }',
+        '  "ssh": { "command": "npx", "args": ["-y", "mcp-server-ssh"] }',
         "",
         "## Plan changes",
         "Plan changes are FREE — remaining time is recalculated (upgrade = shorter expiry, downgrade = longer expiry).",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vpsnet-mcp",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "type": "module",
   "description": "MCP server for managing VPSnet.com virtual private servers",
   "bin": {