OpenAPI Swagger MCP

openapi-swagger-mcp

設定した開発／UAT API に AI アシスタントを接続するローカル MCP サーバーです。Swagger 2.0 または OpenAPI 3.0／3.1 の仕様を使って、エンドポイントの検索、入力項目の説明、リクエストの送信、レスポンスの確認を依頼できます。

例：「注文詳細のエンドポイントを見つけて、呼び出す前に必須パラメーターを説明してください。」

API のアドレスと認証情報は、YAML または JSON ファイルで設定します。MCP クライアントがサーバーを起動し、エンドポイントの数にかかわらず、アシスタントは固定の 11 個のツールを使用します。

初めての方へ： クイックスタートに従って設定し、次に日常的な使い方をお試しください。ツール呼び出しを自分で記述する必要はありません。

すでに接続済みの方へ： 次のステップを選ぶ、トラブルシューティング、またはツールリファレンスに進んでください。

始める前に

必要なもの：

• Node.js 22.19 以降と npm。
• アクセス可能な API と、その Swagger／OpenAPI 仕様（URL またはファイル）。
• ローカルの stdio サーバーを起動できる MCP クライアント。

**開発／UAT サービスに対してのみ使用してください。**ツールは実際の POST、PUT、PATCH、DELETE リクエストを送信します。ロールバック機能はなく、サーバー側の書き込み制御もありません。MCP クライアントに表示される確認プロンプトはクライアントの機能であり、このサーバーが強制するものではありません。

**データの送信先に注意してください。**ツールの引数や結果が、AI プロバイダーの会話履歴に保存される場合があります。レスポンスからトークンや個人情報が除去されることはありません。会話に貼り付けるのではなく、環境変数やファイルからシークレットを読み込んでください。

クイックスタート

1. 設定ファイルを作成する

次の内容を config.dev.yaml として保存します。

services:
  orders:
    baseUrl: http://localhost:8080/api/v1
    spec: http://localhost:8080/v3/api-docs

• orders は、エージェントがツール呼び出しで使用するサービス名です。
• baseUrl は、/api/v1 などのプレフィックスを含めて、リクエストの実際の送信先となる URL です。
• spec は Swagger／OpenAPI の URL、または ./openapi.json のようなファイルパスです。
• auth ブロックがない場合、リクエストは認証なしで送信されます。

上記の URL は例です。ご自身の API がそのアドレスで稼働している場合にのみ機能するため、開発／UAT 環境のアドレスに置き換えてください。

エージェントが送信する内容を確認したい場合は、インスペクターのセットアップと使い方ガイドに従い、ローカルのブラウザー UI を有効にして、正しい MCP セッションを開いてください。

続行する前に： 両方の URL を置き換えて、ファイルを保存してください。絶対パスを控えてください。次の 2 つの手順で同じパスを使用します。

ショートカット： init を実行すると、最小限の設定ファイルが作成され、対応するクライアント設定が出力されます。ファイルの作成前に設定を検証し、既存のファイルを上書きせず、クライアントのファイルも編集しません。

npx -y @nhan7777/[email protected] init --service orders --base-url http://localhost:8080/api/v1 --spec http://localhost:8080/v3/api-docs --out config.dev.yaml --client claude-code

環境変数からベアラートークンを読み込むには、--bearer-env ORDERS_TOKEN を追加します（トークン自体を受け取るフラグはありません）。相対パスで指定した --spec ファイルは、コマンドを実行したディレクトリを基準にします。--client には generic、claude-desktop、claude-code、cursor、vscode、windsurf、cline、codex、omp、kiro のいずれかを指定します。出力される設定例では、設定ファイルの絶対パスが使用されます。

2. 設定を確認する

npx -y @nhan7777/[email protected] --config /absolute/path/config.dev.yaml --check

ok: trueは静的チェックに合格したことを意味します。リモート仕様が取得されたことや、エンドポイントが検証されたことを意味するわけではありません。--checkはネットワーク通信を行わず、ログインせず、アーティファクトディレクトリも作成しません。レポートの形式と終了コードについては、トラブルシューティングを参照してください。

期待される結果： コマンドがコード0で終了し、レポートに"ok": trueが含まれます。そうでない場合は、クライアントに接続する前に報告されたフィールドを修正してください。

--checkは意図的にオフラインで動作します。仕様を読み込めるかどうかも確認したい場合は、明示的に依頼する必要がある別のネットワークチェックを実行してください。

npx -y @nhan7777/[email protected] --config /absolute/path/config.dev.yaml --check-specs

--check-specsは、サーバーと同じネットワークポリシーを適用して、各サービスの仕様（およびローダーによる取得が許可されている外部の$ref）を読み込み、1つのJSONレポートを出力します。ログインせず、業務エンドポイントを呼び出さず、アーティファクトディレクトリも作成しません。設定している場合、静的仕様の認証情報は、サーバーの起動時と同様に仕様自身のオリジンに送信されます。

3. MCP クライアントにサーバーを追加する

mcpServers設定を使用するクライアントでは、これをクライアントのMCP設定ファイルに追加してください（上記のYAMLファイルではありません）。

{
  "mcpServers": {
    "api-dev": {
      "command": "npx",
      "args": [
        "-y",
        "@nhan7777/[email protected]",
        "--config",
        "/absolute/path/config.dev.yaml"
      ]
    }
  }
}

ファイル名と場所はクライアントによって異なります。クライアントにコマンド、引数、環境変数を入力するフォームがある場合は、同じ値を入力してください。すべてのクライアントがmcpServers形式を使用するわけではないため、異なる場合はスニペットを適宜変更してください。サーバーがクライアントの起動ディレクトリに依存しないよう、絶対パスを使用してください。

このサーバーはstdioを使用します。クライアントがプロセスを起動し、stdin/stdoutを介して通信します。Web UIやHTTPポートはありません。stdoutはMCPの通信専用で、ログはstderrに出力されます。チェック後に終了するモードのため、クライアントの設定に--checkを追加しないでください。

各クライアントの正確な設定ファイル、ルートキー、再起動または再接続の手順を含む設定手順については、MCP クライアント設定ガイドを参照してください。

クライアント	設定形式	ガイド
Claude Desktop	JSON、mcpServers	Claude Desktop
Claude Code	CLI claude mcp add、またはJSON mcpServers	Claude Code
Cursor	JSON、mcpServers	Cursor
VS Code / GitHub Copilot	JSON、ファイルによってserversまたはmcpServers	VS Code and GitHub Copilot
Windsurf	JSON、mcpServers	Windsurf
Cline	JSON、mcpServers	Cline
Codex CLI	TOML、mcp_servers	Codex CLI
OMP	JSON、mcpServers	OMP (Oh My Pi)
Kiro	JSON、mcpServers	Kiro

4. 接続してAPIの利用可否を確認する

クライアントの設定を保存し、クライアントでMCPサーバーを再起動または再接続してください。次のように依頼します。

設定済みのAPIを一覧表示し、ordersの仕様が読み込まれたか報告してください。読み込みに失敗した場合は、業務APIのリクエストを行わずにエラーを説明してください。

期待される結果： アシスタントがorders、その仕様のリビジョン、操作数を見つけます。--checkとは異なり、この手順では仕様を読み込みます。サービスを利用できない場合は、トラブルシューティングに従ってください。

5. 最初のエンドポイントを確認する

次のように依頼します。

ordersサービスで注文の詳細を返す操作を見つけてください。その契約を読み、必須の入力を説明してください。まだリクエストは送信しないでください。

期待される結果： GET /orders/{id}のような操作と、独自の仕様で宣言されている入力が示されます。このパスの例がAPIに存在するとは限りません。

これでサーバーを使用する準備ができました。エンドポイントでトークンが必要な場合は、呼び出す前に認証を設定してください。

次のステップを選択

タスクに該当するセクションだけをお読みください。

やりたいこと…	まずはこちら
アシスタントに API の調査や呼び出しを依頼する	日常的な使い方
サービスや開発／UAT 用のアドレスを追加する	API を設定する
既存のトークン、パスワード、API キー、Cookie を使用する	静的な認証情報
ローカルの JSON ファイルにトークンを保存する	シークレットのソース
サービス間で認証情報を共有する、またはアカウントを選択する	複数のアカウントと共有プロファイル
ログインする、または期限切れのトークンを更新する	ログインと更新
OTP を使用する、またはセッションをインポートする	OTP、SSO、対話型セッション
大きなレスポンスを読む、または返されたファイルを保存する	大きなレスポンスとファイル
接続、仕様、認証のエラーを修正する	トラブルシューティング
保護された仕様、TLS、制限を設定する	高度な設定と制限事項
サポート対象のシナリオ向け設定をコピーする	設定のクックブック

日常的な使い方

MCP クライアントで通常の言葉を使ってください。プロンプト内のサービス名、ID、パスは、ご自身のものに置き換えてください。ツールの引数はアシスタントが処理します。正確な構文が必要な場合は、リクエストとレスポンスのリファレンスをご確認ください。

リクエストを送信せずにエンドポイントを探す

orders で、注文詳細のエンドポイントを探してください。その仕様を読み、必須パラメーター、認証、想定されるレスポンスを説明してください。呼び出しはしないでください。

リクエストを送信して結果を理解する

操作を確認し、実際のテスト ID を指定した後で：

orders の注文詳細 GET 操作を、ID demo-123 で呼び出してください。HTTP ステータス、関連するレスポンスフィールド、仕様に関する診断結果を報告してください。自動的に再試行しないでください。

HTTP レスポンスと仕様に関する診断結果は、それぞれ異なる問いに答えます。ステータスは API が返した内容を示し、診断結果はリクエストまたはレスポンスが仕様とどのように一致するかを示します。ステータスが成功でも、レスポンスが契約に準拠しているとは限りません。

リクエストを送信する前にプレビューする

orders の create-order 操作を、指定するテストデータでプレビューしてください。対象サービス、URL、ペイロードを表示し、処理を妨げるものがあれば教えてください。送信はしないでください。

