@askingahuman/mcp-server 1.0.0 → 2.0.1

package/dist/tools/live.js

@@ -0,0 +1,380 @@
+import { ApiError, apiErrorText, callApi, dollars, errorResult, textResult } from '../context.js';
+import { LiveChatError } from '../live/bridge.js';
+import { UNTRUSTED_NOTE, checkOutgoing, untrusted } from '../safety.js';
+import { blockPrice, describeQuote, fetchQuote, humanIdFrom, HUMAN_ID_REQUIRED, spendLimitCents } from './discover.js';
+const SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export const MAX_CHAT_CHARS = 1000;
+const MAX_WAIT_SECONDS = 50;
+const POLL_MS = 3000;
+// Below this much paid time left, tools warn and point to extend_session.
+export const LOW_TIME_MS = 10 * 60_000;
+function sessionIdFrom(args) {
+    const id = args?.session_id;
+    return typeof id === 'string' && SESSION_ID.test(id) ? id : null;
+}
+function waitSeconds(args, fallback) {
+    const n = Number(args?.wait_seconds);
+    return Math.min(MAX_WAIT_SECONDS, Math.max(0, Number.isFinite(n) ? n : fallback));
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+// Asks the client's user to approve a charge. Returns a result to stop with,
+// or null to go ahead.
+async function approve(ctx, message, what) {
+    if (ctx.config.skipApproval && !ctx.config.requireConfirmation)
+        return null;
+    const decision = await ctx.confirm(message);
+    if (decision === 'declined')
+        return textResult(`The user declined the cost, so ${what} and nothing was charged.`);
+    if (decision === 'cancelled') {
+        return textResult(`The cost approval was closed without an answer, or this client did not show it, so ${what} and nothing was charged. ` +
+            'If the approval form never appeared, whoever runs this MCP server can set ASKINGAHUMAN_SKIP_APPROVAL=true ' +
+            '(the spend limit still applies).');
+    }
+    if (decision === 'unsupported' && ctx.config.requireConfirmation) {
+        return errorResult(`Not done: this MCP server requires the user to approve each charge, and this client cannot show a confirmation, so ${what}.`);
+    }
+    return null;
+}
+// "Paid time left: 42 min (until 14:05 UTC)." plus a low-time warning, from
+// GET /api/connect/{id}. Empty before the person accepts.
+export function paidTimeNote(data, now = Date.now()) {
+    if (typeof data.endsAt !== 'string')
+        return '';
+    const endsAt = new Date(data.endsAt);
+    if (Number.isNaN(endsAt.getTime()))
+        return '';
+    const leftMs = endsAt.getTime() - now;
+    const until = `${endsAt.toISOString().slice(11, 16)} UTC`;
+    if (leftMs <= 0)
+        return `The paid time ran out at ${until}.`;
+    let note = `Paid time left: ${Math.ceil(leftMs / 60_000)} min (until ${until}).`;
+    if (leftMs < LOW_TIME_MS) {
+        note += data.canExtend
+            ? ` Less than 10 minutes left: call extend_session to add another ${blockSpan(data.blockMinutes)} if you need it.`
+            : ' Less than 10 minutes left, and this chat is at its time or spend limit, so it cannot be extended.';
+    }
+    return note;
+}
+function blockSpan(blockMinutes) {
+    return Number(blockMinutes) === 60 ? 'hour' : `${blockMinutes ?? '?'} minutes`;
+}
+export const connectHumanTool = {
+    name: 'connect_human',
+    description: 'Request a PAID live text chat with a specific person (human_id). Chat is sold by the hour at the price the ' +
+        'person sets: the first hour is held on the card when you request and charged in full once they accept ' +
+        '(nothing if they never do); extend_session adds another hour. Ending early does not refund paid time. ' +
+        'If the person is offline, the request waits up to 24 hours for them. Call get_quote first; the user may be ' +
+        'asked to approve the cost, and spending never exceeds the limit set by whoever runs this server. All sales ' +
+        'are final. Then call check_connection to wait for the person to accept; you join the chat automatically.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            human_id: { type: 'string', description: 'The person to chat with (humanId from list_humans or who_is_live).' },
+            message: {
+                type: 'string',
+                description: 'What you need help with, shown to the person before they accept (max 500 characters). No links or credentials.',
+                maxLength: 500,
+            },
+            max_spend_usd: {
+                type: 'number',
+                description: 'Optional: the most to spend on the whole chat, extensions included, in US dollars.',
+            },
+        },
+        required: ['human_id', 'message'],
+    },
+};
+export async function handleConnectHuman(args, ctx) {
+    if (!ctx.live) {
+        return errorResult('Live chat is not available on the hosted MCP server. Run the local server (npx -y @askingahuman/mcp-server) to chat live, or use ask_human.');
+    }
+    if (!(await ctx.live.isAvailable())) {
+        return errorResult('Live chat needs the optional package @livekit/rtc-node, which is not installed here. Use ask_human instead, ' +
+            'or reinstall @askingahuman/mcp-server with optional dependencies enabled.');
+    }
+    const humanId = humanIdFrom(args);
+    if (!humanId)
+        return errorResult(HUMAN_ID_REQUIRED);
+    const message = checkOutgoing(args?.message, { apiKey: ctx.apiKey, maxChars: 500 });
+    if (!message.ok)
+        return errorResult(message.reason);
+    // Price first, so the person running the agent approves the actual cost.
+    const quoted = await fetchQuote(args, ctx);
+    if (!quoted.ok)
+        return quoted.result;
+    const quote = quoted.quote;
+    if (!quote.bookable || quote.paymentReady === false)
+        return textResult(describeQuote(quote));
+    const stop = await approve(ctx, `Your AI agent wants to request a paid live chat on askingahuman.\n\n${describeQuote(quote)}\n\nApprove this chat?`, 'no chat was requested');
+    if (stop)
+        return stop;
+    const body = { mode: 'message', humanId, message: message.text, maxSpendCents: spendLimitCents(args, ctx) };
+    try {
+        const res = await callApi(ctx, '/api/connect', { method: 'POST', body });
+        if (res.status === 404)
+            return errorResult('No such person. Use list_humans or who_is_live to find someone.');
+        if (res.status === 409) {
+            // HUMAN_OFFLINE, OVER_SPEND_LIMIT, or the person doesn't take chats.
+            const why = typeof res.data.message === 'string' ? res.data.message : apiErrorText(res, 'Not available');
+            return textResult(`Not started: ${why}${/charged/i.test(why) ? '' : ' Nothing was charged.'}`);
+        }
+        if (res.status === 402) {
+            return errorResult('Payment required: add a card at https://askingahuman.com/developers, then try again. Nothing was charged.');
+        }
+        if (!res.ok)
+            return errorResult(`${apiErrorText(res, 'Failed to request a chat')}. Manage your key at https://askingahuman.com/developers`);
+        const sessionId = String(res.data.sessionId);
+        ctx.live.trackRequest(sessionId);
+        const human = (res.data.human || {});
+        const waits = typeof res.data.waitsUntil === 'string' ? ` (until ${res.data.waitsUntil})` : '';
+        return textResult(`Chat requested. The person has been notified${human.live ? '' : ` and the request waits for them up to 24 hours${waits}`}.\n` +
+            `Session ID: ${sessionId}\n` +
+            `Price: ${blockPrice(res.data.pricing, 'message')}; ${dollars(res.data.holdAmountCents)} held now, charged in full once they accept.\n\n` +
+            `Next: call check_connection with session_id "${sessionId}" and wait_seconds 45 until they accept. ` +
+            `To cancel before they accept, call end_session (the hold is released).`);
+    }
+    catch (err) {
+        return errorResult(err instanceof ApiError ? err.message : 'Failed to request a chat.');
+    }
+}
+export const checkConnectionTool = {
+    name: 'check_connection',
+    description: 'Check a live chat requested with connect_human, optionally waiting up to 50 seconds for the person to accept. ' +
+        'When they accept you join the chat automatically; then use read_messages and send_message. ' +
+        'Shows how much paid time is left. When the session has ended, shows the amount charged.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            session_id: { type: 'string', description: 'The Session ID from connect_human.' },
+            wait_seconds: { type: 'number', description: 'Wait up to this many seconds (0-50) for the person to accept. Default 0.' },
+        },
+        required: ['session_id'],
+    },
+};
+export async function handleCheckConnection(args, ctx) {
+    const sessionId = sessionIdFrom(args);
+    if (!sessionId)
+        return errorResult('Error: session_id must be the Session ID returned by connect_human.');
+    const deadline = Date.now() + waitSeconds(args, 0) * 1000;
+    try {
+        let res = await callApi(ctx, `/api/connect/${sessionId}`);
+        while (res.ok && res.data.status === 'REQUESTED' && Date.now() + POLL_MS < deadline) {
+            await sleep(POLL_MS);
+            res = await callApi(ctx, `/api/connect/${sessionId}`);
+        }
+        if (!res.ok)
+            return errorResult(apiErrorText(res, 'Failed to check the session'));
+        const status = String(res.data.status);
+        if (status === 'REQUESTED') {
+            return textResult('Still waiting for the person to accept. Call check_connection again with wait_seconds 45. ' +
+                'Nothing is charged unless they accept; call end_session to cancel and release the hold.');
+        }
+        if (status === 'ENDED')
+            return textResult(`The session has ended. ${chargedText(res.data.amountCents)}`);
+        if (status === 'ACCEPTED' || status === 'ACTIVE') {
+            if (!ctx.live)
+                return errorResult('Live chat is not available on the hosted MCP server.');
+            if (typeof res.data.url !== 'string' || typeof res.data.token !== 'string') {
+                return errorResult('The session is ready but the join details are missing. Try check_connection again.');
+            }
+            // The join token stays inside this server; it is never shown to the model.
+            const joined = await ctx.live.join(sessionId, res.data.url, res.data.token);
+            const time = paidTimeNote(res.data);
+            return textResult(`${joined === 'joined' ? 'You joined the live chat.' : 'You are in the live chat.'} ` +
+                `Use read_messages (with wait_seconds) to hear from the person and send_message to reply.` +
+                (time ? `
+${time}` : '') +
+                `
+The chat ends when the paid time runs out; extend_session adds time. Call end_session when you are done ` +
+                `(paid time is not refunded).`);
+        }
+        return textResult(`The session is ${status.toLowerCase()} (no charge). Try connect_human again later, or ask_human.`);
+    }
+    catch (err) {
+        if (err instanceof ApiError || err instanceof LiveChatError) {
+            return errorResult(`${err.message} Try check_connection again in a moment.`);
+        }
+        return errorResult('Failed to check the session.');
+    }
+}
+export const sendMessageTool = {
+    name: 'send_message',
+    description: 'Send a chat message to the person in a live session you have joined. Plain text only, up to 1000 characters; ' +
+        'links and credentials are blocked.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            session_id: { type: 'string', description: 'The Session ID.' },
+            text: { type: 'string', description: 'Your message (max 1000 characters).' },
+        },
+        required: ['session_id', 'text'],
+    },
+};
+export async function handleSendMessage(args, ctx) {
+    const sessionId = sessionIdFrom(args);
+    if (!sessionId)
+        return errorResult('Error: session_id must be the Session ID returned by connect_human.');
+    if (!ctx.live)
+        return errorResult('Live chat is not available on the hosted MCP server.');
+    const text = checkOutgoing(args?.text, { apiKey: ctx.apiKey, maxChars: MAX_CHAT_CHARS, field: 'text' });
+    if (!text.ok)
+        return errorResult(text.reason);
+    try {
+        await ctx.live.send(sessionId, text.text);
+        return textResult('Sent. Use read_messages with wait_seconds to wait for the reply.');
+    }
+    catch (err) {
+        return errorResult(err instanceof LiveChatError ? err.message : 'Failed to send the message.');
+    }
+}
+export const readMessagesTool = {
+    name: 'read_messages',
+    description: 'Read new messages from the person in a live session, waiting up to 50 seconds for one to arrive. ' +
+        'Returns only messages you have not read yet, plus notices such as the person leaving or the chat ending, ' +
+        'and how much paid time is left.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            session_id: { type: 'string', description: 'The Session ID.' },
+            wait_seconds: { type: 'number', description: 'Wait up to this many seconds (0-50) for a new message. Default 30.' },
+        },
+        required: ['session_id'],
+    },
+};
+// Best effort: a failed status check never hides the messages.
+async function paidTimeFor(ctx, sessionId) {
+    try {
+        const res = await callApi(ctx, `/api/connect/${sessionId}`, { timeoutMs: 10_000 });
+        return res.ok ? paidTimeNote(res.data) : '';
+    }
+    catch {
+        return '';
+    }
+}
+function chargedText(amountCents) {
+    return Number(amountCents) > 0 ? `Charged ${dollars(amountCents)}.` : 'Nothing was charged; any hold is released.';
+}
+function formatLines(lines) {
+    return lines
+        .map((l) => (l.from === 'human' ? untrusted(l.text, `at="${l.at}"`) : `[${l.at}] Notice: ${l.text}`))
+        .join('\n');
+}
+export async function handleReadMessages(args, ctx) {
+    const sessionId = sessionIdFrom(args);
+    if (!sessionId)
+        return errorResult('Error: session_id must be the Session ID returned by connect_human.');
+    if (!ctx.live)
+        return errorResult('Live chat is not available on the hosted MCP server.');
+    try {
+        const { lines, closed, humanPresent } = await ctx.live.read(sessionId, waitSeconds(args, 30) * 1000);
+        if (lines.length === 0) {
+            if (closed)
+                return textResult('The chat has ended. Use check_connection to see what was charged.');
+            const time = await paidTimeFor(ctx, sessionId);
+            return textResult((humanPresent
+                ? 'No new messages yet. Call read_messages again to keep waiting, or send_message.'
+                : 'No new messages, and the person is not in the chat right now. Call read_messages again to keep waiting.') +
+                (time ? `\n${time}` : ''));
+        }
+        const time = closed ? '' : await paidTimeFor(ctx, sessionId);
+        const footer = closed
+            ? '\n\nThe chat has ended. Use check_connection to see what was charged.'
+            : `\n\nReply with send_message, or call end_session when you are done.${time ? `\n${time}` : ''}`;
+        return textResult(`${UNTRUSTED_NOTE}\n\n${formatLines(lines)}${footer}`);
+    }
+    catch (err) {
+        return errorResult(err instanceof LiveChatError ? err.message : 'Failed to read messages.');
+    }
+}
+export const endSessionTool = {
+    name: 'end_session',
+    description: 'End a live session and leave the chat. A request the person has not accepted yet is cancelled and its hold ' +
+        'released. Once they accepted, every hour bought is charged in full, so ending early does not refund paid time. ' +
+        'Call this when you are done.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            session_id: { type: 'string', description: 'The Session ID.' },
+        },
+        required: ['session_id'],
+    },
+};
+export async function endSessionViaApi(ctx, sessionId) {
+    const res = await callApi(ctx, `/api/connect/${sessionId}/end`, { method: 'POST', body: {} });
+    if (!res.ok && res.status !== 404 && res.status !== 409) {
+        throw new ApiError(apiErrorText(res, 'Failed to end the session'));
+    }
+}
+export async function handleEndSession(args, ctx) {
+    const sessionId = sessionIdFrom(args);
+    if (!sessionId)
+        return errorResult('Error: session_id must be the Session ID returned by connect_human.');
+    try {
+        if (ctx.live)
+            await ctx.live.end(sessionId);
+        else
+            await endSessionViaApi(ctx, sessionId);
+        const res = await callApi(ctx, `/api/connect/${sessionId}`);
+        if (res.ok && res.data.status === 'ENDED')
+            return textResult(`Session ended. ${chargedText(res.data.amountCents)}`);
+        return textResult('Session ended. Use check_connection in a moment to see the final charge.');
+    }
+    catch (err) {
+        return errorResult(err instanceof ApiError ? err.message : 'Failed to end the session. Try again.');
+    }
+}
+export const extendSessionTool = {
+    name: 'extend_session',
+    description: 'Add one more paid block (an hour of chat) to a live chat that has started, charged in full right away to the ' +
+        'same card or balance. The user may be asked to approve the cost. Limited by the session\'s time and spend ' +
+        'limits. Use it when check_connection or read_messages says paid time is running low and you still need the person.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            session_id: { type: 'string', description: 'The Session ID.' },
+        },
+        required: ['session_id'],
+    },
+};
+export async function handleExtendSession(args, ctx) {
+    const sessionId = sessionIdFrom(args);
+    if (!sessionId)
+        return errorResult('Error: session_id must be the Session ID returned by connect_human.');
+    try {
+        const current = await callApi(ctx, `/api/connect/${sessionId}`);
+        if (current.status === 404)
+            return errorResult('No such session.');
+        if (!current.ok)
+            return errorResult(apiErrorText(current, 'Failed to check the session'));
+        const data = current.data;
+        if (data.status === 'REQUESTED')
+            return textResult('The person has not accepted yet; extend once the chat has started.');
+        if (data.status !== 'ACCEPTED' && data.status !== 'ACTIVE')
+            return textResult('This session has ended, so it cannot be extended.');
+        if (!data.canExtend) {
+            return textResult(`This chat is at its time or spend limit, so it cannot be extended. ${paidTimeNote(data)}`.trim());
+        }
+        const pricing = (data.pricing || {});
+        const blocks = Number(data.blocksPurchased ?? 1);
+        const stop = await approve(ctx, `Your AI agent wants to extend a live chat on askingahuman by one more ${blockSpan(data.blockMinutes)}.\n\n` +
+            `Cost: ${dollars(pricing.blockPriceCents)}, charged in full now. Session total: ${dollars((blocks + 1) * Number(pricing.blockPriceCents))}.\n` +
+            `All sales are final.\n\nApprove this extension?`, 'the chat was not extended');
+        if (stop)
+            return stop;
+        const res = await callApi(ctx, `/api/connect/${sessionId}/extend`, { method: 'POST', body: {} });
+        if (res.status === 402) {
+            return errorResult('Payment required: the extra hour could not be authorized on the card or balance. The chat was not extended.');
+        }
+        if (res.status === 409) {
+            const why = typeof res.data.message === 'string' ? res.data.message : apiErrorText(res, 'Cannot extend');
+            return textResult(`Not extended: ${why}`);
+        }
+        if (!res.ok)
+            return errorResult(apiErrorText(res, 'Failed to extend the session'));
+        const endsAt = typeof res.data.endsAt === 'string' ? `${res.data.endsAt.slice(11, 16)} UTC (${res.data.endsAt})` : 'unknown';
+        return textResult(`Extended by one ${blockSpan(res.data.blockMinutes)}. Paid time now runs until ${endsAt}.\n` +
+            `Session total so far: ${dollars(res.data.totalCents)} (${res.data.blocksPurchased} of up to ${res.data.maxBlocks} blocks).`);
+    }
+    catch (err) {
+        return errorResult(err instanceof ApiError ? err.message : 'Failed to extend the session.');
+    }
+}

