apiskill 0.1.0

package/docs/mcp.md

@@ -0,0 +1,79 @@
+# API Skill MCP
+
+[English](mcp.md) / [中文](mcp.zh.md) / [한국어](mcp.ko.md) / [日本語](mcp.ja.md)
+
+## Local Codex Configuration
+
+API Skill runs as a stdio MCP server:
+
+```bash
+node /Users/dobby/dev/apiskill/scripts/mcp-server.mjs
+```
+
+Add this to `/Users/dobby/.codex/config.toml` or keep the project-level `.codex/config.toml` when your Codex client loads project config:
+
+```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_servers.apiskill.env]
+APISKILL_ROOT = "/Users/dobby/dev/apiskill"
+APISKILL_CACHE_DIR = "/Users/dobby/dev/apiskill/cache"
+```
+
+Restart Codex and run `/mcp`. You should see `apiskill` with the tools below.
+
+## Read Tools
+
+- `apiskill_check`: check whether a usable cached OpenAPI document exists and return import examples when it does not.
+- `apiskill_help`: show MCP help, available tools, and import examples.
+- `apiskill_list_versions`: list cached versions.
+- `apiskill_search_endpoints`: search endpoint summaries.
+- `apiskill_query_api`: CLI-equivalent query. Single matches can return JSON, raw endpoint data, or CLI config.
+- `apiskill_get_endpoint`: get one endpoint with parameters, request body, responses, manual config, and optional raw operation.
+- `apiskill_get_ai_context`: get AI-ready Markdown for one endpoint.
+- `apiskill_get_schema`: expand a named schema.
+
+## Write Tools
+
+These tools modify `cache/latest-import.json` and `cache/versions/`:
+
+- `apiskill_import_url`: import a direct OpenAPI JSON/YAML URL.
+- `apiskill_crawl_openapi`: crawl Swagger UI / Knife4j / Redoc and import the discovered document.
+- `apiskill_import_file`: import a local JSON/YAML file.
+- `apiskill_import_curl`: execute a curl command and import its OpenAPI response.
+- `apiskill_create_document`: create a blank OpenAPI document version for from-scratch API authoring.
+- `apiskill_create_api`: create a manual API operation.
+- `apiskill_edit_api`: edit/replace a manual API operation.
+- `apiskill_delete_api`: delete an API operation.
+
+## Author From Scratch
+
+When a project has no upstream documentation yet, ask the agent to call `apiskill_create_document` first:
+
+```json
+{
+  "title": "My API",
+  "version": "1.0.0",
+  "description": "Internal service contract"
+}
+```
+
+Then add endpoints with `apiskill_create_api`, edit them with `apiskill_edit_api`, and query them with `apiskill_get_endpoint` or `apiskill_query_api`. This lets an AI tool build and maintain a local API contract before any third-party OpenAPI source exists.
+
+## Verify
+
+```bash
+npm run mcp
+```
+
+For protocol-level verification, initialize the server, call `tools/list`, then call `apiskill_check` and `apiskill_list_versions`. The server should return `serverInfo.name = apiskill-mcp` and list the `apiskill_*` tools.
+
+## Future Server Deployment
+
+The current setup is local stdio. For a server deployment, either start the same stdio server through SSH/remote execution with server-side `APISKILL_ROOT` and `APISKILL_CACHE_DIR`, or add a Streamable HTTP MCP wrapper that calls the same shared core module. Keep tool names and payload semantics stable.

package/docs/mcp.zh.md

