guardcmd-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sahil Baligar
+
+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,79 @@
+# guardcmd-mcp
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server for
+[GuardCMD](https://guardcmd.ai). It lets Claude Code, Cursor, and your own AI
+apps check actions for abuse, screen prompts, authorize agent tool calls, and
+manage GuardCMD projects and policies.
+
+It runs locally over stdio with **your own** GuardCMD API key and calls the
+GuardCMD API. Requires Node.js 20 or newer.
+
+## Setup
+
+Create an API key at [guardcmd.ai](https://guardcmd.ai), then:
+
+**Claude Code**
+
+```bash
+claude mcp add guardcmd -e GUARDCMD_API_KEY=ag_live_... -- npx -y guardcmd-mcp
+```
+
+**Cursor, Claude Desktop, and other clients** (`mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "guardcmd": {
+      "command": "npx",
+      "args": ["-y", "guardcmd-mcp"],
+      "env": { "GUARDCMD_API_KEY": "ag_live_..." }
+    }
+  }
+}
+```
+
+| Environment variable | Required | Purpose |
+| --- | --- | --- |
+| `GUARDCMD_API_KEY` | yes | Your GuardCMD API key |
+| `API_BASE_URL` | no | API origin (default `https://api.guardcmd.com`) |
+
+The key grants the same access as your dashboard key. Keep it out of shared
+config files and version control.
+
+## Tools
+
+**Runtime checks**
+
+- `check_abuse`: score an action (signup, login, checkout, ...) and get
+  `allow | challenge | throttle | review | block` with reasons.
+- `screen_prompt`: screen a prompt for injection, data exfiltration, cost
+  abuse, and harmful requests.
+- `authorize_tool_call`: before an agent runs a tool, get
+  `allow | require_approval | deny` based on the call, the user's intent, and
+  untrusted context.
+
+**Projects and findings**
+
+- `list_projects`, `get_usage`
+- `scan_repository`, `create_scan`, `get_scan`: map abuse surfaces in a repo
+- `list_abuse_surfaces`, `list_recommendations`
+- `create_protection_pr`: preview a protection patch, or open a pull request
+  when called with `openPr: true`
+
+**Policies and decisions**
+
+- `list_policies`, `get_policy`, `set_rate_limit`
+- `promote_policy` (requires `acknowledgeUserImpact: true`), `rollback_policy`
+- `list_decisions`, `explain_decision`, `submit_feedback`, `get_metrics`
+
+Tools that change state are labeled in their descriptions. Your MCP client
+asks before calling them unless you have allowed them.
+
+## Renamed from AbuseGuard
+
+The `abuseguard-mcp` binary and the `ABUSEGUARD_API_KEY` variable still work
+as deprecated aliases.
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,426 @@
+/**
+ * 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.
+ */
+/** Shape of the structured API error body per CONTRACT.md ("All errors: { error, code }"). */
+export interface ApiErrorBody {
+    error: string;
+    code: string;
+}
+export declare class ApiError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(message: string, code: string, status: number);
+}
+/** Input to POST /v1/evaluate (mirrors the API body; `action` required, rest optional). */
+export interface EvaluateInput {
+    action: string;
+    actorId?: string;
+    ip?: string;
+    email?: string;
+    fingerprint?: string;
+    userAgent?: string;
+    content?: string;
+    meta?: Record<string, unknown>;
+    timestamp?: string;
+}
+/** A single contributing signal in a decision. */
+export interface DecisionSignal {
+    signal: string;
+    score: number;
+    reasons: string[];
+    data?: unknown;
+}
+/** Decision returned by POST /v1/evaluate. */
+export interface EvaluateDecision {
+    action: "allow" | "challenge" | "throttle" | "review" | "block";
+    score: number;
+    flagged: boolean;
+    enforced: boolean;
+    reasons: string[];
+    signals: DecisionSignal[];
+    requestId: string;
+}
+/** Input to POST /v1/guard/prompt (TypeSafe-backed prompt screening). */
+export interface ScreenPromptInput {
+    prompt: string;
+    purpose?: string;
+    context?: Record<string, unknown>;
+    actorId?: string;
+    projectId?: string;
+    environment?: string;
+}
+/** Result of POST /v1/guard/prompt. */
+export interface ScreenPromptResult {
+    id: string | null;
+    decision: "allow" | "review" | "block";
+    score: number;
+    reasons: string[];
+    signals: Record<string, number>;
+    degraded: boolean;
+    latencyMs: number;
+}
+/** Input to POST /v1/guard/tool-call (agent tool-call authorization evidence). */
+export interface AuthorizeToolCallInput {
+    tool: {
+        name: string;
+        mutating: boolean;
+        description?: string;
+    };
+    args?: unknown;
+    userIntent?: string;
+    untrustedContext?: string;
+    actorId?: string;
+    projectId?: string;
+    environment?: string;
+}
+/** Result of POST /v1/guard/tool-call. */
+export interface AuthorizeToolCallResult {
+    id: string | null;
+    decision: "allow" | "require_approval" | "deny";
+    reasons: string[];
+    evidence: Record<string, unknown>;
+    degraded: boolean;
+    latencyMs: number;
+}
+/** Usage returned by GET /v1/usage. */
+export interface UsageResult {
+    plan: string;
+    periodStart?: string;
+    periodEnd?: string;
+    used: number;
+    limit: number | null;
+    remaining: number | null;
+}
+/** A project — a container for scans of a single repository/app. */
+export interface Project {
+    id: string;
+    name: string;
+    defaultEnvironment?: string;
+    createdAt?: string;
+}
+/** A single evidence item attached to a surface (e.g. a matched call site). */
+export interface SurfaceEvidence {
+    kind: string;
+    [key: string]: unknown;
+}
+/** A scan of a repository checkout the server created (see {@link GuardCMDClient.scanUrl}). */
+export interface Scan {
+    id: string;
+    projectId: string;
+    status: string;
+    scannerVersion?: string;
+    stats?: Record<string, unknown>;
+    warnings?: string[];
+    error?: string | null;
+    /** Present on GET /v1/scans/:id. */
+    surfaceCount?: number;
+    recommendationCount?: number;
+    [key: string]: unknown;
+}
+/** An abuse surface discovered by a scan (an endpoint/action that can be abused). */
+export interface Surface {
+    id: string;
+    surfaceKey: string;
+    route?: string;
+    method?: string;
+    action?: string;
+    surfaceType?: string;
+    exposure?: string;
+    abuseClasses?: string[];
+    confidence?: number;
+    impact?: string;
+    priority?: string;
+    priorityScore?: number;
+    evidence?: SurfaceEvidence[];
+    [key: string]: unknown;
+}
+/** A hardening recommendation for a surface. */
+export interface Recommendation {
+    id: string;
+    title: string;
+    summary?: string;
+    suggestedPolicy?: unknown;
+    controls?: unknown;
+    priority?: string;
+    priorityScore?: number;
+    status?: string;
+    [key: string]: unknown;
+}
+/** A whole-file change in an autofix: the file's full text before and after the edit. */
+export interface FileEdit {
+    path: string;
+    before: string;
+    after: string;
+}
+/**
+ * The generated patch for a recommendation (POST /v1/recommendations/:id/autofix). It's a
+ * review-only artifact — a unified diff, per-file before/after edits, and the `.env` keys the
+ * integration needs. It never writes files or opens a PR.
+ */
+export interface AutofixResult {
+    surfaceId: string;
+    recommendationId: string;
+    edits: FileEdit[];
+    /** A unified diff across all edits, PR-ready. */
+    diff: string;
+    /** Env keys the integration needs, e.g. `["GUARDCMD_API_KEY=", "GUARDCMD_PROJECT_ID="]`. */
+    envAdditions: string[];
+    /** True iff every edited code file re-parses cleanly AND contains the inserted guard call. */
+    valid: boolean;
+    /** Non-fatal problems (e.g. "could not locate handler body"); empty on a clean result. */
+    warnings: string[];
+    /** Count of added lines across all edits. */
+    estimatedChangedLines: number;
+    [key: string]: unknown;
+}
+/** A real GitHub pull request opened for a recommendation (POST /v1/recommendations/:id/pull-request). */
+export interface PullRequestResult {
+    number: number;
+    /** The PR's html_url. */
+    url: string;
+    /** The head branch the PR was opened from. */
+    headBranch: string;
+}
+/** Response of the open-PR endpoint: the opened PR plus a compact autofix summary. */
+export interface OpenPullRequestResponse {
+    pullRequest: PullRequestResult;
+    autofix: {
+        valid: boolean;
+        estimatedChangedLines: number;
+        diff: string;
+    };
+}
+/** A single entry in a policy's version history. */
+export interface PolicyVersion {
+    version: number;
+    mode?: string;
+    note?: string;
+    createdAt?: string;
+    config?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/** An anti-abuse policy for a project/action. */
+export interface Policy {
+    id: string;
+    projectId?: string;
+    action?: string;
+    mode?: string;
+    version?: number;
+    config?: Record<string, unknown>;
+    versions?: PolicyVersion[];
+    createdAt?: string;
+    updatedAt?: string;
+    [key: string]: unknown;
+}
+/** A single velocity/rate limit for a policy. */
+export interface RateLimit {
+    dimension: string;
+    limit: number;
+    windowSeconds: number;
+}
+/** Body for PATCH /v1/policies/:id (optimistic concurrency via baseVersion). */
+export interface UpdatePolicyBody {
+    baseVersion: number;
+    config?: Record<string, unknown>;
+    note?: string;
+}
+/** Body for POST /v1/policies/:id/promote. */
+export interface PromotePolicyBody {
+    targetMode: string;
+    acknowledgeUserImpact?: boolean;
+}
+/** Body for POST /v1/policies/:id/rollback. */
+export interface RollbackPolicyBody {
+    toVersion?: number;
+}
+/** Body for POST /v1/policies — either adopt a recommendation, or create from scratch. */
+export type CreatePolicyBody = {
+    recommendationId: string;
+} | {
+    projectId: string;
+    action: string;
+    config: Record<string, unknown>;
+    mode?: string;
+};
+/** Filters for GET /v1/decisions. */
+export interface DecisionFilters {
+    projectId?: string;
+    action?: string;
+    mode?: string;
+    enforced?: boolean;
+    limit?: number;
+    cursor?: string;
+}
+/** A compact decision row in a decision list. */
+export interface DecisionSummary {
+    id: string;
+    action?: string;
+    outcome?: string;
+    score?: number;
+    mode?: string;
+    enforced?: boolean;
+    createdAt?: string;
+    [key: string]: unknown;
+}
+/** Response of GET /v1/decisions. */
+export interface DecisionList {
+    decisions: DecisionSummary[];
+    nextCursor?: string | null;
+}
+/** A full decision (GET /v1/decisions/:id): signals, reasons, policy, feedback. */
+export interface Decision {
+    id: string;
+    action?: string;
+    outcome?: string;
+    score?: number;
+    mode?: string;
+    enforced?: boolean;
+    reasons?: string[];
+    signals?: DecisionSignal[];
+    policy?: Record<string, unknown> | null;
+    feedback?: {
+        label?: string;
+        [key: string]: unknown;
+    } | null;
+    createdAt?: string;
+    [key: string]: unknown;
+}
+/** Aggregate metrics (GET /v1/metrics/summary). */
+export interface MetricsSummary {
+    projectId?: string;
+    window?: string;
+    [key: string]: unknown;
+}
+export interface GuardCMDClientOptions {
+    baseUrl: string;
+    apiKey: string;
+    /** Optional custom fetch (used by tests). Defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+    /** Request timeout in ms (default 15000). */
+    timeoutMs?: number;
+}
+export declare class GuardCMDClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    constructor(opts: GuardCMDClientOptions);
+    evaluate(input: EvaluateInput): Promise<EvaluateDecision>;
+    /** POST /v1/guard/prompt: screen a prompt headed for an LLM. */
+    screenPrompt(input: ScreenPromptInput): Promise<ScreenPromptResult>;
+    /** POST /v1/guard/tool-call: evidence-based authorization for an agent tool call. */
+    authorizeToolCall(input: AuthorizeToolCallInput): Promise<AuthorizeToolCallResult>;
+    usage(): Promise<UsageResult>;
+    /** GET /v1/projects — the account's projects. */
+    listProjects(): Promise<Project[]>;
+    /** POST /v1/projects — create a project. */
+    createProject(name: string): Promise<Project>;
+    /**
+     * 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.
+     */
+    scanUrl(projectId: string, url: string): Promise<Scan>;
+    /** GET /v1/scans/:id — a scan plus surface/recommendation counts. */
+    getScan(scanId: string): Promise<Scan>;
+    /** GET /v1/projects/:id/surfaces — surfaces from the latest completed scan. */
+    listProjectSurfaces(projectId: string): Promise<Surface[]>;
+    /** GET /v1/scans/:id/surfaces — surfaces discovered by a specific scan. */
+    listScanSurfaces(scanId: string): Promise<Surface[]>;
+    /** GET /v1/surfaces/:id — a single surface. */
+    getSurface(surfaceId: string): Promise<Surface>;
+    /** GET /v1/surfaces/:id/recommendations — hardening recommendations. */
+    listSurfaceRecommendations(surfaceId: string): Promise<Recommendation[]>;
+    /**
+     * 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.
+     */
+    generateAutofix(recommendationId: string): Promise<AutofixResult>;
+    /**
+     * 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).
+     */
+    openPullRequest(recommendationId: string, ref?: string): Promise<OpenPullRequestResponse>;
+    /** GET /v1/policies?projectId= — the account's policies (optionally scoped to a project). */
+    listPolicies(projectId?: string): Promise<Policy[]>;
+    /** GET /v1/policies/:id — a policy plus its version history. */
+    getPolicy(policyId: string): Promise<Policy>;
+    /**
+     * 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.
+     */
+    updatePolicy(policyId: string, body: UpdatePolicyBody): Promise<Policy>;
+    /**
+     * POST /v1/policies/:id/promote — promote a policy to `targetMode`. Promoting to `live`
+     * REQUIRES `acknowledgeUserImpact: true` (the API returns 422 without it).
+     */
+    promotePolicy(policyId: string, body: PromotePolicyBody): Promise<Policy>;
+    /** POST /v1/policies/:id/rollback — roll a policy back to a prior version (default: previous). */
+    rollbackPolicy(policyId: string, body?: RollbackPolicyBody): Promise<Policy>;
+    /** POST /v1/policies — create a policy (from a recommendation, or from scratch). */
+    createPolicy(body: CreatePolicyBody): Promise<Policy>;
+    /** GET /v1/decisions — recent decisions (paginated via nextCursor). */
+    listDecisions(filters?: DecisionFilters): Promise<DecisionList>;
+    /** GET /v1/decisions/:id — a full decision (signals, reasons, policy, feedback). */
+    getDecision(decisionId: string): Promise<Decision>;
+    /** POST /v1/decisions/:id/feedback — label a decision `legitimate` or `abusive`. */
+    submitFeedback(decisionId: string, label: "legitimate" | "abusive"): Promise<Decision>;
+    /** GET /v1/metrics/summary — aggregate metrics for a project/window. */
+    getMetrics(opts?: {
+        projectId?: string;
+        window?: string;
+    }): Promise<MetricsSummary>;
+    private request;
+}
+/** @deprecated use {@link GuardCMDClient} (the product was formerly AbuseGuard). */
+export declare const AbuseGuardClient: typeof GuardCMDClient;
+/** @deprecated use {@link GuardCMDClient}. */
+export type AbuseGuardClient = GuardCMDClient;