@runhuman/mcp-server 2.0.3 → 2.0.4

package/.env.example

@@ -1,12 +1,12 @@
-# RunHuman API Configuration
-
-# API Base URL
-# For local development, use http://localhost:3400
-# For production, use your deployed API URL
-RUNHUMAN_API_URL=http://localhost:3400
-
-# API Key
-# Get this from the API dashboard at http://localhost:3400/app.html
-# Or use the default test key below for local development
-# Format: qa_live_xxxxxxxxxxxxxxxxxxxxx
-RUNHUMAN_API_KEY=qa_live_test_key_for_demo_purposes_only_12345
+# RunHuman API Configuration
+
+# API Base URL
+# For local development, use http://localhost:3400
+# For production, use your deployed API URL
+RUNHUMAN_API_URL=http://localhost:3400
+
+# API Key
+# Get this from the API dashboard at http://localhost:3400/app.html
+# Or use the default test key below for local development
+# Format: qa_live_xxxxxxxxxxxxxxxxxxxxx
+RUNHUMAN_API_KEY=qa_live_test_key_for_demo_purposes_only_12345

package/README.md

@@ -1,240 +1,243 @@
-# RunHuman MCP Server
-
-A Model Context Protocol (MCP) server that allows AI agents to interact with the RunHuman QA testing service.
-
-## Overview
-
-This MCP server provides tools for creating and managing human QA jobs through the RunHuman API. AI agents can use this server to:
-
-- Create new QA jobs with custom schemas
-- Check the status of running jobs
-- Retrieve completed job results
-
-## Installation
-
-### For Claude Desktop (Recommended)
-
-1. Get your API key at: https://runhuman.com/app.html
-
-2. Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on Mac):
-
-```json
-{
-  "mcpServers": {
-    "runhuman": {
-      "command": "npx",
-      "args": ["-y", "@runhuman/mcp-server", "--api-key=qa_live_xxxxxxxxxxxxx"]
-    }
-  }
-}
-```
-
-3. Restart Claude Desktop
-
-That's it! The server will be automatically downloaded and run by Claude.
-
-### For Development
-
-From the monorepo root:
-
-```bash
-npm install
-npm run build --workspace=@runhuman/mcp-server
-
-# Run with API key
-node packages/mcp-server/dist/index.js --api-key=qa_live_xxxxx
-```
-
-### Available Tools
-
-#### `create_job`
-Create a new QA job with human testers.
-
-**Parameters:**
-- `url` (string): The URL to test
-- `description` (string): Instructions for the human tester describing what to test
-- `schema` (object): Expected result schema that the tester response will be extracted into
-- `targetDurationMinutes` (number, optional): Time limit for tester (default: 5, range: 1-60)
-
-#### `wait_for_result`
-Check status, wait, and retrieve results for a QA job in a single convenient call.
-
-**Parameters:**
-- `jobId` (string): The ID of the job to check
-- `waitSeconds` (number, optional): How long to wait before checking again (default: 30, range: 1-300)
-
-**Behavior:**
-- Checks status BEFORE waiting (returns immediately if already complete)
-- Waits for the specified duration
-- Checks status AFTER waiting
-- Returns results if complete, otherwise suggests calling again with longer wait time
-
-**Usage Pattern:**
-```javascript
-// After creating a job, call repeatedly with increasing wait times:
-let result = await wait_for_result(jobId, { waitSeconds: 30 });
-if (result.status !== 'completed') {
-  result = await wait_for_result(jobId, { waitSeconds: 45 });
-}
-if (result.status !== 'completed') {
-  result = await wait_for_result(jobId, { waitSeconds: 60 });
-}
-```
-
-**Returns:**
-- `result`: Structured test results extracted from tester's response
-- `status`: Job status (completed, failed, timeout, pending, claimed, in_progress)
-- `costUsd`: Exact cost in USD with full precision (e.g., 0.396)
-- `testDurationSeconds`: Time spent by tester in seconds (rounded up)
-- Additional metadata (timestamps, tester info, etc.)
-
-**Cost Calculation:**
-- Costs are calculated as: `duration × $0.0018/second` (general-use tier)
-- Duration is always rounded UP using Math.ceil (any partial second counts)
-- Costs are never $0 unless the tester never actually worked on it
-- Full precision maintained (not rounded to cents)
-
-## Configuration
-
-The MCP server needs to be configured with your RunHuman API credentials.
-
-### 1. Get an API Key
-
-**Option A: Via Dashboard**
-1. Start the API server: `npm run dev --workspace=@runhuman/api`
-2. Open http://localhost:3400/app.html
-3. Go to "API Keys" tab
-4. Click "Create API Key"
-5. Copy the key (starts with `qa_live_`)
-
-**Option B: Use Default Test Key**
-- For local development, you can use: `qa_live_test_key_123`
-- This key exists in `packages/api/data/api-keys.json`
-
-### 2. Configure Environment Variables
-
-Create a `.env` file in the MCP server directory:
-
-```bash
-# For local development
-RUNHUMAN_API_URL=http://localhost:3400
-RUNHUMAN_API_KEY=qa_live_test_key_123
-
-# For production
-RUNHUMAN_API_URL=https://api.runhuman.com
-RUNHUMAN_API_KEY=qa_live_xxxxxxxxxxxxxxxxxxxxx
-```
-
-**Important:** Never commit `.env` files to git! They're already in `.gitignore`.
-
-### 3. Verify Configuration
-
-Test your API key works:
-
-```bash
-curl http://localhost:3400/api/jobs \
-  -H "Authorization: Bearer qa_live_test_key_123" \
-  -H "Content-Type: application/json" \
-  -d '{"url":"https://example.com","description":"test","outputSchema":{}}'
-```
-
-Should return a job ID if authentication works.
-
-For more details, see [docs/API-AUTHENTICATION.md](docs/API-AUTHENTICATION.md)
-
-## Testing
-
-The MCP server includes automated tests to verify it's working correctly:
-
-```bash
-# Build first
-npm run build --workspace=@runhuman/mcp-server
-
-# Run simple automated test
-npm run test --workspace=@runhuman/mcp-server
-
-# Or use the MCP Inspector (interactive testing)
-npm run test:inspector --workspace=@runhuman/mcp-server
-```
-
-The test script will:
-1. ✅ Initialize a connection to the MCP server
-2. ✅ List all available tools (create_job, wait_for_result)
-3. ✅ Test calling the create_job tool
-
-### Expected Test Output
-
-```
-✅ Server initialized successfully
-✅ Tools listed: create_job, wait_for_result
-✅ create_job tool called successfully
-```
-
-## Development
-
-```bash
-# Watch mode (auto-rebuild on changes)
-npm run dev --workspace=@runhuman/mcp-server
-
-# Build
-npm run build --workspace=@runhuman/mcp-server
-
-# Test after building
-npm run test --workspace=@runhuman/mcp-server
-```
-
-## Integration with Claude Desktop
-
-To use this MCP server with Claude Desktop, add it to your configuration:
-
-```json
-{
-  "mcpServers": {
-    "runhuman": {
-      "command": "node",
-      "args": ["/path/to/qa-experiment/packages/mcp-server/dist/index.js"]
-    }
-  }
-}
-```
-
-## Example Usage
-
-Once connected to an AI agent (like Claude), the agent can use these tools naturally:
-
-**User:** "Can someone test my checkout page at https://myapp.com/checkout?"
-
-**Agent uses create_job:**
-```
-✅ Job created successfully!
-Job ID: job_abc123
-Status: pending
-...
-```
-
-**Agent calls wait_for_result repeatedly until complete:**
-```
-⏳ Job Status: in_progress
-Waited 30s, job not complete yet.
-💡 Suggestion: Call wait_for_result again with waitSeconds: 45
-```
-
-**Finally:**
-```
-✅ Test completed!
-Results Summary:
-- Checkout Flow: ✅ Working
-- Payment Processing: ✅ Successful
-...
-```
-
-## Developer Documentation
-
-For developers working on this MCP server:
-- [docs/HOW-AGENTS-USE-MCP.md](docs/HOW-AGENTS-USE-MCP.md) - How AI agents discover and use MCP servers
-- [docs/TOOL-RESPONSE-BEST-PRACTICES.md](docs/TOOL-RESPONSE-BEST-PRACTICES.md) - Best practices for tool responses
-
-## Learn More
-
-- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
-- [RunHuman API Documentation](../api/README.md)
+# RunHuman MCP Server
+
+A Model Context Protocol (MCP) server that allows AI agents to interact with the RunHuman QA testing service.
+
+## Overview
+
+This MCP server provides tools for creating and managing human QA jobs through the RunHuman API. AI agents can use this server to:
+
+- Create new QA jobs with custom schemas
+- Check the status of running jobs
+- Retrieve completed job results
+
+## Installation
+
+### For Claude Desktop (Recommended)
+
+1. Get your API key at: https://runhuman.com/dashboard/api-keys
+
+2. Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on Mac):
+
+```json
+{
+  "mcpServers": {
+    "runhuman": {
+      "command": "npx",
+      "args": ["-y", "@runhuman/mcp-server", "--api-key=qa_live_xxxxxxxxxxxxx"]
+    }
+  }
+}
+```
+
+3. Restart Claude Desktop
+
+That's it! The server will be automatically downloaded and run by Claude.
+
+### For Development
+
+From the monorepo root:
+
+```bash
+npm install
+npm run build --workspace=@runhuman/mcp-server
+
+# Run with API key
+node packages/mcp-server/dist/index.js --api-key=qa_live_xxxxx
+```
+
+### Available Tools
+
+#### `create_job`
+Create a new QA job with human testers.
+
+**Parameters:**
+- `url` (string): The URL to test
+- `description` (string): Instructions for the human tester describing what to test
+- `schema` (object): Expected result schema that the tester response will be extracted into
+- `targetDurationMinutes` (number, optional): Time limit for tester (default: 5, range: 1-60)
+
+#### `wait_for_result`
+Check status, wait, and retrieve results for a QA job in a single convenient call.
+
+**Parameters:**
+- `jobId` (string): The ID of the job to check
+- `waitSeconds` (number, optional): How long to wait before checking again (default: 30, range: 1-300)
+
+**Behavior:**
+- Checks status BEFORE waiting (returns immediately if already complete)
+- Waits for the specified duration
+- Checks status AFTER waiting
+- Returns results if complete, otherwise suggests calling again with longer wait time
+
+**Usage Pattern:**
+```javascript
+// After creating a job, call repeatedly with increasing wait times:
+let result = await wait_for_result(jobId, { waitSeconds: 30 });
+if (result.status !== 'completed') {
+  result = await wait_for_result(jobId, { waitSeconds: 45 });
+}
+if (result.status !== 'completed') {
+  result = await wait_for_result(jobId, { waitSeconds: 60 });
+}
+```
+
+**Returns:**
+- `result`: Structured test results extracted from tester's response
+- `status`: Job status (completed, failed, timeout, pending, claimed, in_progress)
+- `costUsd`: Exact cost in USD with full precision (e.g., 0.396)
+- `testDurationSeconds`: Time spent by tester in seconds (rounded up)
+- `testerResponse`: Raw natural language feedback from the human tester
+- `testerAlias`: Anonymized tester name (e.g., "Tester Alpha")
+- `testerAvatarUrl`: Avatar image URL for UI display
+- `testerColor`: Hex color code for theming (e.g., "#4A90E2")
+- Additional metadata (timestamps, etc.)
+
+**Cost Calculation:**
+- Costs are calculated as: `duration × $0.0018/second` (general-use tier)
+- Duration is always rounded UP using Math.ceil (any partial second counts)
+- Costs are never $0 unless the tester never actually worked on it
+- Full precision maintained (not rounded to cents)
+
+## Configuration
+
+The MCP server needs to be configured with your RunHuman API credentials.
+
+### 1. Get an API Key
+
+**Option A: Via Dashboard**
+1. Start the API server: `npm run dev --workspace=@runhuman/api`
+2. Open http://localhost:3400/api-keys
+3. Click "Create API Key"
+4. Copy the key (starts with `qa_live_`)
+
+**Option B: Use Default Test Key**
+- For local development, you can use: `qa_live_test_key_123`
+- This key exists in `packages/api/data/api-keys.json`
+
+### 2. Configure Environment Variables
+
+Create a `.env` file in the MCP server directory:
+
+```bash
+# For local development
+RUNHUMAN_API_URL=http://localhost:3400
+RUNHUMAN_API_KEY=qa_live_test_key_123
+
+# For production
+RUNHUMAN_API_URL=https://api.runhuman.com
+RUNHUMAN_API_KEY=qa_live_xxxxxxxxxxxxxxxxxxxxx
+```
+
+**Important:** Never commit `.env` files to git! They're already in `.gitignore`.
+
+### 3. Verify Configuration
+
+Test your API key works:
+
+```bash
+curl http://localhost:3400/api/jobs \
+  -H "Authorization: Bearer qa_live_test_key_123" \
+  -H "Content-Type: application/json" \
+  -d '{"url":"https://example.com","description":"test","outputSchema":{}}'
+```
+
+Should return a job ID if authentication works.
+
+For more details, see [docs/API-AUTHENTICATION.md](docs/API-AUTHENTICATION.md)
+
+## Testing
+
+The MCP server includes automated tests to verify it's working correctly:
+
+```bash
+# Build first
+npm run build --workspace=@runhuman/mcp-server
+
+# Run simple automated test
+npm run test --workspace=@runhuman/mcp-server
+
+# Or use the MCP Inspector (interactive testing)
+npm run test:inspector --workspace=@runhuman/mcp-server
+```
+
+The test script will:
+1. ✅ Initialize a connection to the MCP server
+2. ✅ List all available tools (create_job, wait_for_result)
+3. ✅ Test calling the create_job tool
+
+### Expected Test Output
+
+```
+✅ Server initialized successfully
+✅ Tools listed: create_job, wait_for_result
+✅ create_job tool called successfully
+```
+
+## Development
+
+```bash
+# Watch mode (auto-rebuild on changes)
+npm run dev --workspace=@runhuman/mcp-server
+
+# Build
+npm run build --workspace=@runhuman/mcp-server
+
+# Test after building
+npm run test --workspace=@runhuman/mcp-server
+```
+
+## Integration with Claude Desktop
+
+To use this MCP server with Claude Desktop, add it to your configuration:
+
+```json
+{
+  "mcpServers": {
+    "runhuman": {
+      "command": "node",
+      "args": ["/path/to/qa-experiment/packages/mcp-server/dist/index.js"]
+    }
+  }
+}
+```
+
+## Example Usage
+
+Once connected to an AI agent (like Claude), the agent can use these tools naturally:
+
+**User:** "Can someone test my checkout page at https://myapp.com/checkout?"
+
+**Agent uses create_job:**
+```
+✅ Job created successfully!
+Job ID: job_abc123
+Status: pending
+...
+```
+
+**Agent calls wait_for_result repeatedly until complete:**
+```
+⏳ Job Status: in_progress
+Waited 30s, job not complete yet.
+💡 Suggestion: Call wait_for_result again with waitSeconds: 45
+```
+
+**Finally:**
+```
+✅ Test completed!
+Results Summary:
+- Checkout Flow: ✅ Working
+- Payment Processing: ✅ Successful
+...
+```
+
+## Developer Documentation
+
+For developers working on this MCP server:
+- [docs/HOW-AGENTS-USE-MCP.md](docs/HOW-AGENTS-USE-MCP.md) - How AI agents discover and use MCP servers
+- [docs/TOOL-RESPONSE-BEST-PRACTICES.md](docs/TOOL-RESPONSE-BEST-PRACTICES.md) - Best practices for tool responses
+
+## Learn More
+
+- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
+- [RunHuman API Documentation](../api/README.md)

package/dist/index.d.ts

@@ -1,12 +1,9 @@
 #!/usr/bin/env node
 /**
- * RunHuman MCP Server
+ * RunHuman MCP Server - stdio entry point
  *
- * This MCP server provides tools for AI agents to interact with the RunHuman QA testing service.
- * It allows agents to:
- * - Create QA jobs
- * - Check job status
- * - Retrieve job results
+ * This is the CLI entry point for npx @runhuman/mcp-server.
+ * It uses stdio transport for communication with MCP clients like Claude Desktop.
  *
  * @see https://modelcontextprotocol.io/
  */

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;GAUG"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;;;GAOG"}