JinDaGe - HAL MCP Details

article

README

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

📚 详细文档

完整文档 →

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

💻 使用示例

基础用法

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

高级用法

{
  "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 支持以下环境变量： | 属性 | 详情 | |------|------| | 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 请求中使用这些信息。

工作原理

环境变量：使用 HAL_SECRET_ 前缀定义密钥：

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

模板替换：在请求中使用 {secrets.key} 语法引用密钥：
- URL：https://api.example.com/data?token={secrets.token}
- 请求头：{"Authorization": "Bearer {secrets.api_key}"}
- 请求体：{"username": "{secrets.username}", "password": "{secrets.password}"}
安全性：AI 永远看不到实际的密钥值，仅看到模板占位符。值在请求时进行替换。

自动密钥隐藏

HAL 会自动从发送回 AI 的所有响应中隐藏密钥值，为防止凭证泄露提供了额外的安全层。

工作原理

密钥跟踪：HAL 维护一个从环境变量中获取的所有密钥值的注册表。
响应扫描：扫描所有 HTTP 响应（请求头、请求体、错误消息）以查找密钥值。
自动替换：在将响应发送给 AI 之前，将实际密钥值的任何出现都替换为 [REDACTED]。
全面覆盖：隐藏适用于：
- 错误消息（包括可能暴露凭证的 URL 解析错误）
- 响应头（以防 API 回显身份验证数据）
- 响应体（防止 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/*"

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.*"

可用工具

内置 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/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

安装步骤

# 克隆仓库
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 - 运行测试

⚠️ 安全注意事项

⚠️ 重要提示

HAL 会向外部服务发起实际的 HTTP 请求。

为你的 API 使用适当的身份验证和授权。

注意速率限制和 API 配额。

考虑网络安全和防火墙规则。

使用 Swagger 集成时，确保你的 OpenAPI 规范来自可信来源。

🤝 贡献指南

Fork 仓库。
创建功能分支 (git checkout -b feature/amazing-feature)。
提交更改 (git commit -m 'Add some amazing feature')。
推送到分支 (git push origin feature/amazing-feature)。
打开 Pull Request。

📄 许可证

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

🙏 致谢

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

HAL

README

🚀 HAL (HTTP API Layer)

🚀 快速开始

基础用法（Claude Desktop）

集成 Swagger/OpenAPI 并使用密钥

直接使用

✨ 主要特性

📚 详细文档

💻 使用示例

基础用法

高级用法

🔧 技术细节

配置

密钥管理

工作原理

自动密钥隐藏

工作原理

命名空间和 URL 限制

命名空间约定

URL 限制

URL 过滤

白名单模式

黑名单模式

可用工具

内置 HTTP 工具

list-secrets

http-get

http-post

自动生成的 Swagger/OpenAPI 工具

OpenAPI/Swagger 集成细节

支持的 OpenAPI 特性

示例 OpenAPI 集成

📦 安装指南

前提条件

安装步骤

脚本命令

⚠️ 安全注意事项

🤝 贡献指南

📄 许可证

🙏 致谢

Runtime guide

Hosted runtime

Local runtime / other methods

`list-secrets`

`http-get`

`http-post`