HAL (HTTP API 层)

HAL 是一个提供 HTTP API 能力给大型语言模型的 Model Context Protocol (MCP) 服务器。它允许 LLM 通过安全、受控的接口进行 HTTP 请求并与其他 Web API 进行交互。HAL 还可以从 OpenAPI/Swagger 规范自动生成工具，实现无缝的 API 集成。

文档

完整文档 →

访问我们的综合文档网站以获取详细的指南、示例和 API 参考。

特性

• HTTP GET/POST/PUT/PATCH/DELETE/OPTIONS/HEAD 请求：从任何 HTTP 端点获取和发送数据
• 安全的秘密管理：基于环境的秘密，并使用 {secrets.key} 替换和自动删除
• Swagger/OpenAPI 集成：自动从 API 规范生成工具
• 内置文档：自我记录的 API 参考
• 安全：在隔离环境中运行，具有受控访问权限
• 快速：使用 TypeScript 构建并优化性能

使用方法

HAL 设计用于与兼容 MCP 的客户端一起工作。以下是一些示例：

基本用法（Claude Desktop）

将 HAL 添加到您的 Claude Desktop 配置中（npx 将自动安装并运行 HAL）：

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

结合 Swagger/OpenAPI 集成和秘密

要启用从 OpenAPI 规范自动生成工具并使用秘密：

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

基于 URL 的配置

您还可以直接从 URL 加载 OpenAPI 规范：

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

直接使用

# 启动默认工具的 HAL 服务器
npx hal-mcp

# 或结合 Swagger/OpenAPI 集成
HAL_SWAGGER_FILE=/path/to/api.yaml HAL_API_BASE_URL=https://api.example.com npx hal-mcp

# 或从 URL 加载
HAL_SWAGGER_FILE=/swagger/v1/swagger.json HAL_API_BASE_URL=http://localhost:5065 npx hal-mcp

配置

HAL 支持以下环境变量：

• HAL_SWAGGER_FILE：指向 OpenAPI/Swagger 规范文件的路径或 URL（JSON 或 YAML 格式）。可以是：
  • 本地文件路径：/path/to/api.yaml
  • 完整 URL：https://api.example.com/swagger.json
  • 相对路径：/swagger/v1/swagger.json（与 HAL_API_BASE_URL 组合）
• HAL_API_BASE_URL：API 请求的基本 URL（覆盖 OpenAPI 规范中的服务器指定）
• HAL_SECRET_*：请求中安全替换的秘密值（例如，HAL_SECRET_TOKEN=abc123）
• HAL_ALLOW_*：命名空间秘密的 URL 限制（例如，HAL_ALLOW_MICROSOFT="https://azure.microsoft.com/*"）
• HAL_WHITELIST_URLS：允许的 URL 模式的逗号分隔列表（如果设置，则仅允许这些 URL）
• HAL_BLACKLIST_URLS：阻止的 URL 模式的逗号分隔列表（如果设置，则阻止这些 URL）

秘密管理

HAL 提供安全的秘密管理，使敏感信息如 API 密钥、令牌和密码不暴露在对话中，同时仍允许 AI 在 HTTP 请求中使用它们。

工作原理

1. 环境变量：使用 HAL_SECRET_ 前缀定义秘密：

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

2. 模板替换：在请求中使用 {secrets.key} 语法引用秘密：

   • URL：https://api.example.com/data?token={secrets.token}
   • 头部：{"Authorization": "Bearer {secrets.api_key}"}
   • 请求体：{"username": "{secrets.username}", "password": "{secrets.password}"}

3. 安全性：AI 从未看到实际的秘密值，只看到模板占位符。值在请求时替换。

自动秘密删除

HAL 自动从返回给 AI 的所有响应中删除秘密值，提供额外的安全层以防止凭据泄露。

工作原理

1. 秘密跟踪：HAL 维护来自环境变量的所有秘密值的注册表
2. 响应扫描：扫描所有 HTTP 响应（头部、主体、错误消息）中的秘密值
3. 自动替换：在发送给 AI 之前，将实际秘密值替换为 [REDACTED]
4. 全面覆盖：删除应用于：
   • 错误消息（包括可能暴露凭据的 URL 解析错误）
   • 响应头部（以防 API 回显身份验证数据）
   • 响应主体（保护 API 响应可能包含敏感数据的情况）
   • 返回给 AI 的所有其他文本

