guardcmd-mcp 0.1.0

package/dist/client.js

@@ -0,0 +1,275 @@
+/**
+ * Thin HTTP client for the GuardCMD Cloud API (data plane).
+ *
+ * Talks to `API_BASE_URL` using the caller's `GUARDCMD_API_KEY`.
+ * Endpoints (see platform/CONTRACT.md):
+ *   - POST /v1/evaluate  -> decision
+ *   - GET  /v1/usage     -> plan/used/remaining
+ *
+ * Repository-scan control plane (account-scoped, same API key):
+ *   - GET  /v1/projects                       -> list projects
+ *   - POST /v1/projects                        -> create project
+ *   - POST /v1/projects/:id/scan-url          -> scan a PUBLIC GitHub repo by URL
+ *   - GET  /v1/scans/:id                        -> scan + counts
+ *   - GET  /v1/scans/:id/surfaces             -> surfaces for a scan
+ *   - GET  /v1/projects/:id/surfaces          -> surfaces for latest completed scan
+ *   - GET  /v1/surfaces/:id                     -> a single surface
+ *   - GET  /v1/surfaces/:id/recommendations   -> recommendations for a surface
+ *   - POST /v1/recommendations/:id/autofix    -> generate a PR-ready patch for a recommendation
+ *   - POST /v1/recommendations/:id/pull-request -> open a REAL GitHub PR for a recommendation
+ *
+ * Policy + decision control plane (account-scoped, same API key):
+ *   - GET   /v1/policies?projectId=            -> list policies
+ *   - GET   /v1/policies/:id                    -> policy + version history
+ *   - PATCH /v1/policies/:id                    -> update config (optimistic concurrency)
+ *   - POST  /v1/policies/:id/promote           -> promote to a target mode (shadow/live/...)
+ *   - POST  /v1/policies/:id/rollback          -> roll back to a prior version
+ *   - POST  /v1/policies                        -> create a policy
+ *   - GET   /v1/decisions?...                    -> list recent decisions (paginated)
+ *   - GET   /v1/decisions/:id                    -> a single decision (signals/reasons/policy/feedback)
+ *   - POST  /v1/decisions/:id/feedback         -> label a decision legitimate/abusive
+ *   - GET   /v1/metrics/summary?...             -> aggregate metrics for a window
+ *
+ * All API errors are normalized to `ApiError` carrying `{ error, code, status }`
+ * so callers can surface them as MCP tool errors without crashing.
+ */
+export class ApiError extends Error {
+    code;
+    status;
+    constructor(message, code, status) {
+        super(message);
+        this.name = "ApiError";
+        this.code = code;
+        this.status = status;
+    }
+}
+export class GuardCMDClient {
+    baseUrl;
+    apiKey;
+    fetchImpl;
+    timeoutMs;
+    constructor(opts) {
+        if (!opts.baseUrl)
+            throw new Error("API_BASE_URL is required");
+        if (!opts.apiKey)
+            throw new Error("GUARDCMD_API_KEY is required");
+        // Normalize: strip trailing slash so we can safely append paths.
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+        this.apiKey = opts.apiKey;
+        this.fetchImpl = opts.fetchImpl ?? fetch;
+        this.timeoutMs = opts.timeoutMs ?? 15000;
+    }
+    async evaluate(input) {
+        return this.request("POST", "/v1/evaluate", input);
+    }
+    /** POST /v1/guard/prompt: screen a prompt headed for an LLM. */
+    async screenPrompt(input) {
+        return this.request("POST", "/v1/guard/prompt", input);
+    }
+    /** POST /v1/guard/tool-call: evidence-based authorization for an agent tool call. */
+    async authorizeToolCall(input) {
+        return this.request("POST", "/v1/guard/tool-call", {
+            ...input,
+            args: input.args ?? null,
+        });
+    }
+    async usage() {
+        return this.request("GET", "/v1/usage");
+    }
+    // ---- Repository-scan control plane ----
+    /** GET /v1/projects — the account's projects. */
+    async listProjects() {
+        const res = await this.request("GET", "/v1/projects");
+        return res.projects ?? [];
+    }
+    /** POST /v1/projects — create a project. */
+    async createProject(name) {
+        return this.request("POST", "/v1/projects", { name });
+    }
+    /**
+     * POST /v1/projects/:id/scan-url — scan a PUBLIC GitHub repository by URL.
+     *
+     * This REPLACES the old `createScan(projectId, path)`, which posted a
+     * server-filesystem `path` to `POST /v1/projects/:id/scans`. That endpoint took its scan
+     * root straight from the request body, which made it an arbitrary-file-read primitive for
+     * anyone holding a key (scan a host directory, then read whole file contents back out
+     * through the autofix endpoint). The API now answers it with
+     * 501 `local_path_scans_disabled` unless a development-only switch is set, so a client
+     * method for it would only ever produce an error.
+     *
+     * The server clones the repo itself into a disposable sandbox — the caller never names a
+     * path. Synchronous MVP: the response is already a terminal Scan (`completed` or
+     * `failed`). A malformed URL is 400 `invalid_github_url`; a private/missing repo is
+     * 422 `repo_unavailable`. Both arrive as {@link ApiError} with `code` intact.
+     */
+    async scanUrl(projectId, url) {
+        return this.request("POST", `/v1/projects/${encodeURIComponent(projectId)}/scan-url`, { url });
+    }
+    /** GET /v1/scans/:id — a scan plus surface/recommendation counts. */
+    async getScan(scanId) {
+        return this.request("GET", `/v1/scans/${encodeURIComponent(scanId)}`);
+    }
+    /** GET /v1/projects/:id/surfaces — surfaces from the latest completed scan. */
+    async listProjectSurfaces(projectId) {
+        const res = await this.request("GET", `/v1/projects/${encodeURIComponent(projectId)}/surfaces`);
+        return res.surfaces ?? [];
+    }
+    /** GET /v1/scans/:id/surfaces — surfaces discovered by a specific scan. */
+    async listScanSurfaces(scanId) {
+        const res = await this.request("GET", `/v1/scans/${encodeURIComponent(scanId)}/surfaces`);
+        return res.surfaces ?? [];
+    }
+    /** GET /v1/surfaces/:id — a single surface. */
+    async getSurface(surfaceId) {
+        return this.request("GET", `/v1/surfaces/${encodeURIComponent(surfaceId)}`);
+    }
+    /** GET /v1/surfaces/:id/recommendations — hardening recommendations. */
+    async listSurfaceRecommendations(surfaceId) {
+        const res = await this.request("GET", `/v1/surfaces/${encodeURIComponent(surfaceId)}/recommendations`);
+        return res.recommendations ?? [];
+    }
+    /**
+     * POST /v1/recommendations/:id/autofix — generate a PR-ready patch/diff for a recommendation.
+     * The server re-scans the recommendation's source checkout and returns a review-only patch;
+     * it does not write files or open a real PR.
+     */
+    async generateAutofix(recommendationId) {
+        const res = await this.request("POST", `/v1/recommendations/${encodeURIComponent(recommendationId)}/autofix`);
+        return res.autofix;
+    }
+    /**
+     * POST /v1/recommendations/:id/pull-request — open a REAL GitHub pull request for a
+     * recommendation. The server re-scans a sandboxed checkout of the project's linked repo,
+     * generates + VALIDATES the patch, and only then opens the PR. Returns the opened PR
+     * (number, url, headBranch) plus a compact autofix summary. Requires a linked GitHub repo
+     * (else 409) and a configured GitHub App (else 501).
+     */
+    async openPullRequest(recommendationId, ref) {
+        return this.request("POST", `/v1/recommendations/${encodeURIComponent(recommendationId)}/pull-request`, ref ? { ref } : {});
+    }
+    // ---- Policy control plane ----
+    /** GET /v1/policies?projectId= — the account's policies (optionally scoped to a project). */
+    async listPolicies(projectId) {
+        const qs = projectId ? `?projectId=${encodeURIComponent(projectId)}` : "";
+        const res = await this.request("GET", `/v1/policies${qs}`);
+        return res.policies ?? [];
+    }
+    /** GET /v1/policies/:id — a policy plus its version history. */
+    async getPolicy(policyId) {
+        return this.request("GET", `/v1/policies/${encodeURIComponent(policyId)}`);
+    }
+    /**
+     * PATCH /v1/policies/:id — update a policy's config with optimistic concurrency.
+     * `baseVersion` must match the current version or the API returns 409 (stale).
+     * Produces a new draft/shadow version; it does not enforce by itself.
+     */
+    async updatePolicy(policyId, body) {
+        return this.request("PATCH", `/v1/policies/${encodeURIComponent(policyId)}`, body);
+    }
+    /**
+     * POST /v1/policies/:id/promote — promote a policy to `targetMode`. Promoting to `live`
+     * REQUIRES `acknowledgeUserImpact: true` (the API returns 422 without it).
+     */
+    async promotePolicy(policyId, body) {
+        return this.request("POST", `/v1/policies/${encodeURIComponent(policyId)}/promote`, body);
+    }
+    /** POST /v1/policies/:id/rollback — roll a policy back to a prior version (default: previous). */
+    async rollbackPolicy(policyId, body = {}) {
+        return this.request("POST", `/v1/policies/${encodeURIComponent(policyId)}/rollback`, body);
+    }
+    /** POST /v1/policies — create a policy (from a recommendation, or from scratch). */
+    async createPolicy(body) {
+        return this.request("POST", "/v1/policies", body);
+    }
+    // ---- Decision control plane ----
+    /** GET /v1/decisions — recent decisions (paginated via nextCursor). */
+    async listDecisions(filters = {}) {
+        const params = new URLSearchParams();
+        if (filters.projectId)
+            params.set("projectId", filters.projectId);
+        if (filters.action)
+            params.set("action", filters.action);
+        if (filters.mode)
+            params.set("mode", filters.mode);
+        if (filters.enforced !== undefined)
+            params.set("enforced", String(filters.enforced));
+        if (filters.limit !== undefined)
+            params.set("limit", String(filters.limit));
+        if (filters.cursor)
+            params.set("cursor", filters.cursor);
+        const qs = params.toString();
+        return this.request("GET", `/v1/decisions${qs ? `?${qs}` : ""}`);
+    }
+    /** GET /v1/decisions/:id — a full decision (signals, reasons, policy, feedback). */
+    async getDecision(decisionId) {
+        return this.request("GET", `/v1/decisions/${encodeURIComponent(decisionId)}`);
+    }
+    /** POST /v1/decisions/:id/feedback — label a decision `legitimate` or `abusive`. */
+    async submitFeedback(decisionId, label) {
+        return this.request("POST", `/v1/decisions/${encodeURIComponent(decisionId)}/feedback`, { label });
+    }
+    /** GET /v1/metrics/summary — aggregate metrics for a project/window. */
+    async getMetrics(opts = {}) {
+        const params = new URLSearchParams();
+        if (opts.projectId)
+            params.set("projectId", opts.projectId);
+        if (opts.window)
+            params.set("window", opts.window);
+        const qs = params.toString();
+        return this.request("GET", `/v1/metrics/summary${qs ? `?${qs}` : ""}`);
+    }
+    async request(method, path, body) {
+        const url = `${this.baseUrl}${path}`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        let res;
+        try {
+            res = await this.fetchImpl(url, {
+                method,
+                headers: {
+                    // Contract accepts either scheme; send both to be robust.
+                    Authorization: `Bearer ${this.apiKey}`,
+                    "x-api-key": this.apiKey,
+                    "content-type": "application/json",
+                    accept: "application/json",
+                },
+                body: body === undefined ? undefined : JSON.stringify(body),
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            clearTimeout(timer);
+            const msg = err instanceof Error && err.name === "AbortError"
+                ? `Request to ${url} timed out after ${this.timeoutMs}ms`
+                : `Network error calling ${url}: ${err.message}`;
+            throw new ApiError(msg, "network_error", 0);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const text = await res.text();
+        let parsed = undefined;
+        if (text) {
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                parsed = undefined;
+            }
+        }
+        if (!res.ok) {
+            const errBody = parsed;
+            const code = errBody?.code ?? `http_${res.status}`;
+            const message = errBody?.error ??
+                (text ? text.slice(0, 500) : `HTTP ${res.status} ${res.statusText}`);
+            throw new ApiError(message, code, res.status);
+        }
+        if (parsed === undefined) {
+            throw new ApiError(`Invalid JSON response from ${url}`, "invalid_response", res.status);
+        }
+        return parsed;
+    }
+}
+/** @deprecated use {@link GuardCMDClient} (the product was formerly AbuseGuard). */
+export const AbuseGuardClient = GuardCMDClient;
+//# sourceMappingURL=client.js.map

package/dist/server.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared MCP server factory for GuardCMD Cloud.
+ *
+ * Builds an `McpServer` and registers the two tools defined by the MCP contract
+ * (platform/CONTRACT.md):
+ *   - `check_abuse` — mirrors POST /v1/evaluate, returns the decision.
+ *   - `get_usage`   — mirrors GET /v1/usage, returns plan/used/remaining.
+ *
+ * Both the stdio and HTTP entrypoints call `createServer()` so behavior is identical
+ * across transports.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { GuardCMDClient, type GuardCMDClientOptions } from "./client.js";
+export interface CreateServerOptions {
+    /** Public API origin, e.g. https://api.guardcmd.com (env: API_BASE_URL). */
+    baseUrl?: string;
+    /** Caller's API key (env: GUARDCMD_API_KEY). */
+    apiKey?: string;
+    /** Pre-built client (used by tests). Overrides baseUrl/apiKey if provided. */
+    client?: GuardCMDClient;
+    /** Passthrough for the underlying client (custom fetch, timeout). */
+    clientOptions?: Partial<Pick<GuardCMDClientOptions, "fetchImpl" | "timeoutMs">>;
+}
+/** Public GuardCMD API origin used when no base URL is configured. */
+export declare const DEFAULT_API_BASE_URL = "https://api.guardcmd.com";
+/** Resolve config from options, falling back to env vars with the exact contract names. */
+export declare function resolveConfig(opts?: CreateServerOptions): {
+    baseUrl: string;
+    apiKey: string;
+};
+/**
+ * Create a fully-configured GuardCMD MCP server (tools registered).
+ * Throws if neither options nor env provide baseUrl + apiKey (and no client given).
+ */
+export declare function createServer(opts?: CreateServerOptions): McpServer;