@askingahuman/mcp-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 askingahuman.com
+
+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,96 @@
+# askingahuman MCP Server
+
+Get real human answers from AI agents and LLMs.
+
+When your AI doesn't know the answer, needs a judgment call, or wants a second opinion — ask a real human.
+
+## What It Does
+
+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.
+
+**Two tools:**
+- `ask_human` — Submit a question (max 400 chars). Returns a `questionId`.
+- `check_answer` — Poll for the human's response using the `questionId`.
+
+## Setup
+
+### 1. Get your free API key
+
+Visit [askingahuman.com/developers](https://askingahuman.com/developers) and create a key with your email.
+
+### 2. Add to your MCP client
+
+**Claude Desktop** (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "askingahuman": {
+      "command": "npx",
+      "args": ["-y", "@askingahuman/mcp-server"],
+      "env": {
+        "ASKINGAHUMAN_API_KEY": "ahk_your_key_here"
+      }
+    }
+  }
+}
+```
+
+**Cursor** (Settings > MCP Servers):
+
+```json
+{
+  "askingahuman": {
+    "command": "npx",
+    "args": ["-y", "@askingahuman/mcp-server"],
+    "env": {
+      "ASKINGAHUMAN_API_KEY": "ahk_your_key_here"
+    }
+  }
+}
+```
+
+## Pricing
+
+| Tier | Price | Details |
+|------|-------|---------|
+| Free | $0 | 1 question/month, no credit card needed |
+| Paid | $5/question | After free tier; requires saved payment method |
+
+Add a payment method at [askingahuman.com/developers](https://askingahuman.com/developers) to unlock paid questions.
+
+## Example
+
+An AI agent using this server might:
+
+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
+
+## 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"
+```
+
+## 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/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,39 @@
+#!/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
+            };
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch(console.error);

package/dist/tools/ask-human.d.ts

@@ -0,0 +1,15 @@
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+export declare const askHumanTool: Tool;
+export declare function handleAskHuman(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/ask-human.js

@@ -0,0 +1,91 @@
+export const askHumanTool = {
+    name: 'ask_human',
+    description: 'Submit a question to a real human at askingahuman.com. ' +
+        'The human will read your question and write back a thoughtful answer within 24 hours. ' +
+        'First question each month is free; subsequent questions cost $5 (requires saved payment method). ' +
+        'Returns a questionId — use check_answer to poll for the response.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            question: {
+                type: 'string',
+                description: 'The question to ask the human. Be specific and concise (max 400 characters).',
+                maxLength: 400
+            },
+            contact_email: {
+                type: 'string',
+                description: 'Optional email address to receive a notification when the question is answered.'
+            }
+        },
+        required: ['question']
+    }
+};
+export async function handleAskHuman(args, apiKey, apiBase) {
+    if (!args?.question || typeof args.question !== 'string') {
+        return {
+            content: [{ type: 'text', text: 'Error: question is required.' }],
+            isError: true
+        };
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 30_000);
+    try {
+        const response = await fetch(`${apiBase}/api/questions`, {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${apiKey}`,
+                'Content-Type': 'application/json'
+            },
+            body: JSON.stringify({
+                questionText: args.question,
+                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 question'}. ` +
+                            `Manage your key at https://askingahuman.com/developers`
+                    }],
+                isError: true
+            };
+        }
+        const charged = data.charged;
+        const chargedAmount = data.chargedAmount;
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Question submitted successfully.\n` +
+                        `Question ID: ${data.questionId}\n` +
+                        `Status: ${data.status}\n` +
+                        `Charged: ${charged ? `$${(chargedAmount / 100).toFixed(2)}` : 'Free (monthly allowance)'}\n\n` +
+                        `Use check_answer with question_id "${data.questionId}" to poll for the response. ` +
+                        `Answers typically arrive within 24 hours.`
+                }]
+        };
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === 'AbortError') {
+            return {
+                content: [{
+                        type: 'text',
+                        text: 'Request timed out after 30 seconds. The askingahuman.com API may be temporarily unavailable.'
+                    }],
+                isError: true
+            };
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Network error: ${err instanceof Error ? err.message : 'Unknown error'}. Check your internet connection.`
+                }],
+            isError: true
+        };
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}

package/dist/tools/check-answer.d.ts

@@ -0,0 +1,15 @@
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+export declare const checkAnswerTool: Tool;
+export declare function handleCheckAnswer(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/check-answer.js

@@ -0,0 +1,89 @@
+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. ' +
+        '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.'
+            }
+        },
+        required: ['question_id']
+    }
+};
+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
+        };
+    }
+    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
+        };
+    }
+    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
+        });
+        const data = await response.json();
+        if (!response.ok) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Error (${response.status}): ${data.error || 'Failed to check question'}`
+                    }],
+                isError: true
+            };
+        }
+        if (data.status === 'ANSWERED') {
+            return {
+                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}`
+                    }]
+            };
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Status: ${data.status}. The human has not answered yet. ` +
+                        `Check back later — answers typically arrive within 24 hours.`
+                }]
+        };
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === 'AbortError') {
+            return {
+                content: [{
+                        type: 'text',
+                        text: 'Request timed out after 30 seconds. The askingahuman.com API may be temporarily unavailable.'
+                    }],
+                isError: true
+            };
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Network error: ${err instanceof Error ? err.message : 'Unknown error'}`
+                }],
+            isError: true
+        };
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+    "name": "@askingahuman/mcp-server",
+    "version": "1.0.0",
+    "description": "MCP server for askingahuman.com — let AI agents ask real humans for answers",
+    "type": "module",
+    "main": "dist/index.js",
+    "bin": {
+        "askingahuman-mcp": "dist/index.js"
+    },
+    "scripts": {
+        "build": "tsc",
+        "dev": "tsx src/index.ts",
+        "prepublishOnly": "npm run build"
+    },
+    "keywords": [
+        "mcp",
+        "model-context-protocol",
+        "human",
+        "ai",
+        "agent",
+        "answers",
+        "askingahuman"
+    ],
+    "files": [
+        "dist/",
+        "README.md",
+        "LICENSE"
+    ],
+    "dependencies": {
+        "@modelcontextprotocol/sdk": "^1.0.0"
+    },
+    "devDependencies": {
+        "typescript": "^5.3.0",
+        "@types/node": "^20.0.0",
+        "tsx": "^4.0.0"
+    },
+    "engines": {
+        "node": ">=18.0.0"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/tz-ship-it/askingahuman.com"
+    },
+    "homepage": "https://askingahuman.com/developers",
+    "author": {
+        "name": "askingahuman.com",
+        "url": "https://askingahuman.com"
+    },
+    "license": "MIT"
+}