Hal (http Api Layer)

HAL（HTTP API レイヤー）

HAL は、LLM に HTTP API 機能を提供する Model Context Protocol（MCP）サーバーです。LLM が安全で制御されたインターフェースを通じて HTTP リクエストを実行し、Web API とやり取りできるようにします。また、OpenAPI／Swagger 仕様からツールを自動生成し、シームレスな API 統合を実現できます。

ドキュメント

ドキュメント全文 →

詳細なガイド、例、API リファレンスについては、充実したドキュメントサイトをご覧ください。

機能

• HTTP GET／POST／PUT／PATCH／DELETE／OPTIONS／HEAD リクエスト：任意の HTTP エンドポイントからデータを取得し、送信できます
• 安全なシークレット管理：環境変数に基づくシークレットを {secrets.key} で置換し、自動的に秘匿化します
• Swagger／OpenAPI 統合：API 仕様からツールを自動生成します
• 組み込みドキュメント：自己文書化された API リファレンス
• 安全性：アクセスを制御した隔離環境で動作します
• 高速性：TypeScript で構築され、パフォーマンスが最適化されています

使用方法

HAL は、MCP 対応クライアントで動作するように設計されています。以下に例を示します。

基本的な使用方法（Claude Desktop）

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_FILE：OpenAPI／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_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:[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 を設定すると、指定したパターンに一致する URL を除き、すべての 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 ツール

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

自動生成された Swagger ツールのドキュメントを含む、API ドキュメントと使用例を幅広く参照できます。

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 リクエストが送信されます。

開発

前提条件

• 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 ライセンスの下でライセンスされています。詳細は LICENSE ファイルをご覧ください。

謝辞

• Model Context Protocol TypeScript SDK を使用して構築されています
• LLM が Web API と安全かつ効率的に連携する必要性に着想を得ています
• OpenAPI 連携は swagger-parser によって実現されています