humanpages 1.3.0 → 1.4.1

package/dist/tools.js

@@ -1,33 +1,6 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-import { readFileSync } from 'fs';
-import { join, dirname } from 'path';
-import { fileURLToPath } from 'url';
-const API_BASE = process.env.API_BASE_URL || 'http://localhost:3001';
-const PLAYBOOKS = [
-    { type: 'directory-submissions', name: 'Directory & Listing Submissions', description: 'Submit your product to 80+ directories with CAPTCHAs, manual forms, and account creation. Includes a curated directory list.' },
-    { type: 'qa-testing', name: 'Real-Device QA Testing', description: 'Test your app on real phones, browsers, and networks. Get bug reports with screenshots and device info.' },
-    { type: 'competitor-monitoring', name: 'Competitor Monitoring', description: 'Track competitor pricing, features, and changes — including pages gated behind "contact sales."' },
-    { type: 'localization', name: 'Localization Smoke Testing', description: 'Native speaker flags mistranslations, cultural mismatches, and text overflow in your localized app.' },
-    { type: 'community-management', name: 'Community Management', description: 'Moderate your Discord, subreddit, or forum. Welcome members, answer questions, enforce rules.' },
-];
-const PLAYBOOK_TYPES = PLAYBOOKS.map(p => p.type);
-function getPlaybookContent(taskType) {
-    // Try to find playbooks relative to the compiled output (dist/) or source
-    const possibleBases = [
-        join(dirname(fileURLToPath(import.meta.url)), '..', 'playbooks'),
-        join(dirname(fileURLToPath(import.meta.url)), 'playbooks'),
-    ];
-    for (const base of possibleBases) {
-        try {
-            return readFileSync(join(base, `${taskType}.md`), 'utf-8');
-        }
-        catch {
-            continue;
-        }
-    }
-    throw new Error(`Playbook not found: ${taskType}. Available: ${PLAYBOOK_TYPES.join(', ')}`);
-}
+const API_BASE = process.env.API_BASE_URL || 'https://api.humanpages.ai';
 async function searchHumans(params) {
     const query = new URLSearchParams();
     if (params.skill)
@@ -54,6 +27,8 @@ async function searchHumans(params) {
         query.set('verified', params.verified);
     if (params.min_experience)
         query.set('minExperience', params.min_experience.toString());
+    if (params.fiat_platform)
+        query.set('fiatPlatform', params.fiat_platform);
     const res = await fetch(`${API_BASE}/api/humans/search?${query}`);
     if (!res.ok) {
         throw new Error(`API error: ${res.status}`);
@@ -135,6 +110,10 @@ export function createServer() {
                             type: 'number',
                             description: 'Minimum years of professional experience',
                         },
+                        fiat_platform: {
+                            type: 'string',
+                            description: 'Filter by fiat payment platform the human accepts (e.g., "WISE", "PAYPAL", "VENMO", "REVOLUT", "CASHAPP", "ZELLE", "MONZO", "N26", "MERCADOPAGO")',
+                        },
                     },
                 },
             },
@@ -178,6 +157,10 @@ export function createServer() {
                             type: 'string',
                             description: 'Webhook URL for receiving platform events (new job matches, status changes, announcements). Must be a public HTTPS endpoint.',
                         },
+                        wallet_address: {
+                            type: 'string',
+                            description: 'Optional EVM wallet address (0x...) for USDC payments. Can also be set later with set_wallet.',
+                        },
                     },
                     required: ['name'],
                 },
@@ -196,6 +179,51 @@ export function createServer() {
                     required: ['agent_id'],
                 },
             },
