{"_id":"@ahmaddioxide/mcp-image-resolver","_rev":"2-2f55e5ba688f413594cfb749f1230fa9","name":"@ahmaddioxide/mcp-image-resolver","dist-tags":{"latest":"0.3.0"},"versions":{"0.2.0":{"name":"@ahmaddioxide/mcp-image-resolver","version":"0.2.0","license":"MIT","_id":"@ahmaddioxide/mcp-image-resolver@0.2.0","maintainers":[{"name":"ahmaddioxide","email":"ahmadmahmood296@gmail.com"}],"homepage":"https://github.com/ahmaddioxide/image-resolver-mcp#readme","bugs":{"url":"https://github.com/ahmaddioxide/image-resolver-mcp/issues"},"bin":{"mcp-image-resolver":"build/index.js"},"dist":{"shasum":"16869975e869e531a5b2d43baba9714c3b52ad40","tarball":"https://registry.npmjs.org/@ahmaddioxide/mcp-image-resolver/-/mcp-image-resolver-0.2.0.tgz","fileCount":43,"integrity":"sha512-b24BZsBfSvHEBG72V4P9Km2NvbP3bL6AcAh4800RnKNnDCsyP3PBL3dBlSq613/gKX6vIbZy8Ed2u7iXZ0ZPzA==","signatures":[{"sig":"MEQCIF4SFL2LithLGZ3U75Ew4fhgbk695BsxuR09IiKU8pNXAiBU990sdRdoaVDUmPuTjd/OlIikblXRdLpea1JnGZ8WQw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":50701},"type":"module","engines":{"node":">=18.0.0"},"gitHead":"c5293dcb423711d57084f8f217de92e60323f104","mcpName":"io.github.ahmaddioxide/image-resolver","scripts":{"dev":"npx tsx src/index.ts","build":"tsc && chmod +x build/index.js 2>/dev/null || true","start":"node build/index.js"},"_npmUser":{"name":"ahmaddioxide","email":"ahmadmahmood296@gmail.com"},"repository":{"url":"git+https://github.com/ahmaddioxide/image-resolver-mcp.git","type":"git"},"_npmVersion":"11.6.2","description":"MCP server for context-aware royalty-free image search from Pexels and Unsplash","directories":{},"_nodeVersion":"24.12.0","dependencies":{"zod":"^3.23.0","compromise":"^14.15.0","@modelcontextprotocol/sdk":"^1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","typescript":"^5.0.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-image-resolver_0.2.0_1772696298635_0.18162881956361088","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@ahmaddioxide/mcp-image-resolver","version":"0.3.0","description":"MCP server for context-aware royalty-free image search from Pexels and Unsplash","mcpName":"io.github.ahmaddioxide/image-resolver","type":"module","license":"MIT","repository":{"type":"git","url":"git+https://github.com/ahmaddioxide/image-resolver-mcp.git"},"homepage":"https://github.com/ahmaddioxide/image-resolver-mcp#readme","bugs":{"url":"https://github.com/ahmaddioxide/image-resolver-mcp/issues"},"bin":{"mcp-image-resolver":"build/index.js"},"scripts":{"build":"tsc && chmod +x build/index.js 2>/dev/null || true","start":"node build/index.js","dev":"npx tsx src/index.ts"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.0","compromise":"^14.15.0","zod":"^3.23.0"},"devDependencies":{"@types/node":"^20.0.0","tsx":"^4.0.0","typescript":"^5.0.0"},"engines":{"node":">=18.0.0"},"gitHead":"84d03e6f800c9c95d32a7962ac24768aa9dee1ed","_id":"@ahmaddioxide/mcp-image-resolver@0.3.0","_nodeVersion":"24.12.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-zFHNvneFYJDgSemQ88E7+AUfj8n/b0qhQLkKVnpRs3VdcBi0Zy6zJmkznKhg8tqp2Q+Kj6Q4v8Ohp9VXQOQvQg==","shasum":"5ae67bc097bc84180d4b73a036fec37ff4b66e55","tarball":"https://registry.npmjs.org/@ahmaddioxide/mcp-image-resolver/-/mcp-image-resolver-0.3.0.tgz","fileCount":43,"unpackedSize":51345,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDLSvdWC3b8Km/w+kGvIt3f4H7oGksbn+8ABzU8h3AIcAIgPjwE26wgjFNI2tDyjTwghYLR/yciN6WnHDXIldeqrLA="}]},"_npmUser":{"name":"ahmaddioxide","email":"ahmadmahmood296@gmail.com"},"directories":{},"maintainers":[{"name":"ahmaddioxide","email":"ahmadmahmood296@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-image-resolver_0.3.0_1772703859392_0.25512425372682657"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-05T07:38:18.560Z","modified":"2026-03-05T09:44:19.685Z","0.2.0":"2026-03-05T07:38:18.777Z","0.3.0":"2026-03-05T09:44:19.565Z"},"bugs":{"url":"https://github.com/ahmaddioxide/image-resolver-mcp/issues"},"license":"MIT","homepage":"https://github.com/ahmaddioxide/image-resolver-mcp#readme","repository":{"type":"git","url":"git+https://github.com/ahmaddioxide/image-resolver-mcp.git"},"description":"MCP server for context-aware royalty-free image search from Pexels and Unsplash","maintainers":[{"name":"ahmaddioxide","email":"ahmadmahmood296@gmail.com"}],"readme":"# MCP Image Resolver Server\n\nAn MCP (Model Context Protocol) server that provides royalty-free image search for AI hosts like Cursor, Claude Desktop, VS Code, Windsurf, and more. Ask your AI assistant to find images by natural language—it uses the `search_images` tool and returns structured results from Pexels and Unsplash.\n\n## Features\n\n- **search_images** — Search for royalty-free images (supports limit, page, orientation)\n- **extract_image_query** — Transform free-form text into an image search query\n- **get_best_image** — Return a single best image for a query\n- **search_images_batch** — Run multiple searches in parallel\n- **resolve_image_attribution** — Generate provider-compliant attribution text\n- **Pexels & Unsplash** — Multi-provider support (free tier for both)\n- **Unified response** — Structured results with url, source, dimensions, photographer, tags\n- **Works everywhere** — Any MCP client that supports stdio servers\n\n## Requirements\n\n- Node.js 18+\n- At least one API key: Pexels ([pexels.com/api](https://www.pexels.com/api/)) and/or Unsplash ([unsplash.com/oauth/applications](https://unsplash.com/oauth/applications))\n\n## Quick Start (No Installation Required)\n\nNo cloning or building needed. Just add this config to your MCP client and it runs via `npx` automatically:\n\n```json\n{\n  \"mcpServers\": {\n    \"image-resolver\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@ahmaddioxide/mcp-image-resolver\"],\n      \"env\": {\n        \"PEXELS_API_KEY\": \"your-pexels-api-key\",\n        \"UNSPLASH_ACCESS_KEY\": \"your-unsplash-access-key\"\n      }\n    }\n  }\n}\n```\n\nAt least one API key is required. Both are free — get them here:\n- Pexels: [pexels.com/api](https://www.pexels.com/api/)\n- Unsplash: [unsplash.com/oauth/applications](https://unsplash.com/oauth/applications)\n\n## Architecture (High-Level)\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│                           MCP Client (Cursor, Claude, VS Code, etc.)        │\n│                                     │                                       │\n│                            stdio (stdin/stdout)                             │\n└─────────────────────────────────────┼───────────────────────────────────────┘\n                                      │\n                                      ▼\n┌─────────────────────────────────────────────────────────────────────────────┐\n│                         MCP Image Resolver Server                           │\n│  ┌─────────────────────────────────────────────────────────────────────┐   │\n│  │  index.ts          MCP server entry, registers tools, stdio transport│   │\n│  └─────────────────────────────────────────────────────────────────────┘   │\n│                                      │                                      │\n│                                      ▼                                      │\n│  ┌─────────────────────────────────────────────────────────────────────┐   │\n│  │  tools/search-images.ts   Tool handler: search_images(query)         │   │\n│  └─────────────────────────────────────────────────────────────────────┘   │\n│                                      │                                      │\n│                                      ▼                                      │\n│  ┌──────────────────────┐  ┌──────────────────────┐                        │\n│  │  providers/pexels.ts  │  │ providers/unsplash.ts │                        │\n│  │  Pexels API adapter   │  │ Unsplash API adapter  │──▶ ImageResult schema  │\n│  └──────────────────────┘  └──────────────────────┘                        │\n│               │                        │                                    │\n│               └────────────────────────┴────▶ utils/normalize.ts            │\n└─────────────────────────────────────┼───────────────────────────────────────┘\n                                      │\n                    ┌─────────────────┴─────────────────┐\n                    ▼                                   ▼\n┌──────────────────────────────┐    ┌──────────────────────────────────────────┐\n│  Pexels API                  │    │  Unsplash API                             │\n│  api.pexels.com              │    │  api.unsplash.com                         │\n└──────────────────────────────┘    └──────────────────────────────────────────┘\n```\n\n**Flow:** MCP client → stdio → `index.ts` (registers tools) → `search-images.ts` → Pexels and Unsplash providers (when keys are set). Results are merged (Pexels first, then Unsplash) and normalized to the unified `ImageResult` schema.\n\n## Client Setup\n\n### Cursor\n\nAdd to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):\n\n```json\n{\n  \"mcpServers\": {\n    \"image-resolver\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@ahmaddioxide/mcp-image-resolver\"],\n      \"env\": {\n        \"PEXELS_API_KEY\": \"your-pexels-api-key\",\n        \"UNSPLASH_ACCESS_KEY\": \"your-unsplash-access-key\"\n      }\n    }\n  }\n}\n```\n\nRestart Cursor after config changes.\n\n### Claude Desktop\n\nAdd to your Claude config file:\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- **Linux**: `~/.config/Claude/claude_desktop_config.json`\n\nVia Settings: **Developer → Edit Config**\n\n```json\n{\n  \"mcpServers\": {\n    \"image-resolver\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@ahmaddioxide/mcp-image-resolver\"],\n      \"env\": {\n        \"PEXELS_API_KEY\": \"your-pexels-api-key\",\n        \"UNSPLASH_ACCESS_KEY\": \"your-unsplash-access-key\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop completely after saving.\n\n### VS Code\n\nAdd to `.vscode/mcp.json` (workspace) or your user profile `mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"image-resolver\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@ahmaddioxide/mcp-image-resolver\"],\n      \"env\": {\n        \"PEXELS_API_KEY\": \"your-pexels-api-key\",\n        \"UNSPLASH_ACCESS_KEY\": \"your-unsplash-access-key\"\n      }\n    }\n  }\n}\n```\n\n> **Note:** VS Code uses `servers` (not `mcpServers`) and requires `\"type\": \"stdio\"`.\n\n### Windsurf\n\nAdd to `~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"image-resolver\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@ahmaddioxide/mcp-image-resolver\"],\n      \"env\": {\n        \"PEXELS_API_KEY\": \"your-pexels-api-key\",\n        \"UNSPLASH_ACCESS_KEY\": \"your-unsplash-access-key\"\n      }\n    }\n  }\n}\n```\n\nRefresh the MCP config after changes.\n\n### Other MCP Clients\n\nAny client that supports stdio MCP servers (Amp, Continue.dev, Amazon Q, etc.) can use this server:\n\n- **Command**: `npx`\n- **Args**: `[\"-y\", \"@ahmaddioxide/mcp-image-resolver\"]`\n- **Env**: `{ \"PEXELS_API_KEY\": \"your-key\", \"UNSPLASH_ACCESS_KEY\": \"your-key\" }` (at least one required)\n\n## Usage\n\nOnce configured, ask your AI assistant to find images in natural language. It will call the `search_images` tool automatically.\n\n**Example prompts:**\n\n- \"Find royalty-free images of a sunset mosque\"\n- \"Search for zen yoga images suitable for a wellness app\"\n- \"Get some minimalist office workspace photos\"\n- \"Find images for a cooking blog header\"\n\nThe tool returns image URLs and metadata. Use the links to view or download images.\n\n## Tool Schema\n\n| Tool                          | Params                                   | Description                              |\n|-------------------------------|------------------------------------------|------------------------------------------|\n| **search_images**             | query, limit?, page?, orientation?       | Search images from Pexels and Unsplash   |\n| **extract_image_query**       | context                                  | Extract search terms from free-form text |\n| **get_best_image**            | query, orientation?                      | Return a single best image               |\n| **search_images_batch**       | queries, limit?                          | Run multiple searches in parallel        |\n| **resolve_image_attribution** | photographer, source, url?               | Generate attribution text                |\n\n**Response:** JSON with `results` array of `{ url, source, width, height, photographer, tags }`. Each result includes `source` (`\"Pexels\"` or `\"Unsplash\"`) for attribution.\n\n**Note:** When both providers are configured, results are merged with Pexels first, then Unsplash. Use `limit: 20` or higher to see results from both providers in a single search.\n\n## Testing\n\nExample prompts to verify the tools:\n\n- *\"Search for mountain landscape with limit 20 and show me which results came from Pexels vs Unsplash.\"*\n- *\"Use extract_image_query on: I need a hero image for a meditation app with mountains.\"*\n- *\"Use search_images_batch for 'sunset mosque', 'pakistani flag', and 'zen yoga'.\"*\n- *\"Get a single best image for coffee shop and generate attribution for it.\"*\n\n## Development\n\nTo contribute or run locally, clone the repo and build from source:\n\n```bash\ngit clone https://github.com/ahmaddioxide/image-resolver-mcp.git\ncd image-resolver-mcp\nnpm install\ncp .env.example .env\n# Add PEXELS_API_KEY and/or UNSPLASH_ACCESS_KEY to .env\nnpm run build\n```\n\nOr run in development mode without building, using `tsx`:\n\n```json\n{\n  \"mcpServers\": {\n    \"image-resolver\": {\n      \"command\": \"npx\",\n      \"args\": [\"tsx\", \"/path/to/image-resolver-mcp/src/index.ts\"],\n      \"env\": {\n        \"PEXELS_API_KEY\": \"your-pexels-api-key\",\n        \"UNSPLASH_ACCESS_KEY\": \"your-unsplash-access-key\"\n      }\n    }\n  }\n}\n```\n\n## Attribution\n\nImages are sourced from [Pexels](https://www.pexels.com/) and [Unsplash](https://unsplash.com/). Per their API terms:\n\n- Provide prominent links to Pexels and Unsplash\n- Credit photographers: \"Photo by [Name] on Pexels\" / \"Photo by [Name] on Unsplash\"\n- Response metadata includes `photographer` and `source`; use `resolve_image_attribution` for compliant text\n\n## Contributing\n\nContributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community standards. See [SECURITY.md](SECURITY.md) for vulnerability reporting.\n\n## License\n\nMIT — see [LICENSE](LICENSE).","readmeFilename":"README.md"}