staticx-mcp-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 StaticX
+
+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,146 @@
+# StaticX MCP Server
+
+[![npm](https://img.shields.io/npm/v/staticx-mcp-server)](https://www.npmjs.com/package/staticx-mcp-server)
+[![license](https://img.shields.io/npm/l/staticx-mcp-server)](./LICENSE)
+
+Official Model Context Protocol server for [StaticX](https://staticx.site), the deployment infrastructure for static websites.
+
+Give Claude Code, Cursor, Codex, Cline, Windsurf, Claude Desktop, Zed, Continue, or another MCP client a scoped StaticX API token. The agent can then create sites, upload files, publish immutable releases, inspect logs, connect domains, and roll back with explicit confirmation.
+
+StaticX intentionally uses scoped API tokens instead of OAuth because it is designed for developers, CI/CD, automation tools, and AI agents.
+
+## Install
+
+The package runs directly through `npx`; a global install is not required.
+
+```json
+{
+  "mcpServers": {
+    "staticx": {
+      "command": "npx",
+      "args": ["-y", "staticx-mcp-server"],
+      "env": {
+        "STATICX_API_TOKEN": "sx_replace_with_your_token",
+        "STATICX_API_BASE_URL": "https://staticx.site/api/v1"
+      }
+    }
+  }
+}
+```
+
+Create the narrowest token that fits the job. A short-lived, site-scoped token is the safest default for one-site deployments.
+
+Full client-specific snippets are available in the [StaticX MCP documentation](https://staticx.site/documentation/mcp-clients).
+
+## Claude Code
+
+```bash
+claude mcp add staticx --scope user \
+  --env STATICX_API_TOKEN=sx_replace_with_your_token \
+  --env STATICX_API_BASE_URL=https://staticx.site/api/v1 \
+  -- npx -y staticx-mcp-server
+```
+
+## Codex
+
+```bash
+codex mcp add staticx \
+  --env STATICX_API_TOKEN=sx_replace_with_your_token \
+  --env STATICX_API_BASE_URL=https://staticx.site/api/v1 \
+  -- npx -y staticx-mcp-server
+```
+
+## Local HTTP debugging
+
+```bash
+STATICX_API_TOKEN=sx_replace_with_your_token npx staticx-mcp-server http
+```
+
+Then connect a Streamable HTTP client or the MCP Inspector to:
+
+```text
+http://localhost:3100/mcp
+```
+
+HTTP mode listens on `127.0.0.1` by default. Do not expose it publicly without a secure reverse proxy and a deliberate authentication policy.
+
+## Environment variables
+
+| Variable | Required | Purpose |
+| --- | --- | --- |
+| `STATICX_API_TOKEN` | Yes | Scoped StaticX API token. |
+| `STATICX_API_BASE_URL` | No | Defaults to `https://staticx.site/api/v1`. |
+| `STATICX_PROJECT_ID` | No | Default site ID for site-specific tools. |
+| `STATICX_TIMEOUT_MS` | No | API request timeout in milliseconds. |
+| `STATICX_MCP_PORT` | No | Local HTTP port, default `3100`. |
+| `STATICX_MCP_HOST` | No | Local HTTP bind host, default `127.0.0.1`. |
+
+Never paste a real token into documentation, source control, screenshots, prompts, or issue reports.
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `staticx_config` | Show configuration state without exposing secrets. |
+| `staticx_auth_check` | Validate the configured token. |
+| `staticx_list_workspaces` | List accessible workspaces. |
+| `staticx_create_workspace` | Create a workspace. |
+| `staticx_list_projects` | List accessible sites. |
+| `staticx_get_project` | Read one site. |
+| `staticx_create_project` | Create a site. |
+| `staticx_upload_zip` | Upload a static build ZIP. |
+| `staticx_import_url` | Import a public website URL. |
+| `staticx_deploy_project` | Publish the current workspace. |
+| `staticx_deploy_zip` | Upload and deploy a ZIP end to end. |
+| `staticx_list_deployments` | List immutable releases. |
+| `staticx_rollback_deployment` | Roll back with exact confirmation text. |
+| `staticx_delete_deployment` | Delete an inactive release with exact confirmation text. |
+| `staticx_get_logs` | Read recent site activity. |
+| `staticx_connect_custom_domain` | Start one-record custom domain setup. |
+| `staticx_get_custom_domain_status` | Read domain activation status. |
+| `staticx_set_environment_variables` | Sync site environment variables. |
+| `staticx_agent_guide` | Return the built-in safe deployment guide. |
+
+## Safety contract
+
+- Tokens are never returned by a tool.
+- Write tools explain their effect in their descriptions.
+- Rollback requires `ROLLBACK <deployment_id>`.
+- Deployment deletion requires `DELETE <deployment_id>`.
+- The server only calls the public StaticX `/api/v1` contract.
+- Use a site-scoped token for one-site agents and revoke it when the task is complete.
+
+## Recommended agent prompt
+
+```text
+Use StaticX MCP to deploy this static website.
+
+Before deploying:
+- build the project
+- verify index.html and 404.html exist at the build root
+- explain what you will publish
+
+After deploying:
+- return the live URL and release
+- inspect logs if anything fails
+- do not roll back or delete anything without asking me first
+```
+
+## Development
+
+```bash
+git clone https://github.com/madprodworks-coder/staticx-mcp-server.git
+cd staticx-mcp-server
+npm install
+npm test
+```
+
+The MCP package must continue to use the public StaticX API. It must not import Laravel controllers, services, or internal engine classes.
+
+## Security
+
+Please report vulnerabilities privately as described in [SECURITY.md](./SECURITY.md). Do not open a public issue containing tokens, private URLs, or customer data.
+
+## License
+
+MIT

package/bin/staticx-mcp-server.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+await import('../src/server.mjs');

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "staticx-mcp-server",
+  "version": "1.0.0",
+  "mcpName": "io.github.madprodworks-coder/staticx-mcp-server",
+  "description": "Official API-token-first MCP server for deploying and operating StaticX static sites.",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/madprodworks-coder/staticx-mcp-server.git"
+  },
+  "homepage": "https://staticx.site/documentation/mcp",
+  "bugs": {
+    "url": "https://github.com/madprodworks-coder/staticx-mcp-server/issues"
+  },
+  "bin": {
+    "staticx-mcp-server": "./bin/staticx-mcp-server.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE",
+    "server.json"
+  ],
+  "scripts": {
+    "test": "node --test tests/*.test.mjs",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "staticx",
+    "mcp",
+    "model-context-protocol",
+    "ai-agent",
+    "static-sites",
+    "deployment"
+  ],
+  "license": "MIT",
+  "author": "StaticX",
+  "engines": {
+    "node": ">=18.17"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  }
+}

package/server.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
+  "name": "io.github.madprodworks-coder/staticx-mcp-server",
+  "description": "Deploy and operate versioned StaticX static sites with scoped API tokens.",
+  "version": "1.0.0",
+  "repository": {
+    "url": "https://github.com/madprodworks-coder/staticx-mcp-server",
+    "source": "github"
+  },
+  "websiteUrl": "https://staticx.site/documentation/mcp",
+  "packages": [
+    {
+      "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
+      "identifier": "staticx-mcp-server",
+      "version": "1.0.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "STATICX_API_TOKEN",
+          "description": "Scoped StaticX API token.",
+          "isRequired": true,
+          "isSecret": true
+        },
+        {
+          "name": "STATICX_API_BASE_URL",
+          "description": "StaticX API base URL.",
+          "default": "https://staticx.site/api/v1",
+          "isRequired": false,
+          "isSecret": false
+        },
+        {
+          "name": "STATICX_PROJECT_ID",
+          "description": "Optional default StaticX site ID.",
+          "isRequired": false,
+          "isSecret": false
+        }
+      ]
+    }
+  ]
+}

package/src/server.mjs

@@ -0,0 +1,736 @@
+#!/usr/bin/env node
+
+import { readFile, stat } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { createMcpExpressApp } from '@modelcontextprotocol/sdk/server/express.js';
+import * as z from 'zod/v4';
+
+const SERVER_VERSION = '1.0.0';
+const DEFAULT_API_BASE_URL = 'https://staticx.site/api/v1';
+const DEFAULT_HTTP_PORT = 3100;
+const requestToken = new AsyncLocalStorage();
+
+class StaticxApiError extends Error {
+  constructor(message, status, payload) {
+    super(message);
+    this.name = 'StaticxApiError';
+    this.status = status;
+    this.payload = payload;
+  }
+}
+
+function apiBaseUrl() {
+  return (process.env.STATICX_API_BASE_URL || DEFAULT_API_BASE_URL).replace(/\/+$/, '');
+}
+
+function apiToken() {
+  const token = requestToken.getStore() || process.env.STATICX_API_TOKEN || '';
+
+  if (token.trim() === '') {
+    throw new Error('STATICX_API_TOKEN is required. Create a scoped API token in StaticX and pass it as an MCP environment variable.');
+  }
+
+  return token;
+}
+
+function defaultProjectId() {
+  const value = process.env.STATICX_PROJECT_ID || '';
+
+  return value.trim() === '' ? null : value.trim();
+}
+
+function resolveProjectId(args = {}) {
+  const projectId = args.project_id ?? defaultProjectId();
+
+  if (projectId === null || projectId === undefined || String(projectId).trim() === '') {
+    throw new Error('A project_id is required. Pass project_id to the tool or set STATICX_PROJECT_ID.');
+  }
+
+  return String(projectId).trim();
+}
+
+function timeoutMs() {
+  const value = Number.parseInt(process.env.STATICX_TIMEOUT_MS || '120000', 10);
+
+  return Number.isFinite(value) && value > 0 ? value : 120000;
+}
+
+async function parseResponse(response) {
+  const contentType = response.headers.get('content-type') || '';
+
+  if (contentType.includes('application/json')) {
+    return response.json();
+  }
+
+  const text = await response.text();
+
+  return text === '' ? null : { message: text };
+}
+
+function normalizeApiError(payload, status) {
+  if (payload && typeof payload === 'object') {
+    const message = typeof payload.message === 'string' && payload.message.trim() !== ''
+      ? payload.message
+      : `StaticX API request failed with HTTP ${status}.`;
+
+    return message;
+  }
+
+  return `StaticX API request failed with HTTP ${status}.`;
+}
+
+async function apiRequest(path, options = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs());
+  const headers = {
+    Accept: 'application/json',
+    Authorization: `Bearer ${apiToken()}`,
+    ...(options.headers || {}),
+  };
+
+  try {
+    const response = await fetch(`${apiBaseUrl()}${path}`, {
+      ...options,
+      headers,
+      signal: controller.signal,
+    });
+    const payload = await parseResponse(response);
+
+    if (!response.ok) {
+      throw new StaticxApiError(normalizeApiError(payload, response.status), response.status, payload);
+    }
+
+    return payload;
+  } catch (error) {
+    if (error?.name === 'AbortError') {
+      throw new Error(`StaticX API request timed out after ${timeoutMs()}ms.`);
+    }
+
+    throw error;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function jsonRequest(path, method, body = {}) {
+  return apiRequest(path, {
+    method,
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+}
+
+async function zipBlob(zipPath) {
+  const fileStat = await stat(zipPath);
+
+  if (!fileStat.isFile()) {
+    throw new Error(`ZIP path is not a file: ${zipPath}`);
+  }
+
+  if (!zipPath.toLowerCase().endsWith('.zip')) {
+    throw new Error(`ZIP path must end with .zip: ${zipPath}`);
+  }
+
+  return new Blob([await readFile(zipPath)], { type: 'application/zip' });
+}
+
+function textResult(title, data) {
+  return {
+    content: [
+      {
+        type: 'text',
+        text: `${title}\n\n${JSON.stringify(data, null, 2)}`,
+      },
+    ],
+  };
+}
+
+function textOnly(text) {
+  return {
+    content: [
+      {
+        type: 'text',
+        text,
+      },
+    ],
+  };
+}
+
+function errorResult(error) {
+  const payload = error instanceof StaticxApiError ? error.payload : null;
+  const status = error instanceof StaticxApiError ? error.status : null;
+
+  return {
+    isError: true,
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify({
+          message: error?.message || 'StaticX MCP tool failed.',
+          status,
+          payload,
+        }, null, 2),
+      },
+    ],
+  };
+}
+
+function tool(handler) {
+  return async (args) => {
+    try {
+      return await handler(args || {});
+    } catch (error) {
+      return errorResult(error);
+    }
+  };
+}
+
+function agentGuideText() {
+  return [
+    '# StaticX MCP',
+    '',
+    'This MCP server gives AI agents a safe tool contract over the StaticX `/api/v1` API.',
+    '',
+    'Required environment:',
+    '- `STATICX_API_TOKEN`, a scoped StaticX API token created from Settings.',
+    '- `STATICX_API_BASE_URL`, optional and defaults to `https://staticx.site/api/v1`.',
+    '- `STATICX_PROJECT_ID`, optional default site for site tools.',
+    '',
+    'Safety rules:',
+    '- Never print, log, or return the API token.',
+    '- Explain the intended change before using a write tool.',
+    '- Ask for explicit user confirmation before rollback or deletion.',
+    '- Prefer a site-scoped, short-lived token for one-site jobs.',
+    '',
+    'Recommended deployment flow:',
+    '1. Build the website locally.',
+    '2. Confirm the build output contains `index.html` or `index.htm` plus `404.html` at the root.',
+    '3. Zip the build output so those required files are at the archive root.',
+    '4. Call `staticx_deploy_zip` with the ZIP path and project ID.',
+    '5. If the user wants a custom domain, call `staticx_connect_custom_domain` and return the DNS record to create.',
+    '6. Return the live URL, custom domain status, or the exact MCP/API error.',
+    '',
+    'The MCP server does not call engine classes directly. It uses the same API contract as external tools.',
+  ].join('\n');
+}
+
+function createServer() {
+  const server = new McpServer({
+    name: 'staticx',
+    version: SERVER_VERSION,
+  }, {
+    capabilities: {
+      resources: {},
+      prompts: {},
+      tools: {},
+    },
+  });
+
+  server.registerResource(
+  'staticx-agent-guide',
+  'staticx://agent-guide',
+  {
+    title: 'StaticX Agent Guide',
+    description: 'How agents should deploy static sites safely through StaticX MCP.',
+    mimeType: 'text/markdown',
+  },
+  async (uri) => ({
+    contents: [
+      {
+        uri: uri.href,
+        mimeType: 'text/markdown',
+        text: agentGuideText(),
+      },
+    ],
+  }),
+);
+
+  server.registerPrompt('deploy-static-site', {
+  title: 'Deploy static site',
+  description: 'Instruction template for deploying a local static build through StaticX MCP.',
+  argsSchema: {
+    project_id: z.string().optional().describe('StaticX site ID. If omitted, STATICX_PROJECT_ID must be configured.'),
+    output_dir: z.string().default('dist').describe('Local build output directory that should be zipped before upload.'),
+  },
+}, async ({ project_id: projectId, output_dir: outputDir }) => ({
+  messages: [
+    {
+      role: 'user',
+      content: {
+        type: 'text',
+        text: [
+          'Deploy this static website using the StaticX MCP server.',
+          '',
+          `Project ID: ${projectId || 'use STATICX_PROJECT_ID'}`,
+          `Build output directory: ${outputDir}`,
+          '',
+          'Steps:',
+          '1. Build the project locally.',
+          '2. Confirm the build output contains index.html or index.htm plus 404.html at the root.',
+          '3. Zip the contents of the build output directory so those required files stay at the ZIP root.',
+          '4. Call staticx_deploy_zip with the project_id and zip_path.',
+          '5. If a custom domain is requested, call staticx_connect_custom_domain with domain_name.',
+          '6. Check deployment status and logs if the deploy fails.',
+          '7. Return the live URL, custom domain DNS record, or the exact API error message.',
+        ].join('\n'),
+      },
+    },
+  ],
+}));
+
+server.registerTool('staticx_config', {
+  title: 'StaticX MCP config',
+  description: 'Show the MCP server configuration state without exposing token values.',
+  inputSchema: {},
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: false,
+  },
+}, tool(async () => textResult('StaticX MCP configuration', {
+  api_base_url: apiBaseUrl(),
+  has_api_token: Boolean(process.env.STATICX_API_TOKEN),
+  default_project_id: defaultProjectId(),
+  timeout_ms: timeoutMs(),
+})));
+
+server.registerTool('staticx_auth_check', {
+  title: 'Check StaticX API auth',
+  description: 'Validate the configured API token against GET /user.',
+  inputSchema: {},
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+}, tool(async () => textResult('StaticX API token is valid', await apiRequest('/user'))));
+
+server.registerTool('staticx_list_workspaces', {
+  title: 'List workspaces',
+  description: 'List workspaces visible to the configured API token.',
+  inputSchema: {},
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+}, tool(async () => textResult('Visible workspaces', await apiRequest('/workspaces'))));
+
+server.registerTool('staticx_create_workspace', {
+  title: 'Create workspace',
+  description: 'Create a workspace for the authenticated account.',
+  inputSchema: {
+    name: z.string().min(1).max(255).describe('Workspace name.'),
+  },
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+}, tool(async ({ name }) => textResult('Workspace created', await jsonRequest('/workspaces', 'POST', { name }))));
+
+server.registerTool('staticx_list_projects', {
+  title: 'List projects',
+  description: 'List projects visible to the configured API token, optionally filtered by workspace.',
+  inputSchema: {
+    workspace_id: z.number().int().positive().optional().describe('Optional workspace ID.'),
+  },
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+}, tool(async ({ workspace_id: workspaceId }) => {
+  const query = workspaceId ? `?workspace_id=${encodeURIComponent(String(workspaceId))}` : '';
+
+  return textResult('Visible projects', await apiRequest(`/projects${query}`));
+}));
+
+server.registerTool('staticx_get_project', {
+  title: 'Get project',
+  description: 'Fetch one StaticX project by ID.',
+  inputSchema: {
+    project_id: z.union([z.string(), z.number()]).optional().describe('Project ID. Uses STATICX_PROJECT_ID when omitted.'),
+  },
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+}, tool(async (args) => textResult('Project', await apiRequest(`/projects/${resolveProjectId(args)}`))));
+
+server.registerTool('staticx_connect_custom_domain', {
+  title: 'Connect custom domain',
+  description: 'Move a project to a custom domain and return the one DNS record the user must create.',
+  inputSchema: {
+    project_id: z.union([z.string(), z.number()]).optional().describe('Project ID. Uses STATICX_PROJECT_ID when omitted.'),
+    domain_name: z.string().min(1).max(253).describe('Custom domain, for example app.example.com.'),
+  },
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+}, tool(async (args) => textResult('Custom domain setup', await jsonRequest(
+  `/projects/${resolveProjectId(args)}/domain`,
+  'POST',
+  {
+    domain: args.domain_name,
+  },
+))));
+
+server.registerTool('staticx_get_custom_domain_status', {
+  title: 'Get custom domain status',
+  description: 'Read DNS, SSL, activation, and setup instructions for the project custom domain.',
+  inputSchema: {
+    project_id: z.union([z.string(), z.number()]).optional().describe('Project ID. Uses STATICX_PROJECT_ID when omitted.'),
+  },
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+}, tool(async (args) => textResult('Custom domain status', await apiRequest(`/projects/${resolveProjectId(args)}/domain`))));
+
+server.registerTool('staticx_create_project', {
+  title: 'Create site',
+  description: 'Create an empty StaticX site. Upload files or deploy a ZIP afterwards.',
+  inputSchema: {
+    name: z.string().max(255).optional().describe('Optional project display name.'),
+    description: z.string().max(1000).optional().describe('Optional project description.'),
+    workspace_id: z.number().int().positive().optional().describe('Optional workspace ID.'),
+  },
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+}, tool(async (args) => textResult('Project created', await jsonRequest('/projects', 'POST', args))));
+
+server.registerTool('staticx_upload_zip', {
+  title: 'Upload ZIP',
+  description: 'Upload a built static site ZIP into a project workspace. The ZIP root should contain index.html or index.htm plus 404.html.',
+  inputSchema: {
+    project_id: z.union([z.string(), z.number()]).optional().describe('Project ID. Uses STATICX_PROJECT_ID when omitted.'),
+    zip_path: z.string().min(1).describe('Absolute or current-working-directory-relative path to the ZIP file.'),
+    path: z.string().optional().describe('Optional workspace path. Usually leave empty for project root.'),
+    overwrite_confirmed: z.boolean().default(true).describe('Confirm overwriting existing files.'),
+  },
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+}, tool(async (args) => {
+  const form = new FormData();
+  form.set('mode', 'zip');
+  form.set('overwrite_confirmed', args.overwrite_confirmed === false ? '0' : '1');
+
+  if (args.path) {
+    form.set('path', args.path);
+  }
+
+  form.set('archive', await zipBlob(args.zip_path), basename(args.zip_path));
+
+  return textResult('ZIP uploaded', await apiRequest(`/projects/${resolveProjectId(args)}/files`, {
+    method: 'POST',
+    body: form,
+  }));
+}));
+
+server.registerTool('staticx_import_url', {
+  title: 'Import URL',
+  description: 'Queue a public URL import into the project workspace.',
+  inputSchema: {
+    project_id: z.union([z.string(), z.number()]).optional().describe('Project ID. Uses STATICX_PROJECT_ID when omitted.'),
+    source_url: z.string().url().describe('Public URL to import.'),
+    path: z.string().optional().describe('Optional workspace path. Usually leave empty for project root.'),
+  },
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+}, tool(async (args) => {
+  const form = new FormData();
+  form.set('mode', 'url');
+  form.set('source_url', args.source_url);
+
+  if (args.path) {
+    form.set('path', args.path);
+  }
+
+  return textResult('URL import queued', await apiRequest(`/projects/${resolveProjectId(args)}/files`, {
+    method: 'POST',
+    body: form,
+  }));
+}));
+
+server.registerTool('staticx_deploy_project', {
+  title: 'Deploy project',
+  description: 'Publish a project.',
+  inputSchema: {
+    project_id: z.union([z.string(), z.number()]).optional().describe('Project ID. Uses STATICX_PROJECT_ID when omitted.'),
+  },
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+}, tool(async (args) => textResult('Deployment completed', await jsonRequest(
+  `/projects/${resolveProjectId(args)}/deployments`,
+  'POST',
+))));
+
+server.registerTool('staticx_list_deployments', {
+  title: 'List deployments',
+  description: 'List published deployment versions for a project.',
+  inputSchema: {
+    project_id: z.union([z.string(), z.number()]).optional().describe('Project ID. Uses STATICX_PROJECT_ID when omitted.'),
+  },
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+}, tool(async (args) => textResult('Deployments', await apiRequest(`/projects/${resolveProjectId(args)}/deployments`))));
+
+server.registerTool('staticx_rollback_deployment', {
+  title: 'Roll back deployment',
+  description: 'Make a previous deployment live. Explain the target first and require exact user confirmation.',
+  inputSchema: {
+    project_id: z.union([z.string(), z.number()]).optional().describe('Site ID. Uses STATICX_PROJECT_ID when omitted.'),
+    deployment_id: z.union([z.string(), z.number()]).describe('Deployment ID that should become live.'),
+    confirmation: z.string().describe('Exact text: ROLLBACK <deployment_id>'),
+  },
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: true,
+    openWorldHint: true,
+  },
+}, tool(async (args) => {
+  const deploymentId = String(args.deployment_id).trim();
+  const expected = `ROLLBACK ${deploymentId}`;
+
+  if (args.confirmation !== expected) {
+    throw new Error(`Rollback requires explicit confirmation. Pass confirmation exactly as: ${expected}`);
+  }
+
+  return textResult('Deployment rolled back', await jsonRequest(
+    `/projects/${resolveProjectId(args)}/deployments/${encodeURIComponent(deploymentId)}/rollback`,
+    'POST',
+  ));
+}));
+
+server.registerTool('staticx_delete_deployment', {
+  title: 'Delete deployment',
+  description: 'Permanently delete one inactive deployment. Explain the impact first and require exact user confirmation.',
+  inputSchema: {
+    project_id: z.union([z.string(), z.number()]).optional().describe('Site ID. Uses STATICX_PROJECT_ID when omitted.'),
+    deployment_id: z.union([z.string(), z.number()]).describe('Inactive deployment ID to permanently delete.'),
+    confirmation: z.string().describe('Exact text: DELETE <deployment_id>'),
+  },
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: true,
+    openWorldHint: true,
+  },
+}, tool(async (args) => {
+  const deploymentId = String(args.deployment_id).trim();
+  const expected = `DELETE ${deploymentId}`;
+
+  if (args.confirmation !== expected) {
+    throw new Error(`Deletion requires explicit confirmation. Pass confirmation exactly as: ${expected}`);
+  }
+
+  await apiRequest(`/projects/${resolveProjectId(args)}/deployments/${encodeURIComponent(deploymentId)}`, {
+    method: 'DELETE',
+  });
+
+  return textOnly(`Deployment ${deploymentId} was deleted.`);
+}));
+
+server.registerTool('staticx_get_logs', {
+  title: 'Get project logs',
+  description: 'Read recent project activity logs.',
+  inputSchema: {
+    project_id: z.union([z.string(), z.number()]).optional().describe('Project ID. Uses STATICX_PROJECT_ID when omitted.'),
+  },
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+}, tool(async (args) => textResult('Project logs', await apiRequest(`/projects/${resolveProjectId(args)}/logs`))));
+
+server.registerTool('staticx_deploy_zip', {
+  title: 'Deploy ZIP end to end',
+  description: 'Upload a ZIP, deploy it directly, and return project, deployment, and logs.',
+  inputSchema: {
+    project_id: z.union([z.string(), z.number()]).optional().describe('Project ID. Uses STATICX_PROJECT_ID when omitted.'),
+    zip_path: z.string().min(1).describe('Path to ZIP file whose root contains index.html or index.htm plus 404.html.'),
+    path: z.string().optional().describe('Optional workspace path. Usually leave empty for project root.'),
+    overwrite_confirmed: z.boolean().default(true).describe('Confirm overwriting existing files.'),
+  },
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+}, tool(async (args) => {
+  const projectId = resolveProjectId(args);
+  const form = new FormData();
+  form.set('mode', 'zip');
+  form.set('overwrite_confirmed', args.overwrite_confirmed === false ? '0' : '1');
+
+  if (args.path) {
+    form.set('path', args.path);
+  }
+
+  form.set('archive', await zipBlob(args.zip_path), basename(args.zip_path));
+
+  const upload = await apiRequest(`/projects/${projectId}/files`, {
+    method: 'POST',
+    body: form,
+  });
+  const deployment = await jsonRequest(`/projects/${projectId}/deployments`, 'POST');
+  const project = await apiRequest(`/projects/${projectId}`);
+  const deployments = await apiRequest(`/projects/${projectId}/deployments`);
+  const logs = await apiRequest(`/projects/${projectId}/logs`);
+
+  return textResult('ZIP deployed end to end', {
+    upload,
+    deployment,
+    project,
+    deployments,
+    logs,
+    live_url: project?.data?.public_url || null,
+  });
+}));
+
+server.registerTool('staticx_set_environment_variables', {
+  title: 'Set environment variables',
+  description: 'Sync site environment variables through the StaticX API.',
+  inputSchema: {
+    project_id: z.union([z.string(), z.number()]).optional().describe('Project ID. Uses STATICX_PROJECT_ID when omitted.'),
+    variables: z.record(z.string(), z.string()).describe('Key-value environment variables to store.'),
+  },
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+}, tool(async (args) => textResult('Environment variables synced', await jsonRequest(
+  `/projects/${resolveProjectId(args)}/environment-variables`,
+  'PUT',
+  {
+    variables: Object.entries(args.variables).map(([key, value]) => ({
+      key: key.toUpperCase(),
+      value,
+      is_secret: true,
+    })),
+  },
+))));
+
+server.registerTool('staticx_agent_guide', {
+  title: 'StaticX agent guide',
+  description: 'Return concise instructions for an agent using this MCP server.',
+  inputSchema: {},
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: false,
+  },
+}, tool(async () => textOnly(agentGuideText())));
+
+  return server;
+}
+
+function bearerToken(request) {
+  const authorization = request.headers.authorization || '';
+
+  return authorization.toLowerCase().startsWith('bearer ')
+    ? authorization.slice(7).trim()
+    : '';
+}
+
+async function startStdio() {
+  const server = createServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+async function startHttp() {
+  const app = createMcpExpressApp();
+  const port = Number.parseInt(process.env.STATICX_MCP_PORT || String(DEFAULT_HTTP_PORT), 10);
+  const host = process.env.STATICX_MCP_HOST || '127.0.0.1';
+
+  app.post('/mcp', async (request, response) => {
+    const server = createServer();
+    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+    const token = bearerToken(request);
+
+    try {
+      await requestToken.run(token, async () => {
+        await server.connect(transport);
+        await transport.handleRequest(request, response, request.body);
+      });
+    } catch (error) {
+      if (!response.headersSent) {
+        response.status(500).json({
+          jsonrpc: '2.0',
+          error: {
+            code: -32603,
+            message: error?.message || 'StaticX MCP request failed.',
+          },
+          id: null,
+        });
+      }
+    } finally {
+      response.on('close', () => {
+        transport.close();
+        server.close();
+      });
+    }
+  });
+
+  app.get('/mcp', (_request, response) => {
+    response.status(405).json({
+      jsonrpc: '2.0',
+      error: { code: -32000, message: 'Use POST for MCP requests.' },
+      id: null,
+    });
+  });
+
+  app.delete('/mcp', (_request, response) => {
+    response.status(405).json({
+      jsonrpc: '2.0',
+      error: { code: -32000, message: 'This stateless MCP endpoint has no session to close.' },
+      id: null,
+    });
+  });
+
+  app.listen(port, host, (error) => {
+    if (error) {
+      console.error('StaticX MCP HTTP server failed to start:', error);
+      process.exit(1);
+    }
+
+    console.error(`StaticX MCP HTTP server listening at http://${host}:${port}/mcp`);
+  });
+}
+
+const mode = process.argv[2] || 'stdio';
+
+if (mode === 'http') {
+  await startHttp();
+} else if (mode === 'stdio') {
+  await startStdio();
+} else {
+  console.error(`Unknown StaticX MCP mode "${mode}". Use "stdio" or "http".`);
+  process.exit(1);
+}