mcp-server-mturk 0.1.0__py3-none-any.whl

mcp_server_mturk-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,14 @@
+mturk_mcp/__init__.py,sha256=XI0gVmk3eMl7PXwfwx33zLRuNp2K-0IL2rB3cxJY5ks,106
+mturk_mcp/client.py,sha256=H4MGR8YbpaMhZr27ZBsCg9cLtJdcU4qqUvL0zUVbpIE,2635
+mturk_mcp/server.py,sha256=SBZHvdf_8cByjdY1AmSJ-UEKmP3c0NL8E-fOj4bWCwY,2124
+mturk_mcp/tools/__init__.py,sha256=Vc4VQLqJ1omADCP2BfqHWOni4yvluKIgO2Kui1Za6KU,194
+mturk_mcp/tools/account.py,sha256=AApFAuOvopIWCyTJNeIkphEI2IASXOea5dBTs1FnzLg,5137
+mturk_mcp/tools/assignments.py,sha256=ZFOAerNh7B14J8OeVx-A4y3kgVnETgbxaNntCXPc7O8,15382
+mturk_mcp/tools/hits.py,sha256=lb9xY-XCQMyCu_GzE95xXvNuLm5DASyipeuVkoMrZQA,18951
+mturk_mcp/tools/qualifications.py,sha256=iG9Kz5D34i8IinKMu1rP085zg64ZpbWkSVz7hwfXgCY,16577
+mturk_mcp/tools/workers.py,sha256=4GLZlDFzyzyUMM9pT4IJv5pXmTHrG9CpDIx1IqxgHsg,15392
+mcp_server_mturk-0.1.0.dist-info/METADATA,sha256=x81GIMAG5Ea2ShwPTxnGfr-ZcXroId6Y6vhu5VmpKGA,7665
+mcp_server_mturk-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+mcp_server_mturk-0.1.0.dist-info/entry_points.txt,sha256=RgDOzQaUXCG-ocgo8GhKw7dzh3uKXO_2gE7LuP0P_GM,59
+mcp_server_mturk-0.1.0.dist-info/licenses/LICENSE,sha256=IPe1EzjsFk59zmD6boPfdk5F0YQMtj9XafgjyMQFJBI,1071
+mcp_server_mturk-0.1.0.dist-info/RECORD,,

mcp_server_mturk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mcp_server_mturk-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mcp-server-mturk = mturk_mcp.server:main

mcp_server_mturk-0.1.0.dist-info/licenses/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.

mturk_mcp/__init__.py

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

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)}"

mturk_mcp/server.py

@@ -0,0 +1,75 @@
+"""MTurk MCP Server - Main entry point."""
+
+import asyncio
+import json
+import sys
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import Tool, TextContent
+
+from .client import get_mturk_client, format_error, wrap_html_question, is_sandbox
+
+# Create server instance
+server = Server("mturk")
+
+# Import tool handlers
+from .tools import hits, assignments, qualifications, workers, account
+
+# Collect all tools from modules
+ALL_TOOLS: list[Tool] = []
+TOOL_HANDLERS: dict[str, callable] = {}
+
+
+def register_tool(name: str, description: str, input_schema: dict, handler: callable):
+    """Register a tool with its schema and handler."""
+    ALL_TOOLS.append(Tool(
+        name=name,
+        description=description,
+        inputSchema=input_schema,
+    ))
+    TOOL_HANDLERS[name] = handler
+
+
+# Register all tools from modules
+hits.register_tools(register_tool)
+assignments.register_tools(register_tool)
+qualifications.register_tools(register_tool)
+workers.register_tools(register_tool)
+account.register_tools(register_tool)
+
+
+@server.list_tools()
+async def handle_list_tools() -> list[Tool]:
+    """Return all available MTurk tools."""
+    return ALL_TOOLS
+
+
+@server.call_tool()
+async def handle_call_tool(name: str, arguments: dict) -> list[TextContent]:
+    """Handle tool invocations."""
+    if name not in TOOL_HANDLERS:
+        return [TextContent(type="text", text=f"Unknown tool: {name}")]
+
+    try:
+        handler = TOOL_HANDLERS[name]
+        result = await handler(arguments)
+        return result
+    except Exception as e:
+        return [TextContent(type="text", text=format_error(e))]
+
+
+async def run():
+    """Run the MCP server with stdio transport."""
+    print("[mturk-mcp] Starting MTurk MCP server...", file=sys.stderr)
+    print(f"[mturk-mcp] Registered {len(ALL_TOOLS)} tools", file=sys.stderr)
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(read_stream, write_stream, server.create_initialization_options())
+
+
+def main():
+    """Entry point for the MCP server."""
+    asyncio.run(run())
+
+
+if __name__ == "__main__":
+    main()

