{"_id":"@andrewlwn77/s3-upload-mcp-server","name":"@andrewlwn77/s3-upload-mcp-server","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@andrewlwn77/s3-upload-mcp-server","version":"1.0.0","description":"Pure Node.js MCP server for uploading images to AWS S3 with high-performance validation using Sharp and file-type","main":"dist/index.js","bin":{"s3-upload-mcp-server":"dist/index.js"},"directories":{"doc":"docs","test":"tests"},"scripts":{"build":"tsc","start":"node dist/index.js","dev":"tsc --watch","test":"jest","lint":"eslint src/**/*.ts","clean":"rm -rf dist"},"keywords":["mcp","model-context-protocol","aws","s3","image-upload","sharp","nodejs","aws-sdk-v3","file-type","image-validation"],"author":{"name":"andrewlwn77"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/andrewlwn77/s3-upload-mcp-server.git"},"dependencies":{"@aws-sdk/client-s3":"^3.879.0","@aws-sdk/s3-request-presigner":"^3.879.0","@modelcontextprotocol/sdk":"^0.6.0","file-type":"^21.0.0","mime-types":"^2.1.35","sharp":"^0.34.3","uuid":"^10.0.0"},"devDependencies":{"@types/jest":"^29.5.0","@types/mime-types":"^2.1.4","@types/node":"^22.0.0","@types/uuid":"^10.0.0","@typescript-eslint/eslint-plugin":"^6.0.0","@typescript-eslint/parser":"^6.0.0","eslint":"^8.0.0","jest":"^29.0.0","ts-jest":"^29.0.0","typescript":"^5.0.0"},"engines":{"node":">=18.0.0"},"_id":"@andrewlwn77/s3-upload-mcp-server@1.0.0","gitHead":"9e8cd32510e967324e737bc1ae76be6acb31649d","types":"./dist/index.d.ts","bugs":{"url":"https://github.com/andrewlwn77/s3-upload-mcp-server/issues"},"homepage":"https://github.com/andrewlwn77/s3-upload-mcp-server#readme","_nodeVersion":"22.13.1","_npmVersion":"10.9.2","dist":{"integrity":"sha512-iHmekFNtL+wDsnA7MfY/Sromt8j5XEX1ONeVYMuIFOf8dViy9ZCtnaxUvnU69x5vILdHIobn4ep5g0SbqRhxfw==","shasum":"25877a34aaa0c0a61fed20b02d574dfefc1e87fe","tarball":"https://registry.npmjs.org/@andrewlwn77/s3-upload-mcp-server/-/s3-upload-mcp-server-1.0.0.tgz","fileCount":69,"unpackedSize":464658,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCOfHfxEq1B6LoHC5nmJfDCJM2wSVe5ML6tfx+Te1zzzQIgM4wjucE8r3egB2w4Hk+wB57Njzn1A/3uipslDRVZseQ="}]},"_npmUser":{"name":"andrewlwn77","email":"andrewlwn@gmail.com"},"maintainers":[{"name":"andrewlwn77","email":"andrewlwn@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/s3-upload-mcp-server_1.0.0_1756788857940_0.16872106710633772"},"_hasShrinkwrap":false}},"time":{"created":"2025-09-02T04:54:17.839Z","1.0.0":"2025-09-02T04:54:18.120Z","modified":"2025-09-02T04:54:18.393Z"},"maintainers":[{"name":"andrewlwn77","email":"andrewlwn@gmail.com"}],"description":"Pure Node.js MCP server for uploading images to AWS S3 with high-performance validation using Sharp and file-type","homepage":"https://github.com/andrewlwn77/s3-upload-mcp-server#readme","keywords":["mcp","model-context-protocol","aws","s3","image-upload","sharp","nodejs","aws-sdk-v3","file-type","image-validation"],"repository":{"type":"git","url":"git+https://github.com/andrewlwn77/s3-upload-mcp-server.git"},"author":{"name":"andrewlwn77"},"bugs":{"url":"https://github.com/andrewlwn77/s3-upload-mcp-server/issues"},"license":"MIT","readme":"# S3 Upload MCP Server\n\nA Model Context Protocol (MCP) server that provides image upload capabilities to AWS S3 with public URL generation and bucket management.\n\n## Features\n\n- Upload images directly from base64 data or local filesystem\n- Generate signed public URLs for S3 objects\n- Create and manage S3 buckets with public read policies\n- **Pure Node.js implementation** - no Python dependencies\n- High-performance image validation using Sharp (format, size, dimensions)\n- Buffer-based MIME type detection with file-type\n- Unique filename generation with timestamps and UUIDs\n- Support for multiple image formats (JPEG, PNG, GIF, WebP, BMP)\n- Built with AWS SDK v3 for optimal performance\n\n## Installation\n\n### Via NPM (Recommended)\n\n```bash\nnpm install -g @andrewlwn77/s3-upload-mcp-server\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/andrewlwn77/s3-upload-mcp-server.git\ncd s3-upload-mcp-server\nnpm install\nnpm run build\n```\n\n## Prerequisites\n\n### System Dependencies\n\nPure Node.js implementation - no Python dependencies required! The server uses:\n\n- **Sharp**: High-performance image processing and validation\n- **file-type**: MIME type detection from file buffers\n- **AWS SDK v3**: Modern AWS S3 integration\n\nAll dependencies are automatically installed via npm.\n\n### AWS Configuration\n\nSet up your AWS credentials and configuration:\n\n```bash\nexport AWS_ACCESS_KEY_ID=\"your-access-key\"\nexport AWS_SECRET_ACCESS_KEY=\"your-secret-key\"\nexport AWS_DEFAULT_REGION=\"us-east-1\"\nexport S3_BUCKET_NAME=\"your-default-bucket\"  # Optional\n```\n\n#### Required AWS Permissions\n\nYour AWS credentials need the following S3 permissions:\n\n```json\n{\n  \"Version\": \"2012-10-17\",\n  \"Statement\": [\n    {\n      \"Effect\": \"Allow\",\n      \"Action\": [\n        \"s3:PutObject\",\n        \"s3:GetObject\",\n        \"s3:ListBucket\",\n        \"s3:CreateBucket\",\n        \"s3:PutBucketPolicy\",\n        \"s3:GetBucketLocation\"\n      ],\n      \"Resource\": [\n        \"arn:aws:s3:::your-bucket-name\",\n        \"arn:aws:s3:::your-bucket-name/*\"\n      ]\n    }\n  ]\n}\n```\n\n## Usage\n\n### As MCP Server\n\nAdd to your MCP configuration file (`.mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"s3-upload\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@andrewlwn77/s3-upload-mcp-server\"],\n      \"env\": {\n        \"AWS_ACCESS_KEY_ID\": \"your-access-key\",\n        \"AWS_SECRET_ACCESS_KEY\": \"your-secret-key\",\n        \"AWS_DEFAULT_REGION\": \"us-east-1\",\n        \"S3_BUCKET_NAME\": \"your-default-bucket\"\n      }\n    }\n  }\n}\n```\n\n### Direct Execution\n\n```bash\ns3-upload-mcp-server\n```\n\n## Available Tools\n\n### 1. upload_image_to_s3\n\nUpload image data directly to S3 bucket.\n\n**Parameters:**\n- `image_data` (string, required): Base64 encoded image data\n- `filename` (string, required): Desired filename with extension\n- `bucket` (string, optional): S3 bucket name\n- `content_type` (string, optional): MIME type\n\n**Example:**\n```json\n{\n  \"image_data\": \"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==\",\n  \"filename\": \"test-image.png\",\n  \"bucket\": \"my-image-bucket\"\n}\n```\n\n### 2. upload_image_file_to_s3\n\nUpload image file from local filesystem.\n\n**Parameters:**\n- `file_path` (string, required): Local path to image file\n- `bucket` (string, optional): S3 bucket name\n- `key` (string, optional): S3 object key\n- `preserve_filename` (boolean, optional): Preserve original filename\n\n**Example:**\n```json\n{\n  \"file_path\": \"/path/to/image.jpg\",\n  \"bucket\": \"my-image-bucket\",\n  \"preserve_filename\": true\n}\n```\n\n### 3. generate_public_url\n\nGenerate signed public URL for S3 object.\n\n**Parameters:**\n- `bucket` (string, required): S3 bucket name\n- `key` (string, required): S3 object key\n- `expiration` (integer, optional): URL expiration in seconds (300-604800)\n\n**Example:**\n```json\n{\n  \"bucket\": \"my-image-bucket\",\n  \"key\": \"images/photo.jpg\",\n  \"expiration\": 3600\n}\n```\n\n### 4. create_bucket_if_not_exists\n\nCreate S3 bucket with proper configuration.\n\n**Parameters:**\n- `bucket_name` (string, required): Bucket name (3-63 chars, lowercase)\n- `region` (string, optional): AWS region\n- `enable_public_read` (boolean, optional): Enable public read access\n\n**Example:**\n```json\n{\n  \"bucket_name\": \"my-new-bucket\",\n  \"region\": \"us-west-2\",\n  \"enable_public_read\": true\n}\n```\n\n### 5. set_bucket_public_read_policy\n\nConfigure bucket for public read access.\n\n**Parameters:**\n- `bucket_name` (string, required): S3 bucket name\n\n**Example:**\n```json\n{\n  \"bucket_name\": \"my-bucket\"\n}\n```\n\n### 6. generate_unique_filename\n\nGenerate unique filename with timestamp and UUID.\n\n**Parameters:**\n- `original_name` (string, required): Original filename\n- `prefix` (string, optional): Optional prefix\n- `include_timestamp` (boolean, optional): Include timestamp\n\n**Example:**\n```json\n{\n  \"original_name\": \"photo.jpg\",\n  \"prefix\": \"user_upload\",\n  \"include_timestamp\": true\n}\n```\n\n### 7. validate_image_format\n\nValidate image file format and properties.\n\n**Parameters:**\n- `file_path` (string, required): Path to image file\n- `max_file_size` (integer, optional): Maximum file size in bytes\n\n**Example:**\n```json\n{\n  \"file_path\": \"/path/to/image.jpg\",\n  \"max_file_size\": 5242880\n}\n```\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Required | Description | Default |\n|----------|----------|-------------|---------|\n| `AWS_ACCESS_KEY_ID` | ✅ | AWS access key ID | - |\n| `AWS_SECRET_ACCESS_KEY` | ✅ | AWS secret access key | - |\n| `AWS_DEFAULT_REGION` | ✅ | AWS region | `us-east-1` |\n| `S3_BUCKET_NAME` | ⚪ | Default S3 bucket name | - |\n| `LOG_LEVEL` | ⚪ | Logging level (ERROR, WARN, INFO, DEBUG) | `INFO` |\n| `MAX_FILE_SIZE` | ⚪ | Maximum file size in bytes | `10485760` |\n\n### Supported Image Formats\n\n- JPEG (.jpg, .jpeg)\n- PNG (.png)\n- GIF (.gif)\n- WebP (.webp)\n- BMP (.bmp)\n\n### File Size Limits\n\n- Default maximum: 10MB (10,485,760 bytes)\n- Configurable via `MAX_FILE_SIZE` environment variable\n- Large files (>5MB) use multipart upload automatically\n\n## Error Handling\n\nAll tools return structured responses with success status and error details:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"VALIDATION_ERROR\",\n    \"message\": \"File size exceeds maximum allowed\",\n    \"details\": {},\n    \"retry_after\": 300\n  }\n}\n```\n\n### Error Codes\n\n- `AUTH_ERROR`: AWS authentication failed\n- `BUCKET_ERROR`: S3 bucket operation failed\n- `UPLOAD_ERROR`: File upload failed\n- `VALIDATION_ERROR`: Input validation failed\n- `FILE_ERROR`: File system operation failed\n- `NETWORK_ERROR`: Network connectivity issues\n\n## Development\n\n### Building\n\n```bash\nnpm run build\n```\n\n### Testing\n\n```bash\nnpm test\n```\n\n### Development Mode\n\n```bash\nnpm run dev\n```\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## Support\n\nFor issues and questions:\n- GitHub Issues: https://github.com/andrewlwn77/s3-upload-mcp-server/issues\n- Documentation: See this README and inline code documentation","readmeFilename":"README.md","_rev":"1-f7a785ad3b83134749bf416bd7ff2a0c"}