@agentguard47/mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentGuard
+
+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/dist/client.d.ts

@@ -0,0 +1,49 @@
+export declare class AgentGuardClient {
+    private baseUrl;
+    private apiKey;
+    constructor();
+    private fetch;
+    getTraces(opts?: {
+        limit?: string;
+        offset?: string;
+        service?: string;
+        since?: string;
+        until?: string;
+    }): Promise<{
+        traces: unknown[];
+    }>;
+    getTrace(traceId: string): Promise<{
+        trace_id: string;
+        events: unknown[];
+    }>;
+    getAlerts(opts?: {
+        limit?: string;
+        since?: string;
+    }): Promise<{
+        alerts: unknown[];
+    }>;
+    getUsage(): Promise<{
+        plan: string;
+        current_month: string;
+        event_count: number;
+        event_limit: number;
+        retention_days: number;
+        max_keys: number;
+        max_users: number;
+    }>;
+    getCosts(): Promise<{
+        monthly: {
+            total_cost: number;
+            trace_count: number;
+        };
+        by_model: Array<{
+            model: string;
+            total_cost: number;
+            call_count: number;
+        }>;
+        savings: {
+            guard_events: number;
+            estimated_savings: number;
+        };
+    }>;
+}

package/dist/client.js

@@ -0,0 +1,46 @@
+const DEFAULT_URL = "https://agentguard.dev";
+export class AgentGuardClient {
+    baseUrl;
+    apiKey;
+    constructor() {
+        const apiKey = process.env.AGENTGUARD_API_KEY;
+        if (!apiKey) {
+            throw new Error("AGENTGUARD_API_KEY environment variable is required. " +
+                "Generate one at your AgentGuard dashboard under Settings > API Keys.");
+        }
+        this.apiKey = apiKey;
+        this.baseUrl = (process.env.AGENTGUARD_URL || DEFAULT_URL).replace(/\/$/, "");
+    }
+    async fetch(path, params) {
+        const url = new URL(`${this.baseUrl}${path}`);
+        if (params) {
+            for (const [key, value] of Object.entries(params)) {
+                if (value)
+                    url.searchParams.set(key, value);
+            }
+        }
+        const res = await fetch(url.toString(), {
+            headers: { Authorization: `Bearer ${this.apiKey}` },
+        });
+        if (!res.ok) {
+            const body = await res.text();
+            throw new Error(`AgentGuard API error (${res.status}): ${body}`);
+        }
+        return res.json();
+    }
+    async getTraces(opts) {
+        return this.fetch("/api/v1/traces", opts);
+    }
+    async getTrace(traceId) {
+        return this.fetch(`/api/v1/traces/${encodeURIComponent(traceId)}`);
+    }
+    async getAlerts(opts) {
+        return this.fetch("/api/v1/alerts", opts);
+    }
+    async getUsage() {
+        return this.fetch("/api/v1/usage");
+    }
+    async getCosts() {
+        return this.fetch("/api/v1/costs");
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { AgentGuardClient } from "./client.js";
+import { tools } from "./tools.js";
+const server = new McpServer({
+    name: "agentguard",
+    version: "0.1.0",
+});
+let client;
+try {
+    client = new AgentGuardClient();
+}
+catch (err) {
+    console.error(err.message);
+    process.exit(1);
+}
+// Register each tool with the MCP server
+for (const tool of tools) {
+    // Build a Zod schema from the JSON Schema properties
+    const shape = {};
+    const required = new Set(tool.inputSchema.required ?? []);
+    for (const [key, prop] of Object.entries(tool.inputSchema.properties)) {
+        const p = prop;
+        let field;
+        if (p.type === "number") {
+            field = z.number().describe(p.description ?? "");
+        }
+        else {
+            field = z.string().describe(p.description ?? "");
+        }
+        shape[key] = required.has(key) ? field : field.optional();
+    }
+    const toolName = tool.name;
+    const handler = tool.handler;
+    server.tool(toolName, tool.description, shape, async (args) => {
+        try {
+            const text = await handler(client, args);
+            return { content: [{ type: "text", text }] };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{ type: "text", text: `Error: ${message}` }],
+                isError: true,
+            };
+        }
+    });
+}
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("Fatal:", err);
+    process.exit(1);
+});

