{"_id":"@drumnation/unsplash-smart-mcp-server","_rev":"2-433e012a8aae40296d59bd0308360f1b","name":"@drumnation/unsplash-smart-mcp-server","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@drumnation/unsplash-smart-mcp-server","version":"1.0.0","keywords":["unsplash","mcp","fastmcp","api","stock-photos","ai-agent","attribution","images","cursor","claude"],"author":{"name":"drumnation"},"license":"MIT","_id":"@drumnation/unsplash-smart-mcp-server@1.0.0","maintainers":[{"name":"drumnation","email":"davidmieloch@gmail.com"}],"homepage":"https://github.com/drumnation/unsplash-smart-mcp-server#readme","bugs":{"url":"https://github.com/drumnation/unsplash-smart-mcp-server/issues"},"dist":{"shasum":"88ad7ec2d63406519cd54fdcb1948f5a9d0d649c","tarball":"https://registry.npmjs.org/@drumnation/unsplash-smart-mcp-server/-/unsplash-smart-mcp-server-1.0.0.tgz","fileCount":66,"integrity":"sha512-XA5/MJ0vdenunnhFGhZvvmrs3xMEJUsBNKdWCR87njj8z1jnZTki5405CIShUjTiE6BqpToW8HNce+kvXdKyhQ==","signatures":[{"sig":"MEYCIQC5Ct9H/Fc9DxIo1aznCOmEKQLSieUzuMRQlL4h9RY70wIhAL4VVLce824NxNgtml2rSF9OrWV02+9KpDUMRVLi0zUZ","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":285804},"main":"dist/server.js","type":"module","types":"./dist/server.d.ts","engines":{"node":">=18.x"},"gitHead":"081f0cf11ed02529a51fd6f8512b828f11e7830d","scripts":{"dev":"npx fastmcp dev src/server.ts","lint":"eslint . --ext .ts","test":"tsx --test src/__tests__/**/*.test.ts","build":"tsc","start":"tsx src/server.ts","inspect":"npx fastmcp inspect src/server.ts","publish-npm":"npm run prepare-release && npm publish --access public","test:docker":"tsx tests/docker/docker-test.js","test:manual":"tsx tests/test-stock-photo.js","test:smithery":"tsx tests/docker/smithery-integration.js","prepare-release":"npm run build && npm run test","generate-attributions":"tsx scripts/generate-attributions.ts"},"_npmUser":{"name":"drumnation","email":"davidmieloch@gmail.com"},"repository":{"url":"git+https://github.com/drumnation/unsplash-smart-mcp-server.git","type":"git"},"_npmVersion":"10.9.2","description":"AI-powered FastMCP server for intelligent stock photo search, download, and attribution management from Unsplash","directories":{},"_nodeVersion":"23.10.0","dependencies":{"zod":"^3.21.4","cors":"^2.8.5","glob":"^10.3.10","dotenv":"^16.0.3","express":"^5.0.1","fastmcp":"^1.0.0","fs-extra":"^11.1.1","exiftool-vendored":"^24.2.0","@modelcontextprotocol/sdk":"^1.8.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.15.0","yaml":"^2.7.1","typescript":"^5.0.4","@types/cors":"^2.8.17","@types/node":"^18.16.0","@types/express":"^5.0.1","@types/fs-extra":"^11.0.1"},"_npmOperationalInternal":{"tmp":"tmp/unsplash-smart-mcp-server_1.0.0_1743309879800_0.9592172828571444","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@drumnation/unsplash-smart-mcp-server","version":"1.0.1","description":"AI-powered FastMCP server for intelligent stock photo search, download, and attribution management from Unsplash","main":"dist/server.js","type":"module","scripts":{"build":"tsc","start":"node dist/server.js","dev":"npx fastmcp dev src/server.ts","inspect":"npx fastmcp inspect src/server.ts","test":"tsx --test src/__tests__/**/*.test.ts","test:all":"tsx tests/run-all-tests.js","test:manual":"tsx tests/test-stock-photo.js","test:docker":"tsx tests/docker/docker-test.js","test:docker:uptime":"tsx tests/docker/docker-uptime-test.js","test:smithery":"tsx tests/docker/smithery-integration.js","test:mcp":"tsx tests/mcp/test-mcp.js","lint":"eslint . --ext .ts","generate-attributions":"tsx scripts/generate-attributions.ts","debug-server":"node scripts/debug-server.js","prepare-release":"npm run build && npm run test","publish-npm":"npm run prepare-release && npm publish --access public"},"keywords":["unsplash","mcp","fastmcp","api","stock-photos","ai-agent","attribution","images","cursor","claude"],"author":{"name":"drumnation"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/drumnation/unsplash-smart-mcp-server.git"},"homepage":"https://github.com/drumnation/unsplash-smart-mcp-server#readme","bugs":{"url":"https://github.com/drumnation/unsplash-smart-mcp-server/issues"},"dependencies":{"@modelcontextprotocol/sdk":"^1.8.0","cors":"^2.8.5","dotenv":"^16.0.3","exiftool-vendored":"^24.2.0","express":"^5.0.1","fastmcp":"^1.0.0","fs-extra":"^11.1.1","glob":"^10.3.10","zod":"^3.21.4"},"devDependencies":{"@types/cors":"^2.8.17","@types/express":"^5.0.1","@types/fs-extra":"^11.0.1","@types/node":"^18.16.0","tsx":"^4.15.0","typescript":"^5.0.4","yaml":"^2.7.1"},"engines":{"node":">=18.x"},"_id":"@drumnation/unsplash-smart-mcp-server@1.0.1","gitHead":"e6a75ec72ddf519cb59787feb220c38e4d9979af","types":"./dist/server.d.ts","_nodeVersion":"23.10.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-UUXS70tkCF2KcUTCZODEEGqOFu04Ij/rNkwNqoEOkhR457xkxjjkneHI/Lh/JbViQltwHA/CGaGna89586sz0g==","shasum":"a3b69cbf4fc51acc945af2ae31fc8fece81a7716","tarball":"https://registry.npmjs.org/@drumnation/unsplash-smart-mcp-server/-/unsplash-smart-mcp-server-1.0.1.tgz","fileCount":97,"unpackedSize":365854,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCFRubTAV+S4InTBPL4quxOv7MJiM1y2CWijiTYfrKKhQIhAOKjeXaPFSMN3r6ivUsBGu3lspiw44tI2GvEYfDWmJwV"}]},"_npmUser":{"name":"drumnation","email":"davidmieloch@gmail.com"},"directories":{},"maintainers":[{"name":"drumnation","email":"davidmieloch@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/unsplash-smart-mcp-server_1.0.1_1744572457087_0.8892099488914698"},"_hasShrinkwrap":false}},"time":{"created":"2025-03-30T04:44:39.737Z","modified":"2025-04-13T19:27:37.437Z","1.0.0":"2025-03-30T04:44:40.031Z","1.0.1":"2025-04-13T19:27:37.273Z"},"bugs":{"url":"https://github.com/drumnation/unsplash-smart-mcp-server/issues"},"author":{"name":"drumnation"},"license":"MIT","homepage":"https://github.com/drumnation/unsplash-smart-mcp-server#readme","keywords":["unsplash","mcp","fastmcp","api","stock-photos","ai-agent","attribution","images","cursor","claude"],"repository":{"type":"git","url":"git+https://github.com/drumnation/unsplash-smart-mcp-server.git"},"description":"AI-powered FastMCP server for intelligent stock photo search, download, and attribution management from Unsplash","maintainers":[{"name":"drumnation","email":"davidmieloch@gmail.com"}],"readme":"# 🖼️ Unsplash Smart MCP Server\n\n> **Empower your AI agents with stunning visuals, zero hassle.**\n\nA powerful FastMCP server that enables AI agents to seamlessly search, recommend, and deliver professional stock photos from Unsplash with intelligent context awareness and automated attribution management.\n\n![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)\n![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.x-brightgreen)\n![TypeScript Ready](https://img.shields.io/badge/TypeScript-Ready-blue)\n[![smithery badge](https://smithery.ai/badge/@drumnation/unsplash-smart-mcp-server)](https://smithery.ai/server/@drumnation/unsplash-smart-mcp-server)\n[![npm version](https://img.shields.io/npm/v/@drumnation/unsplash-smart-mcp-server.svg)](https://www.npmjs.com/package/@drumnation/unsplash-smart-mcp-server)\n\n## 🚀 Why Choose This Unsplash Integration\n\nIn the landscape of visual content integration, our Unsplash Smart MCP Server stands out as the **definitive solution** for AI-powered image acquisition:\n\n- **🧠 AI-Agent Optimized**: Purpose-built for AI agents like Claude in Cursor, streamlining image requests with natural language\n- **🔍 Context-Aware Image Selection**: Interprets vague requests intelligently, delivering relevant images even from abstract prompts\n- **⚡ Single Tool Efficiency**: Eliminates tool spam with a unified `stock_photo` tool that handles the entire image workflow\n- **📊 Resource Optimization**: URL-first approach conserves bandwidth and storage while maintaining flexibility\n- **✅ Automatic Attribution**: Built-in compliance with Unsplash's Terms of Service with zero developer effort\n- **📁 Project-Aware Organization**: Intelligently organizes images based on your project structure (Next.js, React, Vue, etc.)\n- **🧩 Seamless Integration**: Designed for minimal setup and maximum compatibility with your existing workflow\n\n## ✨ Features Beyond Comparison\n\n### For AI Agent Developers\n\n- **Smart Contextual Search**: Find the perfect image through natural language requests\n- **Automatic Subject Selection**: AI determines optimal image subjects from your purpose description\n- **Intent-Driven Results**: Get images that match not just keywords, but the underlying intent\n- **Seamless Agent Integration**: Works out-of-the-box with Claude in Cursor and other MCP-compatible agents\n\n### For Project Efficiency\n\n- **Two-Step Workflow**: Get URLs for controlled downloads, avoiding permission issues and unnecessary storage\n- **Project-Aware File Management**: Auto-organizes images based on framework conventions\n- **Intelligent Directory Creation**: Creates appropriate folder structures based on your project type\n- **Progressive Enhancement**: Works with any project size, from quick prototypes to enterprise applications\n\n### For Compliance Peace of Mind\n\n- **Complete Attribution Management**:\n  - Local attribution database tracks all image usage\n  - Automatic embedding of photographer metadata in images (EXIF, IPTC, XMP)\n  - One-click generation of attribution pages in multiple formats\n  - Comprehensive API for attribution data\n\n## 🛠️ Installation\n\n### Prerequisites\n\n- Node.js 18.x or higher\n- An Unsplash API access key ([get one here](https://unsplash.com/developers))\n\n### Local Installation (Recommended)\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/drumnation/unsplash-smart-mcp-server.git\ncd unsplash-smart-mcp-server\n```\n\n2. Install dependencies:\n```bash\nnpm install\n```\n\n3. Configure your Cursor MCP settings:\n   - macOS: Edit `~/.cursor/mcp.json`\n   - Windows: Edit `%USERPROFILE%\\.cursor\\mcp.json`\n   - Linux: Edit `~/.cursor/mcp.json`\n\n4. Add the following configuration:\n```json\n{\n  \"servers\": {\n    \"unsplash\": {\n      \"command\": \"npx\",\n      \"args\": [\"tsx\", \"src/server.ts\"],\n      \"cwd\": \"/absolute/path/to/unsplash-smart-mcp-server\",\n      \"env\": {\n        \"UNSPLASH_ACCESS_KEY\": \"your_api_key_here\"\n      }\n    }\n  }\n}\n```\n\n5. Replace:\n   - `/absolute/path/to/unsplash-smart-mcp-server` with the actual path where you cloned the repo\n   - `your_api_key_here` with your Unsplash API key\n\n6. Save the file and restart Cursor.\n\n> **Important:** Unlike many MCP servers, this server requires direct process piping and cannot be accessed via TCP ports or through npm directly due to how it handles FastMCP's I/O interactions. The local installation method is the most reliable approach.\n\n### Cursor CLI Alternative\n\nIf you prefer using Cursor's CLI:\n\n```bash\nclaude mcp add unsplash npx tsx /path/to/unsplash-smart-mcp-server/src/server.ts --cwd /path/to/unsplash-smart-mcp-server\nclaude mcp config set unsplash UNSPLASH_ACCESS_KEY=your_api_key_here\n```\n\nReplace the paths and API key with your actual values.\n\n### Via Docker (Most Reliable Method)\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/drumnation/unsplash-smart-mcp-server.git\ncd unsplash-smart-mcp-server\n```\n\n2. Create a `docker-compose.yml` file:\n```yaml\nservices:\n  unsplash-mcp:\n    build: .\n    image: unsplash-mcp-server\n    restart: always\n    stdin_open: true\n    tty: true\n    environment:\n      - UNSPLASH_ACCESS_KEY=your_api_key_here\n```\n\n3. Build and start the container:\n```bash\ndocker-compose up -d\n```\n\n4. Configure your Cursor MCP settings:\n   - macOS: Edit `~/.cursor/mcp.json`\n   - Windows: Edit `%USERPROFILE%\\.cursor\\mcp.json`\n   - Linux: Edit `~/.cursor/mcp.json`\n\n5. Add the following configuration:\n```json\n{\n  \"servers\": {\n    \"unsplash\": {\n      \"command\": \"docker\",\n      \"args\": [\"exec\", \"-i\", \"unsplash-mcp-unsplash-mcp-1\", \"tsx\", \"src/server.ts\"],\n      \"env\": {}\n    }\n  }\n}\n```\n\n6. Save the file and restart Cursor.\n\nThis setup will:\n- Start the server automatically when Docker starts\n- Restart the server if it crashes\n- Run in the background without terminal windows\n- Provide a reliable connection to Cursor\n\n### Via Smithery (Cloud Deployment)\n\nIf you prefer cloud deployment, you can use Smithery:\n\n1. Install the server in Cursor via Smithery:\n\n```bash\nnpx @smithery/cli install @drumnation/unsplash-smart-mcp-server --client cursor --key your_api_key_here\n```\n\n2. Alternatively, you can log in to [Smithery.ai](https://smithery.ai) and deploy it through their web interface.\n\n> **Note for Windows users:** Smithery deployment includes special handling for Windows compatibility.\n\nFor detailed instructions and troubleshooting, see the [Smithery Deployment Guide](./docs/smithery-deployment.md).\n\n## 🧩 Integration with AI Agents\n\n### Step-by-Step Guide for Claude in Cursor\n\nOur Unsplash Smart MCP Server is designed to make image acquisition through AI agents effortless and intuitive:\n\n1. **Initiate a request**: Simply ask Claude for an image in natural language\n2. **AI interpretation**: Claude understands your needs and calls the `stock_photo` tool with optimized parameters\n3. **Smart image selection**: The server interprets context and finds the most relevant images\n4. **Presentation of options**: Claude presents you with the best matches and download commands\n5. **Seamless download**: Execute the suggested commands to place images exactly where you need them\n6. **Automatic attribution**: All attribution data is stored and can be accessed whenever needed\n\nThis process eliminates the traditional workflow of:\n1. ~~Searching Unsplash manually~~\n2. ~~Scrolling through hundreds of results~~\n3. ~~Downloading images to random locations~~\n4. ~~Moving files to the correct project folders~~\n5. ~~Manually tracking attribution data~~\n6. ~~Creating attribution pages~~\n\n### Example Prompts for AI Agents\n\nAsk Claude in Cursor for images using natural language prompts like these:\n\n```\n\"Find a professional image for a tech startup landing page hero section\"\n```\n\n## 🪟 Windows Compatibility\n\nIf you're using Windows and experiencing the \"Client closed\" error when running the MCP server in Cursor, follow these special configuration steps:\n\n### Windows-specific MCP Configuration\n\nCreate a file named `mcp.json` in your `.cursor` directory (typically at `%USERPROFILE%\\.cursor\\mcp.json`) with one of these configurations:\n\n#### Option 1: Direct Node Execution (Recommended)\n\n```json\n{\n  \"mcpServers\": {\n    \"stock_photo\": {\n      \"command\": \"node\",\n      \"args\": [\"./node_modules/.bin/tsx\", \"path/to/unsplash-mcp/src/server.ts\"],\n      \"disabled\": false,\n      \"env\": {\n        \"UNSPLASH_ACCESS_KEY\": \"your_api_key_here\"\n      },\n      \"shell\": false\n    }\n  }\n}\n```\n\n#### Option 2: PowerShell Approach\n\n```json\n{\n  \"mcpServers\": {\n    \"stock_photo\": {\n      \"command\": \"powershell\",\n      \"args\": [\"-Command\", \"npx tsx path/to/unsplash-mcp/src/server.ts\"],\n      \"disabled\": false,\n      \"env\": {\n        \"UNSPLASH_ACCESS_KEY\": \"your_api_key_here\"\n      }\n    }\n  }\n}\n```\n\nFor complete documentation on Windows compatibility, see [Windows Compatibility Guide](./docs/windows-compatibility.md).\n\n## 🛠️ API Reference\n\n### URL-First Approach: The Smart Choice\n\nOur architecture uses a URL-first approach rather than direct image embedding for several critical reasons:\n\n1. **Storage Efficiency**: Prevents AI agents from unnecessarily storing large binary data in their context\n2. **Bandwidth Conservation**: Reduces data transfer between services, improving response times\n3. **Placement Flexibility**: Allows developers to download images exactly where they're needed\n4. **Permission Management**: Avoids filesystem permission issues in restricted environments\n5. **Workflow Integration**: Seamlessly integrates with existing development pipelines\n\nThis strategy enables AI agents to intelligently suggest the optimal download location based on project context, without being constrained by their own environment limitations.\n\n### Minimizing Tool Spam and API Calls\n\nUnlike other solutions that require multiple tool calls for searching, filtering, downloading, and attributing images, our server:\n\n- **Unifies the entire image workflow** into a single `stock_photo` tool\n- **Optimizes result retrieval** by requesting more images upfront to enable better filtering\n- **Eliminates ping-pong interactions** between the agent and services\n- **Reduces agent token usage** by streamlining request and response formats\n\nThis design significantly reduces the number of API calls and tool invocations, leading to faster results and lower operational costs.\n\n## 🔄 Automatic Attribution and Compliance\n\n### Unsplash Terms of Service: Effortless Compliance\n\nUsing images from Unsplash requires adherence to their [Terms of Service](https://unsplash.com/license). Our server handles this automatically:\n\n1. **Attribution Data Capture**: Every image download automatically stores photographer information\n2. **Metadata Embedding**: Photographer details are embedded directly into image files\n3. **Attribution Database**: A local database maintains a record of all image usage\n4. **Attribution Generators**: Built-in tools create HTML and React attribution components\n5. **API Access**: Simple endpoints to retrieve attribution data for any project\n\nBy using our Unsplash Smart MCP Server, you are automatically compliant with Unsplash's requirements without any additional effort.\n\n### Attribution Management System\n\nThe server includes a comprehensive attribution management system:\n\n```javascript\n// Retrieve attribution data for your project\nconst attributions = await fetch('http://localhost:3000/api/unsplash', {\n  method: 'POST',\n  headers: { 'Content-Type': 'application/json' },\n  body: JSON.stringify({\n    method: 'get_attributions',\n    params: {\n      format: 'json',  // Options: json, html, react\n      projectPath: '/path/to/your/project'\n    }\n  })\n}).then(res => res.json());\n\n// attributions contains complete data about every image used\n```\n\nThe API can generate three types of attribution files:\n\n1. **JSON**: Structured data for custom implementations\n2. **HTML**: Ready-to-use HTML page for website footer or credits section\n3. **React**: Drop-in React component for modern web applications\n\n## 💼 Developer Workflow Integration\n\n### Real-World Use Cases\n\nOur Unsplash Smart MCP Server seamlessly integrates into your development workflow:\n\n#### UI Development\n- Instantly populate mockups with relevant placeholder images\n- Maintain consistent image dimensions across components\n- Organize images logically within your project structure\n\n#### Documentation\n- Enhance technical documentation with explanatory visuals\n- Create visually appealing tutorials and guides\n- Maintain proper attribution for all visual assets\n\n#### Content Creation\n- Quickly find images for blog posts and articles\n- Generate visuals for social media content\n- Access consistent imagery for product marketing\n\n#### Application Development\n- Populate e-commerce sites with product imagery\n- Create visually rich user experiences\n- Maintain separate image collections for different sections\n\n### Framework-Specific Organization\n\nImages are automatically organized based on your project type:\n\n| Framework | Default Image Path | Alternate Paths |\n|-----------|-------------------|----------------|\n| Next.js   | `/public/images/` | `/public/assets/images/` |\n| React     | `/src/assets/images/` | `/assets/images/` |\n| Vue       | `/src/assets/images/` | `/public/images/` |\n| Angular   | `/src/assets/images/` | `/assets/images/` |\n| Generic   | `/assets/images/` | `~/Downloads/stock-photos/` |\n\n## 🥇 Competitive Differentiation\n\n### Why Choose Our Unsplash Integration?\n\n| Feature | Unsplash Smart MCP Server | Alternatives |\n|---------|--------------|--------------|\n| **AI Agent Integration** | ✅ Purpose-built for AI agent workflow | ❌ Typically requires manual parameter setting |\n| **Context Awareness** | ✅ Interprets vague requests intelligently | ❌ Relies on exact keyword matching |\n| **Tool Efficiency** | ✅ Single tool handles entire workflow | ❌ Often requires multiple separate tools |\n| **Attribution Management** | ✅ Comprehensive system with multiple formats | ❌ Manual tracking or basic text output |\n| **Project Organization** | ✅ Framework-aware folder structures | ❌ Generic downloads to a single location |\n| **Installation Complexity** | ✅ Simple one-line command | ❌ Often requires multiple configuration steps |\n| **Response Format** | ✅ AI-optimized with relevant context | ❌ Generic JSON requiring further processing |\n| **Download Flexibility** | ✅ URL-first with intelligent suggestions | ❌ Either direct downloads or just URLs |\n\n## ⚙️ Configuration\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `UNSPLASH_ACCESS_KEY` | Your Unsplash API access key | - |\n| `PORT` | Port for the server to listen on | `3000` |\n| `HOST` | Host for the server | `localhost` |\n| `ATTRIBUTION_DB_PATH` | Path to store attribution database | `~/.unsplash-mcp` |\n\n### Tool Parameters\n\n#### stock_photo\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|---------|\n| `query` | string | What to search for (AI will choose if not specified) | - |\n| `purpose` | string | Where the image will be used (e.g., hero, background) | - |\n| `count` | number | Number of images to return | `1` |\n| `orientation` | string | Preferred orientation (any, landscape, portrait, square) | `any` |\n| `width` | number | Target width in pixels | - |\n| `height` | number | Target height in pixels | - |\n| `minWidth` | number | Minimum width for filtering results | - |\n| `minHeight` | number | Minimum height for filtering results | - |\n| `outputDir` | string | Directory to save photos | `~/Downloads/stock-photos` |\n| `projectType` | string | Project type for folder structure (next, react, vue, angular) | - |\n| `category` | string | Category for organizing images (e.g., heroes, backgrounds) | - |\n| `downloadMode` | string | Whether to download images or return URLs | `urls_only` |\n\n#### get_attributions\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|---------|\n| `format` | string | Output format (json, html, react) | `json` |\n| `projectPath` | string | Filter attributions to a specific project path | - |\n| `outputPath` | string | Where to save attribution files | - |\n\n## 🔧 Troubleshooting\n\n### Common Issues and Solutions\n\n| Issue | Solution |\n|-------|----------|\n| **Connection Refused** | Ensure the server is running on the configured port |\n| **Authentication Error** | Verify your Unsplash API key is correctly set |\n| **No Images Found** | Try broader search terms or check your search query |\n| **Download Permission Issues** | Use `downloadMode: 'urls_only'` and manual download commands |\n| **Docker Container Exits Prematurely** | Ensure you're using `CMD [\"npm\", \"start\"]` in your Dockerfile instead of directly running the TypeScript file with tsx. This ensures the server stays running in a Docker environment. |\n| **Timeout Errors** | The default MCP timeout is 60 seconds, which may be insufficient for downloading larger images or processing multiple images. For image-heavy operations: 1) Process fewer images per request, 2) Use smaller image dimensions, 3) Consider using `urls_only` mode instead of auto-download, 4) Check network connectivity |\n| **Attribution Not Found** | Verify the image was downloaded through the MCP server |\n| **Unhandled MCP Errors** | If you see `\"McpError: MCP error -32001: Request timed out\"` errors, your request is likely taking too long. Break it into smaller operations or use the URLs-only approach |\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n### Development Workflow\n\n1. Clone the repository\n2. Install dependencies with `npm install`\n3. Create a `.env` file with your Unsplash API key\n4. Run in development mode with `npm run dev`\n5. Run tests with `npm test`\n\n## 🗺️ Roadmap\n\nHere's what we're planning for future releases:\n\n- **Image Editing Capabilities**: Basic resizing, cropping, and adjustment tools\n- **Advanced Search Filters**: More granular control over image selection\n- **Batch Processing**: Handle multiple image requests efficiently\n- **Custom Collections**: Save and manage groups of images for projects\n- **Team Collaboration**: Share attribution and image collections\n- **Usage Analytics**: Track image usage across projects\n- **Additional Image Sources**: Integration with other stock photo providers\n- **Improved Timeout Handling**: Enhanced timeout configuration and recovery mechanisms\n\n## 📄 License\n\nMIT License\n\n## 📚 Attribution Requirements\n\nWhen using images from Unsplash, you must comply with the [Unsplash License](https://unsplash.com/license):\n\n- Attribution is not required but appreciated\n- You cannot sell unaltered copies of the photos\n- You cannot compile photos from Unsplash to create a competing service\n\nOur server's attribution system makes it easy to provide proper credit to photographers.\n\n## 📞 Contact\n\nFor issues or questions, please [open an issue](https://github.com/drumnation/unsplash-smart-mcp-server/issues) on GitHub.\n\n## 🧰 Development and Testing\n\n### Running the Server Locally\n\n```bash\n# Clone the repository\ngit clone https://github.com/drumnation/unsplash-smart-mcp-server.git\ncd unsplash-smart-mcp-server\n\n# Install dependencies\nnpm install\n\n# Set up your environment variables\ncp .env.example .env\n# Edit .env to add your UNSPLASH_ACCESS_KEY\n\n# Start the development server\nnpm run dev\n```\n\n### Testing\n\nThe package includes a comprehensive test suite:\n\n```bash\n# Run core tests\nnpm test\n\n# Run all tests and get a summary report\nnpm run test:all\n```\n\nThe test suite includes:\n- Unit and integration tests\n- Manual tool testing\n- Docker container tests\n- Smithery.ai integration tests\n\nFor detailed information about testing, see [docs/testing.md](docs/testing.md).\n\n---\n\n<p align=\"center\">\n  <strong>Empower your AI agents with the perfect images, every time.</strong><br>\n  Built with ❤️ for developers and AI enthusiasts.\n</p>\n","readmeFilename":"README.md"}