Hal MCP

](https://lobehub.com/mcp/deanward-hal)

HAL（HTTP API层）

HAL是一个模型上下文协议（MCP）服务器，为大型语言模型提供HTTP API功能。它允许大型语言模型通过安全、受控的接口发出HTTP请求并与网络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 桌面版）

在您的Claude Desktop配置中添加HAL（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_FILEOpenAPI/Swagger 规范文件（JSON 或 YAML 格式）的路径或 URL。可以是：

- 本地文件路径： /path/to/api.yaml - 完整URL： https://api.example.com/swagger.json - 相对路径： /swagger/v1/swagger.json （与……结合 HAL_API_BASE_URL）

• HAL_API_BASE_URLAPI请求的基础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

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

- 网址（URLs）: https://api.example.com/data?token={secrets.token} - 标题（或头部信息）： {"Authorization": "Bearer {secrets.api_key}"} - 请求体： {"username": "{secrets.username}", "password": "{secrets.password}"}

1. 安全人工智能从未见过实际的机密值，只看到模板占位符。值在请求时被替换。

自动隐去秘密信息

HAL会自动从发送给AI的所有响应中删除敏感值，为防止凭证泄露提供了额外的安全保障层。

它是如何工作的

1. 秘密追踪HAL 维护一个包含所有环境变量中秘密值的注册表
2. 响应扫描所有HTTP响应（包括头部、主体、错误信息）都会被扫描以查找秘密值
3. 自动替换任何实际秘密值的出现都会被替换为 [REDACTED] 在发送给AI之前
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上，以增强安全性：

命名空间约定

使用 - 用于命名空间分隔符和 _ 对于键内的单词分隔符：

# 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限制

使用（某种方法）将命名空间的秘密限制在特定的URL上 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/*"

解析的工作原理

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

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)

安全优势

• 最小权限原则“Secrets”仅与其预期的服务一起工作
• 防止跨服务泄漏Azure 密钥无法发送到 AWS API
• 纵深防御即使存在人工智能错误或提示注入，机密信息也受到限制
• 清晰的组织结构命名空间结构使密钥管理更加直观

实际使用场景

场景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 存储模式\ ❌（这个符号在中文中通常表示“错误”或“禁止”的意思，但直接翻译时保持原样，因为它是国际通用的符号） 被阻止如果与……一起使用 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

快速参考

图案；样式： HAL_SECRET__ → {secrets..} + HAL_ALLOW_

向后兼容性

非命名空间的密钥（无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 设置后，允许所有URL 除了 那些符合指定模式的：

# Block requests to internal networks and 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

示例

# 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

向任意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工具

当你通过提供Swagger/OpenAPI规范时 HAL_SWAGGER_FILEHAL 将为规范中定义的每个端点自动生成工具。这些工具的命名遵循以下模式： 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"
}

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

发展

先决条件

• 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. 为仓库创建分支
2. 创建一个特性分支（git checkout -b feature/amazing-feature)
3. 提交您的更改（git commit -m 'Add some amazing feature')
4. 推送到分支（git push origin feature/amazing-feature)
5. 提交一个拉取请求

许可证

这个项目遵循MIT许可证授权——详见 许可证 文件中有详细信息。

致谢

• 构建于 模型上下文协议 TypeScript SDK
• 受大型语言模型（LLMs）需要安全高效地与网络API交互的需求启发
• 由……驱动的OpenAPI集成 swagger-parser（注：这个短语在中文中通常直接保留原样，因为它是一个专有名词，指的是用于解析Swagger（一种用于描述和记录API的工具）的解析器或库。不过，为了说明其含义，可以简单解释为“Swagger解析器”或“用于解析Swagger的工具/库”。）