+            {
+                name: 'set_wallet',
+                description: 'Set the wallet address for a registered agent. This is used for receiving USDC payments and checking balance. The address must be a valid EVM address (0x + 40 hex chars). Network defaults to "base" (recommended for low fees).',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        agent_id: {
+                            type: 'string',
+                            description: 'Your registered agent ID',
+                        },
+                        agent_key: {
+                            type: 'string',
+                            description: 'Your agent API key (starts with hp_)',
+                        },
+                        wallet_address: {
+                            type: 'string',
+                            description: 'EVM wallet address (0x...)',
+                        },
+                        wallet_network: {
+                            type: 'string',
+                            enum: ['base', 'ethereum', 'polygon', 'arbitrum', 'base-sepolia'],
+                            description: 'Blockchain network (default: "base"). Options: base, ethereum, polygon, arbitrum',
+                        },
+                    },
+                    required: ['agent_id', 'agent_key', 'wallet_address'],
+                },
+            },
+            {
+                name: 'get_funding_info',
+                description: 'Get funding instructions and current wallet balance for a registered agent. Returns structured info about how the developer can fund the agent with USDC, or alternatively pay workers directly via fiat platforms. Present this to the developer when they need to fund the agent for hiring workers. Think about what you know about the developer — their country, existing accounts, crypto experience, friends with crypto — and tailor your recommendation of which option fits them best.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        agent_id: {
+                            type: 'string',
+                            description: 'Your registered agent ID',
+                        },
+                        agent_key: {
+                            type: 'string',
+                            description: 'Your agent API key (starts with hp_)',
+                        },
+                    },
+                    required: ['agent_id', 'agent_key'],
+                },
+            },
             {
                 name: 'verify_agent_domain',
                 description: 'Verify domain ownership for a registered agent. The agent must have a websiteUrl set. Supports two methods: "well-known" (place a file at /.well-known/humanpages-verify.txt) or "dns" (add a TXT record at _humanpages.yourdomain.com).',
@@ -857,29 +885,6 @@ export function createServer() {
                     required: ['agent_key'],
                 },
             },
-            {
-                name: 'list_playbooks',
-                description: 'List available task delegation playbooks. Each playbook contains step-by-step instructions for hiring a human to do a specific type of work (QA testing, competitor monitoring, directory submissions, etc.).',
-                inputSchema: {
-                    type: 'object',
-                    properties: {},
-                },
-            },
-            {
-                name: 'get_playbook',
-                description: 'Get the full content of a delegation playbook. Returns detailed instructions including search criteria, job offer templates, pricing, verification steps, and communication templates.',
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        task_type: {
-                            type: 'string',
-                            description: 'The playbook type to retrieve',
-                            enum: ['qa-testing', 'competitor-monitoring', 'localization', 'directory-submissions', 'community-management'],
-                        },
-                    },
-                    required: ['task_type'],
-                },
-            },
         ],
     }));
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -899,6 +904,7 @@ export function createServer() {
                     work_mode: args?.work_mode,
                     verified: args?.verified,
                     min_experience: args?.min_experience,
+                    fiat_platform: args?.fiat_platform,
                 });
                 const humans = response.results;
                 const locationNote = response.resolvedLocation
