The Aleph MCP

Instructions

Implementation Reference

• src/tools.js:382-402 (handler)

  Main handler function that extracts the ASN from parameters, calls the API client, formats the classification results into a markdown response, and handles errors.

  async asnClassifications(params) {
    try {
      const { asn } = params;
      const result = await this.client.getASNClassifications(asn);
  
      let response = `🏷️ Classifications for ASN ${asn}\n\n`;
  
      if (typeof result === 'object' && Object.keys(result).length > 0) {
        for (const [key, value] of Object.entries(result)) {
          response += `**${key}:** ${JSON.stringify(value, null, 2)}\n`;
        }
      } else {
        response += 'No classification data available for this ASN.';
      }
  
      return response;
  
    } catch (error) {
      return `❌ Failed to retrieve ASN classifications: ${error.message}`;
    }
  }

• src/tools.js:84-97 (schema)

  Tool schema definition including name, description, and input schema requiring an 'asn' string parameter.

  {
    name: 'thealeph_asn_classifications',
    description: 'Get classification information for a specific ASN',
    inputSchema: {
      type: 'object',
      properties: {
        asn: {
          type: 'string',
          description: 'Autonomous System Number (e.g., "15169" for Google)'
        }
      },
      required: ['asn']
    }
  },

• src/tools.js:226-257 (registration)

  Tool dispatcher (executeTool method) that routes 'thealeph_asn_classifications' calls to the asnClassifications handler via switch statement.

  async executeTool(toolName, params = {}) {
    switch (toolName) {
      case 'thealeph_health_check':
        return this.healthCheck(params);
      case 'thealeph_current_stats':
        return this.currentStats(params);
      case 'thealeph_daily_stats':
        return this.dailyStats(params);
      case 'thealeph_summary_stats':
        return this.summaryStats(params);
      case 'thealeph_export_stats':
        return this.exportStats(params);
      case 'thealeph_asn_classifications':
        return this.asnClassifications(params);
      case 'thealeph_asn_regex':
        return this.asnRegex(params);
      case 'thealeph_asn_hints':
        return this.asnHints(params);
      case 'thealeph_asn_infrastructure_mapping':
        return this.asnInfrastructureMapping(params);
      case 'thealeph_asn_hint_mapping':
        return this.asnHintMapping(params);
      case 'thealeph_query_ptr':
        return this.queryPTR(params);
      case 'thealeph_batch_query_ptr':
        return this.batchQueryPTR(params);
      case 'thealeph_traceroute_mapper':
        return this.tracerouteMapper(params);
      default:
        throw new Error(`Unknown tool: ${toolName}`);
    }
  }

• src/client.js:111-113 (helper)

  API client helper method that performs the HTTP GET request to retrieve ASN classifications from the Aleph API endpoint.

  async getASNClassifications(asn) {
    return this.makeRequest('GET', `/api/asn/${asn}/classifications`);
  }

• src/tools.js:16-221 (helper)

  Method that returns all tool definitions for MCP server registration, including the schema for thealeph_asn_classifications.

  getToolDefinitions() {
    return [
      {
        name: 'thealeph_health_check',
        description: 'Check the health and operational status of The Aleph API',
        inputSchema: {
          type: 'object',
          properties: {},
          required: []
        }
      },
      {
        name: 'thealeph_current_stats',
        description: 'Get current API usage statistics for the last N days',
        inputSchema: {
          type: 'object',
          properties: {
            days: {
              type: 'integer',
              description: 'Number of days to retrieve statistics for (1-30)',
              minimum: 1,
              maximum: 30,
              default: 1
            }
          },
          required: []
        }
      },
      {
        name: 'thealeph_daily_stats',
        description: 'Get API usage statistics for a specific date',
        inputSchema: {
          type: 'object',
          properties: {
            date: {
              type: 'string',
              description: 'Date in YYYY-MM-DD format',
              pattern: '^\\d{4}-\\d{2}-\\d{2}$'
            }
          },
          required: ['date']
        }
      },
      {
        name: 'thealeph_summary_stats',
        description: 'Get a quick summary of API usage statistics',
        inputSchema: {
          type: 'object',
          properties: {},
          required: []
        }
      },
      {
        name: 'thealeph_export_stats',
        description: 'Export all monitoring data in specified format',
        inputSchema: {
          type: 'object',
          properties: {
            format: {
              type: 'string',
              description: 'Export format',
              enum: ['json', 'csv'],
              default: 'json'
            }
          },
          required: []
        }
      },
      {
        name: 'thealeph_asn_classifications',
        description: 'Get classification information for a specific ASN',
        inputSchema: {
          type: 'object',
          properties: {
            asn: {
              type: 'string',
              description: 'Autonomous System Number (e.g., "15169" for Google)'
            }
          },
          required: ['asn']
        }
      },
      {
        name: 'thealeph_asn_regex',
        description: 'Get regex patterns associated with an ASN for PTR record parsing',
        inputSchema: {
          type: 'object',
          properties: {
            asn: {
              type: 'string',
              description: 'Autonomous System Number'
            }
          },
          required: ['asn']
        }
      },
      {
        name: 'thealeph_asn_hints',
        description: 'Get geographic and network hints for an ASN',
        inputSchema: {
          type: 'object',
          properties: {
            asn: {
              type: 'string',
              description: 'Autonomous System Number'
            }
          },
          required: ['asn']
        }
      },
      {
        name: 'thealeph_asn_infrastructure_mapping',
        description: 'Map infrastructure locations for an ASN',
        inputSchema: {
          type: 'object',
          properties: {
            asn: {
              type: 'string',
              description: 'Autonomous System Number'
            }
          },
          required: ['asn']
        }
      },
      {
        name: 'thealeph_asn_hint_mapping',
        description: 'Get hint-based location mapping for an ASN',
        inputSchema: {
          type: 'object',
          properties: {
            asn: {
              type: 'string',
              description: 'Autonomous System Number'
            }
          },
          required: ['asn']
        }
      },
      {
        name: 'thealeph_query_ptr',
        description: 'Query reverse DNS (PTR) records and retrieve network intelligence including ASN, location, and geo hints',
        inputSchema: {
          type: 'object',
          properties: {
            ptr_record: {
              type: 'string',
              description: 'PTR record hostname to query'
            },
            ip: {
              type: 'string',
              description: 'IP address to query'
            },
            asn: {
              type: 'integer',
              description: 'ASN number to query'
            }
          },
          required: []
        }
      },
      {
        name: 'thealeph_batch_query_ptr',
        description: 'Query multiple PTR records in a single batch request',
        inputSchema: {
          type: 'object',
          properties: {
            queries: {
              type: 'array',
              description: 'Array of query objects, each with optional ptr_record, ip, and/or asn',
              items: {
                type: 'object',
                properties: {
                  ptr_record: { type: 'string' },
                  ip: { type: 'string' },
                  asn: { type: 'integer' }
                }
              },
              minItems: 1,
              maxItems: 100
            }
          },
          required: ['queries']
        }
      },
      {
        name: 'thealeph_traceroute_mapper',
        description: 'Enrich traceroute hops with network intelligence including ASN, PTR records, and geographic locations',
        inputSchema: {
          type: 'object',
          properties: {
            traceroute: {
              type: 'string',
              description: 'Traceroute output as a string'
            },
            mode: {
              type: 'string',
              description: 'Traceroute format mode',
              enum: ['string', 'RIPE'],
              default: 'string'
            }
          },
          required: ['traceroute']
        }
      }
    ];
  }