apiskill 0.1.0

package/MCP.md

@@ -0,0 +1,12 @@
+# API Skill MCP Documentation
+
+The detailed MCP documentation has moved to standalone docs:
+
+- [English MCP documentation](docs/mcp.md)
+- [中文 MCP 文档](docs/mcp.zh.md)
+
+Project overview:
+
+- [README](README.md)
+- [Web app docs](docs/web.md) / [Web 中文文档](docs/web.zh.md)
+- [CLI docs](docs/cli.md) / [CLI 中文文档](docs/cli.zh.md)

package/README.ja.md

@@ -0,0 +1,108 @@
+# API Skill
+
+[English](README.md) / [中文](README.zh.md) / [한국어](README.ko.md) / [日本語](README.ja.md)
+
+API Skill は、フロントエンド開発と AI 支援開発のためのローカル OpenAPI/Swagger ワークスペースです。3 つの入口が同じキャッシュ済み API ドキュメントを共有します。
+
+- Web アプリ: API ドキュメントのインポート、閲覧、検索、確認、テスト、手動 API 操作の管理。
+- CLI: ターミナルからドキュメントをインポートし、ローカル API バージョンを管理または照会。
+- MCP サーバー: 同じ API コンテキストと保守操作を Codex や他の MCP クライアントへ公開。
+
+## Web アプリの使い方
+
+プロジェクトルートで起動します。
+
+```bash
+npm install
+npm run dev
+```
+
+ターミナルに表示されたローカル Vite URL を開きます。Web アプリは、直接 OpenAPI JSON/YAML URL のインポート、Swagger UI / Knife4j / Redoc ページのクロール、ローカルファイルのアップロード、OpenAPI ドキュメントを返す curl コマンドの実行、空白ドキュメントの新規作成に対応しています。
+
+インポートまたは新規作成後は、バージョンセレクタでキャッシュ済みドキュメントを切り替え、path、summary、tag、method、パラメータテキストでエンドポイントを検索できます。エンドポイントタブでは、リクエストパラメータ、リクエストボディ、レスポンスフィールド、AI 向けコンテキスト、Raw JSON を確認できます。手動 API 操作の追加、編集、削除も可能で、変更はローカルのキャッシュバージョンとして保存されます。
+
+CLI と MCP を使う前に、まず組み込みチェックを実行してください。
+
+```bash
+npm run cli -- check
+```
+
+CLI でゼロから始める場合は、`npm run cli -- document create --title "My API" --doc-version 1.0.0` で空白ドキュメントを作成し、`api create` でエンドポイントを追加します。MCP クライアントでは、`apiskill_check` でキャッシュを確認し、上流ドキュメントがない場合は `apiskill_create_document` で空白ドキュメントを作成し、`apiskill_help` で利用可能なツールを確認します。
+
+## このツールを開発した理由
+
+大規模 AI モデルが登場してからの数年間で、開発者が AI を使ってコードを書く方法は大きく変化してきました。最初は ChatGPT の Web 画面でコード、エラー、API ドキュメントをコピー&ペーストする使い方が中心でした。その後、Cursor、Codex、Claude Code のようにプロジェクト全体へ統合できるデスクトップまたはローカル開発ツールが登場し、AI 開発は単発の質問からプロジェクト全体のコンテキストを扱う形へ移っていきました。
+
+API ドキュメントの扱い方も変わりました。初期は API ドキュメントをそのまま貼り付けたり、ドキュメント画面のスクリーンショットを渡したりしていました。さらに Context7 のようなツールによって、AI アシスタントが Web 上の API ドキュメントを直接読めるようになりました。これは大きな進歩ですが、実際の開発ではまだいくつかの問題が残ります。
+
+- AI が Web ドキュメントを読み取り解析するには追加 token が必要で、大きな Swagger、Knife4j、製品ドキュメントでは無駄と待ち時間が大きくなります。
+- 社内ドキュメントでは、ログイン、cookie、アクセスキー、社内ネットワークなどのアクセス制御を扱う必要があることがよくあります。
+- AI がドキュメントを読めたとしても、ドキュメントを新規作成、編集、修正、バージョン管理する能力は通常そのままでは提供されません。
+
+API Skill は、このギャップを埋めるために作られました。API ドキュメントをローカルにインポート、クロール、ゼロから作成、照会、編集、バージョン管理し、同じ構造化された契約を Web アプリ、CLI、MCP サーバーから利用できるようにします。目標は、API ドキュメントを何度も貼り付けるテキストやスクリーンショットではなく、AI アシスタントが安定して利用し継続的に管理できるプロジェクトレベルのツールにすることです。
+
+### Token 効率
+
+実際の削減量は、ドキュメントサイズ、schema の深さ、タスクに必要な周辺コンテキストによって変わりますが、実務上の傾向は一貫しています。
+
+| Workflow | モデルへ送る典型的なコンテキスト | 再利用性 | 期待される token 影響 |
+| --- | --- | --- | --- |
+| ドキュメントのスクリーンショット | 画像 token と表示ページ全体の視覚的解析 | 低 | 高コストで、正確なフィールド引用が難しい |
+| ドキュメント本文の貼り付け | ページ全体の本文、ナビゲーション、例、多くの無関係なエンドポイント | 低-中 | タスクごとに数千から数万 token になりやすい |
+| Context7 のような Web ドキュメント読取ツール | AI がリクエスト時に Web ドキュメントを読み取り要約する | 中 | 手動貼り付けより便利だが、ページ取得、解析、広いドキュメントコンテキストのコストは残る |
+| CLI/MCP の対象指定クエリ | 1 つのエンドポイントまたは schema を構造化 JSON/Markdown で返す | 高 | API ドキュメント部分を通常約 70-95% 削減 |
+| MCP 検索後に詳細取得 | 小さな候補リストの後で正確なエンドポイント詳細を取得 | 高 | 大きな API セットに最適で、数百から数千 token に収まりやすい |
+
+保守的な例として、Knife4j/Swagger のモジュールドキュメントをコピーすると 10,000-30,000 token になる場合でも、単一エンドポイント向けの `apiskill_get_endpoint` または `apiskill_query_api` の応答は多くの場合 500-2,000 token 程度です。ドキュメント部分だけで約 5 倍から 60 倍の削減になります。同じドキュメントをフロントエンド、バックエンド、テスト作業で繰り返し使うほど、ローカルキャッシュにより効果は積み上がります。
+
+Context7 のような Web ドキュメント読取ツールは、ドキュメントが公開されていて最新の上流情報を参照したい場合に便利です。一方で、社内 API ドキュメントや繰り返し行うプロダクト開発では API Skill の方が予測しやすくなります。ドキュメントはすでにローカルに取り込まれ、アクセス処理は一度で済み、AI は広い Web ページを読み直す代わりに狭いローカル契約を照会または編集できるためです。
+
+より大きな価値は、token が安くなることだけではありません。構造化 lookup は無関係なコンテキストを減らし、フィールド名、必須フラグ、型、レスポンス構造を保持しやすくし、本当に必要なときだけ深い schema を追加で取得できます。
+
+### 総合的な費用対効果
+
+API Skill のコストは主に初期設定です。依存関係をインストールし、ドキュメントをインポートまたはクロールし、CLI または MCP アクセスを設定します。その後は同じキャッシュが日常の開発を支えます。エンドポイントが多い、schema が深い、複数人で開発している、AI 支援タスクが繰り返されるプロジェクトでは、早い段階で元が取れます。
+
+主なリターンは次の通りです。
+
+- 大きなドキュメントやスクリーンショットを繰り返しプロンプトへ入れる量を減らします。
+- agent に、記憶や視覚抽出ではなく決定的な API 探索ツールを提供します。
+- 上流ドキュメントが実装に遅れているときも、ローカル修正を保持できます。
+- 元のドキュメントソースを変えずに、ターミナル、エディタ、MCP クライアント、Web アプリで API コンテキストを使えます。
+
+エンドポイントが少なく安定している小規模プロジェクトでは、コピー&ペーストでも十分な場合があります。ただし、ページ、サービス、mock、テストを変化する API 契約に合わせて繰り返し実装するチームでは、CLI/MCP アクセスがコンテキストコストと統合ミスを同時に減らします。
+
+### CLI と MCP の使い分け
+
+CLI は最も移植性が高く、決定的な入口です。任意の shell、CI job、エディタ task、コマンドを実行できる AI ツールから利用できます。スクリプト化された一括更新、import/export 検証、再現可能な自動化では、CLI の方がデバッグしやすく共有もしやすいことが多いです。ユーザーや自動化が正確なコマンドだけを実行し、簡潔な結果だけを会話に戻すなら、CLI も token 効率に優れます。
+
+MCP は agent ワークフローに向いています。MCP 対応の AI クライアントはツールを発見し、`apiskill_search_endpoints`、`apiskill_create_document`、`apiskill_create_api`、`apiskill_get_endpoint` を直接呼び出し、構造化された結果だけを受け取れます。ユーザーがコマンド出力や API ドキュメント全体を貼り付ける必要がないため、prompt token を節約できることが多いです。一方で互換性の条件があります。AI ツールが stdio MCP server と tool schema をサポートする必要があり、クライアントによって timeout 処理、作業ディレクトリ設定、承認 UX、ツール結果の表示が異なる場合があります。
+
+CLI と MCP が同じ shared core に同じ payload を渡す場合、生成される API ドキュメントの内容は同じになるべきです。汎用自動化と CI での再現性を重視するなら CLI、AI agent がコーディング中に API ドキュメントを自律的に検索、作成、編集、照会するなら MCP を選びます。
+
+### プロジェクト統合の効果
+
+フロントエンドチームは、ページ、hooks、リクエスト client、フォーム、テーブル、バリデーションロジックを作るときに正確なエンドポイント契約を参照できます。レスポンスフィールド lookup は、ドキュメントページ全体をプロンプトに貼らずに API データを UI 状態へマッピングする助けになります。
+
+バックエンドチームは、同じキャッシュで既存契約を確認し、手動変更を比較し、上流 OpenAPI ドキュメントが更新される前に一時的または修正済みのローカル操作を公開できます。実装とドキュメントが少しずれている場面で特に有用です。
+
+テスト自動化では、同じエンドポイント詳細から mock、fixture payload、contract assertion、end-to-end の準備データを生成またはレビューできます。CLI と MCP がキャッシュを共有するため、テストはリモートドキュメントサイトの現在状態ではなく既知のバージョンに固定できます。
+
+Agent ワークフローでは MCP が最も効果的です。コーディング agent は `apiskill_search_endpoints` で検索し、`apiskill_get_endpoint` で正確なエンドポイントを確認し、必要なら `apiskill_get_schema` で schema コンテキストを取得してからコードを実装または更新できます。API ドキュメントは巨大なテキストではなく、プロジェクトレベルのツールになります。
+
+## ドキュメント
+
+- Web アプリ: [English](docs/web.md) / [中文](docs/web.zh.md) / [한국어](docs/web.ko.md) / [日本語](docs/web.ja.md)
+- CLI 設定と使い方: [English](docs/cli.md) / [中文](docs/cli.zh.md) / [한국어](docs/cli.ko.md) / [日本語](docs/cli.ja.md)
+- MCP 設定と使い方: [English](docs/mcp.md) / [中文](docs/mcp.zh.md) / [한국어](docs/mcp.ko.md) / [日本語](docs/mcp.ja.md)
+
+## データモデル
+
+すべての入口は同じキャッシュを読み書きします。
+
+```text
+cache/latest-import.json
+cache/versions/
+```
+
+Web アプリと CLI は、リモートまたはローカルの OpenAPI ドキュメントをインポートできます。MCP サーバーはキャッシュを照会でき、明示的に書き込みツールを呼び出した場合は、ドキュメントのインポートや手動 API 操作の作成、編集、削除も行えます。

