localsbnb-mcp-server 1.0.1 → 1.0.2

package/README.md

@@ -2,7 +2,7 @@
 
 ## 这是什么？
 
-路客云 AI 助手让您可以在 **Cursor**、**Claude Desktop**、**ChatGPT** 等 AI 工具中，直接用自然语言操作路客云 SPMS（酒店物业管理系统）。
+路客云 AI 助手让您可以在 **Cursor**、**Claude Desktop** 等 AI 工具中，直接用自然语言操作路客云 SPMS（酒店物业管理系统）。
 
 例如，您可以说：
 
@@ -15,11 +15,8 @@ AI 会帮您调用路客云，并返回结果。
 ## 能做什么？
 
 ### 订单管理
-- 查询订单列表
-- 查看订单详情
-- 创建订单
+- 查询订单列表、订单详情
 - 办理入住 / 退房
-- 取消订单
 
 ### 房态管理
 - 查询房态
@@ -27,41 +24,149 @@ AI 会帮您调用路客云，并返回结果。
 - 批量更新价格
 
 ### 数据分析
-- 查询经营数据
-- 查询财务数据
-- 收益分析
-- 入住率相关数据
+- 查询经营数据、财务数据
+- 收益分析、入住率相关数据
 
 ### 渠道管理
-- 查看渠道列表
-- 查看渠道详情
+- 查看渠道列表、渠道详情
 - 关联或解绑渠道
 
-## 如何开始使用？
+---
+
+## 用户初始化与快速入门
+
+### 一、前置条件
+
+| 项目 | 要求 |
+|------|------|
+| **Node.js** | ≥ 18.0（运行 `node -v` 检查） |
+| **路客云账号** | 已开通路客云 SPMS |
+| **访问凭证** | 已获取 **APP_SECRET** 与 **APP_ID**（由路客云管理员配置） |
+| **AI 客户端** | 已安装 Cursor 或 Claude Desktop |
+
+### 二、获取访问凭证
+
+| 凭证 | 说明 | 示例格式 |
+|------|------|----------|
+| **APP_SECRET** | 路客云访问令牌，用于 API 鉴权 | `Bearer eyJxxx...` 或 `ut_xxx` |
+| **APP_ID** | 营地/物业 ID，标识一家店或经营主体 | 数字字符串，如 `12345` |
+
+请联系路客云管理员或进入路客云后台获取：https://pms.lukeyun.com → 「设置」→「API 密钥管理」或联系技术支持。
 
-### 第一步：获取配置信息
+> ⚠️ **安全提醒**：请勿将凭证分享给他人或提交到公开代码仓库。
 
-在路客云 SPMS 中获取：
-- **访问令牌**（Access Token）
-- **营地 ID**（Camp ID）
+### 三、选择安装方式
 
-### 第二步：配置 AI 工具
+**方式 A：npx 直接运行（推荐，免安装）** — 无需下载，首次运行自动拉取。
 
-根据您使用的 AI 工具（Cursor、Claude Desktop、ChatGPT 等），在对应应用中完成 MCP 或 Skill 的配置，填入访问令牌和营地 ID。
+**方式 B：解压包安装** — 从发布页下载 `lukeyun-pms-mcp-vX.X.X.zip`，解压后在目录下执行 `npm install --production`。
 
-### 第三步：开始使用
+**方式 C：从源码构建** — 克隆项目后执行 `npm install` 和 `npm run build`，配置时指向 `dist/run.sh` 或 `dist/run.cjs`。
 
-在 Cursor 中，可以这样使用：
+### 四、配置 MCP 客户端
 
+#### 配置 Cursor
+
+1. 打开 Cursor → `Cmd/Ctrl + ,` 打开设置 → 搜索「MCP」→ 找到 **MCP Servers** → 编辑 `~/.cursor/mcp.json`
+2. 添加配置（**替换凭证为你的实际值**）：
+
+**npx 方式（推荐）**
+```json
+{
+  "mcpServers": {
+    "LocalsBnb MCP": {
+      "command": "npx",
+      "args": ["--yes", "localsbnb-mcp-server"],
+      "env": {
+        "APP_SECRET": "Bearer <你的 token>",
+        "APP_ID": "<你的 campId>"
+      }
+    }
+  }
+}
 ```
-@lukeyun-pms 查询今天的房态信息
+
+**解压包 / 源码构建方式**
+```json
+{
+  "mcpServers": {
+    "LocalsBnb MCP": {
+      "command": "sh",
+      "args": ["/你的实际路径/dist/run.sh"],
+      "env": {
+        "APP_SECRET": "Bearer <你的 token>",
+        "APP_ID": "<你的 campId>"
+      }
+    }
+  }
+}
 ```
 
