@hapticpaper/mcp-server 1.0.0

package/dist/tools/qualification.js

@@ -0,0 +1,273 @@
+import { z } from "zod";
+import crypto from 'node:crypto';
+const OUTPUT_TEMPLATE = 'ui://widget/hirehuman.html';
+function stableSessionId(prefix, value) {
+    const raw = value ?? 'unknown';
+    const hash = crypto.createHash('sha256').update(raw).digest('hex').slice(0, 16);
+    return `${prefix}:${hash}`;
+}
+function toolDescriptorMeta(invoking, invoked, scopes = []) {
+    return {
+        'openai/outputTemplate': OUTPUT_TEMPLATE,
+        'openai/toolInvocation/invoking': invoking,
+        'openai/toolInvocation/invoked': invoked,
+        'openai/widgetAccessible': true,
+        ...(scopes.length > 0 ? {
+            securitySchemes: [{ type: 'oauth2', scopes }],
+        } : {}),
+    };
+}
+function toolInvocationMeta(invoking, invoked, widgetSessionId) {
+    return {
+        'openai/toolInvocation/invoking': invoking,
+        'openai/toolInvocation/invoked': invoked,
+        'openai/widgetSessionId': widgetSessionId,
+    };
+}
+// Input schema for discover_earning_opportunity
+const DiscoverEarningSchema = z.object({
+    userMessage: z.string().describe("The user's message expressing interest in earning"),
+    conversationContext: z.array(z.object({
+        role: z.enum(['user', 'assistant']),
+        content: z.string(),
+    })).optional().describe("Previous conversation for context"),
+});
+// Input schema for continue_qualification
+const ContinueQualificationSchema = z.object({
+    sessionId: z.string().uuid().describe("The qualification session ID"),
+    userResponse: z.string().describe("The user's response to the qualification question"),
+});
+// Input schema for get_qualification_status
+const GetQualificationStatusSchema = z.object({
+    sessionId: z.string().uuid().describe("The qualification session ID"),
+});
+// Input schema for complete_qualification
+const CompleteQualificationSchema = z.object({
+    sessionId: z.string().uuid().describe("The qualification session ID"),
+});
+export function registerQualificationTools(server, client) {
+    // ==========================================
+    // discover_earning_opportunity
+    // ==========================================
+    const discoverInvoking = 'Setting up your earning profile...';
+    const discoverInvoked = 'Profile setup ready!';
+    const discoverHandler = async (args, _extra) => {
+        try {
+            // Detect intent and start qualification session
+            const result = await client.discoverEarningOpportunity({
+                userMessage: args.userMessage,
+                conversationContext: args.conversationContext,
+            });
+            const widgetSessionId = stableSessionId('qual', result.sessionId);
+            return {
+                structuredContent: {
+                    sessionId: result.sessionId,
+                    intentDetected: result.intentDetected,
+                    intentType: result.intentType,
+                    confidenceScore: result.confidenceScore,
+                    nextQuestion: result.nextPrompt?.text,
+                },
+                content: [
+                    {
+                        type: 'text',
+                        text: result.nextPrompt?.text ?? 'Let me help you get started with earning opportunities!',
+                    },
+                ],
+                _meta: {
+                    ...toolInvocationMeta(discoverInvoking, discoverInvoked, widgetSessionId),
+                    result,
+                },
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: `Error: ${err.message}` }],
+                isError: true,
+            };
+        }
+    };
+    // Register with multiple names for compatibility
+    for (const toolName of ['discover_earning_opportunity', 'qualification_start']) {
+        server.registerTool(toolName, {
+            title: 'Discover earning opportunities',
+            description: 'Detect when a user expresses interest in earning money and start a conversational qualification flow to build their profile. No OAuth required - works for new users.',
+            inputSchema: DiscoverEarningSchema,
+            annotations: {
+                readOnlyHint: false,
+                openWorldHint: false,
+                destructiveHint: false,
+            },
+            _meta: toolDescriptorMeta(discoverInvoking, discoverInvoked),
+        }, discoverHandler);
+    }
+    // ==========================================
+    // continue_qualification
+    // ==========================================
+    const continueInvoking = 'Processing your response...';
+    const continueInvoked = 'Ready for next step';
+    const continueHandler = async (args, _extra) => {
+        try {
+            const result = await client.continueQualification(args.sessionId, args.userResponse);
+            const widgetSessionId = stableSessionId('qual', args.sessionId);
+            // Check if qualification is complete
+            if (result.status === 'completed' || result.completionScore >= 0.75) {
+                return {
+                    structuredContent: {
+                        sessionId: args.sessionId,
+                        status: 'completed',
+                        completionScore: result.completionScore,
+                        profileSummary: result.profileSummary,
+                    },
+                    content: [
+                        {
+                            type: 'text',
+                            text: result.nextPrompt?.text ?? `Great! Your profile is now ${Math.round(result.completionScore * 100)}% complete. You're all set to start receiving task opportunities!`,
+                        },
+                    ],
+                    _meta: {
+                        ...toolInvocationMeta(continueInvoking, continueInvoked, widgetSessionId),
+                        result,
+                    },
+                };
+            }
+            return {
+                structuredContent: {
+                    sessionId: args.sessionId,
+                    status: result.status,
+                    currentStage: result.currentStage,
+                    completionScore: result.completionScore,
+                    questionCount: result.questionCount,
+                    nextQuestion: result.nextPrompt?.text,
+                },
+                content: [
+                    {
+                        type: 'text',
+                        text: result.nextPrompt?.text ?? 'Thanks! What else would you like to share?',
+                    },
+                ],
+                _meta: {
+                    ...toolInvocationMeta(continueInvoking, continueInvoked, widgetSessionId),
+                    result,
+                },
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: `Error: ${err.message}` }],
+                isError: true,
+            };
+        }
+    };
+    for (const toolName of ['continue_qualification', 'qualification_continue']) {
+        server.registerTool(toolName, {
+            title: 'Continue qualification',
+            description: 'Submit a user response and get the next qualification question. Use this to continue the conversational profile-building flow.',
+            inputSchema: ContinueQualificationSchema,
+            annotations: {
+                readOnlyHint: false,
+                openWorldHint: false,
+                destructiveHint: false,
+            },
+            _meta: toolDescriptorMeta(continueInvoking, continueInvoked),
+        }, continueHandler);
+    }
+    // ==========================================
+    // get_qualification_status
+    // ==========================================
+    const statusInvoking = 'Checking qualification progress...';
+    const statusInvoked = 'Status retrieved';
+    const statusHandler = async (args, _extra) => {
+        try {
+            const result = await client.getQualificationStatus(args.sessionId);
+            const widgetSessionId = stableSessionId('qual', args.sessionId);
+            return {
+                structuredContent: {
+                    sessionId: args.sessionId,
+                    status: result.status,
+                    currentStage: result.currentStage,
+                    completionScore: result.completionScore,
+                    questionCount: result.questionCount,
+                    extractedSkills: result.extractedSkills,
+                    extractedLocation: result.extractedLocation,
+                },
+                content: [
+                    {
+                        type: 'text',
+                        text: `Profile is ${Math.round(result.completionScore * 100)}% complete. Current stage: ${result.currentStage}`,
+                    },
+                ],
+                _meta: {
+                    ...toolInvocationMeta(statusInvoking, statusInvoked, widgetSessionId),
+                    result,
+                },
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: `Error: ${err.message}` }],
+                isError: true,
+            };
+        }
+    };
+    for (const toolName of ['get_qualification_status', 'qualification_status']) {
+        server.registerTool(toolName, {
+            title: 'Get qualification status',
+            description: 'Check the progress of a qualification session including completion score and extracted profile data.',
+            inputSchema: GetQualificationStatusSchema,
+            annotations: {
+                readOnlyHint: true,
+                openWorldHint: false,
+                destructiveHint: false,
+            },
+            _meta: toolDescriptorMeta(statusInvoking, statusInvoked),
+        }, statusHandler);
+    }
+    // ==========================================
+    // complete_qualification
+    // ==========================================
+    const completeInvoking = 'Finalizing your profile...';
+    const completeInvoked = 'Profile complete!';
+    const completeHandler = async (args, _extra) => {
+        try {
+            const result = await client.completeQualification(args.sessionId);
+            const widgetSessionId = stableSessionId('qual', args.sessionId);
+            return {
+                structuredContent: {
+                    sessionId: args.sessionId,
+                    status: 'completed',
+                    profileId: result.workerProfileId,
+                    completionScore: result.completionScore,
+                },
+                content: [
+                    {
+                        type: 'text',
+                        text: `🎉 Your profile is complete! You'll now start seeing task opportunities that match your skills. Welcome to Haptic!`,
+                    },
+                ],
+                _meta: {
+                    ...toolInvocationMeta(completeInvoking, completeInvoked, widgetSessionId),
+                    result,
+                },
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: `Error: ${err.message}` }],
+                isError: true,
+            };
+        }
+    };
+    for (const toolName of ['complete_qualification', 'qualification_complete']) {
+        server.registerTool(toolName, {
+            title: 'Complete qualification',
+            description: 'Finalize a qualification session and activate the worker profile.',
+            inputSchema: CompleteQualificationSchema,
+            annotations: {
+                readOnlyHint: false,
+                openWorldHint: false,
+                destructiveHint: false,
+            },
+            _meta: toolDescriptorMeta(completeInvoking, completeInvoked),
+        }, completeHandler);
+    }
+}

