@zeph-to/mcp-server 0.2.0

package/README.md

@@ -0,0 +1,242 @@
+# @zeph-to/mcp-server
+
+Zeph MCP server for AI agents. Send notifications, copy to clipboard, request confirmations, and collect text input from users across their devices — all via the [Model Context Protocol](https://modelcontextprotocol.io).
+
+## Setup
+
+### Claude Code
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "zeph": {
+      "command": "npx",
+      "args": ["-y", "@zeph-to/mcp-server"],
+      "env": {
+        "ZEPH_API_KEY": "ak_...",
+        "ZEPH_HOOK_ID": "hook_...",
+        "ZEPH_DEVICE_ID": "dev_..."
+      }
+    }
+  }
+}
+```
+
+### Cursor / Other MCP Clients
+
+```json
+{
+  "command": "npx",
+  "args": ["-y", "@zeph-to/mcp-server"],
+  "env": {
+    "ZEPH_API_KEY": "ak_..."
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `ZEPH_API_KEY` | Yes | API key from Settings > API Keys |
+| `ZEPH_HOOK_ID` | No | Hook ID for interactive tools (`zeph_prompt`, `zeph_input`) |
+| `ZEPH_DEVICE_ID` | No | Target device ID. Omit to send to all devices |
+| `ZEPH_BASE_URL` | No | API base URL (default: `https://api.zeph.to/v1`). Use `https://api.zeph.to/d1` for dev |
+
+## Tools
+
+### zeph_notify
+
+Send a one-way push notification. Supports optional URL (auto-switches to link type).
+
+```
+title:          "Build complete"
+body:           "All 42 tests passed"
+url:            "https://github.com/org/repo/actions/runs/123"  (optional)
+priority:       "low" | "normal" | "high" | "urgent"
+targetDeviceId: "dev_..."  (optional, overrides ZEPH_DEVICE_ID)
+```
+
+### zeph_clipboard
+
+Copy text to the user's device clipboard.
+
+```
+text:           "npm install @zeph-to/mcp-server"
+targetDeviceId: "dev_..."  (optional)
+```
+
+### zeph_list
+
+List recent push notifications.
+
+```
+limit: 5         (1-20, default: 5)
+type:  "note"    (optional filter: note, link, file, clipboard, hook)
+```
+
+Returns: `{ pushes: [...], total: 5, hasMore: true }`
+
+### zeph_dismiss
+
+Mark a specific push as read.
+
+```
+pushId: "push_01HX..."
+```
+
+### zeph_dismiss_all
+
+Clear all notifications at once. No parameters.
+
+Returns: `{ dismissed: 12, badge: 0 }`
+
+### zeph_broadcast
+
+Send a notification to all subscribers of a channel.
+
+```
+channelId: "ch_..."
+title:     "Deploy complete"
+body:      "v2.1.0 is live"
+url:       "https://..."  (optional)
+priority:  "normal"
+```
+
+### zeph_file
+
+Send a text file to the user's device.
+
+```
+fileName:       "report.json"
+content:        "{\"status\": \"ok\"}"
+title:          "Build Report"  (optional, defaults to fileName)
+targetDeviceId: "dev_..."       (optional)
+```
+
+Returns: `{ pushId: "...", fileKey: "...", fileSize: 42 }`
+
+### zeph_prompt
+
+Ask the user to choose from 2-4 options. Blocks until response or timeout.
+
+Requires `ZEPH_HOOK_ID`.
+
+```
+title:    "Deploy to production?"
+body:     "3 migrations pending"
+actions:  [{ id: "yes", label: "Deploy", style: "primary" },
+           { id: "no",  label: "Cancel", style: "danger" }]
+timeout:  120        (seconds, default: 120, max: 300)
+fallback: "no"       (auto-select on timeout, optional)
+```
+
+Returns: `{ actionId: "yes", timedOut: false }`
+
+### zeph_input
+
+Request free-form text input from the user. Blocks until response or timeout.
+
+Requires `ZEPH_HOOK_ID`.
+
+```
+title:       "Commit message"
+body:        "Summarize the changes"
+placeholder: "feat: ..."
+inputType:   "text" | "password" | "multiline"
+timeout:     120    (seconds, default: 120, max: 600)
+```
+
+Returns: `{ value: "feat: add clipboard sync", timedOut: false }`
+
+## Resources
+
+### zeph://devices
+
+Lists connected devices with online status. Use to check which devices will receive notifications.
+
+### zeph://channels
+
+Lists channels the user owns or subscribes to. Use to find `channelId` for `zeph_broadcast`.
+
+## Usage Guide
+
+### When to use each tool
+
+| Situation | Tool | Example |
+|-----------|------|---------|
+| Long task finished | `zeph_notify` | Build complete, test results, deploy done |
+| Need user decision | `zeph_prompt` | Choose deploy target, confirm destructive action |
+| Need free-form input | `zeph_input` | Commit message, env var value, description |
+| Share code/logs | `zeph_file` | Error logs, test reports, generated config |
+| Share snippet | `zeph_clipboard` | API key, URL, shell command |
+
+### Recommended patterns
+
+**Task completion notification:**
+```
+zeph_notify(
+  title: "Build complete: web app",
+  body: "All 42 tests passed. Bundle size: 1.2MB (-3%)"
+)
+```
+
+**Decision gate in CI/deploy flow:**
+```
+zeph_prompt(
+  title: "Deploy to production?",
+  body: "3 migrations pending. Last deploy: 2h ago.",
+  actions: [
+    { id: "deploy", label: "Deploy", style: "primary" },
+    { id: "staging", label: "Staging only", style: "secondary" },
+    { id: "cancel", label: "Cancel", style: "danger" }
+  ],
+  fallback: "cancel"
+)
+```
+
+**Collecting user input remotely:**
+```
+zeph_input(
+  title: "Commit message",
+  body: "Changed: hooks.ts, input.ts, prompt.ts",
+  placeholder: "feat: ..."
+)
+```
+
+**Error alert with link:**
+```
+zeph_notify(
+  title: "CI failed: lint errors",
+  body: "2 errors in src/auth.ts",
+  url: "https://github.com/org/repo/actions/runs/456",
+  priority: "high"
+)
+```
+
+### When NOT to use
+
+- Short responses the user can see immediately in the terminal
+- Read-only operations (file search, code analysis)
+- Every single tool call — only notify on meaningful milestones
+
+### Multi-session workflow
+
+When running multiple AI agent sessions in parallel, use `zeph_notify` to signal completion so the user knows which session finished without checking each terminal.
+
+## API Key Permissions
+
+The API key needs the following scopes:
+
+- `push:read` — for `zeph_list`
+- `push:write` — for `zeph_notify`, `zeph_clipboard`, `zeph_dismiss`, `zeph_dismiss_all`, `zeph_file`
+- `hook:write` — for `zeph_prompt` and `zeph_input`
+- `channel:read` — for `zeph://channels` resource
+
+Create an API key with the **MCP** preset in Settings > API Keys for the correct permissions.
+
+## License
+
+MIT

package/dist/api-client.d.ts

@@ -0,0 +1,54 @@
+import type { McpServerConfig } from './config.js';
+import type { PushResponse, HookTriggerResponse, HookEventResponse, DevicesResponse, PushListResponse, DismissResponse, ChannelsResponse, UploadRequestResponse } from './types.js';
+export declare class ApiError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(message: string, code: string, status: number);
+}
+export declare class ZephApiClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor(config: McpServerConfig);
+    sendPush(params: {
+        title: string;
+        body?: string;
+        url?: string;
+        type?: string;
+        priority?: string;
+        targetDeviceId?: string;
+        channelId?: string;
+        fileKey?: string;
+        fileName?: string;
+        fileSize?: number;
+        fileType?: string;
+    }): Promise<PushResponse>;
+    triggerHook(hookId: string, params: {
+        title: string;
+        body?: string;
+        actions?: {
+            id: string;
+            label: string;
+        }[];
+        timeout?: number;
+        fallback?: string;
+        metadata?: Record<string, unknown>;
+        hookType?: 'one-way' | 'interactive' | 'input';
+    }): Promise<HookTriggerResponse>;
+    getHookEvent(hookId: string, eventId: string): Promise<HookEventResponse>;
+    listDevices(): Promise<DevicesResponse>;
+    listPushes(params?: {
+        limit?: number;
+        type?: string;
+    }): Promise<PushListResponse>;
+    dismissPush(pushId: string): Promise<DismissResponse>;
+    dismissAllPushes(): Promise<DismissResponse>;
+    listChannels(): Promise<ChannelsResponse>;
+    requestUpload(params: {
+        fileName: string;
+        fileType: string;
+        fileSize: number;
+    }): Promise<UploadRequestResponse>;
+    uploadToS3(url: string, content: string, contentType: string): Promise<void>;
+    private request;
+}
+//# sourceMappingURL=api-client.d.ts.map

