@lacneu/atrium-mcp 0.30.0

package/README.md

@@ -0,0 +1,160 @@
+# atrium-mcp
+
+A thin, dependency-light **MCP server + CLI** that proxy the atrium
+`/api/v1` observability surface using an `oc_live_` Bearer API key.
+
+It speaks **HTTP only** — it imports nothing from the Convex app. Each tool maps
+to one `/api/v1` route and one permission, which is enforced **server-side** by the
+deployment (`requirePermission`). A scoped key (e.g. an `observer`) therefore simply
+gets a `403` for routes it isn't allowed to call.
+
+Runtime dependencies: `@modelcontextprotocol/sdk` and `zod` only.
+
+## Configuration (environment)
+
+| Variable                     | Required | Default                  | Meaning                                                  |
+| ---------------------------- | -------- | ------------------------ | -------------------------------------------------------- |
+| `OPENCLAW_WEBCHAT_API_BASE`  | no       | `http://127.0.0.1:3213`  | Deployment `.site` origin, **without** `/api/v1`.        |
+| `OPENCLAW_WEBCHAT_API_KEY`   | **yes**  | —                        | The `oc_live_...` Bearer key.                            |
+
+The `/api/v1` prefix is added internally; you point `API_BASE` at the bare
+`.site` origin. The key is only ever sent in the `Authorization` header — never
+in a URL/query string and never logged.
+
+## Install (released artifact)
+
+Published on every tagged release as **`@lacneu/atrium-mcp`** (npm, OIDC +
+provenance), at the same lockstep version as the app images. Being HTTP-only and
+provider-neutral, the same package serves any MCP-capable gateway (OpenClaw,
+Hermes, Claude Code, …).
+
+```bash
+# ad hoc (any MCP client with stdio command support)
+npx -y @lacneu/atrium-mcp
+
+# pinned, baked into a gateway image
+npm install -g @lacneu/atrium-mcp@<version>   # provides `atrium-mcp` + `atrium` (CLI)
+```
+
+Example OpenClaw declaration (`mcp.servers`, stdio) — one server per deployment,
+credentials injected via a wrapper or the process environment, never in config:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "atrium-prod": { "command": "atrium-mcp-prod" }
+    }
+  }
+}
+```
+
+## Build (from source)
+
+```bash
+cd mcp
+npm install
+npm run build      # emits dist/ (with shebangs preserved)
+```
+
+Other scripts: `npm run typecheck`, `npm test`.
+
+## Tools (MCP) / Commands (CLI)
+
+| MCP tool               | CLI command      | Route                         | Permission         | Purpose |
+| ---------------------- | ---------------- | ----------------------------- | ------------------ | ------- |
+| `health`               | `health`         | `GET  /api/v1/health`         | none               | Liveness probe for the API surface. |
+| `get_compat`           | `compat`         | `GET  /api/v1/compat`         | `bridge.read`      | Bridge version + per-instance gateway versions/capabilities. |
+| `get_integrations`     | —                | `GET  /api/v1/integrations`   | `traces.read`      | Opik/Langfuse configured/enabled + shipping cursors. No keys. |
+| `get_chat_state`       | —                | `GET  /api/v1/chat-state`     | `traces.read`      | Per-message lifecycle of one chat (metadata only). |
+| `get_trace_enrichment` | —                | `GET  /api/v1/trace-enrichment` | `traces.read`    | SOC2-safe span structure from Opik/Langfuse, keyed by `correlationId`. |
+| `diagnose_chat`        | —                | `GET  /api/v1/diagnose`       | `traces.read`      | One assessment of a chat + a suggested action/tool. |
+| `reconcile_chat`       | —                | `POST /api/v1/reconcile-chat` | `selfheal`         | Release a chat's stuck `streaming` message (text preserved). Audited. |
+| `list_traces`          | `traces`         | `GET  /api/v1/traces`         | `traces.read`      | Recent trace events, with filtering. |
+| `get_kpi`              | `kpi`            | `GET  /api/v1/kpi`            | `kpi.read`         | KPI rollups. |
+| `query_openclaw`       | `query-openclaw` | `POST /api/v1/openclaw/query` | `openclaw.query`   | Query OpenClaw via the bridge. |
+| `list_anomalies`       | `anomalies`      | `GET  /api/v1/anomalies`      | `anomalies.read`   | Detected anomalies, with status/severity/source filtering. |
+| `report_anomaly`       | `report-anomaly` | `POST /api/v1/anomalies`      | `anomalies.report` | Record an anomaly / self-repair signal. |
+
+Tools without a CLI command are MCP-only. Every tool's permission is enforced by
+the deployment: a key lacking a tool's permission gets a `403` the tool surfaces
+as an error.
+
+The four read-only diagnostic tools (`get_integrations`, `diagnose_chat`,
+`get_chat_state`, `get_trace_enrichment`) plus the bounded corrective
+`reconcile_chat` compose into a closed loop an agent can drive from a single user
+report. See **[the self-correction loop](../docs/SELF_CORRECTION_LOOP.md)** for how
+they fit together and the SOC2-safe trace catalog (including the `documentary.*`
+document-fetch traces). The whole surface is metadata-only — never message text,
+filenames, URLs, or keys.
+
+## CLI usage
+
+```bash
+export OPENCLAW_WEBCHAT_API_BASE=http://127.0.0.1:3213
+export OPENCLAW_WEBCHAT_API_KEY=oc_live_xxxxxxxxxxxx
+
+node dist/cli.js health
+node dist/cli.js compat
+node dist/cli.js traces --limit 20
+node dist/cli.js traces --kind api.call --correlation-id abc123
+
+# filtering (traces): --q substring, time range, structured fields
+#   --from/--to accept epoch ms OR a Grafana relative token (now, now-<N><unit>)
+node dist/cli.js traces --from now-24h --to now --status-class 4xx --kind api.call --q foo
+node dist/cli.js traces --status 404 --principal-type service --role-key admin
+
+node dist/cli.js kpi --metric api.calls --since 2026-06-01T00:00
+node dist/cli.js kpi --metric api.calls --from now-24h --to now
+node dist/cli.js anomalies --limit 50 --status open
+node dist/cli.js anomalies --from now-1h --severity critical --source detector --q spike
+node dist/cli.js query-openclaw --prompt "summarize last run" --chat-id c1
+node dist/cli.js report-anomaly --kind latency.spike --severity warn --message "p99 > 5s"
+```
+
+If installed/published, the same is available as the `atrium` bin
+(e.g. `atrium traces --limit 20`).
+
+## OpenClaw MCP wiring
+
+Register the stdio server in `~/.openclaw/openclaw.json`. Because this package
+is not published, run the built file directly:
+
+```json
+{
+  "mcpServers": {
+    "atrium": {
+      "command": "node",
+      "args": ["/absolute/path/to/atrium/mcp/dist/server.js"],
+      "env": {
+        "OPENCLAW_WEBCHAT_API_BASE": "http://127.0.0.1:3213",
+        "OPENCLAW_WEBCHAT_API_KEY": "oc_live_..."
+      }
+    }
+  }
+}
+```
+
+After publishing to a registry, the `npx` form works too:
+
+```json
+{
+  "mcpServers": {
+    "atrium": {
+      "command": "npx",
+      "args": ["-y", "atrium-mcp"],
+      "env": {
+        "OPENCLAW_WEBCHAT_API_BASE": "https://<deployment>.convex.site",
+        "OPENCLAW_WEBCHAT_API_KEY": "oc_live_..."
+      }
+    }
+  }
+}
+```
+
+## Security
+
+- The API key lives in env only — never committed, never logged, never in a URL.
+- Stdio transport avoids the DNS-rebinding surface of local HTTP MCP servers.
+- Permission scoping is enforced by the deployment, not the client: a key that
+  lacks a tool's permission gets a `403` that the tool surfaces as an error.

package/dist/cli.d.ts

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+/**
+ * atrium CLI — a thin shell client over the same /api/v1 calls the
+ * MCP server exposes. Same env-var auth (OPENCLAW_WEBCHAT_API_BASE +
+ * OPENCLAW_WEBCHAT_API_KEY); the Bearer key is only ever sent in the
+ * Authorization header (never echoed, never in a URL).
+ *
+ * Usage:
+ *   atrium health
+ *   atrium traces [--limit N] [--q TEXT] [--from T] [--to T] [--kind K]
+ *       [--status CODE] [--status-class 2xx|4xx|5xx] [--direction D]
+ *       [--principal-type T] [--role-key K] [--correlation-id ID]
+ *   atrium kpi [--metric M] [--since ISO] [--from T] [--to T]
+ *   atrium anomalies [--limit N] [--since ISO] [--q TEXT] [--from T]
+ *       [--to T] [--status S] [--severity S] [--source S] [--kind K]
+ *   atrium query-openclaw [--question TEXT]
+ *   atrium report-anomaly --kind K --severity S --message M [--correlation-id ID]
+ *   atrium bridge-status
+ *   atrium sync --instance NAME
+ *
+ * --from/--to accept epoch ms OR a Grafana relative token (e.g. now-24h, now).
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+/**
+ * atrium CLI — a thin shell client over the same /api/v1 calls the
+ * MCP server exposes. Same env-var auth (OPENCLAW_WEBCHAT_API_BASE +
+ * OPENCLAW_WEBCHAT_API_KEY); the Bearer key is only ever sent in the
+ * Authorization header (never echoed, never in a URL).
+ *
+ * Usage:
+ *   atrium health
+ *   atrium traces [--limit N] [--q TEXT] [--from T] [--to T] [--kind K]
+ *       [--status CODE] [--status-class 2xx|4xx|5xx] [--direction D]
+ *       [--principal-type T] [--role-key K] [--correlation-id ID]
+ *   atrium kpi [--metric M] [--since ISO] [--from T] [--to T]
+ *   atrium anomalies [--limit N] [--since ISO] [--q TEXT] [--from T]
+ *       [--to T] [--status S] [--severity S] [--source S] [--kind K]
+ *   atrium query-openclaw [--question TEXT]
+ *   atrium report-anomaly --kind K --severity S --message M [--correlation-id ID]
+ *   atrium bridge-status
+ *   atrium sync --instance NAME
+ *
+ * --from/--to accept epoch ms OR a Grafana relative token (e.g. now-24h, now).
+ */
+import { ApiError, resolveConfig } from "./config.js";
+import { bridgeStatus, getCompat, getKpi, getSchema, health, listAnomalies, listSchemas, listTraces, queryOpenClaw, reportAnomaly, syncInstance, } from "./tools.js";
+/** Parse `--key value`, `--key=value`, and bare `--flag` arguments. */
+function parseArgs(argv) {
+    const positionals = [];
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token.startsWith("--")) {
+            const eq = token.indexOf("=");
+            if (eq !== -1) {
+                flags[token.slice(2, eq)] = token.slice(eq + 1);
+            }
+            else {
+                const next = argv[i + 1];
+                if (next !== undefined && !next.startsWith("--")) {
+                    flags[token.slice(2)] = next;
+                    i++;
+                }
+                else {
+                    flags[token.slice(2)] = true;
+                }
+            }
+        }
+        else {
+            positionals.push(token);
+        }
+    }
+    return { positionals, flags };
+}
+function num(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const n = Number(value);
+    return Number.isFinite(n) ? n : undefined;
+}
+function str(value) {
+    return typeof value === "string" ? value : undefined;
+}
+const USAGE = `atrium — thin CLI over the /api/v1 observability surface
+
+Commands:
+  health                              GET  /health
+  compat                              GET  /compat            (bridge.read)
+  bridge-status                       GET  /bridge-status     (bridge.read)
+  schemas                             GET  /schemas           (public)
+  schema --id NAME                    GET  /schemas/:id       (public)
+  sync --instance NAME                POST /instances/sync    (selfheal)
+  traces [--limit N] [--q TEXT] [--from T] [--to T] [--kind K] [--status CODE]
+         [--status-class 2xx|4xx|5xx] [--direction D] [--principal-type T]
+         [--role-key K] [--correlation-id ID]
+                                      GET  /traces            (traces.read)
+  kpi [--metric M] [--since ISO] [--from T] [--to T]
+                                      GET  /kpi               (kpi.read)
+  anomalies [--limit N] [--since ISO] [--q TEXT] [--from T] [--to T]
+            [--status S] [--severity S] [--source S] [--kind K]
+                                      GET  /anomalies         (anomalies.read)
+  query-openclaw [--question TEXT]    POST /openclaw/query    (openclaw.query)
+  report-anomaly --kind K --severity info|warn|critical --message M [--correlation-id ID]
+                                      POST /anomalies         (anomalies.report)
+
+Filters:
+  --from / --to accept epoch ms (e.g. 1717372800000) OR a Grafana relative
+  token: now, or now-<N><unit> with unit s|m|h|d|w (e.g. --from now-24h --to now).
+  Example: traces --from now-24h --to now --status-class 4xx --kind api.call --q foo
+
+Environment:
+  OPENCLAW_WEBCHAT_API_BASE  deployment .site origin (default http://127.0.0.1:3213)
+  OPENCLAW_WEBCHAT_API_KEY   oc_live_ Bearer key (required)`;
+async function dispatch(config, command, flags) {
+    switch (command) {
+        case "health":
+            return health(config);
+        case "compat":
+            return getCompat(config);
+        case "bridge-status":
+            return bridgeStatus(config);
+        case "schemas":
+            return listSchemas(config);
+        case "schema": {
+            const id = str(flags.id);
+            if (!id) {
+                throw new Error("schema requires --id NAME (e.g. --id provenance.v1)");
+            }
+            return getSchema(config, { id });
+        }
+        case "sync": {
+            const instance = str(flags.instance);
+            if (!instance) {
+                throw new Error("sync requires --instance NAME");
+            }
+            return syncInstance(config, { instance });
+        }
+        case "traces": {
+            const statusClass = str(flags["status-class"]);
+            if (statusClass !== undefined &&
+                statusClass !== "2xx" &&
+                statusClass !== "4xx" &&
+                statusClass !== "5xx") {
+                throw new Error("--status-class must be one of 2xx|4xx|5xx");
+            }
+            return listTraces(config, {
+                limit: num(flags.limit),
+                q: str(flags.q),
+                from: str(flags.from),
+                to: str(flags.to),
+                kind: str(flags.kind),
+                status: num(flags.status),
+                statusClass,
+                direction: str(flags.direction),
+                principalType: str(flags["principal-type"]),
+                roleKey: str(flags["role-key"]),
+                correlationId: str(flags["correlation-id"]),
+            });
+        }
+        case "kpi":
+            return getKpi(config, {
+                metric: str(flags.metric),
+                since: str(flags.since),
+                from: str(flags.from),
+                to: str(flags.to),
+            });
+        case "anomalies":
+            return listAnomalies(config, {
+                limit: num(flags.limit),
+                since: str(flags.since),
+                q: str(flags.q),
+                from: str(flags.from),
+                to: str(flags.to),
+                status: str(flags.status),
+                severity: str(flags.severity),
+                source: str(flags.source),
+                kind: str(flags.kind),
+            });
+        case "query-openclaw":
+            return queryOpenClaw(config, {
+                question: str(flags.question),
+            });
+        case "report-anomaly": {
+            const kind = str(flags.kind);
+            if (!kind) {
+                throw new Error("report-anomaly requires --kind");
+            }
+            const severity = str(flags.severity);
+            if (severity !== "info" && severity !== "warn" && severity !== "critical") {
+                throw new Error("report-anomaly requires --severity info|warn|critical");
+            }
+            const message = str(flags.message);
+            if (!message) {
+                throw new Error("report-anomaly requires --message");
+            }
+            return reportAnomaly(config, {
+                kind,
+                severity,
+                message,
+                correlationId: str(flags["correlation-id"]),
+            });
+        }
+        default:
+            throw new Error(`Unknown command: ${command}`);
+    }
+}
+async function main() {
+    const { positionals, flags } = parseArgs(process.argv.slice(2));
+    const command = positionals[0];
+    if (!command || command === "help" || flags.help) {
+        process.stdout.write(`${USAGE}\n`);
+        return;
+    }
+    let config;
+    try {
+        config = resolveConfig();
+    }
+    catch (err) {
+        // Config error (e.g. missing key). Message names the env var, not its value.
+        process.stderr.write(`${err.message}\n`);
+        process.exitCode = 2;
+        return;
+    }
+    try {
+        const result = await dispatch(config, command, flags);
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    }
+    catch (err) {
+        if (err instanceof ApiError) {
+            const bodyText = typeof err.body === "string"
+                ? err.body
+                : JSON.stringify(err.body, null, 2);
+            process.stderr.write(`API error ${err.status}: ${bodyText}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        process.stderr.write(`${err.message}\n`);
+        process.exitCode = 1;
+    }
+}
+void main();
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Pure, testable HTTP client for the atrium /api/v1 surface.
+ *
+ * This module never imports anything from the Convex app — it only speaks HTTP.
+ * It reads two env vars:
+ *   - OPENCLAW_WEBCHAT_API_BASE : the deployment `.site` origin, WITHOUT the
+ *     `/api/v1` suffix (e.g. http://127.0.0.1:3213). The `/api/v1` prefix is
+ *     added here so tool/CLI call-sites stay clean (`apiFetch(cfg, "/traces")`).
+ *   - OPENCLAW_WEBCHAT_API_KEY  : the `oc_live_...` Bearer key.
+ *
+ * The API key is only ever placed in the `Authorization` header — never in a
+ * URL/query string and never logged.
+ */
+/** Default base origin for a local Convex deployment (.site origin). */
+export declare const DEFAULT_API_BASE = "http://127.0.0.1:3213";
+/** Path prefix for the observability API. Kept here so call-sites omit it. */
+export declare const API_PREFIX = "/api/v1";
+export interface Config {
+    /** Base origin (no trailing slash, no /api/v1). */
+    base: string;
+    /** The oc_live_ Bearer key. */
+    apiKey: string;
+}
+/** Minimal env shape so the resolver is injectable/testable. */
+export type Env = Record<string, string | undefined>;
+/**
+ * Structured error for any non-2xx response (or a fetch/transport failure).
+ * Carries the HTTP `status` and the parsed/raw `body` so callers can surface a
+ * clear message without re-reading the response. Never contains the API key.
+ */
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, body: unknown, message?: string);
+}
+/**
+ * Resolve config from an env bag (defaults to `process.env`). Throws a clear
+ * error naming the missing variable — without ever printing its value.
+ */
+export declare function resolveConfig(env?: Env): Config;
+/** Build the absolute URL for an API path (prepending `${base}/api/v1`). */
+export declare function buildUrl(base: string, path: string): string;
+/** Options for {@link apiFetch}. */
+export interface ApiFetchOptions {
+    /** Injected fetch implementation. Defaults to the global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Call the API at `path` (relative to `${base}/api/v1`), attaching the Bearer
+ * header, and parse the JSON response.
+ *
+ * - 2xx  -> returns the parsed JSON (or `null` for an empty body).
+ * - non-2xx -> throws {@link ApiError} with `{status, body}` (body parsed as
+ *   JSON when possible, otherwise the raw text).
+ * - transport failure -> throws {@link ApiError} with status 0.
+ *
+ * `fetch` is injectable for unit testing; no network call happens in tests.
+ */
+export declare function apiFetch<T = unknown>(config: Config, path: string, init?: RequestInit, options?: ApiFetchOptions): Promise<T>;

package/dist/config.js

@@ -0,0 +1,103 @@
+/**
+ * Pure, testable HTTP client for the atrium /api/v1 surface.
+ *
+ * This module never imports anything from the Convex app — it only speaks HTTP.
+ * It reads two env vars:
+ *   - OPENCLAW_WEBCHAT_API_BASE : the deployment `.site` origin, WITHOUT the
+ *     `/api/v1` suffix (e.g. http://127.0.0.1:3213). The `/api/v1` prefix is
+ *     added here so tool/CLI call-sites stay clean (`apiFetch(cfg, "/traces")`).
+ *   - OPENCLAW_WEBCHAT_API_KEY  : the `oc_live_...` Bearer key.
+ *
+ * The API key is only ever placed in the `Authorization` header — never in a
+ * URL/query string and never logged.
+ */
+/** Default base origin for a local Convex deployment (.site origin). */
+export const DEFAULT_API_BASE = "http://127.0.0.1:3213";
+/** Path prefix for the observability API. Kept here so call-sites omit it. */
+export const API_PREFIX = "/api/v1";
+/**
+ * Structured error for any non-2xx response (or a fetch/transport failure).
+ * Carries the HTTP `status` and the parsed/raw `body` so callers can surface a
+ * clear message without re-reading the response. Never contains the API key.
+ */
+export class ApiError extends Error {
+    status;
+    body;
+    constructor(status, body, message) {
+        super(message ?? `API request failed with status ${status}`);
+        this.name = "ApiError";
+        this.status = status;
+        this.body = body;
+    }
+}
+/**
+ * Resolve config from an env bag (defaults to `process.env`). Throws a clear
+ * error naming the missing variable — without ever printing its value.
+ */
+export function resolveConfig(env = process.env) {
+    const base = (env.OPENCLAW_WEBCHAT_API_BASE ?? DEFAULT_API_BASE).replace(/\/+$/, "");
+    const apiKey = env.OPENCLAW_WEBCHAT_API_KEY;
+    if (!apiKey) {
+        throw new Error("OPENCLAW_WEBCHAT_API_KEY is required (set it in the environment).");
+    }
+    return { base, apiKey };
+}
+/** Build the absolute URL for an API path (prepending `${base}/api/v1`). */
+export function buildUrl(base, path) {
+    const normalizedBase = base.replace(/\/+$/, "");
+    const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+    return `${normalizedBase}${API_PREFIX}${normalizedPath}`;
+}
+/**
+ * Call the API at `path` (relative to `${base}/api/v1`), attaching the Bearer
+ * header, and parse the JSON response.
+ *
+ * - 2xx  -> returns the parsed JSON (or `null` for an empty body).
+ * - non-2xx -> throws {@link ApiError} with `{status, body}` (body parsed as
+ *   JSON when possible, otherwise the raw text).
+ * - transport failure -> throws {@link ApiError} with status 0.
+ *
+ * `fetch` is injectable for unit testing; no network call happens in tests.
+ */
+export async function apiFetch(config, path, init = {}, options = {}) {
+    const doFetch = options.fetchImpl ?? globalThis.fetch;
+    if (typeof doFetch !== "function") {
+        throw new ApiError(0, null, "No fetch implementation available (Node >=18 or inject fetchImpl).");
+    }
+    const url = buildUrl(config.base, path);
+    const headers = new Headers(init.headers);
+    headers.set("Authorization", `Bearer ${config.apiKey}`);
+    headers.set("Accept", "application/json");
+    if (init.body !== undefined && !headers.has("Content-Type")) {
+        headers.set("Content-Type", "application/json");
+    }
+    let res;
+    try {
+        res = await doFetch(url, { ...init, headers });
+    }
+    catch (err) {
+        // Transport-level failure (DNS, connection refused, etc.). Surface it as a
+        // structured error with status 0 so callers handle it uniformly. Never
+        // include the request headers (which hold the key) in the message.
+        const message = err instanceof Error ? err.message : String(err);
+        throw new ApiError(0, null, `Network error reaching API: ${message}`);
+    }
+    const raw = await res.text();
+    const body = parseJsonSafe(raw);
+    if (!res.ok) {
+        throw new ApiError(res.status, body, `API ${res.status} ${res.statusText} for ${path}`);
+    }
+    return body;
+}
+/** Parse a string as JSON; fall back to the raw string when it isn't JSON. */
+function parseJsonSafe(raw) {
+    if (raw.length === 0)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return raw;
+    }
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,wEAAwE;AACxE,MAAM,CAAC,MAAM,gBAAgB,GAAG,uBAAuB,CAAC;AAExD,8EAA8E;AAC9E,MAAM,CAAC,MAAM,UAAU,GAAG,SAAS,CAAC;AAYpC;;;;GAIG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IACxB,MAAM,CAAS;IACf,IAAI,CAAU;IAEvB,YAAY,MAAc,EAAE,IAAa,EAAE,OAAgB;QACzD,KAAK,CAAC,OAAO,IAAI,kCAAkC,MAAM,EAAE,CAAC,CAAC;QAC7D,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,MAAW,OAAO,CAAC,GAAG;IAClD,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,yBAAyB,IAAI,gBAAgB,CAAC,CAAC,OAAO,CACtE,MAAM,EACN,EAAE,CACH,CAAC;IACF,MAAM,MAAM,GAAG,GAAG,CAAC,wBAAwB,CAAC;IAC5C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,mEAAmE,CACpE,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AAC1B,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,QAAQ,CAAC,IAAY,EAAE,IAAY;IACjD,MAAM,cAAc,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAChD,MAAM,cAAc,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC;IAChE,OAAO,GAAG,cAAc,GAAG,UAAU,GAAG,cAAc,EAAE,CAAC;AAC3D,CAAC;AAQD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,MAAc,EACd,IAAY,EACZ,OAAoB,EAAE,EACtB,UAA2B,EAAE;IAE7B,MAAM,OAAO,GAAG,OAAO,CAAC,SAAS,IAAI,UAAU,CAAC,KAAK,CAAC;IACtD,IAAI,OAAO,OAAO,KAAK,UAAU,EAAE,CAAC;QAClC,MAAM,IAAI,QAAQ,CAChB,CAAC,EACD,IAAI,EACJ,oEAAoE,CACrE,CAAC;IACJ,CAAC;IAED,MAAM,GAAG,GAAG,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACxC,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC1C,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,UAAU,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IACxD,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,kBAAkB,CAAC,CAAC;IAC1C,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,EAAE,CAAC;QAC5D,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,kBAAkB,CAAC,CAAC;IAClD,CAAC;IAED,IAAI,GAAa,CAAC;IAClB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;IACjD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,2EAA2E;QAC3E,uEAAuE;QACvE,mEAAmE;QACnE,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,MAAM,IAAI,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,+BAA+B,OAAO,EAAE,CAAC,CAAC;IACxE,CAAC;IAED,MAAM,GAAG,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;IAC7B,MAAM,IAAI,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;IAEhC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,MAAM,IAAI,QAAQ,CAChB,GAAG,CAAC,MAAM,EACV,IAAI,EACJ,OAAO,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,UAAU,QAAQ,IAAI,EAAE,CAClD,CAAC;IACJ,CAAC;IAED,OAAO,IAAS,CAAC;AACnB,CAAC;AAED,8EAA8E;AAC9E,SAAS,aAAa,CAAC,GAAW;IAChC,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAClC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,GAAG,CAAC;IACb,CAAC;AACH,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * atrium MCP server (stdio).
+ *
+ * A thin proxy over our /api/v1 observability surface. It carries an `oc_live_`
+ * Bearer key (from OPENCLAW_WEBCHAT_API_KEY) against the deployment `.site`
+ * origin (OPENCLAW_WEBCHAT_API_BASE) and exposes traces/KPIs/OpenClaw queries/
+ * anomalies as MCP tools for OpenClaw agents.
+ *
+ * It imports NOTHING from the Convex app — HTTP only. Each tool maps 1:1 to a
+ * permission enforced server-side (`requirePermission`), so a scoped key simply
+ * gets a 403 for tools it isn't allowed to call. A tool whose route is not yet
+ * deployed returns the API's response/error gracefully rather than crashing.
+ */
+export {};