GoLogin MCP

Instructions

Implementation Reference

• src/index.ts:454-570 (handler)

  Dynamic handler for all generated tools including 'get_users_proxies_geolocation_traffic'. Matches tool name to OpenAPI path/method (e.g., GET /users/proxies/geolocation/traffic), builds request from args, performs HTTP fetch to GoLogin API, and returns response.

  private async callDynamicTool(
    toolName: string,
    parameters: CallParameters = {},
    headers: Record<string, string> = {}
  ): Promise<CallToolResult> {
    console.log('parameters', parameters.body);
    if (!this.apiSpec || !this.apiSpec.paths) {
      throw new Error('API specification not loaded');
    }
  
    let targetPath = '';
    let targetMethod = '';
    let operation: OpenAPIV3.OperationObject | undefined;
  
    for (const [path, pathItem] of Object.entries(this.apiSpec.paths)) {
      if (!pathItem) continue;
  
      for (const [method, op] of Object.entries(pathItem)) {
        if (['get', 'post', 'put', 'delete', 'patch', 'head', 'options'].includes(method) && op) {
          const opObj = op as OpenAPIV3.OperationObject;
          const generatedToolName = `${method}${path.replace('browser', 'profile').replace(/[^a-zA-Z0-9]/g, '_')}`;
  
          if (generatedToolName === toolName) {
            targetPath = path;
            targetMethod = method.toUpperCase();
            operation = opObj;
            break;
          }
        }
      }
      if (operation) break;
    }
  
  
    if (!operation) {
      throw new Error(`Tool "${toolName}" not found`);
    }
  
    let url = `${this.baseUrl}${targetPath}`;
    const requestHeaders: Record<string, string> = { ...headers };
    let requestBody: string | undefined;
  
    requestHeaders['User-Agent'] = 'gologin-mcp';
    console.error('this.token', this.token);
    if (this.token) {
      requestHeaders['Authorization'] = `Bearer ${this.token}`;
    }
  
    if (parameters.path) {
      for (const [key, value] of Object.entries(parameters.path)) {
        url = url.replace(`{${key}}`, encodeURIComponent(value));
      }
    }
  
    const queryParams = new URLSearchParams();
    if (parameters.query) {
      for (const [key, value] of Object.entries(parameters.query)) {
        if (value) {
          queryParams.append(key, value);
        }
      }
    }
  
    if (queryParams.toString()) {
      url += `?${queryParams.toString()}`;
    }
    if (parameters.body && ['POST', 'PUT', 'PATCH', 'DELETE'].includes(targetMethod)) {
      requestHeaders['Content-Type'] = 'application/json';
      requestBody = JSON.stringify(parameters.body);
    }
    console.log('requestBody', requestBody);
    try {
      const fetchOptions: RequestInit = {
        method: targetMethod,
        headers: requestHeaders,
      };
      console.error('fetchOptions', fetchOptions);
      if (requestBody) {
        fetchOptions.body = requestBody;
      }
      const response = await fetch(url, fetchOptions);
  
      const responseHeaders: Record<string, string> = {};
      response.headers.forEach((value, key) => {
        responseHeaders[key] = value;
      });
  
      let responseBody: any;
      const contentType = response.headers.get('content-type') || '';
  
  
      if (contentType.includes('application/json')) {
        try {
          responseBody = await response.json();
        } catch {
          responseBody = await response.text();
        }
      } else {
        responseBody = await response.text();
      }
      return {
        content: [
          {
            type: 'text',
            text: `API Call Result:\n` +
              `URL: ${url}\n` +
              `Method: ${targetMethod}\n` +
              `Status: ${response.status} ${response.statusText}\n\n` +
              `Response Headers:\n${JSON.stringify(responseHeaders, null, 2)}\n\n` +
              `Response Body:\n${typeof responseBody === 'object' ? JSON.stringify(responseBody, null, 2) : responseBody}`,
          },
        ],
      };
    } catch (error) {
      throw new Error(`API call failed: ${error instanceof Error ? error.message : String(error)}`);
    }
  }

• src/index.ts:47-71 (registration)

  Registers all tools dynamically by iterating OpenAPI spec paths/operations, generating names like 'get_users_proxies_geolocation_traffic' from GET /users/proxies/geolocation/traffic (with browser->profile and non-alnum->_ replacements).

  this.server.setRequestHandler(ListToolsRequestSchema, async () => {
    const tools: Tool[] = [];
    if (this.apiSpec && this.apiSpec.paths) {
      for (const [path, pathItem] of Object.entries(this.apiSpec.paths)) {
        if (!pathItem) continue;
  
        for (const [method, operation] of Object.entries(pathItem)) {
          if (['get', 'post', 'put', 'delete', 'patch', 'head', 'options'].includes(method) && operation) {
            const op = operation as OpenAPIV3.OperationObject;
            const toolName = `${method}${path.replace('browser', 'profile').replace(/[^a-zA-Z0-9]/g, '_')}`;
  
            const inputSchema = this.buildInputSchema(op, path);
  
            tools.push({
              name: toolName,
              description: op.summary || op.description || `${method.toUpperCase()} ${path}`,
              inputSchema,
            });
          }
        }
      }
    }
  
    return { tools };
  });

