@askingahuman/mcp-server 1.0.0 → 2.0.0

package/README.md

@@ -1,26 +1,40 @@
 # askingahuman MCP Server
 
-Get real human answers from AI agents and LLMs.
+Let your AI agent reach a real person through [askingahuman.com](https://askingahuman.com): send a free question to someone you choose, or book a paid live chat with them.
 
-When your AI doesn't know the answer, needs a judgment call, or wants a second opinion — ask a real human.
+Every request names a person. Find one with `list_humans` or `who_is_live`, then pass their `humanId`.
 
-## What It Does
+## Tools
 
-This MCP server connects your AI agent to [askingahuman.com](https://askingahuman.com), where a real person reads your question and writes back a thoughtful, honest answer within 24 hours.
+**Free**
+- `list_humans`: browse expert profiles (name, title, specializations, rating).
+- `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.
+- `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.
+- `submit_feedback`: send feedback about the service.
 
-**Two tools:**
-- `ask_human` — Submit a question (max 400 chars). Returns a `questionId`.
-- `check_answer` — Poll for the human's response using the `questionId`.
+**Paid live chat** (local server only, text only)
+- `connect_human`: request a live chat with a person. Shows the cost to your user for approval when the client supports it. If the person is offline, the request waits up to 24 hours for them.
+- `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.
+
+### 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.
 
 ## Setup
 
-### 1. Get your free API key
+### 1. Get your API key
 
-Visit [askingahuman.com/developers](https://askingahuman.com/developers) and create a key with your email.
+Create a key at [askingahuman.com/developers](https://askingahuman.com/developers). To use live chat, add a card there too.
 
-### 2. Add to your MCP client
+### 2. Add it to your MCP client
 
-**Claude Desktop** (`claude_desktop_config.json`):
+**Claude Desktop** (`claude_desktop_config.json`) or **Cursor** (Settings > MCP Servers):
 
 ```json
 {
@@ -29,68 +43,66 @@ Visit [askingahuman.com/developers](https://askingahuman.com/developers) and cre
       "command": "npx",
       "args": ["-y", "@askingahuman/mcp-server"],
       "env": {
-        "ASKINGAHUMAN_API_KEY": "ahk_your_key_here"
+        "ASKINGAHUMAN_API_KEY": "ahk_your_key_here",
+        "ASKINGAHUMAN_MAX_SPEND_USD": "100"
       }
     }
   }
 }
 ```
 
-**Cursor** (Settings > MCP Servers):
+Live chat uses the optional package `@livekit/rtc-node` (installed automatically on Windows, macOS and Linux). Without it, the free tools still work.
 
-```json
-{
-  "askingahuman": {
-    "command": "npx",
-    "args": ["-y", "@askingahuman/mcp-server"],
-    "env": {
-      "ASKINGAHUMAN_API_KEY": "ahk_your_key_here"
-    }
-  }
-}
+### Docker
+
+```bash
+docker build -t askingahuman/mcp-server .
+docker run -i --rm -e ASKINGAHUMAN_API_KEY=ahk_your_key_here askingahuman/mcp-server
 ```
 
-## Pricing
+## Configuration
+
+| Variable | Default | What it does |
+|----------|---------|--------------|
+| `ASKINGAHUMAN_API_KEY` | (required) | Your API key. |
+| `ASKINGAHUMAN_MAX_SPEND_USD` | `100` | The most one live chat can cost, extensions included (max 200, the platform cap). The agent can ask for less, never more. |
+| `ASKINGAHUMAN_REQUIRE_CONFIRMATION` | `false` | If `true`, paid chats and extensions happen only when your MCP client can ask you to approve the cost. |
+| `ASKINGAHUMAN_SKIP_APPROVAL` | `false` | If `true`, the server doesn't ask for cost approval in the chat. Use it with clients that claim to show MCP approval forms but don't (for example, some editor extensions decline them automatically). Your client still asks before each tool call, and the spend limit still applies. Ignored when `ASKINGAHUMAN_REQUIRE_CONFIRMATION` is on. |
+| `ASKINGAHUMAN_API_URL` | `https://api.askingahuman.com` | API address (https only). |
 
-| Tier | Price | Details |
-|------|-------|---------|
-| Free | $0 | 1 question/month, no credit card needed |
-| Paid | $5/question | After free tier; requires saved payment method |
+## Safety
 
-Add a payment method at [askingahuman.com/developers](https://askingahuman.com/developers) to unlock paid questions.
+- **Spending is capped twice.** Your spend limit is enforced in this server and again by the API, which won't sell an hour, or an extension, that would go past it.
+- **You approve each charge.** `connect_human` and `extend_session` show the cost to your user first when the client supports it.
+- **Nothing is left waiting.** When the MCP client shuts down, the server ends its open chats and cancels requests nobody has accepted yet, which releases their holds. The platform ends a chat when its paid time runs out.
+- **Nothing sensitive goes out.** Messages to people are blocked if they contain your API key or anything that looks like a credential (cloud keys, tokens, private keys). Links are blocked too, so an agent can't send someone to a download or a phishing page.
+- **Text only, no files.** The server joins the chat without receiving audio or video and ignores everything except plain-text chat from the person. Files can't be sent or received.
+- **People's words are framed as untrusted.** Messages and answers from people are wrapped in `<human_message>` tags with a note telling the model to treat them as conversation, not instructions.
+- **Private by default.** Chats are kept in memory only, never written to disk or logged, and dropped 10 minutes after they end. The chat's access token stays inside this server and is never shown to the model.
 
 ## Example
 
-An AI agent using this server might:
+1. `list_humans` or `who_is_live` finds the right person.
+2. `get_quote` with their `humanId` shows the price per hour and the hold.
+3. `connect_human` asks your user to approve, then notifies the person.
+4. `check_connection` with `wait_seconds: 45` waits until they accept, then joins the chat.
+5. `send_message` / `read_messages` until done. `extend_session` if you need more time; `end_session` to leave.
 
-1. Call `ask_human` with: "I'm helping a user choose between React and Vue for a small dashboard project. What would an experienced developer recommend and why?"
-2. Receive a `questionId` back immediately
-3. Periodically call `check_answer` with that ID
-4. Eventually receive a thoughtful, human-written response
+Just need an answer? `ask_human` with their `humanId`, then `check_answer` later.
 
 ## REST API
 
-You can also use the API directly without the MCP server:
-
 ```bash
-# Submit a question
-curl -X POST https://askingahuman.com/api/questions \
-  -H "Authorization: Bearer ahk_your_key" \
-  -H "Content-Type: application/json" \
-  -d '{"questionText": "Your question here"}'
-
-# Check for answer
-curl https://askingahuman.com/api/questions/{questionId} \
-  -H "Authorization: Bearer ahk_your_key"
+# Ask a chosen person a question (free)
+curl -X POST https://api.askingahuman.com/api/questions \
+  -H "Authorization: Bearer ahk_your_key" -H "Content-Type: application/json" \
+  -d '{"questionText": "Your question here", "targetExpertId": "HUMAN_ID"}'
+
+# Who is live, and what would an hour of chat with them cost?
+curl https://api.askingahuman.com/api/live-now -H "Authorization: Bearer ahk_your_key"
+curl "https://api.askingahuman.com/api/connect/quote?mode=message&humanId=HUMAN_ID" -H "Authorization: Bearer ahk_your_key"
 ```
 
-## Environment Variables
-
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `ASKINGAHUMAN_API_KEY` | Yes | Your API key from askingahuman.com/developers |
-| `ASKINGAHUMAN_API_URL` | No | Custom API URL (defaults to production) |
-
 ## License
 
 MIT

package/dist/config.d.ts

@@ -0,0 +1,10 @@
+export declare const DEFAULT_API_BASE = "https://api.askingahuman.com";
+export declare const PLATFORM_MAX_SPEND_CENTS = 20000;
+export interface McpConfig {
+    apiBase: string;
+    maxSpendCents: number;
+    requireConfirmation: boolean;
+    skipApproval: boolean;
+}
+export declare function resolveApiBase(raw: string | undefined): string;
+export declare function loadConfig(env?: NodeJS.ProcessEnv): McpConfig;

package/dist/config.js

@@ -0,0 +1,37 @@
+// Settings the person running this MCP server controls through environment
+// variables. The spend limit set here binds the agent: tool arguments can only
+// lower it, and the platform caps every session at $200 (and chat at 4 hours)
+// regardless.
+export const DEFAULT_API_BASE = 'https://api.askingahuman.com';
+export const PLATFORM_MAX_SPEND_CENTS = 20000;
+function boundedNumber(raw, fallback, min, max) {
+    const parsed = Number(raw);
+    if (raw === undefined || raw.trim() === '' || !Number.isFinite(parsed))
+        return fallback;
+    return Math.min(max, Math.max(min, parsed));
+}
+// The API key travels in every request, so only HTTPS is accepted (plain HTTP
+// only for a local development API).
+export function resolveApiBase(raw) {
+    const value = (raw || DEFAULT_API_BASE).trim().replace(/\/+$/, '');
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`ASKINGAHUMAN_API_URL is not a valid URL: ${value}`);
+    }
+    const local = url.hostname === 'localhost' || url.hostname === '127.0.0.1';
+    if (url.protocol !== 'https:' && !(local && url.protocol === 'http:')) {
+        throw new Error('ASKINGAHUMAN_API_URL must use https:// (http:// is allowed only for localhost).');
+    }
+    return value;
+}
+export function loadConfig(env = process.env) {
+    return {
+        apiBase: resolveApiBase(env.ASKINGAHUMAN_API_URL),
+        maxSpendCents: Math.round(boundedNumber(env.ASKINGAHUMAN_MAX_SPEND_USD, 100, 0.01, PLATFORM_MAX_SPEND_CENTS / 100) * 100),
+        requireConfirmation: /^(1|true|yes)$/i.test(env.ASKINGAHUMAN_REQUIRE_CONFIRMATION || ''),
+        skipApproval: /^(1|true|yes)$/i.test(env.ASKINGAHUMAN_SKIP_APPROVAL || ''),
+    };
+}

