brewpage-mcp 1.20.0 → 1.21.0

package/README.md

@@ -38,7 +38,7 @@ Claude Code: `claude mcp add --transport http brewpage --scope user https://brew
 For clients that only start local servers; the same tools as the server URL.
 
 ```bash
-npx -y brewpage-mcp@1.20.0
+npx -y brewpage-mcp@1.21.0
 ```
 
 Requires Node.js 20 or newer. This starts the stdio server for an MCP client.
@@ -63,7 +63,7 @@ Local fallback (stdio, needs Node.js; the same tools): add to `~/Library/Applica
   "mcpServers": {
     "brewpage": {
       "command": "npx",
-      "args": ["-y", "brewpage-mcp@1.20.0"]
+      "args": ["-y", "brewpage-mcp@1.21.0"]
     }
   }
 }
@@ -86,7 +86,7 @@ Custom servers follow your ChatGPT plan and workspace settings.
 The remote command above is the default. Local fallback: register a project-scoped stdio server:
 
 ```bash
-claude mcp add --transport stdio --scope project brewpage -- npx -y brewpage-mcp@1.20.0
+claude mcp add --transport stdio --scope project brewpage -- npx -y brewpage-mcp@1.21.0
 ```
 
 This writes `.mcp.json` in the project root. Use `--scope user` for user-scoped registration. See the [official Claude Code MCP guide](https://code.claude.com/docs/en/mcp).
@@ -110,7 +110,7 @@ Local fallback (stdio, needs Node.js; the same tools): open **Settings > MCP** a
   "mcpServers": {
     "brewpage": {
       "command": "npx",
-      "args": ["-y", "brewpage-mcp@1.20.0"]
+      "args": ["-y", "brewpage-mcp@1.21.0"]
     }
   }
 }
@@ -124,7 +124,7 @@ Open the Cline MCP settings panel and add:
 {
   "brewpage": {
     "command": "npx",
-    "args": ["-y", "brewpage-mcp@1.20.0"]
+    "args": ["-y", "brewpage-mcp@1.21.0"]
   }
 }
 ```
@@ -731,12 +731,14 @@ Every publish response includes an **owner token** -- the only credential that a
 - Memory: run with `--max-old-space-size=192` and a 512 MiB container limit.
 - Never reads `BREWPAGE_OWNER_TOKEN`; refuses to start when it is set. Pass `ownerToken` per call.
 - One JSON log line per request on stdout (method, tool, status, outcome, ms); no arguments, tokens or IPs. `SIGTERM` drains for up to 30 s.
+- `GET /metrics` (Prometheus text) only for peers in `BREWPAGE_METRICS_CIDRS`, else 404: `brewpage_mcp_requests_total{method,client}`, `brewpage_mcp_tool_calls_total{tool,client,outcome}` and the gauge `brewpage_mcp_clients_today{client}` (distinct caller addresses with a tool call since 00:00 UTC, kept only as hashes with a random salt drawn each day; resets on restart). `client` is `claude` (an address in `BREWPAGE_SHARED_EGRESS_CIDRS` or a `Claude...` User-Agent), `chatgpt` (an address in a published egress list or an `openai-mcp`/`ChatGPT` User-Agent), else `other`; `outcome` is `ok`, `tool_error`, `error` or `client_closed`. No IPs, arguments or content in any label.
 
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `BREWPAGE_TRUSTED_PROXY_CIDRS` | required | Comma list of reverse-proxy CIDRs or IPs |
 | `BREWPAGE_SHARED_EGRESS_CIDRS` | empty | Comma list of platform egress CIDRs (one IP, many users): global limits only, no per-IP caps |
 | `BREWPAGE_SHARED_EGRESS_LIST_URLS` | empty | Comma list of `https` URLs of published egress lists (`{"prefixes":[{"ipv4Prefix"}]}`, at least 100 prefixes, at most 1 MiB, no redirects); fetched at startup and daily, last good list kept |
+| `BREWPAGE_METRICS_CIDRS` | empty | Comma list of CIDRs or IPs allowed to read `GET /metrics`; empty = `/metrics` answers 404 |
 | `BREWPAGE_BACKEND_URL` | `http://brewpage-backend-mcp:8080` | API base URL (internal address) |
 | `BREWPAGE_PUBLIC_ORIGIN` | `https://brewpage.app` | Origin for returned links and forwarded proto/host |
 | `BREWPAGE_MCP_PORT` | `8787` | Listen port |
