localsbnb-mcp-server 1.0.3 → 1.0.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
## 这是什么？
|
|
4
4
|
|
|
5
|
-
路客云 AI 助手让您可以在 **Cursor**、**Claude Desktop** 等 AI 工具中，直接用自然语言操作路客云 SPMS（酒店物业管理系统）。
|
|
5
|
+
路客云 AI 助手让您可以在 **Cursor**、**Claude Desktop**、**Claude Code** 等 AI 工具中，直接用自然语言操作路客云 SPMS（酒店物业管理系统）。
|
|
6
6
|
|
|
7
7
|
例如，您可以说：
|
|
8
8
|
|
|
@@ -42,13 +42,13 @@ AI 会帮您调用路客云，并返回结果。
|
|
|
42
42
|
| **Node.js** | ≥ 18.0（运行 `node -v` 检查） |
|
|
43
43
|
| **路客云账号** | 已开通路客云 SPMS |
|
|
44
44
|
| **访问凭证** | 已获取 **APP_SECRET** 与 **APP_ID**（由路客云管理员配置） |
|
|
45
|
-
| **AI 客户端** | 已安装 Cursor 或 Claude
|
|
45
|
+
| **AI 客户端** | 已安装 Cursor、Claude Desktop 或 Claude Code |
|
|
46
46
|
|
|
47
47
|
### 二、获取访问凭证
|
|
48
48
|
|
|
49
49
|
| 凭证 | 说明 | 示例格式 |
|
|
50
50
|
|------|------|----------|
|
|
51
|
-
| **APP_SECRET** | 路客云访问令牌，用于 API 鉴权 |
|
|
51
|
+
| **APP_SECRET** | 路客云访问令牌，用于 API 鉴权 | 由路客云后台提供的 token 字符串 |
|
|
52
52
|
| **APP_ID** | 营地/物业 ID，标识一家店或经营主体 | 数字字符串，如 `12345` |
|
|
53
53
|
|
|
54
54
|
请联系路客云管理员或进入路客云后台获取：https://minsubao.localhome.cn/ → 「设置」→「API 密钥管理」或联系技术支持。
|
|
@@ -78,7 +78,7 @@ AI 会帮您调用路客云，并返回结果。
|
|
|
78
78
|
"command": "npx",
|
|
79
79
|
"args": ["--yes", "localsbnb-mcp-server"],
|
|
80
80
|
"env": {
|
|
81
|
-
"APP_SECRET": "
|
|
81
|
+
"APP_SECRET": "<你的 token>",
|
|
82
82
|
"APP_ID": "<你的 campId>"
|
|
83
83
|
}
|
|
84
84
|
}
|
|
@@ -94,7 +94,7 @@ AI 会帮您调用路客云，并返回结果。
|
|
|
94
94
|
"command": "sh",
|
|
95
95
|
"args": ["/你的实际路径/dist/run.sh"],
|
|
96
96
|
"env": {
|
|
97
|
-
"APP_SECRET": "
|
|
97
|
+
"APP_SECRET": "<你的 token>",
|
|
98
98
|
"APP_ID": "<你的 campId>"
|
|
99
99
|
}
|
|
100
100
|
}
|
|
@@ -115,27 +115,56 @@ AI 会帮您调用路客云，并返回结果。
|
|
|
115
115
|
2. 添加与上文相同的 `mcpServers` 配置块
|
|
116
116
|
3. 保存并重启 Claude Desktop
|
|
117
117
|
|
|
118
|
-
|
|
118
|
+
#### 配置 Claude Code
|
|
119
119
|
|
|
120
|
-
|
|
120
|
+
Claude Code 是终端版 Claude，通过 `claude mcp add` 添加 MCP 服务。包已发布到 npm，可直接用 npx 运行：
|
|
121
|
+
|
|
122
|
+
**方式 1：命令行添加（推荐）**
|
|
123
|
+
|
|
124
|
+
在终端执行（**替换凭证为你的实际值**）。注意：**服务器名必须写在 `-e` 参数之前**：
|
|
125
|
+
|
|
126
|
+
```bash
|
|
127
|
+
claude mcp add LocalsBnbMCP --scope user \
|
|
128
|
+
-e APP_SECRET="<你的 token>" \
|
|
129
|
+
-e APP_ID="<你的 campId>" \
|
|
130
|
+
-- npx -y localsbnb-mcp-server
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
- 使用 `-e KEY=value` 传递环境变量（勿用 `--env`）
|
|
134
|
+
- `--scope user`：所有项目可用；改为 `--scope local` 仅当前项目
|
|
135
|
+
|
|
136
|
+
**方式 2：手动编辑配置文件**
|
|
137
|
+
|
|
138
|
+
在项目根目录创建或编辑 `.mcp.json`：
|
|
121
139
|
|
|
122
140
|
```json
|
|
123
|
-
|
|
141
|
+
{
|
|
142
|
+
"mcpServers": {
|
|
143
|
+
"LocalsBnb MCP": {
|
|
144
|
+
"command": "npx",
|
|
145
|
+
"args": ["-y", "localsbnb-mcp-server"],
|
|
146
|
+
"env": {
|
|
147
|
+
"APP_SECRET": "<你的 token>",
|
|
148
|
+
"APP_ID": "<你的 campId>"
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
}
|
|
152
|
+
}
|
|
124
153
|
```
|
|
125
154
|
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
| `develop` / `development` | 开发：`hudson-dev.localhome.cn` |
|
|
155
|
+
也可将 MCP 配置写入用户级 `~/.claude.json` 的 `mcpServers` 字段。
|
|
156
|
+
|
|
157
|
+
**验证**：在 Claude Code 中输入 `/mcp` 查看是否已加载，或直接说「查询今天的房态」测试。
|
|
130
158
|
|
|
131
|
-
###
|
|
159
|
+
### 五、验证配置
|
|
132
160
|
|
|
133
161
|
- **Cursor**：`Cmd/Ctrl + Shift + P` → 输入「MCP」，查看是否出现 `LocalsBnb MCP` 相关工具
|
|
134
162
|
- **Claude Desktop**：新开对话，输入 `@LocalsBnb MCP` 或「查询今天的房态」
|
|
163
|
+
- **Claude Code**：输入 `/mcp` 查看工具，或直接说「查询今天的房态」
|
|
135
164
|
|
|
136
165
|
若能返回房态、订单等数据，说明配置成功。
|
|
137
166
|
|
|
138
|
-
###
|
|
167
|
+
### 六、可用工具一览
|
|
139
168
|
|
|
140
169
|
| 工具名 | 说明 | 示例指令 |
|
|
141
170
|
|--------|------|----------|
|
|
@@ -146,24 +175,21 @@ AI 会帮您调用路客云，并返回结果。
|
|
|
146
175
|
| `query_room_prices` | 近期房价 | 「本周房价是多少？」 |
|
|
147
176
|
| `query_operational_data_v2` | 运营数据 | 「今天的经营情况如何？」 |
|
|
148
177
|
|
|
149
|
-
###
|
|
178
|
+
### 七、配置项速查
|
|
150
179
|
|
|
151
180
|
| 环境变量 | 必填 | 说明 |
|
|
152
181
|
|----------|------|------|
|
|
153
182
|
| `APP_SECRET` | 是 | 路客云访问令牌 |
|
|
154
183
|
| `APP_ID` | 是 | 营地 ID |
|
|
155
|
-
| `NODE_ENV` | 否 | `production` / `develop`，切换 API 环境 |
|
|
156
184
|
| `LOG_LEVEL` | 否 | `info` / `debug`，调试用 |
|
|
157
|
-
| `LUKEYUN_API_BASE_URL` | 否 | 显式指定 API 地址 |
|
|
158
185
|
|
|
159
|
-
###
|
|
186
|
+
### 八、常见问题
|
|
160
187
|
|
|
161
188
|
| 问题 | 解决 |
|
|
162
189
|
|------|------|
|
|
163
190
|
| 连接失败 / 无权限 | 确认 `APP_SECRET`、`APP_ID` 正确，且已开通 MCP/API 权限 |
|
|
164
191
|
| 找不到工具 | 检查 JSON 格式、路径是否正确，完全重启客户端 |
|
|
165
192
|
| ERR_REQUIRE_ESM | 使用 `dist/run.sh` 或 `dist/run.cjs` |
|
|
166
|
-
| 想用开发环境 | 在 `env` 中增加 `"NODE_ENV": "develop"` |
|
|
167
193
|
| npx 缓存异常（Windows） | 执行 `npx clear-npx-cache` 后重试 |
|
|
168
194
|
|
|
169
195
|
---
|
|
@@ -190,12 +216,9 @@ AI 会帮您调用路客云，并返回结果。
|
|
|
190
216
|
|
|
191
217
|
## 需要帮助？
|
|
192
218
|
|
|
193
|
-
-
|
|
194
|
-
- **用户配置详解**：`05-用户配置指南.md`
|
|
195
|
-
- **部署说明**：`README-部署说明.md`
|
|
196
|
-
- **技术支持**：support@lukeyun.com
|
|
219
|
+
- **技术支持**：https://minsubao.localhome.cn/
|
|
197
220
|
|
|
198
221
|
---
|
|
199
222
|
|
|
200
223
|
**文档版本**：v1.0
|
|
201
|
-
**最后更新**：
|
|
224
|
+
**最后更新**：2026年
|
package/dist/package.json
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"queryTodayRoomStatus.d.ts","sourceRoot":"","sources":["../../../src/tools/rooms/queryTodayRoomStatus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AA2FtD,eAAO,MAAM,2BAA2B,EAAE,
|
|
1
|
+
{"version":3,"file":"queryTodayRoomStatus.d.ts","sourceRoot":"","sources":["../../../src/tools/rooms/queryTodayRoomStatus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AA2FtD,eAAO,MAAM,2BAA2B,EAAE,WA0EzC,CAAC"}
|
|
@@ -12,10 +12,11 @@ export const queryTodayRoomStatusHandler = async (args, context) => {
|
|
|
12
12
|
permissionChecker.checkPermission('query_today_room_status', ['rooms:read']);
|
|
13
13
|
// 参数验证
|
|
14
14
|
const validatedParams = queryTodayRoomStatusSchema.parse(args);
|
|
15
|
-
// 如果没有提供date
|
|
16
|
-
const date = validatedParams.date || new Date().
|
|
17
|
-
//
|
|
18
|
-
|
|
15
|
+
// 如果没有提供date，使用当天日期（基于中国时区 Asia/Shanghai，确保与路客云 API 一致）
|
|
16
|
+
const date = validatedParams.date || new Date().toLocaleDateString('sv', { timeZone: 'Asia/Shanghai' });
|
|
17
|
+
// 将日期转换为时间戳：必须是一天的开始（中国时区 UTC+8 的 00:00:00）
|
|
18
|
+
// new Date('YYYY-MM-DD') 会被解析为 UTC 午夜，在中国是 08:00，不符合 API 要求
|
|
19
|
+
const dateTimestamp = new Date(`${date}T00:00:00+08:00`).getTime();
|
|
19
20
|
logger.info('Querying today room status', { date });
|
|
20
21
|
// 从context中获取campId
|
|
21
22
|
const campId = context.campId;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"queryTodayRoomStatus.js","sourceRoot":"","sources":["../../../src/tools/rooms/queryTodayRoomStatus.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAC/E,OAAO,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,aAAa;AACb,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,qBAAqB,EAAE,oBAAoB,CAAC,CAAC,QAAQ,EAAE;CAC/E,CAAC,CAAC;AAmFH,MAAM,CAAC,MAAM,2BAA2B,GAAgB,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE;IAC9E,IAAI,CAAC;QACH,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,iBAAiB,EAAE,GAAG,OAAO,CAAC;QAEzD,OAAO;QACP,iBAAiB,CAAC,eAAe,CAAC,yBAAyB,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC;QAE7E,OAAO;QACP,MAAM,eAAe,GAAG,0BAA0B,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAE/D,
|
|
1
|
+
{"version":3,"file":"queryTodayRoomStatus.js","sourceRoot":"","sources":["../../../src/tools/rooms/queryTodayRoomStatus.ts"],"names":[],"mappings":"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"}
|
package/mcp.sample.json
CHANGED