check_budget

Instructions

Implementation Reference

• mcp-server/src/tools.ts:133-175 (handler)

  The 'check_budget' tool handler. It calls getUsage() and getCosts() in parallel via Promise.all, computes a usage percentage, classifies the status (critical/warning/healthy), and returns a JSON summary with plan, event usage, costs, and savings.

  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,
    );
  },

• mcp-server/src/index.ts:23-42 (registration)

  Registration loop that iterates over all tools (including 'check_budget') and registers each with the MCP server via server.tool().

  // Register each tool with the MCP server
  for (const tool of tools) {
    const shape = buildToolShape(tool.inputSchema.properties, tool.inputSchema.required ?? []);
  
    const toolName = tool.name;
    const handler = tool.handler;
  
    server.tool(toolName, tool.description, shape, async (args) => {
      try {
        const text = await handler(client, args as Record<string, unknown>);
        return { content: [{ type: "text" as const, text }] };
      } catch (err) {
        const message = err instanceof Error ? err.message : String(err);
        return {
          content: [{ type: "text" as const, text: `Error: ${message}` }],
          isError: true,
        };
      }
    });
  }

• mcp-server/src/tools.ts:137-140 (schema)

  Input schema for 'check_budget': an empty object (no parameters required).

  inputSchema: {
    type: "object",
    properties: {},
  },

• mcp-server/src/client.ts:59-77 (helper)

  The AgentGuardClient.getUsage() method that fetches /api/v1/usage for plan and event count/limit data.

  async getUsage() {
    return this.fetch<{
      plan: string;
      current_month: string;
      event_count: number;
      event_limit: number;
      retention_days: number;
      max_keys: number;
      max_users: number;
    }>("/api/v1/usage");
  }
  
  async getCosts() {
    return this.fetch<{
      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 };
    }>("/api/v1/costs");
  }

• mcp-server/src/client.ts:71-77 (helper)

  The AgentGuardClient.getCosts() method that fetches /api/v1/costs for monthly total cost, trace count, and savings data.

  async getCosts() {
    return this.fetch<{
      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 };
    }>("/api/v1/costs");
  }