hostinger-api-mcp 0.1.43 → 0.2.2

package/.env.example

@@ -4,6 +4,10 @@ TRANSPORT=stdio # Fixed to stdio
 # Debug
 DEBUG=false
 
+# OAuth Configuration (used when HOSTINGER_API_TOKEN is not set — stdio mode only)
+# Uncomment to override the default OAuth issuer:
+# OAUTH_ISSUER=https://auth.hostinger.com
+
 # --- Authorization Configuration --- 
 # Example for HTTP Bearer Token "apiToken"
 APITOKEN=YOUR_TOKEN_VALUE

package/README.md

@@ -63,7 +63,44 @@ Pick the binary that matches your agent's scope. `hostinger-api-mcp` remains the
 
 The following environment variables can be configured when running the server:
 - `DEBUG`: Enable debug logging (true/false) (default: false)
-- `API_TOKEN`: Your API token, which will be sent in the `Authorization` header.
+- `HOSTINGER_API_TOKEN`: Your API token, which will be sent in the `Authorization` header. When set, OAuth is bypassed entirely.
+- `API_TOKEN`: Deprecated alias for `HOSTINGER_API_TOKEN`. Will be removed in a future version — prefer `HOSTINGER_API_TOKEN`.
+- `OAUTH_ISSUER`: OAuth server base URL (default: `https://auth.hostinger.com`). Only used when `HOSTINGER_API_TOKEN` is not set.
+
+## Authentication
+
+The server supports two authentication methods:
+
+### API Token (recommended for CI/scripts)
+
+Set `HOSTINGER_API_TOKEN` in the environment or `.env` file. When present it always takes precedence — no OAuth code runs.
+
+### OAuth 2.0 with PKCE (interactive sign-in)
+
+When `HOSTINGER_API_TOKEN` is not set and the server runs in stdio mode, OAuth 2.0 with PKCE is used automatically on the first authenticated tool call:
+
+1. A dynamic OAuth client is registered with the issuer (RFC 7591) — once per machine.
+2. A browser window opens to the authorization page.
+3. After sign-in, the server captures the redirect on a local ephemeral port, exchanges the code for tokens, and stores them.
+4. Subsequent calls reuse the stored access token; expired tokens are refreshed automatically. If a refresh token is revoked, the browser flow is re-launched.
+
+Credentials are stored at:
+- macOS / Linux: `~/.config/hostinger-mcp/credentials.json` (mode 0600)
+- Windows: `%APPDATA%\hostinger-mcp\credentials.json`
+
+Credentials are shared across all Hostinger MCP binaries (`hostinger-api-mcp`, `hostinger-vps-mcp`, etc.).
+
+**Manual commands:**
+
+```bash
+# Run the OAuth sign-in flow immediately (don't wait for the first tool call)
+hostinger-api-mcp --login
+
+# Revoke stored credentials
+hostinger-api-mcp --logout
+```
+
+**HTTP transport note:** OAuth sign-in is not supported in `--http` mode. Set `HOSTINGER_API_TOKEN` before using `--http`.
 
 ## Usage
 
@@ -76,7 +113,7 @@ The following environment variables can be configured when running the server:
             "command": "hostinger-api-mcp",
             "env": {
                 "DEBUG": "false",
-                "API_TOKEN": "YOUR API TOKEN"
+                "HOSTINGER_API_TOKEN": "YOUR API TOKEN"
             }
         }
     }
@@ -107,10 +144,12 @@ hostinger-api-mcp --http --host 0.0.0.0 --port 8150
 
 ```
 Options:
-  --http           Use HTTP streaming transport
+  --http           Use HTTP streaming transport (requires HOSTINGER_API_TOKEN env var)
   --stdio          Use Server-Sent Events transport (default)
   --host {host}    Hostname or IP address to listen on (default: 127.0.0.1)
   --port {port}    Port to bind to (default: 8100)
+  --login          Run OAuth sign-in flow and exit
+  --logout         Revoke stored OAuth credentials and exit
   --help           Show help message
 ```
 
