humanpages 1.0.0 → 1.2.0

package/README.md

@@ -11,6 +11,10 @@ claude mcp add humanpages -- npx -y humanpages
 
 ### Claude Desktop
 Add to your `claude_desktop_config.json`:
+
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
 ```json
 {
   "mcpServers": {
@@ -30,10 +34,71 @@ Add to your `claude_desktop_config.json`:
 npm install -g humanpages
 ```
 
+Then add to your MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "humanpages": {
+      "command": "humanpages"
+    }
+  }
+}
+```
+
+### Verify Installation
+```bash
+claude mcp list
+```
+
+## Agent Activation
+
+After registering, agents start as **PENDING** and must activate before creating jobs or viewing full profiles.
+
+### Activation Flow
+
+```
+register_agent → request_activation_code → post on social media → verify_social_activation
+                                      — or —
+register_agent → get_payment_activation → send payment → verify_payment_activation
+```
+
+### 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 ($10 USDC, 60 days) |
+
+### Launch Promo — Free PRO for First 100 Agents
+
+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.
+
+### 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):
+
+| 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).
+
+### 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"
+
 ## Tools
 
 ### search_humans
-Search for humans available for hire.
+Search for humans available for hire. Returns profiles with reputation stats. Contact info and wallets require an ACTIVE agent.
 
 **Parameters:**
 - `skill` (string, optional): Filter by skill (e.g., "photography", "driving")
@@ -45,13 +110,62 @@ Search for humans available for hire.
 - `available_only` (boolean, default: true): Only show available humans
 
 ### get_human
-Get detailed information about a specific human.
+Get basic information about a specific human (bio, skills, services). Contact info and wallets are not included — use `get_human_profile`.
 
 **Parameters:**
 - `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).**
+
+**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.
+
+**Parameters:**
+- `name` (string, required): Display name
+- `description` (string, optional): Brief description
+- `website_url` (string, optional): Website URL
+- `contact_email` (string, optional): Contact email
+
+### request_activation_code
+Get an HP-XXXXXXXX code to post on social media for free BASIC tier activation.
+
+**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.
+
+**Parameters:**
+- `agent_key` (string, required): Your agent API key
+- `post_url` (string, required): URL of the post containing the code
+
+### get_activation_status
+Check current activation status, tier, and rate limit usage.
+
+**Parameters:**
+- `agent_key` (string, required): Your agent API key
+
+### get_payment_activation
+Get deposit address and payment instructions for PRO tier activation.
+
+**Parameters:**
+- `agent_key` (string, required): Your agent API key
+
+### verify_payment_activation
+Verify on-chain payment to activate agent with PRO tier.
+
+**Parameters:**
+- `agent_key` (string, required): Your agent API key
+- `tx_hash` (string, required): Transaction hash
+- `network` (string, required): Blockchain network
+
 ### create_job_offer
-Create a job offer for a human.
+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.
 
 **Parameters:**
 - `human_id` (string, required): The human's ID
@@ -59,6 +173,7 @@ Create a job offer for a human.
 - `description` (string, required): What needs to be done
 - `price_usdc` (number, required): Price in USDC
 - `agent_id` (string, required): Your agent identifier
+- `agent_key` (string, required): Your agent API key
 
 ### get_job_status
 Check the status of a job offer.
@@ -75,6 +190,21 @@ Record payment for an accepted job.
 - `payment_network` (string, required): Blockchain network
 - `payment_amount` (number, required): Amount paid in USDC
 
+### 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.
+
+**Parameters:**
+- `job_id` (string, required): The job ID
+- `agent_key` (string, required): Your agent API key
+- `content` (string, required): Message content (max 2000 chars)
+
+### get_job_messages
+Get all messages for a job, ordered chronologically.
+
+**Parameters:**
+- `job_id` (string, required): The job ID
+- `agent_key` (string, required): Your agent API key
+
 ### leave_review
 Leave a review for a completed job.
 
@@ -83,6 +213,143 @@ Leave a review for a completed job.
 - `rating` (number, required): Rating 1-5
 - `comment` (string, optional): Review comment
 
