maiday-mcp 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,89 @@
+# maiday-mcp
+
+**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.
+
+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.
+
+## Install
+
+### Claude Code
+
+```bash
+claude mcp add -s user maiday -e MAIDAY_HARNESS=claude-code -- npx -y maiday-mcp
+```
+
+### Codex
+
+Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.maiday]
+command = "npx"
+args = ["-y", "maiday-mcp"]
+env = { MAIDAY_HARNESS = "codex" }
+```
+
+### Any MCP client
+
+Run `npx -y maiday-mcp` as a stdio server and set `MAIDAY_HARNESS` to your client's name.
+
+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.
+
+## Tools
+
+### `send_maiday`
+
+Report that the agent got stuck on a step.
+
+| Field | Required | Notes |
+|---|---|---|
+| `url` | yes | The page URL. Only origin and path are sent; query strings and fragments are removed. |
+| `task` | yes | `signup`, `login`, `checkout`, `booking`, `search`, `contact_form`, `account_change`, `data_lookup`, `other` |
+| `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` |
+| `step` | yes | Short description, e.g. "submit shipping address" (≤ 80 chars) |
+| `attempts` | yes | How many tries before stopping |
+| `outcome` | yes | `abandoned`, `workaround_found`, `handed_to_human` |
+| `element` | no | Label or accessible name of the element involved (≤ 120 chars) |
+| `site_message` | no | The error text the site showed (≤ 300 chars, redacted) |
+| `workaround` | no | What worked, if anything (≤ 200 chars) |
+
+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.
+
+### `get_hints`
+
+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.
+
+## When agents should report
+
+Report:
+- after 2 failed attempts at the same step
+- when giving up on a step
+- when handing the task back to the human
+
+Send one report per stuck step, not one per retry. Before a checkout, signup or booking flow, call `get_hints` first.
+
+## Privacy
+
+- **Never sent:** form values, cookies, tokens, query strings or URL fragments.
+- **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.
+- **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/`.
+- **Maiday does not store raw IP addresses in its application database.** It uses keyed hashes for abuse prevention.
+- **First-use notice:** the first tool result carries a one-time notice explaining what Maiday sends, to show to the user.
+
+## Settings
+
+| Variable | Effect |
+|---|---|
+| `MAIDAY_DISABLED=1` | Turn reporting off. Hints keep working. |
+| `MAIDAY_COLLECTOR_URL` | Send reports to another collector, for example a self-hosted one |
+| `MAIDAY_HARNESS`, `MAIDAY_HARNESS_VERSION`, `MAIDAY_MODEL` | Fill the report's `agent` field |
+
+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.
+
+## For site owners
+
+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.
+
+## License
+
+MIT

package/dist/bin.js

@@ -210,6 +210,9 @@ function matchHint(pattern, path) {
       return false;
   return true;
 }
