HAL (HTTP API Layer)

Um servidor MCP que permite que Modelos de Linguagem de Grande Escala façam requisições HTTP e interajam com APIs web. Ele suporta geração automática de ferramentas a partir de especificações OpenAPI/Swagger.

GitHub

Experimente este MCPPatrocinado

Documentação

HAL (HTTP API Layer)

O HAL é um servidor Model Context Protocol (MCP) que fornece capacidades de API HTTP para Modelos de Linguagem de Grande Porte (LLMs). Ele permite que LLMs façam requisições HTTP e interajam com APIs web através de uma interface segura e controlada. O HAL também pode gerar automaticamente ferramentas a partir de especificações OpenAPI/Swagger para integração perfeita com APIs.

Documentação

Documentação Completa →

Visite nosso site de documentação abrangente para guias detalhados, exemplos e referência de API.

Recursos

Requisições HTTP GET/POST/PUT/PATCH/DELETE/OPTIONS/HEAD: Busque e envie dados para qualquer endpoint HTTP
Gerenciamento Seguro de Segredos: Segredos baseados em variáveis de ambiente com substituição {secrets.key} e redação automática
Integração Swagger/OpenAPI: Gere ferramentas automaticamente a partir de especificações de API
Documentação Integrada: Referência de API autodocumentada
Seguro: Executa em ambiente isolado com acesso controlado
Rápido: Construído com TypeScript e otimizado para desempenho

Uso

O HAL foi projetado para funcionar com clientes compatíveis com MCP. Aqui estão alguns exemplos:

Uso Básico (Claude Desktop)

Adicione o HAL à sua configuração do Claude Desktop (o npx instalará e executará o HAL automaticamente):

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

Com Integração Swagger/OpenAPI e Segredos

Para habilitar a geração automática de ferramentas a partir de uma especificação OpenAPI e usar segredos:

{
  "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"
      }
    }
  }
}

Configuração Baseada em URL

Você também pode carregar especificações OpenAPI diretamente de 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 Direto

# 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

Configuração

O HAL suporta as seguintes variáveis de ambiente:

HAL_SWAGGER_FILE: Caminho ou URL para o arquivo de especificação OpenAPI/Swagger (formato JSON ou YAML). Pode ser:
- Caminho de arquivo local: /path/to/api.yaml
- URL completa: https://api.example.com/swagger.json
- Caminho relativo: /swagger/v1/swagger.json (combinado com HAL_API_BASE_URL)
HAL_API_BASE_URL: URL base para requisições de API (substitui os servidores especificados na especificação OpenAPI)
HAL_SECRET_*: Valores de segredos para substituição segura em requisições (ex.: HAL_SECRET_TOKEN=abc123)
HAL_ALLOW_*: Restrições de URL para segredos com namespace (ex.: HAL_ALLOW_MICROSOFT="https://azure.microsoft.com/*")
HAL_WHITELIST_URLS: Lista separada por vírgulas de padrões de URL permitidos (se definido, apenas essas URLs são permitidas)
HAL_BLACKLIST_URLS: Lista separada por vírgulas de padrões de URL bloqueados (se definido, essas URLs são negadas)

Gerenciamento de Segredos

O HAL fornece gerenciamento seguro de segredos para manter informações sensíveis como chaves de API, tokens e senhas fora da conversa, permitindo que a IA os utilize em requisições HTTP.

Como Funciona

Variáveis de Ambiente: Defina segredos usando o prefixo HAL_SECRET_:

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

Substituição de Template: Referencie segredos em suas requisições usando a sintaxe {secrets.key}:
- URLs: https://api.example.com/data?token={secrets.token}
- Cabeçalhos: {"Authorization": "Bearer {secrets.api_key}"}
- Corpos de Requisição: {"username": "{secrets.username}", "password": "{secrets.password}"}
Segurança: A IA nunca vê os valores reais dos segredos, apenas os placeholders do template. Os valores são substituídos no momento da requisição.

Redação Automática de Segredos

O HAL redige automaticamente os valores de segredos de todas as respostas enviadas de volta à IA, fornecendo uma camada adicional de segurança contra exposição de credenciais.

Como Funciona

