# API Skill MCP

[English](https://unpkg.com/apiskill@latest/docs/mcp.md) / [中文](https://unpkg.com/apiskill@latest/docs/mcp.zh.md) / [한국어](https://unpkg.com/apiskill@latest/docs/mcp.ko.md) / [日本語](https://unpkg.com/apiskill@latest/docs/mcp.ja.md)

## ローカル Codex 設定

API Skill は stdio MCP サーバーとして実行されます。

```bash
node /Users/dobby/dev/apiskill/scripts/mcp-server.mjs
```

次の設定を `/Users/dobby/.codex/config.toml` に追加します。Codex クライアントがプロジェクト設定を読む場合は、プロジェクトレベルの `.codex/config.toml` をそのまま使うこともできます。

```toml
[mcp_servers.apiskill]
command = "node"
args = ["/Users/dobby/dev/apiskill/scripts/mcp-server.mjs"]
cwd = "/Users/dobby/dev/apiskill"
startup_timeout_sec = 10
tool_timeout_sec = 60
enabled = true
```

キャッシュ環境変数を設定しない場合、MCP、Web、CLI は同じ `~/.apiskill/cache` を使用します。プロジェクトごとに分離する場合は、3 つのプロセスすべてに同じ絶対パスの `APISKILL_CACHE_DIR` を設定してください。

Codex を再起動して `/mcp` を実行します。`apiskill` と以下のツールが表示されるはずです。

## 読み取りツール

- `apiskill_check`: 利用可能なキャッシュ済み OpenAPI ドキュメントがあるか確認し、ない場合はインポート例を返します。
- `apiskill_help`: MCP ヘルプ、利用可能なツール、インポート例を表示します。
- `apiskill_list_versions`: キャッシュ済みバージョンを一覧表示します。
- `apiskill_search_endpoints`: エンドポイント概要を検索します。
- `apiskill_query_api`: CLI 相当の query です。単一一致では JSON、raw endpoint data、CLI config を返せます。
- `apiskill_get_endpoint`: 1 つのエンドポイントについて、パラメータ、リクエストボディ、レスポンス、手動設定、任意の raw operation を取得します。
- `apiskill_get_ai_context`: AI が使いやすい Markdown を取得します。
- `apiskill_get_schema`: 指定 schema を展開します。

## 書き込みツール

以下のツールは `cache/latest-import.json` と `cache/versions/` を変更します。

- `apiskill_import_url`: 直接 OpenAPI JSON/YAML URL をインポートします。
- `apiskill_crawl_openapi`: Swagger UI / Knife4j / Redoc をクロールし、見つかったドキュメントをインポートします。
- `apiskill_import_file`: ローカル JSON/YAML ファイルをインポートします。
- `apiskill_import_curl`: curl コマンドを実行し、その OpenAPI レスポンスをインポートします。
- `apiskill_create_document`: ゼロから API ドキュメントを作成するための空白 OpenAPI ドキュメントバージョンを作成します。
- `apiskill_create_api`: 手動 API 操作を作成します。
- `apiskill_edit_api`: 手動 API 操作を編集/置換します。
- `apiskill_delete_api`: API 操作を削除します。

## ゼロから作成

プロジェクトにまだ上流ドキュメントがない場合は、まず agent に `apiskill_create_document` を呼び出させます。

```json
{
  "title": "My API",
  "version": "1.0.0",
  "description": "Internal service contract"
}
```

その後、`apiskill_create_api` でエンドポイントを追加し、`apiskill_edit_api` で編集し、`apiskill_get_endpoint` または `apiskill_query_api` で確認します。これにより、第三者の OpenAPI ソースがなくても AI ツールでローカル API 契約を作成し継続管理できます。

## 検証

```bash
npm run mcp
```

プロトコルレベルで検証するには、サーバーを initialize し、`tools/list`、`apiskill_check`、`apiskill_list_versions` を順に呼び出します。サーバーは `serverInfo.name = apiskill-mcp` を返し、`apiskill_*` ツールを一覧表示するはずです。

## 将来のサーバー配備

現在の構成はローカル stdio です。サーバー配備では、SSH/リモート実行経由で同じ stdio サーバーを起動し、サーバー側の `APISKILL_ROOT` と `APISKILL_CACHE_DIR` を設定するか、同じ shared core モジュールを呼び出す Streamable HTTP MCP wrapper を追加できます。ツール名と payload の意味は安定させてください。