+function isValidPathPattern(pp) {
+  return pp.startsWith("/") && pp.length <= HINT_PATH_PATTERN_MAX && !/[?#]/.test(pp) && !hasControlChars(pp) && !pp.split("/").some((seg) => seg.includes("*") && seg !== "*");
+}
 function isSameSiteEndpoint(endpoint, domain) {
   let u;
   try {
@@ -240,7 +243,7 @@ function validateHint(input, domain) {
       return { ok: false, error: "Hints may not contain control characters or line breaks." };
   }
   const pp = h.path_pattern;
-  if (!pp.startsWith("/") || pp.length > HINT_PATH_PATTERN_MAX || /[?#]/.test(pp) || pp.split("/").some((seg) => seg.includes("*") && seg !== "*")) {
+  if (!isValidPathPattern(pp)) {
     return { ok: false, error: `Path pattern must start with "/", be at most ${HINT_PATH_PATTERN_MAX} characters, contain no "?" or "#", and use "*" only as a whole segment.` };
   }
   if (h.kind === "use_endpoint") {
@@ -353,26 +356,45 @@ async function fetchSite(origin, fetchFn, fallback, parent) {
 
 // src/install.ts
 import { createHmac, randomBytes } from "crypto";
-import { mkdir, readFile, writeFile } from "fs/promises";
+import { link, mkdir, readFile, rename, unlink, writeFile } from "fs/promises";
 import { join } from "path";
 var newSecret = () => randomBytes(32).toString("base64url");
+async function claim(target) {
+  const tmp = `${target}.${randomBytes(8).toString("hex")}.tmp`;
+  await writeFile(tmp, JSON.stringify({ secret: newSecret() }) + "\n", { mode: 384 });
+  let created = true;
+  try {
+    await link(tmp, target);
+  } catch (e) {
+    if (e.code !== "EEXIST") throw e;
+    created = false;
+  } finally {
+    await unlink(tmp).catch(() => {
+    });
+  }
+  return { secret: await readSecret(target), created };
+}
+async function replaceWith(file, secret) {
+  const tmp = `${file}.${randomBytes(8).toString("hex")}.tmp`;
+  await writeFile(tmp, JSON.stringify({ secret }) + "\n", { mode: 384 });
+  await rename(tmp, file);
+}
 async function getInstall(home) {
   const dir = join(home, ".maiday");
   const file = join(dir, "install.json");
   await mkdir(dir, { recursive: true });
-  const existing = await readSecret(file);
-  if (existing) return { secret: existing, firstRun: false };
-  const secret = newSecret();
-  try {
-    await writeFile(file, JSON.stringify({ secret }) + "\n", { flag: "wx", mode: 384 });
-    return { secret, firstRun: true };
-  } catch (e) {
-    if (e.code !== "EEXIST") throw e;
-    const raced = await readSecret(file);
-    if (raced) return { secret: raced, firstRun: false };
-    await writeFile(file, JSON.stringify({ secret }) + "\n", { mode: 384 });
-    return { secret, firstRun: true };
+  let existing = await readSecret(file);
+  if (typeof existing === "string") return { secret: existing, firstRun: false };
+  if (existing === null) {
+    const c = await claim(file);
+    if (c.created) return { secret: c.secret, firstRun: true };
+    if (typeof c.secret === "string") return { secret: c.secret, firstRun: false };
+    existing = c.secret;
   }
+  const replacement = await claim(join(dir, "install.v2.json"));
+  if (typeof replacement.secret !== "string") throw new Error(`unreadable ${join(dir, "install.v2.json")}`);
+  await replaceWith(file, replacement.secret);
+  return { secret: replacement.secret, firstRun: existing === null && replacement.created };
 }
 function cachedInstall(home) {
   let p;
@@ -384,14 +406,18 @@ function cachedInstall(home) {
     return p;
   };
 }
-function installIdFor(secret, reportEndpoint) {
-  return createHmac("sha256", secret).update(new URL(reportEndpoint).origin).digest("base64url");
+var INSTALL_ID_VERSION = "v2";
+function installIdFor(secret, reportEndpoint, siteOrigin) {
+  const input = JSON.stringify(["maiday-install-id", INSTALL_ID_VERSION, new URL(reportEndpoint).origin, new URL(siteOrigin).origin]);
+  return `${INSTALL_ID_VERSION}.${createHmac("sha256", secret).update(input).digest("base64url")}`;
 }
+var LEGACY = /* @__PURE__ */ Symbol("legacy install file");
 async function readSecret(file) {
   try {
     const parsed = JSON.parse(await readFile(file, "utf8"));
-    const v = parsed.secret ?? parsed.id;
-    return typeof v === "string" && v.length > 0 && v.length <= 128 ? v : null;
+    const v = parsed.secret;
+    if (typeof v === "string" && v.length > 0 && v.length <= 128) return v;
+    return typeof parsed.id === "string" && parsed.id.length > 0 ? LEGACY : null;
   } catch {
     return null;
   }
@@ -481,7 +507,7 @@ async function sendMaiday(input, deps) {
     return await withDeadline(
       async (signal) => {
         const site = await discover(report.origin, deps.fetch, discoverOpts(deps, signal));
-        const body = { ...checked.data, install_id: installIdFor(secret, site.reportEndpoint) };
+        const body = { ...checked.data, install_id: installIdFor(secret, site.reportEndpoint, checked.data.origin) };
         const res = await deps.fetch(site.reportEndpoint, {
           method: "POST",
           redirect: "manual",
@@ -570,7 +596,7 @@ var sendShape = {
 };
 var asText = (payload) => ({ content: [{ type: "text", text: JSON.stringify(payload) }] });
 function createServer(baseDeps) {
-  const server2 = new McpServer({ name: "maiday-mcp", version: "0.1.0" });
+  const server2 = new McpServer({ name: "maiday-mcp", version: "0.1.2" });
   const deps = { ...baseDeps, install: baseDeps.install ?? cachedInstall(baseDeps.config.home) };
   let noticeClaimed = false;
   const takeNotice = async () => {

package/dist/index.d.ts

@@ -21,11 +21,14 @@ declare function getInstall(home: string): Promise<Install>;
  * firstRun and the first-run notice cannot be lost to a concurrent write. A failure is not cached (next call retries).
  */
 declare function cachedInstall(home: string): () => Promise<Install>;
+/** Prefix of the current reporter-ID scheme; collectors count IDs per scheme and never add schemes together. */
+declare const INSTALL_ID_VERSION = "v2";
 /**
- * The install_id sent to one report endpoint: base64url(HMAC-SHA256(secret, endpoint origin)), 43 chars.
- * Each collector sees a stable id it can count, but ids cannot be linked across collectors.
+ * The install_id sent with a report: "v2." + base64url(HMAC-SHA256(secret, JSON ["maiday-install-id", "v2",
+ * collector origin, site origin])). Stable for one collector and one site; different for every other site or
+ * collector, so reports cannot be linked across sites by matching IDs. JSON keeps the inputs unambiguous.
  */
-declare function installIdFor(secret: string, reportEndpoint: string): string;
+declare function installIdFor(secret: string, reportEndpoint: string, siteOrigin: string): string;
 
 interface Discovered {
     reportEndpoint: string;
@@ -88,5 +91,5 @@ declare function getHints(url: string, deps: Deps): Promise<HintsResult>;
 declare const FIRST_RUN_NOTICE = "Maiday sends anonymous reports when an agent gets stuck on a website (page path, failure type, the site's error message with personal data removed). No form values or personal data are sent. Set MAIDAY_DISABLED=1 to turn reporting off. Please tell the user this once.";
 declare function createServer(baseDeps: Deps): McpServer;
 
-export { DEFAULT_COLLECTOR_URL, FIRST_RUN_NOTICE, HINTS_INSTRUCTIONS, cachedInstall, createServer, defaultEndpoints, discover, getHints, getInstall, installIdFor, isSafeEndpoint, loadConfig, sendMaiday };
+export { DEFAULT_COLLECTOR_URL, FIRST_RUN_NOTICE, HINTS_INSTRUCTIONS, INSTALL_ID_VERSION, cachedInstall, createServer, defaultEndpoints, discover, getHints, getInstall, installIdFor, isSafeEndpoint, loadConfig, sendMaiday };
 export type { Config, Deps, DiscoverOptions, Discovered, Env, HintsResult, Install, SendResult };

package/dist/index.js

@@ -13,26 +13,45 @@ function loadConfig(env = process.env) {
 
 // src/install.ts
 import { createHmac, randomBytes } from "crypto";
-import { mkdir, readFile, writeFile } from "fs/promises";
+import { link, mkdir, readFile, rename, unlink, writeFile } from "fs/promises";
 import { join } from "path";
 var newSecret = () => randomBytes(32).toString("base64url");
+async function claim(target) {
+  const tmp = `${target}.${randomBytes(8).toString("hex")}.tmp`;
+  await writeFile(tmp, JSON.stringify({ secret: newSecret() }) + "\n", { mode: 384 });
+  let created = true;
+  try {
+    await link(tmp, target);
+  } catch (e) {
+    if (e.code !== "EEXIST") throw e;
+    created = false;
+  } finally {
+    await unlink(tmp).catch(() => {
+    });
+  }
+  return { secret: await readSecret(target), created };
+}
+async function replaceWith(file, secret) {
+  const tmp = `${file}.${randomBytes(8).toString("hex")}.tmp`;
+  await writeFile(tmp, JSON.stringify({ secret }) + "\n", { mode: 384 });
+  await rename(tmp, file);
+}
 async function getInstall(home) {
   const dir = join(home, ".maiday");
   const file = join(dir, "install.json");
   await mkdir(dir, { recursive: true });
-  const existing = await readSecret(file);
-  if (existing) return { secret: existing, firstRun: false };
-  const secret = newSecret();
-  try {
-    await writeFile(file, JSON.stringify({ secret }) + "\n", { flag: "wx", mode: 384 });
-    return { secret, firstRun: true };
-  } catch (e) {
-    if (e.code !== "EEXIST") throw e;
-    const raced = await readSecret(file);
-    if (raced) return { secret: raced, firstRun: false };
-    await writeFile(file, JSON.stringify({ secret }) + "\n", { mode: 384 });
-    return { secret, firstRun: true };
+  let existing = await readSecret(file);
+  if (typeof existing === "string") return { secret: existing, firstRun: false };
+  if (existing === null) {
+    const c = await claim(file);
+    if (c.created) return { secret: c.secret, firstRun: true };
+    if (typeof c.secret === "string") return { secret: c.secret, firstRun: false };
+    existing = c.secret;
   }
+  const replacement = await claim(join(dir, "install.v2.json"));
+  if (typeof replacement.secret !== "string") throw new Error(`unreadable ${join(dir, "install.v2.json")}`);
+  await replaceWith(file, replacement.secret);
+  return { secret: replacement.secret, firstRun: existing === null && replacement.created };
 }
 function cachedInstall(home) {
   let p;
@@ -44,14 +63,18 @@ function cachedInstall(home) {
     return p;
   };
 }
-function installIdFor(secret, reportEndpoint) {
-  return createHmac("sha256", secret).update(new URL(reportEndpoint).origin).digest("base64url");
+var INSTALL_ID_VERSION = "v2";
+function installIdFor(secret, reportEndpoint, siteOrigin) {
+  const input = JSON.stringify(["maiday-install-id", INSTALL_ID_VERSION, new URL(reportEndpoint).origin, new URL(siteOrigin).origin]);
+  return `${INSTALL_ID_VERSION}.${createHmac("sha256", secret).update(input).digest("base64url")}`;
 }
+var LEGACY = /* @__PURE__ */ Symbol("legacy install file");
 async function readSecret(file) {
   try {
     const parsed = JSON.parse(await readFile(file, "utf8"));
-    const v = parsed.secret ?? parsed.id;
-    return typeof v === "string" && v.length > 0 && v.length <= 128 ? v : null;
+    const v = parsed.secret;
+    if (typeof v === "string" && v.length > 0 && v.length <= 128) return v;
+    return typeof parsed.id === "string" && parsed.id.length > 0 ? LEGACY : null;
   } catch {
     return null;
   }
@@ -247,6 +270,9 @@ function matchHint(pattern, path) {
       return false;
   return true;
 }
+function isValidPathPattern(pp) {
+  return pp.startsWith("/") && pp.length <= HINT_PATH_PATTERN_MAX && !/[?#]/.test(pp) && !hasControlChars(pp) && !pp.split("/").some((seg) => seg.includes("*") && seg !== "*");
+}
 function isSameSiteEndpoint(endpoint, domain) {
   let u;
   try {
@@ -277,7 +303,7 @@ function validateHint(input, domain) {
       return { ok: false, error: "Hints may not contain control characters or line breaks." };
   }
   const pp = h.path_pattern;
-  if (!pp.startsWith("/") || pp.length > HINT_PATH_PATTERN_MAX || /[?#]/.test(pp) || pp.split("/").some((seg) => seg.includes("*") && seg !== "*")) {
+  if (!isValidPathPattern(pp)) {
     return { ok: false, error: `Path pattern must start with "/", be at most ${HINT_PATH_PATTERN_MAX} characters, contain no "?" or "#", and use "*" only as a whole segment.` };
   }
   if (h.kind === "use_endpoint") {
@@ -472,7 +498,7 @@ async function sendMaiday(input, deps) {
     return await withDeadline(
       async (signal) => {
         const site = await discover(report.origin, deps.fetch, discoverOpts(deps, signal));
-        const body = { ...checked.data, install_id: installIdFor(secret, site.reportEndpoint) };
+        const body = { ...checked.data, install_id: installIdFor(secret, site.reportEndpoint, checked.data.origin) };
         const res = await deps.fetch(site.reportEndpoint, {
           method: "POST",
           redirect: "manual",
@@ -563,7 +589,7 @@ var sendShape = {
 };
 var asText = (payload) => ({ content: [{ type: "text", text: JSON.stringify(payload) }] });
 function createServer(baseDeps) {
-  const server = new McpServer({ name: "maiday-mcp", version: "0.1.0" });
+  const server = new McpServer({ name: "maiday-mcp", version: "0.1.2" });
   const deps = { ...baseDeps, install: baseDeps.install ?? cachedInstall(baseDeps.config.home) };
   let noticeClaimed = false;
   const takeNotice = async () => {
@@ -596,6 +622,7 @@ export {
   DEFAULT_COLLECTOR_URL,
   FIRST_RUN_NOTICE,
   HINTS_INSTRUCTIONS,
+  INSTALL_ID_VERSION,
   cachedInstall,
   createServer,
   defaultEndpoints,

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "maiday-mcp",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Maiday MCP client: privacy-safe stuck reports and site-owner hints for AI agents",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
-    "maiday-mcp": "./dist/bin.js"
+    "maiday-mcp": "dist/bin.js"
   },
   "files": [
     "dist"