heyyumi 0.1.2 → 0.1.3
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 +8 -15
- package/package.json +1 -1
- package/src/commands.js +47 -5
package/README.md
CHANGED
|
@@ -59,7 +59,7 @@ $ npx -y heyyumi search bibimbap --region Myeongdong --page-size 3 --fields core
|
|
|
59
59
|
"distanceM": 241,
|
|
60
60
|
"placeUrl": "https://heyyumi.ai/en/places/8392850",
|
|
61
61
|
"matchReason": "name",
|
|
62
|
-
"yumiBooking": { "canRequest": true
|
|
62
|
+
"yumiBooking": { "canRequest": true }
|
|
63
63
|
},
|
|
64
64
|
{
|
|
65
65
|
"name": "방이옥 종로점",
|
|
@@ -109,9 +109,10 @@ npx -y heyyumi place <placeId> --fields all # menu, hours, attributes,
|
|
|
109
109
|
| `photos ID` | The owner's photo URLs. |
|
|
110
110
|
| `regions NAME` · `categories` · `stats` | Region lookup, category list, coverage numbers. |
|
|
111
111
|
| `reserve ID --time --party --phone [--name --email --note --lang]` | Send a table request. Times without an offset are Korea time. `--email` is required for non-Korean phone numbers. |
|
|
112
|
-
| `wait RESERVATION_ID [--timeout 110]` | Wait for the venue's answer
|
|
112
|
+
| `wait RESERVATION_ID [--timeout 110]` | Wait for the venue's answer. Re-run if `cli.settled` is false. |
|
|
113
113
|
| `reservation RESERVATION_ID` | Check a request once. |
|
|
114
114
|
| `live ID --kind item\|wait\|seats --topic TEXT` · `live-wait QUERY_ID` | Ask the venue right now (stock, wait time, seats). |
|
|
115
|
+
| `guide [search\|place\|reserve\|live]` | Rules for agents, served by HeyYumi and always current. |
|
|
115
116
|
| `tools [TOOL]` · `call TOOL --json '{...}'` | Raw access to every HeyYumi MCP tool. |
|
|
116
117
|
|
|
117
118
|
Flags may use dashes or underscores (`--page-size` = `--page_size`). Bare flags mean `true`.
|
|
@@ -119,30 +120,22 @@ Flags may use dashes or underscores (`--page-size` = `--page_size`). Bare flags
|
|
|
119
120
|
## Output contract
|
|
120
121
|
|
|
121
122
|
- stdout is always one JSON document: compact when piped, indented on a terminal or with `--pretty`. Progress and the sign-in URL go to stderr.
|
|
122
|
-
- Errors: `{"ok": false, "error": {"code", "message", "next"?, "details"?}}`. Server codes are passed through
|
|
123
|
+
- Errors: `{"ok": false, "error": {"code", "message", "next"?, "details"?}}`. Server error codes and messages are passed through.
|
|
123
124
|
- Exit codes: `0` ok · `1` server/tool error · `2` bad usage · `3` not signed in (run `npx -y heyyumi login`).
|
|
124
125
|
- Unknown flags fail with `unknown_option` and a "did you mean" hint instead of being dropped, so a typo never turns into a silently wider search or a nameless booking. Search flags are checked against the live tool schema (cached for an hour), so new server filters work without a CLI update.
|
|
125
126
|
- When a follow-up command is needed, the output carries `cli.next`, e.g. `npx -y heyyumi wait <id>`.
|
|
126
127
|
|
|
127
|
-
## Rules for agents
|
|
128
|
-
|
|
129
|
-
- Only send `reserve` for venues whose result shows `yumiBooking.canRequest: true`. Confirm time, party size, name and phone with the user before sending; it reaches a real venue. Venues with `requestHours` review requests in those hours (Korea time). A request sent outside them comes back with `cli.deferred: true` and `cli.reviewStartsAt`: it is held, and the guest gets the answer by text or email, so don't wait for it now.
|
|
130
|
-
- A request starts as `pending`. Say it is booked only after `wait` returns `status: "confirmed"`. `cancelled` means the venue declined (relay `declineReason` if present); `expired` means no answer in time.
|
|
131
|
-
- `open_at` means the venue is open at that time, not that a table is free. Only a reservation answer says that.
|
|
132
|
-
- There are no star ratings (`rating` is always null). Do not invent one, and do not attribute review counts to any map platform.
|
|
133
|
-
- `associated_with` results are reported visits with a news link, not endorsements. Say "reportedly visited by".
|
|
134
|
-
- Link venue names to their `placeUrl`.
|
|
135
|
-
|
|
136
128
|
## Use it as an agent skill
|
|
137
129
|
|
|
138
|
-
Any agent or skill system that can run a shell command can wrap this CLI:
|
|
130
|
+
Any agent or skill system that can run a shell command can wrap this CLI. The usage rules come from the HeyYumi server, so a skill never goes out of date:
|
|
139
131
|
|
|
140
132
|
```bash
|
|
141
133
|
npx -y heyyumi login --client-name "My Agent" # returns at once if already signed in
|
|
142
|
-
npx -y heyyumi
|
|
134
|
+
npx -y heyyumi guide # rules for agents, read once per task
|
|
135
|
+
npx -y heyyumi guide reserve # before sending a table request
|
|
143
136
|
```
|
|
144
137
|
|
|
145
|
-
A ready-to-copy skill in the common `SKILL.md` format is in [`examples/agent-skill`](https://github.com/hmp-dev/heyyumi-cli/blob/main/examples/agent-skill/SKILL.md). For Claude Code, copy it to `~/.claude/skills/heyyumi-restaurant/SKILL.md`; for other agents,
|
|
138
|
+
A ready-to-copy skill in the common `SKILL.md` format is in [`examples/agent-skill`](https://github.com/hmp-dev/heyyumi-cli/blob/main/examples/agent-skill/SKILL.md). For Claude Code, copy it to `~/.claude/skills/heyyumi-restaurant/SKILL.md`; for other agents, point their skill at `npx -y heyyumi guide`. Treat `reserve` and `live` as actions that need the user's approval first, because they reach a real venue.
|
|
146
139
|
|
|
147
140
|
Not in a terminal? The same tools are available as an MCP server for ChatGPT, Claude, Perplexity and Cursor: `https://mcp.heyyumi.ai/mcp` ([setup guide](https://heyyumi.ai/mcp)). Building a product? See the [REST API](https://heyyumi.ai/developers).
|
|
148
141
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "heyyumi",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.3",
|
|
4
4
|
"description": "Your AI finds and books real Korean restaurants, no Korean needed. 546,000+ verified venues; search, details and table requests as JSON for any agent.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"bin": {
|
package/src/commands.js
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
|
|
3
3
|
const { flagsToToolArgs } = require("./args");
|
|
4
|
-
const { callTool, listTools } = require("./mcp");
|
|
4
|
+
const { callTool, listTools, rpc } = require("./mcp");
|
|
5
5
|
const { login } = require("./oauth");
|
|
6
6
|
const { readCredentials, removeCredentials } = require("./credentials");
|
|
7
7
|
const { normalizeReservationTime } = require("./time");
|
|
@@ -22,8 +22,7 @@ function pick(obj, key) {
|
|
|
22
22
|
return undefined;
|
|
23
23
|
}
|
|
24
24
|
|
|
25
|
-
// A request
|
|
26
|
-
// now would only time out; the guest gets the answer by text or email.
|
|
25
|
+
// A held request is only reviewed from reviewStartsAt, so waiting now would just time out.
|
|
27
26
|
function withReserveNext(data) {
|
|
28
27
|
const id = pick(data, "reservationId") ?? pick(data, "id");
|
|
29
28
|
if (!id || !data || typeof data !== "object" || Array.isArray(data) || pick(data, "settled") === true) return data;
|
|
@@ -35,7 +34,7 @@ function withReserveNext(data) {
|
|
|
35
34
|
deferred: true,
|
|
36
35
|
reviewStartsAt,
|
|
37
36
|
next: `npx -y heyyumi reservation ${id}`,
|
|
38
|
-
note: "
|
|
37
|
+
note: "The request is held for later. Pass on yumiNextStep and don't wait now.",
|
|
39
38
|
},
|
|
40
39
|
};
|
|
41
40
|
}
|
|
@@ -81,6 +80,21 @@ function timeoutFlag(flags, fallback) {
|
|
|
81
80
|
return n;
|
|
82
81
|
}
|
|
83
82
|
|
|
83
|
+
// The server's rules name MCP tools; agents run these CLI commands instead.
|
|
84
|
+
const CLI_FOR_TOOL = {
|
|
85
|
+
search_places: "npx -y heyyumi search",
|
|
86
|
+
nearby_places: "npx -y heyyumi nearby",
|
|
87
|
+
get_place: "npx -y heyyumi place",
|
|
88
|
+
show_place_photos: "npx -y heyyumi photos",
|
|
89
|
+
resolve_regions: "npx -y heyyumi regions",
|
|
90
|
+
request_reservation: "npx -y heyyumi reserve",
|
|
91
|
+
wait_for_reservation: "npx -y heyyumi wait",
|
|
92
|
+
get_reservation: "npx -y heyyumi reservation",
|
|
93
|
+
request_live_status: "npx -y heyyumi live",
|
|
94
|
+
wait_for_live_status: "npx -y heyyumi live-wait",
|
|
95
|
+
};
|
|
96
|
+
const GUIDE_TOPICS = { search: "search_places", place: "get_place", reserve: "request_reservation", live: "request_live_status" };
|
|
97
|
+
|
|
84
98
|
// Commands that build tool arguments by hand. Anything else they get is a typo, and a dropped
|
|
85
99
|
// `--nme` would book under no name, so reject it. Commands not listed forward flags to the tool,
|
|
86
100
|
// where validateArgs checks them against the live schema.
|
|
@@ -97,6 +111,7 @@ const OWN_FLAGS = {
|
|
|
97
111
|
live: ["kind", "topic", "question"],
|
|
98
112
|
"live-wait": ["timeout"],
|
|
99
113
|
tools: [],
|
|
114
|
+
guide: [],
|
|
100
115
|
version: [],
|
|
101
116
|
};
|
|
102
117
|
const OUTPUT_FLAGS = ["pretty", "compact", "help"];
|
|
@@ -270,6 +285,29 @@ const commands = {
|
|
|
270
285
|
return tool(name, args);
|
|
271
286
|
},
|
|
272
287
|
|
|
288
|
+
async guide({ positionals }) {
|
|
289
|
+
const topic = positionals[0];
|
|
290
|
+
if (topic !== undefined) {
|
|
291
|
+
const toolName = GUIDE_TOPICS[topic];
|
|
292
|
+
if (!toolName) throw usageError(`Unknown guide topic "${topic}". Topics: ${Object.keys(GUIDE_TOPICS).join(", ")}`);
|
|
293
|
+
const t = (await listTools()).find((x) => x.name === toolName);
|
|
294
|
+
if (!t) throw new CliError("tool_not_found", `The server has no ${toolName} tool right now.`);
|
|
295
|
+
return { ok: true, topic, command: CLI_FOR_TOOL[toolName], rules: t.description };
|
|
296
|
+
}
|
|
297
|
+
const init = await rpc("initialize", {
|
|
298
|
+
protocolVersion: "2025-06-18",
|
|
299
|
+
capabilities: {},
|
|
300
|
+
clientInfo: { name: "heyyumi-cli", version },
|
|
301
|
+
});
|
|
302
|
+
return {
|
|
303
|
+
ok: true,
|
|
304
|
+
instructions: init?.instructions || "",
|
|
305
|
+
commands: CLI_FOR_TOOL,
|
|
306
|
+
topics: Object.fromEntries(Object.keys(GUIDE_TOPICS).map((k) => [k, `npx -y heyyumi guide ${k}`])),
|
|
307
|
+
note: "These rules come from the HeyYumi server and stay current. They name MCP tools; run the matching command from `commands` (reserve takes --time --party --phone --name --email --note --lang). Read `guide reserve` before sending a table request and `guide live` before asking a venue.",
|
|
308
|
+
};
|
|
309
|
+
},
|
|
310
|
+
|
|
273
311
|
async version() {
|
|
274
312
|
return { ok: true, version };
|
|
275
313
|
},
|
|
@@ -281,6 +319,10 @@ Sign in (once per machine; opens Google sign-in, finishes on its own):
|
|
|
281
319
|
heyyumi login [--no-browser] [--client-name NAME] [--timeout 300] [--force]
|
|
282
320
|
heyyumi status | logout
|
|
283
321
|
|
|
322
|
+
Rules for agents (from the server, always current):
|
|
323
|
+
heyyumi guide read once per task
|
|
324
|
+
heyyumi guide search|place|reserve|live rules for one step
|
|
325
|
+
|
|
284
326
|
Search & details:
|
|
285
327
|
heyyumi search [KEYWORD] --region 을지로 [--subtype korean_bbq] [--open_at "2026-10-25 19:00"] [--parking] ...
|
|
286
328
|
Any search_places filter works as a flag (see: heyyumi tools search_places). 10 results unless --page-size.
|
|
@@ -290,7 +332,7 @@ Search & details:
|
|
|
290
332
|
heyyumi photos PLACE_ID
|
|
291
333
|
heyyumi regions NAME | categories | stats
|
|
292
334
|
|
|
293
|
-
Table requests (
|
|
335
|
+
Table requests (read "heyyumi guide reserve" first; ask the user before sending):
|
|
294
336
|
heyyumi reserve PLACE_ID --time "2026-10-25 19:00" --party 2 --phone 010-1234-5678 [--name NAME]
|
|
295
337
|
[--email EMAIL (required for non-Korean phones)] [--note TEXT] [--lang en]
|
|
296
338
|
heyyumi wait RESERVATION_ID [--timeout 110] waits until confirmed / cancelled / expired (venue has 5 min)
|