package/README.ko.md

@@ -0,0 +1,108 @@
+# API Skill
+
+[English](README.md) / [中文](README.zh.md) / [한국어](README.ko.md) / [日本語](README.ja.md)
+
+API Skill은 프론트엔드 개발과 AI 보조 코딩을 위한 로컬 OpenAPI/Swagger 작업 공간입니다. 세 가지 진입점이 같은 캐시된 API 문서를 공유합니다.
+
+- Web 앱: API 문서를 가져오고, 탐색하고, 검색하고, 검사하고, 테스트하며, 수동 API 작업을 관리합니다.
+- CLI: 터미널에서 문서를 가져오고 로컬 API 버전을 관리하거나 조회합니다.
+- MCP 서버: 같은 API 컨텍스트와 유지 관리 기능을 Codex 또는 다른 MCP 클라이언트에 제공합니다.
+
+## Web 앱 사용
+
+프로젝트 루트에서 시작합니다.
+
+```bash
+npm install
+npm run dev
+```
+
+터미널에 표시되는 로컬 Vite URL을 엽니다. Web 앱은 직접 OpenAPI JSON/YAML URL 가져오기, Swagger UI / Knife4j / Redoc 페이지 크롤링, 로컬 파일 업로드, OpenAPI 문서를 반환하는 curl 명령 실행, 그리고 빈 문서를 처음부터 생성하는 흐름을 지원합니다.
+
+가져오거나 새로 만든 뒤에는 버전 선택기로 캐시된 문서를 전환하고, 경로, 요약, 태그, method, 파라미터 텍스트로 엔드포인트를 검색할 수 있습니다. 엔드포인트 탭에서는 요청 파라미터, 요청 본문, 응답 필드, AI 친화적인 컨텍스트, 원본 JSON을 확인할 수 있습니다. 수동 API 작업을 추가, 편집, 삭제할 수도 있으며, 변경 사항은 로컬 캐시 버전으로 저장됩니다.
+
+CLI와 MCP를 사용하기 전에 내장 검사를 먼저 실행하는 것을 권장합니다.
+
+```bash
+npm run cli -- check
+```
+
+CLI에서 처음부터 시작하려면 `npm run cli -- document create --title "My API" --doc-version 1.0.0`으로 빈 문서를 만들고 `api create`로 엔드포인트를 추가합니다. MCP 클라이언트에서는 `apiskill_check`로 캐시를 확인하고, 상위 문서가 없으면 `apiskill_create_document`로 빈 문서를 만든 뒤, `apiskill_help`로 사용 가능한 도구를 확인합니다.
+
+## 이 도구를 개발한 이유
+
+대형 AI 모델이 등장한 이후 몇 년 동안 개발자가 AI로 코딩하는 방식은 계속 변해 왔습니다. 처음에는 ChatGPT 웹 화면에서 코드, 오류, API 문서를 복사해 붙여 넣는 방식이 많았습니다. 이후 Cursor, Codex, Claude Code처럼 전체 프로젝트에 통합되는 데스크톱 또는 로컬 개발 도구가 등장하면서, AI 개발 방식은 단발성 질의응답에서 프로젝트 전체 컨텍스트를 함께 다루는 방식으로 이동했습니다.
+
+API 문서를 쓰는 방식도 함께 바뀌었습니다. 초기에는 API 문서를 그대로 붙여 넣거나 문서 화면을 캡처해서 AI에게 전달했습니다. 이후 Context7 같은 도구가 등장하면서 AI 어시스턴트가 웹 기반 API 문서를 직접 읽을 수 있게 되었습니다. 이것은 큰 개선이지만, 실제 개발에서는 여전히 몇 가지 문제가 남습니다.
+
+- AI가 웹 문서를 읽고 해석하는 과정은 추가 token을 소비하며, 큰 Swagger, Knife4j, 제품 문서에서는 낭비와 대기 시간이 커집니다.
+- 내부 문서는 로그인, cookie, access key, 사내 네트워크 같은 접근 처리가 필요한 경우가 많습니다.
+- AI가 문서를 읽을 수 있더라도, 문서를 새로 만들거나 수정하거나 버전 관리하는 능력은 보통 직접 제공되지 않습니다.
+
+API Skill은 이 빈틈을 메우기 위해 만들어졌습니다. API 문서를 로컬로 가져오고, 크롤링하고, 처음부터 만들고, 조회하고, 편집하고, 버전 관리하며, 같은 구조화된 계약을 Web 앱, CLI, MCP 서버로 제공합니다. 목표는 API 문서를 반복해서 붙여 넣는 텍스트나 스크린샷이 아니라, AI 어시스턴트가 안정적으로 사용하고 지속적으로 관리할 수 있는 프로젝트 수준 도구로 만드는 것입니다.
+
+### Token 효율
+
+정확한 절감량은 문서 크기, schema 깊이, 작업에 필요한 주변 컨텍스트에 따라 달라지지만 실무 패턴은 일관적입니다.
+
+| Workflow | 모델에 전달되는 일반적인 컨텍스트 | 재사용성 | 예상 token 영향 |
+| --- | --- | --- | --- |
+| 문서 스크린샷 | 이미지 token과 보이는 페이지 전체의 시각적 해석 | 낮음 | 비용이 크고 필드를 정확히 인용하기 어렵습니다 |
+| 문서 텍스트 복사 | 전체 페이지 텍스트, 네비게이션, 예제, 관련 없는 엔드포인트 | 낮음-보통 | 작업당 수천에서 수만 token이 되기 쉽습니다 |
+| Context7 같은 웹 문서 읽기 도구 | AI가 요청 시점에 웹 문서를 읽고 요약합니다 | 보통 | 수동 붙여넣기보다 편하지만, 페이지 가져오기, 파싱, 넓은 문서 컨텍스트 비용은 여전히 발생합니다 |
+| CLI/MCP 정밀 조회 | 하나의 엔드포인트 또는 schema를 구조화된 JSON/Markdown으로 반환 | 높음 | API 문서 컨텍스트를 보통 약 70-95% 줄입니다 |
+| MCP 검색 후 상세 조회 | 작은 후보 목록 뒤 정확한 엔드포인트 상세 정보 조회 | 높음 | 큰 API 세트에 가장 효율적이며 수백-수천 token으로 끝나는 경우가 많습니다 |
+
+보수적인 예로, Knife4j/Swagger 모듈 문서를 복사하면 10,000-30,000 token이 필요할 수 있지만, 단일 엔드포인트에 대한 `apiskill_get_endpoint` 또는 `apiskill_query_api` 응답은 보통 500-2,000 token 정도입니다. 문서 컨텍스트만 놓고 보면 약 5배에서 60배까지 줄어들 수 있습니다. 프론트엔드, 백엔드, 테스트 작업에서 같은 문서를 반복 사용할수록 절감 효과는 누적됩니다.
+
+Context7 같은 웹 문서 읽기 도구는 문서가 공개되어 있고 최신 상위 자료를 참고해야 할 때 유용합니다. 하지만 내부 API 문서나 반복적인 제품 개발에서는 API Skill이 더 예측 가능합니다. 문서가 이미 로컬에 가져와져 있고, 접근 처리는 한 번만 하면 되며, AI가 큰 웹 페이지를 반복해서 읽는 대신 좁은 로컬 계약을 조회하거나 편집할 수 있기 때문입니다.
+
+더 큰 이점은 단순히 token 비용이 낮아지는 것만이 아닙니다. 구조화된 조회는 관련 없는 컨텍스트를 줄이고, 필드명, 필수 여부, 타입, 응답 구조를 더 안정적으로 보존하며, 실제로 필요할 때만 더 깊은 schema를 가져올 수 있게 합니다.
+
+### 종합적인 비용 대비 효과
+
+API Skill의 비용은 주로 한 번의 설정입니다. 의존성을 설치하고, 문서를 가져오거나 크롤링하고, CLI 또는 MCP 접근을 구성하면 됩니다. 그 이후에는 같은 캐시가 일상적인 개발 작업을 지원합니다. 엔드포인트가 많거나, schema가 깊거나, 여러 개발자가 협업하거나, AI 보조 작업이 반복되는 프로젝트라면 보통 빠르게 비용을 회수합니다.
+
+가장 큰 수익은 다음에서 나옵니다.
+
+- 큰 문서나 스크린샷을 반복해서 프롬프트에 넣는 일을 줄입니다.
+- agent에게 기억이나 시각적 추출 대신 결정적인 API 탐색 도구를 제공합니다.
+- 상위 문서가 구현보다 늦을 때 로컬 수정본을 유지할 수 있습니다.
+- 원본 문서 소스를 바꾸지 않고도 터미널, 에디터, MCP 클라이언트, Web 앱에서 API 컨텍스트를 사용할 수 있습니다.
+
+엔드포인트가 아주 적고 안정적인 작은 프로젝트라면 복사-붙여넣기도 충분할 수 있습니다. 하지만 페이지, 서비스, mock, 테스트를 변경되는 API 계약에 맞춰 반복 구현하는 팀이라면 CLI/MCP 접근은 컨텍스트 비용과 통합 실수를 함께 줄여 줍니다.
+
+### CLI와 MCP 선택 기준
+
+CLI는 가장 이식성이 높고 결정적인 진입점입니다. 어떤 shell, CI 작업, 에디터 task, 명령을 실행할 수 있는 AI 도구에서도 사용할 수 있습니다. 스크립트 기반 대량 업데이트, import/export 검증, 재현 가능한 자동화에서는 CLI가 보통 더 디버깅하기 쉽고 공유하기도 쉽습니다. 사용자나 자동화가 정확한 명령만 실행하고 요약 결과만 대화에 가져오면 CLI도 token 효율이 좋습니다.
+
+MCP는 agent 워크플로에 더 적합합니다. MCP를 지원하는 AI 클라이언트는 도구를 발견하고 `apiskill_search_endpoints`, `apiskill_create_document`, `apiskill_create_api`, `apiskill_get_endpoint`를 직접 호출하며 구조화된 결과만 받을 수 있습니다. 사용자가 명령 출력이나 전체 API 문서를 직접 붙여 넣지 않아도 되므로 prompt token을 줄이는 경우가 많습니다. 단점은 호환성입니다. AI 도구가 stdio MCP server와 tool schema를 지원해야 하며, 클라이언트마다 timeout 처리, 작업 디렉터리 설정, 승인 UX, 도구 결과 표시 방식이 다를 수 있습니다.
+
+CLI와 MCP가 같은 shared core에 같은 payload를 전달하면 생성되는 API 문서 내용은 동일해야 합니다. 범용 자동화와 CI 재현성이 중요하면 CLI를, AI agent가 코딩 중 API 문서를 직접 검색, 생성, 편집, 조회해야 하면 MCP를 선택하세요.
+
+### 프로젝트 통합 효과
+
+프론트엔드 팀은 페이지, hooks, 요청 client, 폼, 테이블, 검증 로직을 작성할 때 정확한 엔드포인트 계약을 조회할 수 있습니다. 응답 필드 조회는 전체 문서 페이지를 프롬프트에 붙여 넣지 않고도 API 데이터를 UI 상태로 매핑하는 데 도움을 줍니다.
+
+백엔드 팀은 같은 캐시로 기존 계약을 확인하고, 수동 변경을 비교하며, 상위 OpenAPI 문서가 업데이트되기 전 임시 또는 수정된 로컬 작업을 노출할 수 있습니다. 구현과 문서가 약간 어긋난 상황에 특히 유용합니다.
+
+테스트 자동화는 같은 엔드포인트 상세 정보를 기반으로 mock, fixture payload, contract assertion, end-to-end 준비 데이터를 생성하거나 검토할 수 있습니다. CLI와 MCP가 캐시를 공유하므로 테스트는 원격 문서 사이트의 현재 상태 대신 알려진 버전에 고정할 수 있습니다.
+
+Agent 워크플로는 MCP에서 가장 큰 이점을 얻습니다. 코딩 agent는 `apiskill_search_endpoints`로 검색하고, `apiskill_get_endpoint`로 정확한 엔드포인트를 확인하고, 필요하면 `apiskill_get_schema`로 schema 컨텍스트를 가져온 뒤 코드를 구현하거나 수정할 수 있습니다. API 문서가 거대한 텍스트 덩어리가 아니라 프로젝트 수준 도구가 됩니다.
+
+## 문서
+
+- Web 앱: [English](docs/web.md) / [中文](docs/web.zh.md) / [한국어](docs/web.ko.md) / [日本語](docs/web.ja.md)
+- CLI 구성 및 사용법: [English](docs/cli.md) / [中文](docs/cli.zh.md) / [한국어](docs/cli.ko.md) / [日本語](docs/cli.ja.md)
+- MCP 구성 및 사용법: [English](docs/mcp.md) / [中文](docs/mcp.zh.md) / [한국어](docs/mcp.ko.md) / [日本語](docs/mcp.ja.md)
+
+## 데이터 모델
+
+모든 진입점은 같은 캐시를 읽고 씁니다.
+
+```text
+cache/latest-import.json
+cache/versions/
+```
+
+Web 앱과 CLI는 원격 또는 로컬 OpenAPI 문서를 가져올 수 있습니다. MCP 서버는 캐시를 조회할 수 있으며, 명시적으로 쓰기 도구를 호출하면 문서를 가져오거나 수동 API 작업을 생성, 편집, 삭제할 수 있습니다.

