humanpages 1.0.0 → 1.1.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,56 @@ 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 | 5 jobs/day | Post activation code on social media (free) |
+| PRO | 15 jobs/day | On-chain payment |
+
+### 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 +95,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.**
+
+**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.** Rate limits: BASIC = 5/day, PRO = 15/day.
 
 **Parameters:**
 - `human_id` (string, required): The human's ID
@@ -59,6 +158,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.
@@ -83,6 +183,20 @@ Leave a review for a completed job.
 - `rating` (number, required): Rating 1-5
 - `comment` (string, optional): Review comment
 
+## Example Usage
+
+Once installed, you can ask Claude:
+
+> "Search for humans who can do photography in San Francisco"
+
+> "Get the profile of human ID abc123"
+
+> "Create a job offer for human xyz789 to deliver a package for $20"
+
+> "Request an activation code for my agent"
+
+> "Get the full profile of human abc123 with my agent key"
+
 ## Environment Variables
 
 | Variable | Description | Default |
@@ -104,6 +218,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