openapi-docs-mcp 0.1.0 → 0.1.2

package/README.md

@@ -17,41 +17,84 @@
 - Node.js 20 或更高版本
 - 开发时建议使用 pnpm 11 或更高版本
 
-## 安装与构建
+## 快速开始
+
+包已经发布到 npm：[openapi-docs-mcp](https://www.npmjs.com/package/openapi-docs-mcp)。
+
+### 使用 npx（推荐）
+
+不需要安装，直接下载并运行指定版本：
 
 ```bash
-pnpm install
-pnpm build
+npx -y openapi-docs-mcp@0.1.2 \
+  --source https://api.example.com/v3/api-docs \
+  --timeout 30000
+```
+
+建议在 MCP 配置中固定版本，例如 `openapi-docs-mcp@0.1.2`，避免新版本自动升级后改变行为。
+
+如果希望始终使用最新版本：
+
+```bash
+npx -y openapi-docs-mcp@latest \
+  --source https://api.example.com/v3/api-docs
 ```
 
-构建产物位于 `dist/`。
+### 使用 pnpm dlx
 
-## 启动服务
+```bash
+pnpm dlx openapi-docs-mcp@0.1.2 \
+  --source https://api.example.com/v3/api-docs \
+  --timeout 30000
+```
+
+### 全局安装
+
+```bash
+npm install --global openapi-docs-mcp@0.1.2
+```
+
+安装后可以直接执行：
+
+```bash
+openapi-docs-mcp \
+  --source https://api.example.com/v3/api-docs \
+  --timeout 30000
+```
+
+升级全局版本：
+
+```bash
+npm install --global openapi-docs-mcp@latest
+```
+
+## 启动参数示例
 
 ### 加载本地文档
 
 支持 OpenAPI/Swagger JSON 和 YAML 文件：
 
 ```bash
-node dist/cli.js --source ./openapi.json
+npx -y openapi-docs-mcp@0.1.2 --source ./openapi.json
 ```
 
 也可以直接使用位置参数：
 
 ```bash
-node dist/cli.js ./openapi.yaml
+npx -y openapi-docs-mcp@0.1.2 ./openapi.yaml
 ```
 
 ### 加载远程文档
 
 ```bash
-node dist/cli.js --source https://api.example.com/v3/api-docs
+npx -y openapi-docs-mcp@0.1.2 \
+  --source https://api.example.com/v3/api-docs
 ```
 
 默认远程加载超时时间为 10 秒，可以通过 `--timeout` 修改：
 
 ```bash
-node dist/cli.js \
+npx -y openapi-docs-mcp@0.1.2 \
   --source https://api.example.com/v3/api-docs \
   --timeout 20000
 ```
@@ -61,7 +104,7 @@ node dist/cli.js \
 可以重复使用 `--header`，格式为 `NAME=VALUE`：
 
 ```bash
-node dist/cli.js \
+npx -y openapi-docs-mcp@0.1.2 \
   --source https://api.example.com/v3/api-docs \
   --header Authorization="Bearer token" \
   --header X-Tenant-Id=tenant-1
@@ -84,14 +127,77 @@ node dist/cli.js \
 
 ## MCP Client 配置
 
-构建完成后，可以在任意支持 stdio MCP Server 的 Client 中添加配置。
-
-路径建议使用绝对路径：
+可以在任意支持 stdio MCP Server 的 Client 中通过 `npx` 启动，无需克隆或构建本项目：
 
 ```json
 {
   "mcpServers": {
     "project-api-docs": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "openapi-docs-mcp@0.1.2",
+        "--source",
+        "https://api.example.com/v3/api-docs",
+        "--timeout",
+        "30000"
+      ]
+    }
+  }
+}
+```
+
+同一个 npm 包可以使用不同 OpenAPI 文档启动多个实例，因此不同项目之间不会冲突。
+
+### 同时配置多个实例
+
+每个实例使用不同的 MCP Server 名称和 `--source`：
+
+```json
+{
+  "mcpServers": {
+    "safety-api-docs": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "openapi-docs-mcp@0.1.2",
+        "--source",
+        "https://safety.example.com/v3/api-docs",
+        "--timeout",
+        "30000"
+      ]
+    },
+    "mall-api-docs": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "openapi-docs-mcp@0.1.2",
+        "--source",
+        "https://mall.example.com/v3/api-docs",
+        "--timeout",
+        "30000"
+      ]
+    }
+  }
+}
+```
+
+### 使用本地源码构建
+
+参与开发时才需要克隆源码并构建：
+
+```bash
+pnpm install
+pnpm build
+node dist/cli.js --source ./openapi.json
+```
+
+本地 MCP 配置需要使用 `dist/cli.js` 的绝对路径：
+
+```json
+{
+  "mcpServers": {
+    "local-api-docs": {
       "command": "node",
       "args": [
         "C:/absolute/path/openapi-docs-mcp/dist/cli.js",
@@ -103,8 +209,6 @@ node dist/cli.js \
 }
 ```
 
-同一个 npm 包可以使用不同 OpenAPI 文档启动多个实例，因此不同项目之间不会冲突。
-
 ## MCP 工具
 
 ### `search_api`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openapi-docs-mcp",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "A vendor-neutral MCP server for searching and understanding OpenAPI documents.",
   "type": "module",
   "bin": {