package/dist/tools/reply-to-human.d.ts

@@ -0,0 +1,14 @@
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+export declare const replyToHumanTool: Tool;
+export declare function handleReplyToHuman(args: Record<string, unknown> | undefined, apiKey: string, apiBase: string): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/dist/tools/reply-to-human.js

@@ -0,0 +1,72 @@
+import { checkOutgoing } from '../safety.js';
+const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const MAX_REPLY_CHARS = 2000;
+export const replyToHumanTool = {
+    name: 'reply_to_human',
+    description: 'Continue the conversation with the human who answered your question at askingahuman.com: ' +
+        'ask a follow-up, clarify, or say thanks. Only works after the question is answered. ' +
+        'The human is notified on their phone. Use check_answer to read their response.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            question_id: {
+                type: 'string',
+                description: 'The questionId returned by ask_human (the answered question).',
+            },
+            message: {
+                type: 'string',
+                description: `Your message to the human (max ${MAX_REPLY_CHARS} characters).`,
+            },
+        },
+        required: ['question_id', 'message'],
+    },
+};
+function errorResult(text) {
+    return { content: [{ type: 'text', text }], isError: true };
+}
+export async function handleReplyToHuman(args, apiKey, apiBase) {
+    const questionId = args?.question_id;
+    if (typeof questionId !== 'string' || !UUID_REGEX.test(questionId)) {
+        return errorResult('Error: question_id must be the exact questionId (a UUID) returned by ask_human.');
+    }
+    const checked = checkOutgoing(args?.message, { apiKey, maxChars: MAX_REPLY_CHARS });
+    if (!checked.ok) {
+        return errorResult(checked.reason === 'message is empty.' ? 'Error: message is required.' : `Error: ${checked.reason}`);
+    }
+    const message = checked.text;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 30_000);
+    try {
+        const response = await fetch(`${apiBase}/api/questions/${questionId}/replies`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${apiKey}` },
+            body: JSON.stringify({ text: message }),
+            signal: controller.signal,
+        });
+        const data = (await response.json().catch(() => ({})));
+        if (!response.ok) {
+            if (response.status === 400 && String(data.error).includes('answered')) {
+                return errorResult('The human has not answered this question yet, so there is no conversation to reply to. Use check_answer to wait for the answer.');
+            }
+            return errorResult(`Error (${response.status}): ${data.error || 'Failed to send reply'}`);
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Reply sent to the human (they are notified).\n\n` +
+                        `Use check_answer with question_id "${questionId}" to see their response.`,
+                },
+            ],
+        };
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === 'AbortError') {
+            return errorResult('Request timed out after 30 seconds. Please try again.');
+        }
+        return errorResult(`Network error: ${err instanceof Error ? err.message : 'Unknown error'}.`);
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}

