apifable

仕様を読み解き、APIを理解し、自信を持って統合する。

English | 繁體中文

概要

apifableは、AIがTypeScriptフロントエンドプロジェクトにAPIをよりスムーズに統合できるように支援するMCPサーバーです。API構造の探索、エンドポイントの検索、TypeScript型の生成を容易にし、AIエージェントが正確な統合コードを書くために必要なコンテキストを提供します。

Related MCP server: openapi-mcp-proxy

✨ 特徴

• 📦 AI対応のAPIコンテキスト — APIを理解し、操作するために必要な構造をAIに提供します

• 📘 OpenAPI 3.0 / 3.1サポート — 信頼できる情報源として標準仕様で動作します

• 🤖 AIエージェント用MCPサーバー — Claude、Cursor、Windsurfにプラグイン可能です

• 🔍 API探索ツール — エンドポイントの閲覧、キーワード検索、リクエスト/レスポンス詳細の検査が可能です

• 🏷️ TypeScript型生成 — フロントエンドコードですぐに使用できるTypeScript型定義を生成します

はじめに

インストール

apifable initを実行してプロジェクト設定をセットアップします：

npx apifable@latest init

これにより、プロジェクトルートにapifable.config.jsonが作成されます。仕様パスをチームと共有するため、設定ファイルはバージョン管理にコミットしてください。

コマンド開始後、**Manual file（手動ファイル）とRemote URL（リモートURL）**のいずれかを選択できます。

1. Manual file

OpenAPI仕様がすでにプロジェクト内に存在する場合、または仕様の更新を自分で管理したい場合に使用します。

initは、openapi.yamlのようなローカルファイルパスを尋ねます。

その後、そのパスにOpenAPI仕様を手動で配置する必要があります。バックエンドAPIが変更された場合も、そのファイルを自分で更新する必要があります。

2. Remote URL

OpenAPI仕様が、バックエンドAPIドキュメントによって提供されるOpenAPI仕様エンドポイントなど、安定したリモートURLから利用可能な場合に使用します。

initはまずhttps://api.example.com/openapi.yamlのようなリモートURLを尋ね、次に./openapi.yamlのようなローカル出力パスを尋ねます。

[!NOTE] このモードでは、initはダウンロードされたローカル仕様パスを自動的に.gitignoreに追加します。これは、ファイルがリモートソースからリフレッシュされることを意図しているためです。

その後、以下のコマンドを実行して、リモートURLからローカルパスへOpenAPI仕様をダウンロードできます（spec.url → spec.path）。仕様が変更されるたびに、再度実行してリフレッシュしてください：

npx apifable@latest fetch

ヘッダー

チームと共有可能な非機密ヘッダーについては、apifable.config.jsonにspec.headersを追加してください：

{
  "spec": {
    "path": "openapi.yaml",
    "url": "https://example.com/openapi.yaml",
    "headers": {
      "X-Api-Version": "2"
    }
  }
}

認証ヘッダー（シークレットトークン）

リモートのOpenAPI仕様のダウンロードに認証（プライベートAPI）が必要な場合は、シークレットヘッダーを.apifable/auth.jsonに保存してください。このファイルはバージョン管理にコミットしてはいけません：

{
  "headers": {
    "Authorization": "Bearer YOUR_SECRET_TOKEN"
  }
}

apifable.config.jsonと.apifable/auth.jsonの両方で、ヘッダー値内の${ENV_VAR}構文がサポートされています。

{
  "headers": {
    "Authorization": "Bearer ${MY_API_KEY}"
  }
}

ヘッダーの優先順位（高い順）

1. .apifable/auth.jsonのヘッダー（同名のキーを上書き）

2. apifable.config.jsonのspec.headers

Claude Code

.mcp.jsonに以下を追加してください：

{
  "mcpServers": {
    "apifable": {
      "command": "npx",
      "args": ["-y", "apifable@latest", "mcp"]
    }
  }
}

CursorやWindsurfなどの他のAIエージェントの場合も、同様の手順でapifableをMCPサーバーとして設定できます。

使用方法

APIを探索し、機能を構築するために使用できるプロンプトの例をいくつか紹介します。

APIの探索

List all APIs

Show me APIs related to posts

List APIs under the Post tag

Show me the API details for post comments

Show me the API details for GET /posts/{id}/comments

Show me the API details for postComments

機能の構築

Implement the post comments feature

Post page: src/pages/posts/[id].tsx

Related APIs:
- GET /posts/{id}/comments (list post comments)
- POST /posts/{id}/comments (create a post comment)

