albyhub-admin-mcp 0.1.0

package/.env.example

@@ -0,0 +1,32 @@
+# Copy to .env and fill in. .env is gitignored.
+# Env vars passed by the parent process (Claude Code, etc.) take precedence.
+
+# Required ----------------------------------------------------------------
+
+# Base URL of your Alby Hub instance. Default for the desktop Hub is
+# http://localhost:8080. If your Hub is exposed remotely (e.g. via Cloudflare
+# Tunnel), point this at that URL. HTTPS strongly recommended for non-localhost.
+ALBYHUB_URL=http://localhost:8080
+
+# Alby Hub API access token. Get one from Alby Hub UI:
+#   Settings → Developer / Apps → create a new connection with API scopes.
+# Treat as a SECRET — full API tokens can drain your hub's on-chain balance
+# (e.g., by opening channels). Scope down if your Hub supports it.
+ALBYHUB_TOKEN=paste-yours-here
+
+# Optional ----------------------------------------------------------------
+
+# Force read-only — disables every tool that POSTs/PUTs/DELETEs. The generic
+# proxy_request tool still rejects non-GET methods when this is on.
+# ALBYHUB_READ_ONLY=false
+
+# Two-step confirmation for any non-GET request (proxy_request or future write
+# wrappers). Trades agent autonomy for safety.
+# ALBYHUB_REQUIRE_CONFIRM=false
+
+# Rolling 60s rate limit on outbound requests (per Hub instance).
+# ALBYHUB_MAX_REQUESTS_PER_MINUTE=30
+
+# Logging.
+# ALBYHUB_LOG_PATH=./albyhub-admin-mcp.log
+# ALBYHUB_AUDIT_PATH=./albyhub-admin-mcp-audit.log

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LLMOps.Pro
+
+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,106 @@
+# albyhub-admin-mcp
+
+**Node-admin operations on your Alby Hub, exposed to an LLM agent.** MCP server that wraps the Alby Hub HTTP API — read node info, balances, channels, NWC sub-wallets. Where NWC ([`nwc-mcp`](https://npmjs.com/package/nwc-mcp)) ends (it's wallet-scoped), this server picks up: hub-wide on-chain balance, channel state, sub-wallet inventory.
+
+> **v0.1 — defensive design.** Alby Hub's admin API has evolved across versions and isn't publicly versioned in a stable way. So v0.1 ships **one generic proxy tool** that hits any path (the escape hatch) plus typed wrappers around a few well-established endpoints. If a typed wrapper's endpoint-guess fails against your Hub version, the proxy lets you discover the right path without re-shipping. v0.2 hardens the typed wrappers once smoke-tested against real Hubs.
+
+---
+
+## The six tools
+
+| Tool | Method | Path | Purpose |
+|---|---|---|---|
+| `albyhub_proxy_request` | * | * | Generic HTTP proxy — escape hatch for any endpoint not yet wrapped. |
+| `albyhub_confirm_request` | * | * | Two-step confirm dispatcher for proxy_request. |
+| `albyhub_get_node_info` | GET | `/api/info` | Node identity, network, version. |
+| `albyhub_get_balances` | GET | `/api/balances` | On-chain + Lightning aggregate balances. |
+| `albyhub_list_apps` | GET | `/api/apps` | NWC connections (sub-wallets) provisioned on this hub. |
+| `albyhub_list_channels` | GET | `/api/channels` | Lightning channels with status + capacities. |
+
+All typed wrappers are safe GETs. Non-GET behavior runs through `albyhub_proxy_request`, which is gated by `ALBYHUB_READ_ONLY` and `ALBYHUB_REQUIRE_CONFIRM`.
+
+---
+
+## Requirements
+
+- Node 20+
+- A running Alby Hub instance (desktop app on `http://localhost:8080`, or self-hosted exposed somewhere)
+- An Alby Hub API token (Settings → Developer / Apps in the Hub UI)
+
+## Install
+
+```bash
+npx -y albyhub-admin-mcp
+```
+
+## Configure
+
+```bash
+cp .env.example .env
+# edit .env: set ALBYHUB_URL (default http://localhost:8080) + ALBYHUB_TOKEN
+```
+
+### Required
+
+| Var | Purpose |
+|---|---|
+| `ALBYHUB_URL` | Base URL of your Hub. Default `http://localhost:8080`. Use HTTPS if exposed remotely. |
+| `ALBYHUB_TOKEN` | API access token. **Full-scope tokens can drain the hub's on-chain balance — scope down or use ALBYHUB_READ_ONLY=true if your audience matters.** |
+
+### Optional safety knobs
+
+| Var | Default | Purpose |
+|---|---|---|
+| `ALBYHUB_READ_ONLY` | `false` | Refuse all non-GET requests via `proxy_request`. Strongly recommended for first-time setup. |
+| `ALBYHUB_REQUIRE_CONFIRM` | `false` | Two-step confirm for non-GET requests. |
+| `ALBYHUB_MAX_REQUESTS_PER_MINUTE` | `30` | Rolling 60s rate limit. |
+| `ALBYHUB_LOG_PATH` | `./albyhub-admin-mcp.log` | Server log. |
+| `ALBYHUB_AUDIT_PATH` | `./albyhub-admin-mcp-audit.log` | Append-only JSON-line audit log. |
+
+---
+
+## What if my Hub returns 404 on the typed wrappers?
+
+The endpoint path probably differs in your Hub version. Use `albyhub_proxy_request` to probe — try `/api/node`, `/info`, `/api/v1/info`, etc. Once you find the right path, you can pin it in your usage (and ping the maintainer to fix the typed wrapper in v0.2).
+
+```
+agent: albyhub_proxy_request({ method: "GET", path: "/api/v1/info" })
+→ { status: 200, body: { ... } }   // found it
+```
+
+---
+
+## Safety model
+
+The proxy tool's pipeline:
+
+1. **`ALBYHUB_READ_ONLY` gate** — non-GET requests blocked outright.
+2. **Rate limit** — rolling 60s window on the `requests` bucket.
+3. **`ALBYHUB_REQUIRE_CONFIRM` gate** — non-GET requests return a token; `albyhub_confirm_request` executes.
+4. **HTTP request** — Bearer auth, 15s timeout (override via `timeout_ms`).
+5. **Audit log** — every attempt (ok / blocked / error) as one structured JSON line.
+
+GET-only convenience wrappers skip steps 1 + 3 (they're safe by construction) but still go through rate limit + audit.
+
+---
+
+## Companion servers
+
+- [`nwc-mcp`](https://npmjs.com/package/nwc-mcp) — wallet ops via NIP-47. Use this for per-sub-wallet spend; use `albyhub-admin-mcp` for hub-wide / node-level operations.
+- [`nostr-ops-mcp`](https://npmjs.com/package/nostr-ops-mcp) — NOSTR identity + publishing.
+- [`marketplace-mcp`](https://npmjs.com/package/marketplace-mcp) — NIP-15 marketplace storefront.
+
+---
+
+## License
+
+MIT — see [`LICENSE`](./LICENSE).
+
+## Contact / Issues
+
+Built by **LLMOps.Pro**.
+
+- **NOSTR:** [`npub1hdg932jvwc3jdvkqywgqv0ue4nn60exrf92asy8mtazt3hjg7d2s2yw0nw`](https://njump.me/npub1hdg932jvwc3jdvkqywgqv0ue4nn60exrf92asy8mtazt3hjg7d2s2yw0nw) — follow, DM, zap.
+- **Lightning Address:** `sovereigncitizens@getalby.com` — for support zaps and "this was useful" tips.
+- **Bug reports / feature requests:** open a GitHub issue (link forthcoming).
+- **Security issues:** please disclose privately via NOSTR DM before opening a public issue.

package/dist/index.js

@@ -0,0 +1,509 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { dirname, resolve } from "path";
+import { fileURLToPath } from "url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/config.ts
+import { z } from "zod";
+var boolish = z.string().optional().transform((v) => v === "true" || v === "1");
+var positiveInt = z.coerce.number().int().positive();
+var ConfigSchema = z.object({
+  ALBYHUB_URL: z.string().min(1, "ALBYHUB_URL is required").refine(
+    (s) => {
+      try {
+        new URL(s);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    "ALBYHUB_URL must be a valid URL (e.g. http://localhost:8080)"
+  ),
+  ALBYHUB_TOKEN: z.string().min(1, "ALBYHUB_TOKEN is required \u2014 get one from your Alby Hub UI Settings \u2192 Developer / Apps"),
+  ALBYHUB_READ_ONLY: boolish,
+  ALBYHUB_REQUIRE_CONFIRM: boolish,
+  ALBYHUB_MAX_REQUESTS_PER_MINUTE: positiveInt.default(30),
+  ALBYHUB_LOG_PATH: z.string().default("./albyhub-admin-mcp.log"),
+  ALBYHUB_AUDIT_PATH: z.string().default("./albyhub-admin-mcp-audit.log")
+});
+function loadConfig() {
+  const parsed = ConfigSchema.safeParse(process.env);
+  if (!parsed.success) {
+    const issues = parsed.error.issues.map((i) => `  - ${i.path.join(".")}: ${i.message}`).join("\n");
+    process.stderr.write(
+      `albyhub-admin-mcp: invalid configuration:
+${issues}
+
+Set the required env vars and try again.
+`
+    );
+    process.exit(1);
+  }
+  return parsed.data;
+}
+
+// src/hub-client.ts
+var HubClient = class {
+  constructor(config) {
+    this.config = config;
+  }
+  config;
+  get baseUrl() {
+    return this.config.ALBYHUB_URL.replace(/\/+$/, "");
+  }
+  async request(method, path, opts = {}) {
+    let url = this.baseUrl + (path.startsWith("/") ? path : "/" + path);
+    if (opts.query && Object.keys(opts.query).length > 0) {
+      const qs = new URLSearchParams(opts.query);
+      url += (url.includes("?") ? "&" : "?") + qs.toString();
+    }
+    const headers = {
+      Authorization: `Bearer ${this.config.ALBYHUB_TOKEN}`,
+      Accept: "application/json",
+      ...opts.body !== void 0 ? { "Content-Type": "application/json" } : {},
+      ...opts.extraHeaders ?? {}
+    };
+    const init = {
+      method: method.toUpperCase(),
+      headers
+    };
+    if (opts.body !== void 0) {
+      init.body = typeof opts.body === "string" ? opts.body : JSON.stringify(opts.body);
+    }
+    const timeoutMs = opts.timeoutMs ?? 15e3;
+    const controller = new AbortController();
+    init.signal = controller.signal;
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const res = await fetch(url, init);
+      const text = await res.text();
+      let body = text;
+      const ct = res.headers.get("content-type") ?? "";
+      if (ct.includes("application/json") && text.length > 0) {
+        try {
+          body = JSON.parse(text);
+        } catch {
+        }
+      }
+      const responseHeaders = {};
+      res.headers.forEach((v, k) => responseHeaders[k] = v);
+      return {
+        status: res.status,
+        status_text: res.statusText,
+        ok: res.ok,
+        headers: responseHeaders,
+        body
+      };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  get(path, query) {
+    return this.request("GET", path, { query });
+  }
+};
+
+// src/safety/audit-log.ts
+import { appendFile } from "fs/promises";
+var AuditLog = class {
+  constructor(path) {
+    this.path = path;
+  }
+  path;
+  async record(event) {
+    const line = JSON.stringify({ ts: (/* @__PURE__ */ new Date()).toISOString(), ...event }) + "\n";
+    try {
+      await appendFile(this.path, line, "utf8");
+    } catch (err) {
+      process.stderr.write(`albyhub-admin-mcp: failed to append audit log: ${String(err)}
+`);
+    }
+  }
+};
+
+// src/safety/confirm.ts
+import { randomBytes } from "crypto";
+var DEFAULT_TTL_MS = 5 * 60 * 1e3;
+var ConfirmStore = class {
+  constructor(ttlMs = DEFAULT_TTL_MS) {
+    this.ttlMs = ttlMs;
+  }
+  ttlMs;
+  pending = /* @__PURE__ */ new Map();
+  prepare(action) {
+    this.pruneExpired();
+    const token = randomBytes(16).toString("hex");
+    const expires_at = Date.now() + this.ttlMs;
+    this.pending.set(token, { ...action, token, expires_at });
+    return { token, expires_at };
+  }
+  consume(token) {
+    this.pruneExpired();
+    const stored = this.pending.get(token);
+    if (!stored) return null;
+    this.pending.delete(token);
+    return stored;
+  }
+  pruneExpired() {
+    const now = Date.now();
+    for (const [token, action] of this.pending) {
+      if (action.expires_at <= now) this.pending.delete(token);
+    }
+  }
+};
+
+// src/safety/rate-limiter.ts
+var WINDOW_MS = 6e4;
+var RateLimiter = class {
+  buckets = /* @__PURE__ */ new Map();
+  limits;
+  constructor(limits) {
+    this.limits = new Map(Object.entries(limits));
+  }
+  take(bucket) {
+    const limit = this.limits.get(bucket);
+    if (limit === void 0) return { ok: true };
+    const now = Date.now();
+    const cutoff = now - WINDOW_MS;
+    const entries = (this.buckets.get(bucket) ?? []).filter((ts) => ts > cutoff);
+    if (entries.length >= limit) {
+      return {
+        ok: false,
+        reason: `rate limit hit on "${bucket}": ${entries.length}/${limit} in the last 60s`
+      };
+    }
+    entries.push(now);
+    this.buckets.set(bucket, entries);
+    return { ok: true };
+  }
+  snapshot() {
+    const now = Date.now();
+    const cutoff = now - WINDOW_MS;
+    const out = {};
+    for (const [bucket, limit] of this.limits) {
+      const entries = (this.buckets.get(bucket) ?? []).filter((ts) => ts > cutoff);
+      out[bucket] = { used: entries.length, limit };
+    }
+    return out;
+  }
+};
+
+// src/tools/confirm-request.ts
+import { z as z3 } from "zod";
+
+// src/tools/_result.ts
+function textResult(payload) {
+  const text = typeof payload === "string" ? payload : JSON.stringify(payload, null, 2);
+  return { content: [{ type: "text", text }] };
+}
+function errorResult(message) {
+  return { content: [{ type: "text", text: message }], isError: true };
+}
+
+// src/tools/proxy-request.ts
+import { z as z2 } from "zod";
+var SAFE_METHODS = /* @__PURE__ */ new Set(["GET", "HEAD", "OPTIONS"]);
+var inputSchema = {
+  method: z2.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]).describe("HTTP method. GET/HEAD/OPTIONS are always allowed; others gated by READ_ONLY + REQUIRE_CONFIRM."),
+  path: z2.string().min(1).regex(/^\//, "path must start with `/`").describe("Path on the Hub, e.g. `/api/info` or `/api/channels`. Combined with ALBYHUB_URL."),
+  query: z2.record(z2.string()).optional().describe("Query-string params (string \u2192 string)."),
+  body: z2.any().optional().describe("Request body \u2014 passed as JSON if an object, raw if a string. Ignored for GET/HEAD/OPTIONS."),
+  extra_headers: z2.record(z2.string()).optional().describe("Extra HTTP headers to merge in. Useful if your Hub expects `X-API-Key` instead of `Authorization: Bearer`."),
+  timeout_ms: z2.number().int().positive().max(6e4).optional().describe("Request timeout in ms (default 15000, max 60000).")
+};
+async function evaluateAndProxy(deps, params, opts = {}) {
+  const auditTool = opts.auditTool ?? "albyhub_proxy_request";
+  const inputForAudit = {
+    method: params.method,
+    path: params.path,
+    has_body: params.body !== void 0,
+    extra_header_keys: params.extra_headers ? Object.keys(params.extra_headers) : []
+  };
+  const isWrite = !SAFE_METHODS.has(params.method.toUpperCase());
+  if (isWrite && deps.config.ALBYHUB_READ_ONLY) {
+    await deps.audit.record({
+      tool: auditTool,
+      outcome: "blocked",
+      input: inputForAudit,
+      blocked_reason: "ALBYHUB_READ_ONLY=true \u2014 non-GET methods are disabled"
+    });
+    return errorResult("ALBYHUB_READ_ONLY=true \u2014 non-GET methods are disabled");
+  }
+  const rate = deps.rateLimiter.take("requests");
+  if (!rate.ok) {
+    await deps.audit.record({
+      tool: auditTool,
+      outcome: "blocked",
+      input: inputForAudit,
+      blocked_reason: rate.reason
+    });
+    return errorResult(rate.reason);
+  }
+  if (isWrite && deps.config.ALBYHUB_REQUIRE_CONFIRM && !opts.skipConfirmGate) {
+    const summary = `${params.method.toUpperCase()} ${params.path}${params.body !== void 0 ? " (with body)" : ""}`;
+    const { token, expires_at } = deps.confirm.prepare({
+      tool: auditTool,
+      params,
+      summary
+    });
+    await deps.audit.record({
+      tool: auditTool,
+      outcome: "ok",
+      input: inputForAudit,
+      result: { confirmation_required: true, token }
+    });
+    return textResult({
+      status: "confirmation_required",
+      token,
+      expires_at: new Date(expires_at).toISOString(),
+      summary,
+      next_step: `Call albyhub_confirm_request with token "${token}" to execute.`
+    });
+  }
+  try {
+    const response = await deps.hub.request(params.method, params.path, {
+      body: params.body,
+      query: params.query,
+      extraHeaders: params.extra_headers,
+      timeoutMs: params.timeout_ms
+    });
+    await deps.audit.record({
+      tool: auditTool,
+      outcome: response.ok ? "ok" : "error",
+      input: inputForAudit,
+      result: {
+        status: response.status,
+        ok: response.ok
+      },
+      ...response.ok ? {} : { error: `HTTP ${response.status} ${response.status_text}` }
+    });
+    return textResult({
+      status: response.status,
+      status_text: response.status_text,
+      ok: response.ok,
+      headers: response.headers,
+      body: response.body
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    await deps.audit.record({
+      tool: auditTool,
+      outcome: "error",
+      input: inputForAudit,
+      error: msg
+    });
+    return errorResult(`${auditTool} failed: ${msg}`);
+  }
+}
+function registerProxyRequest(server, deps) {
+  server.registerTool(
+    "albyhub_proxy_request",
+    {
+      description: "Generic HTTP proxy to your Alby Hub admin API. Use this when no typed convenience tool exists for the endpoint you need. Returns the response status, headers, and (JSON-parsed when possible) body. Non-GET methods are gated by ALBYHUB_READ_ONLY and ALBYHUB_REQUIRE_CONFIRM. Pair with the Hub's own docs to discover endpoints; the typed wrappers (get_node_info, list_apps, get_balances) are layered on top of this and good defaults to start with.",
+      inputSchema
+    },
+    async (args) => evaluateAndProxy(deps, args)
+  );
+}
+
+// src/tools/confirm-request.ts
+var inputSchema2 = {
+  token: z3.string().min(1).describe("Confirmation token from a previous non-GET proxy_request.")
+};
+function registerConfirmRequest(server, deps) {
+  server.registerTool(
+    "albyhub_confirm_request",
+    {
+      description: "Execute a previously-prepared non-GET request, identified by its one-time token. Only meaningful when ALBYHUB_REQUIRE_CONFIRM=true. The token is consumed (single use) and the safety pipeline (read-only, rate limit) re-runs before the HTTP call.",
+      inputSchema: inputSchema2
+    },
+    async ({ token }) => {
+      const action = deps.confirm.consume(token);
+      if (!action) {
+        await deps.audit.record({
+          tool: "albyhub_confirm_request",
+          outcome: "blocked",
+          input: { token_prefix: token.slice(0, 8) + "..." },
+          blocked_reason: "token unknown or expired"
+        });
+        return errorResult("Token is unknown or expired. Call the original proxy_request again to get a fresh token.");
+      }
+      const params = action.params;
+      return evaluateAndProxy(deps, params, {
+        skipConfirmGate: true,
+        auditTool: "albyhub_confirm_request"
+      });
+    }
+  );
+}
+
+// src/tools/get-balances.ts
+function registerGetBalances(server, hub, audit) {
+  server.registerTool(
+    "albyhub_get_balances",
+    {
+      description: "Fetch hub balances (on-chain + lightning) from GET /api/balances. Distinct from nwc_get_balance \u2014 that one is a single sub-wallet's view via NWC; this one is the hub-wide aggregate including on-chain. If your Hub returns 404, probe with albyhub_proxy_request."
+    },
+    async () => {
+      try {
+        const r = await hub.get("/api/balances");
+        await audit.record({
+          tool: "albyhub_get_balances",
+          outcome: r.ok ? "ok" : "error",
+          result: { status: r.status, ok: r.ok },
+          ...r.ok ? {} : { error: `HTTP ${r.status} ${r.status_text}` }
+        });
+        return textResult({ status: r.status, ok: r.ok, body: r.body });
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        await audit.record({ tool: "albyhub_get_balances", outcome: "error", error: msg });
+        return errorResult(`albyhub_get_balances failed: ${msg}`);
+      }
+    }
+  );
+}
+
+// src/tools/get-node-info.ts
+function registerGetNodeInfo(server, hub, audit) {
+  server.registerTool(
+    "albyhub_get_node_info",
+    {
+      description: "Fetch Alby Hub node info (identity, network, version) from GET /api/info. Convenience wrapper. If your Hub returns 404 here, the endpoint path differs in your version \u2014 use albyhub_proxy_request to probe alternatives like /api/node or /info."
+    },
+    async () => {
+      try {
+        const r = await hub.get("/api/info");
+        await audit.record({
+          tool: "albyhub_get_node_info",
+          outcome: r.ok ? "ok" : "error",
+          result: { status: r.status, ok: r.ok },
+          ...r.ok ? {} : { error: `HTTP ${r.status} ${r.status_text}` }
+        });
+        return textResult({ status: r.status, ok: r.ok, body: r.body });
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        await audit.record({ tool: "albyhub_get_node_info", outcome: "error", error: msg });
+        return errorResult(`albyhub_get_node_info failed: ${msg}`);
+      }
+    }
+  );
+}
+
+// src/tools/list-apps.ts
+function registerListApps(server, hub, audit) {
+  server.registerTool(
+    "albyhub_list_apps",
+    {
+      description: "List NWC connections / sub-wallets ('apps') currently provisioned on the Hub. Each entry typically includes name, pubkey, scope, daily budget, and creation timestamp. Hits GET /api/apps. Use this to inventory what's connected to your Hub and what each connection's budget cap is."
+    },
+    async () => {
+      try {
+        const r = await hub.get("/api/apps");
+        await audit.record({
+          tool: "albyhub_list_apps",
+          outcome: r.ok ? "ok" : "error",
+          result: { status: r.status, ok: r.ok, app_count: Array.isArray(r.body) ? r.body.length : null },
+          ...r.ok ? {} : { error: `HTTP ${r.status} ${r.status_text}` }
+        });
+        return textResult({ status: r.status, ok: r.ok, body: r.body });
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        await audit.record({ tool: "albyhub_list_apps", outcome: "error", error: msg });
+        return errorResult(`albyhub_list_apps failed: ${msg}`);
+      }
+    }
+  );
+}
+
+// src/tools/list-channels.ts
+function registerListChannels(server, hub, audit) {
+  server.registerTool(
+    "albyhub_list_channels",
+    {
+      description: "List Lightning channels \u2014 typically peer pubkey, capacity, local/remote balance, public/private flag, online status. Hits GET /api/channels. The hub-wide view (vs. nwc-mcp which has no channel concept). Useful for spotting offline channels, low inbound, etc."
+    },
+    async () => {
+      try {
+        const r = await hub.get("/api/channels");
+        await audit.record({
+          tool: "albyhub_list_channels",
+          outcome: r.ok ? "ok" : "error",
+          result: { status: r.status, ok: r.ok, channel_count: Array.isArray(r.body) ? r.body.length : null },
+          ...r.ok ? {} : { error: `HTTP ${r.status} ${r.status_text}` }
+        });
+        return textResult({ status: r.status, ok: r.ok, body: r.body });
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        await audit.record({ tool: "albyhub_list_channels", outcome: "error", error: msg });
+        return errorResult(`albyhub_list_channels failed: ${msg}`);
+      }
+    }
+  );
+}
+
+// src/tools/register.ts
+function registerAllTools(deps) {
+  const { server, hub, audit } = deps;
+  const proxyDeps = {
+    config: deps.config,
+    hub: deps.hub,
+    audit: deps.audit,
+    rateLimiter: deps.rateLimiter,
+    confirm: deps.confirm
+  };
+  registerProxyRequest(server, proxyDeps);
+  registerConfirmRequest(server, proxyDeps);
+  registerGetNodeInfo(server, hub, audit);
+  registerGetBalances(server, hub, audit);
+  registerListApps(server, hub, audit);
+  registerListChannels(server, hub, audit);
+}
+
+// src/index.ts
+function tryLoadEnvFile() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const path = resolve(here, "..", ".env");
+  try {
+    process.loadEnvFile(path);
+  } catch {
+  }
+}
+tryLoadEnvFile();
+async function main() {
+  const config = loadConfig();
+  const audit = new AuditLog(config.ALBYHUB_AUDIT_PATH);
+  const rateLimiter = new RateLimiter({ requests: config.ALBYHUB_MAX_REQUESTS_PER_MINUTE });
+  const confirm = new ConfirmStore();
+  const hub = new HubClient(config);
+  const server = new McpServer(
+    { name: "albyhub-admin-mcp", version: "0.1.0" },
+    { capabilities: { tools: {} } }
+  );
+  registerAllTools({ server, config, hub, audit, rateLimiter, confirm });
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  await audit.record({
+    tool: "_startup",
+    outcome: "ok",
+    result: {
+      hub_url: hub.baseUrl,
+      read_only: config.ALBYHUB_READ_ONLY,
+      require_confirm: config.ALBYHUB_REQUIRE_CONFIRM,
+      rate_limits: rateLimiter.snapshot()
+    }
+  });
+  const shutdown = async (signal) => {
+    await audit.record({ tool: "_shutdown", outcome: "ok", result: { signal } });
+    process.exit(0);
+  };
+  process.on("SIGINT", () => void shutdown("SIGINT"));
+  process.on("SIGTERM", () => void shutdown("SIGTERM"));
+}
+main().catch((err) => {
+  process.stderr.write(`albyhub-admin-mcp: fatal: ${err instanceof Error ? err.stack : String(err)}
+`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "albyhub-admin-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for node-admin operations on an Alby Hub instance via its HTTP API. Lets agents read node info, balances, channels, and sub-wallet apps; sub-wallet provisioning + channel ops gated behind safety knobs. A generic proxy_request tool covers any endpoint the typed wrappers don't yet expose. Pairs with nwc-mcp (NIP-47 wallet ops) — admin handles what NWC can't reach.",
+  "type": "module",
+  "license": "MIT",
+  "author": "LLMOps.Pro <https://njump.me/npub1hdg932jvwc3jdvkqywgqv0ue4nn60exrf92asy8mtazt3hjg7d2s2yw0nw>",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "alby",
+    "alby-hub",
+    "lightning",
+    "bitcoin",
+    "lnd",
+    "node-admin",
+    "claude",
+    "ai-agent",
+    "llm"
+  ],
+  "bin": {
+    "albyhub-admin-mcp": "dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    ".env.example"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --target node20 --clean --shims",
+    "dev": "tsx watch src/index.ts",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "packageManager": "pnpm@9.15.0"
+}