palmier 0.7.3 → 0.7.6

package/README.md

@@ -53,37 +53,47 @@ Palmier exposes an [MCP](https://modelcontextprotocol.io) server at `http://loca
 | `create-contact` | Create a new contact on the user's device | Contacts Access |
 | `read-calendar` | Read calendar events (with time range filter) | Calendar Access |
 | `create-calendar-event` | Create a calendar event on the user's device | Calendar Access |
-| `send-sms` | Send an SMS message from the user's device | SMS Access |
+| `send-sms-message` | Send an SMS message from the user's device | SMS Access |
 | `set-alarm` | Set an alarm on the user's device | None |
 | `read-battery` | Get battery level and charging status | None |
 | `set-ringer-mode` | Set ringer mode (normal/vibrate/silent) | Do Not Disturb Control |
 
 **Available resources:**
-| Resource | URI | REST | Description |
-|----------|-----|------|-------------|
-| Device Notifications | `notifications://device` | `GET /notifications` | Recent notifications from the user's Android device |
-| Device SMS | `sms://device` | `GET /sms` | Recent SMS messages from the user's Android device |
+| Resource | URI | Permission | Description |
+|----------|-----|------------|-------------|
+| Device Notifications | `notifications://device` | Notification Access | Recent notifications from the user's Android device |
+| Device SMS | `sms-messages://device` | SMS Access | Recent SMS messages from the user's Android device |
 
 Resources support MCP subscriptions — clients can subscribe via `resources/subscribe` and receive real-time `notifications/resources/updated` events via the streamable HTTP transport when the resource changes.
 
 All device tools work while the Palmier Android app is in the background — they communicate via FCM data messages which wake the app's service even when it's not in the foreground. Permissions listed above must be granted via toggles in the Android app's settings menu.
 
+### Architecture
+
 ```
 ┌──────────────┐         HTTP          ┌──────────────────┐
 │              │◄──────────────────────│                  │
 │  Host Daemon │                       │   PWA (Browser)  │
-│              │◄──────┐               │                  │
-└──────┬───────┘       │               └──────────────────┘
-       │               │                        │
-       ▼               │  NATS (TLS)            │ NATS (TLS)
-┌──────────────┐       │               ┌────────┴─────────┐
-│  Agent CLIs  │       └───────────────│  Relay Server    │
-│  (Claude,    │                       │  (passthrough,   │
-│   Gemini,    │                       │   push notify)   │
-│   Codex ...) │                       └──────────────────┘
-└──────────────┘
+│  (MCP Server)│◄──────┐               │                  │
+└──┬────────┬──┘       │               └──────────────────┘
+   │        │          │                        │
+   ▼        ▼          │  NATS (TLS)            │ NATS (TLS)
+┌──────┐ ┌──────┐      │               ┌────────┴─────────┐
+│Agent │ │Agent │      └───────────────│  Relay Server    │
+│ CLIs │ │Tools/│                       │  (passthrough,   │
+│      │ │Rsrcs │◄──── FCM ───────────│   push, FCM)     │
+└──────┘ └──────┘                       └──────────────────┘
+                                                │
+                                           FCM  │
+                                                ▼
+                                       ┌──────────────────┐
+                                       │  Android Device  │
+                                       │  (notifications, │
+                                       │   SMS, contacts, │
+                                       │   calendar, GPS) │
+                                       └──────────────────┘
         Local / LAN: direct HTTP
-        Server mode: via relay server
+        Server mode: via relay server + FCM
 ```
 
 ## Access Modes

package/dist/device-capabilities.d.ts

@@ -0,0 +1,9 @@
+export interface RegisteredDevice {
+    clientToken: string;
+    fcmToken: string;
+}
+export type DeviceCapability = "location" | "notifications" | "sms" | "contacts" | "calendar" | "alert" | "battery" | "dnd";
+export declare function getCapabilityDevice(capability: DeviceCapability): RegisteredDevice | null;
+export declare function setCapabilityDevice(capability: DeviceCapability, clientToken: string, fcmToken: string): void;
+export declare function clearCapabilityDevice(capability: DeviceCapability): void;
+//# sourceMappingURL=device-capabilities.d.ts.map

package/dist/device-capabilities.js

@@ -0,0 +1,36 @@
+import * as fs from "fs";
+import * as path from "path";
+import { CONFIG_DIR } from "./config.js";
+const CAPABILITIES_FILE = path.join(CONFIG_DIR, "device-capabilities.json");
+function readAll() {
+    try {
+        if (!fs.existsSync(CAPABILITIES_FILE))
+            return {};
+        return JSON.parse(fs.readFileSync(CAPABILITIES_FILE, "utf-8"));
+    }
+    catch {
+        return {};
+    }
+}
+function writeAll(map) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    fs.writeFileSync(CAPABILITIES_FILE, JSON.stringify(map, null, 2), "utf-8");
+}
+export function getCapabilityDevice(capability) {
+    const map = readAll();
+    const device = map[capability];
+    if (!device?.clientToken || !device?.fcmToken)
+        return null;
+    return device;
+}
+export function setCapabilityDevice(capability, clientToken, fcmToken) {
+    const map = readAll();
+    map[capability] = { clientToken, fcmToken };
+    writeAll(map);
+}
+export function clearCapabilityDevice(capability) {
+    const map = readAll();
+    delete map[capability];
+    writeAll(map);
+}
+//# sourceMappingURL=device-capabilities.js.map