Rastreamento de Segredos: O HAL mantém um registro de todos os valores de segredos das variáveis de ambiente
Verificação de Respostas: Todas as respostas HTTP (cabeçalhos, corpos, mensagens de erro) são verificadas em busca de valores de segredos
Substituição Automática: Qualquer ocorrência de valores reais de segredos é substituída por [REDACTED] antes do envio à IA
Cobertura Abrangente: A redação se aplica a:
- Mensagens de erro (incluindo erros de parsing de URL que possam expor credenciais)
- Cabeçalhos de resposta (caso APIs ecoem dados de autenticação)
- Corpos de resposta (protegendo contra respostas de API que possam incluir dados sensíveis)
- Todo outro texto retornado à IA

Exemplo de Proteção

Antes (vulnerável):

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

Depois (seguro):

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

Essa proteção é automática e não requer configuração — o HAL redigirá quaisquer valores de segredos, independentemente de como apareçam nas respostas, garantindo que, mesmo que uma API ou mensagem de erro tente expor credenciais, a IA nunca veja os valores reais.

Namespaces e Restrições de URL

O HAL suporta a organização de segredos em namespaces e a restrição deles a URLs específicas para maior segurança:

Convenção de Namespace

Use - para separadores de namespace e _ para separadores de palavras dentro das chaves:

# 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}

Restrições de URL

