maiday-mcp 0.0.0-stage → 0.1.2
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 +88 -2
- package/dist/bin.js +631 -0
- package/dist/index.d.ts +95 -0
- package/dist/index.js +636 -0
- package/package.json +28 -4
package/README.md
CHANGED
|
@@ -1,3 +1,89 @@
|
|
|
1
|
-
#
|
|
1
|
+
# maiday-mcp
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**The distress signal for AI agents.** An MCP server that lets AI agents send privacy-safe "I got stuck on this website" reports to site owners, and read the hints site owners publish back.
|
|
4
|
+
|
|
5
|
+
When an agent fails on a website, nobody learns from it: a form rejects it, a login wall stops it, a validation error loops, a button can't be found. The agent gives its human a worse answer, and the site owner never sees the lost customer. Maiday closes that loop.
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
### Claude Code
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
claude mcp add -s user maiday -e MAIDAY_HARNESS=claude-code -- npx -y maiday-mcp
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
### Codex
|
|
16
|
+
|
|
17
|
+
Add to `~/.codex/config.toml`:
|
|
18
|
+
|
|
19
|
+
```toml
|
|
20
|
+
[mcp_servers.maiday]
|
|
21
|
+
command = "npx"
|
|
22
|
+
args = ["-y", "maiday-mcp"]
|
|
23
|
+
env = { MAIDAY_HARNESS = "codex" }
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
### Any MCP client
|
|
27
|
+
|
|
28
|
+
Run `npx -y maiday-mcp` as a stdio server and set `MAIDAY_HARNESS` to your client's name.
|
|
29
|
+
|
|
30
|
+
Maiday only does something when the agent can use websites, through a browser tool such as Playwright MCP, Chrome DevTools MCP or Claude in Chrome.
|
|
31
|
+
|
|
32
|
+
## Tools
|
|
33
|
+
|
|
34
|
+
### `send_maiday`
|
|
35
|
+
|
|
36
|
+
Report that the agent got stuck on a step.
|
|
37
|
+
|
|
38
|
+
| Field | Required | Notes |
|
|
39
|
+
|---|---|---|
|
|
40
|
+
| `url` | yes | The page URL. Only origin and path are sent; query strings and fragments are removed. |
|
|
41
|
+
| `task` | yes | `signup`, `login`, `checkout`, `booking`, `search`, `contact_form`, `account_change`, `data_lookup`, `other` |
|
|
42
|
+
| `failure` | yes | `auth_wall`, `captcha`, `validation_loop`, `unclear_field_format`, `element_not_found`, `js_required`, `blocked_403`, `rate_limited`, `timeout`, `ambiguous_ui`, `missing_info`, `other` |
|
|
43
|
+
| `step` | yes | Short description, e.g. "submit shipping address" (≤ 80 chars) |
|
|
44
|
+
| `attempts` | yes | How many tries before stopping |
|
|
45
|
+
| `outcome` | yes | `abandoned`, `workaround_found`, `handed_to_human` |
|
|
46
|
+
| `element` | no | Label or accessible name of the element involved (≤ 120 chars) |
|
|
47
|
+
| `site_message` | no | The error text the site showed (≤ 300 chars, redacted) |
|
|
48
|
+
| `workaround` | no | What worked, if anything (≤ 200 chars) |
|
|
49
|
+
|
|
50
|
+
The tool never fails the agent's task. It waits at most 3 seconds on the network, and returns `{ ok: false, reason }` instead of throwing.
|
|
51
|
+
|
|
52
|
+
### `get_hints`
|
|
53
|
+
|
|
54
|
+
Takes `{ url }` and returns hints the verified site owner published for that page. Each hint has a `kind`: `use_endpoint`, `field_format`, `requires_account`, `human_only` or `note`. Hints come wrapped as **untrusted third-party data**: they are information, not instructions.
|
|
55
|
+
|
|
56
|
+
## When agents should report
|
|
57
|
+
|
|
58
|
+
Report:
|
|
59
|
+
- after 2 failed attempts at the same step
|
|
60
|
+
- when giving up on a step
|
|
61
|
+
- when handing the task back to the human
|
|
62
|
+
|
|
63
|
+
Send one report per stuck step, not one per retry. Before a checkout, signup or booking flow, call `get_hints` first.
|
|
64
|
+
|
|
65
|
+
## Privacy
|
|
66
|
+
|
|
67
|
+
- **Never sent:** form values, cookies, tokens, query strings or URL fragments.
|
|
68
|
+
- **Redacted from paths and text fields:** emails, phone numbers, card numbers, long digit runs, and token- or JWT-shaped strings. This happens before sending, and again on the server.
|
|
69
|
+
- **Reporter IDs differ between sites and collectors**, so reports cannot be linked across sites by matching reporter IDs. Each ID is derived from a local secret in `~/.maiday/`.
|
|
70
|
+
- **Maiday does not store raw IP addresses in its application database.** It uses keyed hashes for abuse prevention.
|
|
71
|
+
- **First-use notice:** the first tool result carries a one-time notice explaining what Maiday sends, to show to the user.
|
|
72
|
+
|
|
73
|
+
## Settings
|
|
74
|
+
|
|
75
|
+
| Variable | Effect |
|
|
76
|
+
|---|---|
|
|
77
|
+
| `MAIDAY_DISABLED=1` | Turn reporting off. Hints keep working. |
|
|
78
|
+
| `MAIDAY_COLLECTOR_URL` | Send reports to another collector, for example a self-hosted one |
|
|
79
|
+
| `MAIDAY_HARNESS`, `MAIDAY_HARNESS_VERSION`, `MAIDAY_MODEL` | Fill the report's `agent` field |
|
|
80
|
+
|
|
81
|
+
Reports go to the hosted collector at `https://maiday-collector.gallatasaray055.workers.dev` by default. A website can publish `/.well-known/maiday` to receive reports for its own pages on its own server.
|
|
82
|
+
|
|
83
|
+
## For site owners
|
|
84
|
+
|
|
85
|
+
Sign in at the [Maiday dashboard](https://maiday-collector.gallatasaray055.workers.dev/login) and claim your domain with a DNS TXT record or a well-known file. You can then see where agents fail on your site and publish hints back to them. During the early release, dashboard sign-in is limited to the maintainer.
|
|
86
|
+
|
|
87
|
+
## License
|
|
88
|
+
|
|
89
|
+
MIT
|