@@ -755,6 +757,10 @@ Every publish response includes an **owner token** -- the only credential that a
 
 ## Changelog
 
+## 1.21.0 -- 2026-11-12
+
+- Remote mode only: optional `GET /metrics` with usage counts for the operator (calls per tool, Claude, ChatGPT or other clients, distinct clients per day), served only to the addresses in `BREWPAGE_METRICS_CIDRS`. No addresses, arguments or content are kept or shown. Tools, inputs and stdio are unchanged: thirty-two tools, contract 2.27.0. `User-Agent: brewpage-mcp/1.21.0`.
+
 ## 1.20.0 -- 2026-11-12
 
 - Two new tools. `make_private` turns a public publication into a private one: new private link, the public link stops working, views and stats stay; one-way. `set_badge` hides or shows the BrewPage badge on a publication of your profile, up to 5 hidden. `set_visibility` reads as list or unlist; inputs unchanged. The server instructions and the tools that send page code say that page code must not hide or alter the badge. Thirty-two tools. Contract 2.27.0. `User-Agent: brewpage-mcp/1.20.0`.

package/dist/http.js

@@ -8,6 +8,7 @@ import { pathToFileURL } from "node:url";
 import { createMcpHandler, InMemoryTransport, isLegacyRequest, LATEST_PROTOCOL_VERSION } from "@modelcontextprotocol/server";
 import { NodeStreamableHTTPServerTransport, toWebRequest } from "@modelcontextprotocol/node";
 import { createServer, OWNER_TOKEN_ENV, USER_AGENT } from "./tools.js";
+import { classifyClient, UsageMetrics } from "./metrics.js";
 const MIB = 1024 * 1024;
 /** Fits the largest site (25 MiB backend request: 20 MiB of inline text plus JSON escaping).
  * Two 32 MiB sites + 8x1 MiB + 32 light per round peaked at 373 MiB (heap 192): run with mem_limit 512m. */
@@ -143,6 +144,8 @@ function loadConfig() {
         /** Platform egress (one IP, many users): global pools only, no per-client caps or download budget. */
         sharedEgress: parseCidrs("BREWPAGE_SHARED_EGRESS_CIDRS", false),
         sharedEgressLists: parseListUrls("BREWPAGE_SHARED_EGRESS_LIST_URLS"),
+        /** Peers allowed to read GET /metrics (the Prometheus network); empty = /metrics answers 404. */
+        metricsPeers: parseCidrs("BREWPAGE_METRICS_CIDRS", false),
         host: process.env.BREWPAGE_MCP_HOST || "0.0.0.0",
         port,
     };