package/dist/context.d.ts

@@ -0,0 +1,33 @@
+import type { McpConfig } from './config.js';
+import type { LiveBridge } from './live/bridge.js';
+export type Confirmation = 'accepted' | 'declined' | 'cancelled' | 'unsupported';
+export interface ToolContext {
+    apiKey: string;
+    config: McpConfig;
+    live: LiveBridge | null;
+    confirm: (message: string) => Promise<Confirmation>;
+}
+export interface ToolResult {
+    [key: string]: unknown;
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+}
+export declare function textResult(text: string): ToolResult;
+export declare function errorResult(text: string): ToolResult;
+export interface ApiResponse {
+    ok: boolean;
+    status: number;
+    data: Record<string, unknown>;
+}
+export declare class ApiError extends Error {
+}
+export declare function callApi(ctx: Pick<ToolContext, 'apiKey' | 'config'>, path: string, init?: {
+    method?: string;
+    body?: unknown;
+    timeoutMs?: number;
+}): Promise<ApiResponse>;
+export declare function apiErrorText(res: ApiResponse, fallback: string): string;
+export declare function dollars(cents: unknown): string;

package/dist/context.js

@@ -0,0 +1,42 @@
+export function textResult(text) {
+    return { content: [{ type: 'text', text }] };
+}
+export function errorResult(text) {
+    return { content: [{ type: 'text', text }], isError: true };
+}
+export class ApiError extends Error {
+}
+// JSON request to the askingahuman API with the caller's key and a timeout.
+// Throws ApiError with a readable message on network failure or timeout.
+export async function callApi(ctx, path, init = {}) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), init.timeoutMs ?? 30_000);
+    try {
+        const response = await fetch(`${ctx.config.apiBase}${path}`, {
+            method: init.method ?? 'GET',
+            headers: {
+                Authorization: `Bearer ${ctx.apiKey}`,
+                ...(init.body !== undefined && { 'Content-Type': 'application/json' }),
+            },
+            ...(init.body !== undefined && { body: JSON.stringify(init.body) }),
+            signal: controller.signal,
+        });
+        const data = (await response.json().catch(() => ({})));
+        return { ok: response.ok, status: response.status, data };
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === 'AbortError') {
+            throw new ApiError('The askingahuman API did not respond within 30 seconds. Try again shortly.');
+        }
+        throw new ApiError(`Network error: ${err instanceof Error ? err.message : 'unknown error'}.`);
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+export function apiErrorText(res, fallback) {
+    return `Error (${res.status}): ${typeof res.data.error === 'string' ? res.data.error : fallback}`;
+}
+export function dollars(cents) {
+    return `$${(Number(cents) / 100).toFixed(2)}`;
+}