preview_operation は invoke_operation と同じ引数（capture と followRedirects を除く）を受け取り、同じリクエスト準備を実行しますが、何も送信しません。業務リクエストも、ログインやトークン更新も、仕様の取得も行いません。返される内容には、sent: false、ready、対象、メソッド、URL、ヘッダー、Cookie、クエリペア、本文、リクエスト診断結果、使用中の認証バインディングが含まれます。サーバーが挿入する認証情報は、値ではなくバインディング名だけが表示されます。ユーザーまたはアシスタントが入力した値は入力どおりに表示され、無効なデータは無効なままです。

認証情報、読み込み済みの仕様、許可された宛先などが不足している場合、ready は false となり、blockers に理由が示され、リクエストは表示されません。プレビューは承認ではなく、保証でもありません。invoke_operation はリクエストを改めて準備するため、入力、設定、仕様のリビジョン、認証状態が変わっていれば内容が異なる場合があります。プレビューされるのは最初のリクエストだけです。リダイレクト、401 によるトークン更新、レスポンスで設定される Cookie は、invoke 時にのみ発生します。マルチパートの境界文字列はビルドのたびに変わります。また、host や content-length などのヘッダーは HTTP ライブラリによって追加されるため、プレビューには含まれません。

送信するかどうかは、引き続きユーザー自身とクライアントの確認プロンプトで判断してください。このサーバーは承認ステップを強制しません。POST、PUT、PATCH、DELETE リクエストは実際のデータを変更する可能性があります。

サービスまたはアカウントを明示的に選択する

このタスクには orders-uat を使用してください。まず、その注文詳細のコントラクトを確認してください。orders-dev は呼び出さないでください。

複数のプロファイルを設定している場合：

orders で許可されている qa プロファイルを使用してください。認証情報を表示せずに認証状態を確認し、リクエストを実行できる状態かどうかを説明してください。

レスポンスをさらに詳しく調べる

/data/items にある返された成果物を読み取ってください。ページネーションされている場合は、nextOffset を使って続行してください。レスポンスボディが完全かどうかを報告してください。

ファイルの場合は、まずエクスポート先ルートを設定し、アシスタントに新しい保存先パスを指定してください。エクスポートによって既存のファイルが上書きされることはありません。

API を設定する

2 つのサービスを使った、より詳しい例：

# yaml-language-server: $schema=/absolute/path/to/config.schema.json
version: 1                 # optional
services:
  orders:
    baseUrl: https://orders.dev.example.test/api/v1
    spec: https://orders.dev.example.test/v3/api-docs
    auth:
      bearer: { token: { fromEnv: ORDERS_TOKEN } }

  catalog:
    baseUrl: http://localhost:8081
    spec: ./specs/catalog.yaml

YAML（.yaml、.yml）と JSON の両方に対応しています。JSON では、エディターでキーの候補を表示できるように、"$schema": "/absolute/path/to/config.schema.json" を追加してください。設定クックブックは匿名サービスから始まり、シナリオ別にオプトインできる例を紹介しています。必要なブロックだけをコピーしてください。JSON Schemaに各フィールドの説明があります。

主なルール：

• 設定内の相対パスは、コマンドを実行した場所ではなく、設定ファイルを含むディレクトリを基準に解決されます。
• URL は baseUrl から取得されます。 baseUrl: https://host/api/v1 を指定した操作 GET /orders/{id} は、https://host/api/v1/orders/{id} を呼び出します。サーバーは仕様内の servers、host、basePath を無視します。baseUrl にユーザー名、パスワード、クエリ、フラグメントを含めることはできません。
• 環境もサービスとして扱います。 サーバーには環境の概念も、--env フラグも、切り替えツールもありません。各環境のサービスに一意の ID（たとえば orders-dev と orders-uat）を割り当て、エージェントに使用するものを伝えてください。同じ ID プロバイダーを共有するサービスは、プロファイルを共有できます。その場合、トークンのペアと更新処理も共有されます。環境を分離する必要がある場合は、別々の設定ファイルと MCP エントリを使用してください。各プロセスは、それぞれ独自の認証情報、Cookie、成果物を持ちます。
• 設定を変更した場合は、MCP プロセスを再起動する必要があります。refresh_specs で再読み込みされるのは仕様だけです。

環境からトークンを渡す

services:
  orders:
    baseUrl: https://orders.dev.example.test/api/v1
    spec: https://orders.dev.example.test/v3/api-docs
    auth:
      bearer: { token: { fromEnv: ORDERS_TOKEN } }

サーバーは、自身のプロセス環境から ORDERS_TOKEN を読み取ります。これは、コマンドをテストしたシェルの環境とは異なります。クライアントエントリの env フィールド、またはクライアントがプロセスを起動する場所で設定してください。

{
  "mcpServers": {
    "api-dev": {
      "command": "npx",
      "args": ["-y", "@nhan7777/[email protected]", "--config", "/absolute/path/config.dev.yaml"],
      "env": { "ORDERS_TOKEN": "replace-with-your-dev-token" }
    }
  }
}

サーバーは .env ファイルを読み込みません。別のプロセスの環境を変更しても、実行中の MCP サーバーの環境は変わりません。新しい値を適用するには、新しい値を指定して再起動してください。

その他のインストール方法

上記の npx コマンドでは、初回使用時に指定バージョンがダウンロードされます。別の方法：

# Global install; the command is then `openapi-swagger-mcp`
npm install -g @nhan7777/[email protected]

# From a source checkout (see Development)
npm ci && npm run build
node /absolute/path/to/openapi-swagger-mcp/dist/cli.js --config /absolute/path/config.dev.yaml

スコープなしの npm パッケージ openapi-swagger-mcp はインストールしないでください。これは別の利用者のもので、別のプロジェクトです。このパッケージは @nhan7777/openapi-swagger-mcp です。

認証

API に合った方法を選んでください。

API がサポートする最もシンプルな方法から始めてください。利用可能なトークンがあれば、静的認証だけで済みます。レシピとセッションは任意です。このセクションの YAML の例は、指定された場所にマージする設定ブロックであり、実行するコマンドではありません。ツールの例はアシスタントに渡す JSON 引数であり、シェルコマンドではありません。

authenticate と get_auth_status には、{"service":"orders"} または {"profile":"qa"} のどちらか一方だけを指定し、両方を指定しないでください。authenticate では "action":"refresh" も指定できます。action を省略すると、認証が選択されます（ログインレシピがない場合は、静的ソースが再読み込みされます）。

用意されているもの...	使用するもの
利用可能なベアラートークン、Basic 認証情報、API キー、または Cookie	静的認証情報
呼び出すログインまたは更新エンドポイント	ログインと更新
複数のアカウント、または複数のサービスで共有する認証情報	複数のアカウントと共有プロファイル
OTP、SSO、または対話的に受け取るトークン	OTP、SSO、対話型セッション

静的認証情報

次のいずれかの auth ブロックを、baseUrl と spec と同じ階層のサービス内に配置します（たとえば services.orders の下）。共有する ID の場合は、代わりに名前付きのプロファイル内に配置します。

ベアラートークン

auth:
  bearer:
    token: { fromEnv: ORDERS_TOKEN }

サーバーは Authorization: Bearer <token> を追加します。ソース値にはトークンのみを指定し、Bearer のプレフィックスは付けません。

Basic 認証

auth:
  basic:
    username: tester
    password: { fromEnv: API_PASSWORD }

ユーザー名とパスワードは個別に読み込まれ、Basic 形式でエンコードされます。どちらもファイルまたは fromCredential から取得できます。空文字列を指定できるのは、Basic のリテラル値だけです。

ヘッダー、クエリ文字列、または Cookie の API キー

auth:
  apiKey:
    header: X-API-Key
    value: { fromEnv: API_KEY }

API に必要な場合は、header を query または cookie に置き換えてください。各エントリで指定できる送信先は1 つだけです。リストを使って複数の方法を組み合わせることもできます。

auth:
  bearer: { token: { fromEnv: ACCESS_TOKEN } }
  apiKey:
    - { header: X-CSRF-Token, value: { fromEnv: CSRF_TOKEN } }
    - { query: tenant, value: demo }
  cookies: true

ベアラー認証、API キー、Cookie jar は組み合わせられます。ベアラー認証と Basic 認証はどちらも Authorization を使用するため、組み合わせられません。大文字と小文字を区別しない場合に名前が重複するヘッダーは拒否されます。クエリと Cookie の名前では大文字と小文字が区別されます。

Cookie jar

auth: { cookies: true } を指定すると、認証専用の Cookie jar が有効になります。これは生の Cookie 文字列ではありません。通常は capture.cookies: true を指定したログインレシピと組み合わせます（以下を参照）。Cookie のみを使用する認証は、jar が空の間はログイン済みとみなされません。すでに取得済みの Cookie をインポートするには、セッションを使用してください。

シークレットソース

同じ構文を token、value、username、password、および credentials の初期値に使用できます。

構文	意味
{ fromEnv: API_TOKEN }	MCP プロセスの環境変数を読み込みます
{ fromFile: ./secrets.json, pointer: /orders/token }	JSON ファイルからフィールドを読み込みます
{ fromFile: ./token.json }	JSON のルートを読み込みます。ファイルにはプレーンテキストではなく、"demo-token" などの JSON 値を含める必要があります
demo-token	リテラル値です。フィールド名に応じた警告が表示されますが、値がログに記録されることはありません
{ fromCredential: accessToken }	現在の認証から名前付きの値を使用します。通常はレシピで取得した値です

fromCredential は、credentials の初期値、カタログの credentialSources、または仕様取得時の認証では使用できません。バインディングの環境変数とファイルの値は文字列である必要があります。オブジェクトや数値が暗黙的に変換されることはありません。ソースが見つからない場合に、匿名アクセスへ暗黙的にフォールバックすることはありません。シークレットファイルはアップロードとエクスポートから保護されますが、アクセス許可の管理は利用者の責任です。また、これらのファイルをコミットしないでください。

複数のアカウントと共有プロファイル

profiles:
  qa:
    auth: { bearer: { token: { fromEnv: QA_TOKEN } } }
  admin:
    auth: { bearer: { token: { fromEnv: ADMIN_TOKEN } } }

services:
  orders:
    baseUrl: https://orders.dev.example.test
    spec: ./orders.json
    auth:
      profiles: [qa, admin]
      defaultProfile: qa
  reports:
    baseUrl: https://reports.dev.example.test
    spec: ./reports.json
    auth: { profile: qa }

