@hoststack.dev/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HostStack Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,114 @@
+# @hoststack.dev/mcp
+
+Model Context Protocol (MCP) server for [HostStack](https://hoststack.dev) — let Claude, Cursor, and any other MCP-capable agent deploy services, manage databases, rotate env vars, and read logs on your HostStack team.
+
+Two ways to run it:
+
+- **Hosted** (recommended) — point your client at `https://api.hoststack.dev/api/mcp` with a Bearer API key. No local install.
+- **Local stdio** — `npx -y @hoststack.dev/mcp` runs the same server in-process and talks JSON-RPC over stdin/stdout.
+
+## Quick start
+
+### 1. Get an API key
+
+Open the dashboard at <https://hoststack.dev/dashboard/settings/api-keys> and create a key with `full_access` permission. The key is bound to a single team — every tool call operates on that team automatically; agents never need to pass `teamId`.
+
+### 2. Wire it into your client
+
+#### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+	"mcpServers": {
+		"hoststack": {
+			"command": "npx",
+			"args": ["-y", "@hoststack.dev/mcp"],
+			"env": {
+				"HOSTSTACK_API_KEY": "hs_live_..."
+			}
+		}
+	}
+}
+```
+
+#### Cursor
+
+Add to `~/.cursor/mcp.json` (or via Settings → MCP):
+
+```json
+{
+	"hoststack": {
+		"command": "npx",
+		"args": ["-y", "@hoststack.dev/mcp"],
+		"env": {
+			"HOSTSTACK_API_KEY": "hs_live_..."
+		}
+	}
+}
+```
+
+#### Claude Code
+
+```bash
+claude mcp add hoststack -- npx -y @hoststack.dev/mcp -e HOSTSTACK_API_KEY=hs_live_...
+```
+
+#### Any other client (hosted)
+
+```http
+POST https://api.hoststack.dev/api/mcp
+Authorization: Bearer hs_live_...
+Content-Type: application/json
+```
+
+The endpoint speaks the streamable-HTTP MCP transport. Stateless — every request is independent; no session bookkeeping.
+
+### 3. Generate config snippets
+
+The CLI knows how to print config for the three big clients so you don't have to memorise the shape:
+
+```bash
+npx @hoststack.dev/mcp --print-config claude-desktop
+npx @hoststack.dev/mcp --print-config cursor
+npx @hoststack.dev/mcp --print-config claude-code
+```
+
+If `HOSTSTACK_API_KEY` is set in your shell, it gets baked into the snippet; otherwise you'll see a `hs_live_your_api_key_here` placeholder you can search-and-replace.
+
+## Tool inventory
+
+31 tools, grouped by resource:
+
+| Category | Read | Write |
+|---|---|---|
+| **projects** | `list_projects`, `get_project` | `create_project`, `update_project` |
+| **services** | `list_services`, `get_service`, `get_service_metrics`, `get_service_logs` | `update_service`, `update_service_config`, `suspend_service`, `resume_service` |
+| **deploys** | `list_deploys`, `get_deploy`, `get_deploy_logs` | `trigger_deploy`, `cancel_deploy` |
+| **databases** | `list_databases`, `get_database` | — (use the dashboard for create/delete/credentials) |
+| **domains** | `list_domains` | `add_domain`, `verify_domain`, `remove_domain` |
+| **env-vars** | `list_env_vars` | `set_env_var`, `delete_env_var`, `bulk_set_env_vars` |
+| **cron** | `list_cron_executions`, `get_cron_execution` | — |
+| **activity-log** | `list_activity_log` | — |
+| **meta** | `get_me` | — |
+
+A few design notes worth knowing as a caller:
+
+- **`set_env_var` / `delete_env_var` are key-based.** You don't need an env-var ID; the MCP looks up the existing var by key first, then patches or deletes by ID under the hood.
+- **`list_env_vars` masks secret values.** Anything stored with `is_secret: true` comes back as `••••••`. The masking happens server-side, so you can't accidentally leak a secret to the agent's context window.
+- **`get_service_logs` and `get_deploy_logs` are snapshots.** Streaming logs over MCP isn't supported — re-call the tool to get newer entries. Use the dashboard's `/dashboard/services/:id/logs` for live tails.
+- **No `delete_project`, `delete_service`, or `create_service`.** Destructive cascades and the wizard flow are dashboard-only — too risky / too complex for v0.x.
+- **Telemetry, hosted only.** When you use `https://api.hoststack.dev/api/mcp`, we record one row per tool call (tool name, duration, ok/error, SHA-derived hash of input args — never the args themselves) for the analytics page and on-call alerts. Retained 30 days. The local stdio install records nothing.
+
+## Environment variables
+
+| Var | Required | Default | Notes |
+|---|---|---|---|
+| `HOSTSTACK_API_KEY` | yes | — | Bearer token. `hs_live_…` for prod, `hs_test_…` for the test team. |
+| `HOSTSTACK_BASE_URL` | no | `https://api.hoststack.dev` | Override for self-hosted or staging. |
+| `HOSTSTACK_MCP_TRACE` | no | unset | Set to `1` to emit one NDJSON line per tool call to stderr. Useful for `2> mcp-trace.log` debugging without colliding with the JSON-RPC body on stdout. |
+
+## License
+
+MIT — see [LICENSE](./LICENSE).