HAL

🚀 HAL (HTTP API Layer)

HALは、大規模言語モデルにHTTP API機能を提供するModel Context Protocol (MCP)サーバーです。安全で制御されたインターフェースを通じて、LLMがHTTPリクエストを行い、Web APIと相互作用できるようにします。また、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を追加します（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

🔧 技術詳細

構成

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 Storageエンドポイントに制限する
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 などの誤ったサービスのURLを使用した場合

シナリオ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 によって提供されています。