appleby-proxy-mcp 0.0.0-stage → 1.0.0

package/AGENTS.md

@@ -0,0 +1,111 @@
+# AGENTS.md — proxy-mcp
+
+## What this repo is
+
+The MCP server for the appleby.cloud **Nginx Proxy Manager** (NPM on `aplb-proxy`):
+**43 typed tools** over proxy-api's `/npm/v1` facade. A single-file Node ESM program, published to npm as
+**`appleby-proxy-mcp`** (`proxy-mcp` on npm is an unrelated package) and run with
+`npx -y appleby-proxy-mcp`.
+
+It owns only the translation layer: tool names, zod schemas, descriptions, URL construction, and
+a second masking pass. It does not own permissions (proxy-api's `npm.Allowed`), credential
+redaction (proxy-api's `npm.Redact`), the audit trail (proxy-api's `npm.write` Monitor events)
+or NPM's credentials (proxy-api holds them).
+
+## Stack & dependencies
+
+- Node ≥ 18 (global `fetch`, `AbortSignal.timeout`), ESM, top-level `await`.
+- `@modelcontextprotocol/sdk` ^1.29, `zod` ^4.4 (declared explicitly, as in lattice-mcp).
+- No build step. `npm test` runs `verify.mjs`.
+
+## Project structure
+
+| Path | Role |
+|------|------|
+| `index.js` | Setup flow, config, masking, `api()`/`npm()` helpers, shared schemas, every tool grouped under `// ───` banners, transport |
+| `verify.mjs` | `npm test`: syntax, duplicate/misnamed tools, doc counts, version consistency, masking behaviour, proxy-api boundary |
+| `README.md` | Human-facing setup and the full tool tables (verify.mjs checks every tool is listed) |
+
+Keep new tools inside their banner group.
+
+## Running, building & testing
+
+```bash
+npm install
+npm test                                              # must pass before publishing
+PROXY_API_URL=https://proxy-api.appleby.cloud PROXY_API_TOKEN=frt_… node index.js
+```
+
+Smoke test over stdio (the sleeps matter — requests otherwise race the handshake):
+
+```bash
+{ echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}'
+  sleep 2; echo '{"jsonrpc":"2.0","method":"notifications/initialized"}'
+  echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'; sleep 2; } \
+  | PROXY_API_URL=x PROXY_API_TOKEN=x node index.js
+```
+
+## How code is written here
+
+- **Request shapes come from NPM's `/api/schema`, never from guesses.** NPM validates bodies
+  with `additionalProperties: false`, so an extra key is a 400 and a missing enum value a silent
+  wrong default. Fetch `GET /api/schema` from the running NPM (unauthenticated) when adding or
+  changing a tool, and note the NPM version.
+- `body()` strips undefined keys, so updates send only what the caller passed. Fields that are
+  whole-value replacements (`advanced_config`, `locations`, access-list `items`/`clients`) say so
+  in their descriptions.
+- Destructive tools say "Destructive" and name the read to do first.
+- `sanitise()` runs on every response in `api()`; proxy-api's `"[redacted]"` passes through.
+
+## Domain & architecture
+
+```
+agent ─stdio─▶ proxy-mcp ─HTTPS, Bearer frt_─▶ proxy-api.appleby.cloud (LAN) ─▶ /npm/v1/<path>
+                                                   │ Forta token + grant on platform 11
+                                                   │ npm.Allowed · npm.Redact · npm.write event
+                                                   ▼
+                                     NPM API (agent account) on aplb-proxy
+```
+
+Unavailable by design (proxy-api returns 403): `/tokens`, `/users`, certificate download/upload.
+`verify.mjs` fails if a tool targets one of them.
+
+## Ecosystem & related repos
+
+- **Calls:** [`proxy-api`](https://github.com/aidenappl/proxy-api) only.
+- **Configured in:** `agent-config/mcp/servers.json` (`proxy` entry, `${FORTA_API_TOKEN}`).
+- Siblings: `lattice-mcp` (the template for `verify.mjs`), `forta-mcp`, `monitor-mcp`,
+  `keyring-mcp`, `openbucket-mcp`.
+
+## Operations
+
+- **Publishing is deployment:** bump `package.json` and `VERSION` in `index.js`, add a release
+  entry below, `npm test`, then `npm publish` from an interactive terminal (2FA passkey). Running
+  clients keep the old version until restarted.
+- Failures surface as proxy-api's envelope: `error_message` "grant required" (token owner lacks a
+  platform 11 grant), "not available through proxy-api" (allowlist), "nginx proxy manager
+  unreachable" (502 from proxy-api).
+
+## Rules & guardrails
+
+- Never add a tool for a path proxy-api refuses, and never widen proxy-api's allowlist to make one
+  work without updating proxy-api's tests and AGENTS.md in the same change.
+- Never remove a key from `SECRET_FIELDS` or turn masking off by default.
+- A new proxy-api route should add or consciously skip a tool here in the same change.
+
+## Verification
+
+```bash
+node --check index.js
+npm test
+```
+
+## Releases
+
+- **1.0.0** — first release: 43 tools for NPM 2.16 (proxy, redirection and 404 hosts, streams,
+  certificates, access lists, default site, log viewer, audit log).
+
+## Keeping this file updated
+
+Any change to tools, auth, structure or the proxy-api contract updates this file (and README.md's
+tool tables and count) in the same change. `npm test` enforces the counts and the release entry.

package/README.md

@@ -1,3 +1,126 @@
-# Temporary Holding Version
+# proxy-mcp
 
-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.
+MCP server for the appleby.cloud Nginx Proxy Manager — **43 typed tools** over proxy-api.
+
+> **appleby.cloud platform** · MCP server · npm `appleby-proxy-mcp`
+
+---
+
+## Overview
+
+Gives agents (pi, Claude Code) the Nginx Proxy Manager on `aplb-proxy`: proxy, redirection and
+404 hosts, streams, certificates, access lists, the default site, NPM's log viewer and its audit
+log. Every call goes through [`proxy-api`](https://github.com/aidenappl/proxy-api)'s `/npm/v1`
+facade, which authenticates with Forta, enforces an allowlist, redacts credentials and records
+every write in Monitor. NPM's own credentials never reach this server.
+
+The npm name is `appleby-proxy-mcp` — `proxy-mcp` on npm is an unrelated package.
+
+## Role in the appleby.cloud ecosystem
+
+One of the platform `*-mcp` servers (lattice, monitor, forta, keyring, openbucket, proxy). It
+holds no logic: request shapes come from NPM 2.16's `/api/schema`, permissions from proxy-api.
+
+## Tech stack
+
+Node ≥ 18 (ESM) · `@modelcontextprotocol/sdk` · `zod`
+
+## Getting started
+
+### Prerequisites
+
+- A Forta API token (`frt_…`) whose owner holds a grant on the **APLB Proxy Manager** platform
+  (Forta id 11).
+- LAN access to `proxy-api.appleby.cloud` (LAN-only DNS).
+
+### Setup
+
+```bash
+npx appleby-proxy-mcp --setup     # writes the "proxy" block into ~/.mcp.json
+```
+
+Or by hand: `command: npx`, `args: ["-y", "appleby-proxy-mcp"]`, env `PROXY_API_URL`
+(`https://proxy-api.appleby.cloud`) and `PROXY_API_TOKEN`. In agent-config it is the `proxy`
+entry in `mcp/servers.json`, reusing `${FORTA_API_TOKEN}`.
+
+## Development
+
+| Command | What it does |
+|---------|--------------|
+| `npm install` | Install the two dependencies |
+| `npm test` | `verify.mjs`: syntax, tool names/counts, versions, masking, proxy-api's boundary |
+| `node index.js --setup` | Interactive setup |
+| `PROXY_API_URL=… PROXY_API_TOKEN=… node index.js` | Run on stdio |
+
+## Tools
+
+### Health & reports
+
+| Tool | What it does |
+|------|--------------|
+| `proxy_health` | proxy-api's own healthcheck |
+| `proxy_check_version` | NPM's version and whether a newer release exists |
+| `proxy_get_host_report` | Host counts by type |
+
+### Proxy hosts
+
+| Tool | What it does |
+|------|--------------|
+| `proxy_list_proxy_hosts` | List (optionally expand access_list / owner / certificate) |
+| `proxy_get_proxy_host` | One host with advanced config and locations |
+| `proxy_create_proxy_host` | Create (Forta gate recipe in the description) |
+| `proxy_update_proxy_host` | Partial update; advanced_config and locations replace wholesale |
+| `proxy_enable_proxy_host` / `proxy_disable_proxy_host` | Toggle |
+| `proxy_delete_proxy_host` | Delete |
+
+### Redirection & 404 hosts, streams
+
+| Tool | What it does |
+|------|--------------|
+| `proxy_list_redirection_hosts`, `proxy_get_redirection_host` | Read |
+| `proxy_create_redirection_host`, `proxy_update_redirection_host`, `proxy_delete_redirection_host` | Write |
+| `proxy_enable_redirection_host`, `proxy_disable_redirection_host` | Toggle |
+| `proxy_list_dead_hosts`, `proxy_create_dead_host`, `proxy_update_dead_host`, `proxy_delete_dead_host` | 404 hosts |
+| `proxy_list_streams`, `proxy_create_stream`, `proxy_update_stream`, `proxy_delete_stream` | TCP/UDP streams |
+
+### Certificates
+
+| Tool | What it does |
+|------|--------------|
+| `proxy_list_certificates`, `proxy_get_certificate` | Read (keys and DNS credentials redacted) |
+| `proxy_list_dns_providers` | Certbot DNS plugins |
+| `proxy_create_certificate` | Let's Encrypt request (prefer the existing `*.appleby.cloud` wildcard) |
+| `proxy_renew_certificate` | Renew now |
+| `proxy_test_http_challenge` | HTTP-01 reachability check |
+| `proxy_delete_certificate` | Delete |
+
+Downloading and uploading certificates are deliberately unavailable.
+
+### Access lists & settings
+
+| Tool | What it does |
+|------|--------------|
+| `proxy_list_access_lists`, `proxy_get_access_list` | Read (passwords redacted) |
+| `proxy_create_access_list`, `proxy_update_access_list`, `proxy_delete_access_list` | Write |
+| `proxy_list_settings` | Settings |
+| `proxy_update_default_site` | What unknown hostnames get |
+
+### Logs & audit
+
+| Tool | What it does |
+|------|--------------|
+| `proxy_list_log_sources` | What the log viewer can read |
+| `proxy_tail_log` | Tail system, Let's Encrypt or a host's access/error log |
+| `proxy_list_audit_log`, `proxy_get_audit_log_entry` | NPM's audit trail |
+
+For request history and analytics use Monitor (service `proxy`, zone `appleby`).
+
+## Deployment
+
+Publishing is deployment: `npm publish` (2FA passkey, interactive terminal). Clients pick up a
+new version only after they restart.
+
+## Contributing & further reading
+
+- [`AGENTS.md`](AGENTS.md)
+- [`proxy-api`](https://github.com/aidenappl/proxy-api) — the facade, allowlist and redaction

package/index.js

@@ -0,0 +1,537 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { createInterface } from "readline";
+import { readFileSync, writeFileSync, existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+
+const VERSION = "1.0.0";
+
+// --- Interactive setup ---
+
+if (process.argv.includes("--setup")) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const ask = (q) => new Promise((resolve) => rl.question(q, resolve));
+
+    console.log("\n  Proxy MCP Setup\n");
+
+    const apiUrl = (await ask("  proxy-api URL (https://proxy-api.appleby.cloud): ")).trim() || "https://proxy-api.appleby.cloud";
+    const apiToken = (await ask("  Forta API Token (frt_…): ")).trim();
+    rl.close();
+
+    if (!apiToken.startsWith("frt_")) {
+        console.error("\n  Error: proxy-api accepts a Forta API token (frt_…) whose owner holds a grant on");
+        console.error("  the APLB Proxy Manager platform. Create one in the Forta dashboard.\n");
+        process.exit(1);
+    }
+
+    const mcpPath = join(homedir(), ".mcp.json");
+    let config = { mcpServers: {} };
+    if (existsSync(mcpPath)) {
+        try { config = JSON.parse(readFileSync(mcpPath, "utf-8")); } catch {}
+        if (!config.mcpServers) config.mcpServers = {};
+    }
+
+    config.mcpServers.proxy = {
+        command: "npx",
+        args: ["-y", "appleby-proxy-mcp"],
+        env: {
+            PROXY_API_URL: apiUrl,
+            PROXY_API_TOKEN: apiToken,
+        },
+    };
+
+    writeFileSync(mcpPath, JSON.stringify(config, null, 2) + "\n");
+    console.log(`\n  Written to ${mcpPath}`);
+    console.log("  Restart Claude Code to load the Proxy MCP server.\n");
+    process.exit(0);
+}
+
+// --- MCP Server ---
+
+const API_URL = process.env.PROXY_API_URL;
+const API_TOKEN = process.env.PROXY_API_TOKEN;
+
+if (!API_URL || !API_TOKEN) {
+    console.error("PROXY_API_URL and PROXY_API_TOKEN are required.");
+    console.error("Run `npx appleby-proxy-mcp --setup` to configure.");
+    process.exit(1);
+}
+
+// --- Sensitive value masking ---
+//
+// proxy-api already redacts credentials from every NPM response (DNS-provider
+// API tokens, private keys, access-list passwords) and refuses certificate
+// downloads outright. This is the second layer: anything that reaches a
+// model's context is in a transcript forever, so a key proxy-api's list does
+// not know about yet is still masked here.
+//
+// Sensitive values are masked to their first two characters plus a
+// fixed-width tail. proxy-api's own "[redacted]" passes through untouched.
+// Set PROXY_ALLOW_SECRET_VALUES=1 to pass values through unmasked.
+
+const ALLOW_SECRETS = process.env.PROXY_ALLOW_SECRET_VALUES === "1";
+
+function mask(value) {
+    if (typeof value !== "string" || value === "" || value === "[redacted]") return value;
+    if (value.length < 3) return "**********";
+    return value.slice(0, 2) + "**********";
+}
+
+const SECRET_FIELDS = new Set([
+    "dns_provider_credentials", "certificate_key", "password", "secret", "token",
+    "access_token", "refresh_token", "private_key", "api_key",
+]);
+
+function sanitise(node) {
+    if (ALLOW_SECRETS || node === null || typeof node !== "object") return node;
+    if (Array.isArray(node)) return node.map(sanitise);
+    const out = {};
+    for (const [k, v] of Object.entries(node)) {
+        out[k] = SECRET_FIELDS.has(k) && typeof v === "string" ? mask(v) : sanitise(v);
+    }
+    return out;
+}
+
+// --- HTTP helper ---
+//
+// Every NPM call goes through proxy-api's facade: /npm/v1/<path> → NPM's
+// /api/<path>, as the NPM agent account. proxy-api answers in the standard
+// appleby.cloud envelope ({success, data} / {success:false, error_message}).
+
+async function api(method, path, params, body) {
+    const url = new URL(path, API_URL);
+    if (params) {
+        for (const [k, v] of Object.entries(params)) {
+            if (v !== undefined && v !== null && v !== "") url.searchParams.set(k, String(v));
+        }
+    }
+    const opts = {
+        method,
+        headers: { Authorization: `Bearer ${API_TOKEN}` },
+        signal: AbortSignal.timeout(60000),
+    };
+    if (body !== undefined) {
+        opts.headers["Content-Type"] = "application/json";
+        opts.body = JSON.stringify(body);
+    }
+    try {
+        const res = await fetch(url.toString(), opts);
+        const text = await res.text();
+        if (!text) return { success: res.ok, status: res.status };
+        try {
+            return sanitise(JSON.parse(text));
+        } catch {
+            return { success: res.ok, status: res.status, body: text.slice(0, 2000) };
+        }
+    } catch (err) {
+        return { success: false, error: err.message, error_message: `API request failed: ${err.message}` };
+    }
+}
+
+const npm = (method, path, params, body) => api(method, `/npm/v1/${path}`, params, body);
+
+function text(data) {
+    return [{ type: "text", text: JSON.stringify(data, null, 2) }];
+}
+
+// Strips undefined keys so a PUT only sends the fields the caller supplied.
+// NPM validates bodies with additionalProperties: false, so a stray key is a 400.
+function body(obj) {
+    return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined));
+}
+
+// --- Shared schemas (from NPM 2.16's /api/schema) ---
+
+const id = z.number().int().positive();
+const domainNames = z.array(z.string()).min(1).describe("Hostnames this host answers for, e.g. ['app.appleby.cloud']");
+const certificateId = z.union([z.number().int().min(0), z.literal("new")]).optional()
+    .describe("Certificate ID from proxy_list_certificates (0 = none). 'new' requests a new Let's Encrypt cert, which needs meta.letsencrypt_* fields");
+const advancedConfig = z.string().optional().describe("nginx directives placed in the server block (the Advanced tab). Replaces the existing value entirely");
+const meta = z.record(z.string(), z.any()).optional().describe("NPM meta object (rarely needed)");
+const sslFlags = {
+    ssl_forced: z.boolean().optional().describe("Redirect HTTP to HTTPS"),
+    hsts_enabled: z.boolean().optional(),
+    hsts_subdomains: z.boolean().optional(),
+    http2_support: z.boolean().optional(),
+};
+const location = z.object({
+    path: z.string().min(1).describe("Location path, e.g. /api"),
+    forward_scheme: z.enum(["http", "https"]),
+    forward_host: z.string().min(1),
+    forward_port: z.number().int().min(1).max(65535),
+    forward_path: z.string().optional(),
+    advanced_config: z.string().optional(),
+    access_list_id: z.number().int().min(0).optional(),
+});
+const proxyHostFields = {
+    forward_scheme: z.enum(["http", "https"]),
+    forward_host: z.string().describe("Upstream host or IP, e.g. 10.15.10.76"),
+    forward_port: z.number().int().min(1).max(65535),
+    certificate_id: certificateId,
+    ...sslFlags,
+    trust_forwarded_proto: z.boolean().optional().describe("Trust X-Forwarded-Proto from upstream proxies"),
+    block_exploits: z.boolean().optional(),
+    caching_enabled: z.boolean().optional(),
+    allow_websocket_upgrade: z.boolean().optional(),
+    access_list_id: z.number().int().min(0).optional().describe("Access list ID (0 = public)"),
+    advanced_config: advancedConfig,
+    enabled: z.boolean().optional(),
+    meta,
+    locations: z.array(location).optional().describe("Custom locations. Replaces the existing list entirely"),
+};
+const expand = (values) => z.array(z.enum(values)).optional().describe(`Related objects to embed: ${values.join(", ")}`);
+const expandParam = (e) => (e && e.length ? { expand: e.join(",") } : null);
+
+const server = new McpServer({
+    name: "proxy",
+    version: VERSION,
+});
+
+// ─── Health ──────────────────────────────────────────────────────────────────
+
+server.tool("proxy_health", "Check proxy-api is up (its own /healthcheck — not NPM's)", {}, async () => {
+    const res = await api("GET", "/healthcheck");
+    return { content: text(res) };
+});
+
+server.tool("proxy_check_version", "NPM's running version and whether a newer release exists (NPM asks GitHub). Use before and after an upgrade of the jc21/nginx-proxy-manager image on aplb-proxy", {}, async () => {
+    const res = await npm("GET", "version/check");
+    return { content: text(res) };
+});
+
+server.tool("proxy_get_host_report", "Count of proxy, redirection, stream and 404 hosts NPM manages", {}, async () => {
+    const res = await npm("GET", "reports/hosts");
+    return { content: text(res) };
+});
+
+// ─── Proxy hosts ─────────────────────────────────────────────────────────────
+
+server.tool("proxy_list_proxy_hosts", "List NPM proxy hosts: domain_names, forward_scheme/host/port, certificate_id, ssl_forced, block_exploits, websockets, access_list_id, advanced_config, enabled, locations. Start here to find a host's id", {
+    expand: expand(["access_list", "owner", "certificate"]),
+}, async ({ expand: e }) => {
+    const res = await npm("GET", "nginx/proxy-hosts", expandParam(e));
+    return { content: text(res) };
+});
+
+server.tool("proxy_get_proxy_host", "Get one proxy host, including its advanced_config and custom locations", {
+    id,
+    expand: expand(["access_list", "owner", "certificate"]),
+}, async ({ id: hostId, expand: e }) => {
+    const res = await npm("GET", `nginx/proxy-hosts/${hostId}`, expandParam(e));
+    return { content: text(res) };
+});
+
+server.tool("proxy_create_proxy_host", "Create a proxy host. NPM writes and reloads nginx immediately; a config nginx rejects is saved as <id>.conf.err and the host goes offline (meta.nginx_online=false) — check the response's meta. For a Forta-gated host on *.appleby.cloud, put `set $forta_client_id \"<client_id>\"; include /data/nginx/custom/forta-gate.conf;` in advanced_config and use a DNS-01 certificate", {
+    domain_names: domainNames,
+    ...proxyHostFields,
+}, async (args) => {
+    const res = await npm("POST", "nginx/proxy-hosts", null, body(args));
+    return { content: text(res) };
+});
+
+server.tool("proxy_update_proxy_host", "Update a proxy host. Only the fields you pass change — but advanced_config and locations each replace the whole value, so read the host first with proxy_get_proxy_host and send the full edited text. NPM regenerates and reloads the host's nginx config", {
+    id,
+    domain_names: domainNames.optional(),
+    ...Object.fromEntries(Object.entries(proxyHostFields).map(([k, v]) => [k, v.optional()])),
+}, async ({ id: hostId, ...fields }) => {
+    const res = await npm("PUT", `nginx/proxy-hosts/${hostId}`, null, body(fields));
+    return { content: text(res) };
+});
+
+server.tool("proxy_enable_proxy_host", "Enable a disabled proxy host (regenerates its nginx config)", { id }, async ({ id: hostId }) => {
+    const res = await npm("POST", `nginx/proxy-hosts/${hostId}/enable`, null, {});
+    return { content: text(res) };
+});
+
+server.tool("proxy_disable_proxy_host", "Disable a proxy host: its domains stop being served by this host immediately (requests fall to the default site). Reversible with proxy_enable_proxy_host", { id }, async ({ id: hostId }) => {
+    const res = await npm("POST", `nginx/proxy-hosts/${hostId}/disable`, null, {});
+    return { content: text(res) };
+});
+
+server.tool("proxy_delete_proxy_host", "Delete a proxy host and its nginx config. Destructive: every domain on it stops being proxied. Confirm the id with proxy_get_proxy_host first; prefer proxy_disable_proxy_host when unsure", { id }, async ({ id: hostId }) => {
+    const res = await npm("DELETE", `nginx/proxy-hosts/${hostId}`);
+    return { content: text(res) };
+});
+
+// ─── Redirection hosts ───────────────────────────────────────────────────────
+
+const redirectionFields = {
+    forward_http_code: z.number().int().describe("HTTP status for the redirect, e.g. 301, 302, 307, 308"),
+    forward_scheme: z.enum(["auto", "http", "https"]),
+    forward_domain_name: z.string().describe("Target domain, e.g. forta.appleby.cloud"),
+    preserve_path: z.boolean().optional().describe("Append the request path to the target"),
+    certificate_id: certificateId,
+    ...sslFlags,
+    block_exploits: z.boolean().optional(),
+    advanced_config: advancedConfig,
+    meta,
+};
+
+server.tool("proxy_list_redirection_hosts", "List NPM redirection hosts (domain → domain redirects)", {
+    expand: expand(["owner", "certificate"]),
+}, async ({ expand: e }) => {
+    const res = await npm("GET", "nginx/redirection-hosts", expandParam(e));
+    return { content: text(res) };
+});
+
+server.tool("proxy_get_redirection_host", "Get one redirection host", { id }, async ({ id: hostId }) => {
+    const res = await npm("GET", `nginx/redirection-hosts/${hostId}`);
+    return { content: text(res) };
+});
+
+server.tool("proxy_create_redirection_host", "Create a redirection host", {
+    domain_names: domainNames,
+    ...redirectionFields,
+}, async (args) => {
+    const res = await npm("POST", "nginx/redirection-hosts", null, body(args));
+    return { content: text(res) };
+});
+
+server.tool("proxy_update_redirection_host", "Update a redirection host. Only the fields you pass change", {
+    id,
+    domain_names: domainNames.optional(),
+    ...Object.fromEntries(Object.entries(redirectionFields).map(([k, v]) => [k, v.optional()])),
+}, async ({ id: hostId, ...fields }) => {
+    const res = await npm("PUT", `nginx/redirection-hosts/${hostId}`, null, body(fields));
+    return { content: text(res) };
+});
+
+server.tool("proxy_enable_redirection_host", "Enable a redirection host", { id }, async ({ id: hostId }) => {
+    const res = await npm("POST", `nginx/redirection-hosts/${hostId}/enable`, null, {});
+    return { content: text(res) };
+});
+
+server.tool("proxy_disable_redirection_host", "Disable a redirection host", { id }, async ({ id: hostId }) => {
+    const res = await npm("POST", `nginx/redirection-hosts/${hostId}/disable`, null, {});
+    return { content: text(res) };
+});
+
+server.tool("proxy_delete_redirection_host", "Delete a redirection host. Destructive", { id }, async ({ id: hostId }) => {
+    const res = await npm("DELETE", `nginx/redirection-hosts/${hostId}`);
+    return { content: text(res) };
+});
+
+// ─── 404 hosts ───────────────────────────────────────────────────────────────
+
+const deadHostFields = {
+    certificate_id: certificateId,
+    ...sslFlags,
+    advanced_config: advancedConfig,
+    meta,
+};
+
+server.tool("proxy_list_dead_hosts", "List NPM 404 hosts (domains NPM answers with 404)", {
+    expand: expand(["owner", "certificate"]),
+}, async ({ expand: e }) => {
+    const res = await npm("GET", "nginx/dead-hosts", expandParam(e));
+    return { content: text(res) };
+});
+
+server.tool("proxy_create_dead_host", "Create a 404 host", {
+    domain_names: domainNames,
+    ...deadHostFields,
+}, async (args) => {
+    const res = await npm("POST", "nginx/dead-hosts", null, body(args));
+    return { content: text(res) };
+});
+
+server.tool("proxy_update_dead_host", "Update a 404 host. Only the fields you pass change", {
+    id,
+    domain_names: domainNames.optional(),
+    ...deadHostFields,
+}, async ({ id: hostId, ...fields }) => {
+    const res = await npm("PUT", `nginx/dead-hosts/${hostId}`, null, body(fields));
+    return { content: text(res) };
+});
+
+server.tool("proxy_delete_dead_host", "Delete a 404 host. Destructive", { id }, async ({ id: hostId }) => {
+    const res = await npm("DELETE", `nginx/dead-hosts/${hostId}`);
+    return { content: text(res) };
+});
+
+// ─── Streams ─────────────────────────────────────────────────────────────────
+
+const streamFields = {
+    incoming_port: z.number().int().min(1).max(65535).describe("Port NPM listens on (must also be published by the NPM container)"),
+    forwarding_host: z.string().describe("Upstream domain, IPv4 or IPv6"),
+    forwarding_port: z.number().int().min(1).max(65535),
+    tcp_forwarding: z.boolean().optional(),
+    udp_forwarding: z.boolean().optional(),
+    certificate_id: certificateId,
+    meta,
+};
+
+server.tool("proxy_list_streams", "List NPM TCP/UDP streams", {
+    expand: expand(["owner", "certificate"]),
+}, async ({ expand: e }) => {
+    const res = await npm("GET", "nginx/streams", expandParam(e));
+    return { content: text(res) };
+});
+
+server.tool("proxy_create_stream", "Create a TCP/UDP stream. The incoming port must also be published on aplb-proxy's NPM container to be reachable", {
+    ...streamFields,
+}, async (args) => {
+    const res = await npm("POST", "nginx/streams", null, body(args));
+    return { content: text(res) };
+});
+
+server.tool("proxy_update_stream", "Update a stream. Only the fields you pass change", {
+    id,
+    ...Object.fromEntries(Object.entries(streamFields).map(([k, v]) => [k, v.optional()])),
+}, async ({ id: streamId, ...fields }) => {
+    const res = await npm("PUT", `nginx/streams/${streamId}`, null, body(fields));
+    return { content: text(res) };
+});
+
+server.tool("proxy_delete_stream", "Delete a stream. Destructive", { id }, async ({ id: streamId }) => {
+    const res = await npm("DELETE", `nginx/streams/${streamId}`);
+    return { content: text(res) };
+});
+
+// ─── Certificates ────────────────────────────────────────────────────────────
+
+server.tool("proxy_list_certificates", "List NPM certificates: id, nice_name, domain_names, provider, expires_on. Private keys and DNS-provider credentials are always redacted, and downloading a certificate is not available through proxy-api", {
+    expand: expand(["owner"]),
+}, async ({ expand: e }) => {
+    const res = await npm("GET", "nginx/certificates", expandParam(e));
+    return { content: text(res) };
+});
+
+server.tool("proxy_get_certificate", "Get one certificate (credentials redacted)", { id }, async ({ id: certId }) => {
+    const res = await npm("GET", `nginx/certificates/${certId}`);
+    return { content: text(res) };
+});
+
+server.tool("proxy_list_dns_providers", "List the certbot DNS plugins NPM supports, for a DNS-01 certificate request", {}, async () => {
+    const res = await npm("GET", "nginx/certificates/dns-providers");
+    return { content: text(res) };
+});
+
+server.tool("proxy_create_certificate", "Request a Let's Encrypt certificate. Every *.appleby.cloud name is already covered by the wildcard (find it with proxy_list_certificates) — reuse that instead of issuing more. DNS-01 needs meta.dns_challenge=true, meta.dns_provider and meta.dns_provider_credentials (a credential: prefer the existing wildcard)", {
+    provider: z.literal("letsencrypt").describe("Only letsencrypt: uploading custom certificates is not available through proxy-api"),
+    nice_name: z.string().optional(),
+    domain_names: domainNames,
+    meta: z.object({
+        dns_challenge: z.boolean().optional(),
+        dns_provider: z.string().optional().describe("From proxy_list_dns_providers, e.g. cloudflare"),
+        dns_provider_credentials: z.string().optional(),
+        propagation_seconds: z.number().int().min(0).optional(),
+        key_type: z.enum(["rsa", "ecdsa"]).optional(),
+    }).optional(),
+}, async (args) => {
+    const res = await npm("POST", "nginx/certificates", null, body(args));
+    return { content: text(res) };
+});
+
+server.tool("proxy_renew_certificate", "Renew a Let's Encrypt certificate now (NPM also renews automatically at 30 days). Can take a minute — DNS-01 waits for propagation", { id }, async ({ id: certId }) => {
+    const res = await npm("POST", `nginx/certificates/${certId}/renew`, null, {});
+    return { content: text(res) };
+});
+
+server.tool("proxy_test_http_challenge", "Check whether domains can pass Let's Encrypt's HTTP-01 challenge through this NPM (reachability of /.well-known/acme-challenge from the internet)", {
+    domains: z.array(z.string()).min(1),
+}, async ({ domains }) => {
+    const res = await npm("POST", "nginx/certificates/test-http", null, { domains });
+    return { content: text(res) };
+});
+
+server.tool("proxy_delete_certificate", "Delete a certificate. Destructive: hosts using it lose TLS. Check proxy_list_proxy_hosts for certificate_id users first", { id }, async ({ id: certId }) => {
+    const res = await npm("DELETE", `nginx/certificates/${certId}`);
+    return { content: text(res) };
+});
+
+// ─── Access lists ────────────────────────────────────────────────────────────
+
+const accessListFields = {
+    name: z.string(),
+    satisfy_any: z.boolean().optional().describe("Pass if EITHER the IP rules or basic auth match (default: both)"),
+    pass_auth: z.boolean().optional().describe("Forward the Authorization header to the upstream"),
+    items: z.array(z.object({ username: z.string().min(1), password: z.string().optional() })).optional()
+        .describe("Basic-auth users. Replaces the list; an empty password keeps the stored one"),
+    clients: z.array(z.object({ address: z.string().describe("IPv4/IPv6 address or CIDR, or 'all'"), directive: z.enum(["allow", "deny"]) })).optional()
+        .describe("IP rules, in order. Replaces the list"),
+};
+
+server.tool("proxy_list_access_lists", "List NPM access lists (IP allow/deny + basic auth). Passwords are redacted. For appleby.cloud SSO, prefer the Forta gate (see proxy_create_proxy_host) over basic auth", {
+    expand: expand(["owner", "items", "clients", "proxy_hosts"]),
+}, async ({ expand: e }) => {
+    const res = await npm("GET", "nginx/access-lists", expandParam(e));
+    return { content: text(res) };
+});
+
+server.tool("proxy_get_access_list", "Get one access list", {
+    id,
+    expand: expand(["owner", "items", "clients", "proxy_hosts"]),
+}, async ({ id: listId, expand: e }) => {
+    const res = await npm("GET", `nginx/access-lists/${listId}`, expandParam(e));
+    return { content: text(res) };
+});
+
+server.tool("proxy_create_access_list", "Create an access list", accessListFields, async (args) => {
+    const res = await npm("POST", "nginx/access-lists", null, body(args));
+    return { content: text(res) };
+});
+
+server.tool("proxy_update_access_list", "Update an access list. Only the fields you pass change; items and clients replace their whole lists", {
+    id,
+    ...Object.fromEntries(Object.entries(accessListFields).map(([k, v]) => [k, v.optional()])),
+}, async ({ id: listId, ...fields }) => {
+    const res = await npm("PUT", `nginx/access-lists/${listId}`, null, body(fields));
+    return { content: text(res) };
+});
+
+server.tool("proxy_delete_access_list", "Delete an access list. Hosts using it become public. Check proxy_get_access_list with expand proxy_hosts first", { id }, async ({ id: listId }) => {
+    const res = await npm("DELETE", `nginx/access-lists/${listId}`);
+    return { content: text(res) };
+});
+
+// ─── Settings ────────────────────────────────────────────────────────────────
+
+server.tool("proxy_list_settings", "List NPM settings (currently only default-site: what NPM serves for unknown hostnames)", {}, async () => {
+    const res = await npm("GET", "settings");
+    return { content: text(res) };
+});
+
+server.tool("proxy_update_default_site", "Set what NPM serves for a hostname no host claims: congratulations page, 404, 444 (close the connection), a redirect (meta.redirect = URL) or custom HTML (meta.html)", {
+    value: z.enum(["congratulations", "404", "444", "redirect", "html"]),
+    meta: z.object({ redirect: z.string().optional(), html: z.string().optional() }).optional(),
+}, async (args) => {
+    const res = await npm("PUT", "settings/default-site", null, body(args));
+    return { content: text(res) };
+});
+
+// ─── Logs & audit ────────────────────────────────────────────────────────────
+
+server.tool("proxy_list_log_sources", "List the log files NPM's log viewer can read: system, letsencrypt, and each host's access/error logs", {}, async () => {
+    const res = await npm("GET", "logs/sources");
+    return { content: text(res) };
+});
+
+server.tool("proxy_tail_log", "Tail an NPM log. type=host needs host_type + host_id + channel (access|error); type=letsencrypt shows certbot runs (cert renewal failures); type=system is the NPM backend. For history and analytics use Monitor (service \"proxy\", zone appleby) instead — every request and nginx error is there", {
+    type: z.enum(["system", "letsencrypt", "host"]),
+    host_type: z.enum(["proxy", "redirection", "dead", "stream"]).optional(),
+    host_id: z.number().int().positive().optional(),
+    channel: z.enum(["access", "error"]).optional(),
+    lines: z.number().int().min(1).max(5000).optional().describe("Lines from the end (default NPM's)"),
+    level: z.enum(["INFO", "WARN", "ERROR", "DEBUG", "SUCCESS", "FATAL", "COMPLETE"]).optional().describe("system logs only"),
+    search: z.string().optional().describe("Substring filter"),
+}, async (args) => {
+    const res = await npm("GET", "logs/tail", args);
+    return { content: text(res) };
+});
+
+server.tool("proxy_list_audit_log", "NPM's audit log: who created, changed, enabled or deleted which host, certificate or access list. proxy-api's own writes appear as the NPM agent account; Monitor's npm.write events say which Forta user made them", {}, async () => {
+    const res = await npm("GET", "audit-log");
+    return { content: text(res) };
+});
+
+server.tool("proxy_get_audit_log_entry", "Get one audit log entry, with its full before/after meta", { id }, async ({ id: entryId }) => {
+    const res = await npm("GET", `audit-log/${entryId}`);
+    return { content: text(res) };
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "appleby-proxy-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "MCP server for the appleby.cloud Nginx Proxy Manager, through proxy-api (repo: proxy-mcp)",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "appleby-proxy-mcp": "index.js"
+  },
+  "scripts": {
+    "start": "node index.js",
+    "test": "node verify.mjs"
+  },
+  "keywords": [
+    "mcp",
+    "nginx",
+    "nginx-proxy-manager",
+    "reverse-proxy",
+    "model-context-protocol"
+  ],
+  "author": "Aiden Appleby",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aidenappl/proxy-mcp.git"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  }
+}

package/verify.mjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+/**
+ * Static verification for proxy-mcp (published as appleby-proxy-mcp).
+ *
+ * index.js cannot be imported to check it: it ends in a top-level await that
+ * connects the stdio transport. Everything here parses the source instead.
+ * Shape: lattice-mcp's verify.mjs.
+ *
+ *  - Duplicate tool names: server.tool() silently keeps the last registration.
+ *  - Tool counts in README.md / AGENTS.md drifting from the code.
+ *  - Tools not prefixed proxy_.
+ *  - Version drift between package.json, index.js and AGENTS.md.
+ *  - sanitise() unwired from api(), or no longer masking.
+ *  - A tool aimed at an NPM path proxy-api refuses (npm.Allowed in proxy-api):
+ *    it would only ever return 403, and its presence would suggest the
+ *    boundary had moved.
+ */
+
+import { readFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import vm from "node:vm";
+
+const failures = [];
+const fail = (msg) => failures.push(msg);
+
+const source = readFileSync("index.js", "utf8");
+
+// ── Syntax ───────────────────────────────────────────────────────────────────
+try {
+    execFileSync(process.execPath, ["--check", "index.js"], { stdio: "pipe" });
+} catch (err) {
+    fail(`index.js failed to parse:\n${err.stderr?.toString() ?? err.message}`);
+}
+
+// ── Tool registrations ───────────────────────────────────────────────────────
+const names = [...source.matchAll(/server\.tool\(\s*"([^"]+)"/g)].map((m) => m[1]);
+if (names.length === 0) fail("no server.tool() registrations found — did the call shape change?");
+
+const seen = new Set();
+const duplicates = new Set();
+for (const name of names) {
+    if (seen.has(name)) duplicates.add(name);
+    seen.add(name);
+}
+if (duplicates.size > 0) fail(`duplicate tool names: ${[...duplicates].join(", ")}`);
+
+const misnamed = names.filter((n) => !n.startsWith("proxy_"));
+if (misnamed.length > 0) fail(`tools not prefixed with proxy_: ${misnamed.join(", ")}`);
+
+// ── proxy-api's boundary ─────────────────────────────────────────────────────
+const targets = [...source.matchAll(/npm\("(?:GET|POST|PUT|DELETE)",\s*[`"]([^`"]+)[`"]/g)].map((m) => m[1]);
+const forbidden = targets.filter((p) => /^(tokens|users)(\/|$)|\/(download|upload)$/.test(p));
+if (forbidden.length > 0) fail(`tools target paths proxy-api refuses: ${forbidden.join(", ")}`);
+
+// ── Documented counts must match the code ────────────────────────────────────
+const toolCount = names.length;
+for (const file of ["README.md", "AGENTS.md"]) {
+    const doc = readFileSync(file, "utf8");
+    const match = doc.match(/\*\*(\d+) typed tools\*\*/);
+    if (!match) {
+        fail(`${file}: could not find a "**N typed tools**" figure to check against`);
+        continue;
+    }
+    if (Number(match[1]) !== toolCount) {
+        fail(`${file} documents ${match[1]} tools but index.js registers ${toolCount} — update the docs in the same change`);
+    }
+}
+const readme = readFileSync("README.md", "utf8");
+const undocumented = names.filter((n) => !readme.includes(`\`${n}\``));
+if (undocumented.length > 0) fail(`tools missing from the README tool tables: ${undocumented.join(", ")}`);
+
+// ── Version consistency ──────────────────────────────────────────────────────
+let pkg = {};
+try {
+    pkg = JSON.parse(readFileSync("package.json", "utf8"));
+} catch (err) {
+    fail(`package.json is not valid JSON: ${err.message}`);
+}
+const codeVersion = source.match(/const VERSION = "([^"]+)"/)?.[1];
+if (!codeVersion) fail("could not find `const VERSION = \"…\"` in index.js");
+else if (codeVersion !== pkg.version) fail(`version mismatch: package.json is ${pkg.version} but index.js declares ${codeVersion}`);
+if (!/new McpServer\(\{[^}]*version:\s*VERSION/s.test(source)) fail("McpServer is not declared with version: VERSION");
+const agents = readFileSync("AGENTS.md", "utf8");
+if (pkg.version && !agents.includes(`**${pkg.version}**`)) fail(`AGENTS.md has no "**${pkg.version}**" release entry`);
+
+// ── Secret masking ───────────────────────────────────────────────────────────
+if (!/return sanitise\(JSON\.parse\(text\)\)/.test(source)) {
+    fail("api() no longer passes its parsed response through sanitise() — every tool now leaks secrets");
+}
+if (!/const ALLOW_SECRETS = process\.env\.PROXY_ALLOW_SECRET_VALUES === "1"/.test(source)) {
+    fail("the masking opt-out is not the expected PROXY_ALLOW_SECRET_VALUES === \"1\" check — masking may no longer default to on");
+}
+
+const maskingStart = source.indexOf("// --- Sensitive value masking ---");
+const maskingEnd = source.indexOf("// --- HTTP helper ---");
+let maskingCases = 0;
+if (maskingStart === -1 || maskingEnd === -1) {
+    fail("could not find the masking section markers in index.js");
+} else {
+    const sandbox = { process: { env: {} } };
+    vm.createContext(sandbox);
+    vm.runInContext(`${source.slice(maskingStart, maskingEnd)}\nthis.sanitise = sanitise;`, sandbox);
+    const expect = (label, got, want) => {
+        maskingCases++;
+        if (got !== want) fail(`masking: ${label} — got ${JSON.stringify(got)}, want ${JSON.stringify(want)}`);
+    };
+    // Assembled at runtime so no literal looks like a real credential.
+    const fakeToken = "dns_cloudflare_api_token=" + "z".repeat(20);
+    const out = sandbox.sanitise({
+        data: [{
+            id: 46,
+            nice_name: "*.appleby.cloud",
+            meta: { dns_challenge: true, dns_provider: "cloudflare", dns_provider_credentials: fakeToken, certificate_key: "-----BEGIN" },
+            items: [{ username: "admin", password: "hunter2" }],
+            proxied: "[redacted]",
+        }],
+    }).data[0];
+    expect("DNS provider credentials", out.meta.dns_provider_credentials, "dn**********");
+    expect("private key", out.meta.certificate_key, "--**********");
+    expect("access list password", out.items[0].password, "hu**********");
+    expect("ordinary field stays readable", out.meta.dns_provider, "cloudflare");
+    expect("username stays readable", out.items[0].username, "admin");
+    expect("proxy-api's own [redacted] passes through", out.proxied, "[redacted]");
+    expect("non-object passes through", sandbox.sanitise(true), true);
+}
+
+// ── Report ───────────────────────────────────────────────────────────────────
+if (failures.length > 0) {
+    console.error("verification failed:\n");
+    for (const f of failures) console.error(`  ✗ ${f}`);
+    process.exit(1);
+}
+
+console.log("✓ index.js parses");
+console.log(`✓ version ${pkg.version} consistent across package.json, index.js and AGENTS.md`);
+console.log(`✓ ${toolCount} tools registered, no duplicates, all proxy_-prefixed`);
+console.log(`✓ no tool targets a path proxy-api refuses (${targets.length} NPM calls checked)`);
+console.log("✓ README.md and AGENTS.md agree on the tool count; every tool is in the README tables");
+console.log("✓ sanitise() is wired into api() and masking defaults to on");
+console.log(`✓ ${maskingCases} masking behaviour cases pass`);