Frontrun MCP Server

Instructions

Implementation Reference

• index.js:377-393 (handler)

  Tool registration with schema and handler. The handler accepts optional 'since' and 'username' parameters, builds query string, calls the API endpoint '/follows/enriched', and returns the enriched follows data as JSON text.

  // --- GET /v1/follows/enriched ---
  server.tool(
    'frontrun_enriched_follows',
    'Get new follows with full enrichment: AI classification + your custom rules + your custom tags, all merged. This is the most powerful endpoint for custom workflows.',
    {
      since: z.string().optional().describe('Time window: "24h", "48h", "7d", etc. Default: "24h"'),
      username: z.string().optional().describe('Filter to a specific tracked account'),
    },
    async ({ since, username }) => {
      const params = new URLSearchParams();
      if (since) params.set('since', since);
      if (username) params.set('username', username);
      const qs = params.toString();
      const result = await apiCall('GET', `/follows/enriched${qs ? '?' + qs : ''}`);
      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
    }
  );

• index.js:381-384 (schema)

  Zod schema defining two optional input parameters: 'since' for time window filtering and 'username' for filtering to a specific tracked account.

  {
    since: z.string().optional().describe('Time window: "24h", "48h", "7d", etc. Default: "24h"'),
    username: z.string().optional().describe('Filter to a specific tracked account'),
  },

• index.js:29-73 (helper)

  API client helper function that handles HTTP requests to the Frontrun API with authentication, error handling, timeout management, and response parsing.

  async function apiCall(method, path, body = null) {
    const url = `${API_URL}/v1${path}`;
    const options = {
      method,
      headers: {
        'X-API-Key': API_KEY,
        'Content-Type': 'application/json',
      },
    };
    if (body) {
      options.body = JSON.stringify(body);
    }
  
    const controller = new AbortController();
    const timeout = setTimeout(() => controller.abort(), 60000);
    options.signal = controller.signal;
  
    let response;
    try {
      response = await fetch(url, options);
    } catch (err) {
      clearTimeout(timeout);
      if (err.name === 'AbortError') return { error: 'Request timed out (60s). Try a narrower query.' };
      return { error: `Network error: ${err.message}` };
    }
    clearTimeout(timeout);
  
    if (response.status === 429) {
      const retry = response.headers.get('Retry-After') || '60';
      return { error: `Rate limited. Retry in ${retry}s.` };
    }
    if (response.status === 401) {
      return { error: 'Invalid API key. Check FRONTRUN_API_KEY.' };
    }
    if (response.status === 402) {
      const data = await response.json();
      return { error: 'Insufficient balance', ...data };
    }
    if (!response.ok) {
      const text = await response.text();
      return { error: `HTTP ${response.status}: ${text.slice(0, 500)}` };
    }
  
    return response.json();
  }