HAL (HTTP API Layer)

Instructions

Implementation Reference

• src/index.ts:679-692 (registration)

  Registration of the 'http-options' tool, including input schema validation using Zod and a handler function that delegates to the shared makeHttpRequest helper with 'OPTIONS' method.
  server.registerTool( "http-options", { title: "HTTP OPTIONS Request", description: "Make an HTTP OPTIONS request to a specified URL to check available methods and headers. Supports secret substitution using {secrets.key} syntax in URL and headers where 'key' corresponds to HAL_SECRET_KEY environment variables.", inputSchema: { url: z.string().url(), headers: z.record(z.string()).optional() } }, async ({ url, headers = {} }: { url: string; headers?: Record<string, string> }) => { return makeHttpRequest('OPTIONS', url, { headers }); } );
• src/index.ts:343-447 (helper)

  Core helper function that implements the HTTP request logic for all HTTP tools, including OPTIONS. Handles secret substitution with URL restrictions, global URL filters, fetch execution, response formatting, and automatic secret redaction from outputs.
  async function makeHttpRequest( method: string, url: string, options: { headers?: Record<string, string>; body?: string; queryParams?: Record<string, any>; } = {} ) { try { const { headers = {}, body, queryParams = {} } = options; // First, substitute secrets in URL to get the final URL for validation // We need to do this in two passes to handle URL restrictions properly const processedUrl = substituteSecrets(url, url); // Now substitute secrets in headers, body, and query parameters using the processed URL const processedHeaders = substituteSecretsInObject(headers, processedUrl); const processedBody = body ? substituteSecrets(body, processedUrl) : body; const processedQueryParams = substituteSecretsInObject(queryParams, processedUrl); // Build URL with query parameters const urlObj = new URL(processedUrl); Object.entries(processedQueryParams).forEach(([key, value]) => { if (value !== undefined && value !== null) { urlObj.searchParams.set(key, String(value)); } }); const finalUrl = urlObj.toString(); // Check global URL whitelist/blacklist const urlCheck = isUrlAllowedGlobal(finalUrl); if (!urlCheck.allowed) { throw new Error(urlCheck.reason || 'URL is not allowed'); } const defaultHeaders = { 'User-Agent': 'HAL-MCP/1.0.0', ...processedHeaders }; // Add Content-Type for methods that typically send data if (['POST', 'PUT', 'PATCH'].includes(method.toUpperCase()) && processedBody && !('Content-Type' in processedHeaders)) { (defaultHeaders as any)['Content-Type'] = 'application/json'; } const response = await fetch(finalUrl, { method: method.toUpperCase(), headers: defaultHeaders, body: processedBody }); const contentType = response.headers.get('content-type') || 'text/plain'; let content: string; // HEAD requests don't have a body by design if (method.toUpperCase() === 'HEAD') { content = '(No body - HEAD request)'; } else { try { if (contentType.includes('application/json')) { const text = await response.text(); if (text.trim()) { content = JSON.stringify(JSON.parse(text), null, 2); } else { content = '(Empty response)'; } } else { content = await response.text(); } } catch (parseError) { // If JSON parsing fails, try to get text try { content = await response.text(); } catch (textError) { content = '(Unable to parse response)'; } } } // Redact secrets from response headers and content before returning const redactedHeaders = Array.from(response.headers.entries()) .map(([key, value]) => `${key}: ${redactSecretsFromText(value)}`) .join('\n'); const redactedContent = redactSecretsFromText(content); return { content: [{ type: "text" as const, text: `Status: ${response.status} ${response.statusText}\n\nHeaders:\n${redactedHeaders}\n\nBody:\n${redactedContent}` }] }; } catch (error) { const errorMessage = error instanceof Error ? error.message : 'Unknown error'; const redactedErrorMessage = redactSecretsFromText(errorMessage); return { content: [{ type: "text" as const, text: `Error making ${method.toUpperCase()} request: ${redactedErrorMessage}` }], isError: true }; } }
• src/index.ts:684-687 (schema)

  Zod input schema for the 'http-options' tool: requires a URL (validated as URL format) and optional headers object.
  inputSchema: { url: z.string().url(), headers: z.record(z.string()).optional() }