package/dist/tools/tasks.js

@@ -0,0 +1,246 @@
+import { z } from "zod";
+import { requireScopes } from "../auth/access.js";
+import crypto from 'node:crypto';
+const OUTPUT_TEMPLATE = 'ui://widget/hirehuman.html';
+function stableSessionId(prefix, value) {
+    const raw = value ?? 'unknown';
+    const hash = crypto.createHash('sha256').update(raw).digest('hex').slice(0, 16);
+    return `${prefix}:${hash}`;
+}
+function oauthSecuritySchemes(scopes) {
+    return [
+        {
+            type: 'oauth2',
+            scopes,
+        },
+    ];
+}
+function toolDescriptorMeta(invoking, invoked, scopes) {
+    return {
+        'openai/outputTemplate': OUTPUT_TEMPLATE,
+        'openai/toolInvocation/invoking': invoking,
+        'openai/toolInvocation/invoked': invoked,
+        'openai/widgetAccessible': true,
+        securitySchemes: oauthSecuritySchemes(scopes),
+    };
+}
+function toolInvocationMeta(invoking, invoked, widgetSessionId) {
+    return {
+        'openai/toolInvocation/invoking': invoking,
+        'openai/toolInvocation/invoked': invoked,
+        'openai/widgetSessionId': widgetSessionId,
+    };
+}
+const CreateTaskSchema = z.object({
+    title: z.string().min(5).max(200).describe("Short title for the task"),
+    description: z.string().min(20).max(5000).describe("Detailed description of what needs to be done"),
+    budget: z.number().min(5).max(500).describe("Payment to worker in dollars"),
+    location: z.object({
+        address: z.string().describe("Street address where task will be performed"),
+        city: z.string().optional(),
+        state: z.string().optional(),
+        zip: z.string().optional(),
+    }).optional().describe("Location for physical tasks"),
+    deadline: z.string().datetime().optional().describe("When the task must be completed by"),
+    requirements: z.object({
+        proofOfWork: z.boolean().default(true),
+        gpsRequired: z.boolean().default(true)
+    }).optional(),
+});
+export function registerTaskTools(server, client) {
+    const createTaskInvoking = 'Creating your task';
+    const createTaskInvoked = 'Task created';
+    const createTaskHandler = async (args, extra) => {
+        try {
+            const auth = requireScopes(extra, ['tasks:write']);
+            const task = await client.createTask(args, auth.token);
+            const widgetSessionId = `task:${task.id}`;
+            return {
+                structuredContent: {
+                    task: {
+                        id: task.id,
+                        title: task.title,
+                        status: task.status,
+                        budget: task.budget,
+                    },
+                },
+                content: [{ type: 'text', text: `Created task “${task.title}” (ID: ${task.id}).` }],
+                _meta: {
+                    ...toolInvocationMeta(createTaskInvoking, createTaskInvoked, widgetSessionId),
+                    task,
+                },
+            };
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error creating task: ${err.response?.data?.error?.message || err.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    };
+    for (const toolName of ['create_task', 'tasks_create']) {
+        server.registerTool(toolName, {
+            title: 'Create a task',
+            description: 'Create a new task for a human worker. This is a write action and may charge the user.',
+            inputSchema: CreateTaskSchema,
+            annotations: {
+                readOnlyHint: false,
+                openWorldHint: false,
+                destructiveHint: false,
+            },
+            _meta: toolDescriptorMeta(createTaskInvoking, createTaskInvoked, ['tasks:write']),
+        }, createTaskHandler);
+    }
+    const getTaskInvoking = 'Fetching task details';
+    const getTaskInvoked = 'Task details ready';
+    const getTaskHandler = async (args, extra) => {
+        try {
+            const auth = requireScopes(extra, ['tasks:read']);
+            const task = await client.getTask(args.taskId, auth.token);
+            const widgetSessionId = `task:${args.taskId}`;
+            return {
+                structuredContent: {
+                    task: {
+                        id: task.id,
+                        title: task.title,
+                        status: task.status,
+                        budget: task.budget,
+                    },
+                },
+                content: [{ type: 'text', text: `Task ${task.id}: ${task.status}` }],
+                _meta: {
+                    ...toolInvocationMeta(getTaskInvoking, getTaskInvoked, widgetSessionId),
+                    task,
+                },
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: `Error: ${err.message}` }],
+                isError: true,
+            };
+        }
+    };
+    for (const toolName of ['get_task', 'tasks_get']) {
+        server.registerTool(toolName, {
+            title: 'Get task',
+            description: 'Get details of a task by ID.',
+            inputSchema: z.object({ taskId: z.string().uuid() }),
+            annotations: {
+                readOnlyHint: true,
+                openWorldHint: false,
+                destructiveHint: false,
+            },
+            _meta: toolDescriptorMeta(getTaskInvoking, getTaskInvoked, ['tasks:read']),
+        }, getTaskHandler);
+    }
+    const listTasksInvoking = 'Loading your tasks';
+    const listTasksInvoked = 'Tasks loaded';
+    const listTasksHandler = async (args, extra) => {
+        try {
+            const auth = requireScopes(extra, ['tasks:read']);
+            const tasks = await client.listTasks(args, auth.token);
+            const items = Array.isArray(tasks) ? tasks : tasks?.tasks ?? [];
+            const widgetSessionId = stableSessionId('tasks', auth.userId ?? auth.clientId);
+            if (items.length === 0) {
+                return {
+                    structuredContent: { tasks: [] },
+                    content: [{ type: 'text', text: 'No tasks found.' }],
+                    _meta: {
+                        ...toolInvocationMeta(listTasksInvoking, listTasksInvoked, widgetSessionId),
+                        tasks: items,
+                    },
+                };
+            }
+            const summary = items
+                .map((t) => `- [${t.status}] ${t.title} ($${t.budget}) (ID: ${t.id})`)
+                .join('\n');
+            return {
+                structuredContent: {
+                    tasks: items.map((t) => ({
+                        id: t.id,
+                        title: t.title,
+                        status: t.status,
+                        budget: t.budget,
+                    })),
+                },
+                content: [{ type: 'text', text: `My tasks:\n${summary}` }],
+                _meta: {
+                    ...toolInvocationMeta(listTasksInvoking, listTasksInvoked, widgetSessionId),
+                    tasks: items,
+                },
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: `Error: ${err.message}` }],
+                isError: true,
+            };
+        }
+    };
+    for (const toolName of ['list_my_tasks', 'tasks_list']) {
+        server.registerTool(toolName, {
+            title: 'List my tasks',
+            description: 'List tasks created by the current user.',
+            inputSchema: z.object({
+                status: z.enum(['open', 'assigned', 'completed', 'cancelled']).optional(),
+                limit: z.number().min(1).max(50).optional(),
+            }),
+            annotations: {
+                readOnlyHint: true,
+                openWorldHint: false,
+                destructiveHint: false,
+            },
+            _meta: toolDescriptorMeta(listTasksInvoking, listTasksInvoked, ['tasks:read']),
+        }, listTasksHandler);
+    }
+    const cancelTaskInvoking = 'Cancelling task';
+    const cancelTaskInvoked = 'Task cancelled';
+    const cancelTaskHandler = async (args, extra) => {
+        try {
+            const auth = requireScopes(extra, ['tasks:write']);
+            const res = await client.cancelTask(args.taskId, args.reason, auth.token);
+            const widgetSessionId = `task:${args.taskId}`;
+            return {
+                structuredContent: {
+                    taskId: args.taskId,
+                    refunded: Boolean(res?.refunded),
+                },
+                content: [
+                    {
+                        type: 'text',
+                        text: `Cancelled task ${args.taskId}. Refunded: ${res?.refunded ? 'Yes' : 'No'}`,
+                    },
+                ],
+                _meta: {
+                    ...toolInvocationMeta(cancelTaskInvoking, cancelTaskInvoked, widgetSessionId),
+                    result: res,
+                },
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: `Error: ${err.message}` }],
+                isError: true,
+            };
+        }
+    };
+    for (const toolName of ['cancel_task', 'tasks_cancel']) {
+        server.registerTool(toolName, {
+            title: 'Cancel task',
+            description: 'Cancel a pending task. This is a write action and may have irreversible side effects.',
+            inputSchema: z.object({ taskId: z.string().uuid(), reason: z.string().optional() }),
+            annotations: {
+                readOnlyHint: false,
+                openWorldHint: false,
+                destructiveHint: true,
+            },
+            _meta: toolDescriptorMeta(cancelTaskInvoking, cancelTaskInvoked, ['tasks:write']),
+        }, cancelTaskHandler);
+    }
+}