package/dist/tools.d.ts

@@ -0,0 +1,12 @@
+import { AgentGuardClient } from "./client.js";
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+    handler: (client: AgentGuardClient, args: Record<string, unknown>) => Promise<string>;
+}
+export declare const tools: ToolDefinition[];

package/dist/tools.js

@@ -0,0 +1,128 @@
+export const tools = [
+    {
+        name: "query_traces",
+        description: "Search recent traces from your AgentGuard-instrumented agents. " +
+            "Filter by service name, time range, or paginate through results.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                limit: { type: "number", description: "Max traces to return (default 20, max 500)" },
+                offset: { type: "number", description: "Offset for pagination" },
+                service: { type: "string", description: "Filter by service name" },
+                since: { type: "string", description: "ISO timestamp — only traces after this time" },
+                until: { type: "string", description: "ISO timestamp — only traces before this time" },
+            },
+        },
+        handler: async (client, args) => {
+            const result = await client.getTraces({
+                limit: args.limit ? String(args.limit) : "20",
+                offset: args.offset ? String(args.offset) : undefined,
+                service: args.service,
+                since: args.since,
+                until: args.until,
+            });
+            return JSON.stringify(result, null, 2);
+        },
+    },
+    {
+        name: "get_trace",
+        description: "Get the full event tree for a specific trace by its trace ID. " +
+            "Shows all spans, tool calls, LLM calls, guard triggers, and errors.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                trace_id: { type: "string", description: "The trace ID to look up" },
+            },
+            required: ["trace_id"],
+        },
+        handler: async (client, args) => {
+            const result = await client.getTrace(args.trace_id);
+            return JSON.stringify(result, null, 2);
+        },
+    },
+    {
+        name: "get_alerts",
+        description: "Get recent guard alerts (loop detection, budget exceeded) and errors. " +
+            "Useful for checking if your agents are hitting safety limits.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                limit: { type: "number", description: "Max alerts to return (default 50)" },
+                since: { type: "string", description: "ISO timestamp — only alerts after this time" },
+            },
+        },
+        handler: async (client, args) => {
+            const result = await client.getAlerts({
+                limit: args.limit ? String(args.limit) : undefined,
+                since: args.since,
+            });
+            return JSON.stringify(result, null, 2);
+        },
+    },
+    {
+        name: "get_usage",
+        description: "Check your current event quota usage and plan limits. " +
+            "Shows event count vs limit, retention period, and plan details.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+        handler: async (client) => {
+            const result = await client.getUsage();
+            const pct = result.event_limit > 0
+                ? ((result.event_count / result.event_limit) * 100).toFixed(1)
+                : "0";
+            return JSON.stringify({ ...result, usage_percent: `${pct}%` }, null, 2);
+        },
+    },
+    {
+        name: "get_costs",
+        description: "Get cost breakdown for the current month: total spend, cost by model, " +
+            "and estimated savings from guard interventions.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+        handler: async (client) => {
+            const result = await client.getCosts();
+            return JSON.stringify(result, null, 2);
+        },
+    },
+    {
+        name: "check_budget",
+        description: "Quick pass/fail budget health check. Combines usage quota and cost data " +
+            "to give a summary of whether you're within safe operating limits.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+        handler: async (client) => {
+            const [usage, costs] = await Promise.all([
+                client.getUsage(),
+                client.getCosts(),
+            ]);
+            const usagePct = usage.event_limit > 0
+                ? (usage.event_count / usage.event_limit) * 100
+                : 0;
+            const status = usagePct >= 90
+                ? "critical"
+                : usagePct >= 75
+                    ? "warning"
+                    : "healthy";
+            return JSON.stringify({
+                status,
+                plan: usage.plan,
+                events: {
+                    used: usage.event_count,
+                    limit: usage.event_limit,
+                    percent: `${usagePct.toFixed(1)}%`,
+                },
+                costs: {
+                    monthly_total: costs.monthly.total_cost,
+                    trace_count: costs.monthly.trace_count,
+                },
+                savings: costs.savings,
+            }, null, 2);
+        },
+    },
+];

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@agentguard47/mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for AgentGuard — query traces, alerts, usage, and costs from AI coding agents",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "agentguard-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.2",
+    "typescript": "^5.0.0"
+  }
+}