@@ -0,0 +1,79 @@
+# API Skill MCP
+
+[English](mcp.md) / [中文](mcp.zh.md) / [한국어](mcp.ko.md) / [日本語](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_servers.apiskill.env]
+APISKILL_ROOT = "/Users/dobby/dev/apiskill"
+APISKILL_CACHE_DIR = "/Users/dobby/dev/apiskill/cache"
+```
+
+重启 Codex 后运行 `/mcp`，应该能看到 `apiskill` 和下面的工具。
+
+## 只读工具
+
+- `apiskill_check`：检查是否有可用的 OpenAPI 缓存文档；如果没有，会返回导入示例。
+- `apiskill_help`：展示 MCP 帮助、可用工具和导入示例。
+- `apiskill_list_versions`：列出缓存版本。
+- `apiskill_search_endpoints`：搜索接口摘要。
+- `apiskill_query_api`：等价于 CLI query。单条匹配时可以返回 JSON、raw endpoint 或 CLI config。
+- `apiskill_get_endpoint`：获取单个接口的参数、请求体、响应字段、手动配置和可选 raw operation。
+- `apiskill_get_ai_context`：获取适合 AI 使用的接口 Markdown。
+- `apiskill_get_schema`：展开指定 schema。
+
+## 写入工具
+
+以下工具会修改 `cache/latest-import.json` 和 `cache/versions/`：
+
+- `apiskill_import_url`：导入直接 OpenAPI JSON/YAML 地址。
+- `apiskill_crawl_openapi`：爬取 Swagger UI / Knife4j / Redoc 并导入识别到的文档。
+- `apiskill_import_file`：导入本地 JSON/YAML 文件。
+- `apiskill_import_curl`：执行 curl 命令并导入其 OpenAPI 响应。
+- `apiskill_create_document`：创建空白 OpenAPI 文档版本，用于从零编写接口文档。
+- `apiskill_create_api`：创建手动接口。
+- `apiskill_edit_api`：编辑/替换手动接口。
+- `apiskill_delete_api`：删除接口。
+
+## 从零编写
+
+如果项目还没有上游文档，可以先让 AI 调用 `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 工具生成并持续维护本地接口契约。
+
+## 验证
+
+```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` 配好；长期多人使用时再增加 Streamable HTTP MCP 包装层，继续调用同一个 shared core 模块，并保持工具名称和参数语义稳定。

package/docs/web.ja.md

@@ -0,0 +1,44 @@
+# API Skill Web アプリ
+
+[English](web.md) / [中文](web.zh.md) / [한국어](web.ko.md) / [日本語](web.ja.md)
+
+## 起動
+
+```bash
+npm install
+npm run dev
+```
+
+ターミナルに表示される Vite URL を開きます。
+
+## インポート元
+
+Web アプリは 4 種類のインポート方法に対応しています。
+
+- 直接 OpenAPI/Swagger JSON または YAML URL。
+- Swagger UI、Knife4j、Redoc ページのクロール。
+- ローカル JSON/YAML ファイルのアップロード。
+- OpenAPI/Swagger ドキュメントを返す curl コマンド。
+- 上流ドキュメントがまだない場合の空白ドキュメント作成。
+
+インポートされたドキュメントは `cache/versions/` に書き込まれ、`cache/latest-import.json` が現在の最新バージョンを指します。
+
+## ゼロからドキュメントを作成
+
+New Document タブで、タイトル、バージョン、任意の説明を入力して空白の OpenAPI 3.0 ドキュメントを作成できます。新しいドキュメントはすぐにアクティブなキャッシュバージョンになります。その後、Add/Edit/Delete API 操作を使って、外部ドキュメントを先にインポートせずに AI アシスタントや開発者が API 契約を段階的に作成できます。
+
+## API の閲覧と確認
+
+検索コントロールを使って、keyword、tag、method、リクエストボディの有無でエンドポイントをフィルタできます。エンドポイントをタブで開くと、次の情報を確認できます。
+
+- リクエストパラメータ。
+- リクエストボディフィールド。
+- レスポンスフィールド。
+- AI 向け Markdown コンテキスト。
+- Raw OpenAPI JSON。
+
+## バージョンと手動 API の管理
+
+バージョン管理機能でキャッシュ済みバージョンを切り替えたり削除したりできます。Add/Edit/Delete API 操作は、上流 OpenAPI ドキュメントが不完全な場合、一時的なローカル契約が必要な場合、またはドキュメント全体をゼロから作成する場合に手動操作を管理するために使います。
+
+手動操作はインポート済みドキュメントと同じバージョンキャッシュに保存されるため、CLI と MCP サーバーからすぐに照会できます。

package/docs/web.ko.md