mturk_mcp/tools/__init__.py

@@ -0,0 +1,5 @@
+"""MTurk MCP tools - organized by functionality."""
+
+from . import hits, assignments, qualifications, workers, account
+
+__all__ = ["hits", "assignments", "qualifications", "workers", "account"]

mturk_mcp/tools/account.py

@@ -0,0 +1,109 @@
+"""Account and utility tools for MTurk."""
+
+import json
+from mcp.types import TextContent
+
+from ..client import get_mturk_client, format_error, is_sandbox
+
+
+def register_tools(register):
+    """Register account-related tools."""
+
+    async def get_account_balance(args: dict) -> list[TextContent]:
+        """Get the available balance in your MTurk requester account."""
+        try:
+            client = get_mturk_client()
+            response = client.get_account_balance()
+            result = {
+                "available_balance": response["AvailableBalance"],
+                "on_hold_balance": response.get("OnHoldBalance"),
+                "environment": "sandbox" if is_sandbox() else "production",
+            }
+            return [TextContent(type="text", text=json.dumps(result, indent=2))]
+        except Exception as e:
+            return [TextContent(type="text", text=format_error(e))]
+
+    register(
+        "get_account_balance",
+        """Retrieves the current available balance in your Amazon Mechanical Turk requester account.
+
+Use this tool to check how much money you have available before creating HITs, or to verify funds after making payments. The balance is returned in USD.
+
+Returns two values:
+- available_balance: Money you can spend on HITs and bonuses right now
+- on_hold_balance: Money reserved for pending assignments (will be released when you approve/reject work)
+
+Also indicates whether you're connected to the sandbox (testing) or production environment. In sandbox mode, the balance is fake money for testing purposes.
+
+This tool takes no parameters and should be called whenever you need to verify you have sufficient funds for an operation.""",
+        {"type": "object", "properties": {}, "required": []},
+        get_account_balance,
+    )
+
+    async def list_reviewable_hits(args: dict) -> list[TextContent]:
+        """List HITs that have assignments ready for review."""
+        try:
+            client = get_mturk_client()
+            params = {
+                "Status": args.get("status", "Reviewable"),
+                "MaxResults": min(args.get("max_results", 100), 100),
+            }
+            if args.get("hit_type_id"):
+                params["HITTypeId"] = args["hit_type_id"]
+
+            response = client.list_reviewable_hits(**params)
+            hits = response.get("HITs", [])
+            result = {
+                "count": len(hits),
+                "hits": [
+                    {
+                        "hit_id": hit["HITId"],
+                        "hit_type_id": hit.get("HITTypeId"),
+                        "title": hit.get("Title"),
+                        "creation_time": str(hit.get("CreationTime")),
+                    }
+                    for hit in hits
+                ],
+            }
+            return [TextContent(type="text", text=json.dumps(result, indent=2))]
+        except Exception as e:
+            return [TextContent(type="text", text=format_error(e))]
+
+    register(
+        "list_reviewable_hits",
+        """Finds HITs that have worker submissions waiting to be reviewed (approved or rejected).
+
+Use this tool when you want to check if any workers have completed assignments that need your attention. This is typically the first step in the review workflow - call this to find HITs with pending work, then use list_assignments to see the actual submissions.
+
+A HIT becomes 'Reviewable' when at least one worker has submitted an assignment that hasn't been approved or rejected yet. Once all assignments for a HIT are reviewed, it moves out of the reviewable state.
+
+The status parameter filters results:
+- 'Reviewable' (default): HITs with at least one submitted assignment awaiting review
+- 'Reviewing': HITs you've marked as being actively reviewed (rarely used)
+
+Returns basic HIT info including hit_id (needed for list_assignments), title, and creation time. Does not return the actual worker submissions - use list_assignments for that.""",
+        {
+            "type": "object",
+            "properties": {
+                "hit_type_id": {
+                    "type": "string",
+                    "description": "Optional filter to only show HITs of a specific type. HIT types group HITs with the same reward, duration, and qualifications. Omit to see all reviewable HITs."
+                },
+                "status": {
+                    "type": "string",
+                    "enum": ["Reviewable", "Reviewing"],
+                    "description": "Filter by review status. 'Reviewable' (default) shows HITs with pending submissions. 'Reviewing' shows HITs marked as being actively reviewed.",
+                    "default": "Reviewable"
+                },
+                "max_results": {
+                    "type": "integer",
+                    "description": "Maximum number of HITs to return, between 1 and 100. Defaults to 100. Use smaller values for faster responses when you only need a few results.",
+                    "default": 100,
+                    "minimum": 1,
+                    "maximum": 100
+                },
+            },
+            "required": [],
+        },
+        list_reviewable_hits,
+    )