Hal

🚀 HAL (HTTP API Layer)

HALは、大規模言語モデルにHTTP API機能を提供するModel Context Protocol (MCP)サーバーです。これにより、LLMは安全で制御されたインターフェースを通じてHTTPリクエストを行い、Web APIと相互作用することができます。また、HALはOpenAPI/Swagger仕様から自動的にツールを生成し、シームレスなAPI統合を実現します。

🚀 クイックスタート

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"
      }
    }
  }
}

直接使用する場合

# デフォルトのツールで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リファレンスについては、包括的なドキュメントサイトをご覧ください。

💻 使用例

基本的な使用法（Claude Desktop）

Claude Desktopの設定にHALを追加するコード例です。

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

Swagger/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

🔧 技術詳細

設定

HALは以下の環境変数をサポートしています。

シークレット管理

動作原理

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

名前空間と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}

# 2段階の名前空間  
HAL_SECRET_AZURE-COGNITIVE_API_KEY=your_key
→ {secrets.azure.cognitive.api_key}

# 3段階の名前空間
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 Storageのパターンに一致します。
❌ ブロックされる：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制限に違反すると、明確なエラーメッセージが表示されます。

❌ 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_<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リクエストが行われます。

開発

前提条件

• 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. リポジトリをフォークします。
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によって提供されています。