示例保护

之前（易受攻击）：

错误：无法从包含凭据的 URL 构造请求：
https://65GQiI8-1JCOWV1KAuYr0g:-VOIfpydl2GWfucCdEJ1BJ2vrsJyjQ@www.reddit.com/api/v1/access_token

之后（安全）：

错误：无法从包含凭据的 URL 构造请求：
https://[REDACTED]:[REDACTED]@www.reddit.com/api/v1/access_token

这种保护是自动的，不需要配置——无论响应中如何出现，HAL 都会删除任何秘密值，确保即使 API 或错误消息试图暴露凭据，AI 也永远不会看到实际值。

命名空间和 URL 限制

HAL 支持将秘密组织成命名空间，并将其限制为特定 URL 以增强安全性：

命名空间约定

使用 - 分隔命名空间，使用 _ 分隔键内的单词：

# 单一命名空间
HAL_SECRET_MICROSOFT_API_KEY=your-api-key
# 使用：{secrets.microsoft.api_key}

# 多级命名空间
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
# 使用：{secrets.azure.storage.access_key}
# 使用：{secrets.azure.cognitive.api_key}
# 使用：{secrets.google.cloud.storage.service_account_key}

URL 限制

使用 HAL_ALLOW_* 环境变量将命名空间秘密限制为特定 URL：

# 限制 Microsoft 秘密到 Microsoft 域
HAL_SECRET_MICROSOFT_API_KEY=your-api-key
HAL_ALLOW_MICROSOFT="https://azure.microsoft.com/*,https://*.microsoft.com/*"

# 限制 Azure 存储秘密到 Azure 存储端点
HAL_SECRET_AZURE-STORAGE_ACCESS_KEY=your-storage-key
HAL_ALLOW_AZURE-STORAGE="https://*.blob.core.windows.net/*,https://*.queue.core.windows.net/*"

# 多个 URL 用逗号分隔
HAL_SECRET_GOOGLE-CLOUD_API_KEY=your-google-key
HAL_ALLOW_GOOGLE-CLOUD="https://*.googleapis.com/*,https://*.googlecloud.com/*"

如何解析

理解环境变量名称如何成为模板键：

HAL_SECRET_AZURE-STORAGE_ACCESS_KEY
│         │              │
│         │              └─ 键："ACCESS_KEY" → "access_key" 
│         └─ 命名空间："AZURE-STORAGE" → "azure.storage"
└─ 前缀

最终模板：{secrets.azure.storage.access_key}

逐步分解：

1. 删除 HAL_SECRET_ 前缀 → AZURE-STORAGE_ACCESS_KEY
2. 按第一个 _ 分割 → 命名空间：AZURE-STORAGE，键：ACCESS_KEY
3. 转换命名空间：AZURE-STORAGE → azure.storage（破折号变为点，小写）
4. 转换键：ACCESS_KEY → access_key（下划线保留，小写）
5. 组合：{secrets.azure.storage.access_key}

更多示例

# 简单命名空间
HAL_SECRET_GITHUB_TOKEN=your_token
→ {secrets.github.token}

# 两级命名空间  
HAL_SECRET_AZURE-COGNITIVE_API_KEY=your_key
→ {secrets.azure.cognitive.api_key}

# 三级命名空间
HAL_SECRET_GOOGLE-CLOUD-STORAGE_SERVICE_ACCOUNT=your_account
→ {secrets.google.cloud.storage.service_account}

# 复杂键带有下划线
HAL_SECRET_AWS-S3_BUCKET_ACCESS_KEY_ID=your_id
→ {secrets.aws.s3.bucket_access_key_id}

# 无命名空间（旧风格）
HAL_SECRET_API_KEY=your_key
→ {secrets.api_key}

视觉指南：完整流程

环境变量          模板使用                   URL 限制
├─ 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}   └─ （无限制）

安全优势