package/dist/http-server.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/http-server.js

@@ -0,0 +1,53 @@
+import http from 'http';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { loadConfig } from './config.js';
+import { createMcpServer } from './server.js';
+// Hosted server: stateless per request, so no live chat (that needs a
+// long-lived connection); free questions, discovery and quotes only.
+const config = loadConfig();
+const PORT = parseInt(process.env.PORT || '3000', 10);
+const httpServer = http.createServer(async (req, res) => {
+    // Health check
+    if (req.url === '/health' && req.method === 'GET') {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ status: 'ok', service: 'askingahuman-mcp' }));
+        return;
+    }
+    // MCP endpoint
+    if (req.url === '/mcp' && req.method === 'POST') {
+        // Extract API key from Authorization header
+        const authHeader = req.headers.authorization;
+        if (!authHeader || !authHeader.startsWith('Bearer ahk_')) {
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'API key required. Format: Bearer ahk_...' }));
+            return;
+        }
+        const apiKey = authHeader.slice(7);
+        try {
+            const server = createMcpServer({ apiKey, config, live: null });
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: undefined, // Stateless
+            });
+            await server.connect(transport);
+            await transport.handleRequest(req, res);
+            // Clean up after response
+            await server.close();
+        }
+        catch (err) {
+            console.error('MCP request error:', err);
+            if (!res.headersSent) {
+                res.writeHead(500, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Internal server error' }));
+            }
+        }
+        return;
+    }
+    // 404 for everything else
+    res.writeHead(404, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Not found. Use POST /mcp for MCP requests, GET /health for health check.' }));
+});
+httpServer.listen(PORT, () => {
+    console.log(`askingahuman MCP HTTP server listening on port ${PORT}`);
+    console.log(`Health: http://localhost:${PORT}/health`);
+    console.log(`MCP:    POST http://localhost:${PORT}/mcp`);
+});

