Sidearm MCP Server

Instructions

Implementation Reference

• src/tools/get-billing.ts:5-59 (handler)

  Main implementation of the get_billing tool. Contains the tool registration, schema definition (Zod validation for account_id, start_date, end_date, type, tags), and the async handler function that calls the API and returns formatted results.

  export function register(server: McpServer, api: ApiClient): void {
    server.tool(
      "get_billing",
      "Get billing and usage events for your account. Returns credit consumption, " +
        "API call history, and a link to the Stripe customer portal. " +
        "Filter by date range, event type, or tags.",
      {
        account_id: z.string().describe("Your account UUID"),
        start_date: z
          .string()
          .optional()
          .describe("Filter events from this ISO 8601 date (inclusive)"),
        end_date: z
          .string()
          .optional()
          .describe("Filter events until this ISO 8601 date (inclusive)"),
        type: z
          .string()
          .optional()
          .describe("Filter by event type"),
        tags: z
          .string()
          .optional()
          .describe("Comma-separated tags to filter by"),
      },
      async (params) => {
        try {
          const result = await api.get(
            `/api/v1/billing/${encodeURIComponent(params.account_id)}`,
            {
              start_date: params.start_date,
              end_date: params.end_date,
              type: params.type,
              tags: params.tags,
            },
          );
          return {
            content: [
              { type: "text" as const, text: JSON.stringify(result, null, 2) },
            ],
          };
        } catch (err) {
          return {
            content: [
              {
                type: "text" as const,
                text: `Error: ${err instanceof Error ? err.message : String(err)}`,
              },
            ],
            isError: true as const,
          };
        }
      },
    );
  }

• src/tools/get-billing.ts:11-29 (schema)

  Input schema definition using Zod. Validates required account_id parameter and optional start_date, end_date, type, and tags filters for the billing query.

  {
    account_id: z.string().describe("Your account UUID"),
    start_date: z
      .string()
      .optional()
      .describe("Filter events from this ISO 8601 date (inclusive)"),
    end_date: z
      .string()
      .optional()
      .describe("Filter events until this ISO 8601 date (inclusive)"),
    type: z
      .string()
      .optional()
      .describe("Filter by event type"),
    tags: z
      .string()
      .optional()
      .describe("Comma-separated tags to filter by"),
  },

• src/index.ts:21-21 (registration)

  Import of the get_billing tool registration function from ./tools/get-billing.js

  import { register as getBilling } from "./tools/get-billing.js";

• src/index.ts:67-67 (registration)

  Registration call that initializes the get_billing tool with the MCP server and API client instance

  getBilling(server, api);

• src/api.ts:12-23 (helper)

  ApiClient.get() method used by the get_billing handler to make HTTP GET requests with query parameters and Bearer token authentication

  async get<T = unknown>(
    path: string,
    params?: Record<string, string | undefined>,
  ): Promise<T> {
    const url = new URL(`${this.baseUrl}${path}`);
    if (params) {
      for (const [k, v] of Object.entries(params)) {
        if (v !== undefined) url.searchParams.set(k, v);
      }
    }
    return this.request<T>(url, { method: "GET" });
  }