package/dist/api-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAEV,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAEpB,qBAAa,QAAS,SAAQ,KAAK;aAGf,IAAI,EAAE,MAAM;aACZ,MAAM,EAAE,MAAM;gBAF9B,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM;CAKjC;AAKD,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,MAAM,EAAE,eAAe;IAK7B,QAAQ,CAAC,MAAM,EAAE;QACrB,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,GAAG,OAAO,CAAC,YAAY,CAAC;IAInB,WAAW,CACf,MAAM,EAAE,MAAM,EACd,MAAM,EAAE;QACN,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;QAC1C,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACnC,QAAQ,CAAC,EAAE,SAAS,GAAG,aAAa,GAAG,OAAO,CAAC;KAChD,GACA,OAAO,CAAC,mBAAmB,CAAC;IAIzB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAIzE,WAAW,IAAI,OAAO,CAAC,eAAe,CAAC;IAIvC,UAAU,CAAC,MAAM,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAQjF,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAIrD,gBAAgB,IAAI,OAAO,CAAC,eAAe,CAAC;IAI5C,YAAY,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAIzC,aAAa,CAAC,MAAM,EAAE;QAC1B,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KAClB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAI5B,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAYpE,OAAO;CAsCtB"}

package/dist/api-client.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZephApiClient = exports.ApiError = void 0;
+class ApiError extends Error {
+    code;
+    status;
+    constructor(message, code, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = 'ApiError';
+    }
+}
+exports.ApiError = ApiError;
+const DEFAULT_TIMEOUT_MS = 30_000;
+const POLL_TIMEOUT_MS = 15_000;
+class ZephApiClient {
+    apiKey;
+    baseUrl;
+    constructor(config) {
+        this.apiKey = config.apiKey;
+        this.baseUrl = config.baseUrl;
+    }
+    async sendPush(params) {
+        return this.request('POST', '/pushes/send', params);
+    }
+    async triggerHook(hookId, params) {
+        return this.request('POST', `/hooks/${hookId}/trigger`, params);
+    }
+    async getHookEvent(hookId, eventId) {
+        return this.request('GET', `/hooks/${hookId}/events/${eventId}`, undefined, POLL_TIMEOUT_MS);
+    }
+    async listDevices() {
+        return this.request('GET', '/devices');
+    }
+    async listPushes(params) {
+        const query = new URLSearchParams();
+        if (params?.limit)
+            query.set('limit', String(params.limit));
+        if (params?.type)
+            query.set('type', params.type);
+        const qs = query.toString();
+        return this.request('GET', `/pushes${qs ? `?${qs}` : ''}`);
+    }
+    async dismissPush(pushId) {
+        return this.request('POST', `/pushes/${pushId}/dismiss`);
+    }
+    async dismissAllPushes() {
+        return this.request('POST', '/pushes/dismiss-all');
+    }
+    async listChannels() {
+        return this.request('GET', '/channels');
+    }
+    async requestUpload(params) {
+        return this.request('POST', '/files/upload-request', params);
+    }
+    async uploadToS3(url, content, contentType) {
+        const response = await fetch(url, {
+            method: 'PUT',
+            headers: { 'Content-Type': contentType },
+            body: content,
+            signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS),
+        });
+        if (!response.ok) {
+            throw new ApiError(`S3 upload failed with status ${response.status}`, 'UPLOAD_FAILED', response.status);
+        }
+    }
+    async request(method, path, body, timeoutMs = DEFAULT_TIMEOUT_MS) {
+        const url = `${this.baseUrl}${path}`;
+        const headers = {
+            'X-API-Key': this.apiKey,
+        };
+        if (body) {
+            headers['Content-Type'] = 'application/json';
+        }
+        let response;
+        try {
+            response = await fetch(url, {
+                method,
+                headers,
+                body: body ? JSON.stringify(body) : undefined,
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+        }
+        catch (err) {
+            if (err instanceof DOMException && err.name === 'TimeoutError') {
+                throw new ApiError('Request timed out', 'TIMEOUT', 408);
+            }
+            throw err;
+        }
+        if (!response.ok) {
+            let errorBody = null;
+            try {
+                errorBody = (await response.json());
+            }
+            catch {
+                // Non-JSON error response (e.g., HTML error page)
+            }
+            const message = errorBody?.error?.message ?? `Request failed with status ${response.status}`;
+            const code = errorBody?.error?.code ?? 'UNKNOWN_ERROR';
+            throw new ApiError(message, code, response.status);
+        }
+        return (await response.json());
+    }
+}
+exports.ZephApiClient = ZephApiClient;

package/dist/config.d.ts

@@ -0,0 +1,8 @@
+export interface McpServerConfig {
+    apiKey: string;
+    baseUrl: string;
+    hookId?: string;
+    deviceId?: string;
+}
+export declare const loadConfig: () => McpServerConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,eAAO,MAAM,UAAU,QAAO,eAc7B,CAAC"}

package/dist/config.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadConfig = void 0;
+const DEFAULT_BASE_URL = 'https://api.zeph.to/v1';
+const loadConfig = () => {
+    const apiKey = process.env['ZEPH_API_KEY'];
+    if (!apiKey) {
+        throw new Error('ZEPH_API_KEY environment variable is required. Get one at Settings → API Keys.');
+    }
+    return {
+        apiKey,
+        baseUrl: (process.env['ZEPH_BASE_URL'] ?? DEFAULT_BASE_URL).replace(/\/$/, ''),
+        hookId: process.env['ZEPH_HOOK_ID'],
+        deviceId: process.env['ZEPH_DEVICE_ID'],
+    };
+};
+exports.loadConfig = loadConfig;

package/dist/error-format.d.ts

@@ -0,0 +1,8 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { ToolError } from './types.js';
+export declare const textResult: (obj: unknown) => CallToolResult;
+export declare const errorResult: (obj: ToolError) => CallToolResult;
+export declare const hookNotConfiguredError: () => CallToolResult;
+export declare const timeoutError: (seconds: number, suggestion: string) => CallToolResult;
+export declare const formatToolError: (err: unknown) => CallToolResult;
+//# sourceMappingURL=error-format.d.ts.map

package/dist/error-format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-format.d.ts","sourceRoot":"","sources":["../src/error-format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,eAAO,MAAM,UAAU,GAAI,KAAK,OAAO,KAAG,cAExC,CAAC;AAEH,eAAO,MAAM,WAAW,GAAI,KAAK,SAAS,KAAG,cAG3C,CAAC;AAEH,eAAO,MAAM,sBAAsB,QAAO,cAKtC,CAAC;AAEL,eAAO,MAAM,YAAY,GAAI,SAAS,MAAM,EAAE,YAAY,MAAM,KAAG,cAK/D,CAAC;AAEL,eAAO,MAAM,eAAe,GAAI,KAAK,OAAO,KAAG,cAsB9C,CAAC"}

package/dist/error-format.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatToolError = exports.timeoutError = exports.hookNotConfiguredError = exports.errorResult = exports.textResult = void 0;
+const api_client_js_1 = require("./api-client.js");
+const textResult = (obj) => ({
+    content: [{ type: 'text', text: JSON.stringify(obj) }],
+});
+exports.textResult = textResult;
+const errorResult = (obj) => ({
+    content: [{ type: 'text', text: JSON.stringify(obj) }],
+    isError: true,
+});
+exports.errorResult = errorResult;
+const hookNotConfiguredError = () => (0, exports.errorResult)({
+    error: 'HOOK_NOT_CONFIGURED',
+    message: 'ZEPH_HOOK_ID environment variable is not set',
+    suggestion: 'Create a Hook in Settings → Hooks, then set ZEPH_HOOK_ID in your MCP server config',
+});
+exports.hookNotConfiguredError = hookNotConfiguredError;
+const timeoutError = (seconds, suggestion) => (0, exports.errorResult)({
+    error: 'TIMEOUT',
+    message: `No response received within ${seconds} seconds`,
+    suggestion,
+});
+exports.timeoutError = timeoutError;
+const formatToolError = (err) => {
+    const toolError = {
+        error: 'UNKNOWN',
+        message: err instanceof Error ? err.message : String(err),
+    };
+    if (err instanceof api_client_js_1.ApiError) {
+        toolError.error = err.code;
+        toolError.message = err.message;
+        if (err.code === 'QUOTA_EXCEEDED') {
+            toolError.suggestion = 'Monthly quota exceeded. Upgrade plan for higher limits';
+        }
+        else if (err.code === 'UNAUTHORIZED') {
+            toolError.suggestion = 'Check ZEPH_API_KEY environment variable';
+        }
+        else if (err.code === 'HOOK_DISABLED') {
+            toolError.suggestion = 'Enable the Hook in Settings → Hooks';
+        }
+        else if (err.code === 'FORBIDDEN') {
+            toolError.suggestion = 'Check API key permissions (needs push:write and hook:write)';
+        }
+    }
+    return (0, exports.errorResult)(toolError);
+};
+exports.formatToolError = formatToolError;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const config_js_1 = require("./config.js");
+const api_client_js_1 = require("./api-client.js");
+const notify_js_1 = require("./tools/notify.js");
+const prompt_js_1 = require("./tools/prompt.js");
+const input_js_1 = require("./tools/input.js");
+const clipboard_js_1 = require("./tools/clipboard.js");
+const list_js_1 = require("./tools/list.js");
+const dismiss_js_1 = require("./tools/dismiss.js");
+const broadcast_js_1 = require("./tools/broadcast.js");
+const file_js_1 = require("./tools/file.js");
+const devices_js_1 = require("./resources/devices.js");
+const channels_js_1 = require("./resources/channels.js");
+const createServer = () => {
+    const config = (0, config_js_1.loadConfig)();
+    const client = new api_client_js_1.ZephApiClient(config);
+    const server = new mcp_js_1.McpServer({
+        name: 'zeph',
+        version: '0.2.0',
+    }, {
+        instructions: [
+            'Zeph MCP Server — Send notifications, files, clipboard text, broadcast to channels, manage push history, and interact with users across their devices.',
+            '',
+            'Available tools:',
+            '- zeph_notify: Send push notifications with optional URL (task completion, errors, links)',
+            '- zeph_clipboard: Copy text to user\'s device clipboard',
+            '- zeph_list: List recent push notifications (history, deduplication)',
+            '- zeph_dismiss: Mark a push as read',
+            '- zeph_dismiss_all: Clear all notifications',
+            '- zeph_broadcast: Send to all subscribers of a channel',
+            '- zeph_file: Send a text file (logs, reports, code)',
+            '- zeph_prompt: Ask user to choose from options (requires ZEPH_HOOK_ID)',
+            '- zeph_input: Request text input from user (requires ZEPH_HOOK_ID)',
+            '',
+            'Resources:',
+            '- zeph://devices: Check which devices are online',
+            '- zeph://channels: List available channels for broadcasting',
+        ].join('\n'),
+    });
+    (0, notify_js_1.registerNotifyTool)(server, client, config);
+    (0, clipboard_js_1.registerClipboardTool)(server, client, config);
+    (0, list_js_1.registerListTool)(server, client);
+    (0, dismiss_js_1.registerDismissTool)(server, client);
+    (0, dismiss_js_1.registerDismissAllTool)(server, client);
+    (0, broadcast_js_1.registerBroadcastTool)(server, client);
+    (0, file_js_1.registerFileTool)(server, client, config);
+    (0, prompt_js_1.registerPromptTool)(server, client, config);
+    (0, input_js_1.registerInputTool)(server, client, config);
+    (0, devices_js_1.registerDevicesResource)(server, client);
+    (0, channels_js_1.registerChannelsResource)(server, client);
+    return server;
+};
+const main = async () => {
+    const server = createServer();
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    console.error('Zeph MCP Server running on stdio');
+};
+main().catch((err) => {
+    console.error('Fatal error:', err);
+    process.exit(1);
+});

package/dist/poll.d.ts

@@ -0,0 +1,10 @@
+import type { ZephApiClient } from './api-client.js';
+import type { HookEventResponse } from './types.js';
+export interface PollContext {
+    _meta?: {
+        progressToken?: string | number;
+    };
+    sendNotification: (notification: any) => Promise<void>;
+}
+export declare const pollForResponse: (client: ZephApiClient, hookId: string, eventId: string, timeoutSeconds: number, ctx: PollContext) => Promise<HookEventResponse | null>;
+//# sourceMappingURL=poll.d.ts.map

package/dist/poll.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"poll.d.ts","sourceRoot":"","sources":["../src/poll.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAE5C,gBAAgB,EAAE,CAAC,YAAY,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACxD;AAOD,eAAO,MAAM,eAAe,GAC1B,QAAQ,aAAa,EACrB,QAAQ,MAAM,EACd,SAAS,MAAM,EACf,gBAAgB,MAAM,EACtB,KAAK,WAAW,KACf,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAsClC,CAAC"}

package/dist/poll.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pollForResponse = void 0;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const PROGRESS_INTERVAL_SECONDS = 5;
+const pollForResponse = async (client, hookId, eventId, timeoutSeconds, ctx) => {
+    const progressToken = ctx._meta?.progressToken;
+    const startTime = Date.now();
+    const timeoutMs = timeoutSeconds * 1000;
+    let attempt = 0;
+    let lastProgressAt = 0;
+    while (Date.now() - startTime < timeoutMs) {
+        const event = await client.getHookEvent(hookId, eventId);
+        if (event.data.status === 'responded')
+            return event;
+        if (event.data.status === 'cancelled')
+            throw new Error('User cancelled the request');
+        if (event.data.status === 'timed_out')
+            return null;
+        // Throttled progress notification (every 5s)
+        if (progressToken !== undefined) {
+            const elapsed = Math.floor((Date.now() - startTime) / 1000);
+            if (elapsed - lastProgressAt >= PROGRESS_INTERVAL_SECONDS) {
+                lastProgressAt = elapsed;
+                await ctx.sendNotification({
+                    method: 'notifications/progress',
+                    params: {
+                        progressToken,
+                        progress: elapsed,
+                        total: timeoutSeconds,
+                        message: `Waiting for user response... (${elapsed}s / ${timeoutSeconds}s)`,
+                    },
+                });
+            }
+        }
+        // Adaptive interval: 2s for first 5 attempts, then 3s
+        const interval = attempt < 5 ? 2000 : 3000;
+        await sleep(interval);
+        attempt++;
+    }
+    return null;
+};
+exports.pollForResponse = pollForResponse;

package/dist/resources/channels.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ZephApiClient } from '../api-client.js';
+export declare const registerChannelsResource: (server: McpServer, client: ZephApiClient) => void;
+//# sourceMappingURL=channels.d.ts.map

package/dist/resources/channels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channels.d.ts","sourceRoot":"","sources":["../../src/resources/channels.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,eAAO,MAAM,wBAAwB,GAAI,QAAQ,SAAS,EAAE,QAAQ,aAAa,SAuBhF,CAAC"}

package/dist/resources/channels.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerChannelsResource = void 0;
+const registerChannelsResource = (server, client) => {
+    server.registerResource('channels', 'zeph://channels', {
+        title: 'Channels',
+        description: 'List of channels the user owns or subscribes to. Use to find channelId for broadcasting.',
+        mimeType: 'application/json',
+    }, async (uri) => {
+        try {
+            const response = await client.listChannels();
+            return {
+                contents: [{ uri: uri.href, text: JSON.stringify(response.data, null, 2) }],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Failed to fetch channels';
+            return {
+                contents: [{ uri: uri.href, text: JSON.stringify({ error: message }) }],
+            };
+        }
+    });
+};
+exports.registerChannelsResource = registerChannelsResource;