• 認証方法を指定せずに orders を呼び出すと、qa が使用されます。admin を使用するには、invoke_operation に "auth":{"mode":"profile","profileId":"admin"} を渡します。
• サービスに profiles が定義されていても defaultProfile がない場合、リクエストはデフォルトで匿名になります。最初のプロファイルが自動的に選ばれることはありません。そのサービスを対象とする認証ツールでは、プロファイルの指定が求められます。
• プロファイルを直接操作するには、{"profile":"qa"} を指定して authenticate または get_auth_status を呼び出します。service と profile の両方を渡さないでください。
• プロファイルを使用できるのは、そのプロファイルを参照するサービスのみです。qa を使用する2つのサービスは、同じ認証情報、Cookie jar、更新タスクを共有します。Cookie の適用範囲は引き続きドメインとパスによって決まります。
• 名前付きプロファイルには、独自の credentials、authentication、refresh を設定できます。レシピでは request.service を明示的に設定してください。別の認証サービスを指定することもできます。これにより、レシピからその操作を呼び出せるようになるだけです。認証サービスに業務用の認証情報が渡されるわけではありません。
• プロファイルを参照するサービスには、独自の credentials、authentication、refresh を設定してはいけません。これらはプロファイルに設定してください。

ログインと更新

認証情報を取得するために API を呼び出す必要がある場合は、レシピを使用します。ユーザー名とパスワードは必須ではありません。本文には、グラントコード、クライアント認証情報、または API の仕様で必要とされる値を指定できます。

次の3つの要素には、それぞれ異なる役割があります。

• auth：業務リクエストで送信するものです。
• credentials：初期値となる名前付きの値です。参照されない限り送信されません。
• authentication / refresh：1つの操作を呼び出し、その結果を取得します。

例：グラントコードと更新トークン

services:
  accounts:
    baseUrl: https://accounts.dev.example.test
    spec: https://accounts.dev.example.test/v3/api-docs
    auth:
      bearer: { token: { fromCredential: accessToken } }
      apiKey: { header: X-CSRF-Token, value: { fromCredential: csrf } }
      cookies: true
    credentials:
      grantCode: { fromEnv: GRANT_CODE }
    authentication:
      request:
        operation: POST /session/exchange
        body:
          json:
            grantCode: { fromCredential: grantCode }
      capture:
        credentials:
          accessToken: { bodyPointer: /session/accessToken }
          refreshToken: { bodyPointer: /session/refreshToken }
          csrf: { header: X-CSRF-Token }
        cookies: true
    refresh:
      request:
        operation: POST /session/refresh
        body:
          form:
            refresh_token: { fromCredential: refreshToken }
      capture:
        credentials:
          accessToken: { bodyPointer: /access_token }
          refreshToken: { bodyPointer: /refresh_token }

どちらの操作も仕様に定義されている必要があります。/session/accessToken のような JSON Pointer は、response.session.accessToken を読み取ります。更新トークンは認証情報ストアに保存されます。この例では更新レシピでのみ送信され、業務リクエストでは送信されません。

使用方法。 ツール名の後に JSON 引数を指定します。これらはシェルコマンドではありません。

1. {"service":"accounts"} を指定して authenticate を呼び出します。
2. recovering の報告がなくなるまで、{"service":"accounts"} を指定して get_auth_status を呼び出します。
3. 状態が ready になったら、通常どおり API を呼び出します。
4. 手動で更新するには、{"service":"accounts","action":"refresh"} を指定して authenticate を呼び出します。

エージェントに次のように依頼することもできます：「設定済みのレシピで accounts サービスを認証し、完了するまで待ってから、ステータスを報告してください。認証情報は表示しないでください。」

覚えておくべきルール

• authenticate は authentication のみを実行します。レシピがない場合は、静的ソースを再読み込みします。ビジネス上の呼び出しで認証情報が不足していても、自動的にログインすることはありません。
• action: refresh は refresh のみを実行します。更新用レシピがない場合は、ローカルで AUTH_REFRESH_UNAVAILABLE エラーになります。
• 401 がバックグラウンドでの更新を開始することはありますが、元のリクエストが自動的に再送されることはありません。呼び出し元には引き続き、401 と authRecovery が返されます。更新の完了後、再度呼び出すかどうかは、あなたまたはエージェントが判断します。
• 403、匿名リクエスト、セッション、または Authorization をオーバーライドしたリクエストでは、更新は開始されません。
• レシピの実行中は、新しいビジネスリクエストは AUTH_RECOVERING エラーになります。同じアクションを再度呼び出すと実行中の処理に合流し、別のアクションを呼び出すと AUTH_BUSY エラーになります。
• 更新に失敗しても、ループで再試行することはありません。適切なアクションを指定して authenticate を呼び出し、明示的に再試行してください。
• 取得した認証情報、Cookie、バインディングの更新はまとめて適用されます。必須の取得項目が不足している場合、一部だけが適用されることはありません。取得対象に指定されていない認証情報は以前の値を保持するため、更新トークンをローテーションするには、再度取得する必要があります。
• 管理対象レシピで取得するヘッダーは、Bearer を含め、そのままの内容で保持されます。スカラー値の取得では、空でない文字列または有限数を受け付けます。数値は文字列に変換されます。
• レシピでは、デフォルトで HTTP 200-299 を成功とみなします。変更するには successStatuses: [200, 201] を設定します。レシピはリダイレクトを追跡せず、リクエストを再送せず、前提となるレシピも実行しません。

レシピのリクエスト。 request は service、operation、path、query、headers、cookies、body、auth をサポートします。

• service のデフォルトは、そのレシピを所有するサービスです。名前付きプロファイル内のレシピでは、明示的に設定する必要があります。
• request.auth のデフォルトは匿名であり、所有元のベアラー認証情報や Cookie を継承しません。それらを送信するには、認証方式を明示的に指定してください。cookies: true を指定すると、現在の Cookie ジャーが使用されます。
• ペイロード内のテンプレートは置換されます：{fromEnv}、{fromFile,pointer?}、{fromCredential}。値を {literal: {fromEnv: "text"}} のようにラップすると、そのオブジェクトは変更されずに送信されます。
• fromCredential の名前は、初期認証情報または取得項目で宣言されている必要があります。認証では、自身が将来取得する認証情報を使用できず、初期定義のある認証情報のみ使用できます。更新では、認証が取得した認証情報を使用できます。
• 取得には、空でない認証情報または cookies: true が必要です。Cookie を取得するには、所有元で auth.cookies: true が設定されている必要があります。
• 認証で取得する場合は、新しい Cookie ジャーが開始されます。更新の場合は、既存の Cookie ジャーを保持して更新します。

レシピの本文には、次のいずれか1つの形式を指定します。これらは代替形式のため、4つすべてを1つのレシピに貼り付けないでください：

# JSON; you can add contentType next to json
body: { json: { name: demo } }

# application/x-www-form-urlencoded, for example client credentials
body:
  form:
    grant_type: client_credentials
    client_id: { fromEnv: CLIENT_ID }
    client_secret: { fromEnv: CLIENT_SECRET }

# Multipart; files must be under uploadRoots
body:
  multipart:
    fields: { note: demo }
    files: [{ field: document, path: ./fixtures/demo.pdf }]

# Binary
body: { binary: { file: ./fixtures/demo.bin, contentType: application/octet-stream } }

レシピ内のファイルパスは固定設定です。認証情報の置換によって指定することはできません。

OTP、SSO、インタラクティブセッション

エージェントとユーザーが複数の手順を進める必要がある場合は、セッションを使用します。OTP をリクエストし、入力して、トークンまたは Cookie を受け取ってから、API を呼び出します。サーバーが単独で OTP をリクエストしたり、ポーリングしたり、ブラウザーを開いたり、CAPTCHA を解いたりすることはありません。セッションは 1 つのサービスに紐付けられます。

レスポンスからキャプチャする

1. OTP をリクエストする操作を、明示的なリクエストがあった場合に一度だけauth: {mode: anonymous}で呼び出します。
2. ユーザーが OTP を入力します。invoke_operationで検証操作を呼び出します。

{
  "service": "accounts",
  "operation": "POST /otp/verify",
  "revision": "<revision>",
  "auth": { "mode": "anonymous" },
  "input": { "body": { "json": { "value": { "code": "<OTP-provided-by-the-user>" } } } },
  "capture": {
    "tokens": [
      { "id": "access", "type": "bearer", "from": "body", "pointer": "/token" }
    ],
    "cookies": true
  }
}

3. capture.stateがcapturedの場合は、capture.sessionIdを読み取ります。
4. ビジネス操作をauth: {mode: session, sessionId: ...}で呼び出します。

レスポンスが実際に Cookie を設定する場合に限り、capture.cookiesを有効にします。ヘッダーからトークンをキャプチャするには、{"id":"access","type":"bearer","from":"header","header":"Authorization"}を使用します。管理対象レシピとは異なり、セッションのベアラーヘッダーキャプチャではBearer のプレフィックスが削除されます。API キーの場合は、in: header|query|cookieとnameを指定してtype: apiKeyを使用します。

デフォルトでは、キャプチャは 200〜299 のレスポンスにのみ適用されます。これを変更するには、successStatusesを設定します。キャプチャに失敗しても、セッションが部分的に更新されることはありません。既存のセッションを更新するには、capture.sessionIdを追加します。

すでに持っている認証情報をインポートする

設定でカタログを宣言することをおすすめします。

credentialSources:
  qaToken: { fromEnv: QA_SESSION_TOKEN }

次に、manage_sessionを呼び出します。

{
  "action": "create",
  "service": "accounts",
  "credentialSourceIds": [{ "sourceId": "qaToken", "type": "bearer" }]
}

インポートできるのは、トップレベルのcredentialSourcesで宣言された ID のみです。サービスまたはプロファイル内のインラインシークレットや、キャプチャされた更新トークンは、自動的にカタログに表示されません。

値を直接インポートする必要がある場合（AI との会話履歴に残る可能性があります）。

{
  "action": "create",
  "service": "accounts",
  "credentials": {
    "components": [{ "id": "access", "type": "bearer", "value": "<token>" }],
    "cookies": [{ "name": "sid", "value": "<cookie-value>" }]
  }
}