package/dist/tools/submit-feedback.d.ts

@@ -0,0 +1,15 @@
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+export declare const submitFeedbackTool: Tool;
+export declare function handleSubmitFeedback(args: Record<string, unknown> | undefined, apiKey: string, apiBase: string): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: undefined;
+}>;

package/dist/tools/submit-feedback.js

@@ -0,0 +1,77 @@
+export const submitFeedbackTool = {
+    name: 'submit_feedback',
+    description: 'Submit feedback about the askingahuman.com MCP server or service. ' +
+        'Use this to report issues, suggest improvements, or provide general feedback from an AI agent.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            feedback: {
+                type: 'string',
+                description: 'The feedback message. Be specific and detailed.',
+            },
+            contact_email: {
+                type: 'string',
+                description: 'Optional email address for follow-up.',
+            },
+        },
+        required: ['feedback'],
+    },
+};
+export async function handleSubmitFeedback(args, apiKey, apiBase) {
+    if (!args?.feedback || typeof args.feedback !== 'string') {
+        return {
+            content: [{ type: 'text', text: 'Error: The feedback parameter is required.' }],
+            isError: true,
+        };
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 30_000);
+    try {
+        const response = await fetch(`${apiBase}/api/feedback`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                feedback: args.feedback,
+                contactEmail: typeof args.contact_email === 'string' ? args.contact_email : undefined,
+            }),
+            signal: controller.signal,
+        });
+        const data = (await response.json());
+        if (!response.ok) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error (${response.status}): ${data.error || 'Failed to submit feedback'}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Feedback submitted successfully. Thank you!`,
+                },
+            ],
+        };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Network error: ${err instanceof Error ? err.message : 'Unknown error'}.`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}

