lauther-mcp 0.1.1 → 0.3.0

package/README.md

@@ -30,7 +30,7 @@ token**. Then add the server to your MCP config:
 
 Nothing to install — `npx` fetches it. Node 18+.
 
-## The two tools
+## The tools
 
 ### `ask_approval`
 
@@ -62,6 +62,49 @@ It reports what actually happened, including the case worth knowing about: if
 no device is registered on your account, you're told that rather than given a
 cheerful success for a notification nobody received.
 
+### `get_location`
+
+Asks you to share where you are, once. You get a prompt on your phone with
+**Share location** and **Decline**; the agent receives one position, as it was
+when you tapped.
+
+| Result | What the agent is told |
+| --- | --- |
+| `SHARED` | latitude, longitude, accuracy in metres, and when it was read |
+| `DECLINED` | do not retry and do not find the location another way |
+| `NO ANSWER` | silence is not consent; nothing was shared |
+| `EXPIRED` | the request lapsed on your phone; nothing was shared |
+
+Options: `question` (what you see on the prompt), `details`,
+`require_biometric`, `timeout_seconds` (default 120).
+
+### `request_photo`
+
+Asks you for one picture, taken on the spot or picked from your library. The
+agent gets the link **and the image itself**, so it can look at it. The link
+works for 7 days, after which the photo is deleted. If the image cannot be
+fetched the agent still gets the text and the link.
+
+Same options and the same four outcomes as `get_location`.
+
+### `ask_text`
+
+Asks you a short question and waits for you to type the answer on your phone:
+a verification code, a choice, a name, a fact only you know. The prompt shows
+the question and a field, with **Reply** and **Decline**. Answers run to 500
+characters, so it is for short things.
+
+| Result | What the agent is told |
+| --- | --- |
+| `ANSWERED` | exactly what you typed, in quotes |
+| `DECLINED` | do not retry and do not get the answer another way |
+| `NO ANSWER` | silence is not consent; nothing was sent |
+| `EXPIRED` | the request lapsed on your phone; nothing was sent |
+
+Options: `question` (default "Answer a question?"), `details`,
+`placeholder` (a hint in the field, such as "6-digit code"),
+`require_biometric`, `timeout_seconds` (default 120).
+
 ## Telling your agent when to use it
 
 Most models won't reach for an approval tool unless asked. Something like this

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "lauther-mcp",
   "mcpName": "io.github.csanadymiklos/lauther",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "MCP server that lets an AI agent ask its owner for approval on their phone before doing something irreversible.",
   "keywords": [
     "mcp",
@@ -20,7 +20,7 @@
   "author": "Dipling Kft.",
   "type": "module",
   "bin": {
-    "lauther-mcp": "./src/index.js"
+    "lauther-mcp": "src/index.js"
   },
   "main": "./src/index.js",
   "files": [
@@ -35,7 +35,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "lauther-client": "^0.2.0",
+    "lauther-client": "^0.4.0",
     "zod": "^3.25.0"
   },
   "repository": {

package/src/index.js

@@ -2,11 +2,14 @@
 /**
  * lauther-mcp — an MCP server that puts a human in the loop, on their phone.
  *
- * Two tools, and resisting a third is the point:
+ * Five tools, each one thing an agent needs a person for:
  *
- *   ask_approval      the agent is about to do something irreversible and
- *                     asks first. Blocks until a person answers.
+ *   ask_approval       the agent is about to do something irreversible and
+ *                      asks first. Blocks until a person answers.
  *   send_notification  "the migration finished", "the build broke".
+ *   get_location       "where are you?" - one position, shared on a tap.
+ *   request_photo      "show me" - one picture, taken or picked on the phone.
+ *   ask_text           "what is the code?" - a short answer, typed on the phone.
  *
  * The interesting one is ask_approval. Lauther's /v1/approve long-polls for at
  * most 25 seconds, which suits a shell one-liner and not an agent whose owner
@@ -19,6 +22,9 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { Lauther, LautherError } from "lauther-client";
+import { createRequire } from "node:module";
+
+const PKG_VERSION = createRequire(import.meta.url)("../package.json").version;
 
 const TOKEN = process.env.LAUTHER_TOKEN;
 const BASE_URL = process.env.LAUTHER_BASE_URL; // tests and self-hosted relays
@@ -35,6 +41,12 @@ if (!TOKEN) {
 
 const lauther = new Lauther(TOKEN, BASE_URL ? { baseUrl: BASE_URL } : {});
 
+/** The server keeps shared photos for 7 days (SPEC_REQUESTS 1.5). */
+const PHOTO_RETENTION = "7 days";
+
+/** A shared photo is shown to the agent inline; the API caps uploads at 2 MB. */
+const MAX_INLINE_PHOTO_BYTES = 4 * 1024 * 1024;
+
 const text = (s) => ({ content: [{ type: "text", text: s }] });
 const failure = (s) => ({ content: [{ type: "text", text: s }], isError: true });
 
@@ -50,8 +62,54 @@ function explain(err) {
   return `Unexpected error: ${err?.message ?? String(err)}`;
 }
 
+/** `2026-10-13T09:00:00.000Z` becomes `2026-10-13T09:00:00Z`; anything odd passes through. */
+function isoSeconds(at) {
+  const d = new Date(at);
+  return Number.isNaN(d.getTime()) ? String(at) : d.toISOString().replace(/\.\d+Z$/, "Z");
+}
+
+/** " Confirmed by biometric." or nothing. */
+const confirmation = (out) => (out.confirmedBy ? ` Confirmed by ${out.confirmedBy}.` : "");
+
+/**
+ * The non-yes outcomes of a request, worded for an agent. Returns null when
+ * the person did approve, so the caller can describe what was shared.
+ *
+ * @param {string} what "location", "photo" or "answer", for the sentence
+ */
+function notShared(out, what) {
+  if (out.response === "approve") return null;
+  if (out.response === "deny") {
+    return text(`DECLINED after ${out.waitedSeconds}s. Do not retry, and do not try ` +
+      `to get the ${what} another way - report the refusal and stop.`);
+  }
+  if (out.expired) {
+    return text(`EXPIRED after ${out.waitedSeconds}s - the request lapsed on their ` +
+      `phone before anyone answered, and no ${what} was shared. Expiry is not ` +
+      "consent: say it expired and let the human restart it when they are back.");
+  }
+  return text(`NO ANSWER after ${out.waitedSeconds}s - nobody responded, so no ` +
+    `${what} was shared. Silence is not consent: say the request went unanswered ` +
+    "and let the human restart it when they are back.");
+}
+
+/** Fetch a shared photo for inline display. Null on any failure: the text still works. */
+async function fetchPhoto(url) {
+  try {
+    const res = await fetch(url, { signal: AbortSignal.timeout(10_000) });
+    if (!res.ok) return null;
+    const bytes = Buffer.from(await res.arrayBuffer());
+    if (bytes.length === 0 || bytes.length > MAX_INLINE_PHOTO_BYTES) return null;
+    return bytes.toString("base64");
+  } catch {
+    return null;
+  }
+}
+
 export function buildServer() {
-  const server = new McpServer({ name: "lauther", version: "0.1.0" });
+  // The version comes from package.json so it cannot drift from what npm
+  // published (it did once: 0.1.1 on npm reported itself as 0.1.0).
+  const server = new McpServer({ name: "lauther", version: PKG_VERSION });
 
   server.registerTool(
     "ask_approval",
@@ -147,6 +205,177 @@ export function buildServer() {
     },
   );
 
+  server.registerTool(
+    "get_location",
+    {
+      title: "Ask a human to share their location",
+      description:
+        "Ask the human who owns this phone to share where they are right now. " +
+        "They get a prompt and choose Share or Decline; if they share, one " +
+        "position is sent, once, as it was at that moment. Use it when you " +
+        "need their location to do the task (find the nearest branch, set a " +
+        "timezone, log a site visit), not to track them. Returns SHARED with " +
+        "latitude, longitude and accuracy, or DECLINED, NO ANSWER or EXPIRED. " +
+        "On anything but SHARED you have no location: do not guess one.",
+      inputSchema: {
+        question: z.string().min(1).max(250).optional()
+          .describe("What they see on the prompt. Say why you need it: " +
+            "'Share your location so I can find the nearest pharmacy?'. " +
+            "Defaults to 'Share your location?'."),
+        details: z.string().max(2000).optional()
+          .describe("Anything else that helps them decide."),
+        require_biometric: z.boolean().optional()
+          .describe("Demand a fingerprint or face before the location is sent."),
+        timeout_seconds: z.number().int().min(5).max(900).optional()
+          .describe("How long to wait for an answer. Defaults to 120."),
+      },
+    },
+    async ({ question = "Share your location?", details, require_biometric,
+      timeout_seconds = 120 }) => {
+      try {
+        const out = await lauther.requestLocation({
+          title: question,
+          message: details,
+          requireBiometric: require_biometric,
+          timeoutSeconds: timeout_seconds,
+        });
+        const notYes = notShared(out, "location");
+        if (notYes) return notYes;
+
+        const loc = out.result;
+        if (!loc || typeof loc.lat !== "number" || typeof loc.lng !== "number") {
+          return failure("They approved, but Lauther returned no usable position. " +
+            "You have no location: do not guess one.");
+        }
+        const accuracy = typeof loc.accuracy === "number"
+          ? ` (±${Math.round(loc.accuracy)} m)` : "";
+        const at = loc.at ? ` at ${isoSeconds(loc.at)}` : "";
+        return text(`SHARED after ${out.waitedSeconds}s: ` +
+          `${loc.lat.toFixed(4)}, ${loc.lng.toFixed(4)}${accuracy}${at}.` +
+          `${confirmation(out)} That is where they were at that moment, shared once ` +
+          "for what you asked about - use it for that and nothing else.");
+      } catch (err) {
+        return failure(explain(err) + " No location was obtained, so do not guess one.");
+      }
+    },
+  );
+
+  server.registerTool(
+    "request_photo",
+    {
+      title: "Ask a human for a photo",
+      description:
+        "Ask the human who owns this phone for one picture. They get a prompt " +
+        "and choose to take a photo (or pick one) or Decline. Use it when you " +
+        "need to see something only they can show you: a label, a screen, a " +
+        "whiteboard, a damaged part. Returns SHARED with a link plus the image " +
+        "itself so you can look at it directly, or DECLINED, NO ANSWER or " +
+        "EXPIRED. The link works for 7 days and the photo is then deleted.",
+      inputSchema: {
+        question: z.string().min(1).max(250).optional()
+          .describe("What they see on the prompt. Say what you need to see: " +
+            "'Take a photo of the error on the printer display?'. " +
+            "Defaults to 'Take a photo?'."),
+        details: z.string().max(2000).optional()
+          .describe("Anything else that helps them decide or frame the shot."),
+        require_biometric: z.boolean().optional()
+          .describe("Demand a fingerprint or face before the photo is sent."),
+        timeout_seconds: z.number().int().min(5).max(900).optional()
+          .describe("How long to wait for an answer. Defaults to 120."),
+      },
+    },
+    async ({ question = "Take a photo?", details, require_biometric,
+      timeout_seconds = 120 }) => {
+      try {
+        const out = await lauther.requestPhoto({
+          title: question,
+          message: details,
+          requireBiometric: require_biometric,
+          timeoutSeconds: timeout_seconds,
+        });
+        const notYes = notShared(out, "photo");
+        if (notYes) return notYes;
+
+        const photo = out.result;
+        if (!photo || typeof photo.url !== "string") {
+          return failure("They approved, but Lauther returned no photo. You have " +
+            "nothing to look at: do not guess what it showed.");
+        }
+        const size = photo.width && photo.height ? ` ${photo.width}x${photo.height}` : "";
+        const line = `SHARED after ${out.waitedSeconds}s: photo${size} at ${photo.url} ` +
+          `- available for ${PHOTO_RETENTION}.${confirmation(out)}`;
+
+        const data = await fetchPhoto(photo.url);
+        if (!data) {
+          return text(`${line} The image could not be fetched to show you inline, ` +
+            "but the link above still works.");
+        }
+        return {
+          content: [
+            { type: "text", text: `${line} The picture is attached.` },
+            { type: "image", data, mimeType: "image/jpeg" },
+          ],
+        };
+      } catch (err) {
+        return failure(explain(err) + " No photo was obtained, so do not guess what it showed.");
+      }
+    },
+  );
+
+  server.registerTool(
+    "ask_text",
+    {
+      title: "Ask a human a short question",
+      description:
+        "Ask the human who owns this phone a short question and wait for them " +
+        "to type the answer on it. Use it for something only they know: a " +
+        "verification code, a choice between options, a name, a short fact. " +
+        "Never for long text (answers are capped at 500 characters), and not " +
+        "for permission to act: use ask_approval for that. Returns ANSWERED " +
+        "with exactly what they typed, or DECLINED, NO ANSWER or EXPIRED. On " +
+        "anything but ANSWERED you have no answer: do not guess one.",
+      inputSchema: {
+        question: z.string().min(1).max(250).optional()
+          .describe("The question, as they read it on a lock screen. Be " +
+            "specific about the shape of the answer: 'What is the 6-digit " +
+            "code from your authenticator?'. Defaults to 'Answer a question?'."),
+        details: z.string().max(2000).optional()
+          .describe("Anything else that helps them answer."),
+        placeholder: z.string().max(80).optional()
+          .describe("A hint shown in the answer field, e.g. '6-digit code'."),
+        require_biometric: z.boolean().optional()
+          .describe("Demand a fingerprint or face before the answer is sent."),
+        timeout_seconds: z.number().int().min(5).max(900).optional()
+          .describe("How long to wait for an answer. Defaults to 120."),
+      },
+    },
+    async ({ question = "Answer a question?", details, placeholder, require_biometric,
+      timeout_seconds = 120 }) => {
+      try {
+        const out = await lauther.requestText({
+          title: question,
+          message: details,
+          placeholder,
+          requireBiometric: require_biometric,
+          timeoutSeconds: timeout_seconds,
+        });
+        const notYes = notShared(out, "answer");
+        if (notYes) return notYes;
+
+        const answer = out.result;
+        if (!answer || typeof answer.text !== "string") {
+          return failure("They replied, but Lauther returned no usable answer. " +
+            "You have no answer: do not guess one.");
+        }
+        return text(`ANSWERED after ${out.waitedSeconds}s: ${JSON.stringify(answer.text)}.` +
+          `${confirmation(out)} That is what they typed, sent once in reply to what ` +
+          "you asked - use it for that and nothing else.");
+      } catch (err) {
+        return failure(explain(err) + " No answer was obtained, so do not guess one.");
+      }
+    },
+  );
+
   return server;
 }