Frontrun MCP Server

Instructions

Implementation Reference

• index.js:257-260 (handler)

  Handler function for frontrun_create_rule tool. Makes a POST API call to /classify/rules endpoint with name, conditions, and actions parameters. Returns JSON-formatted response.

  async ({ name, conditions, actions }) => {
    const result = await apiCall('POST', '/classify/rules', { name, conditions, actions });
    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
  }

• index.js:242-256 (schema)

  Zod schema defining input validation for frontrun_create_rule. Includes name (string), conditions object (bio_keywords, username_pattern, sector_contains, must_be_company), and actions object (custom_sector, custom_entity_type, tags, priority).

  {
    name: z.string().describe('Human-readable rule name, e.g. "DeFi Protocols"'),
    conditions: z.object({
      bio_keywords: z.array(z.string()).optional().describe('Keywords to match in bio (any match triggers)'),
      username_pattern: z.string().optional().describe('Regex pattern for username'),
      sector_contains: z.string().optional().describe('Match entities in this sector'),
      must_be_company: z.boolean().optional().describe('Only match companies (true) or individuals (false)'),
    }).describe('Conditions that must ALL be met'),
    actions: z.object({
      custom_sector: z.string().optional().describe('Override sector classification'),
      custom_entity_type: z.string().optional().describe('Override entity type'),
      tags: z.array(z.string()).optional().describe('Tags to apply, e.g. ["watchlist", "competitor"]'),
      priority: z.string().optional().describe('"high", "medium", or "low"'),
    }).describe('What to apply when conditions match'),
  },

• index.js:239-261 (registration)

  Registration of frontrun_create_rule tool with MCP server. Defines tool name, description, schema, and handler function using server.tool() method.

  server.tool(
    'frontrun_create_rule',
    'Create a custom classification rule. Rules auto-tag entities matching conditions (bio keywords, sector, username pattern). Use this to build custom watchlists, sector taxonomies, or competitor tracking.',
    {
      name: z.string().describe('Human-readable rule name, e.g. "DeFi Protocols"'),
      conditions: z.object({
        bio_keywords: z.array(z.string()).optional().describe('Keywords to match in bio (any match triggers)'),
        username_pattern: z.string().optional().describe('Regex pattern for username'),
        sector_contains: z.string().optional().describe('Match entities in this sector'),
        must_be_company: z.boolean().optional().describe('Only match companies (true) or individuals (false)'),
      }).describe('Conditions that must ALL be met'),
      actions: z.object({
        custom_sector: z.string().optional().describe('Override sector classification'),
        custom_entity_type: z.string().optional().describe('Override entity type'),
        tags: z.array(z.string()).optional().describe('Tags to apply, e.g. ["watchlist", "competitor"]'),
        priority: z.string().optional().describe('"high", "medium", or "low"'),
      }).describe('What to apply when conditions match'),
    },
    async ({ name, conditions, actions }) => {
      const result = await apiCall('POST', '/classify/rules', { name, conditions, actions });
      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
    }
  );

• index.js:29-73 (helper)

  Helper function apiCall that handles HTTP requests to the Frontrun API. Includes timeout handling (60s), error handling for network issues, rate limiting (429), authentication (401), insufficient balance (402), and other HTTP errors. Constructs full URL, sets headers with API key, and serializes request body.

  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();
  }