@@ -128,7 +167,7 @@ import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/
 const transport = new StreamableHTTPClientTransport({
   url: "http://localhost:8100/",
   headers: {
-    "Authorization": `Bearer ${process.env.API_TOKEN}`
+    "Authorization": `Bearer ${process.env.HOSTINGER_API_TOKEN}`
   }
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hostinger-api-mcp",
-  "version": "0.1.43",
+  "version": "0.2.2",
   "description": "MCP server for Hostinger API",
   "repository": {
     "type": "git",

package/src/core/oauth-error.html

@@ -0,0 +1,90 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Authentication failed</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=DM+Sans:wght@400;500;700&display=swap" rel="stylesheet">
+  <style>
+    :root {
+      --primary: #673DE6;
+      --primary-hover: #5025D1;
+      --deep: #2F1C6A;
+      --bg: #F4F5FF;
+      --lavender: #b6b2ff;
+    }
+    *, *::before, *::after { box-sizing: border-box; }
+    html, body { height: 100%; margin: 0; }
+    body {
+      font-family: "DM Sans", system-ui, -apple-system, BlinkMacSystemFont, sans-serif;
+      background: var(--bg);
+      color: var(--deep);
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      padding: 24px;
+    }
+    .card {
+      background: #ffffff;
+      border-radius: 16px;
+      box-shadow: 0 10px 40px rgba(31, 19, 70, 0.08);
+      padding: 48px 56px;
+      max-width: 480px;
+      width: 100%;
+      text-align: center;
+    }
+    .icon {
+      width: 72px;
+      height: 72px;
+      border-radius: 50%;
+      background: #ffffff;
+      color: var(--primary);
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      margin-bottom: 24px;
+      border: 2px solid var(--primary);
+    }
+    .icon svg { width: 36px; height: 36px; }
+    h1 {
+      font-size: 28px;
+      font-weight: 700;
+      letter-spacing: -0.01em;
+      margin: 0 0 12px;
+      color: var(--deep);
+    }
+    p {
+      font-size: 16px;
+      line-height: 1.5;
+      margin: 0 0 16px;
+      color: var(--deep);
+      opacity: 0.72;
+    }
+    .error-detail {
+      display: inline-block;
+      margin-top: 8px;
+      font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, "Cascadia Code", monospace;
+      font-size: 14px;
+      color: var(--deep);
+      background: var(--bg);
+      padding: 8px 14px;
+      border-radius: 8px;
+      border: 1px solid var(--lavender);
+    }
+  </style>
+</head>
+<body>
+  <main class="card" role="alert" aria-live="assertive">
+    <div class="icon" aria-hidden="true">
+      <svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+        <path d="M18 6L6 18M6 6l12 12" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"/>
+      </svg>
+    </div>
+    <h1>Authentication failed</h1>
+    <p>You can close this tab.</p>
+    <code class="error-detail">{{error}}</code>
+  </main>
+</body>
+</html>

package/src/core/oauth-success.html

@@ -0,0 +1,77 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Authentication successful</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=DM+Sans:wght@400;500;700&display=swap" rel="stylesheet">
+  <style>
+    :root {
+      --primary: #673DE6;
+      --primary-hover: #5025D1;
+      --deep: #2F1C6A;
+      --bg: #F4F5FF;
+      --lavender: #b6b2ff;
+    }
+    *, *::before, *::after { box-sizing: border-box; }
+    html, body { height: 100%; margin: 0; }
+    body {
+      font-family: "DM Sans", system-ui, -apple-system, BlinkMacSystemFont, sans-serif;
+      background: var(--bg);
+      color: var(--deep);
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      padding: 24px;
+    }
+    .card {
+      background: #ffffff;
+      border-radius: 16px;
+      box-shadow: 0 10px 40px rgba(31, 19, 70, 0.08);
+      padding: 48px 56px;
+      max-width: 480px;
+      width: 100%;
+      text-align: center;
+    }
+    .icon {
+      width: 72px;
+      height: 72px;
+      border-radius: 50%;
+      background: var(--primary);
+      color: #ffffff;
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      margin-bottom: 24px;
+    }
+    .icon svg { width: 36px; height: 36px; }
+    h1 {
+      font-size: 28px;
+      font-weight: 700;
+      letter-spacing: -0.01em;
+      margin: 0 0 12px;
+      color: var(--deep);
+    }
+    p {
+      font-size: 16px;
+      line-height: 1.5;
+      margin: 0;
+      color: var(--deep);
+      opacity: 0.72;
+    }
+  </style>
+</head>
+<body>
+  <main class="card" role="status" aria-live="polite">
+    <div class="icon" aria-hidden="true">
+      <svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+        <path d="M20 6L9 17l-5-5" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"/>
+      </svg>
+    </div>
+    <h1>Authentication successful</h1>
+    <p>You can close this tab and return to your application.</p>
+  </main>
+</body>
+</html>

package/src/core/oauth.js

@@ -0,0 +1,406 @@
+import { createHash, randomBytes } from "crypto";
+import { createServer } from "http";
+import { readFile, writeFile, mkdir } from "fs/promises";
+import { existsSync, readFileSync } from "fs";
+import { exec } from "child_process";
+import { fileURLToPath } from "url";
+import path from "path";
+import os from "os";
+import axios from "axios";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SUCCESS_HTML = readFileSync(path.join(__dirname, "oauth-success.html"), "utf8");
+const ERROR_HTML_TEMPLATE = readFileSync(path.join(__dirname, "oauth-error.html"), "utf8");
+
+function escapeHtml(s) {
+  return String(s).replace(/[&<>"']/g, (ch) => ({
+    "&": "&amp;",
+    "<": "&lt;",
+    ">": "&gt;",
+    '"': "&quot;",
+    "'": "&#39;",
+  })[ch]);
+}
+
+const DEFAULT_ISSUER = "https://auth.hostinger.com";
+const REGISTER_PATH = "/api/external/v1/oauth-server/register";
+const AUTHORIZE_PATH = "/api/external/v1/oauth-server/authorize";
+const TOKEN_PATH = "/api/external/v1/oauth-server/token";
+const REVOKE_PATH = "/api/external/v1/oauth-server/token/revoke";
+const CLIENT_NAME = "hostinger-mcp";
+const CALLBACK_PATH = "/oauth/callback";
+const CREDENTIALS_DIR_NAME = "hostinger-mcp";
+const CREDENTIALS_FILE_NAME = "credentials.json";
+const EXPIRY_BUFFER_SECONDS = 60;
+
+export class OAuthRefreshError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "OAuthRefreshError";
+    this.code = "OAUTH_INVALID_GRANT";
+  }
+}
+
+/**
+ * Resolve the bearer token from the environment. HOSTINGER_API_TOKEN is the
+ * preferred name; API_TOKEN and APITOKEN are kept as backwards-compatible
+ * aliases (API_TOKEN is deprecated and will be removed in a future version).
+ * Empty values fall through, matching the previous `||` behavior.
+ */
+export function getEnvToken() {
+  return (
+    process.env["HOSTINGER_API_TOKEN"] ||
+    process.env["API_TOKEN"] ||
+    process.env["APITOKEN"]
+  );
+}
+
+export class OAuthProvider {
+  constructor(issuerBaseUrl) {
+    this.issuer = (
+      issuerBaseUrl ||
+      process.env["OAUTH_ISSUER"] ||
+      DEFAULT_ISSUER
+    ).replace(/\/$/, "");
+    this._loginInProgress = null;
+  }
+
+  async getAccessToken() {
+    const envToken = getEnvToken();
+    if (envToken) {
+      return envToken;
+    }
+
+    if (!this._loginInProgress) {
+      this._loginInProgress = this._resolveToken().finally(() => {
+        this._loginInProgress = null;
+      });
+    }
+    return await this._loginInProgress;
+  }
+
+  async _resolveToken() {
+    const creds = await this._load();
+
+    if (
+      creds &&
+      creds.access_token &&
+      creds.expires_at &&
+      Date.now() < creds.expires_at
+    ) {
+      return creds.access_token;
+    }
+
+    if (creds && creds.refresh_token && creds.client_id) {
+      try {
+        return await this._refresh(creds);
+      } catch (err) {
+        if (err.code !== "OAUTH_INVALID_GRANT") {
+          throw err;
+        }
+      }
+    }
+
+    return await this._login();
+  }
+
+  async login() {
+    if (this._loginInProgress) {
+      return await this._loginInProgress;
+    }
+    this._loginInProgress = this._login().finally(() => {
+      this._loginInProgress = null;
+    });
+    return await this._loginInProgress;
+  }
+
+  /**
+   * Force a fresh token, bypassing the cached-token fast path. Called by the
+   * runtime when the API rejects an apparently-valid token with 401. Tries the
+   * refresh grant first; if the refresh token is also dead (4xx), falls through
+   * to the full browser login flow.
+   */
+  async reauthenticate() {
+    if (!this._loginInProgress) {
+      this._loginInProgress = this._reauthenticate().finally(() => {
+        this._loginInProgress = null;
+      });
+    }
+    return await this._loginInProgress;
+  }
+
+  async _reauthenticate() {
+    const creds = await this._load();
+    if (creds && creds.refresh_token && creds.client_id) {
+      try {
+        return await this._refresh(creds);
+      } catch (err) {
+        if (err.code !== "OAUTH_INVALID_GRANT") {
+          throw err;
+        }
+      }
+    }
+    return await this._login();
+  }
+
+  async logout() {
+    const creds = await this._load();
+    if (!creds) {
+      return;
+    }
+    if (creds.access_token && creds.client_id) {
+      try {
+        const params = new URLSearchParams();
+        params.set("token", creds.access_token);
+        params.set("client_id", creds.client_id);
+        await axios.post(`${this.issuer}${REVOKE_PATH}`, params.toString(), {
+          headers: { "Content-Type": "application/x-www-form-urlencoded" },
+          validateStatus: () => true,
+        });
+      } catch (_) {}
+    }
+    await this._save({ client_id: creds.client_id });
+  }
+
+  async _login() {
+    let creds = (await this._load()) || {};
+
+    const port = await this._getFreePort();
+    const redirectUri = `http://127.0.0.1:${port}${CALLBACK_PATH}`;
+
+    if (!creds.client_id) {
+      creds.client_id = await this._register(redirectUri);
+    }
+
+    const { verifier, challenge } = this._generatePKCE();
+    const state = this._generateState();
+
+    const callbackPromise = this._listenForCallback(state, port);
+
+    const authorizeUrl = new URL(`${this.issuer}${AUTHORIZE_PATH}`);
+    authorizeUrl.searchParams.set("client_id", creds.client_id);
+    authorizeUrl.searchParams.set("redirect_uri", redirectUri);
+    authorizeUrl.searchParams.set("state", state);
+    authorizeUrl.searchParams.set("code_challenge", challenge);
+    authorizeUrl.searchParams.set("code_challenge_method", "S256");
+    authorizeUrl.searchParams.set("response_type", "code");
+
+    this._openBrowser(authorizeUrl.toString());
+
+    const { code } = await callbackPromise;
+
+    const params = new URLSearchParams();
+    params.set("grant_type", "authorization_code");
+    params.set("code", code);
+    params.set("code_verifier", verifier);
+    params.set("redirect_uri", redirectUri);
+    params.set("client_id", creds.client_id);
+
+    const resp = await axios.post(
+      `${this.issuer}${TOKEN_PATH}`,
+      params.toString(),
+      {
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        validateStatus: () => true,
+      },
+    );
+
+    if (resp.status >= 400) {
+      throw new Error(
+        `Token exchange failed (${resp.status}): ${JSON.stringify(resp.data)}`,
+      );
+    }
+
+    const tokens = resp.data;
+    const newCreds = {
+      client_id: creds.client_id,
+      access_token: tokens.access_token,
+      refresh_token: tokens.refresh_token,
+      expires_at:
+        Date.now() + (tokens.expires_in - EXPIRY_BUFFER_SECONDS) * 1000,
+    };
+    await this._save(newCreds);
+    return tokens.access_token;
+  }
+
+  async _refresh(creds) {
+    const params = new URLSearchParams();
+    params.set("grant_type", "refresh_token");
+    params.set("refresh_token", creds.refresh_token);
+    params.set("client_id", creds.client_id);
+
+    const resp = await axios.post(
+      `${this.issuer}${TOKEN_PATH}`,
+      params.toString(),
+      {
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        validateStatus: () => true,
+      },
+    );
+
+    if (resp.status >= 400 && resp.status < 500) {
+      throw new OAuthRefreshError(
+        `Refresh token rejected (${resp.status}): ${JSON.stringify(resp.data)}`,
+      );
+    }
+
+    if (resp.status >= 500) {
+      throw new Error(
+        `Token refresh failed (${resp.status}): ${JSON.stringify(resp.data)}`,
+      );
+    }
+
+    const tokens = resp.data;
+    const newCreds = {
+      client_id: creds.client_id,
+      access_token: tokens.access_token,
+      refresh_token: tokens.refresh_token || creds.refresh_token,
+      expires_at:
+        Date.now() + (tokens.expires_in - EXPIRY_BUFFER_SECONDS) * 1000,
+    };
+    await this._save(newCreds);
+    return tokens.access_token;
+  }
+
+  async _register(redirectUri) {
+    const resp = await axios.post(
+      `${this.issuer}${REGISTER_PATH}`,
+      {
+        client_name: CLIENT_NAME,
+        redirect_uris: [redirectUri],
+      },
+      {
+        headers: { "Content-Type": "application/json" },
+        validateStatus: () => true,
+      },
+    );
+
+    if (resp.status >= 400 || !resp.data || !resp.data.client_id) {
+      throw new Error(
+        `Client registration failed (${resp.status}): ${JSON.stringify(resp.data)}`,
+      );
+    }
+    return resp.data.client_id;
+  }
+
+  _generatePKCE() {
+    const verifier = randomBytes(32).toString("base64url");
+    const challenge = createHash("sha256").update(verifier).digest("base64url");
+    return { verifier, challenge };
+  }
+
+  _generateState() {
+    return randomBytes(16).toString("hex");
+  }
+
+  _listenForCallback(expectedState, port) {
+    return new Promise((resolve, reject) => {
+      const server = createServer((req, res) => {
+        const url = new URL(req.url, `http://127.0.0.1:${port}`);
+        if (url.pathname !== CALLBACK_PATH) {
+          res.writeHead(404);
+          res.end();
+          return;
+        }
+
+        const code = url.searchParams.get("code");
+        const state = url.searchParams.get("state");
+        const error = url.searchParams.get("error");
+
+        const body = error
+          ? ERROR_HTML_TEMPLATE.replace("{{error}}", escapeHtml(error))
+          : SUCCESS_HTML;
+        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+        res.end(body);
+
+        setImmediate(() => server.close());
+
+        if (error) {
+          return reject(
+            new Error(`OAuth error from authorization server: ${error}`),
+          );
+        }
+        if (!state || state !== expectedState) {
+          return reject(new Error("OAuth state mismatch"));
+        }
+        if (!code) {
+          return reject(new Error("No authorization code received"));
+        }
+        resolve({ code, port });
+      });
+      server.on("error", reject);
+      server.listen(port, "127.0.0.1");
+    });
+  }
+
+  _getFreePort() {
+    return new Promise((resolve, reject) => {
+      const srv = createServer();
+      srv.unref();
+      srv.on("error", reject);
+      srv.listen(0, "127.0.0.1", () => {
+        const addr = srv.address();
+        const port = typeof addr === "object" && addr ? addr.port : 0;
+        srv.close(() => resolve(port));
+      });
+    });
+  }
+
+  _credentialsPath() {
+    if (process.platform === "win32") {
+      const base = process.env["APPDATA"] || os.homedir();
+      return path.join(base, CREDENTIALS_DIR_NAME, CREDENTIALS_FILE_NAME);
+    }
+    return path.join(
+      os.homedir(),
+      ".config",
+      CREDENTIALS_DIR_NAME,
+      CREDENTIALS_FILE_NAME,
+    );
+  }
+
+  async _load() {
+    const p = this._credentialsPath();
+    if (!existsSync(p)) {
+      return null;
+    }
+    try {
+      const raw = await readFile(p, "utf8");
+      return JSON.parse(raw);
+    } catch (_) {
+      return null;
+    }
+  }
+
+  async _save(creds) {
+    const p = this._credentialsPath();
+    await mkdir(path.dirname(p), { recursive: true });
+    const writeOpts =
+      process.platform === "win32"
+        ? { encoding: "utf8" }
+        : { encoding: "utf8", mode: 0o600 };
+    await writeFile(p, JSON.stringify(creds, null, 2), writeOpts);
+  }
+
+  _openBrowser(url) {
+    process.stderr.write(`\n[OAuth] Opening browser for sign-in:\n  ${url}\n`);
+    process.stderr.write(
+      "[OAuth] If the browser does not open, copy the URL above into one manually.\n\n",
+    );
+    let cmd;
+    if (process.platform === "darwin") {
+      cmd = `open "${url}"`;
+    } else if (process.platform === "win32") {
+      cmd = `start "" "${url}"`;
+    } else {
+      cmd = `xdg-open "${url}"`;
+    }
+    exec(cmd, (err) => {
+      if (err) {
+        process.stderr.write(
+          `[OAuth] Could not auto-launch browser: ${err.message}\n`,
+        );
+      }
+    });
+  }
+}