@askingahuman/mcp-server 2.0.5 → 2.1.0

package/README.md

@@ -7,12 +7,12 @@ Every request names a person. Find one with `list_humans` or `who_is_live`, then
 ## Tools
 
 **Free**
-- `list_humans`: browse expert profiles (name, title, specializations, rating).
+- `list_humans`: browse expert profiles (name, title, specializations, track record, and the credentials askingahuman has checked). Filter with `credential` (`license`, `degree`, `certification`, `employment`, `portfolio`) or `verified_only`.
 - `who_is_live`: see who is live right now. It can wait up to 50 seconds for someone to come online.
 - `ask_human`: send a free question (max 400 characters) to the person you choose. Not everyone takes free questions. Returns a `questionId`.
-- `check_answer`: read the answer and any follow-up conversation.
+- `check_answer`: read the answer and any follow-up conversation, with the signed answer receipt.
 - `reply_to_human`: continue the conversation after an answer.
-- `get_quote`: see what a live chat with a person would cost, what is held on the card, and how long it can run. Nothing is charged.
+- `get_quote`: see what a live chat with a person would cost, what the first block costs (held when you request), and how long it can run. Nothing is charged.
 - `rate_human`: after a session ends or a question is answered, give the person a thumbs up or down (once). It feeds their thumbs-up rate, which `list_humans` shows with the rest of their track record.
 - `submit_feedback`: send feedback about the service.
 
@@ -21,11 +21,19 @@ Every request names a person. Find one with `list_humans` or `who_is_live`, then
 - `check_connection`: wait for the person to accept. You then join the chat automatically. Shows the paid time left.
 - `read_messages` / `send_message`: talk in the chat. `read_messages` warns when less than 10 minutes of paid time remain.
 - `extend_session`: add another hour, with the same cost approval as `connect_human`. Shows the new end time.
-- `end_session`: leave the chat. Before the person accepts, this cancels the request and releases the hold.
+- `end_session`: leave the chat and get the signed session receipt. Before the person accepts, this cancels the request and releases the hold.
 
 ### How live chat is priced
 
