@hapticpaper/mcp-server 1.0.0

package/dist/index.js

@@ -0,0 +1,309 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { mcpAuthMetadataRouter, getOAuthProtectedResourceMetadataUrl } from "@modelcontextprotocol/sdk/server/auth/router.js";
+import { requireBearerAuth } from "@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js";
+import dotenv from 'dotenv';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import jwt from 'jsonwebtoken';
+import { HireHumanClient } from "./client/hireHumanClient.js";
+import { registerAllTools } from "./tools/index.js";
+import { registerAllResources } from "./resources/index.js";
+import { TokenManager, MCPOAuthHandler } from "./auth/oauth.js";
+dotenv.config();
+async function main() {
+    const args = process.argv.slice(2);
+    const command = args[0];
+    const tokenManager = new TokenManager();
+    if (command === 'auth') {
+        // Run Auth Flow
+        console.error('Starting Authentication Flow...');
+        const auth = new MCPOAuthHandler({
+            clientId: 'mcp-client', // Matches seedMcpClient.ts
+            authorizationUrl: process.env.AUTH_URL || 'https://hapticpaper.com/oauth/authorize',
+            tokenUrl: process.env.TOKEN_URL || 'https://hapticpaper.com/api/v1/oauth/token',
+            redirectUri: 'http://localhost:8765/callback',
+            scopes: ['tasks:read', 'tasks:write', 'workers:read']
+        });
+        try {
+            const tokens = await auth.authenticate();
+            await tokenManager.saveTokens(tokens);
+            console.error('Authentication successful! Token saved.');
+            process.exit(0);
+        }
+        catch (error) {
+            console.error('Authentication failed:', error);
+            process.exit(1);
+        }
+    }
+    function registerWidgetTemplate(server) {
+        // The widget bundle is built by packages/mcp-server/web and inlined into the HTML template.
+        const widgetBundlePath = path.resolve(process.cwd(), 'web', 'dist', 'widget.js');
+        if (!fs.existsSync(widgetBundlePath)) {
+            console.error(`[MCP] Widget bundle not found at ${widgetBundlePath}. Run: (cd packages/mcp-server/web && npm run build)`);
+            return;
+        }
+        const widgetJs = fs.readFileSync(widgetBundlePath, 'utf8');
+        server.registerResource('hirehuman-widget', 'ui://widget/hirehuman.html', {}, async () => ({
+            contents: [
+                {
+                    uri: 'ui://widget/hirehuman.html',
+                    mimeType: 'text/html+skybridge',
+                    text: `
+<div id="hirehuman-root"></div>
+<style>
+  :root { color-scheme: light dark; }
+  body { margin: 0; font-family: ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Helvetica, Arial; }
+  #hirehuman-root { padding: 12px; }
+  .hh-title { font-size: 14px; font-weight: 600; margin-bottom: 8px; }
+  .hh-muted { opacity: 0.7; font-size: 12px; }
+  .hh-card { border: 1px solid rgba(127,127,127,0.25); border-radius: 12px; padding: 10px; margin: 8px 0; }
+  .hh-row { display: flex; justify-content: space-between; gap: 12px; align-items: center; }
+  .hh-btn { border: 1px solid rgba(127,127,127,0.35); border-radius: 10px; padding: 6px 10px; background: transparent; cursor: pointer; }
+  .hh-btn:disabled { opacity: 0.6; cursor: not-allowed; }
+  .hh-pill { font-size: 12px; padding: 2px 8px; border-radius: 999px; border: 1px solid rgba(127,127,127,0.35); }
+  .hh-grid { display: grid; grid-template-columns: 1fr; gap: 8px; }
+</style>
+<script type="module">
+${widgetJs}
+</script>
+                        `.trim(),
+                    _meta: {
+                        'openai/widgetPrefersBorder': true,
+                        'openai/widgetDomain': 'https://chatgpt.com',
+                        'openai/widgetDescription': 'Shows interactive task and worker results for Hire-a-Human tools.',
+                        'openai/widgetCSP': {
+                            connect_domains: ['https://chatgpt.com'],
+                            resource_domains: ['https://*.oaistatic.com'],
+                        },
+                    },
+                },
+            ],
+        }));
+    }
+    function createMcpServer(client) {
+        const server = new McpServer({
+            name: "hire-a-human",
+            version: "1.0.0"
+        });
+        registerWidgetTemplate(server);
+        registerAllTools(server, client);
+        registerAllResources(server, client);
+        return server;
+    }
+    // Initialize Client
+    const client = new HireHumanClient({
+        baseUrl: process.env.API_URL || 'https://hapticpaper.com/api/v1',
+        tokenProvider: async () => {
+            const tokens = await tokenManager.loadTokens();
+            return tokens?.access_token || '';
+        }
+    });
+    // Transport
+    const transportType = process.env.MCP_TRANSPORT || 'stdio';
+    if (transportType === 'http') {
+        const host = process.env.HOST || '127.0.0.1';
+        const port = Number(process.env.PORT || 3001);
+        const app = createMcpExpressApp({
+            host,
+            allowedHosts: process.env.MCP_ALLOWED_HOSTS?.split(',').map((s) => s.trim()).filter(Boolean),
+        });
+        // Use standard Express API to enable trust proxy for Cloud Run
+        app.set('trust proxy', 1);
+        const configuredResourceUrl = process.env.RESOURCE_SERVER_URL;
+        const resourceServerUrl = new URL(configuredResourceUrl || `http://${host}:${port}/mcp`);
+        // MCP spec: authorization base URL is the MCP server origin (path stripped)
+        // e.g., https://mcp.hapticpaper.com for MCP server at https://mcp.hapticpaper.com/mcp
+        const mcpOrigin = resourceServerUrl.origin;
+        // Backend OAuth endpoints
+        const backendBaseUrl = process.env.BACKEND_PUBLIC_URL || process.env.API_URL?.replace(/\/api\/v1\/?$/, '') || 'http://localhost:3000';
+        const backendOAuthBase = `${backendBaseUrl}/api/v1/oauth`;
+        const scopesSupported = ['tasks:read', 'tasks:write', 'workers:read'];
+        // RFC 8414: OAuth Authorization Server Metadata
+        // MCP spec says this MUST be at {authorization_base_url}/.well-known/oauth-authorization-server
+        app.get('/.well-known/oauth-authorization-server', (_req, res) => {
+            res.json({
+                issuer: mcpOrigin,
+                authorization_endpoint: `${backendOAuthBase}/authorize`,
+                token_endpoint: `${backendOAuthBase}/token`,
+                registration_endpoint: `${mcpOrigin}/register`,
+                response_types_supported: ['code'],
+                grant_types_supported: ['authorization_code', 'refresh_token'],
+                token_endpoint_auth_methods_supported: ['client_secret_post', 'client_secret_basic', 'none'],
+                code_challenge_methods_supported: ['S256', 'plain'],
+                scopes_supported: scopesSupported,
+            });
+        });
+        // RFC 7591: Dynamic Client Registration
+        // Proxy to backend
+        app.post('/register', async (req, res) => {
+            try {
+                const response = await fetch(`${backendOAuthBase}/register`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify(req.body),
+                });
+                const data = await response.json();
+                res.status(response.status).json(data);
+            }
+            catch (error) {
+                console.error('[MCP] Registration proxy error:', error);
+                res.status(500).json({ error: 'Registration failed' });
+            }
+        });
+        // For legacy/SDK compatibility
+        const issuer = mcpOrigin;
+        const oauthMetadata = {
+            issuer,
+            authorization_endpoint: `${backendOAuthBase}/authorize`,
+            token_endpoint: `${backendOAuthBase}/token`,
+            registration_endpoint: `${mcpOrigin}/register`,
+            response_types_supported: ['code'],
+            grant_types_supported: ['authorization_code', 'refresh_token'],
+            token_endpoint_auth_methods_supported: ['client_secret_post', 'client_secret_basic', 'none'],
+        };
+        const authMetadataDisabled = String(process.env.MCP_AUTH_METADATA_DISABLED || '').toLowerCase() === 'true';
+        const canAdvertiseAuthMetadata = issuer.startsWith('https://') && resourceServerUrl.protocol === 'https:';
+        const shouldAdvertiseAuthMetadata = !authMetadataDisabled && canAdvertiseAuthMetadata;
+        // Always serve protected resource metadata at the expected URL so MCP clients
+        // (including VS Code and ChatGPT) can start the OAuth handshake.
+        const protectedResourceMetadataUrl = getOAuthProtectedResourceMetadataUrl(resourceServerUrl);
+        const protectedResourceMetadataPath = new URL(protectedResourceMetadataUrl).pathname;
+        app.get(protectedResourceMetadataPath, (_req, res) => {
+            res.json({
+                resource: resourceServerUrl.toString(),
+                authorization_servers: [issuer],
+                scopes_supported: scopesSupported,
+                resource_name: 'Hire-a-Human MCP',
+            });
+        });
+        if (shouldAdvertiseAuthMetadata) {
+            // Advertise MCP auth metadata (RFC 9728 protected-resource metadata, etc.)
+            app.use(mcpAuthMetadataRouter({
+                oauthMetadata,
+                resourceServerUrl,
+                scopesSupported,
+                resourceName: 'Hire-a-Human MCP',
+            }));
+        }
+        else if (!authMetadataDisabled) {
+            console.error(`[MCP] Auth metadata not advertised because URLs are not HTTPS. ` +
+                `Set RESOURCE_SERVER_URL and AUTHORIZATION_SERVER_ISSUER to https://... (recommended for ChatGPT Connectors), ` +
+                `or set MCP_AUTH_METADATA_DISABLED=true for local dev. ` +
+                `(issuer=${issuer}, resourceServerUrl=${resourceServerUrl.toString()})`);
+        }
+        const tokenVerifier = {
+            verifyAccessToken: async (token) => {
+                const secret = process.env.JWT_SECRET;
+                if (!secret) {
+                    throw new Error('Server misconfigured: JWT_SECRET is not set');
+                }
+                const decoded = jwt.verify(token, secret);
+                if (!decoded || typeof decoded !== 'object') {
+                    throw new Error('Invalid token');
+                }
+                const scopeStr = typeof decoded.scope === 'string' ? decoded.scope : '';
+                const permissions = Array.isArray(decoded.permissions) ? decoded.permissions : [];
+                const scopes = [
+                    ...scopeStr.split(/\s+/).map((s) => s.trim()).filter(Boolean),
+                    ...permissions.map((s) => (typeof s === 'string' ? s.trim() : '')).filter(Boolean),
+                ];
+                const exp = decoded.exp;
+                return {
+                    token,
+                    clientId: decoded.client_id || 'unknown',
+                    scopes: Array.from(new Set(scopes)),
+                    expiresAt: typeof exp === 'number' ? exp : Math.floor(Date.now() / 1000) + 3600,
+                };
+            },
+        };
+        const authMiddleware = requireBearerAuth({
+            verifier: tokenVerifier,
+            requiredScopes: [],
+            resourceMetadataUrl: protectedResourceMetadataUrl,
+        });
+        const transports = {};
+        const shouldRequireAuth = (req) => {
+            // Only POST requests perform JSON-RPC actions. GET/DELETE are session transport mechanics.
+            if (req.method !== 'POST')
+                return false;
+            // Allow unauthenticated initialize + listing so clients can discover tools/resources.
+            const body = req.body;
+            if (isInitializeRequest(body))
+                return false;
+            const method = body?.method;
+            if (method === 'tools/list' || method === 'resources/list' || method === 'prompts/list')
+                return false;
+            // Require OAuth for tool calls and everything else.
+            return true;
+        };
+        app.use('/mcp', (req, res, next) => {
+            if (!shouldRequireAuth(req))
+                return next();
+            return authMiddleware(req, res, next);
+        });
+        const handleMcpRequest = async (req, res) => {
+            const sessionId = req.headers['mcp-session-id'];
+            let transport;
+            if (sessionId && transports[sessionId]) {
+                transport = transports[sessionId];
+            }
+            else if (!sessionId && req.method === 'POST' && isInitializeRequest(req.body)) {
+                transport = new StreamableHTTPServerTransport({
+                    sessionIdGenerator: () => crypto.randomUUID(),
+                    onsessioninitialized: (newSessionId) => {
+                        transports[newSessionId] = transport;
+                    },
+                });
+                transport.onclose = () => {
+                    if (transport?.sessionId) {
+                        delete transports[transport.sessionId];
+                    }
+                };
+                const server = createMcpServer(client);
+                await server.connect(transport);
+            }
+            else {
+                res.status(400).json({
+                    jsonrpc: '2.0',
+                    error: {
+                        code: -32000,
+                        message: 'Bad Request: No valid session ID provided',
+                    },
+                    id: null,
+                });
+                return;
+            }
+            await transport.handleRequest(req, res, req.body);
+        };
+        const handleSessionRequest = async (req, res) => {
+            const sessionId = req.headers['mcp-session-id'];
+            if (!sessionId || !transports[sessionId]) {
+                res.status(400).send('Invalid or missing session ID');
+                return;
+            }
+            await transports[sessionId].handleRequest(req, res);
+        };
+        app.post('/mcp', handleMcpRequest);
+        app.get('/mcp', handleSessionRequest);
+        app.delete('/mcp', handleSessionRequest);
+        app.listen(port, host, () => {
+            console.error(`MCP Server listening on http://${host}:${port}/mcp`);
+            console.error(`OAuth resource metadata: ${getOAuthProtectedResourceMetadataUrl(resourceServerUrl)}`);
+        });
+    }
+    else {
+        const transport = new StdioServerTransport();
+        const server = createMcpServer(client);
+        await server.connect(transport);
+        console.error('MCP Server running on stdio');
+    }
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/dist/resources/index.js