-或直接描述您的需求，例如：
+> 若 `run.sh` 报错，可改用：`"command": "node"`，`"args": ["/你的路径/dist/run.cjs"]`
 
+3. 完全重启 Cursor
+
+#### 配置 Claude Desktop
+
+1. 找到配置文件：
+   - macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`
+   - Windows：`%APPDATA%\Claude\claude_desktop_config.json`
+   - Linux：`~/.config/Claude/claude_desktop_config.json`
+2. 添加与上文相同的 `mcpServers` 配置块
+3. 保存并重启 Claude Desktop
+
+### 五、环境选择（开发 / 生产）
+
+默认使用**生产环境**。如需**开发环境**，在 `env` 中增加：
+
+```json
+"NODE_ENV": "develop"
 ```
-帮我查一下今天有哪些订单需要办理入住
-```
+
+| NODE_ENV | API 环境 |
+|----------|----------|
+| 不设置 / `production` | 生产：`hudson-prod.localhome.cn` |
+| `develop` / `development` | 开发：`hudson-dev.localhome.cn` |
+
+### 六、验证配置
+
+- **Cursor**：`Cmd/Ctrl + Shift + P` → 输入「MCP」，查看是否出现 `LocalsBnb MCP` 相关工具
+- **Claude Desktop**：新开对话，输入 `@LocalsBnb MCP` 或「查询今天的房态」
+
+若能返回房态、订单等数据，说明配置成功。
+
+### 七、可用工具一览
+
+| 工具名 | 说明 | 示例指令 |
+|--------|------|----------|
+| `query_today_orders` | 今日订单（预抵/在住/预离） | 「今天有哪些订单？」 |
+| `get_order_details_v2` | 订单详情 | 「查一下订单 12345 的详情」 |
+| `query_today_room_status` | 今日房态 | 「今天房态怎么样？」 |
+| `query_room_status_new` | 房型日历价（新接口） | 「查一下未来 7 天的房态和价格」 |
+| `query_room_prices` | 近期房价 | 「本周房价是多少？」 |
+| `query_operational_data_v2` | 运营数据 | 「今天的经营情况如何？」 |
+
+### 八、配置项速查
+
+| 环境变量 | 必填 | 说明 |
+|----------|------|------|
+| `APP_SECRET` | 是 | 路客云访问令牌 |
+| `APP_ID` | 是 | 营地 ID |
+| `NODE_ENV` | 否 | `production` / `develop`，切换 API 环境 |
+| `LOG_LEVEL` | 否 | `info` / `debug`，调试用 |
+| `LUKEYUN_API_BASE_URL` | 否 | 显式指定 API 地址 |
+
+### 九、常见问题
+
+| 问题 | 解决 |
+|------|------|
+| 连接失败 / 无权限 | 确认 `APP_SECRET`、`APP_ID` 正确，且已开通 MCP/API 权限 |
+| 找不到工具 | 检查 JSON 格式、路径是否正确，完全重启客户端 |
+| ERR_REQUIRE_ESM | 使用 `dist/run.sh` 或 `dist/run.cjs` |
+| 想用开发环境 | 在 `env` 中增加 `"NODE_ENV": "develop"` |
+| npx 缓存异常（Windows） | 执行 `npx clear-npx-cache` 后重试 |
+
+---
 
 ## 使用场景示例
 
@@ -85,9 +190,12 @@ AI 会帮您调用路客云，并返回结果。
 
 ## 需要帮助？
 
+- **工具说明**：`03-工具定义规范.md`
+- **用户配置详解**：`05-用户配置指南.md`
+- **部署说明**：`README-部署说明.md`
 - **技术支持**：support@lukeyun.com
 
 ---
 
 **文档版本**：v1.0  
-**最后更新**：2024年
+**最后更新**：2025年

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "localsbnb-mcp-server",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "LocalsBnb MCP Server",
   "main": "dist/index.js",
   "type": "module",
@@ -53,9 +53,6 @@
     "tsx": "^4.6.0",
     "typescript": "^5.3.2"
   },
-  "overrides": {
-    "readable-stream": "3.6.2"
-  },
   "engines": {
     "node": ">=18.0.0"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "localsbnb-mcp-server",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "LocalsBnb MCP Server",
   "main": "dist/index.js",
   "type": "module",
@@ -53,9 +53,6 @@
     "tsx": "^4.6.0",
     "typescript": "^5.3.2"
   },
-  "overrides": {
-    "readable-stream": "3.6.2"
-  },
   "engines": {
     "node": ">=18.0.0"
   },