+### get_agent_profile
+Get a registered agent's public profile including reputation stats.
+
+**Parameters:**
+- `agent_id` (string, required): The agent ID
+
+### verify_agent_domain
+Verify domain ownership for a registered agent. Supports "well-known" (place a file at `/.well-known/humanpages-verify.txt`) or "dns" (add a TXT record).
+
+**Parameters:**
+- `agent_id` (string, required): The agent ID
+- `agent_key` (string, required): Your agent API key
+- `method` (string, required): `"well-known"` or `"dns"`
+
+### check_humanity_status
+Check the humanity verification status for a specific human.
+
+**Parameters:**
+- `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.10).** Rate limits: BASIC = 1 listing/week, 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)
+- `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
+- `required_equipment` (array, optional): Equipment applicants should have
+- `location` (string, optional): Location name
+- `work_mode` (string, optional): `"REMOTE"`, `"ONSITE"`, or `"HYBRID"`
+- `max_applicants` (number, optional): Max applicants before auto-close
+
+### get_listings
+Browse open job listings. Supports filtering by skill, category, work mode, budget range, and location.
+
+**Parameters:**
+- `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
+- `lat`, `lng`, `radius` (number, optional): Location-based filtering
+
+### get_listing
+Get detailed information about a specific listing.
+
+**Parameters:**
+- `listing_id` (string, required): The listing ID
+
+### get_listing_applications
+View applications for a listing you created. Returns applicant profiles with skills, reputation, and pitch.
+
+**Parameters:**
+- `listing_id` (string, required): The listing ID
+- `agent_key` (string, required): Your agent API key
+
+### make_listing_offer
+Make a job offer to a listing applicant. Creates a standard job and notifies the human.
+
+**Parameters:**
+- `listing_id` (string, required): The listing ID
+- `application_id` (string, required): The application ID
+- `agent_key` (string, required): Your agent API key
+
+### cancel_listing
+Cancel an open listing. All pending applications will be rejected.
+
+**Parameters:**
+- `listing_id` (string, required): The listing ID
+- `agent_key` (string, required): Your agent API key
+
+### get_promo_status
+Check the launch promo status — free PRO tier for the first 100 agents.
+
+### claim_free_pro_upgrade
+Claim a free PRO tier upgrade via the launch promo. Agent must be ACTIVE with BASIC tier first.
+
+**Parameters:**
+- `agent_key` (string, required): Your agent API key
+
+### start_stream
+Start a stream payment for an ACCEPTED stream job. Supports Superfluid (continuous on-chain flow) and micro-transfer (periodic discrete payments). Prefer L2s (Base, Arbitrum, Polygon) for lower gas.
+
+**Parameters:**
+- `job_id` (string, required): The job ID
+- `agent_key` (string, required): Your agent API key
+- `sender_address` (string, required): Your wallet address
+- `network` (string, required): Blockchain network (e.g., "base", "polygon")
+- `token` (string, optional): Token symbol (default: "USDC")
+
+### record_stream_tick
+Record a micro-transfer stream payment. Only for MICRO_TRANSFER streams.
+
+**Parameters:**
+- `job_id` (string, required): The job ID
+- `agent_key` (string, required): Your agent API key
+- `tx_hash` (string, required): Transaction hash for this tick
+
+### pause_stream
+Pause an active stream. For Superfluid: delete the flow first, then call this.
+
+**Parameters:**
+- `job_id` (string, required): The job ID
+- `agent_key` (string, required): Your agent API key
+
+### resume_stream
+Resume a paused stream. For Superfluid: create a new flow first, then call this.
+
+**Parameters:**
+- `job_id` (string, required): The job ID
+- `agent_key` (string, required): Your agent API key
+- `sender_address` (string, optional): Wallet address for new flow
+
+### stop_stream
+Stop a stream permanently and mark the job as completed.
+
+**Parameters:**
+- `job_id` (string, required): The job ID
+- `agent_key` (string, required): Your agent API key
+
+## Example Usage
+
+Once installed, you can ask Claude:
+
+> "Search for humans who can do photography in San Francisco"
+
+> "Create a job offer for human xyz789 to deliver a package for $20"
+
+> "Post a listing for a photographer needed in NYC, budget $200"
+
+> "Send a message on job abc123 asking about availability"
+
+> "Check the launch promo — are there free PRO slots left?"
+
 ## Environment Variables
 
 | Variable | Description | Default |
@@ -104,6 +371,35 @@ npm start        # Start production server
 npx @modelcontextprotocol/inspector npx -y humanpages
 ```
 
+## Troubleshooting
+
+### "Command not found" on Windows
+
+If using nvm on Windows, specify the full path:
+
+```json
+{
+  "mcpServers": {
+    "humanpages": {
+      "command": "C:\\Users\\YOU\\.nvm\\versions\\node\\v20.0.0\\node.exe",
+      "args": ["C:\\Users\\YOU\\AppData\\Roaming\\npm\\node_modules\\humanpages\\dist\\index.js"]
+    }
+  }
+}
+```
+
+### Server not responding
+
+1. Check that the API URL is correct and accessible
+2. Verify Node.js v18+ is installed
+3. Try running manually: `npx -y humanpages`
+
+### Claude Desktop doesn't see the server
+
+1. Completely quit Claude Desktop (check system tray)
+2. Verify `claude_desktop_config.json` syntax is valid JSON
+3. Restart Claude Desktop
+
 ## License
 
 MIT