@@ -932,6 +938,7 @@ export function createServer() {
   Equipment: ${h.equipment.join(', ') || 'None listed'}
   Languages: ${h.languages.join(', ') || 'Not specified'}
   Experience: ${h.yearsOfExperience ? `${h.yearsOfExperience} years` : 'Not specified'}
+  Payment methods: ${h.paymentMethods && h.paymentMethods.length > 0 ? h.paymentMethods.join(', ') : 'Not specified'}
   Jobs completed: ${rep?.jobsCompleted || 0}`;
                 })
                     .join('\n\n');
@@ -1011,6 +1018,7 @@ ${servicesInfo || 'No services listed'}`;
                         websiteUrl: args?.website_url,
                         contactEmail: args?.contact_email,
                         webhookUrl: args?.webhook_url,
+                        walletAddress: args?.wallet_address,
                     }),
                 });
                 if (!res.ok) {
@@ -1069,6 +1077,102 @@ To get a verified badge, set up domain verification using \`verify_agent_domain\
                     content: [{ type: 'text', text: details }],
                 };
             }
+            if (name === 'set_wallet') {
+                const agentKey = args?.agent_key;
+                if (!agentKey) {
+                    throw new Error('agent_key is required.');
+                }
+                const res = await fetch(`${API_BASE}/api/agents/${args?.agent_id}/wallet`, {
+                    method: 'PATCH',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'X-Agent-Key': agentKey,
+                    },
+                    body: JSON.stringify({
+                        walletAddress: args?.wallet_address,
+                        walletNetwork: args?.wallet_network || 'base',
+                    }),
+                });
+                if (!res.ok) {
+                    const error = await res.json();
+                    throw new Error(error.error || `API error: ${res.status}`);
+                }
+                const result = await res.json();
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `**Wallet Set!**
+
+**Agent:** ${result.name}
+**Wallet Address:** \`${result.walletAddress}\`
+**Network:** ${result.walletNetwork}
+
+Your wallet is now configured. Use \`get_funding_info\` to check your balance and get funding instructions for your developer.`,
+                        }],
+                };
+            }
+            if (name === 'get_funding_info') {
+                const agentKey = args?.agent_key;
+                if (!agentKey) {
+                    throw new Error('agent_key is required.');
+                }
+                // Fetch balance
+                const balanceRes = await fetch(`${API_BASE}/api/agents/${args?.agent_id}/balance`);
+                if (!balanceRes.ok) {
+                    throw new Error(`Could not fetch balance: ${balanceRes.status}`);
+                }
+                const balanceData = await balanceRes.json();
+                const hasWallet = balanceData.walletAddress != null;
+                const balance = balanceData.balance ?? '0.00';
+                const network = balanceData.network || 'base';
+                const addr = balanceData.walletAddress || '(not set)';
+                // Build Transak URL (pre-filled with wallet, params encoded for safety)
+                const transakUrl = hasWallet
+                    ? `https://global.transak.com/?cryptoCurrencyCode=USDC&network=${encodeURIComponent(network)}&walletAddress=${encodeURIComponent(addr)}`
+                    : 'https://global.transak.com/?cryptoCurrencyCode=USDC&network=base';
+                const fundingMethods = [
+                    { method: 'crypto_transfer', label: 'Send USDC', description: `Send USDC to ${addr} on ${network}` },
+                    { method: 'credit_card', label: 'Buy with card', provider: 'Transak', url: transakUrl },
+                    { method: 'peer_exchange', label: 'Convert via Peer', provider: 'Peer (peer.xyz)', url: 'https://peer.xyz', description: 'Convert from Wise, PayPal, Venmo, or 15+ other platforms to USDC' },
+                    { method: 'ask_friend', label: 'Ask someone with crypto', description: `Have them send USDC to ${addr}` },
+                ];
+                const fiatAlternative = {
+                    description: 'You can also pay workers directly via shared payment platforms (Wise, PayPal, Venmo, Revolut, etc.) without needing crypto. Search for workers who accept your preferred platform.',
+                    useSearchParam: 'fiat_platform',
+                };
+                const message = `I need funding to hire workers on your behalf.
+
+Current balance: $${balance} USDC${hasWallet ? '' : ' (no wallet set — use set_wallet first)'}
+Wallet address: ${addr}
+Network: ${network}
+
+**Option A — Fund with USDC (for crypto payments):**
+
+1. Already have crypto? Send USDC to my wallet address above on ${network}.
+2. Buy with card: [Transak](${transakUrl})
+3. Convert from Wise/PayPal/Venmo/etc: [Peer (peer.xyz)](https://peer.xyz)
+4. Know someone with crypto? Ask them to send USDC to my address.
+
+**Option B — Pay workers directly with fiat:**
+I can find workers who accept payment platforms you already use (Wise, PayPal, Venmo, Revolut, etc.). You'd pay them directly — no crypto needed.
+
+**Think about what works best for you** — consider what accounts you already have, whether you or anyone you know holds crypto, and what payment methods are common where you are. I can help figure out the easiest path.
+
+Which option works best for you?`;
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                currentBalance: balance,
+                                walletAddress: addr,
+                                walletNetwork: network,
+                                fundingMethods,
+                                fiatAlternative,
+                                message,
+                            }, null, 2),
+                        }],
+                };
+            }
             if (name === 'verify_agent_domain') {
                 const res = await fetch(`${API_BASE}/api/agents/${args?.agent_id}/verify-domain`, {
                     method: 'POST',
@@ -2108,28 +2212,6 @@ Thank you for your feedback. This helps build the human's reputation.`,
                     ],
                 };
             }
