check_credits

Instructions

Implementation Reference

• src/index.ts:302-338 (registration)

  Registration of the 'check_credits' tool with the MCP server, including its input schema (empty) and handler function.

  server.registerTool(
    'check_credits',
    {
      description:
        'Check your GovRider credit balance. Each enriched search costs 1 credit. Discovery search and opportunity details are free.',
      inputSchema: {},
    },
    async () => {
      const { ok, status, data } = await apiCall('/api/v1/credits', undefined, 'GET')
  
      if (!ok) {
        return {
          content: [{ type: 'text' as const, text: errorText(data, status) }],
          isError: true,
        }
      }
  
      const credits = data.credits as number
      const totalScanned = data.total_scanned as number
  
      return {
        content: [{
          type: 'text' as const,
          text: [
            `Credits remaining: ${credits}`,
            `Database: ${totalScanned?.toLocaleString() ?? '?'} active opportunities indexed`,
            '',
            'Pricing:',
            '- search_opportunities: FREE (sector + metadata only)',
            '- search_enriched: 1 credit (compact ranked summary of 10 matches)',
            '- get_opportunity: FREE (full details for any match from last search)',
            '- Buy credits: https://govrider.ai/pricing',
          ].join('\n'),
        }],
      }
    },
  )

• src/index.ts:309-337 (handler)

  Handler function for check_credits: calls GET /api/v1/credits via apiCall, returns remaining credits and total scanned opportunities, along with pricing info.

  async () => {
    const { ok, status, data } = await apiCall('/api/v1/credits', undefined, 'GET')
  
    if (!ok) {
      return {
        content: [{ type: 'text' as const, text: errorText(data, status) }],
        isError: true,
      }
    }
  
    const credits = data.credits as number
    const totalScanned = data.total_scanned as number
  
    return {
      content: [{
        type: 'text' as const,
        text: [
          `Credits remaining: ${credits}`,
          `Database: ${totalScanned?.toLocaleString() ?? '?'} active opportunities indexed`,
          '',
          'Pricing:',
          '- search_opportunities: FREE (sector + metadata only)',
          '- search_enriched: 1 credit (compact ranked summary of 10 matches)',
          '- get_opportunity: FREE (full details for any match from last search)',
          '- Buy credits: https://govrider.ai/pricing',
        ].join('\n'),
      }],
    }
  },

• src/index.ts:304-307 (schema)

  Input schema for check_credits — empty object since no parameters are needed.

  {
    description:
      'Check your GovRider credit balance. Each enriched search costs 1 credit. Discovery search and opportunity details are free.',
    inputSchema: {},

• src/index.ts:52-78 (helper)

  apiCall helper used by the check_credits handler to make the GET request to /api/v1/credits.

  async function apiCall(
    path: string,
    body?: Record<string, unknown>,
    method: 'GET' | 'POST' = 'POST',
  ): Promise<{
    ok: boolean
    status: number
    data: Record<string, unknown>
  }> {
    const res = await fetch(`${API_BASE}${path}`, {
      method,
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json',
      },
      ...(body ? { body: JSON.stringify(body) } : {}),
    })
  
    let data: Record<string, unknown>
    try {
      data = (await res.json()) as Record<string, unknown>
    } catch {
      data = { error: 'invalid_response', message: `Server returned ${res.status} with non-JSON body` }
    }
  
    return { ok: res.ok, status: res.status, data }
  }

• src/index.ts:80-86 (helper)

  errorText helper used by check_credits to format error messages for different HTTP status codes (401, 402, 429).

  function errorText(data: Record<string, unknown>, status: number): string {
    const msg = (data.message as string) ?? 'Unknown error'
    if (status === 401) return `Authentication failed: ${msg}. Check your GOVRIDER_API_KEY.`
    if (status === 402) return `No credits remaining. Purchase more at https://govrider.ai/pricing`
    if (status === 429) return `Rate limit exceeded. ${msg}`
    return `Error (${status}): ${msg}`
  }