helipod-mcp 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 PT Samudra Inovasi Terpadu (Helipod)
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,215 @@
1
- # Temporary Holding Version
1
+ # Helipod MCP server and skills
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Use [Helipod](https://helipod.io) from AI coding tools: deploy apps and databases, run VPS servers, buy domains and edit DNS, and send email, by asking in plain language.
4
+
5
+ - **MCP server** (`helipod-mcp`): 70 tools over the Container, VPS, Domain and Email APIs. Works in Claude Code, Codex, Cursor, VS Code, Windsurf, Claude Desktop and any MCP client.
6
+ - **Skills** (`skills/`): step-by-step playbooks so the agent deploys, prices and confirms the way Helipod expects (price first, confirm before deleting, read build logs on failure).
7
+
8
+ Step-by-step guides for each tool (Claude Code, Codex, Cursor, VS Code, Gemini CLI, opencode, Windsurf, Claude Desktop, Cline and others): **https://docs.helipod.io/docs/helipod/ai-agents**
9
+
10
+ ## 1. Get a key
11
+
12
+ In the [dashboard](https://helipod.io/project) open a project, then **Settings → API keys**. Choose the products (Container API, VPS API, Domain API) and the reach (one project, or the whole account; the Domain API needs a whole-account key). The key starts with `hel_`.
13
+
14
+ Optional: an **email API key** from the project's **Email** section, for the email tools.
15
+
16
+ ```sh
17
+ export HELIPOD_API_KEY=hel_...
18
+ export HELIPOD_EMAIL_API_KEY=... # optional
19
+ ```
20
+
21
+ Start with a key limited to one project while you try things out.
22
+
23
+ ## 2. Connect your tool
24
+
25
+ The server is the npm package `helipod-mcp` (Node.js 18 or newer). The configs below run it with `npx -y helipod-mcp` (or the installed `helipod-mcp` command) and pass `HELIPOD_API_KEY` from your environment.
26
+
27
+ ### Claude Code (plugin: MCP server + skills)
28
+
29
+ ```sh
30
+ /plugin marketplace add helipodapp/mcp
31
+ /plugin install helipod@mcp
32
+ ```
33
+
34
+ MCP server only:
35
+
36
+ ```sh
37
+ claude mcp add helipod --env HELIPOD_API_KEY=$HELIPOD_API_KEY -- npx -y helipod-mcp
38
+ ```
39
+
40
+ ### Codex
41
+
42
+ Install once (Codex does not wait for MCP servers to start, so an installed server is ready for the first message while `npx` can miss it):
43
+
44
+ ```sh
45
+ npm install -g helipod-mcp
46
+ ```
47
+
48
+ `~/.codex/config.toml`:
49
+
50
+ ```toml
51
+ [mcp_servers.helipod]
52
+ command = "helipod-mcp"
53
+ env_vars = ["HELIPOD_API_KEY", "HELIPOD_EMAIL_API_KEY"]
54
+ ```
55
+
56
+ ### Cursor
57
+
58
+ `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):
59
+
60
+ ```json
61
+ {
62
+ "mcpServers": {
63
+ "helipod": {
64
+ "command": "npx",
65
+ "args": ["-y", "helipod-mcp"],
66
+ "env": { "HELIPOD_API_KEY": "${env:HELIPOD_API_KEY}" }
67
+ }
68
+ }
69
+ }
70
+ ```
71
+
72
+ ### Gemini CLI
73
+
74
+ `~/.gemini/settings.json`:
75
+
76
+ ```json
77
+ {
78
+ "mcpServers": {
79
+ "helipod": {
80
+ "command": "npx",
81
+ "args": ["-y", "helipod-mcp"],
82
+ "env": { "HELIPOD_API_KEY": "$HELIPOD_API_KEY" }
83
+ }
84
+ }
85
+ }
86
+ ```
87
+
88
+ Gemini CLI only starts MCP servers in folders you have trusted.
89
+
90
+ ### opencode
91
+
92
+ `~/.config/opencode/opencode.json`:
93
+
94
+ ```json
95
+ {
96
+ "mcp": {
97
+ "helipod": {
98
+ "type": "local",
99
+ "command": ["npx", "-y", "helipod-mcp"],
100
+ "environment": { "HELIPOD_API_KEY": "{env:HELIPOD_API_KEY}" }
101
+ }
102
+ }
103
+ }
104
+ ```
105
+
106
+ ### VS Code (Copilot agent mode)
107
+
108
+ `.vscode/mcp.json`:
109
+
110
+ ```json
111
+ {
112
+ "inputs": [{ "id": "helipod-key", "type": "promptString", "description": "Helipod API key", "password": true }],
113
+ "servers": {
114
+ "helipod": {
115
+ "type": "stdio",
116
+ "command": "npx",
117
+ "args": ["-y", "helipod-mcp"],
118
+ "env": { "HELIPOD_API_KEY": "${input:helipod-key}" }
119
+ }
120
+ }
121
+ }
122
+ ```
123
+
124
+ ### Windsurf
125
+
126
+ `~/.codeium/windsurf/mcp_config.json`:
127
+
128
+ ```json
129
+ {
130
+ "mcpServers": {
131
+ "helipod": {
132
+ "command": "npx",
133
+ "args": ["-y", "helipod-mcp"],
134
+ "env": { "HELIPOD_API_KEY": "hel_..." }
135
+ }
136
+ }
137
+ }
138
+ ```
139
+
140
+ ### Other clients
141
+
142
+ Run `npx -y helipod-mcp` as a stdio MCP server with `HELIPOD_API_KEY` (and optionally `HELIPOD_EMAIL_API_KEY`) in its environment.
143
+
144
+ ## Hosted server (nothing to install)
145
+
146
+ Clients that connect by URL can use `https://api.helipod.io/mcp` (Streamable HTTP) with `Authorization: Bearer hel_...` (and `X-Helipod-Email-Key` for the email tools). Same tools; the key is used per request and never stored.
147
+
148
+ ```sh
149
+ claude mcp add --transport http helipod https://api.helipod.io/mcp --header "Authorization: Bearer $HELIPOD_API_KEY"
150
+ ```
151
+
152
+ ```toml
153
+ # Codex: ~/.codex/config.toml
154
+ [mcp_servers.helipod]
155
+ url = "https://api.helipod.io/mcp"
156
+ bearer_token_env_var = "HELIPOD_API_KEY"
157
+ ```
158
+
159
+ ## Skills for other agents
160
+
161
+ Claude Code gets the skills with the plugin. For Codex, Cursor, Gemini CLI, opencode, GitHub Copilot and other agents that read `SKILL.md` files:
162
+
163
+ ```sh
164
+ npx skills add helipodapp/mcp -g
165
+ ```
166
+
167
+ Pick your agents when asked (or pass `-a codex cursor gemini-cli opencode -y`). Without `-g` the skills go into the current project only.
168
+
169
+ ## 3. Ask
170
+
171
+ - "Deploy this repo to my Helipod project and give me the URL."
172
+ - "Add Postgres to production and connect it to the api service."
173
+ - "Why did the last deploy fail?"
174
+ - "Is tokosaya.id available, and how much is it?"
175
+ - "Point www.tokosaya.id at my web service."
176
+ - "Create a 2 GB Ubuntu VPS and open port 443."
177
+ - "Send a test email from hello@mail.example.com to me."
178
+
179
+ ## Tools
180
+
181
+ | Area | Tools |
182
+ |---|---|
183
+ | Containers | projects, services (create from image, Git or Dockerfile), deploy, deployments and build logs, restart, variables, domains, scale, volumes, logs, metrics, templates, multi-service stacks |
184
+ | VPS | plans, create, power, reinstall, password, login details, terminate, renew, upgrade, auto-renew, firewall, snapshots |
185
+ | Domains | search, prices, register, transfer, renew, DNS records, nameservers, WHOIS privacy |
186
+ | Email | status, send, sent log, sending domains, templates, contacts |
187
+ | Other | `helipod_request` for any other documented endpoint |
188
+
189
+ Each tool is marked read-only, write or destructive, so clients can ask before running the risky ones. Calls that cost money support a dry run, and the server tells the agent to show the price and wait for your OK.
190
+
191
+ ## Safety
192
+
193
+ - The agent can only do what the key allows. Use a project-limited key and only the products you need.
194
+ - Paid actions (new services, VPS, domains, scaling) charge your Helipod wallet. Keep tool approvals on for write and destructive tools.
195
+ - Revoke a key in the dashboard at any time.
196
+
197
+ ## Configuration
198
+
199
+ | Variable | Default |
200
+ |---|---|
201
+ | `HELIPOD_API_KEY` | (required for containers, VPS, domains) |
202
+ | `HELIPOD_EMAIL_API_KEY` | (required for email tools) |
203
+ | `HELIPOD_API_URL` | `https://api.helipod.io/api` |
204
+ | `HELIPOD_EMAIL_API_URL` | `https://mail.helipod.io/api/email` |
205
+
206
+ ## Development
207
+
208
+ ```sh
209
+ bun install
210
+ bun run typecheck
211
+ bun test # catalog tests; live tests need HELIPOD_TEST_KEY
212
+ bun run build # dist/stdio.js, dist/index.js, dist/http.js
213
+ ```
214
+
215
+ Docs: https://docs.helipod.io