• src/index.ts:204-249 (schema)

  Dynamically builds input schema for each tool from corresponding OpenAPI operation's parameters (path/query) and requestBody, used for 'get_users_proxies_geolocation_traffic' schema.

  private buildInputSchema(operation: OpenAPIV3.OperationObject, path: string): any {
    const properties: any = {};
    const required: string[] = [];
  
    const pathParams = this.extractPathParameters(operation, path);
    const queryParams = this.extractQueryParameters(operation);
    const bodySchema = this.extractRequestBodySchema(operation);
  
    if (pathParams.properties && Object.keys(pathParams.properties).length > 0) {
      for (const [key, prop] of Object.entries(pathParams.properties)) {
        properties[key] = this.convertOpenAPISchemaToJsonSchema(prop as OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject);
        if (pathParams.required.includes(key)) {
          required.push(key);
        }
      }
    }
  
    if (queryParams.properties && Object.keys(queryParams.properties).length > 0) {
      for (const [key, prop] of Object.entries(queryParams.properties)) {
        properties[key] = this.convertOpenAPISchemaToJsonSchema(prop as OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject);
        if (queryParams.required.includes(key)) {
          required.push(key);
        }
      }
    }
  
    if (bodySchema && bodySchema.properties) {
      for (const [key, prop] of Object.entries(bodySchema.properties)) {
        properties[key] = this.convertOpenAPISchemaToJsonSchema(prop as OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject);
        if (bodySchema.required && bodySchema.required.includes(key)) {
          required.push(key);
        }
      }
    }
  
    const schema: any = {
      type: 'object',
      properties,
    };
  
    if (required.length > 0) {
      schema.required = required;
    }
  
    return schema;
  }

• src/index.ts:177-202 (helper)

  Loads the OpenAPI specification from GoLogin which defines the /users/proxies/geolocation/traffic endpoint used for the tool.

  private async loadApiSpec(): Promise<void> {
    const url = 'https://docs-download.gologin.com/openapi-test.json';
    console.log('url', url);
    const response = await fetch(url);
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }
  
    const contentType = response.headers.get('content-type') || '';
    let spec: any;
  
    if (contentType.includes('application/json')) {
      spec = await response.json();
    } else {
      const text = await response.text();
      try {
        spec = JSON.parse(text);
      } catch {
        spec = yaml.load(text);
      }
    }
    // console.log('spec', spec);
    this.apiSpec = spec;
  
    this.baseUrl = this.getBaseUrl(spec);
  }

• src/index.ts:96-175 (handler)

  Helper handler extracts and categorizes input arguments into path/query/body for the dynamic API call for the tool.

  private extractParametersFromArgs(toolName: string, args: Record<string, any>): CallParameters {
    if (!this.apiSpec || !this.apiSpec.paths) {
      return { body: args };
    }
  
    let operation: OpenAPIV3.OperationObject | undefined;
    let path = '';
  
    for (const [apiPath, pathItem] of Object.entries(this.apiSpec.paths)) {
      if (!pathItem) continue;
  
      for (const [method, op] of Object.entries(pathItem)) {
        if (['get', 'post', 'put', 'delete', 'patch', 'head', 'options'].includes(method) && op) {
          const opObj = op as OpenAPIV3.OperationObject;
          const generatedToolName = opObj.operationId || `${method}_${apiPath.replace(/[^a-zA-Z0-9]/g, '_')}`;
  
          if (generatedToolName === toolName) {
            operation = opObj;
            path = apiPath;
            break;
          }
        }
      }
      if (operation) break;
    }
  
    if (!operation) {
      return { body: args };
    }
  
    const pathParams: Record<string, string> = {};
    const queryParams: Record<string, string> = {};
    const bodyParams: any = {};
  
    const pathParamNames = path.match(/\{([^}]+)\}/g)?.map(p => p.slice(1, -1)) || [];
  
    if (operation.parameters) {
      operation.parameters.forEach(param => {
        if ('$ref' in param) return;
  
        const parameter = param as OpenAPIV3.ParameterObject;
        const paramName = parameter.name;
  
        if (parameter.in === 'path' && args[paramName] !== undefined) {
          pathParams[paramName] = String(args[paramName]);
        } else if (parameter.in === 'query' && args[paramName] !== undefined) {
          queryParams[paramName] = String(args[paramName]);
        }
      });
    }
  
    pathParamNames.forEach(paramName => {
      if (args[paramName] !== undefined && !pathParams[paramName]) {
        pathParams[paramName] = String(args[paramName]);
      }
    });
  
    const usedParams = new Set([...Object.keys(pathParams), ...Object.keys(queryParams)]);
    for (const [key, value] of Object.entries(args)) {
      if (!usedParams.has(key)) {
        bodyParams[key] = value;
      }
    }
  
    const parameters: CallParameters = {};
  
    if (Object.keys(pathParams).length > 0) {
      parameters.path = pathParams;
    }
  
    if (Object.keys(queryParams).length > 0) {
      parameters.query = queryParams;
    }
  
    if (Object.keys(bodyParams).length > 0) {
      parameters.body = bodyParams;
    }
  
    return parameters;
  }