{"action":"inspect","sessionId":"<id>"}で内容を確認するか、sessionIdを省略してセッションを一覧表示します。{"action":"delete","sessionId":"<id>"}で削除します。確認で返されるのはメタデータのみで、シークレットは含まれません。

セッションは 1 つのサービスに紐付けられ、自動で更新されることはなく、管理対象のプロファイルを変更することも、プロファイルに昇格することもありません。セッションはメモリ内に保持され、プロセスの終了時に消去されます。

大きなレスポンスとファイル

サーバーはレスポンスをアーティファクトとして保存し、上限付きのビューを返します。そのため、長いファイルや base64 文字列が会話に大量に表示されることはありません。

• bodyTransformed: true：ビューが短縮されており、レスポンス全体ではありません。
• omissions：短縮されたフィールド、その理由、JSON Pointer、アーティファクト ID。
• rawBodyArtifact：HTTP コンテンツのデコード後のレスポンスエンティティバイト。メタデータと SHA-256 を含みます。

アーティファクトの一部を読み取る

ポインターを指定してread_artifactを呼び出します。

{ "artifactId": "<id>", "pointer": "/data/status" }

または、ページ単位で読み取ります。

{ "artifactId": "<id>", "offset": 0, "limit": 4096 }

結果のnextOffsetを使って続きの読み取りを行います。文字列へのポインターはテキストを返し、オブジェクトまたは配列へのポインターは JSON を返します。バイナリアーティファクトを読み取るとメタデータのみが返されます。ファイルを取得するにはエクスポートを使用してください。ポインターは解析済みの JSON 値に対して動作するため、数値の精度には上限があります。originalをエクスポートすると、バイト列を正確に保持できます。

ファイルをエクスポートする

出力先は files.exportRoots の配下である必要があります。export_artifact を呼び出します。

{
  "artifactId": "<id>",
  "pointer": "/data/imageBase64",
  "destination": "/absolute/path/exports/image.png",
  "representation": "decoded"
}

表現	結果
original	アーティファクトの元のバイト列
text	アーティファクト、またはポインターが示すフィールドのテキスト
decoded	文字列を厳密に Base64 デコードした結果

エクスポートによって既存のファイルが上書きされることはなく、ルートの外に出るシンボリックリンクもたどりません。Content-Disposition のファイル名は信頼されません。デフォルトでは、アーティファクトはプロセスの実行中のみ存在し、正常終了時に削除されます。エクスポートしたファイルは残ります。意図的にセッションを保持するには、トレース、ポリシー、セッションのライフサイクルを参照してください。

Base64 フィールドを設定で明示するには、次のようにします。