@@ -457,7 +460,10 @@ async function main() {
     const heavy = new Pool(MAX_HEAVY_IN_FLIGHT, MAX_HEAVY_PER_CLIENT);
     let draining = false;
     const listed = new Map();
-    let sharedEgress = blockList(config.sharedEgress);
+    const staticEgress = blockList(config.sharedEgress);
+    let listedEgress = blockList([]);
+    const metricsPeers = config.metricsPeers.length > 0 ? blockList(config.metricsPeers) : undefined;
+    const metrics = new UsageMetrics([...toolNames]);
     /** Never throws: a failed fetch or parse keeps the last good set and logs a warning. */
     async function loadEgressList(url) {
         try {
@@ -469,7 +475,7 @@ async function main() {
             }
             const ranges = parseEgressList(await readCapped(res, SHARED_LIST_MAX_BYTES));
             listed.set(url, ranges);
-            sharedEgress = blockList([...config.sharedEgress, ...[...listed.values()].flat()]);
+            listedEgress = blockList([...listed.values()].flat());
             log({ event: "shared_egress_list", url, ranges: ranges.length });
         }
         catch (error) {
@@ -479,7 +485,7 @@ async function main() {
     const refreshEgressLists = () => config.sharedEgressLists.forEach((url) => void loadEgressList(url));
     refreshEgressLists();
     setInterval(refreshEgressLists, SHARED_LIST_REFRESH_MS).unref();
-    async function handleMcp(req, res, entry) {
+    async function handleMcp(req, res, entry, usage) {
         if (req.headers.origin !== undefined)
             return rpcError(res, 403, SERVER_ERROR, "Origin not allowed.");
         const peer = peerAddress(req);
@@ -502,7 +508,9 @@ async function main() {
             rpcError(res, 503, SERVER_ERROR, "Busy, retry shortly.", { "Retry-After": "1" });
         };
         const known = Number.isFinite(declared);
-        const shared = sharedEgress.check(client, isIP(client) === 6 ? "ipv6" : "ipv4");
+        const family = isIP(client) === 6 ? "ipv6" : "ipv4";
+        const egress = staticEgress.check(client, family) ? "static" : listedEgress.check(client, family) ? "listed" : undefined;
+        const shared = egress !== undefined;
         const capKey = shared ? undefined : client;
         // Registered first: a client that leaves at any point, even while queued, aborts the call.
         const abort = new AbortController();
@@ -562,6 +570,8 @@ async function main() {
             const toolName = rpc.method === "tools/call" ? rpc.params?.name : undefined;
             entry.method = typeof rpc.method === "string" ? rpc.method.slice(0, MAX_LOGGED_METHOD) : null;
             entry.tool = rpc.method === "tools/call" ? (typeof toolName === "string" && toolNames.has(toolName) ? toolName : "unknown") : null;
+            usage.client = classifyClient(egress, (req.headers["user-agent"] ?? "").slice(0, MAX_LOGGED_METHOD));
+            usage.address = client;
             // Stateless: no server-push streams, as the 2025 GET stream (405); a refused auto-open never fails a connect.
             if (rpc.method === "subscriptions/listen") {
                 const id = message.id;
@@ -634,18 +644,24 @@ async function main() {
             slot?.give(capKey);
         }
     }
-    function handle(req, res, entry) {
+    function handle(req, res, entry, usage) {
         const path = (req.url ?? "/").split("?")[0];
         if (path === "/healthz") {
             res.writeHead(draining ? 503 : 200, { "Content-Type": "application/json" });
             res.end(JSON.stringify({ status: draining ? "draining" : "ok", version: VERSION }));
             return Promise.resolve();
         }
+        const peer = peerAddress(req);
+        if (path === "/metrics" && req.method === "GET" && isIP(peer) !== 0 && metricsPeers?.check(peer, isIP(peer) === 6 ? "ipv6" : "ipv4")) {
+            res.writeHead(200, { "Content-Type": "text/plain; version=0.0.4; charset=utf-8" });
+            res.end(metrics.render());
+            return Promise.resolve();
+        }
         if (path !== "/mcp") {
             rpcError(res, 404, SERVER_ERROR, "Not found.");
             return Promise.resolve();
         }
-        return handleMcp(req, res, entry).catch((error) => {
+        return handleMcp(req, res, entry, usage).catch((error) => {
             entry.outcome = "exception";
             log({ event: "request_failed", message: error instanceof Error ? error.message : String(error) });
             if (!res.headersSent)
@@ -657,11 +673,12 @@ async function main() {
     const httpServer = createHttpServer((req, res) => {
         const started = performance.now();
         const entry = { http: req.method ?? "", method: null, tool: null, status: 0, outcome: null, ms: 0 };
-        const logged = !(req.url ?? "").startsWith("/healthz");
+        const usage = {};
+        const logged = !(req.url ?? "").startsWith("/healthz") && !(req.url ?? "").startsWith("/metrics");
         const closedEarly = new Promise((resolve) => res.once("close", () => resolve(!res.writableFinished)));
         let done;
         try {
-            done = handle(req, res, entry);
+            done = handle(req, res, entry, usage);
         }
         catch (error) {
             entry.outcome = "exception";
@@ -681,6 +698,11 @@ async function main() {
                 entry.outcome ??= res.statusCode < 400 ? "ok" : `http_${res.statusCode}`;
             entry.ms = Math.round(performance.now() - started);
             log(entry);
+            if (usage.client === undefined || typeof entry.method !== "string")
+                return;
+            metrics.request(entry.method, usage.client);
+            if (typeof entry.tool === "string")
+                metrics.toolCall(entry.tool, usage.client, String(entry.outcome), usage.address);
         });
     });
     // Whole request incl. queue wait: 30 s queue + 2 s grace + 32 MiB at the body floor (~131 s) + margin.

package/dist/metrics.d.ts

@@ -0,0 +1,24 @@
+/** Client class: Claude (Anthropic egress or Claude UA), ChatGPT (OpenAI egress or UA), else other. */
+export type ClientClass = "claude" | "chatgpt" | "other";
+/** Egress source of the caller's IP: static shared CIDRs = Anthropic, published lists = OpenAI (deploy contract). */
+export type Egress = "static" | "listed" | undefined;
+export declare function classifyClient(egress: Egress, userAgent: string): ClientClass;
+/** Bounded outcome label from the request log outcome. */
+export declare function outcomeClass(outcome: string | number | null | undefined): string;
+/** In-memory MCP usage counters in Prometheus text format; labels are closed sets, never IPs or arguments. */
+export declare class UsageMetrics {
+    private readonly tools;
+    private readonly now;
+    private readonly requests;
+    private readonly toolCalls;
+    private day;
+    private salt;
+    private readonly daily;
+    constructor(tools: readonly string[], now?: () => Date);
+    request(method: string, client: ClientClass): void;
+    /** One tools/call; `address` only feeds the daily distinct set as a keyed hash. */
+    toolCall(tool: string, client: ClientClass, outcome: string, address: string): void;
+    render(): string;
+    /** New UTC day: forget every hash and draw a new random salt, so days cannot be linked. */
+    private roll;
+}

package/dist/metrics.js

@@ -0,0 +1,84 @@
+import { createHmac, randomBytes } from "node:crypto";
+const CLIENTS = ["claude", "chatgpt", "other"];
+const METHODS = ["initialize", "notifications/initialized", "tools/list", "tools/call", "ping", "server/discover", "other"];
+const OUTCOMES = ["ok", "tool_error", "error", "client_closed"];
+/** Distinct-client memory bound (~100 bytes each); past it the day's gauge stops growing. */
+const MAX_DAILY_CLIENTS = 100_000;
+export function classifyClient(egress, userAgent) {
+    if (egress === "static" || /^claude/i.test(userAgent))
+        return "claude";
+    if (egress === "listed" || /^openai-mcp|chatgpt/i.test(userAgent))
+        return "chatgpt";
+    return "other";
+}
+/** Bounded outcome label from the request log outcome. */
+export function outcomeClass(outcome) {
+    return outcome === "ok" || outcome === "tool_error" || outcome === "client_closed" ? outcome : "error";
+}
+/** In-memory MCP usage counters in Prometheus text format; labels are closed sets, never IPs or arguments. */
+export class UsageMetrics {
+    tools;
+    now;
+    requests = new Map();
+    toolCalls = new Map();
+    day = "";
+    salt = Buffer.alloc(0);
+    daily = new Map();
+    constructor(tools, now = () => new Date()) {
+        this.tools = tools;
+        this.now = now;
+        // Every series born at 0, so increase() sees the first call after a restart.
+        for (const client of CLIENTS) {
+            for (const method of METHODS)
+                this.requests.set(`${method}\t${client}`, 0);
+            for (const tool of [...tools, "unknown"])
+                for (const outcome of OUTCOMES)
+                    this.toolCalls.set(`${tool}\t${client}\t${outcome}`, 0);
+        }
+    }
+    request(method, client) {
+        const key = `${METHODS.includes(method) ? method : "other"}\t${client}`;
+        this.requests.set(key, (this.requests.get(key) ?? 0) + 1);
+    }
+    /** One tools/call; `address` only feeds the daily distinct set as a keyed hash. */
+    toolCall(tool, client, outcome, address) {
+        const key = `${this.tools.includes(tool) ? tool : "unknown"}\t${client}\t${outcomeClass(outcome)}`;
+        this.toolCalls.set(key, (this.toolCalls.get(key) ?? 0) + 1);
+        this.roll();
+        const seen = this.daily.get(client);
+        if ([...this.daily.values()].reduce((sum, set) => sum + set.size, 0) >= MAX_DAILY_CLIENTS)
+            return;
+        seen.add(createHmac("sha256", this.salt).update(address).digest("base64").slice(0, 22));
+    }
+    render() {
+        this.roll();
+        const lines = [
+            "# HELP brewpage_mcp_requests_total Remote MCP JSON-RPC requests by method and client class.",
+            "# TYPE brewpage_mcp_requests_total counter",
+            ...[...this.requests].map(([key, value]) => {
+                const [method, client] = key.split("\t");
+                return `brewpage_mcp_requests_total{method="${method}",client="${client}"} ${value}`;
+            }),
+            "# HELP brewpage_mcp_tool_calls_total Remote MCP tools/call by tool, client class and outcome.",
+            "# TYPE brewpage_mcp_tool_calls_total counter",
+            ...[...this.toolCalls].map(([key, value]) => {
+                const [tool, client, outcome] = key.split("\t");
+                return `brewpage_mcp_tool_calls_total{tool="${tool}",client="${client}",outcome="${outcome}"} ${value}`;
+            }),
+            "# HELP brewpage_mcp_clients_today Distinct client addresses with a tools/call since 00:00 UTC (since start if later).",
+            "# TYPE brewpage_mcp_clients_today gauge",
+            ...CLIENTS.map((client) => `brewpage_mcp_clients_today{client="${client}"} ${this.daily.get(client).size}`),
+        ];
+        return `${lines.join("\n")}\n`;
+    }
+    /** New UTC day: forget every hash and draw a new random salt, so days cannot be linked. */
+    roll() {
+        const day = this.now().toISOString().slice(0, 10);
+        if (day === this.day)
+            return;
+        this.day = day;
+        this.salt = randomBytes(32);
+        for (const client of CLIENTS)
+            this.daily.set(client, new Set());
+    }
+}

package/dist/tools.d.ts

@@ -1,6 +1,6 @@
 import { McpServer } from "@modelcontextprotocol/server";
 export declare const DEFAULT_BASE_URL = "https://brewpage.app";
-export declare const USER_AGENT = "brewpage-mcp/1.20.0";
+export declare const USER_AGENT = "brewpage-mcp/1.21.0";
 export declare const OWNER_TOKEN_ENV = "BREWPAGE_OWNER_TOKEN";
 /** Server instructions of the handshake: one paragraph per line; the first stands alone within 512 chars. */
 export declare const SERVER_INSTRUCTIONS: string;

package/dist/tools.js

@@ -2,7 +2,7 @@ import { McpServer } from "@modelcontextprotocol/server";
 import { z } from "zod";
 import { PAGE_DATA_CALLS, PAGE_DATA_GUIDE } from "./guides/page-data.js";
 export const DEFAULT_BASE_URL = "https://brewpage.app";
-export const USER_AGENT = "brewpage-mcp/1.20.0";
+export const USER_AGENT = "brewpage-mcp/1.21.0";
 export const OWNER_TOKEN_ENV = "BREWPAGE_OWNER_TOKEN";
 /** Server instructions of the handshake: one paragraph per line; the first stands alone within 512 chars. */
 export const SERVER_INSTRUCTIONS = [
@@ -518,7 +518,7 @@ export function createServer(options = {}) {
     const apiFetch = options.fetch ?? fetch;
     const server = new McpServer({
         name: "brewpage-mcp",
-        version: "1.20.0",
+        version: "1.21.0",
     }, { instructions: SERVER_INSTRUCTIONS });
     /** Caller argument first, then the configured default; `fromEnv` marks the configured one. */
     function ownerTokenFor(argument) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brewpage-mcp",
-  "version": "1.20.0",
+  "version": "1.21.0",
   "mcpName": "io.github.kochetkov-ma/brewpage-mcp",
   "description": "MCP server for BrewPage — publish and manage HTML, sites, KV, JSON and files from AI assistants",
   "type": "module",