HAL (HTTP API Layer)

Un servidor MCP que permite a los modelos de lenguaje grandes realizar solicitudes HTTP e interactuar con APIs web. Admite la generación automática de herramientas a partir de especificaciones OpenAPI/Swagger.

GitHub

Prueba este MCPPatrocinado

Documentación

HAL (HTTP API Layer)

HAL es un servidor de Model Context Protocol (MCP) que proporciona capacidades de API HTTP a los Modelos de Lenguaje de Gran Tamaño. Permite que los LLM realicen solicitudes HTTP e interactúen con APIs web a través de una interfaz segura y controlada. HAL también puede generar automáticamente herramientas a partir de especificaciones OpenAPI/Swagger para una integración de API sin interrupciones.

Documentación

Documentación Completa →

Visite nuestro sitio de documentación integral para obtener guías detalladas, ejemplos y referencia de API.

Características

Solicitudes HTTP GET/POST/PUT/PATCH/DELETE/OPTIONS/HEAD: Obtenga y envíe datos a cualquier endpoint HTTP
Gestión Segura de Secretos: Secretos basados en variables de entorno con sustitución de {secrets.key} y redacción automática
Integración Swagger/OpenAPI: Genere automáticamente herramientas a partir de especificaciones de API
Documentación Integrada: Referencia de API autodocumentada
Seguro: Se ejecuta en un entorno aislado con acceso controlado
Rápido: Construido con TypeScript y optimizado para rendimiento

Uso

HAL está diseñado para funcionar con clientes compatibles con MCP. Aquí hay algunos ejemplos:

Uso Básico (Claude Desktop)

Agregue HAL a su configuración de Claude Desktop (npx instalará y ejecutará HAL automáticamente):

{
  "mcpServers": {
    "hal": {
      "command": "npx",
      "args": ["hal-mcp"]
    }
  }
}

Con Integración Swagger/OpenAPI y Secretos

Para habilitar la generación automática de herramientas a partir de una especificación OpenAPI y usar secretos:

{
  "mcpServers": {
    "hal": {
      "command": "npx",
      "args": ["hal-mcp"],
      "env": {
        "HAL_SWAGGER_FILE": "/path/to/your/openapi.json",
        "HAL_API_BASE_URL": "https://api.example.com",
        "HAL_SECRET_API_KEY": "your-secret-api-key",
        "HAL_SECRET_USERNAME": "your-username",
        "HAL_SECRET_PASSWORD": "your-password"
      }
    }
  }
}

Configuración Basada en URL

También puede cargar especificaciones OpenAPI directamente desde URLs:

{
  "mcpServers": {
    "hal": {
      "command": "npx",
      "args": ["hal-mcp"],
      "env": {
        "HAL_SWAGGER_FILE": "/swagger/v1/swagger.json",
        "HAL_API_BASE_URL": "http://localhost:5065",
        "HAL_SECRET_API_KEY": "your-secret-api-key"
      }
    }
  }
}

Uso Directo

# Start the HAL server with default tools
npx hal-mcp

# Or with Swagger/OpenAPI integration
HAL_SWAGGER_FILE=/path/to/api.yaml HAL_API_BASE_URL=https://api.example.com npx hal-mcp

# Or load from URL
HAL_SWAGGER_FILE=/swagger/v1/swagger.json HAL_API_BASE_URL=http://localhost:5065 npx hal-mcp

Configuración

HAL admite las siguientes variables de entorno:

HAL_SWAGGER_FILE: Ruta o URL al archivo de especificación OpenAPI/Swagger (formato JSON o YAML). Puede ser:
- Ruta de archivo local: /path/to/api.yaml
- URL completa: https://api.example.com/swagger.json
- Ruta relativa: /swagger/v1/swagger.json (combinada con HAL_API_BASE_URL)
HAL_API_BASE_URL: URL base para solicitudes de API (anula los servidores especificados en la especificación OpenAPI)
HAL_SECRET_*: Valores secretos para sustitución segura en solicitudes (por ejemplo, HAL_SECRET_TOKEN=abc123)
HAL_ALLOW_*: Restricciones de URL para secretos con espacios de nombres (por ejemplo, HAL_ALLOW_MICROSOFT="https://azure.microsoft.com/*")
HAL_WHITELIST_URLS: Lista separada por comas de patrones de URL permitidos (si se establece, solo se permiten estas URLs)
HAL_BLACKLIST_URLS: Lista separada por comas de patrones de URL bloqueados (si se establece, estas URLs se deniegan)