package/README.md

@@ -0,0 +1,119 @@
+# API Skill
+
+[English](README.md) / [中文](README.zh.md) / [한국어](README.ko.md) / [日本語](README.ja.md)
+
+API Skill is a local OpenAPI/Swagger workspace for frontend and agent-assisted development. It has three surfaces that share the same cached API documents:
+
+- Web app: import, browse, search, inspect, test, and manually maintain API operations.
+- CLI: import documents, manage/query local API versions, and start a MOCK server from a terminal.
+- MCP server: expose the same API context and maintenance actions to Codex or other MCP clients.
+
+## Web App Usage
+
+After installing from npm, start the web app from any project directory:
+
+```bash
+npm install -g apiskill
+apiskill run web
+```
+
+The web app stores version data in `cache/` under the current directory by default. When developing this repository, you can also start it from the project root:
+
+```bash
+npm install
+npm run dev
+```
+
+Open the local URL shown in the terminal. The web app can import API documents from a direct OpenAPI JSON/YAML URL, crawl a Swagger UI / Knife4j / Redoc page, upload a local file, execute a curl command that returns an OpenAPI document, or create a blank document from scratch.
+
+After importing or creating a blank document, use the version selector to switch cached documents, search endpoints by path, summary, tag, method, or parameter text, and open endpoint tabs to inspect request parameters, request bodies, response fields, AI-ready context, and raw JSON. You can also add, edit, or delete manual API operations; those changes are saved as local cached versions.
+
+After API document data exists, click Start MOCK Service in the web app or run `apiskill mock` in CLI to start a local random-data MOCK API server from the current interface definitions.
+
+For CLI and MCP usage, run the built-in checks first:
+
+```bash
+npm run cli -- check
+```
+
+After npm installation, the equivalent command is `apiskill check`.
+
+To start from zero in CLI, run `npm run cli -- document create --title "My API" --doc-version 1.0.0`, then add endpoints with `api create`. In MCP clients, call `apiskill_check` to verify the cache, `apiskill_create_document` to create a blank document when no upstream docs exist, and `apiskill_help` to list available tools.
+
+## Why This Tool Exists
+
+Since large AI models became available, the way developers use AI for coding has changed quickly. At first, many of us worked in the ChatGPT web UI by copying code, errors, and API documentation back and forth. Later, tools such as Cursor, Codex, and Claude Code made it possible for AI assistants to work inside an entire project, so the workflow moved from isolated prompts toward project-aware development.
+
+API documentation workflows changed along the way too. The earliest pattern was to paste API docs or upload screenshots. Then tools such as Context7 made it possible for AI assistants to read web-based API documentation directly. That is a big improvement, but it still leaves several practical problems:
+
+- Reading and parsing web documentation consumes extra tokens and often adds noticeable waiting time, especially for large Swagger, Knife4j, or product docs.
+- Internal documentation often requires authentication, cookies, network access, or other access-key handling before an AI tool can read it.
+- Even when the AI can read the documentation, it usually cannot edit the API documentation itself or maintain a local versioned contract for the project.
+
+API Skill was created to close that gap. It imports, crawls, creates, queries, edits, and versions API documentation locally, then exposes the same structured contract through the web app, CLI, and MCP server. The goal is to make API docs a project-level tool that AI assistants can reliably use and maintain, rather than a blob of pasted text or a screenshot.
+
+### Token Efficiency
+
+The exact saving depends on document size, schema depth, and how much surrounding conversation the task needs, but the practical pattern is consistent:
+
+| Workflow | Typical context sent to the model | Reuse | Expected token impact |
+| --- | --- | --- | --- |
+| Screenshot of docs | Image tokens plus visual parsing of the whole visible page | Low | High cost, harder to quote exact fields |
+| Pasted docs text | Full page text, navigation, examples, and often many unrelated endpoints | Low to medium | Often thousands to tens of thousands of tokens per task |
+| Web-doc readers such as Context7 | AI reads and summarizes web documentation at request time | Medium | Better than manual paste, but still pays for page retrieval, parsing, and often broad documentation context |
+| CLI/MCP targeted query | One endpoint or schema in structured JSON/Markdown | High | Commonly reduces API-document context by about 70-95% |
+| MCP search then endpoint lookup | Small candidate list, then exact endpoint details | High | Best for large API sets; often avoids sending more than a few hundred to a few thousand tokens |
+
+A conservative example: if a copied Knife4j/Swagger page or exported text for a module is 10,000-30,000 tokens, a targeted `apiskill_get_endpoint` or `apiskill_query_api` response for one endpoint is often 500-2,000 tokens. That is roughly a 5x to 60x reduction for the documentation portion of the prompt. The saving compounds across repeated frontend, backend, and test tasks because the imported document stays local and does not need to be pasted again.
+
+Web-doc readers such as Context7 are useful when the documentation is public and the task needs fresh upstream reference material. For internal API docs or repeated product work, API Skill is more predictable because the document is already imported, access handling happens once, and the AI can query or edit a narrow local contract instead of re-reading broad web pages.
+
+The bigger gain is not only lower token usage. Structured lookups reduce irrelevant context, make field names and required flags easier to preserve, and let the assistant fetch more detail only when the current task actually needs it.
+
+### Overall Cost Effectiveness
+
+API Skill has a small setup cost: install dependencies, import or crawl the document, and configure CLI or MCP access. After that, the same cache serves daily development work. The break-even point is usually reached quickly when a project has many endpoints, nested schemas, multiple developers, or repeated AI-assisted tasks.
+
+The strongest return comes from:
+
+- Reducing repeated prompt stuffing and screenshot interpretation.
+- Giving agents deterministic tools for API discovery instead of relying on memory or visual extraction.
+- Keeping local corrections when upstream docs lag behind implementation.
+- Making API context available inside terminals, editors, MCP clients, and the web app without changing the source document.
+
+For very small projects with only a few stable endpoints, copy-paste may be acceptable. For teams that repeatedly implement pages, services, mocks, or tests against changing API contracts, CLI/MCP access usually pays for itself through lower context cost and fewer integration mistakes.
+
+### CLI vs MCP
+
+CLI is the most portable and deterministic surface. It works in any shell, CI job, editor task, or AI tool that can run commands. For scripted bulk updates, import/export checks, and reproducible automation, CLI is usually faster to debug and easier to share. It can also be token-efficient when the user or automation calls exact commands and only pastes back concise results.
+
+MCP is usually better for agent workflows. A compatible AI client can discover tools, call `apiskill_search_endpoints`, `apiskill_create_document`, `apiskill_create_api`, or `apiskill_get_endpoint` directly, and only receive structured results. This often saves prompt tokens because the user does not need to paste command output or full API documents into the conversation. The tradeoff is compatibility: MCP requires the AI tool to support stdio MCP servers and tool schemas, and different clients may vary in timeout handling, working-directory setup, approval UX, and how tool results are displayed.
+
+Generated API content should be the same when CLI and MCP call the same shared core with the same payload. Choose CLI for universal automation and CI-friendly repeatability; choose MCP when an AI agent should autonomously search, create, edit, and query API documentation during coding.
+
+### Project Integration Benefits
+
+Frontend teams can query exact endpoint contracts while building pages, hooks, request clients, forms, tables, and validation logic. Response-field lookups make it easier to map API data into UI state without pasting an entire doc page into the prompt.
+
+Backend teams can use the same cache to inspect existing contracts, compare manual changes, and expose temporary or corrected local operations before the upstream OpenAPI source is updated. This is useful when implementation and documentation are slightly out of sync.
+
+Test automation can generate or review mocks, fixture payloads, contract assertions, and end-to-end setup from the same endpoint details used by frontend and backend work. Because CLI and MCP share the cache, tests can run against a known version instead of whatever a remote documentation site currently returns.
+
+Agent workflows benefit most from MCP. A coding agent can call `apiskill_search_endpoints`, inspect the exact endpoint with `apiskill_get_endpoint`, fetch schema context with `apiskill_get_schema`, and then implement or update code with less manual prompting. That turns API documentation from a blob of text into a project-level tool.
+
+## Documentation
+
+- Web app: [English](docs/web.md) / [中文](docs/web.zh.md) / [한국어](docs/web.ko.md) / [日本語](docs/web.ja.md)
+- CLI configuration and usage: [English](docs/cli.md) / [中文](docs/cli.zh.md) / [한국어](docs/cli.ko.md) / [日本語](docs/cli.ja.md)
+- MCP configuration and usage: [English](docs/mcp.md) / [中文](docs/mcp.zh.md) / [한국어](docs/mcp.ko.md) / [日本語](docs/mcp.ja.md)
+
+## Data Model
+
+All surfaces read and write the same cache:
+
+```text
+cache/latest-import.json
+cache/versions/
+```
+
+The web app and CLI can import remote or local OpenAPI documents. The MCP server can query the cache and, when explicitly called through write tools, import documents or create/edit/delete manual API operations.