@@ -0,0 +1,31 @@
+const TEMPLATES_URI = "hirehuman://templates";
+const templates = [
+    {
+        id: "moving",
+        name: "Moving Help",
+        description: "Help moving furniture or boxes",
+        priceRange: "$40-80",
+        typicalDuration: "2-4 hours"
+    },
+    {
+        id: "cleaning",
+        name: "House Cleaning",
+        description: "Standard house cleaning",
+        priceRange: "$80-150",
+        typicalDuration: "3-5 hours"
+    }
+];
+export function registerAllResources(server, _client) {
+    server.registerResource('task-templates', TEMPLATES_URI, {
+        title: 'Task Templates',
+        description: 'List of common task templates with pricing guidance',
+    }, async () => ({
+        contents: [
+            {
+                uri: TEMPLATES_URI,
+                mimeType: 'application/json',
+                text: JSON.stringify(templates, null, 2),
+            },
+        ],
+    }));
+}

package/dist/tools/account.js

@@ -0,0 +1,86 @@
+import { z } from "zod";
+import { requireScopes } from "../auth/access.js";
+const OUTPUT_TEMPLATE = 'ui://widget/hirehuman.html';
+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,
+    };
+}
+// No input needed - just returns current user's account info
+const GetAccountSchema = z.object({}).describe("No parameters required");
+export function registerAccountTools(server, client) {
+    const getAccountInvoking = 'Fetching your account details';
+    const getAccountInvoked = 'Account details ready';
+    const getAccountHandler = async (_args, extra) => {
+        try {
+            const auth = requireScopes(extra, ['account:read']);
+            const result = await client.getAccount(auth.token);
+            const account = result.data;
+            const widgetSessionId = `account:${account.userId}`;
+            return {
+                structuredContent: {
+                    account: {
+                        displayName: account.displayName,
+                        email: account.email,
+                        balanceDollars: account.balanceDollars,
+                        hasPaymentMethod: account.hasPaymentMethod,
+                    },
+                },
+                content: [
+                    {
+                        type: 'text',
+                        text: `Welcome, ${account.displayName}! Your Haptic Paper balance is $${account.balanceDollars.toFixed(2)}.${account.hasPaymentMethod ? '' : ' Add a payment method to create paid tasks.'}`,
+                    },
+                ],
+                _meta: {
+                    ...toolInvocationMeta(getAccountInvoking, getAccountInvoked, widgetSessionId),
+                    account,
+                },
+            };
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error fetching account: ${err.response?.data?.error?.message || err.message || 'Unknown error'}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    };
+    // Register as both naming conventions for compatibility
+    for (const toolName of ['get_account', 'account_get']) {
+        server.registerTool(toolName, {
+            title: 'Get account details',
+            description: 'Get your Haptic Paper account information including display name, email, and credit balance. Use this to check how much credit is available for creating tasks.',
+            inputSchema: GetAccountSchema,
+            annotations: {
+                readOnlyHint: true,
+                openWorldHint: false,
+                destructiveHint: false,
+            },
+            _meta: toolDescriptorMeta(getAccountInvoking, getAccountInvoked, ['account:read']),
+        }, getAccountHandler);
+    }
+}

package/dist/tools/estimates.js

@@ -0,0 +1,123 @@
+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,
+    };
+}
+export function registerEstimateTools(server, client) {
+    const getEstimateInvoking = 'Calculating estimate';
+    const getEstimateInvoked = 'Estimate ready';
+    const getEstimateHandler = async (args, extra) => {
+        try {
+            const auth = requireScopes(extra, ['tasks:read']);
+            const est = await client.getEstimate(args, auth.token);
+            const widgetSessionId = stableSessionId('estimate', JSON.stringify({ userId: auth.userId ?? auth.clientId, args }));
+            return {
+                structuredContent: {
+                    estimate: {
+                        estimatedPrice: est.estimatedPrice,
+                        priceRange: est.priceRange,
+                        estimatedCompletionTime: est.estimatedCompletionTime,
+                        workersAvailable: est.workersAvailable,
+                    },
+                },
+                content: [
+                    {
+                        type: 'text',
+                        text: `Estimate: $${est.estimatedPrice} (${est.priceRange?.min}-${est.priceRange?.max}), time: ${est.estimatedCompletionTime}`,
+                    },
+                ],
+                _meta: {
+                    ...toolInvocationMeta(getEstimateInvoking, getEstimateInvoked, widgetSessionId),
+                    estimate: est,
+                },
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: `Error: ${err.message}` }],
+                isError: true,
+            };
+        }
+    };
+    for (const toolName of ['get_estimate', 'estimates_get']) {
+        server.registerTool(toolName, {
+            title: 'Get estimate',
+            description: 'Get a price and time estimate for a task. Recommended before creating a task.',
+            inputSchema: z.object({
+                description: z.string().describe('Task description'),
+                urgency: z.enum(['flexible', 'today', 'urgent']).optional(),
+                location: z.object({ address: z.string() }).optional(),
+            }),
+            annotations: {
+                readOnlyHint: true,
+                openWorldHint: false,
+                destructiveHint: false,
+            },
+            _meta: toolDescriptorMeta(getEstimateInvoking, getEstimateInvoked, ['tasks:read']),
+        }, getEstimateHandler);
+    }
+    const listSkillsInvoking = 'Loading skill categories';
+    const listSkillsInvoked = 'Skill categories ready';
+    const listSkillCategoriesHandler = async (_args, extra) => {
+        try {
+            const auth = requireScopes(extra, ['tasks:read']);
+            const cats = await client.getSkillCategories();
+            const widgetSessionId = stableSessionId('skills', auth.userId ?? auth.clientId);
+            const text = cats
+                .map((c) => `### ${c.name}\n${c.description}\nRange: $${c.priceRange.min}-$${c.priceRange.max}`)
+                .join('\n\n');
+            return {
+                structuredContent: { categories: cats },
+                content: [{ type: 'text', text }],
+                _meta: {
+                    ...toolInvocationMeta(listSkillsInvoking, listSkillsInvoked, widgetSessionId),
+                    categories: cats,
+                },
+            };
+        }
+        catch (err) {
+            return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+        }
+    };
+    for (const toolName of ['list_skill_categories', 'skills_list_categories']) {
+        server.registerTool(toolName, {
+            title: 'List skill categories',
+            description: 'List available skill categories and typical pricing ranges.',
+            inputSchema: z.object({}),
+            annotations: {
+                readOnlyHint: true,
+                openWorldHint: false,
+                destructiveHint: false,
+            },
+            _meta: toolDescriptorMeta(listSkillsInvoking, listSkillsInvoked, ['tasks:read']),
+        }, listSkillCategoriesHandler);
+    }
+}

package/dist/tools/index.js

@@ -0,0 +1,12 @@
+import { registerTaskTools } from "./tasks.js";
+import { registerWorkerTools } from "./workers.js";
+import { registerEstimateTools } from "./estimates.js";
+import { registerQualificationTools } from "./qualification.js";
+import { registerAccountTools } from "./account.js";
+export function registerAllTools(server, client) {
+    registerAccountTools(server, client);
+    registerTaskTools(server, client);
+    registerWorkerTools(server, client);
+    registerEstimateTools(server, client);
+    registerQualificationTools(server, client);
+}