Gestión de Secretos

HAL proporciona una gestión segura de secretos para mantener información sensible como claves de API, tokens y contraseñas fuera de la conversación, mientras permite que la IA los use en solicitudes HTTP.

Cómo Funciona

Variables de Entorno: Defina secretos usando el prefijo HAL_SECRET_:

HAL_SECRET_API_KEY=your-secret-api-key
HAL_SECRET_TOKEN=your-auth-token
HAL_SECRET_USERNAME=your-username

Sustitución de Plantillas: Haga referencia a secretos en sus solicitudes usando la sintaxis {secrets.key}:
- URLs: https://api.example.com/data?token={secrets.token}
- Encabezados: {"Authorization": "Bearer {secrets.api_key}"}
- Cuerpos de Solicitud: {"username": "{secrets.username}", "password": "{secrets.password}"}
Seguridad: La IA nunca ve los valores secretos reales, solo los marcadores de posición de plantilla. Los valores se sustituyen en el momento de la solicitud.

Redacción Automática de Secretos

HAL redacta automáticamente los valores secretos de todas las respuestas enviadas a la IA, proporcionando una capa adicional de seguridad contra la exposición de credenciales.

Cómo Funciona

Seguimiento de Secretos: HAL mantiene un registro de todos los valores secretos de las variables de entorno
Escaneo de Respuestas: Todas las respuestas HTTP (encabezados, cuerpos, mensajes de error) se escanean en busca de valores secretos
Reemplazo Automático: Cualquier aparición de valores secretos reales se reemplaza con [REDACTED] antes de enviarla a la IA
Cobertura Integral: La redacción se aplica a:
- Mensajes de error (incluidos errores de análisis de URL que podrían exponer credenciales)
- Encabezados de respuesta (en caso de que las APIs devuelvan datos de autenticación)
- Cuerpos de respuesta (protegiendo contra respuestas de API que podrían incluir datos sensibles)
- Todo otro texto devuelto a la IA

Ejemplo de Protección

Antes (vulnerable):

Error: Request cannot be constructed from a URL that includes credentials: 
https://65GQiI8-1JCOWV1KAuYr0g:-VOIfpydl2GWfucCdEJ1BJ2vrsJyjQ@www.reddit.com/api/v1/access_token

Después (seguro):

Error: Request cannot be constructed from a URL that includes credentials: 
https://[REDACTED]:[REDACTED]@www.reddit.com/api/v1/access_token

Esta protección es automática y no requiere configuración: HAL redactará cualquier valor secreto sin importar cómo aparezca en las respuestas, asegurando que incluso si una API o mensaje de error intenta exponer credenciales, la IA nunca vea los valores reales.

Espacios de Nombres y Restricciones de URL

HAL admite organizar secretos en espacios de nombres y restringirlos a URLs específicas para mayor seguridad:

Convención de Espacios de Nombres

Use - para separadores de espacios de nombres y _ para separadores de palabras dentro de las claves:

# Single namespace
HAL_SECRET_MICROSOFT_API_KEY=your-api-key
# Usage: {secrets.microsoft.api_key}

# Multi-level namespaces
HAL_SECRET_AZURE-STORAGE_ACCESS_KEY=your-storage-key
HAL_SECRET_AZURE-COGNITIVE_API_KEY=your-cognitive-key
HAL_SECRET_GOOGLE-CLOUD-STORAGE_SERVICE_ACCOUNT_KEY=your-service-key
# Usage: {secrets.azure.storage.access_key}
# Usage: {secrets.azure.cognitive.api_key}
# Usage: {secrets.google.cloud.storage.service_account_key}

