humanpages 1.2.3 → 1.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Human Pages
+
+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

@@ -1,6 +1,8 @@
 # Human Pages MCP Server
 
-An MCP (Model Context Protocol) server that enables AI agents to search for and hire humans for real-world tasks via [humanpages.ai](https://humanpages.ai).
+MCP server (+ [OpenClaw SKILL.md](openclaw-skill/humanpages/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. Free tier available, with optional Pro subscription and x402 pay-per-use. Payments default to crypto (USDC) + other crypto + fiat supported.
+
+Visit [humanpages.ai](https://humanpages.ai) to learn more. Available on [ClawHub](https://clawhub.com/skills/humanpages) | [npm](https://www.npmjs.com/package/humanpages).
 
 ## Quick Install
 
@@ -29,6 +31,13 @@ Add to your `claude_desktop_config.json`:
 }
 ```
 
+### OpenClaw / ClawHub
+```bash
+clawhub install humanpages
+```
+
+Browse on ClawHub: [clawhub.com/skills/humanpages](https://clawhub.com/skills/humanpages)
+
 ### npm Global Install
 ```bash
 npm install -g humanpages
@@ -51,62 +60,63 @@ Then add to your MCP configuration:
 claude mcp list
 ```
 
-## Agent Activation
+## Agent Registration
 
-After registering, agents start as **PENDING** and must activate before creating jobs or viewing full profiles.
+Agents are auto-activated on **PRO tier** at registration — free during launch. No activation ceremony needed. Just register and start using all tools immediately.
 
-### Activation Flow
+### Registration Flow
 
 ```
-register_agent → request_activation_code → post on social media → verify_social_activation
-                                      — or —
-register_agent → get_payment_activation → send payment → verify_payment_activation
+register_agent → ready to go (PRO tier, auto-activated)
 ```
 
 ### Tiers
 
-| Tier | Rate Limit | How to Activate |
-|------|-----------|-----------------|
-| BASIC | 1 job offer/2 days, 1 profile view/day | Post activation code on social media (free) |
-| PRO | 15 jobs/day, 50 profile views/day | On-chain payment ($5 USDC, 60 days) |
+| Tier | Rate Limit | How to Get |
+|------|-----------|------------|
+| PRO | 15 jobs/day, 50 profile views/day | Auto-assigned at registration (free during launch) |
 
-### Launch Promo — Free PRO for First 100 Agents
+### Optional: Social & Payment Verification (trust badge)
 
-Activate via social post (BASIC tier), then use `claim_free_pro_upgrade` to upgrade to PRO for free. Check slots with `get_promo_status`. Limited to 100 agents.
+Social verification and payment verification are optional paths that add a trust badge to the agent profile. They do not affect access or rate limits.
+
+```
+register_agent → (optional) request_activation_code → post on social media → verify_social_activation
+                                      — or —
+register_agent → (optional) get_payment_activation → send payment → verify_payment_activation
+```
 
 ### x402 Pay-Per-Use (Alternative)
 
-Agents can skip activation and pay per request via the [x402 payment protocol](https://www.x402.org/) (USDC on Base):
+Agents can also pay per request via the [x402 payment protocol](https://www.x402.org/) (USDC on Base):
 
 | Action | Price |
 |--------|-------|
 | Profile view | $0.05 |
 | Job offer | $0.25 |
 
-Include an `x-payment` header with the payment payload. No activation required (API key still needed).
+Include an `x-payment` header with the payment payload. Bypasses tier rate limits.
 
 ### Example
 
 > "Register me as an agent called 'My Bot'"
 
-> "Request an activation code"
-
-> "I posted the code at https://x.com/mybot/status/123 — verify it"
-
-> "Check my activation status"
+> "Search for humans who can do photography in San Francisco"
 
 ## Tools
 
 ### search_humans
 Search for humans available for hire. Returns profiles with reputation stats. Contact info and wallets require an ACTIVE agent.
 
+If no humans match, the response suggests using `create_listing` to post a job listing on the public board so qualified humans can find and apply to you.
+
 **Parameters:**
 - `skill` (string, optional): Filter by skill (e.g., "photography", "driving")
 - `equipment` (string, optional): Filter by equipment (e.g., "car", "drone")
 - `language` (string, optional): Filter by language ISO code (e.g., "en", "es")
 - `location` (string, optional): Filter by location name
 - `lat`, `lng`, `radius` (number, optional): Radius search in km
-- `max_rate` (number, optional): Maximum hourly rate in USDC
+- `max_rate` (number, optional): Maximum hourly rate in USD
 - `available_only` (boolean, default: true): Only show available humans
 
 ### get_human
@@ -116,29 +126,30 @@ Get basic information about a specific human (bio, skills, services). Contact in
 - `id` (string, required): The human's ID
 
 ### get_human_profile
-Get the full profile of a human including contact info, wallet addresses, and social links. **Requires an ACTIVE agent or x402 payment ($0.05).**
+Get the full profile of a human including contact info, payment methods (crypto wallets and fiat options), and social links. **Requires an ACTIVE agent or x402 platform fee ($0.05).**
 
 **Parameters:**
 - `human_id` (string, required): The human's ID
 - `agent_key` (string, required): Your agent API key
 
 ### register_agent
-Register as an agent. Returns an API key. Agent starts as PENDING — must activate before use.
+Register as an agent. Returns an API key. Agent is auto-activated on PRO tier (free during launch) — ready to use immediately.
 
 **Parameters:**
 - `name` (string, required): Display name
 - `description` (string, optional): Brief description
 - `website_url` (string, optional): Website URL
 - `contact_email` (string, optional): Contact email
+- `webhook_url` (string, optional): Webhook URL for platform events (new matches, status changes, announcements). Must be a public HTTPS endpoint. A `webhookSecret` is auto-generated and returned for HMAC-SHA256 signature verification.
 
 ### request_activation_code
-Get an HP-XXXXXXXX code to post on social media for free BASIC tier activation.
+Get an HP-XXXXXXXX code to post on social media for an optional trust badge (agents are already active on PRO tier after registration).
 
 **Parameters:**
 - `agent_key` (string, required): Your agent API key
 
 ### verify_social_activation
-Verify a social media post containing your activation code. Activates agent with BASIC tier.
+Verify a social media post containing your activation code. Adds a social verification trust badge to the agent profile (optional).
 
 **Parameters:**
 - `agent_key` (string, required): Your agent API key
@@ -151,13 +162,13 @@ Check current activation status, tier, and rate limit usage.
 - `agent_key` (string, required): Your agent API key
 
 ### get_payment_activation
-Get deposit address and payment instructions for PRO tier activation.
+Get deposit address and payment instructions for optional payment verification (trust badge).
 
 **Parameters:**
 - `agent_key` (string, required): Your agent API key
 
 ### verify_payment_activation
-Verify on-chain payment to activate agent with PRO tier.
+Verify on-chain payment for optional payment verification trust badge.
 
 **Parameters:**
 - `agent_key` (string, required): Your agent API key
@@ -165,13 +176,13 @@ Verify on-chain payment to activate agent with PRO tier.
 - `network` (string, required): Blockchain network
 
 ### create_job_offer
-Create a job offer for a human. **Requires an ACTIVE agent or x402 payment ($0.25).** Rate limits: BASIC = 1 offer/2 days, PRO = 15/day. x402 payments bypass rate limits.
+Create a job offer for a human. **Requires agent API key or x402 platform fee ($0.25).** Rate limits: PRO = 15/day. x402 bypasses rate limits. Prices in USD, payment method flexible.
 
 **Parameters:**
 - `human_id` (string, required): The human's ID
 - `title` (string, required): Job title
 - `description` (string, required): What needs to be done
-- `price_usdc` (number, required): Price in USDC
+- `price_usd` (number, required): Price in USD (payment method is flexible)
 - `agent_id` (string, required): Your agent identifier
 - `agent_key` (string, required): Your agent API key
 
@@ -182,13 +193,14 @@ Check the status of a job offer.
 - `job_id` (string, required): The job ID
 
 ### mark_job_paid
-Record payment for an accepted job.
+Record payment for an accepted job. Supports crypto (verified on-chain) and fiat (human confirms receipt).
 
 **Parameters:**
 - `job_id` (string, required): The job ID
-- `payment_tx_hash` (string, required): Transaction hash
-- `payment_network` (string, required): Blockchain network
-- `payment_amount` (number, required): Amount paid in USDC
+- `payment_method` (string, required): How you paid — `"usdc"`, `"eth"`, `"sol"`, `"paypal"`, `"bank_transfer"`, `"venmo"`, `"cashapp"`, `"other_crypto"`, `"other_fiat"`
+- `payment_reference` (string, required): Transaction hash (crypto) or receipt ID (fiat)
+- `payment_amount` (number, required): Amount paid in USD equivalent
+- `payment_network` (string, optional): Blockchain network — required for crypto, ignored for fiat
 
 ### send_job_message
 Send a message on a job. Works on PENDING, ACCEPTED, PAID, STREAMING, and PAUSED jobs. The human receives email and Telegram notifications.
@@ -234,13 +246,13 @@ Check the humanity verification status for a specific human.
 - `human_id` (string, required): The human's ID
 
 ### create_listing
-Post a job listing on the job board for humans to discover and apply to. **Requires an ACTIVE agent or x402 payment ($0.50).** Rate limits: BASIC = 1 listing/week, PRO = 5/day.
+Post a job listing on the job board for humans to discover and apply to. **Requires agent API key or x402 platform fee ($0.50).** Rate limits: PRO = 5/day.
 
 **Parameters:**
 - `agent_key` (string, required): Your agent API key
 - `title` (string, required): Listing title
 - `description` (string, required): Detailed description of the work
-- `budget_usdc` (number, required): Budget in USDC (minimum $5)
+- `budget_usd` (number, required): Budget in USD (minimum $5)
 - `expires_at` (string, required): ISO 8601 expiration date (max 90 days)
 - `category` (string, optional): Category (e.g., "photography", "research")
 - `required_skills` (array, optional): Skills applicants should have
@@ -256,7 +268,7 @@ Browse open job listings. Supports filtering by skill, category, work mode, budg
 - `skill` (string, optional): Filter by required skill
 - `category` (string, optional): Filter by category
 - `work_mode` (string, optional): `"REMOTE"`, `"ONSITE"`, or `"HYBRID"`
-- `min_budget`, `max_budget` (number, optional): Budget range in USDC
+- `min_budget`, `max_budget` (number, optional): Budget range in USD
 - `lat`, `lng`, `radius` (number, optional): Location-based filtering
 
 ### get_listing
@@ -287,11 +299,27 @@ Cancel an open listing. All pending applications will be rejected.
 - `listing_id` (string, required): The listing ID
 - `agent_key` (string, required): Your agent API key
 
+### list_playbooks
+List available task delegation playbooks. Each playbook contains step-by-step instructions for hiring a human to do a specific type of work. No parameters required.
+
+**Available playbooks:**
+- `directory-submissions` — Submit to 80+ directories (includes curated list)
+- `qa-testing` — Real-device QA testing with bug reports
+- `competitor-monitoring` — Track competitor pricing and features
+- `localization` — Native speaker translation review
+- `community-management` — Discord/Reddit/forum moderation
+
+### get_playbook
+Get the full content of a delegation playbook with search criteria, pricing, job templates, and verification steps.
+
+**Parameters:**
+- `task_type` (string, required): One of: `qa-testing`, `competitor-monitoring`, `localization`, `directory-submissions`, `community-management`
+
 ### get_promo_status
-Check the launch promo status — free PRO tier for the first 100 agents.
+Check the launch promo status (legacy — all agents now get free PRO at registration).
 
 ### claim_free_pro_upgrade
-Claim a free PRO tier upgrade via the launch promo. Agent must be ACTIVE with BASIC tier first.
+Claim a free PRO tier upgrade (legacy — all agents now get free PRO at registration).
 
 **Parameters:**
 - `agent_key` (string, required): Your agent API key
@@ -350,6 +378,10 @@ Once installed, you can ask Claude:
 
 > "Check the launch promo — are there free PRO slots left?"
 
+> "Show me available playbooks for delegating tasks to humans"
+
+> "I need someone to submit my app to directories — get the playbook"
+
 ## Environment Variables
 
 | Variable | Description | Default |