Hal

🚀 HAL (HTTP API Layer)

HAL 是一个模型上下文协议（MCP）服务器，为大语言模型提供 HTTP API 功能。它允许大语言模型通过安全、可控的接口进行 HTTP 请求，并与 Web API 进行交互。此外，HAL 还能根据 OpenAPI/Swagger 规范自动生成工具，实现无缝的 API 集成。

🚀 快速开始

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

直接使用

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

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

✨ 主要特性

• 支持多种 HTTP 请求方法：支持 HTTP GET/POST/PUT/PATCH/DELETE/OPTIONS/HEAD 请求，可从任何 HTTP 端点获取和发送数据。
• 安全的密钥管理：基于环境变量的密钥管理，支持 {secrets.key} 替换，并自动隐藏密钥。
• Swagger/OpenAPI 集成：可根据 API 规范自动生成工具。
• 内置文档：API 具备自文档化的参考说明。
• 安全性高：在隔离环境中运行，访问受严格控制。
• 性能卓越：采用 TypeScript 构建，经过性能优化。

📦 安装指南

开发环境准备

• Node.js 18 或更高版本
• npm 或 yarn

安装步骤

# 克隆仓库
git clone https://github.com/your-username/hal-mcp.git
cd hal-mcp

# 安装依赖
npm install

# 构建项目
npm run build

# 以开发模式运行
npm run dev

脚本说明

• npm run build：构建 TypeScript 项目。
• npm run dev：以热重载模式进行开发。
• npm start：启动已构建的服务器。
• npm run lint：运行 ESLint 代码检查。
• npm test：运行测试。

📚 详细文档

完整文档 →

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

🔧 技术细节

配置

HAL 支持以下环境变量：

属性	详情
HAL_SWAGGER_FILE	OpenAPI/Swagger 规范文件的路径（JSON 或 YAML 格式）
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 的其他文本

保护示例

之前（存在安全风险）：

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

之后（安全）：

Error: Request cannot be constructed from a URL that includes credentials: 
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 Storage 密钥限制在 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：开发环境与生产环境

# 开发环境
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：

# 阻止访问内部网络和本地主机
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.username}

使用示例：
- URL: "https://api.example.com/data?token={secrets.api_key}"
- 请求头: {"Authorization": "Bearer {secrets.api_key}"}
- 请求体: {"username": "{secrets.username}"}

安全说明：仅显示密钥名称，从不显示实际的密钥值。

http-get

向任何 URL 发出 HTTP GET 请求。 参数：

• url（字符串，必需）：请求的 URL
• headers（对象，可选）：要发送的额外请求头 示例：

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

http-post

发出带有可选请求体和请求头的 HTTP POST 请求。 参数：

• url（字符串，必需）：请求的 URL
• body（字符串，可选）：请求体内容
• headers（对象，可选）：要发送的额外请求头
• contentType（字符串，可选）：Content-Type 请求头（默认："application/json"） 示例：

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

自动生成的 Swagger/OpenAPI 工具

通过 HAL_SWAGGER_FILE 提供 Swagger/OpenAPI 规范时，HAL 将为规范中定义的每个端点自动生成工具。这些工具的命名模式为 swagger_{operationId}，并包括：

• 自动参数验证：基于 OpenAPI 模式进行验证。
• 路径参数替换：（例如，/users/{id} → /users/123）
• 查询参数处理
• 请求体支持：支持 POST/PUT/PATCH 操作。
• 正确的 HTTP 方法映射

例如，如果你的 OpenAPI 规范定义了一个 operationId 为 "getUser" 的操作，HAL 将创建一个名为 swagger_getUser 的工具，你可以直接使用。

可用资源

docs://hal/api

访问全面的 API 文档和使用示例，包括任何自动生成的 Swagger 工具的文档。

OpenAPI/Swagger 集成细节

支持的 OpenAPI 特性

• ✅ OpenAPI 3.x 和 Swagger 2.x 规范
• ✅ JSON 和 YAML 格式支持
• ✅ 路径参数（/users/{id}）
• ✅ 查询参数
• ✅ 请求体（JSON、表单编码）
• ✅ 所有 HTTP 方法（GET、POST、PUT、PATCH、DELETE 等）
• ✅ 参数验证（字符串、数字、布尔值、数组）
• ✅ 必需/可选参数处理
• ✅ 自定义请求头支持

示例 OpenAPI 集成

给定以下 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 将自动创建一个 swagger_getUser 工具，LLM 可以这样使用：

{
  "id": "123"
}

这将向 https://api.example.com/v1/users/123 发出 GET 请求。

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

致谢

• 基于 Model Context Protocol TypeScript SDK 构建。
• 受大语言模型安全高效地与 Web API 交互的需求启发。
• OpenAPI 集成由 swagger-parser 提供支持。

⚠️ 重要提示

• HAL 会向外部服务发出实际的 HTTP 请求，请为你的 API 使用适当的身份验证和授权。
• 注意速率限制和 API 配额。
• 考虑网络安全和防火墙规则。
• 使用 Swagger 集成时，确保你的 OpenAPI 规范来自可信来源。

💡 使用建议

• 在开发和测试阶段，建议使用开发环境的密钥和配置，避免使用生产环境的敏感信息。
• 定期审查和更新密钥，以确保安全性。
• 在使用 URL 过滤时，仔细规划白名单和黑名单，避免误阻止或允许不必要的访问。