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 過濾時，仔細規劃白名單和黑名單，避免誤阻止或允許不必要的訪問。