• 最小特权原则：秘密仅适用于其预期服务
• 防止跨服务泄漏：Azure 秘密不能发送到 AWS API
• 纵深防御：即使有 AI 错误或提示注入，秘密也是受限的
• 清晰组织：命名空间结构使秘密管理更直观

实际使用场景

场景 1：多云应用

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

请求中的使用：

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

✅ 有效：URL 匹配 Azure 存储模式
❌ 阻止：如果用于 https://s3.amazonaws.com/bucket - 错误的服务！

场景 2：开发 vs 生产

# 开发环境
HAL_SECRET_DEV-API_KEY=dev_key_123
HAL_ALLOW_DEV-API="https://dev-api.example.com/*,https://staging-api.example.com/*"

# 生产环境  
HAL_SECRET_PROD-API_KEY=prod_key_456
HAL_ALLOW_PROD-API="https://api.example.com/*"

场景 3：部门隔离

# 营销团队 API
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/*"

# 工程团队 API
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/*"

错误示例

当 URL 限制被违反时，您会收到明确的错误消息：

❌ 错误：秘密 'azure.storage.access_key'（命名空间：AZURE-STORAGE）不允许用于 URL 'https://api.github.com/user'。 
   允许的模式：https://*.blob.core.windows.net/*, https://*.queue.core.windows.net/*

这有助于您快速识别：

• 哪个秘密被阻止了
• 尝试访问的 URL
• 实际允许的 URL

快速参考

环境变量	模板使用	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

模式：HAL_SECRET_<NAMESPACE>_<KEY> → {secrets.<namespace>.<key>} + HAL_ALLOW_<NAMESPACE>

向后兼容性

非命名空间的秘密（没有 URL 限制）继续像以前一样工作：

HAL_SECRET_API_KEY=your-key
# 使用：{secrets.api_key} - 适用于任何 URL（无限制）

URL 过滤

HAL 支持全局 URL 过滤，以控制可以通过白名单或黑名单模式访问哪些 URL。这提供了超出命名空间基础秘密限制的额外安全层。

白名单模式

当设置 HAL_WHITELIST_URLS 时，只有匹配指定模式的 URL 才被允许：

# 只允许对 GitHub 和 Google API 的请求
HAL_WHITELIST_URLS="https://api.github.com/*,https://*.googleapis.com/*"

黑名单模式

当设置 HAL_BLACKLIST_URLS 时，所有 URL 都被允许除了那些匹配指定模式的 URL：

# 阻止对内部网络和 localhost 的请求
HAL_BLACKLIST_URLS="http://localhost:*,https://192.168.*,https://10.*,https://172.16.*"

模式语法

URL 模式支持使用 * 的通配符匹配：

• https://api.example.com/* - 匹配 API 下的任何路径
• https://*.example.com/* - 匹配任何子域
• *://internal.company.com/* - 匹配任何协议

重要说明

• 白名单优先：如果同时设置了 HAL_WHITELIST_URLS 和 HAL_BLACKLIST_URLS，则使用白名单并记录警告
• 全局过滤：此过滤应用于所有 HTTP 请求，无论使用什么秘密或工具
• 大小写不敏感：URL 模式匹配是大小写不敏感的
• 默认无过滤：如果未设置任一环境变量，则允许所有 URL

示例

# 生产环境 - 只允许特定 API
HAL_WHITELIST_URLS="https://api.stripe.com/*,https://*.googleapis.com/*,https://api.github.com/*"

# 开发环境 - 阻止内部服务
HAL_BLACKLIST_URLS="http://localhost:*,https://192.168.*,https://admin.internal.com/*"

# 严格设置 - 只允许 HTTPS 到特定域
HAL_WHITELIST_URLS="https://api.trusted-service.com/*,https://webhooks.trusted-service.com/*"

示例使用

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

在发出请求前，{secrets.github_token} 将被替换为 HAL_SECRET_GITHUB_TOKEN 环境变量的值。

可用工具

内置 HTTP 工具

这些工具始终可用，无论配置如何：

list-secrets

获取可用于 {secrets.key} 语法的秘密键列表。

参数：无

示例响应：

可用秘密（总计 3 个）：

您可以在 HTTP 请求中使用这些秘密键，使用 {secrets.key} 语法：

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