-            if (name === 'list_playbooks') {
-                const list = PLAYBOOKS.map(p => `- **${p.name}** (\`${p.type}\`): ${p.description}`).join('\n');
-                return {
-                    content: [{
-                            type: 'text',
-                            text: `**Available Delegation Playbooks**\n\n${list}\n\nUse \`get_playbook(task_type)\` to get full instructions for any playbook.`,
-                        }],
-                };
-            }
-            if (name === 'get_playbook') {
-                const taskType = args?.task_type;
-                if (!taskType || !PLAYBOOK_TYPES.includes(taskType)) {
-                    return {
-                        content: [{ type: 'text', text: `Invalid task_type. Must be one of: ${PLAYBOOK_TYPES.join(', ')}` }],
-                        isError: true,
-                    };
-                }
-                const content = getPlaybookContent(taskType);
-                return {
-                    content: [{ type: 'text', text: content }],
-                };
-            }
             return {
                 content: [{ type: 'text', text: `Unknown tool: ${name}` }],
                 isError: true,

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "humanpages",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "mcpName": "io.github.human-pages-ai/humanpages",
-  "description": "MCP server (+ OpenClaw SKILL.md) that gives AI agents access to real-world people who listed themselves to be hired by agents. 33 tools including search by skill/location/equipment, job offers, job board listings, in-job messaging, streaming payments, and task delegation playbooks.",
+  "description": "MCP server (+ OpenClaw SKILL.md) that gives AI agents access to real-world people who listed themselves to be hired by agents. 31 tools including search by skill/location/equipment, job offers, job board listings, in-job messaging, streaming payments, and agent funding.",
   "main": "dist/index.js",
   "type": "module",
   "bin": {
@@ -16,8 +16,7 @@
     "dist/tools.d.ts",
     "dist/http.js",
     "dist/http.d.ts",
-    "README.md",
-    "playbooks/"
+    "README.md"
   ],
   "scripts": {
     "dev": "tsx watch src/index.ts",

package/playbooks/community-management.md

@@ -1,210 +0,0 @@
-# Community Management Playbook
-
-Hire a human to manage your online community on a daily basis. Community management requires empathy, judgment, cultural awareness, and the ability to de-escalate conflict — tasks that remain firmly human.
-
----
-
-## When to Use
-
-- Your product has an active community (Discord, Slack, forum, Telegram, subreddit) that needs daily attention
-- User questions are going unanswered for more than 24 hours
-- You're seeing spam, toxicity, or off-topic content that needs moderation
-- You want to build community engagement proactively (not just reactive support)
-- You're launching a community and need someone to seed conversations and welcome new members
-
-## Why a Human Is Needed
-
-Community management is fundamentally a relationship-building activity. Members need to feel heard by a real person. Moderation decisions require judgment calls about tone, intent, and context that automated systems get wrong. A human community manager can read the room, de-escalate tensions before they become crises, identify power users to elevate, and create the kind of authentic engagement that builds loyalty. Bots managing communities feel like bots — and community members leave.
-
-## Search Criteria
-
-**Primary search:**
-```json
-{
-  "skill": "community management",
-  "available_now": true,
-  "limit": 10
-}
-```
-
-**Fallback search:**
-```json
-{
-  "skill": "moderation",
-  "available_now": true,
-  "limit": 10
-}
-```
-
-**Second fallback:**
-```json
-{
-  "skill": "customer support",
-  "available_now": true,
-  "limit": 10
-}
-```
-
-## Candidate Evaluation
-
-Priority criteria when reviewing `get_human_profile` results:
-
-1. **Community management experience** — prior experience moderating Discord, Slack, forums, or social media communities
-2. **Communication style** — warm, professional, and empathetic; check their bio for tone
-3. **Timezone coverage** — should be active during your community's peak hours
-4. **Platform familiarity** — experience with the specific platform you use (Discord roles, Slack workflows, Reddit moderation tools, etc.)
-5. **Language skills** — must be fluent in your community's primary language; multilingual is a bonus for international communities
-6. **Availability commitment** — community management requires daily presence, not occasional check-ins
-
-## Job Offer Template
-
-**Title:** Daily community management for [COMMUNITY_NAME] on [PLATFORM]
-
-**Description:**
-```
-Manage the [COMMUNITY_NAME] community on [PLATFORM] ([INVITE_LINK]).
-
-Daily responsibilities:
-1. **Welcome new members** — greet new joins within [N] hours, point
-   them to introductions channel and key resources
-2. **Answer questions** — respond to user questions or route them to
-   the right person/channel. Aim for < [N]-hour first response time
-3. **Moderate content** — remove spam, enforce community guidelines,
-   warn or mute rule violators
-4. **Engage proactively** — start [N] conversations/week, share
-   relevant content, highlight interesting user contributions
-5. **Escalate issues** — flag technical bugs, feature requests, and
-   serious incidents to me immediately via [ESCALATION_CHANNEL]
-6. **Weekly summary** — deliver a structured report every [DAY]
-
-Community guidelines: [LINK_TO_GUIDELINES]
-Key resources to share with members: [LINK_TO_FAQ_OR_DOCS]
-Escalation contact: [YOUR_CONTACT]
-
-Active hours required: [TIMEZONE] [START_TIME]-[END_TIME], [DAYS]
-
-Weekly summary format:
-- New members this week: [count]
-- Messages/posts this week: [count]
-- Questions answered: [count]
-- Issues escalated: [list]
-- Top discussions/threads: [list with links]
-- Spam/moderation actions: [count and summary]
-- Community sentiment: [positive/neutral/negative + explanation]
-- Suggestions for improvement: [2-3 ideas]
-```
-
-**Suggested price:** $50-100 per week, depending on community size and activity level. Small community (< 100 active members): $50/week. Medium (100-500 active): $75/week. Large (500+ active): $100/week.
-
-## Expected Deliverables
-
-1. Daily presence in the community during agreed hours (verifiable via message timestamps)
-2. Responses to user questions within the agreed SLA (e.g., 4-hour first response)
-3. Moderation actions logged (spam removed, warnings issued, bans with reason)
-4. Weekly summary report covering all metrics listed in the job description
-5. Escalation of critical issues in real-time via the agreed channel
-6. Proactive engagement: conversation starters, content shares, member highlights
-
-## Verification Criteria
-
-Before calling `mark_job_paid` (weekly):
-
-1. **Presence check** — review message timestamps to confirm daily activity during agreed hours
-2. **Response time** — spot-check 3-5 user questions and measure time-to-first-response against SLA
-3. **Moderation quality** — review moderation log; actions should be justified and proportionate
-4. **Weekly summary delivered** — report should be on time, complete, and contain actionable insights
-5. **No unanswered questions** — scan channels for questions that went unaddressed for more than the SLA period
-6. **Community health** — subjective check: does the community feel more active and welcoming than before?
-
-## Communication Template
-
-**First message after job offer is accepted:**
-
-```
-Hi [NAME], welcome aboard!
-
-Here's everything you need to get started:
-
-Community access:
-- Platform: [PLATFORM]
-- Invite link: [INVITE_LINK]
-- Your role/permissions: [ROLE] (I'll assign this once you join)
-
-Key channels:
-- #general — main discussion
-- #help — user questions (priority channel)
-- #introductions — new member welcomes
-- #announcements — official announcements (only I post here)
-
-Community guidelines: [LINK]
-FAQ / documentation: [LINK]
-
-Your schedule:
-- Active hours: [TIMEZONE] [HOURS], [DAYS]
-- Weekly summary due: [DAY] by [TIME]
-- Escalation: DM me on [PLATFORM] or message me here for anything
-  urgent (bugs, angry users, security issues)
-
-For the first week, focus on:
-1. Learning the community culture — read recent conversations
-2. Introducing yourself (I'll announce you as a community manager)
-3. Responding to any unanswered questions in #help
-4. Identifying the top 5 most active members (good candidates for
-   community champions later)
-
-Don't hesitate to ask me if anything is unclear. I'd rather you ask
-than guess, especially for moderation decisions in the first week.
-```
-
-## Estimated Timeline
-
-- **Onboarding:** 1-2 days to learn the community, culture, and tools
-- **Daily time commitment:** 2-4 hours per day, depending on community activity
-- **Weekly summary:** 30-60 minutes to compile
-- **First week:** Expect reduced efficiency as the manager learns the community
-
-## Recurring Schedule
-
-**Cadence:** Daily (with weekly summary and payment)
-
-**Weekly workflow:**
-1. Monday: Review previous week's summary, set focus areas for the new week
-2. Daily: Community manager is active during agreed hours, handles all responsibilities
-3. Friday/Saturday: Community manager compiles weekly summary
-4. Weekly review: Verify deliverables, provide feedback, pay for the week
-5. Create next week's job (or use a standing arrangement if the platform supports it)
-
-**Monthly review:**
-- Assess community health metrics trend (growing? stagnating? declining?)
-- Review moderation patterns — are the same issues recurring? Update guidelines if so
-- Discuss with the community manager what's working and what needs adjustment
-- Adjust compensation if the community has grown significantly
-
-**Scaling:**
-- At 500+ active members, consider a second community manager for timezone coverage
-- At 1000+ members, consider specialized roles: moderator, content creator, support lead
-- Community managers can help recruit and train additional moderators from the community
-
----
-
-## Example Agent Workflow
-
-```
-1. search_humans({ skill: "community management", available_now: true, limit: 10 })
-2. For each candidate: get_human_profile({ username: candidate.username })
-3. Select best candidate based on evaluation criteria (especially timezone and platform experience)
-4. create_job_offer({
-     human_username: selected.username,
-     title: "Daily community management for MyApp Discord — Week 1",
-     description: "...[filled template]...",
-     price: 75,
-     currency: "USD"
-   })
-5. send_job_message({ job_id: job.id, message: "...[onboarding template]..." })
-6. Grant community platform permissions to the new manager
-7. Monitor: check community activity daily, get_job_status({ job_id: job.id }) at week end
-8. Review weekly summary against verification criteria
-9. mark_job_paid({ job_id: job.id })
-10. leave_review({ job_id: job.id, rating: 5, comment: "..." })
-11. Create next week's job offer (adjusting focus areas based on this week's summary)
-```