ping-a-human 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ping-a-human contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,146 @@
+# ping-a-human
+
+An open-source [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that adds a
+human-in-the-loop step to any AI pipeline, agent, or automation. It lets an AI **notify** a human or
+**ask** a human and wait for their answer — reaching the person on the messaging app they already use
+(Telegram first; Slack, WhatsApp, and more later).
+
+Unlike MCP's built-in elicitation (which prompts inside the AI client UI), `ping-a-human` reaches the
+human **out-of-band on their own messaging app**, so it works even when nobody is watching the AI
+session.
+
+## Tools
+
+The server exposes two tools over stdio:
+
+- **`notify_human`** — fire-and-forget. Sends a message to the configured human and returns
+  immediately without waiting for a reply.
+  - Input: `{ message: string }`
+- **`ask_human`** — sends a question, then **blocks until the human replies** (or a timeout elapses)
+  and returns their answer.
+  - Input: `{ question: string, choices?: string[], timeoutMs?: number }`
+  - With `choices`, the options render as tappable Telegram inline buttons and the tapped value is
+    returned (e.g. `["Yes", "No"]`).
+  - On timeout it returns a clear timed-out result instead of an error, so the calling agent gets a
+    clean signal. Default timeout is 5 minutes.
+
+## Install
+
+No clone or build required. The server runs straight from npm via your package runner:
+
+```bash
+npx  ping-a-human setup     # npm
+bunx ping-a-human setup     # bun
+pnpm dlx ping-a-human setup # pnpm
+```
+
+Your MCP client (Claude Desktop, Cursor, etc.) launches it the same way (see step 2) — so end users
+never install anything globally. Cloning the repo is only needed for contributing.
+
+## Quickstart
+
+### 1. Create a Telegram bot and configure the server
+
+Run the interactive setup wizard — it validates your bot token, auto-detects your chat id, writes the
+config, and prints the MCP client entry to paste:
+
+```bash
+npx ping-a-human setup
+```
+
+The wizard walks you through:
+
+1. Message [@BotFather](https://t.me/BotFather) in Telegram, send `/newbot`, and copy the bot token.
+2. Paste the token when prompted — the wizard verifies it via Telegram and shows your bot's `@username`.
+3. Send your new bot any message (e.g. "hi") in Telegram, then press Enter — the wizard auto-detects
+   your `chat_id`.
+4. The config is saved to `~/.config/ping-a-human/config.json` and the wizard prints an `mcpServers`
+   snippet.
+
+### 2. Add the server to your MCP client
+
+Add this to your MCP client config (Claude Desktop, Cursor, etc.):
+
+```json
+{
+  "mcpServers": {
+    "ping-a-human": {
+      "command": "npx",
+      "args": ["-y", "ping-a-human"]
+    }
+  }
+}
+```
+
+Restart the client. It will list `notify_human` and `ask_human`.
+
+### 3. Use it from an agent
+
+- **Notify** when a long job finishes: `notify_human({ message: "Deploy to prod finished ✅" })`.
+- **Ask before a risky action**:
+  `ask_human({ question: "Apply this DB migration to prod?", choices: ["Yes", "No"] })` — the human
+  taps a button and the agent receives `"Yes"` or `"No"`.
+- **Ask an open question**: `ask_human({ question: "What should the release title be?" })` — the agent
+  receives the human's free-text reply.
+
+## Configuration
+
+The server reads configuration with this precedence:
+
+1. Environment variables `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` (both required together).
+2. A config file at `$PING_A_HUMAN_CONFIG`, or `~/.config/ping-a-human/config.json` by default,
+   shaped as:
+
+```json
+{ "telegram": { "botToken": "123456:ABC-...", "chatId": "4242" } }
+```
+
+The bot token is a secret — it is never logged or echoed. All diagnostics go to **stderr**; **stdout**
+is reserved for the MCP JSON-RPC channel.
+
+## Local development
+
+```bash
+npm install
+npm run build
+node dist/index.js          # starts the stdio MCP server
+node dist/index.js setup    # runs the setup wizard
+npm test                    # runs the full test suite
+```
+
+### Live smoke test (optional)
+
+With real credentials set, send a real message and wait for a reply:
+
+```bash
+TELEGRAM_BOT_TOKEN=... TELEGRAM_CHAT_ID=... node scripts/smoke-telegram.mjs
+```
+
+Without credentials it prints a skip notice and exits 0, so it is safe in CI.
+
+## End-to-end verification (live)
+
+A repeatable manual procedure that exercises the whole loop against real Telegram:
+
+1. **Create a bot.** In Telegram, message [@BotFather](https://t.me/BotFather), send `/newbot`, and
+   copy the token.
+2. **Run setup.** `npx ping-a-human setup` — paste the token, message your bot when prompted, and let
+   the wizard auto-detect your `chat_id` and write the config.
+3. **Wire up a client.** Add the printed `mcpServers` snippet to Claude Desktop / Cursor and restart.
+4. **Prove `ask_human` with buttons.** From the client, call
+   `ask_human({ question: "Proceed?", choices: ["Yes", "No"] })`. You should receive a Telegram message
+   with two buttons; tap one and confirm the agent receives that exact value.
+5. **Prove `notify_human`.** Call `notify_human({ message: "hello from my agent" })` and confirm the
+   message arrives and the call returns immediately.
+6. **Prove the timeout.** Call `ask_human({ question: "...", timeoutMs: 10000 })` and do not reply;
+   after ~10s the agent should receive a clear timed-out result (not an error).
+
+No MCP client handy? The credential-gated smoke script exercises the live send → reply path directly:
+
+```bash
+TELEGRAM_BOT_TOKEN=... TELEGRAM_CHAT_ID=... node scripts/smoke-telegram.mjs
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/channel-factory.d.ts

@@ -0,0 +1,25 @@
+import type { Channel } from "./channel.js";
+import { type LoadConfigOptions } from "./config.js";
+/**
+ * Single seam where resolved configuration meets a concrete channel provider.
+ *
+ * Tools (notify_human / ask_human) depend only on the {@link Channel}
+ * interface; this factory is the one place that knows Telegram is the current
+ * implementation (R005). Adding Slack/WhatsApp later means branching here on a
+ * provider field — tool logic stays untouched.
+ */
+export type CreateChannelOptions = LoadConfigOptions & {
+    /**
+     * Pre-built channel override. When provided it is returned as-is, bypassing
+     * config loading. Used by tests to inject a stub Channel.
+     */
+    channel?: Channel;
+};
+/**
+ * Build a {@link Channel} from configuration.
+ *
+ * Throws (via loadConfig) with a clear, secret-free message when configuration
+ * is missing or invalid. Callers should surface that as a tool result rather
+ * than crashing the server.
+ */
+export declare function createChannel(opts?: CreateChannelOptions): Channel;

package/dist/channel-factory.js

@@ -0,0 +1,19 @@
+import { loadConfig } from "./config.js";
+import { TelegramChannel } from "./channels/telegram.js";
+/**
+ * Build a {@link Channel} from configuration.
+ *
+ * Throws (via loadConfig) with a clear, secret-free message when configuration
+ * is missing or invalid. Callers should surface that as a tool result rather
+ * than crashing the server.
+ */
+export function createChannel(opts = {}) {
+    if (opts.channel) {
+        return opts.channel;
+    }
+    const config = loadConfig(opts);
+    return new TelegramChannel({
+        botToken: config.telegram.botToken,
+        chatId: config.telegram.chatId,
+    });
+}

package/dist/channel.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Transport-agnostic messaging channel contract.
+ *
+ * This interface is deliberately free of any provider-specific types so that
+ * the first messaging provider is just one implementation and others (Slack,
+ * WhatsApp) can be added later without changing tool logic (R005). Tools
+ * (notify_human / ask_human) import ONLY this module — never a concrete
+ * channel's types.
+ */
+/** Opaque handle to a message that was sent through a channel. */
+export type MessageRef = {
+    /** Provider-neutral message identifier (the provider's message id as a string). */
+    id: string;
+};
+/** Options controlling how a message is sent. */
+export type SendOptions = {
+    /**
+     * Optional predefined choices. When present, the channel should render them
+     * as tappable buttons and return the selected value as the reply answer.
+     */
+    choices?: string[];
+};
+/** Options controlling how long, and from when, to wait for a human reply. */
+export type AwaitReplyOptions = {
+    /** Overall deadline in milliseconds. On expiry, awaitReply resolves to a timeout result. */
+    timeoutMs: number;
+    /** Optional anchor: only consider replies that arrive after this sent message. */
+    sinceRef?: MessageRef;
+};
+/** The human who answered. Neutral identity — no provider-specific fields. */
+export type Respondent = {
+    /** Provider-neutral respondent identifier. */
+    id: string;
+    /** Best-effort display name, when available. */
+    name?: string;
+};
+/**
+ * Result of awaiting a human reply. A discriminated union so callers must
+ * handle the timeout case explicitly instead of treating it as an error.
+ */
+export type ReplyResult = {
+    status: "answered";
+    answer: string;
+    respondent: Respondent;
+} | {
+    status: "timeout";
+};
+/**
+ * A messaging channel that can deliver a message to a human and (optionally)
+ * wait for their reply.
+ */
+export interface Channel {
+    /**
+     * Deliver a message. Returns a reference to the sent message. Does not wait
+     * for a reply — use awaitReply for that.
+     */
+    send(message: string, options?: SendOptions): Promise<MessageRef>;
+    /**
+     * Wait for the next human reply (free text or a chosen option) until the
+     * deadline. Resolves to an answered result or a timeout result; it does not
+     * throw on timeout.
+     */
+    awaitReply(options: AwaitReplyOptions): Promise<ReplyResult>;
+}

package/dist/channel.js

@@ -0,0 +1,10 @@
+/**
+ * Transport-agnostic messaging channel contract.
+ *
+ * This interface is deliberately free of any provider-specific types so that
+ * the first messaging provider is just one implementation and others (Slack,
+ * WhatsApp) can be added later without changing tool logic (R005). Tools
+ * (notify_human / ask_human) import ONLY this module — never a concrete
+ * channel's types.
+ */
+export {};

package/dist/channels/telegram.d.ts

@@ -0,0 +1,37 @@
+import type { AwaitReplyOptions, Channel, MessageRef, ReplyResult, SendOptions } from "../channel.js";
+type FetchImpl = typeof fetch;
+export type TelegramChannelConfig = {
+    botToken: string;
+    chatId: string;
+    /** Injectable for tests; defaults to the global fetch. */
+    fetchImpl?: FetchImpl;
+    /** Server-side long-poll seconds per getUpdates call. Tests use 0 for speed. */
+    longPollSeconds?: number;
+};
+/**
+ * Telegram implementation of the Channel interface using the Bot API over
+ * plain HTTPS (Node's built-in fetch). No third-party Telegram SDK.
+ *
+ * Reply capture uses getUpdates long-polling (no webhook / public URL needed).
+ * Both free-text replies (update.message) and inline-button taps
+ * (update.callback_query) resolve awaitReply. The getUpdates offset cursor is
+ * owned per instance and always advanced to update_id + 1 to avoid redelivery.
+ */
+export declare class TelegramChannel implements Channel {
+    private readonly botToken;
+    private readonly chatId;
+    private readonly fetchImpl;
+    private readonly longPollSeconds;
+    /** getUpdates cursor: next update offset to request. */
+    private offset;
+    /** Maps short callback_data tokens back to human-readable choice values. */
+    private callbackChoices;
+    constructor(config: TelegramChannelConfig);
+    /** POST a JSON body to a Bot API method. Never logs or echoes the token. */
+    private api;
+    send(message: string, options?: SendOptions): Promise<MessageRef>;
+    awaitReply(options: AwaitReplyOptions): Promise<ReplyResult>;
+    private fromConfiguredChat;
+    private respondentFrom;
+}
+export {};

package/dist/channels/telegram.js

@@ -0,0 +1,118 @@
+/**
+ * Telegram implementation of the Channel interface using the Bot API over
+ * plain HTTPS (Node's built-in fetch). No third-party Telegram SDK.
+ *
+ * Reply capture uses getUpdates long-polling (no webhook / public URL needed).
+ * Both free-text replies (update.message) and inline-button taps
+ * (update.callback_query) resolve awaitReply. The getUpdates offset cursor is
+ * owned per instance and always advanced to update_id + 1 to avoid redelivery.
+ */
+export class TelegramChannel {
+    botToken;
+    chatId;
+    fetchImpl;
+    longPollSeconds;
+    /** getUpdates cursor: next update offset to request. */
+    offset;
+    /** Maps short callback_data tokens back to human-readable choice values. */
+    callbackChoices = new Map();
+    constructor(config) {
+        this.botToken = config.botToken;
+        this.chatId = config.chatId;
+        this.fetchImpl = config.fetchImpl ?? fetch;
+        this.longPollSeconds = config.longPollSeconds ?? 30;
+    }
+    /** POST a JSON body to a Bot API method. Never logs or echoes the token. */
+    async api(method, body) {
+        const url = `https://api.telegram.org/bot${this.botToken}/${method}`;
+        const res = await this.fetchImpl(url, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(body),
+        });
+        const json = (await res.json());
+        if (!json.ok) {
+            // Reference the method, not the token, in the error.
+            throw new Error(`Telegram API ${method} failed: ${json.description ?? "unknown error"}`);
+        }
+        return json.result;
+    }
+    async send(message, options) {
+        const body = {
+            chat_id: this.chatId,
+            text: message,
+        };
+        if (options?.choices && options.choices.length > 0) {
+            // Build inline buttons. callback_data is capped at 64 bytes by Telegram,
+            // so use a short index token and map it back to the choice value.
+            this.callbackChoices.clear();
+            const row = options.choices.map((choice, i) => {
+                const token = `c${i}`;
+                this.callbackChoices.set(token, choice);
+                return { text: choice, callback_data: token };
+            });
+            body.reply_markup = { inline_keyboard: [row] };
+        }
+        const result = await this.api("sendMessage", body);
+        return { id: String(result.message_id) };
+    }
+    async awaitReply(options) {
+        const deadline = Date.now() + options.timeoutMs;
+        while (Date.now() < deadline) {
+            const remainingMs = deadline - Date.now();
+            // Don't long-poll longer than the time we have left.
+            const pollSeconds = Math.max(0, Math.min(this.longPollSeconds, Math.floor(remainingMs / 1000)));
+            const updates = await this.api("getUpdates", {
+                offset: this.offset,
+                timeout: pollSeconds,
+                allowed_updates: ["message", "callback_query"],
+            });
+            for (const update of updates) {
+                // Always advance the cursor so updates are not redelivered.
+                this.offset = update.update_id + 1;
+                // Free-text reply.
+                const msg = update.message;
+                if (msg?.text && this.fromConfiguredChat(msg.chat)) {
+                    return {
+                        status: "answered",
+                        answer: msg.text,
+                        respondent: this.respondentFrom(msg.from),
+                    };
+                }
+                // Inline-button tap.
+                const cb = update.callback_query;
+                if (cb) {
+                    // Best-effort: clear the client's loading spinner.
+                    try {
+                        await this.api("answerCallbackQuery", { callback_query_id: cb.id });
+                    }
+                    catch {
+                        // Non-fatal; the answer was still captured.
+                    }
+                    const answer = (cb.data && this.callbackChoices.get(cb.data)) ?? cb.data ?? "";
+                    if (this.fromConfiguredChat(cb.message?.chat) || cb.message == null) {
+                        return {
+                            status: "answered",
+                            answer,
+                            respondent: this.respondentFrom(cb.from),
+                        };
+                    }
+                }
+            }
+        }
+        return { status: "timeout" };
+    }
+    fromConfiguredChat(chat) {
+        if (!chat)
+            return false;
+        return String(chat.id) === this.chatId;
+    }
+    respondentFrom(user) {
+        if (!user)
+            return { id: "unknown" };
+        return {
+            id: String(user.id),
+            name: user.first_name ?? user.username,
+        };
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,54 @@
+import { z } from "zod";
+/**
+ * Persisted configuration shape. The setup wizard (S04) writes this exact
+ * structure, and the channel layer reads it. Validated with zod so malformed
+ * config fails loudly with a clear (secret-free) message.
+ */
+export declare const ConfigSchema: z.ZodObject<{
+    telegram: z.ZodObject<{
+        botToken: z.ZodString;
+        chatId: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        botToken: string;
+        chatId: string;
+    }, {
+        botToken: string;
+        chatId: string;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    telegram: {
+        botToken: string;
+        chatId: string;
+    };
+}, {
+    telegram: {
+        botToken: string;
+        chatId: string;
+    };
+}>;
+export type PingConfig = z.infer<typeof ConfigSchema>;
+/** Environment variable name pointing at an explicit config file path. */
+export declare const CONFIG_PATH_ENV = "PING_A_HUMAN_CONFIG";
+/**
+ * Default on-disk config location: ~/.config/ping-a-human/config.json.
+ * Exported so the S04 setup wizard writes to the same place loadConfig reads.
+ */
+export declare function defaultConfigPath(): string;
+export type LoadConfigOptions = {
+    /** Explicit config object — highest precedence (used by tests). */
+    config?: PingConfig;
+    /** Explicit config file path — overrides env and default. */
+    path?: string;
+    /** Environment source (defaults to process.env); injectable for tests. */
+    env?: NodeJS.ProcessEnv;
+};
+/**
+ * Resolve configuration with this precedence:
+ *   1. opts.config (explicit object)
+ *   2. env vars TELEGRAM_BOT_TOKEN + TELEGRAM_CHAT_ID (both must be present)
+ *   3. config file at opts.path -> $PING_A_HUMAN_CONFIG -> defaultConfigPath()
+ *
+ * Throws a clear, secret-free Error when configuration is missing or invalid.
+ * The bot token value is never included in any thrown message.
+ */
+export declare function loadConfig(opts?: LoadConfigOptions): PingConfig;

package/dist/config.js

@@ -0,0 +1,80 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { z } from "zod";
+/**
+ * Persisted configuration shape. The setup wizard (S04) writes this exact
+ * structure, and the channel layer reads it. Validated with zod so malformed
+ * config fails loudly with a clear (secret-free) message.
+ */
+export const ConfigSchema = z.object({
+    telegram: z.object({
+        botToken: z.string().min(1),
+        // chat ids can be large negative numbers for groups; keep as string to
+        // avoid JS number precision issues.
+        chatId: z.string().min(1),
+    }),
+});
+/** Environment variable name pointing at an explicit config file path. */
+export const CONFIG_PATH_ENV = "PING_A_HUMAN_CONFIG";
+/**
+ * Default on-disk config location: ~/.config/ping-a-human/config.json.
+ * Exported so the S04 setup wizard writes to the same place loadConfig reads.
+ */
+export function defaultConfigPath() {
+    return join(homedir(), ".config", "ping-a-human", "config.json");
+}
+/**
+ * Resolve configuration with this precedence:
+ *   1. opts.config (explicit object)
+ *   2. env vars TELEGRAM_BOT_TOKEN + TELEGRAM_CHAT_ID (both must be present)
+ *   3. config file at opts.path -> $PING_A_HUMAN_CONFIG -> defaultConfigPath()
+ *
+ * Throws a clear, secret-free Error when configuration is missing or invalid.
+ * The bot token value is never included in any thrown message.
+ */
+export function loadConfig(opts = {}) {
+    const env = opts.env ?? process.env;
+    // 1. Explicit object.
+    if (opts.config) {
+        return ConfigSchema.parse(opts.config);
+    }
+    // 2. Environment variable overrides (handy for tests and CI).
+    const envToken = env.TELEGRAM_BOT_TOKEN;
+    const envChatId = env.TELEGRAM_CHAT_ID;
+    if (envToken && envChatId) {
+        return ConfigSchema.parse({
+            telegram: { botToken: envToken, chatId: envChatId },
+        });
+    }
+    // 3. Config file.
+    const filePath = opts.path ?? env[CONFIG_PATH_ENV] ?? defaultConfigPath();
+    let raw;
+    try {
+        raw = readFileSync(filePath, "utf8");
+    }
+    catch {
+        throw new Error(`No ping-a-human configuration found. Set TELEGRAM_BOT_TOKEN and ` +
+            `TELEGRAM_CHAT_ID, or create a config file at ${filePath} ` +
+            `(run 'ping-a-human setup').`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`Config file at ${filePath} is not valid JSON.`);
+    }
+    const result = ConfigSchema.safeParse(parsed);
+    if (!result.success) {
+        // Surface which fields are wrong without echoing any values.
+        const issues = result.error.issues
+            .map((i) => i.path.join("."))
+            .filter(Boolean)
+            .join(", ");
+        throw new Error(`Config file at ${filePath} is missing or has invalid fields` +
+            (issues ? `: ${issues}` : "") +
+            `. Expected { telegram: { botToken, chatId } }.`);
+    }
+    return result.data;
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type CreateChannelOptions } from "./channel-factory.js";
+/**
+ * Build the MCP server with notify_human and ask_human registered.
+ *
+ * The Channel is resolved lazily (per tool call) via {@link createChannel} so
+ * the server still boots without configuration; a missing/invalid config
+ * surfaces as a tool error result instead of crashing at startup. Tests inject
+ * a stub Channel through `channelOptions.channel`.
+ */
+export declare function createServer(channelOptions?: CreateChannelOptions): McpServer;

package/dist/index.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import { createChannel } from "./channel-factory.js";
+import { askHuman, notifyHuman } from "./tools.js";
+import { runSetup } from "./setup.js";
+/**
+ * Build the MCP server with notify_human and ask_human registered.
+ *
+ * The Channel is resolved lazily (per tool call) via {@link createChannel} so
+ * the server still boots without configuration; a missing/invalid config
+ * surfaces as a tool error result instead of crashing at startup. Tests inject
+ * a stub Channel through `channelOptions.channel`.
+ */
+export function createServer(channelOptions = {}) {
+    const server = new McpServer({ name: "ping-a-human", version: "0.1.0" });
+    const resolveChannel = () => createChannel(channelOptions);
+    // 1.x registerTool: inputSchema is a ZodRawShape (plain object), NOT z.object(...).
+    server.registerTool("notify_human", {
+        title: "Notify human",
+        description: "Send a fire-and-forget message to the configured human (via Telegram) and return immediately without waiting for a reply.",
+        inputSchema: { message: z.string() },
+    }, async ({ message }) => notifyHuman(resolveChannel(), { message }));
+    server.registerTool("ask_human", {
+        title: "Ask human",
+        description: "Send a question to the configured human and block until they reply (or a timeout elapses). Optionally provide choices to render tappable buttons. Returns the human's answer, or a clear timed-out result.",
+        inputSchema: {
+            question: z.string(),
+            choices: z.array(z.string()).optional(),
+            timeoutMs: z.number().int().positive().optional(),
+        },
+    }, async ({ question, choices, timeoutMs }) => askHuman(resolveChannel(), { question, choices, timeoutMs }));
+    return server;
+}
+async function main() {
+    // Subcommand routing: `ping-a-human setup` runs the interactive wizard;
+    // any other invocation starts the MCP server over stdio.
+    if (process.argv[2] === "setup") {
+        const code = await runSetup();
+        process.exit(code);
+    }
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Diagnostics MUST go to stderr — stdout is the MCP JSON-RPC channel.
+    console.error("ping-a-human MCP server running on stdio");
+}
+// Only auto-start when run as the entrypoint, so tests can import createServer.
+// Resolve symlinks on both sides: when launched via the npm-installed bin,
+// process.argv[1] is the .bin symlink while import.meta.url is the real file,
+// so a naive string compare would never match and the server wouldn't start.
+function isEntrypoint() {
+    const argv1 = process.argv[1];
+    if (!argv1)
+        return false;
+    try {
+        return realpathSync(argv1) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
+}
+if (isEntrypoint()) {
+    main().catch((err) => {
+        console.error(err);
+        process.exit(1);
+    });
+}

package/dist/setup.d.ts

@@ -0,0 +1,67 @@
+import type { Readable, Writable } from "node:stream";
+import { type PingConfig } from "./config.js";
+type FetchImpl = typeof fetch;
+export type ValidateTokenResult = {
+    ok: true;
+    botUsername: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Validate a bot token by calling getMe. On success returns the bot's
+ * @username (proof the token works) — never the token itself. On failure
+ * returns a secret-free reason.
+ */
+export declare function validateToken(token: string, fetchImpl?: FetchImpl): Promise<ValidateTokenResult>;
+export type DetectChatIdResult = {
+    chatId: string;
+    fromName?: string;
+} | null;
+/**
+ * Detect the chat id by calling getUpdates and reading the most recent update
+ * that carries a chat. Returns null when there are no usable updates yet (the
+ * user must message the bot first). Reads newest-first so a fresh message wins.
+ */
+export declare function detectChatId(token: string, fetchImpl?: FetchImpl): Promise<DetectChatIdResult>;
+export type WriteConfigDeps = {
+    path?: string;
+    writeFile?: (path: string, data: string) => Promise<void>;
+    mkdir?: (path: string, opts: {
+        recursive: boolean;
+    }) => Promise<unknown>;
+};
+/**
+ * Persist config in the exact shape loadConfig reads, creating the parent dir
+ * if needed. Returns the path written. Validates against ConfigSchema first so
+ * we never write a malformed file.
+ */
+export declare function writeConfig(config: PingConfig, deps?: WriteConfigDeps): Promise<string>;
+/** The MCP client entry users paste into Claude Desktop / Cursor config. */
+export declare function mcpClientEntry(): {
+    command: string;
+    args: string[];
+};
+/** A ready-to-paste mcpServers JSON snippet for the MCP client config. */
+export declare function mcpClientEntrySnippet(): string;
+export type RunSetupDeps = {
+    /** Where prompts are read from (defaults to process.stdin). */
+    input?: Readable;
+    /** Where prompts/diagnostics are written (defaults to process.stderr). */
+    output?: Writable;
+    fetchImpl?: FetchImpl;
+    writeConfigDeps?: WriteConfigDeps;
+    /** Attempts to detect the chat id after the user messages the bot. */
+    detectAttempts?: number;
+    /** Delay (ms) between chat-id detection attempts. */
+    detectDelayMs?: number;
+    /** Sleep impl (injectable for tests). */
+    sleep?: (ms: number) => Promise<void>;
+};
+/**
+ * Interactive setup wizard. Returns a process exit code (0 success, non-zero
+ * failure). All prompts/diagnostics go to `output` (stderr by default); the bot
+ * token is never written back to output.
+ */
+export declare function runSetup(deps?: RunSetupDeps): Promise<number>;
+export {};

package/dist/setup.js

@@ -0,0 +1,198 @@
+import { mkdir as fsMkdir, writeFile as fsWriteFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import * as readline from "node:readline/promises";
+import { stdin as processStdin } from "node:process";
+import { ConfigSchema, defaultConfigPath, } from "./config.js";
+const API_BASE = "https://api.telegram.org";
+/** POST a JSON body to a Bot API method. Never includes the token in errors. */
+async function callApi(token, method, body, fetchImpl) {
+    const res = await fetchImpl(`${API_BASE}/bot${token}/${method}`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body ?? {}),
+    });
+    return (await res.json());
+}
+/**
+ * Validate a bot token by calling getMe. On success returns the bot's
+ * @username (proof the token works) — never the token itself. On failure
+ * returns a secret-free reason.
+ */
+export async function validateToken(token, fetchImpl = fetch) {
+    let resp;
+    try {
+        resp = await callApi(token, "getMe", {}, fetchImpl);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            reason: `Could not reach Telegram: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    if (!resp.ok || !resp.result) {
+        return {
+            ok: false,
+            reason: resp.description ??
+                "Telegram rejected the token (getMe failed). Double-check the token from BotFather.",
+        };
+    }
+    return { ok: true, botUsername: resp.result.username ?? "(unknown)" };
+}
+/** Pull the chat id + best-effort name out of a single update. */
+function chatFromUpdate(u) {
+    const msg = u.message ?? u.edited_message ?? u.channel_post;
+    if (msg?.chat) {
+        return { chatId: String(msg.chat.id), fromName: nameOf(msg) };
+    }
+    const cbMsg = u.callback_query?.message;
+    if (cbMsg?.chat) {
+        return {
+            chatId: String(cbMsg.chat.id),
+            fromName: u.callback_query?.from?.first_name ?? u.callback_query?.from?.username,
+        };
+    }
+    return null;
+}
+function nameOf(msg) {
+    return (msg.from?.first_name ??
+        msg.from?.username ??
+        msg.chat?.title ??
+        msg.chat?.username);
+}
+/**
+ * Detect the chat id by calling getUpdates and reading the most recent update
+ * that carries a chat. Returns null when there are no usable updates yet (the
+ * user must message the bot first). Reads newest-first so a fresh message wins.
+ */
+export async function detectChatId(token, fetchImpl = fetch) {
+    let resp;
+    try {
+        resp = await callApi(token, "getUpdates", { timeout: 0 }, fetchImpl);
+    }
+    catch {
+        return null;
+    }
+    const updates = resp.ok && resp.result ? resp.result : [];
+    for (let i = updates.length - 1; i >= 0; i--) {
+        const found = chatFromUpdate(updates[i]);
+        if (found)
+            return found;
+    }
+    return null;
+}
+/**
+ * Persist config in the exact shape loadConfig reads, creating the parent dir
+ * if needed. Returns the path written. Validates against ConfigSchema first so
+ * we never write a malformed file.
+ */
+export async function writeConfig(config, deps = {}) {
+    const valid = ConfigSchema.parse(config);
+    const path = deps.path ?? defaultConfigPath();
+    const mkdir = deps.mkdir ?? ((p, o) => fsMkdir(p, o));
+    const writeFile = deps.writeFile ?? ((p, d) => fsWriteFile(p, d, "utf8"));
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, JSON.stringify(valid, null, 2) + "\n");
+    return path;
+}
+/** The MCP client entry users paste into Claude Desktop / Cursor config. */
+export function mcpClientEntry() {
+    return { command: "npx", args: ["-y", "ping-a-human"] };
+}
+/** A ready-to-paste mcpServers JSON snippet for the MCP client config. */
+export function mcpClientEntrySnippet() {
+    return JSON.stringify({ mcpServers: { "ping-a-human": mcpClientEntry() } }, null, 2);
+}
+const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Interactive setup wizard. Returns a process exit code (0 success, non-zero
+ * failure). All prompts/diagnostics go to `output` (stderr by default); the bot
+ * token is never written back to output.
+ */
+export async function runSetup(deps = {}) {
+    const input = deps.input ?? processStdin;
+    // Default prompts to stderr so this stays consistent with the stdout-is-MCP
+    // rule, even though setup is a separate invocation.
+    const output = deps.output ?? process.stderr;
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const detectAttempts = deps.detectAttempts ?? 10;
+    const detectDelayMs = deps.detectDelayMs ?? 2000;
+    const sleep = deps.sleep ?? defaultSleep;
+    const rl = readline.createInterface({ input, output });
+    const log = (s) => output.write(s + "\n");
+    // Prompt wrapper that tolerates a closed/EOF'd input stream (e.g. piped or
+    // non-interactive runs) by returning empty instead of throwing
+    // ERR_USE_AFTER_CLOSE, so the loops fall through to their abort messages.
+    const ask = async (q) => {
+        try {
+            return await rl.question(q);
+        }
+        catch (err) {
+            if (err?.code === "ERR_USE_AFTER_CLOSE")
+                return "";
+            throw err;
+        }
+    };
+    try {
+        log("ping-a-human setup");
+        log("");
+        log("1. In Telegram, message @BotFather, send /newbot, and follow the prompts.");
+        log("2. Copy the bot token it gives you (looks like 123456:ABC-...).");
+        log("");
+        let token = "";
+        let botUsername = "";
+        for (let i = 0; i < 3; i++) {
+            token = (await ask("Paste your bot token: ")).trim();
+            if (!token) {
+                log("No token entered.");
+                continue;
+            }
+            const v = await validateToken(token, fetchImpl);
+            if (v.ok) {
+                botUsername = v.botUsername;
+                break;
+            }
+            log(`Token rejected: ${v.reason}`);
+            token = "";
+        }
+        if (!token) {
+            log("Could not validate a bot token after 3 attempts. Aborting.");
+            return 1;
+        }
+        log(`Token OK — bot is @${botUsername}.`);
+        log("");
+        log(`3. Open Telegram, find @${botUsername}, and send it any message (e.g. \"hi\").`);
+        await ask("   Press Enter once you've sent a message to the bot... ");
+        let detected = null;
+        for (let attempt = 1; attempt <= detectAttempts; attempt++) {
+            detected = await detectChatId(token, fetchImpl);
+            if (detected)
+                break;
+            if (attempt < detectAttempts) {
+                log(`   No message seen yet (attempt ${attempt}/${detectAttempts}); retrying...`);
+                await sleep(detectDelayMs);
+            }
+        }
+        if (!detected) {
+            log("");
+            log("Could not detect your chat. Make sure you sent a message to the bot,");
+            log("then run 'ping-a-human setup' again.");
+            return 1;
+        }
+        log(`Detected chat${detected.fromName ? ` from ${detected.fromName}` : ""} (id ${detected.chatId}).`);
+        const config = {
+            telegram: { botToken: token, chatId: detected.chatId },
+        };
+        const savedPath = await writeConfig(config, deps.writeConfigDeps);
+        log(`Saved config to ${savedPath}`);
+        log("");
+        log("4. Add this to your MCP client config (Claude Desktop / Cursor):");
+        log("");
+        log(mcpClientEntrySnippet());
+        log("");
+        log("Done. notify_human and ask_human are ready to use.");
+        return 0;
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/tools.d.ts

@@ -0,0 +1,33 @@
+import type { Channel } from "./channel.js";
+/**
+ * Shape of an MCP tool result we return. Mirrors the structure the MCP SDK
+ * expects from a registerTool handler ({ content: [...] }), kept local so these
+ * handlers are pure and unit-testable without the SDK.
+ */
+export type ToolResult = {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+};
+/**
+ * notify_human: fire-and-forget. Deliver a message to the human channel and
+ * return immediately without awaiting any reply (R001).
+ */
+export declare function notifyHuman(channel: Channel, args: {
+    message: string;
+}): Promise<ToolResult>;
+export type AskHumanArgs = {
+    question: string;
+    choices?: string[];
+    /** Reply deadline in ms. Defaults to 5 minutes. */
+    timeoutMs?: number;
+};
+/**
+ * ask_human: deliver a question (optionally with tappable choices), block until
+ * the human replies or the deadline elapses, then return the answer + who
+ * answered (R002), or a clear timed-out result (R002). Choices render as inline
+ * buttons and the tapped value is returned (R003).
+ */
+export declare function askHuman(channel: Channel, args: AskHumanArgs): Promise<ToolResult>;

package/dist/tools.js

@@ -0,0 +1,50 @@
+function text(t, isError = false) {
+    return { content: [{ type: "text", text: t }], ...(isError ? { isError } : {}) };
+}
+/**
+ * notify_human: fire-and-forget. Deliver a message to the human channel and
+ * return immediately without awaiting any reply (R001).
+ */
+export async function notifyHuman(channel, args) {
+    try {
+        const ref = await channel.send(args.message);
+        return text(`Message delivered to human (ref: ${ref.id}).`);
+    }
+    catch (err) {
+        return text(`Failed to notify human: ${errMessage(err)}`, true);
+    }
+}
+const DEFAULT_ASK_TIMEOUT_MS = 5 * 60 * 1000;
+/**
+ * ask_human: deliver a question (optionally with tappable choices), block until
+ * the human replies or the deadline elapses, then return the answer + who
+ * answered (R002), or a clear timed-out result (R002). Choices render as inline
+ * buttons and the tapped value is returned (R003).
+ */
+export async function askHuman(channel, args) {
+    const timeoutMs = args.timeoutMs ?? DEFAULT_ASK_TIMEOUT_MS;
+    let ref;
+    try {
+        ref = await channel.send(args.question, { choices: args.choices });
+    }
+    catch (err) {
+        return text(`Failed to ask human: ${errMessage(err)}`, true);
+    }
+    let reply;
+    try {
+        reply = await channel.awaitReply({ timeoutMs, sinceRef: ref });
+    }
+    catch (err) {
+        return text(`Failed while awaiting human reply: ${errMessage(err)}`, true);
+    }
+    if (reply.status === "timeout") {
+        return text(`Timed out after ${timeoutMs}ms waiting for the human to reply. No answer was received.`);
+    }
+    const who = reply.respondent.name
+        ? `${reply.respondent.name} (${reply.respondent.id})`
+        : reply.respondent.id;
+    return text(`Human (${who}) answered: ${reply.answer}`);
+}
+function errMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "ping-a-human",
+  "version": "0.1.0",
+  "description": "An MCP server that adds a human-in-the-loop step to any AI pipeline by reaching a human on their own messaging app (Telegram first).",
+  "type": "module",
+  "bin": {
+    "ping-a-human": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "test": "node --test 'tests/*.test.mjs'",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "human-in-the-loop",
+    "telegram",
+    "ai",
+    "agent",
+    "notification"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/startriseio/ping-a-human.git"
+  },
+  "homepage": "https://github.com/startriseio/ping-a-human#readme",
+  "bugs": {
+    "url": "https://github.com/startriseio/ping-a-human/issues"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  }
+}