[!TIP] 機能を構築するためのプロンプトを書く際は、関連するコンテキスト（ページパス、コンポーネントの場所、関連するAPI、従うべきパターンや例）を含めてください。

AIエージェントへのガイダンス

AIエージェントがapifableをより効果的に使用できるように、プロジェクトのAGENTS.mdに以下を追加してください：

## API Integration (apifable)

- Always use `get_endpoint` to verify the exact path, method, and parameters before writing integration code. Never assume.
- When presenting endpoint list data from apifable tools, display exactly these columns in order: `Method` (Uppercase), `Path`, `Summary`. Keep all values verbatim, including summary prefixes like `[ 32 - 001 ]`. Do not omit, rename, paraphrase, or add extra columns.
- When saving generated types, store them under `src/types/` and name files by domain (e.g., `src/types/auth.ts`, `src/types/user.ts`), not by OpenAPI tag names.

上記は推奨される開始点です。エンドポイントリストの列や型フォルダーのパスは、プロジェクトに合わせて自由に調整してください。

MCPツールリファレンス

get_spec_info

APIのタイトル、バージョン、説明、サーバー、およびすべてのタグとエンドポイント数を返します。馴染みのない仕様の全体像を把握するために、ここから始めてください。

list_endpoints_by_tag

入力:

• tag (string): フィルタリングするタグ名

• limit (number, optional): 返すエンドポイントの最大数

• offset (number, optional): スキップするエンドポイントの数（デフォルト: 0）

指定されたタグに属するすべてのエンドポイントを返します。レスポンスには、ページネーション用のtotal、offset、hasMoreフィールドが含まれます。結果が30件を超え、limitが指定されていない場合は警告が含まれます。

search_endpoints

入力:

• query (string): 検索するキーワード

• tag (string, optional): 検索を特定のタグに制限する

• limit (number, optional): 返す結果の最大数（デフォルト: 10）

operationId、パス、概要、説明に対するキーワード検索を行います。結果は関連度順にランク付けされます。完全一致が見つからない場合は、自動的にあいまい検索にフォールバックします。レスポンスにはmatchTypeフィールド（"exact"または"fuzzy"）が含まれます。あいまい検索の結果には、結果ごとにscoreフィールドも含まれます。

get_endpoint

入力（いずれかを選択）:

• method (string) + path (string): HTTPメソッドとエンドポイントパス（例: get + /users/{id}）

• operationId (string): 操作ID（例: listUsers）

パラメーター、requestBody、レスポンスを含むエンドポイントオブジェクト全体を返します。サポートされている内部コンポーネントの$refはインラインで解決されます。

search_schemas

入力:

• query (string): 検索するキーワード

• limit (number, optional): 返す結果の最大数（デフォルト: 10）

スキーマ名と説明に対するキーワード検索を行います。結果は関連度順にランク付けされます。完全一致が見つからない場合は、自動的にあいまい検索にフォールバックします。レスポンスにはmatchTypeフィールド（"exact"または"fuzzy"）が含まれます。あいまい検索の結果には、結果ごとにscoreフィールドも含まれます。結果が空の場合、次のステップへのガイダンスを含むmessageフィールドが含まれることがあります。

get_schema

入力:

• name (string): components/schemas内のスキーマ名

サポートされている内部コンポーネントの$refが解決されたスキーマ全体を返します。

get_types

入力（いずれかのモードを選択）:

• schemas (string[]): components/schemas内のスキーマ名の配列

• method (string) + path (string): HTTPメソッドとエンドポイントパス

• operationId (string): 操作ID（例: listUsers）

自己完結型のTypeScript宣言をコードテキストとして生成します。エンドポイントモードでは、スキーマの依存関係を収集する前に、サポートされている内部コンポーネントの$refを追跡します。推移的な依存関係を自動的に含め、import文は含めません。

モードのルール:

• 1回の呼び出しにつき、必ず1つのモードを使用してください：schemas、method + path、またはoperationId

• 同じ呼び出し内でモードを混在させないでください

制限事項

• 外部の$ref（他のファイルやURLへの参照など）はサポートされていません。

• OpenAPI 2.0 (Swagger) はサポートされていません。OpenAPI 3.0および3.1仕様のみがサポートされています。

スポンサー

このパッケージが役に立ったと感じた場合は、私の活動を支援するためにスポンサーになることを検討してください〜。あなたのアイコンが私の主要プロジェクトに表示されます。

クレジット

• @reapi/mcp-openapi — インスピレーションの源

ライセンス

MIT LICENSE

Star History