Restricciones de URL

Restrinja secretos con espacios de nombres a URLs específicas usando variables de entorno HAL_ALLOW_*:

# Restrict Microsoft secrets to Microsoft domains
HAL_SECRET_MICROSOFT_API_KEY=your-api-key
HAL_ALLOW_MICROSOFT="https://azure.microsoft.com/*,https://*.microsoft.com/*"

# Restrict Azure Storage secrets to Azure storage endpoints
HAL_SECRET_AZURE-STORAGE_ACCESS_KEY=your-storage-key
HAL_ALLOW_AZURE-STORAGE="https://*.blob.core.windows.net/*,https://*.queue.core.windows.net/*"

# Multiple URLs are comma-separated
HAL_SECRET_GOOGLE-CLOUD_API_KEY=your-google-key
HAL_ALLOW_GOOGLE-CLOUD="https://*.googleapis.com/*,https://*.googlecloud.com/*"

Cómo Funciona el Análisis

Comprender cómo los nombres de variables de entorno se convierten en claves de plantilla:

HAL_SECRET_AZURE-STORAGE_ACCESS_KEY
│         │              │
│         │              └─ Key: "ACCESS_KEY" → "access_key" 
│         └─ Namespace: "AZURE-STORAGE" → "azure.storage"
└─ Prefix

Final template: {secrets.azure.storage.access_key}

Desglose paso a paso:

Eliminar el prefijo HAL_SECRET_ → AZURE-STORAGE_ACCESS_KEY
Dividir en el primer _ → Espacio de nombres: AZURE-STORAGE, Clave: ACCESS_KEY
Transformar el espacio de nombres: AZURE-STORAGE → azure.storage (los guiones se convierten en puntos, minúsculas)
Transformar la clave: ACCESS_KEY → access_key (los guiones bajos permanecen, minúsculas)
Combinar: {secrets.azure.storage.access_key}

Más Ejemplos

# Simple namespace
HAL_SECRET_GITHUB_TOKEN=your_token
→ {secrets.github.token}

# Two-level namespace  
HAL_SECRET_AZURE-COGNITIVE_API_KEY=your_key
→ {secrets.azure.cognitive.api_key}

# Three-level namespace
HAL_SECRET_GOOGLE-CLOUD-STORAGE_SERVICE_ACCOUNT=your_account
→ {secrets.google.cloud.storage.service_account}

# Complex key with underscores
HAL_SECRET_AWS-S3_BUCKET_ACCESS_KEY_ID=your_id
→ {secrets.aws.s3.bucket_access_key_id}

# No namespace (legacy style)
HAL_SECRET_API_KEY=your_key
→ {secrets.api_key}

Guía Visual: Flujo Completo

Environment Variable          Template Usage                   URL Restriction
├─ HAL_SECRET_MICROSOFT_API_KEY    ├─ {secrets.microsoft.api_key}    ├─ HAL_ALLOW_MICROSOFT
├─ HAL_SECRET_AZURE-STORAGE_KEY    ├─ {secrets.azure.storage.key}    ├─ HAL_ALLOW_AZURE-STORAGE  
├─ HAL_SECRET_AWS-S3_ACCESS_KEY    ├─ {secrets.aws.s3.access_key}    ├─ HAL_ALLOW_AWS-S3
└─ HAL_SECRET_UNRESTRICTED_TOKEN   └─ {secrets.unrestricted.token}   └─ (no restriction)

Beneficios de Seguridad

Principio de Mínimo Privilegio: Los secretos solo funcionan con sus servicios previstos
Previene Fugas Entre Servicios: Los secretos de Azure no se pueden enviar a APIs de AWS
Defensa en Profundidad: Incluso con errores de IA o inyección de prompts, los secretos están restringidos
Organización Clara: La estructura de espacios de nombres hace que la gestión de secretos sea más intuitiva

Escenarios de Uso en el Mundo Real

Escenario 1: Aplicación Multi-Nube