package/README.zh.md

@@ -0,0 +1,119 @@
+# API Skill
+
+[English](README.md) / [中文](README.zh.md) / [한국어](README.ko.md) / [日本語](README.ja.md)
+
+API Skill 是一个本地 OpenAPI/Swagger 工作区，面向前端开发和 AI 辅助编码。它提供三种入口，并共享同一份本地缓存接口文档：
+
+- Web 端：导入、浏览、搜索、查看、测试和手动维护接口。
+- CLI：在终端里导入文档、管理版本、查询和维护本地接口，并启动 MOCK 服务。
+- MCP 服务：把同一套接口上下文和维护能力暴露给 Codex 或其他 MCP 客户端。
+
+## Web 端使用
+
+从 npm 安装后，可以在任意项目目录启动 Web 端：
+
+```bash
+npm install -g apiskill
+apiskill run web
+```
+
+Web 端默认使用当前目录下的 `cache/` 保存版本数据。开发本仓库时也可以在项目根目录启动：
+
+```bash
+npm install
+npm run dev
+```
+
+打开终端输出的本地地址。Web 端可以导入直接的 OpenAPI JSON/YAML 地址，爬取 Swagger UI / Knife4j / Redoc 页面，上传本地文件，执行返回 OpenAPI 文档的 curl 命令，也可以从零新建空白文档。
+
+导入或新建文档后，可以用版本选择器切换缓存文档，按路径、摘要、tag、method 或参数文本搜索接口，并打开接口 tab 查看请求参数、请求体、响应字段、AI 友好的上下文和原始 JSON。也可以新增、编辑、删除手动接口；这些改动会保存为本地缓存版本。
+
+已有 API 文档数据后，可以在 Web 端点击“启动MOCK服务”，或在 CLI 里运行 `apiskill mock`，根据当前接口定义启动本地随机数据 MOCK API 服务。
+
+CLI 和 MCP 使用前建议先运行内置检查：
+
+```bash
+npm run cli -- check
+```
+
+npm 安装后的等价命令是 `apiskill check`。
+
+如果要通过 CLI 从零开始，运行 `npm run cli -- document create --title "My API" --doc-version 1.0.0` 创建空白文档，再用 `api create` 追加接口。在 MCP 客户端里，先调用 `apiskill_check` 检查缓存；没有上游文档时调用 `apiskill_create_document` 创建空白文档；再调用 `apiskill_help` 查看可用工具。
+
+## 为什么开发这个工具
+
+自从 AI 大模型面世这几年，开发人员使用 AI 写代码的方式一直在变化。最开始，很多人是在 ChatGPT 网页端来回复制粘贴代码、报错和接口文档；后来 Cursor、Codex、Claude Code 这类可以集成整个项目的桌面端或本地开发工具出现，AI 辅助开发逐渐从单次问答变成了围绕整个项目上下文协作。
+
+接口文档的使用方式也在变化。最早通常是直接复制粘贴接口文档，或者把接口文档截图发给 AI；后来有了 Context7 这类工具，可以让 AI 助手直接读取网页端 API 文档。这已经方便了很多，但实际开发里仍然有几个问题：
+
+- AI 解析网页文档会消耗额外 token，文档越大浪费越明显，也会带来更多等待时间。
+- 有些内部文档需要登录、cookie、访问密钥或内网环境，AI 工具读取前还要额外处理访问权限问题。
+- 即使 AI 能读取到文档，当需要新增、编辑、修正文档时，它通常也没有直接维护接口文档和版本的能力。
+
+因此才有了开发 API Skill 的想法。它把接口文档导入、爬取、从零创建、查询、编辑和多版本管理都放到本地，并通过 Web、CLI、MCP 暴露同一份结构化契约。目标是让接口文档变成 AI 助手可以稳定调用和持续维护的项目级工具，而不是一大段反复粘贴的文本或截图。
+
+### Token 节省评估
+
+实际节省比例取决于文档大小、schema 层级深度和任务本身需要多少上下文，但工程上的趋势比较稳定：
+
+| 方式 | 通常发送给模型的上下文 | 复用性 | 预期 token 影响 |
+| --- | --- | --- | --- |
+| 文档截图 | 图片 token，加上整页可视内容解析 | 低 | 成本高，也不利于精确引用字段 |
+| 复制文档文本 | 整页文本、导航、示例，以及很多无关接口 | 中低 | 单次任务经常是数千到数万 token |
+| Context7 这类网页文档读取工具 | AI 在请求时读取并总结网页文档 | 中 | 比手动粘贴更方便，但仍要承担页面获取、解析和较宽泛文档上下文的成本 |
+| CLI/MCP 精确查询 | 一个接口或 schema 的结构化 JSON/Markdown | 高 | 接口文档上下文通常可减少约 70-95% |
+| MCP 先搜索再查详情 | 小候选列表，再获取精确接口详情 | 高 | 大接口集最划算，常常只需要几百到几千 token |
+
+一个保守例子：如果复制一段 Knife4j/Swagger 模块文档需要 10,000-30,000 token，那么一次针对单接口的 `apiskill_get_endpoint` 或 `apiskill_query_api` 返回通常在 500-2,000 token 左右。仅接口文档这部分，就可能减少约 5 倍到 60 倍的上下文体积。随着前端、后端、测试任务反复使用同一份文档，节省会继续叠加，因为文档已经在本地缓存，不需要每次重新粘贴。
+
+Context7 这类网页文档读取工具很适合公开文档、并且需要实时参考上游资料的场景。但对于内部接口文档或反复迭代的业务项目，API Skill 会更可控：文档已经导入本地，访问权限只需要处理一次，AI 可以查询或编辑很窄的本地接口契约，而不是反复读取大段网页内容。
+
+更大的收益不只是 token 便宜。结构化查询能减少无关上下文，让字段名、必填状态、类型和响应结构更容易被保留，也允许 AI 在确实需要时再继续取更深的 schema。
+
+### 综合性价比
+
+API Skill 的成本主要是一次性配置：安装依赖、导入或爬取文档、配置 CLI 或 MCP。完成后，同一份缓存可以服务日常开发。只要项目接口数量较多、schema 较深、多人协作，或经常让 AI 辅助写页面、服务和测试，通常很快就能回本。
+
+收益主要来自：
+
+- 减少反复粘贴大段文档和截图识别。
+- 给 AI agent 一个确定性的接口发现工具，而不是依赖记忆或视觉提取。
+- 当上游文档滞后时，可以保留本地修正。
+- 让接口上下文同时出现在终端、编辑器、MCP 客户端和 Web 端，不需要改变原始文档来源。
+
+如果项目很小，只有少量稳定接口，直接复制文本也可以接受。但对于需要持续实现页面、服务、mock 或测试的团队，CLI/MCP 通常能同时降低上下文成本和集成错误率。
+
+### CLI 和 MCP 怎么选
+
+CLI 是最通用、最确定的入口。它可以在任何 shell、CI 任务、编辑器任务，或能执行命令的 AI 工具里使用。脚本化批量更新、导入导出检查、可复现自动化这类场景，CLI 通常更容易调试和分享。如果用户或自动化只执行精确命令，并只把精简结果带回对话，CLI 也很省 token。
+
+MCP 更适合 agent 工作流。兼容 MCP 的 AI 客户端可以自动发现工具，直接调用 `apiskill_search_endpoints`、`apiskill_create_document`、`apiskill_create_api`、`apiskill_get_endpoint` 等能力，并只接收结构化结果。这样通常能节省提示词 token，因为用户不需要手动粘贴命令输出或完整接口文档。代价是兼容性：AI 工具需要支持 stdio MCP server 和工具 schema，不同客户端在超时处理、工作目录配置、权限确认体验、工具结果展示上可能会有差异。
+
+如果 CLI 和 MCP 调用同一套 shared core，并传入相同 payload，生成的 API 文档内容应该一致。需要通用自动化和 CI 可复现时优先 CLI；希望 AI agent 在编码过程中自主搜索、创建、编辑、查询接口文档时优先 MCP。
+
+### 项目集成收益
+
+前端团队可以在写页面、hooks、请求 client、表单、表格和校验逻辑时查询精确接口契约。响应字段查询能帮助把 API 数据映射到 UI 状态，而不需要把整页文档贴给模型。
+
+后端团队可以用同一份缓存查看现有契约、对比手动变更，并在上游 OpenAPI 文档更新前先维护临时或修正后的本地接口。这对实现已经变化但文档还没同步的场景很实用。
+
+测试自动化可以基于同一份接口详情生成或检查 mock、fixture、契约断言和端到端测试准备数据。因为 CLI 和 MCP 共享缓存，测试可以绑定到某个已知版本，而不是依赖远程文档站点当前返回的内容。
+
+Agent 工作流最适合接入 MCP。编码 agent 可以先调用 `apiskill_search_endpoints` 搜索接口，再用 `apiskill_get_endpoint` 获取精确详情，需要时用 `apiskill_get_schema` 展开 schema，然后再实现或修改代码。这样接口文档不再是一大坨文本，而变成项目级工具。
+
+## 文档
+
+- Web 端：[English](docs/web.md) / [中文](docs/web.zh.md) / [한국어](docs/web.ko.md) / [日本語](docs/web.ja.md)
+- CLI 配置和使用：[English](docs/cli.md) / [中文](docs/cli.zh.md) / [한국어](docs/cli.ko.md) / [日本語](docs/cli.ja.md)
+- MCP 配置和使用：[English](docs/mcp.md) / [中文](docs/mcp.zh.md) / [한국어](docs/mcp.ko.md) / [日本語](docs/mcp.ja.md)
+
+## 数据模型
+
+所有入口都读写同一套缓存：
+
+```text
+cache/latest-import.json
+cache/versions/
+```
+
+Web 端和 CLI 可以导入远程或本地 OpenAPI 文档。MCP 服务可以查询缓存；当明确调用写入工具时，也可以导入文档或创建、编辑、删除手动接口。