HAL (HTTP API Layer)

Instructions

Implementation Reference

• src/index.ts:695-794 (registration)

  Registration of the 'list-secrets' MCP tool, including its schema (empty input) and inline handler function that lists available secrets.
  server.registerTool( "list-secrets", { title: "List Available Secrets", description: "Get a list of available secret keys that can be used with {secrets.key} syntax. Only shows the key names, never the actual secret values.", inputSchema: {} }, async () => { try { const secretKeys = Object.keys(secrets); if (secretKeys.length === 0) { return { content: [{ type: "text" as const, text: "No secrets are currently configured. To add secrets, set environment variables with the HAL_SECRET_ prefix.\n\nExample:\n HAL_SECRET_API_KEY=your_api_key\n HAL_SECRET_TOKEN=your_token\n\nThen use them in requests like: {secrets.api_key} or {secrets.token}\n\nFor namespaced secrets with URL restrictions:\n HAL_SECRET_MICROSOFT_API_KEY=your_api_key\n HAL_ALLOW_MICROSOFT=\"https://azure.microsoft.com/*\"\n Usage: {secrets.microsoft.api_key}" }] }; } let response = `Available secrets (${secretKeys.length} total):\n\n`; // Group secrets by namespace const namespacedSecrets: Record<string, string[]> = {}; const unrestrictedSecrets: string[] = []; for (const [key, secretInfo] of Object.entries(secrets)) { if (secretInfo.namespace) { const namespaceTemplate = secretInfo.namespace.toLowerCase().replace(/-/g, '.'); if (!namespacedSecrets[namespaceTemplate]) { namespacedSecrets[namespaceTemplate] = []; } namespacedSecrets[namespaceTemplate].push(key); } else { unrestrictedSecrets.push(key); } } // Show unrestricted secrets first if (unrestrictedSecrets.length > 0) { response += "**Unrestricted Secrets** (can be used with any URL):\n"; unrestrictedSecrets.forEach((key, index) => { response += `${index + 1}. {secrets.${key}}\n`; }); response += "\n"; } // Show namespaced secrets with their restrictions for (const [namespace, keys] of Object.entries(namespacedSecrets)) { const firstKey = keys[0]; const secretInfo = secrets[firstKey]; response += `**Namespace: ${namespace}**\n`; if (secretInfo.allowedUrls && secretInfo.allowedUrls.length > 0) { response += `Restricted to URLs: ${secretInfo.allowedUrls.join(', ')}\n`; } else { response += "No URL restrictions (can be used with any URL)\n"; } response += "Secrets:\n"; keys.forEach((key, index) => { response += `${index + 1}. {secrets.${key}}\n`; }); response += "\n"; } response += "**Usage examples:**\n"; const exampleKey = secretKeys[0] || 'token'; response += `- URL: "https://api.example.com/data?token={secrets.${exampleKey}}"\n`; response += `- Header: {"Authorization": "Bearer {secrets.${exampleKey}}"}\n`; response += `- Body: {"username": "{secrets.${secretKeys.find(k => k.includes('user')) || 'username'}}"}\n\n`; response += "**Security Notes:**\n"; response += "- Only the key names are shown here. The actual secret values are never exposed to the AI.\n"; response += "- Secrets are substituted securely at request time.\n"; const restrictedCount = Object.values(secrets).filter(s => s.allowedUrls).length; if (restrictedCount > 0) { response += `- ${restrictedCount} secrets have URL restrictions for enhanced security.\n`; response += "- If a secret is restricted, it will only work with URLs matching its allowed patterns.\n"; } return { content: [{ type: "text" as const, text: response }] }; } catch (error) { const errorMessage = error instanceof Error ? error.message : 'Unknown error'; return { content: [{ type: "text" as const, text: `Error listing secrets: ${redactSecretsFromText(errorMessage)}` }], isError: true }; } } );
• src/index.ts:702-793 (handler)

  The core handler logic for 'list-secrets': iterates over global 'secrets' store, formats response with grouped secret keys, namespace restrictions, usage examples, and security information without exposing values.
  async () => { try { const secretKeys = Object.keys(secrets); if (secretKeys.length === 0) { return { content: [{ type: "text" as const, text: "No secrets are currently configured. To add secrets, set environment variables with the HAL_SECRET_ prefix.\n\nExample:\n HAL_SECRET_API_KEY=your_api_key\n HAL_SECRET_TOKEN=your_token\n\nThen use them in requests like: {secrets.api_key} or {secrets.token}\n\nFor namespaced secrets with URL restrictions:\n HAL_SECRET_MICROSOFT_API_KEY=your_api_key\n HAL_ALLOW_MICROSOFT=\"https://azure.microsoft.com/*\"\n Usage: {secrets.microsoft.api_key}" }] }; } let response = `Available secrets (${secretKeys.length} total):\n\n`; // Group secrets by namespace const namespacedSecrets: Record<string, string[]> = {}; const unrestrictedSecrets: string[] = []; for (const [key, secretInfo] of Object.entries(secrets)) { if (secretInfo.namespace) { const namespaceTemplate = secretInfo.namespace.toLowerCase().replace(/-/g, '.'); if (!namespacedSecrets[namespaceTemplate]) { namespacedSecrets[namespaceTemplate] = []; } namespacedSecrets[namespaceTemplate].push(key); } else { unrestrictedSecrets.push(key); } } // Show unrestricted secrets first if (unrestrictedSecrets.length > 0) { response += "**Unrestricted Secrets** (can be used with any URL):\n"; unrestrictedSecrets.forEach((key, index) => { response += `${index + 1}. {secrets.${key}}\n`; }); response += "\n"; } // Show namespaced secrets with their restrictions for (const [namespace, keys] of Object.entries(namespacedSecrets)) { const firstKey = keys[0]; const secretInfo = secrets[firstKey]; response += `**Namespace: ${namespace}**\n`; if (secretInfo.allowedUrls && secretInfo.allowedUrls.length > 0) { response += `Restricted to URLs: ${secretInfo.allowedUrls.join(', ')}\n`; } else { response += "No URL restrictions (can be used with any URL)\n"; } response += "Secrets:\n"; keys.forEach((key, index) => { response += `${index + 1}. {secrets.${key}}\n`; }); response += "\n"; } response += "**Usage examples:**\n"; const exampleKey = secretKeys[0] || 'token'; response += `- URL: "https://api.example.com/data?token={secrets.${exampleKey}}"\n`; response += `- Header: {"Authorization": "Bearer {secrets.${exampleKey}}"}\n`; response += `- Body: {"username": "{secrets.${secretKeys.find(k => k.includes('user')) || 'username'}}"}\n\n`; response += "**Security Notes:**\n"; response += "- Only the key names are shown here. The actual secret values are never exposed to the AI.\n"; response += "- Secrets are substituted securely at request time.\n"; const restrictedCount = Object.values(secrets).filter(s => s.allowedUrls).length; if (restrictedCount > 0) { response += `- ${restrictedCount} secrets have URL restrictions for enhanced security.\n`; response += "- If a secret is restricted, it will only work with URLs matching its allowed patterns.\n"; } return { content: [{ type: "text" as const, text: response }] }; } catch (error) { const errorMessage = error instanceof Error ? error.message : 'Unknown error'; return { content: [{ type: "text" as const, text: `Error listing secrets: ${redactSecretsFromText(errorMessage)}` }], isError: true }; } }
• src/index.ts:697-700 (schema)

  Tool metadata and input schema definition (no input parameters required).
  { title: "List Available Secrets", description: "Get a list of available secret keys that can be used with {secrets.key} syntax. Only shows the key names, never the actual secret values.", inputSchema: {}
• src/index.ts:172-200 (helper)

  Helper function that populates the global 'secrets' store from HAL_SECRET_* environment variables, used by list-secrets handler.
  function loadSecrets(): void { secrets = {}; const urlRestrictions = loadUrlRestrictions(); for (const [key, value] of Object.entries(process.env)) { if (key.startsWith('HAL_SECRET_') && value) { const { namespace, key: secretKey, templateKey } = parseSecretKey(key); const secretInfo: SecretInfo = { value, namespace, allowedUrls: namespace ? urlRestrictions[namespace] : undefined, templateKey }; secrets[templateKey] = secretInfo; } } if (Object.keys(secrets).length > 0) { console.error(`Loaded ${Object.keys(secrets).length} secrets from environment variables`); // Log namespace restrictions (without secret values) const restrictedCount = Object.values(secrets).filter(s => s.allowedUrls).length; if (restrictedCount > 0) { console.error(`${restrictedCount} secrets have URL restrictions`); } } }