package/dist/tools/workers.js

@@ -0,0 +1,139 @@
+import { z } from "zod";
+import { requireScopes } from "../auth/access.js";
+import crypto from 'node:crypto';
+const OUTPUT_TEMPLATE = 'ui://widget/hirehuman.html';
+function stableSessionId(prefix, value) {
+    const raw = value ?? 'unknown';
+    const hash = crypto.createHash('sha256').update(raw).digest('hex').slice(0, 16);
+    return `${prefix}:${hash}`;
+}
+function oauthSecuritySchemes(scopes) {
+    return [
+        {
+            type: 'oauth2',
+            scopes,
+        },
+    ];
+}
+function toolDescriptorMeta(invoking, invoked, scopes) {
+    return {
+        'openai/outputTemplate': OUTPUT_TEMPLATE,
+        'openai/toolInvocation/invoking': invoking,
+        'openai/toolInvocation/invoked': invoked,
+        'openai/widgetAccessible': true,
+        securitySchemes: oauthSecuritySchemes(scopes),
+    };
+}
+function toolInvocationMeta(invoking, invoked, widgetSessionId) {
+    return {
+        'openai/toolInvocation/invoking': invoking,
+        'openai/toolInvocation/invoked': invoked,
+        'openai/widgetSessionId': widgetSessionId,
+    };
+}
+const SearchWorkersSchema = z.object({
+    taskDescription: z.string().describe("Description of what needs to be done"),
+    location: z.object({
+        address: z.string(),
+        radiusMiles: z.number().default(10)
+    }).optional(),
+    skills: z.array(z.string()).optional()
+});
+export function registerWorkerTools(server, client) {
+    const searchWorkersInvoking = 'Searching nearby workers';
+    const searchWorkersInvoked = 'Worker results ready';
+    const searchWorkersHandler = async (args, extra) => {
+        try {
+            const auth = requireScopes(extra, ['workers:read']);
+            const result = await client.searchWorkers(args, auth.token);
+            const widgetSessionId = stableSessionId('workers', JSON.stringify({ userId: auth.userId ?? auth.clientId, args }));
+            if (!result.workers || result.workers.length === 0) {
+                return {
+                    structuredContent: { workers: [], suggestedBudget: result?.suggestedBudget },
+                    content: [{ type: 'text', text: 'No workers found matching criteria.' }],
+                    _meta: {
+                        ...toolInvocationMeta(searchWorkersInvoking, searchWorkersInvoked, widgetSessionId),
+                        result,
+                    },
+                };
+            }
+            return {
+                structuredContent: {
+                    workers: result.workers.map((w) => ({
+                        id: w.id,
+                        name: w.name,
+                        rating: w.rating,
+                        distanceMiles: w.distanceMiles,
+                        estimatedArrival: w.estimatedArrival,
+                    })),
+                    suggestedBudget: result.suggestedBudget,
+                },
+                content: [
+                    {
+                        type: 'text',
+                        text: `Found ${result.workers.length} workers. Suggested budget: $${result.suggestedBudget}`,
+                    },
+                ],
+                _meta: {
+                    ...toolInvocationMeta(searchWorkersInvoking, searchWorkersInvoked, widgetSessionId),
+                    result,
+                },
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: `Error: ${err.message}` }],
+                isError: true,
+            };
+        }
+    };
+    for (const toolName of ['search_workers', 'workers_search']) {
+        server.registerTool(toolName, {
+            title: 'Search workers',
+            description: 'Search for available workers. Returns anonymized profiles.',
+            inputSchema: SearchWorkersSchema,
+            annotations: {
+                readOnlyHint: true,
+                openWorldHint: false,
+                destructiveHint: false,
+            },
+            _meta: toolDescriptorMeta(searchWorkersInvoking, searchWorkersInvoked, ['workers:read']),
+        }, searchWorkersHandler);
+    }
+    const getWorkerInvoking = 'Loading worker profile';
+    const getWorkerInvoked = 'Worker profile ready';
+    const getWorkerProfileHandler = async (args, extra) => {
+        try {
+            const auth = requireScopes(extra, ['workers:read']);
+            const worker = await client.getWorkerProfile(args.workerId, auth.token);
+            const widgetSessionId = `worker:${args.workerId}`;
+            return {
+                structuredContent: { worker },
+                content: [{ type: 'text', text: `Worker profile loaded: ${worker?.id ?? args.workerId}` }],
+                _meta: {
+                    ...toolInvocationMeta(getWorkerInvoking, getWorkerInvoked, widgetSessionId),
+                    worker,
+                },
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: `Error: ${err.message}` }],
+                isError: true,
+            };
+        }
+    };
+    for (const toolName of ['get_worker_profile', 'workers_get_profile']) {
+        server.registerTool(toolName, {
+            title: 'Get worker profile',
+            description: 'Get a detailed worker profile by ID.',
+            inputSchema: z.object({ workerId: z.string().uuid() }),
+            annotations: {
+                readOnlyHint: true,
+                openWorldHint: false,
+                destructiveHint: false,
+            },
+            _meta: toolDescriptorMeta(getWorkerInvoking, getWorkerInvoked, ['workers:read']),
+        }, getWorkerProfileHandler);
+    }
+}