Hal (http Api Layer)

HAL（HTTP API 层）

HAL 是一种模型上下文协议（MCP）服务，可为大语言模型提供 HTTP API 功能。它允许大模型通过安全、受控的接口发送 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"
      }
    }
  }
}

直接使用

# 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

配置

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 规范中指定的 servers）
• 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:[email protected]/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，以增强安全性：

命名空间约定

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

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

URL 限制

使用 HAL_ALLOW_* 环境变量，将命名空间密钥限制为仅适用于特定 URL：

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

解析方式

了解环境变量名称如何转换为模板键：

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

Final template: {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}

更多示例

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

图示：完整流程

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)

安全优势

• 最小权限原则：密钥只能用于预期的服务
• 防止跨服务泄露：Azure 密钥无法发送到 AWS API
• 纵深防御：即使出现 AI 错误或提示词注入，密钥也会受到限制
• 清晰整理：命名空间结构让密钥管理更直观

实际使用场景

场景 1：多云应用

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

在请求中的用法：

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

✅ 可用：URL 符合 Azure Storage 模式
❌ 被阻止：如果用于 https://s3.amazonaws.com/bucket——服务不匹配！

场景 2：开发环境与生产环境

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

场景 3：部门隔离

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

错误示例

违反 URL 限制时，你会收到清晰的错误消息：

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

这有助于你快速识别：

• 被阻止的密钥
• 尝试访问的 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
# Usage: {secrets.api_key} - works with any URL (no restrictions)

URL 过滤

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

白名单模式

设置 HAL_WHITELIST_URLS 后，仅允许与指定模式匹配的 URL：

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

黑名单模式

设置 HAL_BLACKLIST_URLS 时，除与指定模式匹配的网址外，所有网址都允许访问：

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

模式语法

网址模式支持使用 * 进行通配符匹配：

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

重要说明

• 白名单优先：如果同时设置了 HAL_WHITELIST_URLS 和 HAL_BLACKLIST_URLS，则使用白名单，并记录一条警告
• 全局过滤：此设置适用于所有 HTTP 请求，无论使用了哪些密钥或工具
• 不区分大小写：网址模式匹配不区分大小写
• 默认不进行过滤：如果未设置这两个环境变量中的任何一个，则允许访问所有网址

示例

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

使用示例

{
  "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} 语法搭配使用的可用密钥列表。

**参数：**无

示例响应：

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

**安全说明：**只显示密钥名称，不会显示实际的密钥值。

http-get

向任意网址发送 HTTP GET 请求。

参数：

• 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（字符串，必填）：要请求的网址
• 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 工具，供大模型如下使用：

{
  "id": "123"
}

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

开发

先决条件

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

设置

# 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

脚本

• npm run build - 构建 TypeScript 项目
• npm run dev - 以开发模式运行并启用热重载
• npm start - 启动构建后的服务
• npm run lint - 运行 ESLint
• npm test - 运行测试

安全注意事项

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

贡献

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交你的更改（git commit -m 'Add some amazing feature'）
4. 将更改推送到分支（git push origin feature/amazing-feature）
5. 发起 Pull Request

许可证

此项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

致谢

• 基于 Model Context Protocol TypeScript SDK 构建
• 灵感源于让大模型安全、高效地与 Web API 交互的需求
• OpenAPI 集成由 swagger-parser 提供支持