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 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 提供安全的密鑰管理功能，可將 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 的所有其他文本

命名空間和 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 規範來自可信來源。

🤝 貢獻指南

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 提供支持。