-Each person sets their own price per hour of chat. The first hour is held on the card when you request and charged in full once the person accepts; if they never accept, nothing is charged. `extend_session` buys one more hour at a time, charged in full. Paid time is not refunded if you end early, so the chat stays open until the paid time runs out or you end it. A session, extensions included, is capped by your spend limit, by the platform's $200 limit and by its 4-hour chat limit. All sales are final.
+Each person sets their own price per hour of chat. The first hour costs that price or the platform's session minimum, whichever is higher (`get_quote` shows both); it is held when you request and charged in full once the person accepts. If they never accept, nothing is charged. `extend_session` buys one more hour at a time, charged in full. Paid time is not refunded if you end early, so the chat stays open until the paid time runs out or you end it. A session, extensions included, is capped by your spend limit, by the platform's $200 limit and by its 4-hour chat limit. All sales are final.
+
+### Paying without a card
+
+A key pays with the card saved on it at [askingahuman.com/developers](https://askingahuman.com/developers), or with prepaid credit. When the API offers them, its `402 Payment Required` answers also carry [x402](https://x402.org) (USDC on Base) and [MPP](https://mpp.dev) challenges: an agent with an x402 or MPP client can pay one, the payment becomes prepaid credit on the key, and the request goes through. The tools say when this applies. Details are on the [developers page](https://askingahuman.com/developers).
+
+### Receipts
+
+Answers and settled sessions come with a signed receipt (Ed25519 JWS). Verify it with the public keys at `https://api.askingahuman.com/.well-known/askingahuman-receipt-keys.json`.
 
 ## Setup
 

package/dist/server.d.ts

@@ -1,7 +1,7 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import type { McpConfig } from './config.js';
 import type { LiveBridge } from './live/bridge.js';
-export declare const SERVER_VERSION = "2.0.5";
+export declare const SERVER_VERSION = "2.1.0";
 export declare function createMcpServer(opts: {
     apiKey: string | undefined;
     config: McpConfig;

package/dist/server.js

@@ -9,7 +9,7 @@ import { getQuoteTool, handleGetQuote, handleListHumans, listHumansTool } from '
 import { handleWhoIsLive, whoIsLiveTool } from './tools/who-is-live.js';
 import { handleRateHuman, rateHumanTool } from './tools/rate-human.js';
 import { checkConnectionTool, connectHumanTool, endSessionTool, extendSessionTool, handleCheckConnection, handleConnectHuman, handleEndSession, handleExtendSession, handleReadMessages, handleSendMessage, readMessagesTool, sendMessageTool, } from './tools/live.js';
-export const SERVER_VERSION = '2.0.5';
+export const SERVER_VERSION = '2.1.0';
 const legacy = (fn) => async (args, ctx) => (await fn(args, ctx.apiKey, ctx.config.apiBase));
 // Always available: free questions and discovery.
 const CORE_TOOLS = [

package/dist/tools/check-answer.js

@@ -1,4 +1,5 @@
 import { UNTRUSTED_NOTE, untrusted } from '../safety.js';
+import { receiptNote } from './live.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',
@@ -110,6 +111,7 @@ export async function handleCheckAnswer(args, apiKey, apiBase) {
                             `Question: ${data.text}\n${screenshotNote}\n` +
                             `Answer:\n${untrusted(String(data.answer ?? ''))}\n\n` +
                             `Answered at: ${data.answeredAt}` +
+                            receiptNote(data.receipt) +
                             conversation +
                             `\n\nTo ask a follow-up or respond, use reply_to_human with question_id "${args.question_id}".`,
                     },

package/dist/tools/discover.d.ts

@@ -15,5 +15,6 @@ export declare function fetchQuote(args: Record<string, unknown> | undefined, ct
     result: ToolResult;
 }>;
 export declare function blockPrice(pricing: unknown, mode?: unknown): string;
+export declare const NO_PAYMENT_HINT: 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

@@ -10,10 +10,17 @@ export const listHumansTool = {
         type: 'object',
         properties: {
             specialty: { type: 'string', description: 'Optional: only experts with this specialization.', maxLength: 100 },
+            credential: {
+                type: 'string',
+                enum: ['license', 'degree', 'certification', 'employment', 'portfolio'],
+                description: 'Optional: only experts with a credential of this type that askingahuman has checked.',
+            },
+            verified_only: { type: 'boolean', description: 'Optional: only experts with at least one checked credential.' },
             limit: { type: 'number', description: 'How many to return (1-25, default 10).' },
         },
     },
 };
+const CREDENTIAL_TYPES = ['license', 'degree', 'certification', 'employment', 'portfolio'];
 // "live 12 h in the last 30 days · answers in about 4 min · accepts 90% of
 // requests · 95% thumbs up". Rates only appear once the API has enough data.
 function duration(seconds) {
@@ -43,6 +50,10 @@ export async function handleListHumans(args, ctx) {
     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));
+    if (typeof args?.credential === 'string' && CREDENTIAL_TYPES.includes(args.credential))
+        query.set('credential', args.credential);
+    if (args?.verified_only === true)
+        query.set('verifiedOnly', 'true');
     try {
         const res = await callApi(ctx, `/humans?${query}`);
         if (!res.ok)
@@ -55,9 +66,16 @@ export async function handleListHumans(args, ctx) {
         const lines = humans.map((h) => {
             const specs = Array.isArray(h.specializations) ? h.specializations.map((s) => short(s, 40)).join(', ') : '';
             const record = trackRecord(h.stats);
+            const creds = Array.isArray(h.credentials)
+                ? h.credentials
+                    .map((c) => [short(c.title, 60), c.issuer ? short(c.issuer, 60) : ''].filter(Boolean).join(', '))
+                    .filter(Boolean)
+                    .join('; ')
+                : '';
             return `- ${short(h.name, 60)} (humanId: ${short(h.humanId, 80)})${h.title ? ` — ${short(h.title, 80)}` : ''}` +
                 (specs ? `\n  Specializations: ${specs}` : '') +
-                (record ? `\n  Track record: ${record}` : '');
+                (record ? `\n  Track record: ${record}` : '') +
+                (creds ? `\n  Checked credentials: ${creds}` : '');
         });
         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.');
@@ -123,6 +141,17 @@ function hours(minutes) {
     const n = Number(minutes);
     return n % 60 === 0 ? `${n / 60} hour${n === 60 ? '' : 's'}` : `${n} minutes`;
 }
+// Told to the agent when its key can't pay yet.
+export const NO_PAYMENT_HINT = 'This API key has no card or prepaid credit yet. Add a card at https://askingahuman.com/developers, ' +
+    'or, when the 402 from the API offers x402 (USDC on Base) or MPP, pay it: the payment becomes prepaid credit on the key.';
+// The first block is charged at least the session minimum ($20); extensions at the block price.
+function firstCharge(q) {
+    const first = Number(q.firstChargeCents ?? q.holdAmountCents);
+    const block = Number(q.pricing?.blockPriceCents);
+    const minimum = Number(q.sessionMinimumCents);
+    const floor = Number.isFinite(block) && first > block && minimum > 0 ? ` (the ${dollars(minimum)} session minimum)` : '';
+    return `The first block costs ${dollars(first)}${floor}, held when you request; each extension costs ${dollars(block)}.`;
+}
 export function describeQuote(q) {
     const human = q.human;
     const who = human ? `${cleanIncoming(String(human.name || 'This person'), 60)} (humanId: ${human.humanId})` : 'This person';
@@ -132,11 +161,11 @@ export function describeQuote(q) {
     }
     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` +
+        `${firstCharge(q)}\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.` : ''));
+        (q.paymentReady === false ? `\n${NO_PAYMENT_HINT}` : ''));
 }
 export async function handleGetQuote(args, ctx) {
     const res = await fetchQuote(args, ctx);

package/dist/tools/live.d.ts

@@ -12,6 +12,7 @@ export declare function handleSendMessage(args: Record<string, unknown> | undefi
 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 const receiptNote: (receipt: unknown) => string;
 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;

package/dist/tools/live.js

@@ -1,7 +1,7 @@
 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';
+import { blockPrice, describeQuote, fetchQuote, humanIdFrom, HUMAN_ID_REQUIRED, NO_PAYMENT_HINT, 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;
@@ -118,7 +118,7 @@ export async function handleConnectHuman(args, ctx) {
             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.');
+            return errorResult(`Payment required. ${paymentHint(res.data)} Nothing was charged.`);
         }
         if (!res.ok)
             return errorResult(`${apiErrorText(res, 'Failed to request a chat')}. Manage your key at https://askingahuman.com/developers`);
@@ -128,7 +128,7 @@ export async function handleConnectHuman(args, ctx) {
         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` +
+            `Price: ${blockPrice(res.data.pricing, 'message')}; ${dollars(res.data.holdAmountCents)} held now for the first block, 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).`);
     }
@@ -298,6 +298,19 @@ export const endSessionTool = {
         required: ['session_id'],
     },
 };
+// A 402: the key has no card or credit. The API offers x402 and MPP
+// challenges (data.payWith) when they are turned on.
+function paymentHint(data) {
+    return typeof data.payWith === 'string'
+        ? 'This key has no card or credit. The 402 also accepts x402 (USDC on Base) or MPP; a payment becomes prepaid credit on the key. ' +
+            'Pay it with an x402 or MPP client, or add a card at https://askingahuman.com/developers.'
+        : NO_PAYMENT_HINT;
+}
+// Settled sessions carry a signed receipt (Ed25519 JWS; public keys at
+// https://api.askingahuman.com/.well-known/askingahuman-receipt-keys.json).
+export const receiptNote = (receipt) => typeof receipt === 'string' && receipt
+    ? `\nSigned receipt (verify with the keys at https://api.askingahuman.com/.well-known/askingahuman-receipt-keys.json):\n${receipt}`
+    : '';
 // After a session the person took (it was charged), invite a thumbs up/down.
 const rateHint = (amountCents) => Number(amountCents) > 0 ? '\nDid they help? Give a thumbs up or down with rate_human and this session_id.' : '';
 export async function endSessionViaApi(ctx, sessionId) {
@@ -316,8 +329,9 @@ export async function handleEndSession(args, ctx) {
         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)}${rateHint(res.data.amountCents)}`);
+        if (res.ok && res.data.status === 'ENDED') {
+            return textResult(`Session ended. ${chargedText(res.data.amountCents)}${receiptNote(res.data.receipt)}${rateHint(res.data.amountCents)}`);
+        }
         return textResult('Session ended. Use check_connection in a moment to see the final charge.');
     }
     catch (err) {
@@ -358,13 +372,13 @@ export async function handleExtendSession(args, ctx) {
         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` +
+            `Cost: ${dollars(pricing.blockPriceCents)}, charged in full now. Session total: ${dollars(Number(pricing.firstChargeCents ?? pricing.blockPriceCents) + blocks * 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.');
+            return errorResult(`Payment required: the extra block could not be paid. ${paymentHint(res.data)} The chat was not extended.`);
         }
         if (res.status === 409) {
             const why = typeof res.data.message === 'string' ? res.data.message : apiErrorText(res, 'Cannot extend');

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@askingahuman/mcp-server",
-    "version": "2.0.5",
+    "version": "2.1.0",
     "mcpName": "com.askingahuman/mcp-server",
     "description": "MCP server for askingahuman.com: let AI agents reach real people, with free questions and capped, paid live chats. mcprush.com-cd4a86101a8a6fd64075c4f5",
     "type": "module",