@@ -0,0 +1,44 @@
+# API Skill Web 앱
+
+[English](web.md) / [中文](web.zh.md) / [한국어](web.ko.md) / [日本語](web.ja.md)
+
+## 시작
+
+```bash
+npm install
+npm run dev
+```
+
+터미널에 출력되는 Vite URL을 엽니다.
+
+## 가져오기 소스
+
+Web 앱은 네 가지 가져오기 방식을 지원합니다.
+
+- 직접 OpenAPI/Swagger JSON 또는 YAML URL.
+- Swagger UI, Knife4j, Redoc 페이지 크롤링.
+- 로컬 JSON/YAML 파일 업로드.
+- OpenAPI/Swagger 문서를 반환하는 curl 명령.
+- 상위 문서가 아직 없을 때 빈 문서 생성.
+
+가져온 문서는 `cache/versions/`에 기록되고, `cache/latest-import.json`은 활성 최신 버전을 가리킵니다.
+
+## 처음부터 문서 만들기
+
+New Document 탭에서 제목, 버전, 선택적 설명을 입력해 빈 OpenAPI 3.0 문서를 만들 수 있습니다. 새 문서는 즉시 활성 캐시 버전이 됩니다. 이후 Add/Edit/Delete API 작업으로 AI 어시스턴트나 개발자가 외부 문서를 먼저 가져오지 않고도 API 계약을 점진적으로 작성할 수 있습니다.
+
+## API 탐색 및 확인
+
+검색 컨트롤로 keyword, tag, method, 요청 본문 존재 여부에 따라 엔드포인트를 필터링할 수 있습니다. 엔드포인트를 탭으로 열면 다음을 확인할 수 있습니다.
+
+- 요청 파라미터.
+- 요청 본문 필드.
+- 응답 필드.
+- AI 친화적인 Markdown 컨텍스트.
+- 원본 OpenAPI JSON.
+
+## 버전 및 수동 API 관리
+
+버전 관리자로 캐시된 버전을 전환하거나 삭제할 수 있습니다. Add/Edit/Delete API 작업은 상위 OpenAPI 문서가 불완전하거나, 임시 로컬 계약이 필요하거나, 전체 문서를 처음부터 작성해야 할 때 수동 작업을 유지하는 데 사용합니다.
+
+수동 작업은 가져온 문서와 같은 버전 캐시에 저장되므로 CLI와 MCP 서버에서 즉시 조회할 수 있습니다.

package/docs/web.md

@@ -0,0 +1,57 @@
+# API Skill Web App
+
+[English](web.md) / [中文](web.zh.md) / [한국어](web.ko.md) / [日本語](web.ja.md)
+
+## Start
+
+After installing from npm:
+
+```bash
+npm install -g apiskill
+apiskill run web
+```
+
+The default cache directory is `cache/` under the current directory. When developing this repository, you can also use:
+
+```bash
+npm install
+npm run dev
+```
+
+Open the local URL printed by the terminal.
+
+## Import Sources
+
+The web app supports four import paths:
+
+- Direct OpenAPI/Swagger JSON or YAML URL.
+- Swagger UI, Knife4j, or Redoc page crawl.
+- Local JSON/YAML file upload.
+- Curl command that returns an OpenAPI/Swagger document.
+- Blank document creation when no upstream documentation exists yet.
+
+Imported documents are written to `cache/versions/`, and `cache/latest-import.json` points to the active latest version.
+
+## Create A Document From Scratch
+
+Use the New Document button to create a blank OpenAPI 3.0 document with a title, version, and optional description. The new document becomes the active cached version immediately. You can then use Add/Edit/Delete API actions to let an AI assistant or developer build the API contract incrementally without importing external documentation first.
+
+## MOCK Server
+
+After API document data exists, click Start MOCK Service. The web backend starts a local MOCK API server from the current document paths, HTTP methods, and response schemas. Calling a matching API returns random JSON data. When no usable API data exists yet, the page prompts you to import, crawl, or create a document first.
+
+## Browse And Inspect APIs
+
+Use the search controls to filter endpoints by keyword, tag, method, or request-body presence. Open endpoints as tabs to inspect:
+
+- Request parameters.
+- Request body fields.
+- Response fields.
+- AI-ready Markdown context.
+- Raw OpenAPI JSON.
+
+## Manage Versions And Manual APIs
+
+Use the version manager to switch or delete cached versions. Use Add/Edit/Delete API actions to maintain local manual operations when the upstream OpenAPI document is incomplete, when you need a temporary local contract, or when the whole document is being authored from zero.
+
+Manual operations are stored in the same versioned cache as imported documents, so the CLI and MCP server can query them immediately.