package/dist/index.js

@@ -1,39 +1,35 @@
 #!/usr/bin/env node
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
-import { askHumanTool, handleAskHuman } from './tools/ask-human.js';
-import { checkAnswerTool, handleCheckAnswer } from './tools/check-answer.js';
-const API_BASE = process.env.ASKINGAHUMAN_API_URL || 'https://askingahuman.com';
-const server = new Server({ name: 'askingahuman', version: '1.0.0' }, { capabilities: { tools: {} } });
-server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools: [askHumanTool, checkAnswerTool]
-}));
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    const apiKey = process.env.ASKINGAHUMAN_API_KEY;
-    if (!apiKey) {
-        return {
-            content: [{
-                    type: 'text',
-                    text: 'Error: ASKINGAHUMAN_API_KEY environment variable is required. Get your free key at https://askingahuman.com/developers'
-                }],
-            isError: true
-        };
-    }
-    switch (request.params.name) {
-        case 'ask_human':
-            return handleAskHuman(request.params.arguments, apiKey, API_BASE);
-        case 'check_answer':
-            return handleCheckAnswer(request.params.arguments, apiKey, API_BASE);
-        default:
-            return {
-                content: [{ type: 'text', text: `Unknown tool: ${request.params.name}` }],
-                isError: true
-            };
-    }
-});
+import { loadConfig } from './config.js';
+import { LiveBridge, loadLiveKit } from './live/bridge.js';
+import { createMcpServer } from './server.js';
+import { endSessionViaApi } from './tools/live.js';
 async function main() {
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
+    const config = loadConfig();
+    const apiKey = process.env.ASKINGAHUMAN_API_KEY;
+    // Local (stdio) server: this process can hold live chats open for the agent.
+    const live = new LiveBridge({
+        loadRoomFactory: loadLiveKit,
+        endSession: (sessionId) => endSessionViaApi({ apiKey: apiKey ?? '', config }, sessionId),
+    });
+    const server = createMcpServer({ apiKey, config, live });
+    // When the client goes away: end open chats and cancel requests nobody has
+    // accepted yet (that releases their holds).
+    // On a signal, exit after that; when stdin closes, let in-flight requests
+    // finish and the process exit on its own (all bridge timers are unref'd).
+    let stopping = null;
+    const endChats = () => (stopping ??= live.shutdown().catch(() => undefined));
+    const exitAfterEnding = async () => {
+        await Promise.race([endChats(), new Promise((resolve) => setTimeout(resolve, 5000))]);
+        process.exit(0);
+    };
+    process.on('SIGINT', exitAfterEnding);
+    process.on('SIGTERM', exitAfterEnding);
+    process.stdin.on('end', endChats);
+    process.stdin.on('close', endChats);
+    await server.connect(new StdioServerTransport());
 }