encodedFields:
  - service: orders
    pointer: /data/*/thumbnail
    encoding: base64
    mediaType: image/png

* はパスの 1 セグメントに一致します。ルールを 1 つの操作に限定するには、operation を追加します。format: byte、contentEncoding、データ URI などのスキーマヒントも、エンコーディングの確認に役立ちます。単に Base64 のように見える文字列が、Base64 であると断定されることはありません。

レスポンスが responseBytes を超える場合も、ステータスとヘッダーは取得できますが、本文は不完全なことがあります（bodyComplete: false）。アーティファクトの合計ストレージ容量は sessionArtifactBytes、アーティファクトの数は maxArtifacts によって制限されます。

トラブルシューティング

まず、設定を確認します。

npx -y @nhan7777/[email protected] --config /absolute/path/config.yaml --check

レポートには ok、services、checks、remoteSpecsChecked: false、operationsChecked: false が含まれます。各チェックには field、state（ok、pending、error のいずれか）、および場合によっては code が含まれます。

• pending は、実行時に認証情報が取得されることを意味します。静的エラーではありません。
• レシピがある場合も、環境変数とファイルのソース、ローカルの仕様ファイルと CA ファイル、アップロード先とエクスポート先のルートを確認します。
• リモートの仕様ファイルの取得、仕様内容の解析、リモートでの操作の確認、レシピの実行、アーティファクトディレクトリの作成は行いません。
• 設定を解析できない場合、またはスキーマに適合しない場合は、サニタイズされたエラーが stderr に出力され、stdout は空になります。解析できた場合は、シークレット値を含まない JSON レポートが 1 つ stdout に出力されます。

終了コード	意味
0	静的チェックに合格しました
1	設定、ソース、ファイル、またはルートに問題があります
2	--config の指定漏れや不明なフラグなど、CLI の使用方法に誤りがあります

個別の --check-specs ネットワークチェックでは、各サービスの state（ready または unavailable）、仕様の revision、表示可能な operationCount、失敗した場合は上限付きの error を含む { ok, services } が出力されます。すべてのサービスが準備完了の場合は 0、利用できないサービスがある場合は 1、--check と併用した場合は 2 で終了します。

よくある問題

症状／コード	対処方法
MCP クライアントが接続できない	Node が 22.19 以降であること、CLI と設定ファイルのパスが絶対パスであること、エントリーに --check が含まれていないことを確認します。ソースから実行する場合は、ビルド済みであることを確認します
CONFIG_INVALID	--check を実行し、失敗したフィールドを確認します。修正の参考として JSON Schema を使用し、古い構文を混在させないでください（制限事項を参照）
SOURCE_UNAVAILABLE / CREDENTIAL_INVALID	MCP プロセスの環境、JSON ファイル、ポインター、および値が文字列であることを確認します。シークレットをログに貼り付けないでください
サービスが unavailable と表示される	list_apis のエラーを確認します。仕様、参照先、CA ファイル、ファイル権限を確認して修正し、refresh_specs を実行します。軽微な仕様の問題は警告のみを発生させ、サービスを利用不可にはしません
AUTH_REQUIRED	静的ソースを確認するか、authenticate を呼び出します。OTP フローでは、セッションを使用します
AUTH_RECOVERING	get_auth_status が recovering を報告しなくなるまで待ちます。書き込み操作を大量に再試行しないでください
AUTH_BUSY	別の操作を要求する前に、実行中のアクションが完了するまで待ちます
AUTH_REFRESH_UNAVAILABLE	更新レシピが設定されていません。明示的に再認証するか、セッションをインポートします
AUTH_RECIPE_INPUT	レシピに必要な認証情報またはテンプレートに値がありません。レシピは前提条件となる手順を実行しません
AUTH_RECIPE_INVALID / AUTH_RECIPE_FAILED	レシピの操作、リクエストボディ、ステータス、サービスを確認します
AUTH_CAPTURE_FAILED	JSON Pointer、ヘッダー、または Set-Cookie を確認します。キャプチャ結果が一部だけ公開されることはありません
AUTH_TARGET_REQUIRED	複数のプロファイルを持つサービスに、デフォルトが設定されていません。{profile: ...} を渡します
PROFILE_NOT_ALLOWED / SESSION_SERVICE_MISMATCH	サービスに表示されているプロファイル、またはそのサービス用に作成されたセッションを使用します
SPEC_REVISION_MISMATCH	list、search、または schema から最新のリビジョンを取得し、呼び出す前にコントラクトを再読み込みします
UPLOAD_NOT_ALLOWED / エクスポートエラー	ルート、実際のパス、保護されたファイル、および保存先が存在しないことを確認します
リフレッシュ開始後の HTTP 401	これは元のリクエストに対するレスポンスです。リフレッシュが完了するまで待ってから、新しいリクエストを送信するか判断します

再起動とリフレッシュのどちらが必要ですか？ 設定の変更には MCP プロセスの再起動が必要です。refresh_specs は仕様のみを再読み込みします。レシピなしで authenticate を実行すると、静的な認証ソースが再読み込みされますが、設定全体は再読み込みされません。

リクエストとレスポンスのリファレンス

通常のフロー

手順	ツール	引数の例
サービスとリビジョンを確認する	list_apis	{}
操作を探す	search_operations	{"service":"orders","query":"order detail","limit":5}
コントラクトを読み込む	get_operation_schema	{"service":"orders","operation":"GET /orders/{id}","revision":"<revision-you-just-received>"}
リクエストを送信する	invoke_operation	以下を参照

invoke_operation の呼び出し全体の例：

{
  "service": "orders",
  "operation": "GET /orders/{id}",
  "revision": "<revision-you-just-received>",
  "input": {
    "path": { "id": "demo-123" },
    "query": { "includeItems": true },
    "headers": { "X-Request-ID": "demo-request" }
  }
}

operation は検索結果として返されるキーで、通常は METHOD /path です。operationId ではありません。revision は仕様のリビジョンで、古くなったコントラクトに基づいて操作を呼び出すのを防ぎます。仕様が変更されたら、{"service":"orders"} を指定して refresh_specs を呼び出し、その後、再度検索するかコントラクトを読み込んで新しいリビジョンを取得します。リフレッシュに失敗した場合は、最後に有効だったスナップショットが保持されます。

search_operations は service、method、tag、includeDeprecated、fields、limit、cursor を受け取ります。検索対象、結果の順位付け、追加の出力フィールドの意味については、検索を参照してください。同じクエリで nextCursor を渡すと、次のページを取得できます。クエリ、仕様のリビジョン、検索設定、または操作フィルターを変更すると、以前のカーソルは無効になります。エラーにはその理由（details.reason）が示されます。

リクエストボディ

以下のスニペットは、input 内に入れるフラグメントです。完全なツール呼び出しではありません。リクエストで指定できるボディタイプは1つまでです。

認証レシピとの違いに注意してください。invoke_operation.input.body では json.value と form.fields のラッパーを使いますが、レシピの body ではラッパーのない json と form を使います（ログインとトークンの更新を参照）。

JSON：

{ "body": { "json": { "value": { "name": "demo", "quantity": 2 } } } }

フォーム（application/x-www-form-urlencoded）：

{ "body": { "form": { "fields": { "name": "demo", "tags": ["a", "b"] } } } }

json または form 内に contentType を設定して、操作で宣言されているメディアタイプのいずれかを選択できます。

マルチパートおよびバイナリアップロードの場合は、まず設定でディレクトリを許可して作成します。

files:
  uploadRoots: [./fixtures]
  exportRoots: [./exports]

次に、ツール呼び出しで絶対パスを渡します。

マルチパート：

{
  "body": {
    "multipart": {
      "fields": { "description": "demo" },
      "files": [
        { "field": "document", "path": "/absolute/path/fixtures/demo.pdf", "filename": "demo.pdf", "contentType": "application/pdf" }
      ]
    }
  }
}

バイナリ：

{ "body": { "binary": { "file": "/absolute/path/fixtures/demo.bin", "contentType": "application/octet-stream" } } }

マルチパートの files 配列では、同じ field を複数回指定できます。uploadRoots の外にあるファイル、ルート外へ抜けるシンボリックリンク、保護されたファイルは拒否されます。メディアタイプは操作で宣言されているものと一致する必要があるため、送信前に契約を確認してください。

認証の選択とネガティブテスト

invoke_operation.auth には4つのモードがあります。

モード	動作
{"mode":"default"} または auth なし	サービスのデフォルト認証を使います。デフォルト認証がない場合は匿名で実行します
{"mode":"profile","profileId":"qa"}	サービスで許可されている名前付きプロファイルを使います
{"mode":"session","sessionId":"<id>"}	同じサービスにバインドされた対話型セッションを使います
{"mode":"anonymous"}	認証情報や Cookie を引き継ぎません。ただし、input で明示的に渡したデータは送信されます

無効なトークンをテストするには、独自の input.headers.Authorization を渡してください。この値はそのリクエストに限って対応する認証情報を上書きし、管理対象の認証情報には変更を加えず、自動更新も実行しません。

サーバーは渡された内容をそのままシリアライズし、データを修正しません。デフォルト値の追加、型の強制変換、未知のフィールドや null の削除は行いません。ボディを省略する場合と、バイト列 null を送信する {"json":{"value":null}} を送る場合は異なります。HTTP 4xx／5xx レスポンスは実際の結果として返され、「ツールの検証に失敗しました」というエラーには変換されません。

安全に送信できないリクエストはローカルでブロックされます。たとえば、パスパラメーターの欠落、パスの逸脱、ヘッダー内の CR／LF、操作で宣言されていないメディアタイプ、またはトランスポートが管理するヘッダーの上書きが該当します。

結果の確認

• sent: false：リクエストは送信されていません。error.code と error.message を確認してください。
• http.status と http.headers：実際の HTTP 結果です。
• bodyView：エージェントが読み取ることを想定したレスポンスの部分です。
• diagnostics.request と diagnostics.response：診断専用の、仕様に基づくチェックです。HTTP の結果に代わるものではありません。状態は valid、invalid、not_available、error です。
• bodyComplete: false：制限またはストリームエラーにより、ボディが一部しか取得されていません。レスポンス全体が有効だったと判断しないでください。
• authRecovery：401 の後にバックグラウンドで行われる更新の状態です。リクエストが再送されたことを意味するものではありません。
• ネットワーク、TLS、タイムアウトの障害では、見せかけの HTTP ステータスは生成されません。error.mayHaveBeenSent は、リクエストがすでにマシンから送信された可能性があるかどうかを示します。書き込み操作を再試行する際は注意してください。

デフォルトではリダイレクトに従いません。followRedirects: true の場合、設定された baseUrl のパスプレフィックス内にとどまる同一オリジンへのリダイレクトのみ、上限の範囲内で追跡されます。303、および301／302の後の POST は GET になります。307／308ではメソッドとボディが維持されます。認証情報が別のオリジンに転送されることはありません。サービスのオリジン、ベースパス、許可された宛先から外れるリダイレクトには従わず、3xx レスポンスと注記が返されます。

高度な設定と制限

仕様のダウンロードと$refの認証

仕様取得の認証は業務認証とは別です。静的シークレットのみを使用し、レシピは実行しません。

services:
  privateApi:
    baseUrl: https://api.dev.example.test
    spec:
      source: { url: https://docs.dev.example.test/openapi.json }
      auth:
        bearer: { token: { fromEnv: DOCS_TOKEN } }
      allowedOrigins: [https://schemas.dev.example.test]
      roots: [./specs]
    auth:
      bearer: { token: { fromEnv: API_TOKEN } }

仕様取得の認証情報は仕様ソースのオリジンにのみ送信され、$refを経由して到達する別のオリジンには送信されません。リモート仕様からローカルファイルを参照することはできません。ローカルの$refは許可されたルート内にとどまる必要があります。ローカル仕様のディレクトリが、その仕様のルートとして使用されます。仕様の取得ではリダイレクトを追跡しません。参照先が存在しないか壊れている場合、そのサービスのスナップショットは拒否されますが、ほかのサービスは引き続き動作します。

不完全な仕様：エラーではなく警告

フレームワークが生成する仕様（たとえばNestJS）には、軽微な誤りが含まれることがよくあります。次の3つはサービスをブロックしません。これらはlist_apisのwarningsに表示されます。リストは最大20項目、合計4096バイト、各項目512バイトかつ1行に制限されます。優先順位は、除外された操作、セキュリティスキーム、重複するoperationIdの順です。正確な件数はwarningSummary（total、shown、omitted、excludedOperations）に記載され、リスト末尾に追加の行として表示されることはありません。list_apisの出力予算を超える場合、警告テキストは短縮されます（件数は正確なままです）。メタデータさえ大きすぎる場合は、結果にservicesInline: falseとservicesArtifactが含まれます。read_artifactを使って全体を読み取ってください。

仕様の問題	処理	影響
エンドポイント間でoperationIdが重複している	警告のみ	操作はMETHOD /pathで呼び出すため、呼び出しには影響しません。そのIDを検索すると複数の結果が返されます。operationフィールドで区別してください
type: httpのセキュリティスキームに余分なin／nameがある	検証時に余分なフィールドは無視されます。元の仕様は保持されます	影響なし
パスパラメーターがパスに含まれていない操作（たとえば、パスに{customerId}がないのにcustomerIdを宣言している）	その操作のみが除外されます	見つけることができません。直接呼び出すと、メッセージoperation was excluded from this specificationおよびdetails.reason = PATH_PARAMETER_NOT_IN_TEMPLATEを伴うOPERATION_UNKNOWNが返されます。ほかの操作は通常どおり動作します

ほかの問題は、サービス全体を引き続きSPEC_INVALIDでブロックします。たとえば、一致するパラメーターがないパステンプレート{id}、見つからない$refの参照先、不正なOpenAPI構造などです。

警告は問題を報告するだけです。仕様を修正するものではないため、可能であればバックエンド側で修正してください。

$refとメソッドまたはparametersの併用は拒否されます。 文字列の$refと、get、put、post、delete、options、head、patch、trace、parametersのいずれかを同時に持つ仕様内のオブジェクトは拒否されます（<document>: an object combines $ref with execution siblings (a method or parameters)）。この場合の処理（無視、上書き、マージ）はツールによって異なり、バンドラーは黙ってマージするため、サーバー側ではどれかを選択しません。仕様の作成者が選択する必要があります。summary、description、x-*の兄弟要素は引き続き使用できます。

検査は、バンドラーによるマージ前に、読み込まれるすべての元のドキュメント（ルートと、$refが参照する許可済みのファイルまたはURL）に対して実行され、バンドル後のドキュメントにも再度実行されます。これは、コンテナー上の拡張された$ref（たとえばpaths: { $ref: 'p.json', '/a': { $ref: '#/x' } }）によって、個別にはどちらも有効な2つのオブジェクトから、バンドラーがメソッドを持つ$refを生成する場合があるためです。サーバーはオブジェクトの形状をバンドル前後に確認しますが、$refのパスを独自に再解決することはありません。そのため、サンプルデータ（example、enum、default、x-*）だけでなく、スキーマ、Links、Responses、さらにはマージ後にのみ現れる形状も含め、この形状を持つすべてのオブジェクトが拒否されます。これは互換性上の制限です。この制限に該当した場合、仕様の意味を変えずに済むなら、キーの名前を変更するか、そのオブジェクトから$refを削除して仕様を変更してください。 拡張された $ref が受け付けられます。 コンテナー上で $ref が拡張され、マージ後の結果に禁止された組み合わせが含まれなくなった場合、サーバーはバンドラーライブラリによるマージを受け入れます。スカラー値では拡張側が優先され、オブジェクトはマージされ、配列は全体が置き換えられます。たとえば、外部ファイルで必須のクエリパラメーター external を含む parameters が宣言され、拡張側で root を含む parameters が宣言されている場合、公開されるコントラクトには root だけが含まれます。配列は結合されず置き換えられるため、external パラメーターはなくなります。MCP 経由で公開され、リクエストのシリアライズに使用されるコントラクトは、バンドルと検証の後のものです。実際のサーバーがこのコントラクトを受け入れる証拠はないため、get_operation_schema で確認し、副作用を伴うリクエストを送信する前に適切な環境で試してください。

読み取り制限。 バンドラーが読み取ろうとする異なる $ref 文字列の数は、refGraphDocuments によって上限が定められます。.//a.json のように表記が異なる同じファイルを複数回読み取る場合も含め、読み取る合計バイト数は refGraphBytes によって上限が定められます。設定された読み取り予算を超えると、SPEC_LIMIT_EXCEEDED で停止します。これらの入力バイト数の予算は、ヒープや RSS のハードリミットではありません。仕様の読み込みエラーと解析エラーは 2048 バイトに制限されます。

サービスごとの TLS

tls:
  caFile: ./certs/dev-ca.pem
  verify: true

このブロックはサービスの下に配置します。verify: false を設定すると、そのサービスに限り TLS 検証が無効になり、警告が表示されます。テスト環境で本当に必要な場合に限って使用してください。デフォルトの証明書の問題を解決する方法ではありません。ツールは呼び出し時に TLS 設定を変更しません。

ファイルと制限

files:
  uploadRoots: [./fixtures]
  exportRoots: [./exports]
  artifactRoot: ./runtime-artifacts
limits:
  requestTimeoutMs: 30000
  responseBytes: 52428800
  uploadBytes: 52428800
  toolOutputBytes: 32768

変更する値だけを宣言してください。各制限は最大値のある正の整数です。範囲は JSON Schema を確認してください。

キー	デフォルト	対象
requestTimeoutMs	30000 ms	リダイレクト先への移動を含むリクエスト。レシピにもタイムアウトがあります
maxConcurrentRequests	8	通常のリクエスト
recipeConcurrency	2	認証レシピ用の別枠
specDocumentBytes	10 MiB	1 つの仕様ドキュメント
refGraphDocuments	100	ref グラフ内のドキュメント
refGraphBytes	50 MiB	ref グラフ内の合計バイト数
refGraphDepth	64	ref とテンプレートの深さ
responseBytes	50 MiB	1 つのレスポンス
uploadBytes	50 MiB	1 つのアップロード
sessionArtifactBytes	250 MiB	アーティファクトの合計容量
inlineStringBytes	4096 bytes	文字列をインライン表示するしきい値
toolOutputBytes	32768 bytes	1 つのツール結果の予算
artifactPageBytes	16384 bytes	1 回のアーティファクト読み取りページ
maxRedirects	5	有効時にたどるリダイレクト数
maxArtifacts	20000	セッションごとのアーティファクト数。超過分は容量上限に達した場合と同様に切り捨てられます
traceBytes	64 MiB	1 セッションのトレース用ディスク容量。traceSegmentBytes の 4 倍以上
traceSegmentBytes	4 MiB	1 つのトレースファイル
traceEventBytes	64 KiB	1 つのトレースイベント。1 セグメントの半分以下
traceIndexBytes	32 MiB	トレースインデックスのメモリ予算。書き込みキューを含みます（保守的な見積もりであり、ヒープ制限ではありません）
traceQueueBytes	4 MiB	書き込み待ちのトレースバイト数。超過分のイベントは破棄され、件数が記録されます
traceMaxOpenRecords	256	同時進行できる呼び出し、交換、認証実行の数
traceInputInlineBytes	4096 bytes	トレース内にインラインで保持されるエージェント入力。これを超える入力は 1 つのアーティファクトになります
traceFieldValueBytes	4096 bytes	これより長いヘッダー、Cookie、クエリ値は記録されません
requestBodyTraceBytes	1 MiB	これより大きいリクエストボディはアーティファクトとして保存されません

uploadRoots と exportRoots のデフォルトは空のため、宣言するまでアップロードとエクスポートは無効です。artifactRoot はまだ存在していなくてもかまいません。サーバーが実行時に作成します。

検索

search_operations は字句検索であり、読み込まれた仕様を対象にサーバープロセス内で実行されます。モデル、ネイティブ推論ランタイム、埋め込みサービス、検索ネットワーク呼び出しは使用しません。任意で利用できたセマンティック／モデル実験は削除されており、search.semantic はサポートされていません。

• インデックス対象： パス、METHOD /path、operationId、タグ、概要、説明、パラメーター名と説明、リクエストとレスポンスのフィールドパス（ネスト、$ref 経由、配列、allOf/anyOf/oneOf を含み、レスポンスヘッダーも対象）、スキーマ名とフィールドの説明。リクエストとレスポンスは分けて扱われます。
• テキスト： Unicode に対応しています。ラテン文字では大文字小文字、互換文字、アクセントを正規化します（don hang で đơn hàng が見つかります）。その他の文字体系の記号は保持されます（が と か は異なる文字として扱われます）。orderId、order_id、order-id、OrderID は一致します。漢字、かな、タイ語、ラオス語、クメール語、ミャンマー語のテキストは、辞書の単語ではなく、文字と文字のペアで照合されます。
• ランキング： 完全一致するパス、METHOD /path、または operationId（大文字小文字を区別）が最初に表示され、次にテンプレートに一致する具体的なパス（/orders/42 で /orders/{id} が見つかります）、正規化された識別子の一致、フィールドに応じて重み付けされた字句一致、誤字の一致が続きます。誤字の照合は、検索対象のフィールドのどこにも存在しない単語にのみ適用され、編集距離と比較予算は固定されています。
• fields： 用語が一致する場所を限定します。指定できる値は、identifier、text、parameter、requestField、responseField、schema です。{"query":"taxCode","fields":["responseField"]} は、taxCode を返す操作を見つけ、受け付けるだけの操作は見つけません。
• クエリ： 空のクエリはブラウズします（ランキングは行いません）。絵文字など、文字または数字を含まないクエリはエラー（QUERY_UNPROCESSABLE）となり、すべての項目を一覧表示することはありません。fields の指定にはクエリが必要です。
• 結果： 各ヒットには、tier、スコア、最大 3 件の matches（フィールド、元のテキスト、一致した用語、exact|token|alias|fuzzy、スキーマフィールドの場所）が含まれます。targets は、ページ内の各サービスをその baseUrl に対応付けます。unavailableServices には、有効な仕様がない設定済みサービスが列挙されます。インデックスが不完全な場合は、理由とともに coverage が表示されます。
• 出力予算： 結果全体は limits.toolOutputBytes の範囲内に収まります。まず根拠情報が削られ、次にページが縮小されます。nextCursor は常に、返された最後のヒットの次から続行します。必須メタデータを含めた 1 件のヒットが収まらない場合、呼び出しは OUTPUT_TOO_LARGE で失敗します。
• 操作フィルター： サービスの operations フィルターで非表示になっている操作はインデックスに登録されないため、検索や根拠情報の表示はできません。フィルターの識別情報はすべてのカーソルに含まれます。
• エイリアス： 仕様で使われていない単語は、search.aliases で宣言できます。一覧にない限り、同義語として扱われることはありません。また、グループは連鎖しません。

search:
  aliases:
    - { terms: ["đơn hàng", "order"], services: [orders] }
  limits:
    schemaDepth: 6                   # more keys: see examples/config.example.yaml

インデックスのメモリ使用量は search.limits.indexBudgetBytes（デフォルトは 64 MiB。保守的な推定値であり、ヒープの測定値ではありません）で制限され、設定済みサービス間で均等に分割されます。仕様が予算に収まらない場合、優先順位（識別子が最優先）に従ってインデックスに登録され、不足している内容は coverage に示されます。検索品質は bench/search の小規模な合成コーパスで測定しています。手法と目標に達しなかった結果については、README を参照してください。

字句検索では、宣言されていない業務上の同義語は推論されません。固定された合成 dev2 データセットでは、エイリアスなしの言い換えに対する recall@5 は 1/8、MRR は 0.041667 で、リリース済みベースラインの言い換え MRR 0.25 を下回っています。偽陽性は 6/64 です。これらは制限事項であり、品質向上を示す主張ではありません。以前のセマンティック実験の報告や結果は、履歴上の証拠にすぎず、提供中の機能を説明するものではありません。

トレース、ポリシー、セッションのライフサイクル

サーバーはローカルプロセスです。設定した API を直接呼び出し、生のレスポンスをローカルのアーティファクトに保持します。テレメトリを送信したり、埋め込み、再ランキング、モデルの各サービスを呼び出したりすることはありません。アシスタントが読み取るコンテンツは、MCP クライアントからモデルプロバイダーに転送される場合がありますが、これはこのサーバーの範囲外です。クライアントがコンテナ内または別のマシンで実行されている場合、リクエストはその場所から送信されます。

記録される内容。 このプロセスが行うすべてのツール呼び出しと HTTP 通信には、callId、requestId（リダイレクトの各段階、ログイン、更新、仕様または $ref の取得ごとに 1 つ）、authRunId の ID が付与されます。invoke_operation は trace: { callId, requestIds } を返します。記録には、サービス、操作、仕様のリビジョン、タイミング、送信状態、アーティファクトへのリンク（リクエストボディ、大きい場合はエージェントの入力、レスポンスボディ）が含まれます。生のボディがトレースやログにコピーされることはなく、アーティファクトに保持されます。サーバーが把握するのは自身が行った処理だけです。近い時間に届いたリクエストからタスクを推測することはありません。

送信状態	意味
not_sent	プロセスから何も送信されていません（ポリシーによるブロック、接続拒否、送信前の DNS または TLS エラー）
maybe_sent	リクエストが送信された可能性がありますが、レスポンスはありません（タイムアウト、リセット）
response_received	HTTP レスポンスを受信しました。4xx と 5xx は通常の結果であり、失敗ではありません

記録されない内容。 ヘッダー、Cookie、クエリの値は、エージェントが送信したとおりに記録されます。設定、セッション、Cookie jar からサーバーが挿入した認証情報は、名前のみ記録されます（unrecordedReason: credential）。ログインと更新では、リクエストは保存されません（テンプレート内のシークレットから構築されるため）。また、レスポンスヘッダーの値も記録されません。ステータスにかかわらず、生のレスポンスボディはローカルアーティファクト（モード 0600）として保持されます。これはデバッグデータです。このアーティファクトにはトークンが含まれる場合があります。トレースはパケットキャプチャではありません。HTTP クライアントを監視するものであり、ライブラリが追加する host、content-length、connection は監視対象ではありません。

読み取り方法。 トレースは、App.trace を通じてプロセス内で読み取ります（ページング前にフィルターを適用する、上限付きのクエリを使用します）。現時点では、これを公開する MCP ツールはありません。files.retention.keepOnExit: true にすると、セッションディレクトリに JSON Lines 形式のトレース（trace/seg-N.jsonl）、アーティファクト、手動確認用の artifacts.jsonl が保持されます。

上限。 トレースのメモリ、ディスク、書き込みキューには厳格な上限があります（上記の制限を参照）。上限に達すると、収まりきらない内容の記録は停止し、その件数（droppedEvents、droppedRecords）を数えて、ツール呼び出しを失敗させる代わりに degraded を報告します。書き込みは非同期です。クラッシュ後にディスク上に残るのは、フラッシュ済みのデータだけです。プロセスの実行中にアーティファクトが削除されることはありません。

送信先。 業務リクエストはサービスの baseUrl のオリジンに送信されます。レシピは、指定されたサービスのオリジンに送信されます。仕様はそれ自体のオリジンに、$ref は allowedOrigins に送信されます。トップレベルに network.allow リストを追加すると、指定したすべてのオリジンをリストに含めることを必須にできます（含まれていない場合、サーバーは起動を拒否し、--check は NETWORK_NOT_ALLOWED を報告します）。チェックでは、リダイレクトの各段階でオリジン文字列を比較します。名前が解決される IP、プロキシ、CA は確認せず、プライベートアドレスもブロックしません。設定したループバックまたは VPN のエンドポイントには到達できます。これは SSRF や DNS リバインディングへの防御ではありません。

操作フィルター。 include と exclude のルール（method、path の glob、operationId、tag）を指定する services.<id>.operations は、検索、コントラクト、呼び出しから操作を隠します。非表示の操作は OPERATION_NOT_ALLOWED を返し、何も送信しません。設定済みのログインおよび更新レシピはフィルターの対象外ですが、エージェントが実行することはできません。サンプル設定の operation-filter レシピを参照してください。 セッションのライフサイクル。 デフォルトでは、通常のシャットダウン時にセッションディレクトリが削除され、次回の起動時にクラッシュしたプロセスが残したディレクトリが削除されます。files.retention でこの動作を変更できます。keepOnExit はディレクトリを保持し、意図的に終了したことを示すマークを付けます。crashedSessionMaxAgeHours はクラッシュ時の残存ファイルを指定した時間だけ保持し、maxRetainedBytes は保持されたセッションのうち古いものから削除します。シャットダウン時は、実行中のキャプチャと読み取り処理が終了するまで待機し、それらの処理で使用中のファイルは削除しません。

ローカルリクエストインスペクター

オプションのインスペクターは、使用中の MCP プロセス向けの読み取り専用ブラウザー UIです。ツールの操作、HTTP リクエスト／レスポンス、認証の実行状況、診断情報を表示します。API リクエストを送信したり、コピーした cURL コマンドを実行したりすることはありません。MCP 接続自体は引き続きstdioを使用し、ブラウザー UI は独立したループバック HTTP サーバーです。

1. API 設定で有効にする

既存の services 設定と同じ階層に、次のブロックを追加します。

inspector:
  enabled: true
  port: 0

インスペクターはデフォルトで無効です。port: 0 を指定すると、プロセスごとに空いているポートが選択されます。受け付けられるのはループバックホスト（127.0.0.1 または ::1）のみです。ブラウザーは MCP プロセスをホストしているマシンで実行するか、明示的に設定したトンネルを使用する必要があります。

設定を変更するかパッケージを更新した後は、クライアント（OMP、Claude Code、Cursor など）でこの MCP サーバーを再起動または再接続してください。デフォルトでは、シャットダウン時に現在のセッションのトレースとアーティファクトが削除されます。 これらを保持するには、セッションの開始前に files.retention.keepOnExit: true を設定してください。ファイルを保持しても、停止したセッションのブラウザー UI は稼働し続けません。

2. 正しい MCP セッションの URL を取得する

その MCP サーバーに接続しているアシスタントに、次のように依頼します。

list_apis を呼び出し、session.sessionId、session.inspector.state、session.inspector.urlCommand だけを表示してください。URL コマンドは実行しないでください。

状態が running のとき、urlCommand には実行可能ファイル（command）とその引数のリスト（args）が含まれます。そのコマンドをローカルターミナルで自分でそのまま実行してください。トークンを含む URL が出力されるので、ブラウザーで開きます。アシスタント経由でコマンドを実行したり、出力をチャットに貼り付けたりしないでください。

または、同じ設定パスと list_apis が返すセッション ID を使用します。

npx -y @nhan7777/[email protected] \
  --config /absolute/path/config.dev.yaml \
  --inspector-url --session <session-id>

<session-id> を完全な s-... の値に置き換えてください。このコマンドは既存のインスペクターを検出するだけで、MCP サーバーや新しいセッションを起動しません。--session を指定しない場合は、その設定に対応する稼働中のインスペクターがすべて一覧表示されます。複数のクライアントやエージェントのウィンドウで同じ設定を共有している場合は、必ず最初または最新の URL ではなく、正確なセッション ID を使用してください。

URL にはフラグメント（#t=...）に秘密のトークンが含まれています。パスワードと同様に扱い、チャット、スクリーンショット、ログに残さないでください。このトークンは、そのセッションの inspector.json ディスクリプター（モード 0600）にも保存されます。秘密情報を含まないセッション／コマンド情報は、list_apis、MCP の初期化手順、起動時の stderr から確認できますが、クライアントによっては自動表示されないことがあります。このメタデータによって OMP にインスペクターボタンが追加されることはありません。

3. リクエストとレスポンスを確認する

1. いつもどおり、アシスタントに MCP ツールを使うよう依頼します。タイムラインは自動的に更新され、各ツールのアクションが、関連する HTTP リクエスト、リダイレクトの経由先、認証のやり取りとグループ化されます。preview_operation は HTTP リクエストを伴わないオフラインのツールアクションです。invoke_operation には実際に送信されたリクエストが表示されます。
2. ツールの行を選択すると、その引数、概要、関連するやり取りを確認できます。HTTP の行を選択すると、左右に並んだ Request + Response ワークベンチが開きます。
3. All Activity、Tools Only、API Requests Only、Errors & Blocked を使い分け、サービス、目的、送信状態、ステータスで検索またはフィルタリングします。フィルターは最初のページだけでなく、保持されている履歴全体に適用されます。Load older records を使うとページを続けて読み込めます。削除済みのレコードは復元できません。
4. ヘッダー、クエリパラメーター、Cookie、本文の各ページを確認します。Raw (hex) には保存された元のバイト列が表示されます。Text (derived) と Formatted (derived) は表示用の表現です。再フォーマットされたデータや不完全なデータについては、ビューアーに警告が表示されます。
5. 記録されたターゲットには Copy URL、Copy Path、Copy Domain を使います（Copy Domain にはスキームとポートも含まれます）。マスクされたクエリ値はプレースホルダーのままです。Copy Request Body ／ Copy Response Body は、保存済みの空でない本文がある場合にのみ表示され、HTTP ヘッダーやビューアーの注釈を含めず、すべてのページにわたる本文の内容をコピーします。JSON のコピーに含まれるのは JSON ペイロードのみです。保存が不完全な場合や派生テキストの場合、データに影響することがあるため、ビューアーの警告を確認してください。
6. cURL を開くとコマンドが自動的に読み込まれます。必要に応じて Copy cURL を使います。自分で実行する前に、警告と認証情報のプレースホルダーを確認してください。コピーしてもコマンドは実行されません。ツールの行には Copy Target があり、該当する値がある場合は Copy Args ／ Copy Summary も表示されます。

Pause を使うとタイムラインとの同期が停止します。Resume を使うと、現在のフィルターと読み込み済みの範囲に追いつきます。Auto / Light / Dark では UI テーマを変更できます。管理された認証情報は記録されませんが、明示的に表示したエージェント提供のシークレットや、生の認証レスポンスのアーティファクトには、認証情報やトークンが含まれることがあります。

トラブルシューティング

症状	確認すること
INSPECTOR_DISABLED ／ 状態 disabled	MCP プロセスに渡した正確な設定に inspector.enabled: true を追加し、再接続します。
INSPECTOR_NOT_RUNNING	まず MCP サーバーを起動または接続し、その接続から新しいセッション ID を取得します。不明なセッション、終了済みのセッション、異なる設定のセッションが、別のセッションに置き換えられることはありません。
状態 unavailable	起動時の stderr を確認します。固定ポートがすでに使用されている可能性があります。port: 0 を推奨します。Inspector を起動できなくても、MCP ツールは利用できる場合があります。
更新後も古い UI が表示される	新しいプロセスで新しいパッケージが読み込まれるよう MCP を再接続し、その新しい URL を取得します。古いタブを更新しても、古いプロセスが保持しているコードは更新されません。
別のウィンドウのアクティビティが表示される、またはタイムラインが空	ヘッダーのセッション ID と、目的のクライアント接続からの list_apis を照合し、その接続の正確な --session URL を取得します。フィルターを解除し、トレースが有効かどうかを確認します。
セッションの準備が整う前に MCP 接続がタイムアウトする	起動時に、設定済みのスペックが読み込まれるまで待機します。リモートのスペックホストや VPN にアクセスできるか確認してください。Inspector を有効にしても、到達できない API／スペックのエンドポイントは修正されません。
本文や認証情報が見つからない	利用可能性や不完全なデータに関する警告を確認します。注入された認証情報と認証リクエストの本文は、意図的に記録されません。

Inspector が読み取るのは、実行中の自身のプロセスのトレースのみです。セッションを横断するダッシュボードではありません。inspector.timelineLimit が制限するのはフィードのページ数であり、参照可能な履歴全体ではありません。API 利用者向けの GET /api/feed は、calls、exchanges、トレースのステータス、およびセッションとフィルターに紐付いた任意の nextCursor を返します。ページを移動しても、削除済みのレコードは復元できません。

制限事項

• stdio 経由のローカル MCP サーバーです。ホスト型ゲートウェイでも、HTTP MCP サーバーでもありません。
• ワークフローエンジンではありません。レシピ 1 つにつき操作は 1 つです。複数ステップのフローは、エージェントまたは人がオーケストレーションします。
• OAuth/PKCE コールバック、OTP ポーリング、CAPTCHA、ブラウザーログインの自動化には対応していません。スクリプト、HMAC 署名、mTLS クライアント認証にも対応していません。
• テレメトリーはありません。仕様とレスポンスは信頼できないデータであり、エージェントへの指示ではありません。また、説明と拡張機能が実行されることはありません。
• 検証結果は仕様の品質に依存します。不明な形式は合格ではなく、未検証として記録されます。検索はトークンのスコアリングによる決定論的なものであり、トークンの削減やセマンティック検索の精度について、本プロジェクトは何も保証しません。
• 互換性に関する注意：古い設定形式とツール形式は、エイリアスなしで削除されました。bearer.login、プロファイルの components／recovery、サービスレベルの allowedProfiles／defaultProfile、$source／$component、authenticate_profile、get_profile_status は、現在は動作しません。このガイドに記載されている形式を使用してください。

デモを試す

ご自身の API や実際の認証情報を使わずにツールの動作を確認するには、次のようにします。

npx -y @nhan7777/[email protected] demo

demo は 127.0.0.1 上で架空のデータを使った合成バックエンドを起動し、一時的なプロジェクトを書き出します。このプロジェクトには、匿名の demo-shop と、ログインおよび更新に対応した demo-account の 2 つのサービスが含まれます。そして、ほかの設定と同じように stdio 経由で提供されるため、--config の代わりに同じコマンドをクライアントのエントリーに指定してください。バックエンドのアドレスと設定ファイルのパスは stderr に出力され、stdout は MCP 専用のままです。まず demo-account の認証を要求してから、その GET /me を呼び出してください。POST /orders は 422 を返し、受信した内容をそのまま返すため、無効なデータが変更されずに送信されることを確認できます。また、GET /reports/large は、アーティファクトとして保存できる大きさの本文を返します。

バックエンドには実際の認証がないため、デモの実行中は、マシン上のほかのプロセスからもアクセスできます。終了時に一時ディレクトリは削除されます。--dir <path> を指定すると、代わりに新規または空のディレクトリが使用され、削除されずに残ります。

デモでは、ローカルリクエストインスペクターが有効になります。読み取り専用で、ループバックのみで待ち受け、トークンが必要ですが、デモがトークンを表示することはありません。開くには、別のターミナルで次のコマンドを実行してください（デモは設定ファイルのパスを含む正確なコマンドを stderr に出力します）。

npx -y @nhan7777/[email protected] --config /path/printed/by/the/demo/config.json --inspector-url

--inspector-url は、設定されたアーティファクトディレクトリからセッションのディスクリプターを読み込み、それがこの設定と実行中のプロセスに属することを確認してから、stdout に 1 行につき 1 つの URL を出力します。URL には秘密のトークンが含まれるため、パスワードと同じように扱い、シェルの履歴、スクリーンショット、チャットに残さないでください。このコマンドはサーバーを起動せず、何も作成せず、開けるものがない場合は INSPECTOR_DISABLED または INSPECTOR_NOT_RUNNING を伴って 1 で終了します。タイムラインでは、preview_operation は HTTP の送受信を伴わない呼び出しとして表示され、invoke_operation には実際に送信された送受信が表示されます。

複数の MCP プロセスで 1 つの設定を共有できます。list_apis は秘密情報を含まない session オブジェクト（sessionId と、インスペクターの state：running、disabled、unavailable）を返します。インスペクターが実行中の場合は、--inspector-url --session <id> を介してこのプロセスのインスペクターだけを特定する urlCommand（command と args）も返します。同じオブジェクトは、MCP の初期化指示と、stderr に出力される起動ログの行にも含まれます。コマンドはご自身でターミナルから実行してください。トークンを含む URL が出力されるため、その出力をチャットに貼り付けないでください。--session が受け付けるのは、s- に英数字を続けた形式で、--inspector-url と併用する場合に限られます。また、別のセッションへのフォールバックは行いません。不明なセッション、停止中のセッション、または別の設定に属するセッションを指定すると、INSPECTOR_NOT_RUNNING を伴って 1 で終了します。これにより情報がクライアントから利用可能になりますが、クライアントがそれを表示するかどうかはクライアント次第です。

ツールリファレンス

ツール	用途
list_apis	サービス、仕様の準備状況とリビジョン、操作数、仕様のwarnings、認証モードと機能、仕様の読み込みエラーを確認します
search_operations	識別子、テキスト、パラメーター、リクエスト／レスポンスのフィールド、スキーマ名で検索します。一致理由、フィールドの対象範囲、ページングも確認できます
get_operation_schema	操作のパラメーター、本文、レスポンススキーマ、セキュリティ、参照を確認します。大きなコントラクトはアーティファクトに保存されます
preview_operation	invoke_operationが準備するリクエスト、または準備できない理由を、何も送信せずに確認します
invoke_operation	実際のリクエストを送信し、HTTP の結果、診断情報、セッションへの任意の記録を取得します
refresh_specs	仕様を再読み込みして検証します。失敗した場合は、以前の有効なスナップショットが保持されます
authenticate	認証を実行するか、明示的な更新を行うか、静的な認証ソースを再読み込みします
get_auth_status	状態、リビジョン、機能、認証情報とバインディングの有無、Cookie 名、失敗を確認します。認証情報の値は返しません
manage_session	カタログから、または直接認証情報をインポートして、セッションを作成、確認、削除します
read_artifact	ページまたは JSON Pointer を指定して、保存されたレスポンスまたはコントラクトを読み取ります
export_artifact	バイト列、テキスト、または Base64 デコード済みデータを、exportRoots配下の新しいファイルに書き込みます

エンドポイントの数が増えても、ツールの数は増えません。設定済みサービスの外部を呼び出すための任意の URL、任意の環境変数名やファイルのシークレット名、スクリプト、環境を切り替えるパラメーターを受け付けるツールはありません。

レジストリとマーケットプレイス

npm パッケージは、MCP クライアント上でローカルに実行されます。カタログに掲載されても、カタログがパッケージをホストしたり、API 設定へのアクセス権を得たりすることはありません。インストールを機能させるために、プライベート設定やトークンをマーケットプレイスにアップロードしないでください。

チャネル	2026-10-21 に確認したステータス	インストール方法
npm	公開パッケージです。現在のlatestバージョンはレジストリで確認してください	クイックスタートまたはクライアントガイドに従ってください
Official MCP Registry	公開はタグ付きリリースのワークフローで検証されます	メタデータは npm の stdio パッケージを示しています。ローカルの--configパスを指定してください
GitHub MCP Registry	別個の掲載は検証されていません	Official Registry への公開は、このギャラリーにすぐ表示されることを証明するものではありません。手動でのクライアント設定は独立して機能します
Glama	0.1.2を基準に最終確認済み。ツールの検査はまだ保留中です	npm の手順に従ってください。Glama のホスト型デプロイは、このサーバー用に設定されていません
Smithery	未申請	接続管理、アカウント、CLI は 2026-10-31 に終了する予定です。Smithery アダプターやホスト型エンドポイントは提供されていません

リポジトリの所有者は、GitHub ログインを通じてGlama の掲載を申請し、リポジトリの再同期をリクエストできます。別途掲載する必要はありません。Glama は公開リポジトリをビルドして検査する場合がありますが、プライベートな API 認証情報やネットワークアクセスを提供する許可ではありません。

開発

ソースをチェックアウトして作業します。

npm ci
npm run build
npm run typecheck
npm run gen:schema
npm test
npm run test:integration
npm run smoke
npm run verify:package
npm audit --omit=dev --audit-level=high

統合テストとスモークテストの前にビルドしてください。一部のテストでは、コンパイル済みの CLI を stdio 経由で実行するためです。テストでは、ループバックバックエンド、合成データ、テスト専用の自己署名証明書を使用します。実際の認証情報は必要ありません。依存関係を変更した場合は、npm run gen:notices を実行してサードパーティ通知を更新してください。

npm test には単体テストと統合テストの両方が含まれています。npm run test:integration は任意のサブセットであり、追加の必須チェックではありません。CI では、合成ソースを使って設定クックブックも検証し、gen:schema で生成された変更がコミットされていない場合は拒否します。設定スキーマを変更した後は再生成し、変更に config.schema.json を含めてください。

Inspector を変更する場合は、ビルド前に埋め込みアセットを再生成してから、node tests/inspector-smoke.mjs を実行してください。コンパイル済み CLI と合成バックエンドを使ってブラウザーで検証するには、node tests/inspector-smoke.mjs --hold を使用します。ハーネスが出力するのは記述子のパスのみで、トークン URL は出力されません。保留中は、stdin に改行区切りの JSON を送ることで、実際の MCP トラフィックを生成できます。

{"id":"seed","action":"seed","count":230}
{"id":"one","action":"invoke","operation":"GET /widgets/{id}","input":{"path":{"id":7}}}
{"id":"slow","action":"start","operation":"GET /widgets/{id}","input":{"path":{"id":7},"query":{"hold":"1"}}}
{"id":"release","action":"release"}
{"action":"stop"}

各呼び出しが完了すると、トレース ID を含む command_done が出力されます。start はコマンドリーダーをブロックせずに実行されます。release は保留中のウィジェット応答を完了させ、決定論的なインフライト／ライブ更新の確認を可能にします。停止または Ctrl-C を押すと、MCP プロセスが終了し、記述子が削除されます。

タグの公開では、タグのコミットに対して同じ 9 セルの CI マトリックスを実行し、すべてのセルが合格するまで待機します。その後に限り、公開ジョブが独自の tarball をビルドして検証し、SHA-256 の対応ファイルを確認したうえで、npm の信頼済み公開を通じてその正確なバイト列を公開します。タグはパッケージのバージョンと一致し、そのコミットは main に属している必要があります。

npm への公開後、ワークフローは最大 20 回、公開メタデータの確認を行います（HTTP 404 の場合は 15 秒間隔）。公開された名前、バージョン、mcpName、tarball の整合性も検証します。その後、チェックサムで固定された mcp-publisher と GitHub OIDC を使用して、Official MCP Registry に server.json を公開します。CI で個別のレジストリトークンは必要ありません。レジストリへの公開はメタデータの配布であり、リモートホスティングではありません。

npm の公開が成功してレジストリへの公開が失敗した場合、npm へのリリースはすでに完了しています。 カタログを修正するためにタグを削除したり、バージョンを再利用したり、npm への公開を再実行したりしないでください。その npm バージョンが確認可能になり、server.json がそのバージョンと一致したら、リポジトリのルートからレジストリへの公開ステップのみを再実行して復旧します。

mcp-publisher validate
mcp-publisher login github
mcp-publisher publish

ログインすると、デバイス認証フローが開始されます。.mcpregistry_* ファイルは絶対にコミットせず、その内容をチャットに貼り付けないでください。公式の自動化ガイドを参照してください。クライアント固有のマーケットプレイスでは、リスティングを個別にインデックス化または審査する場合があります。Official Registry に登録されても、他の場所での承認や即時掲載が保証されるわけではありません。

npm run verify:package の実行前に、npm run build が必要です。このコマンドは実際にパッケージを作成し、tarball を別のコンシューマーディレクトリにインストールして、インストール済みのコピーに対して --check、bin シム、スモークテストを実行した後、そのコピーを監査します。すべてに合格した場合に限り、tarball は .release/<name>.tgz に .sha256 ファイルとともに配置されます。監査に失敗した場合、tarball は証拠として .release/diagnostic/NOT-RELEASABLE-... に保持されます。npm pack --dry-run では代用できません。この方法でローカルの候補を検証することと、それを公開することは別の作業です。公開は、独立した意図的なレジストリアクションです。CI マトリックス（Node 22.19.0、22、24 を使った Ubuntu、macOS、Windows）は、それ自体がリリース条件です。

MIT ライセンスの下でリリースされています。依存関係のライセンスは THIRD_PARTY_NOTICES.md に記載されています。