Pexels Media Access Gateway (MCP Server)

This implementation functions as a Model Context Protocol (MCP) gateway, exposing the functionality of the Pexels media repository to consuming AI agents. It translates abstract media requests into concrete API calls against the Pexels infrastructure.

Core Capabilities

• Execute parameterized retrieval operations for visual media (photos, videos) based on textual descriptors, orientation, spectral characteristics, and dimensional requirements.
• Access curated sets and trending assets maintained by Pexels.
• Traverse Pexels' catalog structure via collection identifiers.
• Obtain granular metadata pertaining to any specific visual item.
• Access content addresses directly through specialized URI schemes.

Prerequisites

• Execution environment requires Node.js version 18 or newer.
• A valid authentication credential (API Key) obtained from the official Pexels developer portal (https://www.pexels.com/api/) is mandatory.

Local Setup and Operation

1. Clone the source code repository.
2. Resolve project dependencies: bash pnpm install
3. Compile the necessary artifacts: bash pnpm build
4. Initiate the service in development mode (ensure the environment variable is set): bash PEXELS_API_KEY=your_secret_key pnpm dev

Smithery Deployment Instructions

This service is structured for deployment onto the Smithery orchestration layer. The deployment process involves:

1. Registering this server instance within your Smithery workspace or claiming an existing endpoint.
2. Navigating to the administrative 'Deployments' section (requires owner privileges).
3. Executing the deployment procedure.
4. Crucially, supplying the requisite Pexels API Key within the server's runtime configuration parameters during setup.

Available Agent Tools

The gateway exposes the following programmatic interfaces for media interaction:

Photographic Asset Tools

• searchPhotos: Executes a query against the photo catalog. Guidance: Employ highly descriptive, contextual keywords (e.g., 'Nordic minimalist kitchen interior', 'vintage film grain portrait') rather than vague terms ('kitchen', 'portrait'). Refinement is possible using optional parameters such as orientation, size, color, and locale (e.g., 'de-DE'). Supports pagination controls. Output includes essential metadata (identifiers, URLs) and real-time API consumption metrics.
• downloadPhoto: Retrieves a direct endpoint for a specified image ID at a requested resolution (defaults to 'original'). Supported resolutions include 'original', 'large2x', 'large', 'medium', 'small', 'portrait', 'landscape', 'tiny'. Returns a URL suitable for immediate transfer, a suggested file name (including resolution context), and required attribution text. The consuming client must utilize external transfer mechanisms (e.g., cURL, wget) to finalize the download.
• getCuratedPhotos: Fetches a predefined, algorithmically selected set of high-quality photographs, supporting page navigation.
• getPhoto: Fetches the complete descriptive metadata record for an image identified by its unique ID.

Videographic Asset Tools

• searchVideos: Queries the video library using descriptive search terms (e.g., 'aerial perspective rainforest canopy', 'low light city time-lapse'). Parameters for orientation, size, locale, page, and result counts are available for constraint application. Returns metadata objects and current rate status.
• getPopularVideos: Retrieves a list of currently trending video assets, filterable by aspect ratio, clip duration, and pagination.
• getVideo: Fetches comprehensive metadata for a single video resource via its unique identifier.
• downloadVideo: Provides a direct acquisition link for a video asset, specifying quality preference ('hd' or 'sd'). The response contains the URL, a recommended filename, and necessary credit information. Client interaction via standard transfer tools is expected.

Collection Management Tools

• getFeaturedCollections: Lists collections that Pexels highlights, supporting pagination.
• ~~getMyCollections~~: (Functionality suppressed) This operation requires delegated user authorization (OAuth 2.0), which this server implementation does not currently support.
• getCollectionMedia: Retrieves the constituent assets (photos or videos) belonging to a specified collection ID, with options to filter by asset type, ordering, and page parameters.

Content Address Schemes (URIs)

The following uniform resource identifiers allow direct content resolution:

• pexels-photo://{id}: Targets a singular photographic asset.
• pexels-video://{id}: Targets a singular videographic asset.
• pexels-collection://{id}: Targets a curated grouping of assets.

Operational Feedback and Constraints

Informative error diagnostics are returned for common faults (e.g., invalid credentials, rate exhaustion, resource non-existence). All successful responses embed critical Pexels API usage metrics (request allowance remaining, time until reset).

Adherence to Pexels Attribution Policy

Strict adherence to Pexels' required acknowledgments is mandatory for all displayed content:

• Display a clear, visible reference back to the source platform (e.g., "Visuals sourced from Pexels").
• Provide specific credit to the original creator (e.g., "Image captured by Jane Smith via Pexels").

Licensing

ISC

WIKIPEDIA: XMLHttpRequest (XHR) is an API in the form of a JavaScript object whose methods transmit HTTP requests from a web browser to a web server. The methods allow a browser-based application to send requests to the server after page loading is complete, and receive information back. XMLHttpRequest is a component of Ajax programming. Prior to Ajax, hyperlinks and form submissions were the primary mechanisms for interacting with the server, often replacing the current page with another one.

== History == The concept behind XMLHttpRequest was conceived in 2000 by the developers of Microsoft Outlook. The concept was then implemented within the Internet Explorer 5 browser (1999). However, the original syntax did not use the XMLHttpRequest identifier. Instead, the developers used the identifiers ActiveXObject("Msxml2.XMLHTTP") and ActiveXObject("Microsoft.XMLHTTP"). As of Internet Explorer 7 (2006), all browsers support the XMLHttpRequest identifier. The XMLHttpRequest identifier is now the de facto standard in all the major browsers, including Mozilla's Gecko layout engine (2002), Safari 1.2 (2004) and Opera 8.0 (2005).

=== Standards === The World Wide Web Consortium (W3C) published a Working Draft specification for the XMLHttpRequest object on April 5, 2006. On February 25, 2008, the W3C published the Working Draft Level 2 specification. Level 2 added methods to monitor event progress, allow cross-site requests, and handle byte streams. At the end of 2011, the Level 2 specification was absorbed into the original specification. At the end of 2012, the WHATWG took over development and maintains a living document using Web IDL.

== Usage == Generally, sending a request with XMLHttpRequest has several programming steps.

Create an XMLHttpRequest object by calling a constructor: Call the "open" method to specify the request type, identify the relevant resource, and select synchronous or asynchronous operation: For an asynchronous request, set a listener that will be notified when the request's state changes: Initiate the request by calling the "send" method: Respond to state changes in the event listener. If the server sends response data, by default it is captured in the "responseText" property. When the object stops processing the response, it changes to state 4, the "done" state. Aside from these general steps, XMLHttpRequest has many options to control how the request is sent and how the response is processed. Custom header fields can be added to the request to indicate how the server should fulfill it, and data can be uploaded to the server by providing it in the "send" call. The response can be parsed from the JSON format into a readily usable JavaScript object, or processed gradually as it arrives rather than waiting for the entire text. The request can be aborted prematurely or set to fail if not completed in a specified amount of time.

== Cross-domain requests ==

In the early development of the World Wide Web, it was found possible to brea