# Azure services
HAL_SECRET_AZURE-STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;...
HAL_SECRET_AZURE-COGNITIVE_SPEECH_KEY=abcd1234...
HAL_ALLOW_AZURE-STORAGE="https://*.blob.core.windows.net/*,https://*.queue.core.windows.net/*"
HAL_ALLOW_AZURE-COGNITIVE="https://*.cognitiveservices.azure.com/*"

# AWS services  
HAL_SECRET_AWS-S3_ACCESS_KEY=AKIA...
HAL_SECRET_AWS-LAMBDA_API_KEY=lambda_key...
HAL_ALLOW_AWS-S3="https://s3.*.amazonaws.com/*,https://*.s3.amazonaws.com/*"
HAL_ALLOW_AWS-LAMBDA="https://*.lambda.amazonaws.com/*"

# Google Cloud
HAL_SECRET_GOOGLE-CLOUD_SERVICE_ACCOUNT_KEY={"type":"service_account"...}
HAL_ALLOW_GOOGLE-CLOUD="https://*.googleapis.com/*"

Uso en solicitudes:

{
  "url": "https://mystorageaccount.blob.core.windows.net/container/file",
  "headers": {
    "Authorization": "Bearer {secrets.azure.storage.connection_string}"
  }
}

✅ Funciona: La URL coincide con el patrón de Azure Storage
❌ Bloqueado: Si se usa con https://s3.amazonaws.com/bucket - ¡servicio incorrecto!

Escenario 2: Desarrollo vs Producción

# Development environment
HAL_SECRET_DEV-API_KEY=dev_key_123
HAL_ALLOW_DEV-API="https://dev-api.example.com/*,https://staging-api.example.com/*"

# Production environment  
HAL_SECRET_PROD-API_KEY=prod_key_456
HAL_ALLOW_PROD-API="https://api.example.com/*"

Escenario 3: Aislamiento de Departamentos

# Marketing team APIs
HAL_SECRET_MARKETING-CRM_API_KEY=crm_key...
HAL_SECRET_MARKETING-ANALYTICS_TOKEN=analytics_token...
HAL_ALLOW_MARKETING-CRM="https://api.salesforce.com/*"
HAL_ALLOW_MARKETING-ANALYTICS="https://api.googleanalytics.com/*"

# Engineering team APIs
HAL_SECRET_ENGINEERING-GITHUB_TOKEN=ghp_...
HAL_SECRET_ENGINEERING-JIRA_API_KEY=jira_key...
HAL_ALLOW_ENGINEERING-GITHUB="https://api.github.com/*"
HAL_ALLOW_ENGINEERING-JIRA="https://*.atlassian.net/*"

Ejemplos de Errores

Cuando se violan las restricciones de URL, se obtienen mensajes de error claros:

❌ Error: Secret 'azure.storage.access_key' (namespace: AZURE-STORAGE) is not allowed for URL 'https://api.github.com/user'. 
   Allowed patterns: https://*.blob.core.windows.net/*, https://*.queue.core.windows.net/*

Esto ayuda a identificar rápidamente:

Qué secreto fue bloqueado
Qué URL se intentó
Qué URLs están realmente permitidas

Referencia Rápida

Variable de Entorno	Uso en Plantilla	Restricción de URL
`HAL_SECRET_GITHUB_TOKEN`	`{secrets.github.token}`	`HAL_ALLOW_GITHUB`
`HAL_SECRET_AZURE-STORAGE_KEY`	`{secrets.azure.storage.key}`	`HAL_ALLOW_AZURE-STORAGE`
`HAL_SECRET_AWS-S3_ACCESS_KEY`	`{secrets.aws.s3.access_key}`	`HAL_ALLOW_AWS-S3`
`HAL_SECRET_GOOGLE-CLOUD_API_KEY`	`{secrets.google.cloud.api_key}`	`HAL_ALLOW_GOOGLE-CLOUD`

Patrón: HAL_SECRET_<NAMESPACE>_<KEY> → {secrets.<namespace>.<key>} + HAL_ALLOW_<NAMESPACE>

Compatibilidad Hacia Atrás