package/dist/mcp-tools.js

@@ -1,6 +1,6 @@
 import { StringCodec } from "nats";
 import { registerPending } from "./pending-requests.js";
-import { getLocationDevice } from "./location-device.js";
+import { getCapabilityDevice } from "./device-capabilities.js";
 import { getNotifications } from "./notification-store.js";
 import { getSmsMessages } from "./sms-store.js";
 export class ToolError extends Error {
@@ -145,11 +145,11 @@ const deviceGeolocationTool = {
     async handler(_args, ctx) {
         if (!ctx.nc)
             throw new ToolError("Not connected to server (NATS unavailable)", 503);
-        const locDevice = getLocationDevice();
-        if (!locDevice)
+        const device = getCapabilityDevice("location");
+        if (!device)
             throw new ToolError("No device has location access enabled", 400);
         const sc = StringCodec();
-        const ackReply = await ctx.nc.request(`host.${ctx.config.hostId}.fcm.geolocation`, sc.encode(JSON.stringify({ hostId: ctx.config.hostId, requestId: ctx.sessionId, fcmToken: locDevice.fcmToken })), { timeout: 5_000 });
+        const ackReply = await ctx.nc.request(`host.${ctx.config.hostId}.fcm.geolocation`, sc.encode(JSON.stringify({ hostId: ctx.config.hostId, requestId: ctx.sessionId, fcmToken: device.fcmToken })), { timeout: 5_000 });
         const ack = JSON.parse(sc.decode(ackReply.data));
         if (ack.error)
             throw new ToolError(ack.error, 502);
@@ -186,8 +186,11 @@ const readContactsTool = {
     async handler(_args, ctx) {
         if (!ctx.nc)
             throw new ToolError("Not connected to server (NATS unavailable)", 503);
+        const device = getCapabilityDevice("contacts");
+        if (!device)
+            throw new ToolError("No device has contacts access enabled", 400);
         const sc = StringCodec();
-        const ackReply = await ctx.nc.request(`host.${ctx.config.hostId}.fcm.contacts`, sc.encode(JSON.stringify({ hostId: ctx.config.hostId, requestId: ctx.sessionId, action: "read" })), { timeout: 5_000 });
+        const ackReply = await ctx.nc.request(`host.${ctx.config.hostId}.fcm.contacts`, sc.encode(JSON.stringify({ hostId: ctx.config.hostId, requestId: ctx.sessionId, fcmToken: device.fcmToken, action: "read" })), { timeout: 5_000 });
         const ack = JSON.parse(sc.decode(ackReply.data));
         if (ack.error)
             throw new ToolError(ack.error, 502);
@@ -229,12 +232,15 @@ const createContactTool = {
     async handler(args, ctx) {
         if (!ctx.nc)
             throw new ToolError("Not connected to server (NATS unavailable)", 503);
+        const device = getCapabilityDevice("contacts");
+        if (!device)
+            throw new ToolError("No device has contacts access enabled", 400);
         const { name, phone, email } = args;
         if (!name)
             throw new ToolError("name is required", 400);
         const sc = StringCodec();
         const ackReply = await ctx.nc.request(`host.${ctx.config.hostId}.fcm.contacts`, sc.encode(JSON.stringify({
-            hostId: ctx.config.hostId, requestId: ctx.sessionId,
+            hostId: ctx.config.hostId, requestId: ctx.sessionId, fcmToken: device.fcmToken,
             action: "create", name, phone, email,
         })), { timeout: 5_000 });
         const ack = JSON.parse(sc.decode(ackReply.data));
@@ -277,10 +283,13 @@ const readCalendarTool = {
     async handler(args, ctx) {
         if (!ctx.nc)
             throw new ToolError("Not connected to server (NATS unavailable)", 503);
+        const device = getCapabilityDevice("calendar");
+        if (!device)
+            throw new ToolError("No device has calendar access enabled", 400);
         const { startDate, endDate } = args;
         const sc = StringCodec();
         const ackReply = await ctx.nc.request(`host.${ctx.config.hostId}.fcm.calendar`, sc.encode(JSON.stringify({
-            hostId: ctx.config.hostId, requestId: ctx.sessionId,
+            hostId: ctx.config.hostId, requestId: ctx.sessionId, fcmToken: device.fcmToken,
             action: "read",
             ...(startDate ? { startDate: String(startDate) } : {}),
             ...(endDate ? { endDate: String(endDate) } : {}),
@@ -328,12 +337,15 @@ const createCalendarEventTool = {
     async handler(args, ctx) {
         if (!ctx.nc)
             throw new ToolError("Not connected to server (NATS unavailable)", 503);
+        const device = getCapabilityDevice("calendar");
+        if (!device)
+            throw new ToolError("No device has calendar access enabled", 400);
         const { title, startTime, endTime, location, description } = args;
         if (!title || !startTime || !endTime)
             throw new ToolError("title, startTime, and endTime are required", 400);
         const sc = StringCodec();
         const ackReply = await ctx.nc.request(`host.${ctx.config.hostId}.fcm.calendar`, sc.encode(JSON.stringify({
-            hostId: ctx.config.hostId, requestId: ctx.sessionId,
+            hostId: ctx.config.hostId, requestId: ctx.sessionId, fcmToken: device.fcmToken,
             action: "create",
             title, startTime: String(startTime), endTime: String(endTime),
             ...(location ? { location } : {}),
@@ -362,7 +374,7 @@ const createCalendarEventTool = {
     },
 };
 const sendSmsTool = {
-    name: "send-sms",
+    name: "send-sms-message",
     description: [
         "Send an SMS message from the user's mobile device.",
         "Blocks until the device responds (up to 30 seconds).",
@@ -379,12 +391,15 @@ const sendSmsTool = {
     async handler(args, ctx) {
         if (!ctx.nc)
             throw new ToolError("Not connected to server (NATS unavailable)", 503);
+        const device = getCapabilityDevice("sms");
+        if (!device)
+            throw new ToolError("No device has SMS access enabled", 400);
         const { to, body } = args;
         if (!to || !body)
             throw new ToolError("to and body are required", 400);
         const sc = StringCodec();
         const ackReply = await ctx.nc.request(`host.${ctx.config.hostId}.fcm.sms`, sc.encode(JSON.stringify({
-            hostId: ctx.config.hostId, requestId: ctx.sessionId,
+            hostId: ctx.config.hostId, requestId: ctx.sessionId, fcmToken: device.fcmToken,
             action: "send", to, body,
         })), { timeout: 5_000 });
         const ack = JSON.parse(sc.decode(ackReply.data));
@@ -409,48 +424,44 @@ const sendSmsTool = {
         return result;
     },
 };
-const setAlarmTool = {
-    name: "set-alarm",
+const sendAlertTool = {
+    name: "send-alert",
     description: [
-        "Set an alarm on the user's mobile device.",
+        "Send an alert to the user's mobile device with an alarm sound and full-screen popup.",
+        "Use this to urgently get the user's attention. The device will play an alarm sound and show a full-screen dialog even on the lock screen.",
         "Blocks until the device responds (up to 30 seconds).",
         'Response: `{"ok": true}` on success, or `{"error": "..."}` on failure.',
     ],
     inputSchema: {
         type: "object",
         properties: {
-            hour: { type: "number", description: "Hour (0-23)" },
-            minutes: { type: "number", description: "Minutes (0-59)" },
-            label: { type: "string", description: "Alarm label" },
-            days: {
-                type: "array",
-                items: { type: "number" },
-                description: "Recurring days (1=Sun, 2=Mon, ..., 7=Sat). Omit for one-time.",
-            },
+            title: { type: "string", description: "Alert title" },
+            description: { type: "string", description: "Alert description/details" },
         },
-        required: ["hour", "minutes"],
+        required: ["title"],
     },
     async handler(args, ctx) {
         if (!ctx.nc)
             throw new ToolError("Not connected to server (NATS unavailable)", 503);
-        const { hour, minutes, label, days } = args;
-        if (hour == null || minutes == null)
-            throw new ToolError("hour and minutes are required", 400);
+        const device = getCapabilityDevice("alert");
+        if (!device)
+            throw new ToolError("No device has alert access enabled", 400);
+        const { title, description } = args;
+        if (!title)
+            throw new ToolError("title is required", 400);
         const sc = StringCodec();
         const payload = {
-            hostId: ctx.config.hostId, requestId: ctx.sessionId,
-            action: "set", hour: String(hour), minutes: String(minutes),
+            hostId: ctx.config.hostId, requestId: ctx.sessionId, fcmToken: device.fcmToken,
+            title,
         };
-        if (label)
-            payload.label = label;
-        if (days?.length)
-            payload.days = days.join(",");
-        const ackReply = await ctx.nc.request(`host.${ctx.config.hostId}.fcm.alarm`, sc.encode(JSON.stringify(payload)), { timeout: 5_000 });
+        if (description)
+            payload.description = description;
+        const ackReply = await ctx.nc.request(`host.${ctx.config.hostId}.fcm.alert`, sc.encode(JSON.stringify(payload)), { timeout: 5_000 });
         const ack = JSON.parse(sc.decode(ackReply.data));
         if (ack.error)
             throw new ToolError(ack.error, 502);
         const responsePromise = new Promise((resolve, reject) => {
-            const sub = ctx.nc.subscribe(`host.${ctx.config.hostId}.alarm.${ctx.sessionId}`, { max: 1 });
+            const sub = ctx.nc.subscribe(`host.${ctx.config.hostId}.alert.${ctx.sessionId}`, { max: 1 });
             const timer = setTimeout(() => {
                 sub.unsubscribe();
                 reject(new ToolError("Device did not respond within 30 seconds", 504));
@@ -482,8 +493,11 @@ const readBatteryTool = {
     async handler(_args, ctx) {
         if (!ctx.nc)
             throw new ToolError("Not connected to server (NATS unavailable)", 503);
+        const device = getCapabilityDevice("battery");
+        if (!device)
+            throw new ToolError("No device has battery access enabled", 400);
         const sc = StringCodec();
-        const ackReply = await ctx.nc.request(`host.${ctx.config.hostId}.fcm.battery`, sc.encode(JSON.stringify({ hostId: ctx.config.hostId, requestId: ctx.sessionId })), { timeout: 5_000 });
+        const ackReply = await ctx.nc.request(`host.${ctx.config.hostId}.fcm.battery`, sc.encode(JSON.stringify({ hostId: ctx.config.hostId, requestId: ctx.sessionId, fcmToken: device.fcmToken })), { timeout: 5_000 });
         const ack = JSON.parse(sc.decode(ackReply.data));
         if (ack.error)
             throw new ToolError(ack.error, 502);
@@ -523,11 +537,14 @@ const setRingerModeTool = {
     async handler(args, ctx) {
         if (!ctx.nc)
             throw new ToolError("Not connected to server (NATS unavailable)", 503);
+        const device = getCapabilityDevice("dnd");
+        if (!device)
+            throw new ToolError("No device has Do Not Disturb control enabled", 400);
         const { mode } = args;
         if (!["normal", "vibrate", "silent"].includes(mode))
             throw new ToolError("mode must be 'normal', 'vibrate', or 'silent'", 400);
         const sc = StringCodec();
-        const ackReply = await ctx.nc.request(`host.${ctx.config.hostId}.fcm.ringer`, sc.encode(JSON.stringify({ hostId: ctx.config.hostId, requestId: ctx.sessionId, mode })), { timeout: 5_000 });
+        const ackReply = await ctx.nc.request(`host.${ctx.config.hostId}.fcm.ringer`, sc.encode(JSON.stringify({ hostId: ctx.config.hostId, requestId: ctx.sessionId, fcmToken: device.fcmToken, mode })), { timeout: 5_000 });
         const ack = JSON.parse(sc.decode(ackReply.data));
         if (ack.error)
             throw new ToolError(ack.error, 502);
@@ -550,7 +567,7 @@ const setRingerModeTool = {
         return result;
     },
 };
-export const agentTools = [notifyTool, requestInputTool, requestConfirmationTool, deviceGeolocationTool, readContactsTool, createContactTool, readCalendarTool, createCalendarEventTool, sendSmsTool, setAlarmTool, readBatteryTool, setRingerModeTool];
+export const agentTools = [notifyTool, requestInputTool, requestConfirmationTool, deviceGeolocationTool, readContactsTool, createContactTool, readCalendarTool, createCalendarEventTool, sendSmsTool, sendAlertTool, readBatteryTool, setRingerModeTool];
 export const agentToolMap = new Map(agentTools.map((t) => [t.name, t]));
 const deviceNotificationsResource = {
     uri: "notifications://device",
@@ -564,14 +581,14 @@ const deviceNotificationsResource = {
     read: getNotifications,
 };
 const deviceSmsResource = {
-    uri: "sms://device",
+    uri: "sms-messages://device",
     name: "Device SMS",
     description: [
         "Get recent SMS messages from the user's Android device.",
         "Response: JSON array of message objects with `id`, `sender`, `body`, `timestamp`.",
     ],
     mimeType: "application/json",
-    restPath: "/sms",
+    restPath: "/sms-messages",
     read: getSmsMessages,
 };
 export const agentResources = [deviceNotificationsResource, deviceSmsResource];