Related Pages

Related topics: Entrypoints and Runtime Surface, Architecture Evidence Map, Operations and Verification Boundaries

Repository Overview

This page is generated from repository evidence because the Human Wiki provider was unavailable. It intentionally limits itself to README and file-tree facts.

README Evidence

MCP Image Resolver Server

An 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.

Features

• search_images — Search for royalty-free images (supports limit, page, orientation)
• extract_image_query — Transform free-form text into an image search query
• get_best_image — Return a single best image for a query
• search_images_batch — Run multiple searches in parallel
• resolve_image_attribution — Generate provider-compliant attribution text
• Pexels & Unsplash — Multi-provider support (free tier for both)
• Unified response — Structured results with url, source, dimensions, photographer, tags
• Works everywhere — Any MCP client that supports stdio servers

Requirements

• Node.js 18+
• At least one API key: Pexels (pexels.com/api) and/or Unsplash (unsplash.com/oauth/applications)

Quick Start (No Installation Required)

No cloning or building needed. Just add this config to your MCP client and it runs via npx automatically:

{
  "mcpServers": {
    "image-resolver": {
      "command": "npx",
      "args": ["-y", "@ahmaddioxide/mcp-image-resolver"],
      "env": {
        "PEXELS_API_KEY": "your-pexels-api-key",
        "UNSPLASH_ACCESS_KEY": "your-unsplash-access-key"
      }
    }
  }
}

At least one API key is required. Both are free — get them here:

• Pexels: pexels.com/api
• Unsplash: unsplash.com/oauth/applications

Architecture (High-Level)

┌─────────────────────────────────────────────────────────────────────────────┐
│                           MCP Client (Cursor, Claude, VS Code, etc.)        │
│                                     │                                       │
│                            stdio (stdin/stdout)                             │
└─────────────────────────────────────┼───────────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│

[excerpt truncated]

## Selected Source Inventory

- `README.md`
- `package.json`
- `src/index.ts`
- `src/providers/pexels.ts`
- `src/providers/types.ts`
- `src/providers/unsplash.ts`
- `src/tools/extract-image-query.ts`
- `src/tools/get-best-image.ts`
- `src/tools/resolve-image-attribution.ts`
- `src/tools/search-images-batch.ts`
- `src/tools/search-images.ts`
- `src/utils/normalize.ts`

| File | Evidence role | Size |
|---|---|---|
| `README.md` | README/product and usage evidence | 12124 bytes |
| `package.json` | package/runtime metadata | 1054 bytes |
| `src/index.ts` | implementation surface | 4377 bytes |
| `src/providers/pexels.ts` | implementation surface | 1650 bytes |
| `src/providers/types.ts` | implementation surface | 971 bytes |
| `src/providers/unsplash.ts` | implementation surface | 2053 bytes |
| `src/tools/extract-image-query.ts` | implementation surface | 535 bytes |
| `src/tools/get-best-image.ts` | implementation surface | 801 bytes |
| `src/tools/resolve-image-attribution.ts` | implementation surface | 768 bytes |
| `src/tools/search-images-batch.ts` | implementation surface | 1103 bytes |
| `src/tools/search-images.ts` | implementation surface | 2138 bytes |
| `src/utils/normalize.ts` | implementation surface | 1930 bytes |

Source: `[README.md:1-120]()`

Related Pages

Related topics: Repository Overview, Architecture Evidence Map, Operations and Verification Boundaries

Entrypoints and Runtime Surface

The files below are the highest-signal candidates for how the project is installed, started, configured, or embedded. Treat this as an evidence map, not an inferred API contract.

Source: README.md:1-120

Related Pages

Related topics: Repository Overview, Entrypoints and Runtime Surface, Operations and Verification Boundaries

Architecture Evidence Map

This section maps source paths into likely architectural areas based on repository layout only. Claims that require execution are intentionally not made here.

• .: README.md, package.json
• src: src/index.ts, src/providers/pexels.ts, src/providers/types.ts, src/providers/unsplash.ts, src/tools/extract-image-query.ts, src/tools/get-best-image.ts

Source: package.json:1-120

Related Pages

Related topics: Repository Overview, Entrypoints and Runtime Surface, Architecture Evidence Map

Operations and Verification Boundaries

Operational guidance is limited to files that are present in the repository. Before using this project in an agent workflow, verify install, quickstart, and runtime behavior in a sandbox.

• Documentation signal: README.md
• Runtime/package signal: package.json
• Source inspection signal: src/index.ts
• Source inspection signal: src/providers/pexels.ts
• Source inspection signal: src/providers/types.ts
• Source inspection signal: src/providers/unsplash.ts
• Source inspection signal: src/tools/extract-image-query.ts
• Source inspection signal: src/tools/get-best-image.ts
• Source inspection signal: src/tools/resolve-image-attribution.ts
• Source inspection signal: src/tools/search-images-batch.ts

Source: src/index.ts:1-120

Doramagic Pitfall Log

Doramagic extracted 7 source-linked risk signals. Review them before installing or handing real data to the project.

1. Project risk: Project risk needs validation

• Severity: medium
• Finding: Project risk is backed by a source signal: Project risk needs validation. Treat it as a review item until the current version is checked.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: identity.distribution | mcp_registry:io.github.ahmaddioxide/image-resolver:0.2.0 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.ahmaddioxide%2Fimage-resolver/versions/0.2.0 | repo=image-resolver-mcp; install=@ahmaddioxide/mcp-image-resolver

2. Capability assumption: README/documentation is current enough for a first validation pass.

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: capability.assumptions | mcp_registry:io.github.ahmaddioxide/image-resolver:0.2.0 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.ahmaddioxide%2Fimage-resolver/versions/0.2.0 | README/documentation is current enough for a first validation pass.

3. Maintenance risk: Maintainer activity is unknown

• Severity: medium
• Finding: Maintenance risk is backed by a source signal: Maintainer activity is unknown. Treat it as a review item until the current version is checked.
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | mcp_registry:io.github.ahmaddioxide/image-resolver:0.2.0 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.ahmaddioxide%2Fimage-resolver/versions/0.2.0 | last_activity_observed missing

4. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: downstream_validation.risk_items | mcp_registry:io.github.ahmaddioxide/image-resolver:0.2.0 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.ahmaddioxide%2Fimage-resolver/versions/0.2.0 | no_demo; severity=medium

5. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: risks.scoring_risks | mcp_registry:io.github.ahmaddioxide/image-resolver:0.2.0 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.ahmaddioxide%2Fimage-resolver/versions/0.2.0 | no_demo; severity=medium

6. Maintenance risk: issue_or_pr_quality=unknown

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | mcp_registry:io.github.ahmaddioxide/image-resolver:0.2.0 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.ahmaddioxide%2Fimage-resolver/versions/0.2.0 | issue_or_pr_quality=unknown

7. Maintenance risk: release_recency=unknown

• Severity: low
• Finding: release_recency=unknown。
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | mcp_registry:io.github.ahmaddioxide/image-resolver:0.2.0 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.ahmaddioxide%2Fimage-resolver/versions/0.2.0 | release_recency=unknown

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using image-resolver-mcp with real data or production workflows.

• Project risk needs validation - GitHub / issue