Los secretos sin espacio de nombres (sin restricciones de URL) continúan funcionando como antes:

HAL_SECRET_API_KEY=your-key
# Usage: {secrets.api_key} - works with any URL (no restrictions)

Filtrado de URLs

HAL admite filtrado global de URLs para controlar qué URLs se pueden acceder mediante patrones de lista blanca o lista negra. Esto proporciona una capa de seguridad adicional más allá de las restricciones de secretos basadas en espacios de nombres.

Modo Lista Blanca

Cuando se establece HAL_WHITELIST_URLS, solo se permiten las URLs que coinciden con los patrones especificados:

# Only allow requests to GitHub and Google APIs
HAL_WHITELIST_URLS="https://api.github.com/*,https://*.googleapis.com/*"

Modo Lista Negra

Cuando se establece HAL_BLACKLIST_URLS, todas las URLs están permitidas excepto aquellas que coinciden con los patrones especificados:

# Block requests to internal networks and localhost
HAL_BLACKLIST_URLS="http://localhost:*,https://192.168.*,https://10.*,https://172.16.*"

Sintaxis de Patrones

Los patrones de URL admiten coincidencias con comodines usando *:

https://api.example.com/* - Coincide con cualquier ruta bajo la API
https://*.example.com/* - Coincide con cualquier subdominio
*://internal.company.com/* - Coincide con cualquier protocolo

Notas Importantes

La lista blanca tiene prioridad: Si se establecen tanto HAL_WHITELIST_URLS como HAL_BLACKLIST_URLS, se usa la lista blanca y se registra una advertencia
Filtrado global: Esto se aplica a todas las solicitudes HTTP, independientemente de los secretos o herramientas utilizados
No distingue mayúsculas y minúsculas: La coincidencia de patrones de URL no distingue mayúsculas y minúsculas
Sin filtrado por defecto: Si no se establece ninguna variable de entorno, todas las URLs están permitidas

Ejemplos

# Production environment - only allow specific APIs
HAL_WHITELIST_URLS="https://api.stripe.com/*,https://*.googleapis.com/*,https://api.github.com/*"

# Development environment - block internal services
HAL_BLACKLIST_URLS="http://localhost:*,https://192.168.*,https://admin.internal.com/*"

# Restrictive setup - only allow HTTPS to specific domains
HAL_WHITELIST_URLS="https://api.trusted-service.com/*,https://webhooks.trusted-service.com/*"

Ejemplo de Uso

{
  "url": "https://api.github.com/user",
  "headers": {
    "Authorization": "Bearer {secrets.github_token}",
    "Accept": "application/vnd.github.v3+json"
  }
}

El {secrets.github_token} se reemplazará con el valor de la variable de entorno HAL_SECRET_GITHUB_TOKEN antes de realizar la solicitud.

Herramientas Disponibles

Herramientas HTTP Integradas

Estas herramientas están siempre disponibles independientemente de la configuración:

`list-secrets`

Obtenga una lista de claves secretas disponibles que se pueden usar con la sintaxis {secrets.key}.

Parámetros: Ninguno

Ejemplo de Respuesta:

Available secrets (3 total):

You can use these secret keys in your HTTP requests using the {secrets.key} syntax:

1. {secrets.api_key}
2. {secrets.github_token}  
3. {secrets.username}

Usage examples:
- URL: "https://api.example.com/data?token={secrets.api_key}"
- Header: {"Authorization": "Bearer {secrets.api_key}"}
- Body: {"username": "{secrets.username}"}

Nota de Seguridad: Solo muestra los nombres de las claves, nunca los valores secretos reales.

`http-get`

Realice solicitudes HTTP GET a cualquier URL.

Parámetros:

url (cadena, obligatorio): La URL a solicitar
headers (objeto, opcional): Encabezados adicionales para enviar

Ejemplo:

{
  "url": "https://api.github.com/user",
  "headers": {
    "Authorization": "Bearer {secrets.github_token}",
    "Accept": "application/vnd.github.v3+json"
  }
}

`http-post`