package/dist/tools/who-is-live.d.ts

@@ -0,0 +1,4 @@
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { ToolContext, ToolResult } from '../context.js';
+export declare const whoIsLiveTool: Tool;
+export declare function handleWhoIsLive(args: Record<string, unknown> | undefined, ctx: ToolContext): Promise<ToolResult>;

package/dist/tools/who-is-live.js

@@ -0,0 +1,53 @@
+import { ApiError, apiErrorText, callApi, errorResult, textResult } from '../context.js';
+import { cleanIncoming } from '../safety.js';
+const MAX_WAIT_SECONDS = 50;
+const POLL_MS = 5000;
+export const whoIsLiveTool = {
+    name: 'who_is_live',
+    description: 'See which people are live right now and can take a live chat. Free; nobody is notified. ' +
+        'Set wait_seconds to wait (up to 50 seconds) for someone to come online. ' +
+        'Use get_quote with a humanId to see their price before connect_human.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            specialization: { type: 'string', description: 'Optional: only people with this specialization.', maxLength: 100 },
+            wait_seconds: { type: 'number', description: 'Wait up to this many seconds (0-50) for someone to be live. Default 0.' },
+        },
+    },
+};
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export async function handleWhoIsLive(args, ctx) {
+    const query = new URLSearchParams();
+    if (typeof args?.specialization === 'string' && args.specialization.trim()) {
+        query.set('specialization', args.specialization.trim().slice(0, 100));
+    }
+    const wait = Math.min(MAX_WAIT_SECONDS, Math.max(0, Number(args?.wait_seconds) || 0));
+    const deadline = Date.now() + wait * 1000;
+    const qs = query.toString();
+    const path = `/api/live-now${qs ? `?${qs}` : ''}`;
+    try {
+        let res = await callApi(ctx, path);
+        while (res.ok && Number(res.data.count) === 0 && Date.now() + POLL_MS < deadline) {
+            await sleep(POLL_MS);
+            res = await callApi(ctx, path);
+        }
+        if (!res.ok)
+            return errorResult(apiErrorText(res, 'Failed to check who is live'));
+        const humans = res.data.humans || [];
+        if (humans.length === 0) {
+            return textResult(wait > 0
+                ? `Nobody came online in the last ${Math.round(wait)} seconds. A chat request (connect_human) waits up to 24 hours for an offline person, or ask_human sends them a free question.`
+                : 'Nobody is live right now. A chat request (connect_human) waits up to 24 hours for an offline person, or ask_human sends them a free question. Find people with list_humans.');
+        }
+        const short = (v, n) => cleanIncoming(String(v ?? ''), n).replace(/\s+/g, ' ').trim();
+        const lines = humans.map((h) => {
+            const specs = Array.isArray(h.specializations) ? h.specializations.slice(0, 6).map((s) => short(s, 40)).join(', ') : '';
+            return `- ${short(h.name, 60) || 'An expert'} (humanId: ${short(h.humanId, 80)})${specs ? ` — ${specs}` : ''}`;
+        });
+        return textResult(`${humans.length} ${humans.length === 1 ? 'person is' : 'people are'} live now:\n${lines.join('\n')}\n\n` +
+            'Use get_quote with a humanId to see their price, then connect_human to request a live chat.');
+    }
+    catch (err) {
+        return errorResult(err instanceof ApiError ? err.message : 'Failed to check who is live.');
+    }
+}