mcp-server-mturk 0.1.0__tar.gz

mcp_server_mturk-0.1.0/.claude/settings.local.json

@@ -0,0 +1,14 @@
+{
+  "permissions": {
+    "allow": [
+      "mcp__mturk-sandbox__get_account_balance",
+      "mcp__mturk-sandbox__list_hits",
+      "mcp__mturk-sandbox__list_reviewable_hits",
+      "mcp__mturk-sandbox__list_blocked_workers",
+      "mcp__mturk-sandbox__list_qualification_types",
+      "mcp__mturk-sandbox__create_hit",
+      "mcp__mturk-sandbox__list_assignments",
+      "mcp__mturk-sandbox__approve_assignment"
+    ]
+  }
+}

mcp_server_mturk-0.1.0/.env.example

@@ -0,0 +1,7 @@
+# AWS Credentials for MTurk
+AWS_ACCESS_KEY_ID=your_access_key_here
+AWS_SECRET_ACCESS_KEY=your_secret_key_here
+
+# Set to "true" to use MTurk Sandbox (for testing)
+# Leave as "false" or unset for production
+MTURK_SANDBOX=true

mcp_server_mturk-0.1.0/LICENSE

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

mcp_server_mturk-0.1.0/PKG-INFO

@@ -0,0 +1,271 @@
+Metadata-Version: 2.4
+Name: mcp-server-mturk
+Version: 0.1.0
+Summary: MCP server for Amazon Mechanical Turk - enables AI agents to create HITs, review assignments, manage workers, and access human intelligence
+Project-URL: Homepage, https://github.com/davidmcsharry/mcp-server-mturk
+Project-URL: Repository, https://github.com/davidmcsharry/mcp-server-mturk
+Project-URL: Issues, https://github.com/davidmcsharry/mcp-server-mturk/issues
+Author: David McSharry
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,amazon,crowdsourcing,human-intelligence,llm,mcp,mechanical-turk,model-context-protocol,mturk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: boto3>=1.35.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Description-Content-Type: text/markdown
+
+# mcp-server-mturk
+
+An MCP (Model Context Protocol) server that enables AI agents to interact with Amazon Mechanical Turk. This allows AI systems to request human intelligence for surveys, data labeling, content moderation, and any other MTurk-supported task.
+
+## Features
+
+- **24 tools** covering the full MTurk API
+- **HIT Management**: Create, list, update, and delete Human Intelligence Tasks
+- **Assignment Workflow**: Review, approve, reject, and bulk-approve worker submissions
+- **Qualification System**: Create custom qualifications to filter workers
+- **Worker Management**: Block/unblock workers, send notifications, pay bonuses
+- **Account Management**: Check balance, list reviewable HITs
+
+## Installation
+
+### Using uvx (recommended)
+
+No installation needed. Run directly:
+
+```bash
+uvx mcp-server-mturk
+```
+
+### Using pip
+
+```bash
+pip install mcp-server-mturk
+python -m mturk_mcp.server
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `AWS_ACCESS_KEY_ID` | Yes | Your AWS access key with MTurk permissions |
+| `AWS_SECRET_ACCESS_KEY` | Yes | Your AWS secret key |
+| `MTURK_SANDBOX` | No | Set to `true` for sandbox mode (testing) |
+
+### AWS Credentials Setup
+
+1. Go to [AWS IAM Console](https://console.aws.amazon.com/iam/)
+2. Create a new user with `AmazonMechanicalTurkFullAccess` policy
+3. Generate access keys for the user
+
+### MTurk Account Setup
+
+1. Create an [MTurk Requester account](https://requester.mturk.com/)
+2. For testing, also register for the [MTurk Sandbox](https://requestersandbox.mturk.com/)
+
+## Usage with AI Clients
+
+### Claude Code
+
+```bash
+# Sandbox mode (recommended for testing)
+claude mcp add mturk-sandbox \
+  --env AWS_ACCESS_KEY_ID=your_key \
+  --env AWS_SECRET_ACCESS_KEY=your_secret \
+  --env MTURK_SANDBOX=true \
+  -- uvx mcp-server-mturk
+
+# Production mode (uses real money!)
+claude mcp add mturk \
+  --env AWS_ACCESS_KEY_ID=your_key \
+  --env AWS_SECRET_ACCESS_KEY=your_secret \
+  -- uvx mcp-server-mturk
+```
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "mturk-sandbox": {
+      "command": "uvx",
+      "args": ["mcp-server-mturk"],
+      "env": {
+        "AWS_ACCESS_KEY_ID": "your_key",
+        "AWS_SECRET_ACCESS_KEY": "your_secret",
+        "MTURK_SANDBOX": "true"
+      }
+    }
+  }
+}
+```
+
+Config file locations:
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+### Cursor
+
+Add to Cursor's MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "mturk": {
+      "command": "uvx",
+      "args": ["mcp-server-mturk"],
+      "env": {
+        "AWS_ACCESS_KEY_ID": "your_key",
+        "AWS_SECRET_ACCESS_KEY": "your_secret",
+        "MTURK_SANDBOX": "true"
+      }
+    }
+  }
+}
+```
+
+### Using pip instead of uvx
+
+Replace `"command": "uvx", "args": ["mcp-server-mturk"]` with:
+
+```json
+{
+  "command": "python",
+  "args": ["-m", "mturk_mcp.server"]
+}
+```
+
+## Available Tools
+
+### HIT Operations (6 tools)
+
+| Tool | Description |
+|------|-------------|
+| `create_hit` | Create a new Human Intelligence Task with HTML form |
+| `get_hit` | Get details and status of a specific HIT |
+| `list_hits` | List all HITs for your account |
+| `delete_hit` | Delete a HIT (must have no pending assignments) |
+| `update_hit_expiration` | Extend or expire a HIT |
+| `create_additional_assignments` | Add more worker slots to an existing HIT |
+
+### Assignment Management (5 tools)
+
+| Tool | Description |
+|------|-------------|
+| `list_assignments` | Get all worker submissions for a HIT |
+| `get_assignment` | Get details including worker's answer |
+| `approve_assignment` | Approve and pay for completed work |
+| `reject_assignment` | Reject unsatisfactory work (use sparingly) |
+| `approve_all_submitted_assignments` | Bulk approve all pending assignments |
+
+### Qualification Management (5 tools)
+
+| Tool | Description |
+|------|-------------|
+| `create_qualification_type` | Create a custom worker qualification |
+| `list_qualification_types` | List available qualifications |
+| `assign_qualification` | Grant a qualification to a worker |
+| `revoke_qualification` | Remove a qualification from a worker |
+| `get_qualification_score` | Check a worker's qualification value |
+
+### Worker Management (6 tools)
+
+| Tool | Description |
+|------|-------------|
+| `block_worker` | Block a worker from all your HITs |
+| `unblock_worker` | Remove a worker block |
+| `list_blocked_workers` | List all blocked workers |
+| `notify_workers` | Send email to workers |
+| `send_bonus` | Send bonus payment to a worker |
+| `list_bonus_payments` | List bonus payments made |
+
+### Account & Utility (2 tools)
+
+| Tool | Description |
+|------|-------------|
+| `get_account_balance` | Check your MTurk account balance |
+| `list_reviewable_hits` | Find HITs with work ready for review |
+
+## Example Prompts
+
+Once connected, you can ask your AI assistant things like:
+
+```
+"Check my MTurk account balance"
+
+"Create a survey HIT asking 100 people their favorite programming language, paying $0.10 each"
+
+"List all my HITs and show which ones have pending assignments"
+
+"Show me the submitted assignments for HIT abc123"
+
+"Approve all submitted assignments for HIT abc123 with the message 'Thank you!'"
+
+"Send a $0.50 bonus to worker xyz789 for their detailed response"
+
+"Create a 'Trusted Worker' qualification and assign it to workers who did good work"
+```
+
+## Sandbox vs Production
+
+| Mode | Environment Variable | Use For |
+|------|---------------------|---------|
+| **Sandbox** | `MTURK_SANDBOX=true` | Testing, development, no real money |
+| **Production** | `MTURK_SANDBOX=false` (or unset) | Real HITs, real workers, real payments |
+
+**Always test with sandbox first!** Production mode uses real money and interacts with real workers.
+
+## Development
+
+### Running locally
+
+```bash
+# Clone and install
+git clone https://github.com/davidmcsharry/mcp-server-mturk
+cd mcp-server-mturk
+uv sync
+
+# Run the server
+uv run python -m mturk_mcp.server
+```
+
+### Testing with MCP Inspector
+
+```bash
+npx @modelcontextprotocol/inspector uvx mcp-server-mturk
+```
+
+### Building
+
+```bash
+uv build
+```
+
+### Publishing to PyPI
+
+```bash
+uv publish
+```
+
+## License
+
+MIT
+
+## Links
+
+- [Model Context Protocol](https://modelcontextprotocol.io/)
+- [MTurk API Documentation](https://docs.aws.amazon.com/AWSMechTurk/latest/AWSMturkAPI/Welcome.html)
+- [MTurk Requester Portal](https://requester.mturk.com/)
+- [MTurk Sandbox](https://requestersandbox.mturk.com/)

mcp_server_mturk-0.1.0/README.md

@@ -0,0 +1,247 @@
+# mcp-server-mturk
+
+An MCP (Model Context Protocol) server that enables AI agents to interact with Amazon Mechanical Turk. This allows AI systems to request human intelligence for surveys, data labeling, content moderation, and any other MTurk-supported task.
+
+## Features
+
+- **24 tools** covering the full MTurk API
+- **HIT Management**: Create, list, update, and delete Human Intelligence Tasks
+- **Assignment Workflow**: Review, approve, reject, and bulk-approve worker submissions
+- **Qualification System**: Create custom qualifications to filter workers
+- **Worker Management**: Block/unblock workers, send notifications, pay bonuses
+- **Account Management**: Check balance, list reviewable HITs
+
+## Installation
+
+### Using uvx (recommended)
+
+No installation needed. Run directly:
+
+```bash
+uvx mcp-server-mturk
+```
+
+### Using pip
+
+```bash
+pip install mcp-server-mturk
+python -m mturk_mcp.server
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `AWS_ACCESS_KEY_ID` | Yes | Your AWS access key with MTurk permissions |
+| `AWS_SECRET_ACCESS_KEY` | Yes | Your AWS secret key |
+| `MTURK_SANDBOX` | No | Set to `true` for sandbox mode (testing) |
+
+### AWS Credentials Setup
+
+1. Go to [AWS IAM Console](https://console.aws.amazon.com/iam/)
+2. Create a new user with `AmazonMechanicalTurkFullAccess` policy
+3. Generate access keys for the user
+
+### MTurk Account Setup
+
+1. Create an [MTurk Requester account](https://requester.mturk.com/)
+2. For testing, also register for the [MTurk Sandbox](https://requestersandbox.mturk.com/)
+
+## Usage with AI Clients
+
+### Claude Code
+
+```bash
+# Sandbox mode (recommended for testing)
+claude mcp add mturk-sandbox \
+  --env AWS_ACCESS_KEY_ID=your_key \
+  --env AWS_SECRET_ACCESS_KEY=your_secret \
+  --env MTURK_SANDBOX=true \
+  -- uvx mcp-server-mturk
+
+# Production mode (uses real money!)
+claude mcp add mturk \
+  --env AWS_ACCESS_KEY_ID=your_key \
+  --env AWS_SECRET_ACCESS_KEY=your_secret \
+  -- uvx mcp-server-mturk
+```
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "mturk-sandbox": {
+      "command": "uvx",
+      "args": ["mcp-server-mturk"],
+      "env": {
+        "AWS_ACCESS_KEY_ID": "your_key",
+        "AWS_SECRET_ACCESS_KEY": "your_secret",
+        "MTURK_SANDBOX": "true"
+      }
+    }
+  }
+}
+```
+
+Config file locations:
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+### Cursor
+
+Add to Cursor's MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "mturk": {
+      "command": "uvx",
+      "args": ["mcp-server-mturk"],
+      "env": {
+        "AWS_ACCESS_KEY_ID": "your_key",
+        "AWS_SECRET_ACCESS_KEY": "your_secret",
+        "MTURK_SANDBOX": "true"
+      }
+    }
+  }
+}
+```
+
+### Using pip instead of uvx
+
+Replace `"command": "uvx", "args": ["mcp-server-mturk"]` with:
+
+```json
+{
+  "command": "python",
+  "args": ["-m", "mturk_mcp.server"]
+}
+```
+
+## Available Tools
+
+### HIT Operations (6 tools)
+
+| Tool | Description |
+|------|-------------|
+| `create_hit` | Create a new Human Intelligence Task with HTML form |
+| `get_hit` | Get details and status of a specific HIT |
+| `list_hits` | List all HITs for your account |
+| `delete_hit` | Delete a HIT (must have no pending assignments) |
+| `update_hit_expiration` | Extend or expire a HIT |
+| `create_additional_assignments` | Add more worker slots to an existing HIT |
+
+### Assignment Management (5 tools)
+
+| Tool | Description |
+|------|-------------|
+| `list_assignments` | Get all worker submissions for a HIT |
+| `get_assignment` | Get details including worker's answer |
+| `approve_assignment` | Approve and pay for completed work |
+| `reject_assignment` | Reject unsatisfactory work (use sparingly) |
+| `approve_all_submitted_assignments` | Bulk approve all pending assignments |
+
+### Qualification Management (5 tools)
+
+| Tool | Description |
+|------|-------------|
+| `create_qualification_type` | Create a custom worker qualification |
+| `list_qualification_types` | List available qualifications |
+| `assign_qualification` | Grant a qualification to a worker |
+| `revoke_qualification` | Remove a qualification from a worker |
+| `get_qualification_score` | Check a worker's qualification value |
+
+### Worker Management (6 tools)
+
+| Tool | Description |
+|------|-------------|
+| `block_worker` | Block a worker from all your HITs |
+| `unblock_worker` | Remove a worker block |
+| `list_blocked_workers` | List all blocked workers |
+| `notify_workers` | Send email to workers |
+| `send_bonus` | Send bonus payment to a worker |
+| `list_bonus_payments` | List bonus payments made |
+
+### Account & Utility (2 tools)
+
+| Tool | Description |
+|------|-------------|
+| `get_account_balance` | Check your MTurk account balance |
+| `list_reviewable_hits` | Find HITs with work ready for review |
+
+## Example Prompts
+
+Once connected, you can ask your AI assistant things like:
+
+```
+"Check my MTurk account balance"
+
+"Create a survey HIT asking 100 people their favorite programming language, paying $0.10 each"
+
+"List all my HITs and show which ones have pending assignments"
+
+"Show me the submitted assignments for HIT abc123"
+
+"Approve all submitted assignments for HIT abc123 with the message 'Thank you!'"
+
+"Send a $0.50 bonus to worker xyz789 for their detailed response"
+
+"Create a 'Trusted Worker' qualification and assign it to workers who did good work"
+```
+
+## Sandbox vs Production
+
+| Mode | Environment Variable | Use For |
+|------|---------------------|---------|
+| **Sandbox** | `MTURK_SANDBOX=true` | Testing, development, no real money |
+| **Production** | `MTURK_SANDBOX=false` (or unset) | Real HITs, real workers, real payments |
+
+**Always test with sandbox first!** Production mode uses real money and interacts with real workers.
+
+## Development
+
+### Running locally
+
+```bash
+# Clone and install
+git clone https://github.com/davidmcsharry/mcp-server-mturk
+cd mcp-server-mturk
+uv sync
+
+# Run the server
+uv run python -m mturk_mcp.server
+```
+
+### Testing with MCP Inspector
+
+```bash
+npx @modelcontextprotocol/inspector uvx mcp-server-mturk
+```
+
+### Building
+
+```bash
+uv build
+```
+
+### Publishing to PyPI
+
+```bash
+uv publish
+```
+
+## License
+
+MIT
+
+## Links
+
+- [Model Context Protocol](https://modelcontextprotocol.io/)
+- [MTurk API Documentation](https://docs.aws.amazon.com/AWSMechTurk/latest/AWSMturkAPI/Welcome.html)
+- [MTurk Requester Portal](https://requester.mturk.com/)
+- [MTurk Sandbox](https://requestersandbox.mturk.com/)

mcp_server_mturk-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "mcp-server-mturk"
+version = "0.1.0"
+description = "MCP server for Amazon Mechanical Turk - enables AI agents to create HITs, review assignments, manage workers, and access human intelligence"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "David McSharry" }
+]
+keywords = [
+    "mcp",
+    "model-context-protocol",
+    "mturk",
+    "mechanical-turk",
+    "amazon",
+    "crowdsourcing",
+    "human-intelligence",
+    "ai-agents",
+    "llm",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "mcp>=1.0.0",
+    "boto3>=1.35.0",
+    "pydantic>=2.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/davidmcsharry/mcp-server-mturk"
+Repository = "https://github.com/davidmcsharry/mcp-server-mturk"
+Issues = "https://github.com/davidmcsharry/mcp-server-mturk/issues"
+
+[project.scripts]
+mcp-server-mturk = "mturk_mcp.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mturk_mcp"]

mcp_server_mturk-0.1.0/src/mturk_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""MTurk MCP Server - Enable AI agents to interact with Amazon Mechanical Turk."""
+
+__version__ = "0.1.0"

mcp_server_mturk-0.1.0/src/mturk_mcp/client.py

@@ -0,0 +1,75 @@
+"""AWS MTurk client wrapper with environment-based configuration."""
+
+import os
+import sys
+import boto3
+from botocore.exceptions import ClientError, NoCredentialsError
+
+_client = None
+
+SANDBOX_ENDPOINT = "https://mturk-requester-sandbox.us-east-1.amazonaws.com"
+
+
+def get_mturk_client():
+    """Get or create the MTurk client singleton."""
+    global _client
+    if _client is None:
+        use_sandbox = os.environ.get("MTURK_SANDBOX", "false").lower() == "true"
+        endpoint_url = SANDBOX_ENDPOINT if use_sandbox else None
+
+        _client = boto3.client(
+            "mturk",
+            region_name="us-east-1",
+            endpoint_url=endpoint_url,
+            aws_access_key_id=os.environ.get("AWS_ACCESS_KEY_ID"),
+            aws_secret_access_key=os.environ.get("AWS_SECRET_ACCESS_KEY"),
+        )
+
+        # Log which environment we're using
+        env_name = "SANDBOX" if use_sandbox else "PRODUCTION"
+        print(f"[mturk-mcp] Connected to MTurk {env_name}", file=sys.stderr)
+
+    return _client
+
+
+def is_sandbox() -> bool:
+    """Check if we're using the sandbox environment."""
+    return os.environ.get("MTURK_SANDBOX", "false").lower() == "true"
+
+
+def wrap_html_question(html_content: str) -> str:
+    """Wrap HTML content in MTurk's HTMLQuestion format."""
+    return f"""<?xml version="1.0" encoding="UTF-8"?>
+<HTMLQuestion xmlns="http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/2011-11-11/HTMLQuestion.xsd">
+  <HTMLContent><![CDATA[
+<!DOCTYPE html>
+<html>
+<head>
+  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
+  <script type="text/javascript" src="https://s3.amazonaws.com/mturk-public/externalHIT_v1.js"></script>
+</head>
+<body>
+  <form name="mturk_form" method="post" id="mturk_form" action="https://www.mturk.com/mturk/externalSubmit">
+    <input type="hidden" name="assignmentId" id="assignmentId" value="">
+    {html_content}
+    <p><input type="submit" id="submitButton" value="Submit"></p>
+  </form>
+  <script>
+    turkSetAssignmentID();
+  </script>
+</body>
+</html>
+]]></HTMLContent>
+  <FrameHeight>600</FrameHeight>
+</HTMLQuestion>"""
+
+
+def format_error(e: Exception) -> str:
+    """Format AWS errors into user-friendly messages."""
+    if isinstance(e, NoCredentialsError):
+        return "AWS credentials not found. Set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables."
+    if isinstance(e, ClientError):
+        error_code = e.response.get("Error", {}).get("Code", "Unknown")
+        error_msg = e.response.get("Error", {}).get("Message", str(e))
+        return f"MTurk API error ({error_code}): {error_msg}"
+    return f"Error: {str(e)}"