volthq-mcp-server

Instructions

Implementation Reference

• packages/mcp-server/src/tools/get-spend.ts:21-43 (handler)

  The logic handler for the volt_get_spend tool.

  export function handleGetSpend(input: GetSpendInput, tracker: SpendTracker) {
    const summary = tracker.getSummary(input.time_range);
  
    if (summary.totalCalls === 0) {
      return {
        content: [
          {
            type: 'text' as const,
            text: `No inference calls recorded for ${input.time_range}. Spend data is collected as you use AI providers.`,
          },
        ],
      };
    }
  
    return {
      content: [
        {
          type: 'text' as const,
          text: formatSpendSummary(summary),
        },
      ],
    };
  }

• packages/mcp-server/src/tools/get-spend.ts:12-17 (schema)

  Input validation schema for volt_get_spend.

  export const getSpendSchema = z.object({
    time_range: z
      .enum(['today', '7d', '30d'])
      .default('today')
      .describe('Time range for the summary: today, 7d (7 days), or 30d (30 days)'),
  });

• packages/mcp-server/src/index.ts:163-168 (registration)

  Tool registration for volt_get_spend in the MCP server.

  server.tool(
    'volt_get_spend',
    'Get spending summary by provider and model for today, 7 days, or 30 days.',
    getSpendSchema.shape,
    async (input) => maybeAddFirstRun(handleGetSpend(getSpendSchema.parse(input), spendTracker)),
  );

• packages/mcp-server/src/tools/get-spend.ts:45-74 (helper)

  Helper function to format the spending summary text for the tool output.

  function formatSpendSummary(s: SpendSummary): string {
    const lines: string[] = [
      `Spend Summary (${s.timeRange})`,
      '─'.repeat(60),
      `Total spend: $${s.totalSpend.toFixed(2)}`,
      `Total calls: ${s.totalCalls}`,
      `Avg cost/call: $${s.averageCostPerCall.toFixed(4)}`,
      `Tokens: ${s.totalTokensInput.toLocaleString()} input / ${s.totalTokensOutput.toLocaleString()} output`,
    ];
  
    const providerEntries = Object.entries(s.byProvider).sort((a, b) => b[1] - a[1]);
    if (providerEntries.length > 0) {
      lines.push('', 'By Provider:');
      for (const [provider, cost] of providerEntries) {
        const pct = s.totalSpend > 0 ? Math.round((cost / s.totalSpend) * 100) : 0;
        lines.push(`  ${provider}: $${cost.toFixed(2)} (${pct}%)`);
      }
    }
  
    const modelEntries = Object.entries(s.byModel).sort((a, b) => b[1] - a[1]);
    if (modelEntries.length > 0) {
      lines.push('', 'By Model:');
      for (const [model, cost] of modelEntries) {
        const pct = s.totalSpend > 0 ? Math.round((cost / s.totalSpend) * 100) : 0;
        lines.push(`  ${model}: $${cost.toFixed(2)} (${pct}%)`);
      }
    }
  
    return lines.join('\n');
  }