@askingahuman/mcp-server 1.0.0 → 2.0.0

package/dist/tools/check-answer.js

@@ -1,86 +1,151 @@
+import { UNTRUSTED_NOTE, untrusted } 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;
 export const checkAnswerTool = {
     name: 'check_answer',
     description: 'Check if a human has answered your question at askingahuman.com. ' +
         'Poll this tool periodically after calling ask_human — recommended interval is every 30 minutes or less. ' +
-        'Answers typically arrive within 24 hours. ' +
+        'An expert answers when they are free. ' +
         'Returns the answer text if ready, or the current status if still pending.',
     inputSchema: {
         type: 'object',
         properties: {
             question_id: {
                 type: 'string',
-                description: 'The questionId returned by ask_human.'
-            }
+                description: 'The questionId returned by ask_human.',
+            },
         },
-        required: ['question_id']
-    }
+        required: ['question_id'],
+    },
 };
+// Follow-up messages after the answer, oldest first, as a readable transcript.
+// Best-effort: if the replies can't be loaded, the answer is still returned.
+async function fetchConversation(questionId, apiKey, apiBase, signal) {
+    try {
+        const response = await fetch(`${apiBase}/api/questions/${questionId}/replies`, {
+            headers: { Authorization: `Bearer ${apiKey}` },
+            signal,
+        });
+        if (!response.ok)
+            return '';
+        const data = (await response.json());
+        const replies = data.replies ?? [];
+        if (replies.length === 0)
+            return '';
+        const lines = replies.map((r) => r.authorType === 'human' ? untrusted(r.text, `at="${r.createdAt}"`) : `[${r.createdAt}] You: ${r.text}`);
+        const last = replies[replies.length - 1];
+        const turn = last.authorType === 'human'
+            ? 'The human replied last — it is your turn to respond.'
+            : 'You replied last — waiting for the human.';
+        return `\n\nConversation since the answer (${replies.length} message${replies.length === 1 ? '' : 's'}):\n${lines.join('\n')}\n${turn}`;
+    }
+    catch {
+        return '';
+    }
+}
 export async function handleCheckAnswer(args, apiKey, apiBase) {
     if (!args?.question_id || typeof args.question_id !== 'string') {
         return {
-            content: [{ type: 'text', text: 'Error: question_id is required.' }],
-            isError: true
+            content: [
+                {
+                    type: 'text',
+                    text: 'Error: The question_id parameter is required. You must provide the exact questionId that was returned when you called the ask_human tool.',
+                },
+            ],
+            isError: true,
         };
     }
     if (!UUID_REGEX.test(args.question_id)) {
         return {
-            content: [{ type: 'text', text: 'Error: question_id must be a valid UUID (e.g., the value returned by ask_human).' }],
-            isError: true
+            content: [
+                {
+                    type: 'text',
+                    text: `Error: The question_id "${args.question_id}" is not a valid UUID format. Please ensure you are using the exact questionId string returned by the ask_human tool.`,
+                },
+            ],
+            isError: true,
         };
     }
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), 30_000);
     try {
         const response = await fetch(`${apiBase}/api/questions/${args.question_id}`, {
-            headers: { 'Authorization': `Bearer ${apiKey}` },
-            signal: controller.signal
+            headers: { Authorization: `Bearer ${apiKey}` },
+            signal: controller.signal,
         });
-        const data = await response.json();
+        const data = (await response.json());
         if (!response.ok) {
+            if (response.status === 404) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error (404): The question_id "${args.question_id}" was not found. Please verify that you have submitted the question successfully and are using the correct questionId.`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
             return {
-                content: [{
+                content: [
+                    {
                         type: 'text',
-                        text: `Error (${response.status}): ${data.error || 'Failed to check question'}`
-                    }],
-                isError: true
+                        text: `Error (${response.status}): ${data.error || 'Failed to check question status'}`,
+                    },
+                ],
+                isError: true,
             };
         }
+        const screenshotNote = data.hasScreenshot
+            ? '\n(This question included a screenshot for human context.)\n'
+            : '';
         if (data.status === 'ANSWERED') {
+            const conversation = Number(data.replyCount) > 0
+                ? await fetchConversation(args.question_id, apiKey, apiBase, controller.signal)
+                : '';
             return {
-                content: [{
+                content: [
+                    {
                         type: 'text',
-                        text: `The human has answered your question.\n\n` +
-                            `Question: ${data.text}\n\n` +
-                            `Answer: ${data.answer}\n\n` +
-                            `Answered at: ${data.answeredAt}`
-                    }]
+                        text: `The human has answered your question.\n\n${UNTRUSTED_NOTE}\n\n` +
+                            `Question: ${data.text}\n${screenshotNote}\n` +
+                            `Answer:\n${untrusted(String(data.answer ?? ''))}\n\n` +
+                            `Answered at: ${data.answeredAt}` +
+                            conversation +
+                            `\n\nTo ask a follow-up or respond, use reply_to_human with question_id "${args.question_id}".`,
+                    },
+                ],
             };
         }
         return {
-            content: [{
+            content: [
+                {
                     type: 'text',
-                    text: `Status: ${data.status}. The human has not answered yet. ` +
-                        `Check back later — answers typically arrive within 24 hours.`
-                }]
+                    text: `Status: ${data.status}. The human has not answered yet.${screenshotNote} ` +
+                        `Check back later; an expert answers when they are free.`,
+                },
+            ],
         };
     }
     catch (err) {
         if (err instanceof Error && err.name === 'AbortError') {
             return {
-                content: [{
+                content: [
+                    {
                         type: 'text',
-                        text: 'Request timed out after 30 seconds. The askingahuman.com API may be temporarily unavailable.'
-                    }],
-                isError: true
+                        text: 'Request timed out after 30 seconds. The askingahuman.com API may be temporarily unavailable. Please try checking again later.',
+                    },
+                ],
+                isError: true,
             };
         }
         return {
-            content: [{
+            content: [
+                {
                     type: 'text',
-                    text: `Network error: ${err instanceof Error ? err.message : 'Unknown error'}`
-                }],
-            isError: true
+                    text: `Network error: ${err instanceof Error ? err.message : 'Unknown error'}. Please check your connection and try again.`,
+                },
+            ],
+            isError: true,
         };
     }
     finally {

package/dist/tools/discover.d.ts

@@ -0,0 +1,18 @@
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { ToolContext, ToolResult } from '../context.js';
+export declare const listHumansTool: Tool;
+export declare function handleListHumans(args: Record<string, unknown> | undefined, ctx: ToolContext): Promise<ToolResult>;
+export declare const getQuoteTool: Tool;
+export declare function humanIdFrom(args: Record<string, unknown> | undefined): string | null;
+export declare const HUMAN_ID_REQUIRED = "Error: human_id is required: choose the person with list_humans or who_is_live and pass their humanId.";
+export declare function spendLimitCents(args: Record<string, unknown> | undefined, ctx: ToolContext): number;
+export declare function fetchQuote(args: Record<string, unknown> | undefined, ctx: ToolContext): Promise<{
+    ok: true;
+    quote: Record<string, unknown>;
+} | {
+    ok: false;
+    result: ToolResult;
+}>;
+export declare function blockPrice(pricing: unknown, mode?: unknown): string;
+export declare function describeQuote(q: Record<string, unknown>): string;
+export declare function handleGetQuote(args: Record<string, unknown> | undefined, ctx: ToolContext): Promise<ToolResult>;

package/dist/tools/discover.js

@@ -0,0 +1,118 @@
+import { ApiError, apiErrorText, callApi, dollars, errorResult, textResult } from '../context.js';
+import { cleanIncoming } from '../safety.js';
+export const listHumansTool = {
+    name: 'list_humans',
+    description: 'List the reviewed experts on askingahuman.com: name, title, specializations, languages and rating. ' +
+        'Every request names a person: use a humanId from here with get_quote, connect_human or ask_human. ' +
+        'Profiles are public summaries only; no contact details are shared.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            specialty: { type: 'string', description: 'Optional: only experts with this specialization.', maxLength: 100 },
+            limit: { type: 'number', description: 'How many to return (1-25, default 10).' },
+        },
+    },
+};
+export async function handleListHumans(args, ctx) {
+    const limit = Math.min(25, Math.max(1, Math.floor(Number(args?.limit) || 10)));
+    const query = new URLSearchParams({ audience: 'bot', limit: String(limit) });
+    if (typeof args?.specialty === 'string' && args.specialty.trim())
+        query.set('specialty', args.specialty.trim().slice(0, 100));
+    try {
+        const res = await callApi(ctx, `/humans?${query}`);
+        if (!res.ok)
+            return errorResult(apiErrorText(res, 'Failed to list experts'));
+        const humans = res.data.humans || [];
+        if (humans.length === 0)
+            return textResult('No experts match that search.');
+        // Profile text is written by the experts themselves; keep it short and clean.
+        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.map((s) => short(s, 40)).join(', ') : '';
+            const rating = typeof h.rating === 'number' && h.rating > 0 ? ` · rated ${h.rating.toFixed(1)}` : '';
+            return `- ${short(h.name, 60)} (humanId: ${short(h.humanId, 80)})${h.title ? ` — ${short(h.title, 80)}` : ''}${rating}` +
+                (specs ? `\n  Specializations: ${specs}` : '');
+        });
+        return textResult(`${humans.length} expert${humans.length === 1 ? '' : 's'}:\n${lines.join('\n')}\n\n` +
+            'Prices and live status are not listed here; use get_quote with a humanId to see them.');
+    }
+    catch (err) {
+        return errorResult(err instanceof ApiError ? err.message : 'Failed to list experts.');
+    }
+}
+export const getQuoteTool = {
+    name: 'get_quote',
+    description: 'Check, at no cost, what a live chat with a specific person would cost: their price per hour of chat, what is ' +
+        'held on the card, how long the chat can run with extensions, and whether they are live now. Nothing is charged ' +
+        'and nobody is notified. Call this before connect_human.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            human_id: { type: 'string', description: 'The person (humanId from list_humans or who_is_live).' },
+            max_spend_usd: {
+                type: 'number',
+                description: 'Optional: the most to spend on the whole chat, extensions included, in US dollars.',
+            },
+        },
+        required: ['human_id'],
+    },
+};
+const HUMAN_ID = /^[A-Za-z0-9_:.-]{1,128}$/;
+// The person a tool call names, or null when missing or malformed.
+export function humanIdFrom(args) {
+    const id = typeof args?.human_id === 'string' ? args.human_id.trim() : '';
+    return HUMAN_ID.test(id) ? id : null;
+}
+export const HUMAN_ID_REQUIRED = 'Error: human_id is required: choose the person with list_humans or who_is_live and pass their humanId.';
+// The spend limit sent to the API: the agent's request, never above the operator's.
+export function spendLimitCents(args, ctx) {
+    const asked = Number(args?.max_spend_usd);
+    return Math.max(1, Math.min(ctx.config.maxSpendCents, Number.isFinite(asked) && asked > 0 ? Math.round(asked * 100) : Infinity));
+}
+export async function fetchQuote(args, ctx) {
+    const humanId = humanIdFrom(args);
+    if (!humanId)
+        return { ok: false, result: errorResult(HUMAN_ID_REQUIRED) };
+    const query = new URLSearchParams({ mode: 'message', humanId, maxSpendCents: String(spendLimitCents(args, ctx)) });
+    try {
+        const res = await callApi(ctx, `/api/connect/quote?${query}`);
+        if (res.status === 404) {
+            return { ok: false, result: errorResult('No such person. Use list_humans or who_is_live to find someone.') };
+        }
+        if (!res.ok)
+            return { ok: false, result: errorResult(apiErrorText(res, 'Failed to get a quote')) };
+        return { ok: true, quote: res.data };
+    }
+    catch (err) {
+        return { ok: false, result: errorResult(err instanceof ApiError ? err.message : 'Failed to get a quote.') };
+    }
+}
+// "$120.00 per hour of chat", "$90.00 per 30 min of video".
+export function blockPrice(pricing, mode = 'message') {
+    const p = (pricing || {});
+    const span = p.blockMinutes === 60 ? 'hour' : `${p.blockMinutes ?? '?'} min`;
+    return `${dollars(p.blockPriceCents)} per ${span} of ${mode === 'video' ? 'video' : 'chat'}`;
+}
+function hours(minutes) {
+    const n = Number(minutes);
+    return n % 60 === 0 ? `${n / 60} hour${n === 60 ? '' : 's'}` : `${n} minutes`;
+}
+export function describeQuote(q) {
+    const human = q.human;
+    const who = human ? `${cleanIncoming(String(human.name || 'This person'), 60)} (humanId: ${human.humanId})` : 'This person';
+    if (!q.bookable) {
+        const price = q.pricing ? ` Their price: ${blockPrice(q.pricing, q.mode)}.` : '';
+        return `${who}: ${String(q.message || 'a live chat is not available.')}${price} Nothing was charged.`;
+    }
+    return (`${who} is ${human?.live ? 'live now' : 'offline; a chat request waits up to 24 hours for them'}.\n` +
+        `Price: ${blockPrice(q.pricing, q.mode)}, charged in full once they accept (nothing if they never do). ` +
+        `${dollars(q.holdAmountCents)} is held on the card when you request.\n` +
+        `Length: one hour to start; extend_session adds another hour, up to ${hours(q.maxSessionMinutes)} ` +
+        `within your ${dollars(q.spendLimitCents)} spend limit. Ending early does not refund paid time.\n` +
+        `All sales are final.` +
+        (q.paymentReady === false ? `\nThis API key has no card on file: add one at https://askingahuman.com/developers before connecting.` : ''));
+}
+export async function handleGetQuote(args, ctx) {
+    const res = await fetchQuote(args, ctx);
+    return res.ok ? textResult(describeQuote(res.quote)) : res.result;
+}

package/dist/tools/live.d.ts

@@ -0,0 +1,18 @@
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { ToolContext, ToolResult } from '../context.js';
+export declare const MAX_CHAT_CHARS = 1000;
+export declare const LOW_TIME_MS: number;
+export declare function paidTimeNote(data: Record<string, unknown>, now?: number): string;
+export declare const connectHumanTool: Tool;
+export declare function handleConnectHuman(args: Record<string, unknown> | undefined, ctx: ToolContext): Promise<ToolResult>;
+export declare const checkConnectionTool: Tool;
+export declare function handleCheckConnection(args: Record<string, unknown> | undefined, ctx: ToolContext): Promise<ToolResult>;
+export declare const sendMessageTool: Tool;
+export declare function handleSendMessage(args: Record<string, unknown> | undefined, ctx: ToolContext): Promise<ToolResult>;
+export declare const readMessagesTool: Tool;
+export declare function handleReadMessages(args: Record<string, unknown> | undefined, ctx: ToolContext): Promise<ToolResult>;
+export declare const endSessionTool: Tool;
+export declare function endSessionViaApi(ctx: Pick<ToolContext, 'apiKey' | 'config'>, sessionId: string): Promise<void>;
+export declare function handleEndSession(args: Record<string, unknown> | undefined, ctx: ToolContext): Promise<ToolResult>;
+export declare const extendSessionTool: Tool;
+export declare function handleExtendSession(args: Record<string, unknown> | undefined, ctx: ToolContext): Promise<ToolResult>;