Realice solicitudes HTTP POST con cuerpo y encabezados opcionales.

Parámetros:

url (cadena, obligatorio): La URL a solicitar
body (cadena, opcional): Contenido del cuerpo de la solicitud
headers (objeto, opcional): Encabezados adicionales para enviar
contentType (cadena, opcional): Encabezado Content-Type (predeterminado: "application/json")

Ejemplo:

{
  "url": "https://api.example.com/data",
  "body": "{\"message\": \"Hello, World!\", \"user\": \"{secrets.username}\"}",
  "headers": {
    "Authorization": "Bearer {secrets.api_key}"
  },
  "contentType": "application/json"
}

Herramientas Swagger/OpenAPI Generadas Automáticamente

Cuando proporciona una especificación Swagger/OpenAPI a través de HAL_SWAGGER_FILE, HAL generará automáticamente herramientas para cada endpoint definido en la especificación. Estas herramientas se nombran usando el patrón swagger_{operationId} e incluyen:

Validación automática de parámetros basada en el esquema OpenAPI
Sustitución de parámetros de ruta (por ejemplo, /users/{id} → /users/123)
Manejo de parámetros de consulta
Soporte de cuerpo de solicitud para operaciones POST/PUT/PATCH
Mapeo adecuado de métodos HTTP

Por ejemplo, si su especificación OpenAPI define una operación con operationId: "getUser", HAL creará una herramienta llamada swagger_getUser que puede usar directamente.

Recursos Disponibles

`docs://hal/api`

Acceda a documentación integral de API y ejemplos de uso, incluida documentación para cualquier herramienta Swagger generada automáticamente.

Detalles de Integración OpenAPI/Swagger

Características OpenAPI Admitidas

✅ Especificaciones OpenAPI 3.x y Swagger 2.x
✅ Soporte de formato JSON y YAML
✅ Parámetros de ruta (/users/{id})
✅ Parámetros de consulta
✅ Cuerpo de solicitud (JSON, codificado en formulario)
✅ Todos los métodos HTTP (GET, POST, PUT, PATCH, DELETE, etc.)
✅ Validación de parámetros (cadena, número, booleano, matrices)
✅ Manejo de parámetros obligatorios/opcionales
✅ Soporte de encabezados personalizados

Ejemplo de Integración OpenAPI

Dada esta especificación OpenAPI:

openapi: 3.0.0
info:
  title: Example API
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /users/{id}:
    get:
      operationId: getUser
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success

HAL creará automáticamente una herramienta swagger_getUser que el LLM puede usar así:

{
  "id": "123"
}

Esto realizará una solicitud GET a https://api.example.com/v1/users/123.

Desarrollo

Requisitos Previos

Node.js 18 o posterior
npm o yarn

Configuración

# Clone the repository
git clone https://github.com/your-username/hal-mcp.git
cd hal-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

Scripts

npm run build - Compilar el proyecto TypeScript
npm run dev - Ejecutar en modo desarrollo con recarga automática
npm start - Iniciar el servidor compilado
npm run lint - Ejecutar ESLint
npm test - Ejecutar pruebas

Consideraciones de Seguridad

HAL realiza solicitudes HTTP reales a servicios externos
Use autenticación y autorización apropiadas para sus APIs
Tenga en cuenta los límites de velocidad y las cuotas de API
Considere la seguridad de red y las reglas de firewall
Al usar la integración Swagger, asegúrese de que sus especificaciones OpenAPI provengan de fuentes confiables

Contribuciones

Haga un fork del repositorio
Cree una rama de características (git checkout -b feature/amazing-feature)
Haga commit de sus cambios (git commit -m 'Add some amazing feature')
Haga push a la rama (git push origin feature/amazing-feature)
Abra una Solicitud de Extracción (Pull Request)

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulte el archivo LICENSE para más detalles.

Agradecimientos

Construido con el Model Context Protocol TypeScript SDK
Inspirado por la necesidad de que los LLM interactúen con APIs web de manera segura y eficiente
Integración OpenAPI impulsada por swagger-parser