feat: add bulk metadata transfer job management tools (#1594)

Co-authored-by: Sanket Agrawal <[email protected]>

Author: charlie-7

src/aws-iot-sitewise-mcp-server/README.md

@@ -30,6 +30,15 @@ A comprehensive MCP (Model Context Protocol) server that provides full AWS IoT S
 - **Time Series Management**: Associate and manage time series data streams
 - **Edge Computing**: Support for local data processing and intermittent connectivity
 
+#### 📦 Bulk Operations & Metadata Transfer
+
+- **Bulk Export**: Export ALL IoT SiteWise resources (asset models, assets, etc.) in one operation using metadata transfer jobs
+- **Bulk Import Schema**: Create and validate structured schemas for bulk asset/model imports
+- **Metadata Transfer Jobs**: Manage large-scale data migration between S3 and IoT SiteWise
+- **Job Monitoring**: Track progress and status of bulk operations
+- **Multi-Source Support**: Transfer data between S3 buckets and IoT SiteWise
+- **Schema Validation**: Ensure data integrity with comprehensive validation before import
+
 #### 🔒 Security & Configuration
 
 - **Access Policies**: Fine-grained access control for users and resources
@@ -72,17 +81,19 @@ Step-by-step guidance for setting up data ingestion:
 
 ```bash
 # Install UV if you don't have it yet
-curl -sSf https://astral.sh/uv/install | sh
+curl -sSf https://astral.sh/uv/install.sh | sh
 
 # Clone the repository
 git clone https://github.com/awslabs/mcp.git
-cd src/aws-iot-sitewise-mcp-server
+cd mcp/src/aws-iot-sitewise-mcp-server
 
 # Install as a uv tool (this makes it available globally via uvx)
 uv tool install .
 
 # The server is now available globally via uvx
 uvx awslabs.aws-iot-sitewise-mcp-server
+# use @latest flag for automatically pull updates on server
+uvx awslabs.aws-iot-sitewise-mcp-server@latest
 
 # Note: The server runs silently, waiting for MCP client connections.
 # You'll need to configure an MCP client to connect to it.
@@ -96,7 +107,7 @@ pip install aws-iot-sitewise-mcp
 
 # Or install from source
 git clone https://github.com/awslabs/mcp.git
-cd src/aws-iot-sitewise-mcp-server
+cd mcp/src/aws-iot-sitewise-mcp-server
 pip install .
 
 # Run the server
@@ -105,7 +116,10 @@ python -m awslabs.aws_iot_sitewise_mcp_server.server
 
 ### AWS Configuration
 
-Configure AWS credentials using any of these methods:
+Configure AWS credentials with permissions for:
+- AWS IoT SiteWise (full access for write operations)
+- AWS IoT TwinMaker (for metadata transfer operations)
+- Amazon S3 (for bulk import/export operations)
 
 ```bash
 # AWS CLI (recommended)
@@ -133,7 +147,7 @@ Add to your `claude_desktop_config.json`:
   "mcpServers": {
     "aws-iot-sitewise": {
       "command": "uvx",
-      "args": ["awslabs.aws-iot-sitewise-mcp-server"],
+      "args": ["awslabs.aws-iot-sitewise-mcp-server@latest"],
       "env": {
         "AWS_REGION": "us-west-2",
         "AWS_PROFILE": "your-profile-name",
@@ -152,7 +166,7 @@ Add to your `claude_desktop_config.json`:
   "mcpServers": {
     "aws-iot-sitewise": {
       "command": "uvx",
-      "args": ["awslabs.aws-iot-sitewise-mcp-server"],
+      "args": ["awslabs.aws-iot-sitewise-mcp-server@latest"],
       "env": {
         "AWS_REGION": "us-west-2",
         "AWS_PROFILE": "your-profile-name",
@@ -215,7 +229,7 @@ Configure in your workspace or global settings:
   "mcpServers": {
     "aws-iot-sitewise": {
       "command": "uvx",
-      "args": ["awslabs.aws-iot-sitewise-mcp-server"],
+      "args": ["awslabs.aws-iot-sitewise-mcp-server@latest"],
       "env": {
         "AWS_REGION": "us-west-2",
         "AWS_PROFILE": "your-profile-name",
@@ -234,7 +248,7 @@ Configure in your workspace or global settings:
   "mcpServers": {
     "aws-iot-sitewise": {
       "command": "uvx",
-      "args": ["awslabs.aws-iot-sitewise-mcp-server"],
+      "args": ["awslabs.aws-iot-sitewise-mcp-server@latest"],
       "env": {
         "AWS_REGION": "us-west-2",
         "AWS_PROFILE": "your-profile-name",
@@ -355,6 +369,16 @@ Configure in your workspace or global settings:
 | `unlink_time_series_asset_property` | Unlink streams |
 | `delete_time_series` | Remove time series |
 
+### Metadata Transfer & Bulk Import Tools
+
+| Tool Name | Description |
+|-----------|-------------|
+| `create_bulk_import_schema` | Construct and validate bulk import schemas for asset models and assets |
+| `create_metadata_transfer_job` | **🚀 PRIMARY TOOL for bulk export/import operations** - Use this for exporting all resources |
+| `cancel_metadata_transfer_job` | Cancel running metadata transfer jobs |
+| `get_metadata_transfer_job` | Get detailed information about metadata transfer jobs |
+| `list_metadata_transfer_jobs` | List metadata transfer jobs with filtering options |
+
 ### Access Control & Configuration Tools
 
 | Tool Name | Description |
@@ -637,6 +661,18 @@ The implementation is validated against:
    - Check timestamp formats
    - Validate data types and ranges
 
+4. **Metadata Transfer Issues**
+   - Verify IoT TwinMaker service permissions
+   - Check S3 bucket access for source/destination operations
+   - Validate bulk import schema format
+   - Monitor job status for detailed error messages
+
+5. **Bulk Import Schema Errors**
+   - Ensure asset model external IDs are unique
+   - Verify property data types match requirements
+   - Check hierarchy references are valid
+   - Use create_bulk_import_schema tool for validation
+
 ### Getting Help
 
 - Check AWS IoT SiteWise documentation

src/aws-iot-sitewise-mcp-server/awslabs/aws_iot_sitewise_mcp_server/client.py

@@ -45,3 +45,17 @@ def create_iam_client(region: str = 'us-east-1'):
     config = Config(user_agent_extra=f'awslabs/mcp/aws-iot-sitewise-mcp-server/{__version__}')
 
     return boto3.client('iam', region_name=region, config=config)
+
+
+def create_twinmaker_client(region: str = 'us-east-1'):
+    """Create a standardized AWS IoT TwinMaker client with proper user agent.
+
+    Args:
+        region: AWS region name (default: us-east-1)
+
+    Returns:
+        boto3 IoT TwinMaker client instance
+    """
+    config = Config(user_agent_extra=f'awslabs/mcp/aws-iot-sitewise-mcp-server/{__version__}')
+
+    return boto3.client('iottwinmaker', region_name=region, config=config)