package/docs/web.zh.md

@@ -0,0 +1,57 @@
+# API Skill Web 端
+
+[English](web.md) / [中文](web.zh.md) / [한국어](web.ko.md) / [日本語](web.ja.md)
+
+## 启动
+
+从 npm 安装后启动：
+
+```bash
+npm install -g apiskill
+apiskill run web
+```
+
+默认缓存目录是当前目录下的 `cache/`。开发本仓库时也可以使用：
+
+```bash
+npm install
+npm run dev
+```
+
+打开终端输出的本地地址。
+
+## 导入来源
+
+Web 端支持四种导入方式：
+
+- 直接导入 OpenAPI/Swagger JSON 或 YAML 地址。
+- 爬取 Swagger UI、Knife4j、Redoc 页面。
+- 上传本地 JSON/YAML 文件。
+- 执行返回 OpenAPI/Swagger 文档的 curl 命令。
+- 没有上游文档时从零创建空白文档。
+
+导入后的文档会写入 `cache/versions/`，`cache/latest-import.json` 指向当前最新版本。
+
+## 从零创建文档
+
+使用“新建文档”按钮可以创建一份空白 OpenAPI 3.0 文档，填写文档名称、版本和可选描述。新文档会立即成为当前缓存版本。之后可以通过 Add/Edit/Delete API 动作，让 AI 助手或开发者逐步补充接口契约，不需要先导入第三方文档。
+
+## MOCK 服务
+
+已有 API 文档数据后，可以点击“启动MOCK服务”。Web 后端会根据当前文档的接口路径、HTTP 方法和响应 schema 启动本地 MOCK API 服务，访问对应接口时返回随机 JSON 数据。没有可用接口数据时，页面会提示先导入、爬取或新建文档。
+
+## 查询和查看接口
+
+可以按关键词、tag、HTTP method、是否有请求体过滤接口。打开接口 tab 后可以查看：
+
+- 请求参数。
+- 请求体字段。
+- 响应字段。
+- 适合直接给 AI 使用的 Markdown 上下文。
+- 原始 OpenAPI JSON。
+
+## 版本和手动接口维护
+
+版本管理器可以切换或删除缓存版本。Add/Edit/Delete API 用于维护本地手动接口，适合上游文档缺字段、接口暂未同步、需要临时本地契约，或整套文档都要从零编写的场景。
+
+手动接口和导入文档使用同一套版本化缓存，因此 CLI 和 MCP 服务可以立即查询到这些变更。

package/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>API Skill Console</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/mcp-config.example.json

@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "apiskill": {
+      "command": "node",
+      "args": ["/Users/dobby/dev/apiskill/scripts/mcp-server.mjs"],
+      "cwd": "/Users/dobby/dev/apiskill",
+      "env": {
+        "APISKILL_ROOT": "/Users/dobby/dev/apiskill",
+        "APISKILL_CACHE_DIR": "/Users/dobby/dev/apiskill/cache"
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "apiskill",
+  "version": "0.1.0",
+  "type": "module",
+  "files": [
+    "src",
+    "scripts",
+    "docs",
+    "skills",
+    "dist",
+    "index.html",
+    "vite.config.ts",
+    "tsconfig.json",
+    "README*.md",
+    "MCP.md",
+    "mcp-config.example.json"
+  ],
+  "bin": {
+    "apiskill": "scripts/apiskill-cli.mjs"
+  },
+  "scripts": {
+    "dev": "vite --host 0.0.0.0 && node scripts/mcp-server.mjs",
+    "build": "tsc -b && vite build",
+    "prepack": "npm run build",
+    "preview": "vite preview --host 0.0.0.0",
+    "mcp": "node scripts/mcp-server.mjs",
+    "cli": "node scripts/apiskill-cli.mjs"
+  },
+  "dependencies": {
+    "@vitejs/plugin-react": "^4.3.4",
+    "commander": "^14.0.3",
+    "lucide-react": "^0.468.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "typescript": "^5.8.3",
+    "vite": "^6.0.7",
+    "yaml": "^2.8.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "@types/react": "^18.3.18",
+    "@types/react-dom": "^18.3.5"
+  }
+}