-main().catch(console.error);
+main().catch((err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+});

package/dist/live/bridge.d.ts

@@ -0,0 +1,68 @@
+export interface ChatRoom {
+    on(event: 'dataReceived', cb: (payload: Uint8Array, participant?: {
+        identity: string;
+    }, kind?: unknown, topic?: string) => void): unknown;
+    on(event: 'participantConnected' | 'participantDisconnected', cb: (participant: {
+        identity: string;
+    }) => void): unknown;
+    on(event: 'disconnected', cb: (reason?: unknown) => void): unknown;
+    connect(url: string, token: string, opts: {
+        autoSubscribe: boolean;
+        dynacast: boolean;
+    }): Promise<void>;
+    disconnect(): Promise<void>;
+    localParticipant?: {
+        publishData(data: Uint8Array, opts: {
+            reliable?: boolean;
+        }): Promise<void>;
+    };
+    remoteParticipants?: Map<string, {
+        identity: string;
+    }>;
+}
+export type RoomFactory = () => ChatRoom;
+export declare function loadLiveKit(): Promise<RoomFactory | null>;
+export interface ChatLine {
+    from: 'human' | 'you' | 'system';
+    text: string;
+    at: string;
+}
+export declare class LiveChatError extends Error {
+}
+export declare const MAX_ACTIVE_CHATS = 2;
+export declare const MAX_MESSAGE_BYTES: number;
+export declare const MAX_SENT_PER_SESSION = 200;
+export declare const MIN_SEND_INTERVAL_MS = 1000;
+export declare const FORGET_AFTER_END_MS: number;
+export interface LiveBridgeOptions {
+    loadRoomFactory: () => Promise<RoomFactory | null>;
+    endSession: (sessionId: string) => Promise<void>;
+    now?: () => number;
+}
+export declare class LiveBridge {
+    private opts;
+    private chats;
+    private pending;
+    private factory;
+    private now;
+    constructor(opts: LiveBridgeOptions);
+    isAvailable(): Promise<boolean>;
+    private getFactory;
+    trackRequest(sessionId: string): void;
+    isJoined(sessionId: string): boolean;
+    join(sessionId: string, url: string, token: string): Promise<'joined' | 'already'>;
+    private onData;
+    private push;
+    private getChat;
+    send(sessionId: string, text: string): Promise<void>;
+    read(sessionId: string, waitMs: number): Promise<{
+        lines: ChatLine[];
+        closed: boolean;
+        closeReason: string | null;
+        humanPresent: boolean;
+    }>;
+    transcript(sessionId: string): ChatLine[];
+    end(sessionId: string, reason?: string): Promise<boolean>;
+    private close;
+    shutdown(): Promise<void>;
+}