govrider-mcp-server

Instructions

Implementation Reference

• src/index.ts:271-299 (handler)

  The main handler function for check_credits tool. Makes a GET API call to /api/v1/credits, handles errors, and returns formatted credit balance information including credits remaining, database size, and pricing details.

    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 (full AI analysis, match scores, URLs)',
            '- Buy credits: https://govrider.ai/pricing',
          ].join('\n'),
        }],
      }
    },
  )

• src/index.ts:264-270 (registration)

  Tool registration for check_credits with the MCP server. Defines the tool name, description, and empty inputSchema (no parameters required).

  server.registerTool(
    'check_credits',
    {
      description:
        'Check your GovRider credit balance. Each enriched search costs 1 credit. Discovery search is free.',
      inputSchema: {},
    },

• src/index.ts:43-69 (helper)

  apiCall helper function that makes HTTP requests to the GovRider API with Bearer token authentication. Used by the check_credits handler to fetch credit balance.

  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:71-77 (helper)

  errorText helper function that formats error messages based on HTTP status codes (401 for auth errors, 402 for no credits, 429 for rate limits). Used by the check_credits handler for error responses.

  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}`
  }