Restrinja segredos com namespace a URLs específicas usando variáveis de ambiente 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/*"

Como Funciona o Parsing

Entendendo como nomes de variáveis de ambiente se tornam chaves de template:

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

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

Análise passo a passo:

Remova o prefixo HAL_SECRET_ → AZURE-STORAGE_ACCESS_KEY
Divida no primeiro _ → Namespace: AZURE-STORAGE, Chave: ACCESS_KEY
Transforme o namespace: AZURE-STORAGE → azure.storage (travessões viram pontos, minúsculas)
Transforme a chave: ACCESS_KEY → access_key (underscores permanecem, minúsculas)
Combine: {secrets.azure.storage.access_key}

Mais Exemplos

# 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}

Guia Visual: Fluxo 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)

Benefícios de Segurança

Princípio do Menor Privilégio: Segredos funcionam apenas com seus serviços pretendidos
Previne Vazamento Entre Serviços: Segredos do Azure não podem ser enviados para APIs da AWS
Defesa em Profundidade: Mesmo com erros de IA ou injeção de prompt, os segredos são restritos
Organização Clara: A estrutura de namespace torna o gerenciamento de segredos mais intuitivo

Cenários de Uso no Mundo Real

Cenário 1: Aplicação Multi-Nuvem

# 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 em requisições:

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

✅ Funciona: URL corresponde ao padrão do Azure Storage
❌ Bloqueado: Se usado com https://s3.amazonaws.com/bucket - serviço errado!

Cenário 2: Desenvolvimento vs Produção

# 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/*"

Cenário 3: Isolamento por Departamento

# 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/*"

Exemplos de Erro

Quando as restrições de URL são violadas, você recebe mensagens de erro claras:

❌ 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/*

Isso ajuda você a identificar rapidamente:

Qual segredo foi bloqueado
Qual URL foi tentada
Quais URLs são realmente permitidas

Referência Rápida

Variável de Ambiente	Uso no Template	Restrição 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`

Padrão: HAL_SECRET_<NAMESPACE>_<KEY> → {secrets.<namespace>.<key>} + HAL_ALLOW_<NAMESPACE>

Compatibilidade Retroativa

Segredos sem namespace (sem restrições de URL) continuam funcionando como antes:

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

Filtragem de URL

O HAL suporta filtragem global de URL para controlar quais URLs podem ser acessadas por meio de padrões de lista de permissões ou lista de bloqueios. Isso fornece uma camada adicional de segurança além das restrições de segredos baseadas em namespace.

Modo Lista de Permissões

Quando HAL_WHITELIST_URLS é definido, apenas URLs que correspondem aos padrões especificados são permitidas:

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

Modo Lista de Bloqueios

Quando HAL_BLACKLIST_URLS é definido, todas as URLs são permitidas exceto aquelas que correspondem aos padrões especificados:

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

Sintaxe de Padrões

Os padrões de URL suportam correspondência com curingas usando *:

https://api.example.com/* - Corresponde a qualquer caminho sob a API
https://*.example.com/* - Corresponde a qualquer subdomínio
*://internal.company.com/* - Corresponde a qualquer protocolo

Notas Importantes

A lista de permissões tem precedência: Se tanto HAL_WHITELIST_URLS quanto HAL_BLACKLIST_URLS forem definidos, a lista de permissões é usada e um aviso é registrado
Filtragem global: Isso se aplica a todas as requisições HTTP, independentemente de segredos ou ferramentas usadas
Insensível a maiúsculas/minúsculas: A correspondência de padrões de URL não diferencia maiúsculas de minúsculas
Sem filtragem por padrão: Se nenhuma das variáveis de ambiente for definida, todas as URLs são permitidas

Exemplos

# 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/*"

Exemplo de Uso

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

O {secrets.github_token} será substituído pelo valor da variável de ambiente HAL_SECRET_GITHUB_TOKEN antes de fazer a requisição.

Ferramentas Disponíveis

Ferramentas HTTP Integradas

Essas ferramentas estão sempre disponíveis, independentemente da configuração:

`list-secrets`

Obtenha uma lista de chaves de segredos disponíveis que podem ser usadas com a sintaxe {secrets.key}.

Parâmetros: Nenhum

Exemplo de Resposta:

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 Segurança: Mostra apenas os nomes das chaves, nunca os valores reais dos segredos.

`http-get`

Faça requisições HTTP GET para qualquer URL.

Parâmetros:

url (string, obrigatório): A URL a ser requisitada
headers (objeto, opcional): Cabeçalhos adicionais a enviar

Exemplo:

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

`http-post`

Faça requisições HTTP POST com corpo e cabeçalhos opcionais.

Parâmetros:

url (string, obrigatório): A URL a ser requisitada
body (string, opcional): Conteúdo do corpo da requisição
headers (objeto, opcional): Cabeçalhos adicionais a enviar
contentType (string, opcional): Cabeçalho Content-Type (padrão: "application/json")

Exemplo:

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

Ferramentas Swagger/OpenAPI Geradas Automaticamente

Quando você fornece uma especificação Swagger/OpenAPI via HAL_SWAGGER_FILE, o HAL gerará automaticamente ferramentas para cada endpoint definido na especificação. Essas ferramentas são nomeadas usando o padrão swagger_{operationId} e incluem:

Validação automática de parâmetros baseada no esquema OpenAPI
Substituição de parâmetros de caminho (ex.: /users/{id} → /users/123)
Tratamento de parâmetros de consulta
Suporte a corpo de requisição para operações POST/PUT/PATCH
Mapeamento adequado de métodos HTTP

Por exemplo, se sua especificação OpenAPI define uma operação com operationId: "getUser", o HAL criará uma ferramenta chamada swagger_getUser que você pode usar diretamente.

Recursos Disponíveis

`docs://hal/api`

Acesse documentação abrangente da API e exemplos de uso, incluindo documentação para quaisquer ferramentas Swagger geradas automaticamente.

Detalhes da Integração OpenAPI/Swagger

Recursos OpenAPI Suportados

✅ Especificações OpenAPI 3.x e Swagger 2.x
✅ Suporte aos formatos JSON e YAML
✅ Parâmetros de caminho (/users/{id})
✅ Parâmetros de consulta
✅ Corpo de requisição (JSON, codificado em formulário)
✅ Todos os métodos HTTP (GET, POST, PUT, PATCH, DELETE, etc.)
✅ Validação de parâmetros (string, número, booleano, arrays)
✅ Tratamento de parâmetros obrigatórios/opcionais
✅ Suporte a cabeçalhos personalizados

Exemplo de Integração OpenAPI

Dada esta especificação 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

O HAL criará automaticamente uma ferramenta swagger_getUser que o LLM pode usar assim:

{
  "id": "123"
}

Isso fará uma requisição GET para https://api.example.com/v1/users/123.

Desenvolvimento

Pré-requisitos

Node.js 18 ou posterior
npm ou yarn

Configuração

# 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 - Compila o projeto TypeScript
npm run dev - Executa em modo de desenvolvimento com recarga automática
npm start - Inicia o servidor compilado
npm run lint - Executa o ESLint
npm test - Executa os testes

Considerações de Segurança

O HAL faz requisições HTTP reais a serviços externos
Use autenticação e autorização apropriadas para suas APIs
Esteja atento aos limites de taxa e cotas de API
Considere a segurança de rede e regras de firewall
Ao usar a integração Swagger, garanta que suas especificações OpenAPI sejam de fontes confiáveis

Contribuindo

Faça um fork do repositório
Crie um branch de funcionalidade (git checkout -b feature/amazing-feature)
Faça commit das suas alterações (git commit -m 'Add some amazing feature')
Envie para o branch (git push origin feature/amazing-feature)
Abra um Pull Request

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.

Agradecimentos

Construído com o Model Context Protocol TypeScript SDK
Inspirado pela necessidade de LLMs interagirem com APIs web de forma segura e eficiente
Integração OpenAPI alimentada por swagger-parser