@rahmandayub/pexels-mcp 0.0.0-stage → 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +192 -2
- package/dist/cache.js +77 -0
- package/dist/cache.js.map +1 -0
- package/dist/config.js +127 -0
- package/dist/config.js.map +1 -0
- package/dist/errors.js +57 -0
- package/dist/errors.js.map +1 -0
- package/dist/index.js +77 -0
- package/dist/index.js.map +1 -0
- package/dist/log.js +54 -0
- package/dist/log.js.map +1 -0
- package/dist/pexels/client.js +193 -0
- package/dist/pexels/client.js.map +1 -0
- package/dist/pexels/quirks.js +283 -0
- package/dist/pexels/quirks.js.map +1 -0
- package/dist/pexels/schemas.js +134 -0
- package/dist/pexels/schemas.js.map +1 -0
- package/dist/present/collection.js +23 -0
- package/dist/present/collection.js.map +1 -0
- package/dist/present/envelope.js +20 -0
- package/dist/present/envelope.js.map +1 -0
- package/dist/present/photo.js +86 -0
- package/dist/present/photo.js.map +1 -0
- package/dist/present/util.js +24 -0
- package/dist/present/util.js.map +1 -0
- package/dist/present/video.js +117 -0
- package/dist/present/video.js.map +1 -0
- package/dist/tools/collection-media.js +54 -0
- package/dist/tools/collection-media.js.map +1 -0
- package/dist/tools/curated-photos.js +42 -0
- package/dist/tools/curated-photos.js.map +1 -0
- package/dist/tools/featured-collections.js +42 -0
- package/dist/tools/featured-collections.js.map +1 -0
- package/dist/tools/get-photo.js +46 -0
- package/dist/tools/get-photo.js.map +1 -0
- package/dist/tools/get-video.js +46 -0
- package/dist/tools/get-video.js.map +1 -0
- package/dist/tools/helpers.js +38 -0
- package/dist/tools/helpers.js.map +1 -0
- package/dist/tools/index.js +21 -0
- package/dist/tools/index.js.map +1 -0
- package/dist/tools/photo-url.js +84 -0
- package/dist/tools/photo-url.js.map +1 -0
- package/dist/tools/popular-videos.js +62 -0
- package/dist/tools/popular-videos.js.map +1 -0
- package/dist/tools/preview.js +21 -0
- package/dist/tools/preview.js.map +1 -0
- package/dist/tools/search-photos.js +67 -0
- package/dist/tools/search-photos.js.map +1 -0
- package/dist/tools/search-videos.js +60 -0
- package/dist/tools/search-videos.js.map +1 -0
- package/dist/types.js +118 -0
- package/dist/types.js.map +1 -0
- package/dist/version.js +6 -0
- package/dist/version.js.map +1 -0
- package/package.json +52 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Rahmandayub
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,193 @@
|
|
|
1
|
-
#
|
|
1
|
+
# pexels-mcp
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
MCP server for the [Pexels](https://www.pexels.com/api/) photo & video API, built for coding agents.
|
|
4
|
+
|
|
5
|
+
It does not just wrap the API: it turns Pexels' sharp edges into a stable contract — compact
|
|
6
|
+
results by default, honest page-number pagination, and errors an agent can act on.
|
|
7
|
+
|
|
8
|
+
```
|
|
9
|
+
search → pick by aspect ratio / dimensions → use preview_url or download_url
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
## Install
|
|
13
|
+
|
|
14
|
+
Node 22 or newer.
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
# from npm
|
|
18
|
+
npx -y @rahmandayub/pexels-mcp
|
|
19
|
+
|
|
20
|
+
# from this repo
|
|
21
|
+
npm install && npm run build && node dist/index.js
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
The server speaks MCP over stdio. stdout carries JSON-RPC only; all logs go to stderr.
|
|
25
|
+
|
|
26
|
+
## Configure
|
|
27
|
+
|
|
28
|
+
The API key comes from env or a config file (env wins):
|
|
29
|
+
|
|
30
|
+
| Source | Value |
|
|
31
|
+
|---|---|
|
|
32
|
+
| `PEXELS_API_KEY` | the key itself |
|
|
33
|
+
| `${XDG_CONFIG_HOME:-~/.config}/pexels-mcp/config.json` | `{"apiKey": "…"}` |
|
|
34
|
+
|
|
35
|
+
On macOS/Linux:
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
mkdir -p ~/.config/pexels-mcp
|
|
39
|
+
printf '{"apiKey": "%s"}\n' "$YOUR_KEY" > ~/.config/pexels-mcp/config.json
|
|
40
|
+
chmod 600 ~/.config/pexels-mcp/config.json
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Optional overrides: `PEXELS_MCP_TIMEOUT_MS` (1000–60000), `PEXELS_MCP_MAX_RETRIES` (0–5),
|
|
44
|
+
`PEXELS_MCP_CACHE_TTL_S` (0–3600, `0` disables the cache), `PEXELS_MCP_LOG_LEVEL`
|
|
45
|
+
(`debug`/`info`/`warn`/`error`), `PEXELS_MCP_LOCALE`.
|
|
46
|
+
|
|
47
|
+
The key is never written to tool output, and is redacted to its first four characters in logs.
|
|
48
|
+
|
|
49
|
+
## Register in a client
|
|
50
|
+
|
|
51
|
+
OpenCode (`opencode.json`):
|
|
52
|
+
|
|
53
|
+
```json
|
|
54
|
+
{
|
|
55
|
+
"mcp": {
|
|
56
|
+
"pexels": {
|
|
57
|
+
"type": "local",
|
|
58
|
+
"command": ["npx", "-y", "@rahmandayub/pexels-mcp"],
|
|
59
|
+
"environment": { "PEXELS_API_KEY": "your_key" }
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
From a local checkout, use `"command": ["node", "/absolute/path/to/pexels-mcp/dist/index.js"]`.
|
|
66
|
+
|
|
67
|
+
## Tools
|
|
68
|
+
|
|
69
|
+
All tools are read-only and return a short text summary plus `structuredContent` validated
|
|
70
|
+
against an advertised `outputSchema`.
|
|
71
|
+
|
|
72
|
+
| Tool | Purpose |
|
|
73
|
+
|---|---|
|
|
74
|
+
| `search_photos` | Search photos: `query`, `orientation`, `size`, `color`, `locale`, `page`, `per_page`, `detail` |
|
|
75
|
+
| `curated_photos` | Pexels editor picks |
|
|
76
|
+
| `get_photo` | One photo by id; `preview: true` attaches the image inline |
|
|
77
|
+
| `photo_url` | Derived URL for a given `width`/`height` (e.g. a 1600×900 hero) |
|
|
78
|
+
| `search_videos` | Search videos: `query`, `orientation`, `size`, `locale`, `page`, `per_page`, `detail` |
|
|
79
|
+
| `popular_videos` | Trending videos filtered by `min_/max_width`, `min_/max_height`, `min_/max_duration` |
|
|
80
|
+
| `get_video` | One video by id; `preview: true` attaches the thumbnail inline |
|
|
81
|
+
| `featured_collections` | Curated collections with photo/video counts |
|
|
82
|
+
| `collection_media` | Items in a collection, optionally `media_type=photos\|videos` |
|
|
83
|
+
|
|
84
|
+
`size` means different things per medium: for photos it is the minimum megapixel bucket
|
|
85
|
+
(`large` 24MP, `medium` 12MP, `small` 4MP); for videos it is the resolution
|
|
86
|
+
(`large` 4K, `medium` 1080p, `small` 480p).
|
|
87
|
+
|
|
88
|
+
`color` accepts a named colour (`red`, `orange`, `yellow`, `green`, `turquoise`, `blue`,
|
|
89
|
+
`violet`, `pink`, `brown`, `black`, `gray`, `white`) or `#rgb` / `#rrggbb`, normalised to
|
|
90
|
+
`rrggbb`.
|
|
91
|
+
|
|
92
|
+
### Detail levels
|
|
93
|
+
|
|
94
|
+
`detail: "brief"` is the default and is sized for agent context (~1,200 tokens for
|
|
95
|
+
`per_page: 15`). `detail: "full"` adds every rendition or every video quality.
|
|
96
|
+
|
|
97
|
+
| | `brief` | `full` |
|
|
98
|
+
|---|---|---|
|
|
99
|
+
| Photo | preview + download URL, dimensions, attribution | + all 8 renditions, `avg_color`, `liked` |
|
|
100
|
+
| Video | the single best file | every file with `fps`, `size_mb`, content type, plus `tags` and 3 pictures |
|
|
101
|
+
| Collection | metadata | same |
|
|
102
|
+
|
|
103
|
+
### Exact sizes
|
|
104
|
+
|
|
105
|
+
`photo_url` derives a CDN URL from the URL Pexels already returned, so it costs one cached
|
|
106
|
+
lookup and **no image download**:
|
|
107
|
+
|
|
108
|
+
```json
|
|
109
|
+
{ "id": 40090812, "width": 1600, "height": 900 }
|
|
110
|
+
→ https://images.pexels.com/photos/40090812/pexels-photo-40090812.jpeg
|
|
111
|
+
?auto=compress&cs=tinysrgb&w=1600&h=900&fit=crop
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
- Both sides given → `fit=crop` (exact box, verified against the live CDN).
|
|
115
|
+
- One side given → the ratio is kept.
|
|
116
|
+
- `fit: "max"` keeps the ratio inside the box.
|
|
117
|
+
- Dimensions are limited to 16–5000 px, and only `images.pexels.com` URLs are ever produced.
|
|
118
|
+
|
|
119
|
+
### Inline previews
|
|
120
|
+
|
|
121
|
+
`get_photo` and `get_video` accept `preview: true`, which attaches one small image block
|
|
122
|
+
(~480 px wide, roughly 20 KB) so a model can actually judge the shot. It is off by default
|
|
123
|
+
and exists only on single-item tools — a list of 15 images would cost far more context than
|
|
124
|
+
it saves.
|
|
125
|
+
|
|
126
|
+
`structuredContent` and the `outputSchema` are identical with or without a preview: the image
|
|
127
|
+
travels as an MCP `image` content block next to the text. Previews are capped at 1.5 MB, cached,
|
|
128
|
+
and the API key is never sent to the image CDN.
|
|
129
|
+
|
|
130
|
+
### Pagination
|
|
131
|
+
|
|
132
|
+
Always page numbers: `pagination.next_page` / `pagination.prev_page`. Pexels returns
|
|
133
|
+
pagination URLs containing a duplicated `/v1` segment (`/v1/v1/search`); those are never
|
|
134
|
+
forwarded. When `total_results` is missing, the next page is inferred from page fullness.
|
|
135
|
+
|
|
136
|
+
### Errors
|
|
137
|
+
|
|
138
|
+
Failures come back as tool results with `isError: true`, a message, and a hint — never as
|
|
139
|
+
protocol errors, so the agent can self-correct:
|
|
140
|
+
|
|
141
|
+
| `code` | Meaning |
|
|
142
|
+
|---|---|
|
|
143
|
+
| `UNAUTHORIZED` | 401/403 — check the API key |
|
|
144
|
+
| `NOT_FOUND` | 404 — verify the id |
|
|
145
|
+
| `RATE_LIMITED` | 429 — wait for the quota window |
|
|
146
|
+
| `UPSTREAM_UNAVAILABLE` | 5xx from Pexels |
|
|
147
|
+
| `NETWORK` | timeout / connection failure after retries |
|
|
148
|
+
| `DECODE` | response shape changed (reported as a bug, endpoint named) |
|
|
149
|
+
| `INVALID_INPUT` | Pexels rejected a request parameter |
|
|
150
|
+
| `INTERNAL` | unexpected |
|
|
151
|
+
|
|
152
|
+
Invalid arguments are rejected by the schema before any network call, with messages that
|
|
153
|
+
restate the valid range or list the valid colours.
|
|
154
|
+
|
|
155
|
+
## Behaviour worth knowing
|
|
156
|
+
|
|
157
|
+
- **Retry**: `429`, `5xx`, timeouts and connection errors, up to `1 + maxRetries` attempts,
|
|
158
|
+
backoff `0.5s → 1s → 2s` (cap 8s), `Retry-After` honoured and capped at 10s.
|
|
159
|
+
- **Cache**: in-memory, TTL 300s, 256 entries, LRU, single-flight. Identical requests are
|
|
160
|
+
keyed independently of argument order, so repeated queries cost no quota.
|
|
161
|
+
- **Rate limit**: `x-ratelimit-remaining` is read from every response and a warning is logged
|
|
162
|
+
when it drops below 20.
|
|
163
|
+
- **`size_mb` for videos** is computed from the `size` byte count Pexels reports. It is `null`
|
|
164
|
+
for payloads that omit it.
|
|
165
|
+
- **Attribution**: every item carries `photographer`/`creator` and `page_url`.
|
|
166
|
+
|
|
167
|
+
## Development
|
|
168
|
+
|
|
169
|
+
```bash
|
|
170
|
+
npm run dev # tsx watch
|
|
171
|
+
npm run typecheck # src + tests
|
|
172
|
+
npm run lint
|
|
173
|
+
npm test # unit + contract + integration, no network
|
|
174
|
+
npm run build
|
|
175
|
+
npm run test:live # opt-in, hits the real API (PEXELS_LIVE=1)
|
|
176
|
+
npm run fixtures # re-record test/fixtures/raw from the live API
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
Layout: `src/pexels/*` owns every Pexels quirk (`quirks.ts`, tolerant `schemas.ts`, `client.ts`),
|
|
180
|
+
`src/present/*` is pure formatting, and `src/tools/*` only wires them together.
|
|
181
|
+
|
|
182
|
+
Tests cover three levels: unit (quirks, cache, config, presenters), contract (recorded real
|
|
183
|
+
payloads through the schemas and presenters) and integration (`InMemoryTransport`, all 9 tools,
|
|
184
|
+
including the capitalised collection-tag regression).
|
|
185
|
+
|
|
186
|
+
## Not in v1
|
|
187
|
+
|
|
188
|
+
Downloading assets to disk, `multi_search`, semantic reranking, and account writes are
|
|
189
|
+
deliberately out of scope.
|
|
190
|
+
|
|
191
|
+
## License
|
|
192
|
+
|
|
193
|
+
MIT
|
package/dist/cache.js
ADDED
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* In-memory TTL + LRU cache with single-flight de-duplication.
|
|
3
|
+
*
|
|
4
|
+
* Purpose: agents repeat identical queries while assembling a page, and the
|
|
5
|
+
* Pexels quota is shared. Errors are never cached.
|
|
6
|
+
*/
|
|
7
|
+
export class RequestCache {
|
|
8
|
+
entries = new Map();
|
|
9
|
+
inflight = new Map();
|
|
10
|
+
ttlMs;
|
|
11
|
+
maxEntries;
|
|
12
|
+
now;
|
|
13
|
+
constructor(options) {
|
|
14
|
+
this.ttlMs = options.ttlMs;
|
|
15
|
+
this.maxEntries = options.maxEntries ?? 256;
|
|
16
|
+
this.now = options.now ?? Date.now;
|
|
17
|
+
}
|
|
18
|
+
get size() {
|
|
19
|
+
return this.entries.size;
|
|
20
|
+
}
|
|
21
|
+
clear() {
|
|
22
|
+
this.entries.clear();
|
|
23
|
+
this.inflight.clear();
|
|
24
|
+
}
|
|
25
|
+
/** Cache key must not depend on the order the caller supplied arguments in. */
|
|
26
|
+
static key(path, params) {
|
|
27
|
+
const pairs = Object.entries(params)
|
|
28
|
+
.filter(([, value]) => value !== undefined && value !== null && value !== '')
|
|
29
|
+
.map(([name, value]) => `${encodeURIComponent(name)}=${encodeURIComponent(String(value))}`)
|
|
30
|
+
.sort();
|
|
31
|
+
return pairs.length > 0 ? `${path}?${pairs.join('&')}` : path;
|
|
32
|
+
}
|
|
33
|
+
async wrap(key, load) {
|
|
34
|
+
if (this.ttlMs <= 0) {
|
|
35
|
+
return { value: await load(), cacheHit: false };
|
|
36
|
+
}
|
|
37
|
+
const cached = this.lookup(key);
|
|
38
|
+
if (cached !== undefined)
|
|
39
|
+
return { value: cached, cacheHit: true };
|
|
40
|
+
const pending = this.inflight.get(key);
|
|
41
|
+
if (pending)
|
|
42
|
+
return { value: await pending, cacheHit: true };
|
|
43
|
+
const promise = load()
|
|
44
|
+
.then((value) => {
|
|
45
|
+
this.store(key, value);
|
|
46
|
+
return value;
|
|
47
|
+
})
|
|
48
|
+
.finally(() => {
|
|
49
|
+
this.inflight.delete(key);
|
|
50
|
+
});
|
|
51
|
+
this.inflight.set(key, promise);
|
|
52
|
+
return { value: await promise, cacheHit: false };
|
|
53
|
+
}
|
|
54
|
+
lookup(key) {
|
|
55
|
+
const entry = this.entries.get(key);
|
|
56
|
+
if (!entry)
|
|
57
|
+
return undefined;
|
|
58
|
+
if (entry.expiresAt <= this.now()) {
|
|
59
|
+
this.entries.delete(key);
|
|
60
|
+
return undefined;
|
|
61
|
+
}
|
|
62
|
+
// Refresh recency: Map preserves insertion order, so re-insert at the end.
|
|
63
|
+
this.entries.delete(key);
|
|
64
|
+
this.entries.set(key, entry);
|
|
65
|
+
return entry.value;
|
|
66
|
+
}
|
|
67
|
+
store(key, value) {
|
|
68
|
+
this.entries.set(key, { expiresAt: this.now() + this.ttlMs, value });
|
|
69
|
+
while (this.entries.size > this.maxEntries) {
|
|
70
|
+
const oldest = this.entries.keys().next();
|
|
71
|
+
if (oldest.done)
|
|
72
|
+
break;
|
|
73
|
+
this.entries.delete(oldest.value);
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
//# sourceMappingURL=cache.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"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"}
|
package/dist/config.js
ADDED
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
import { readFileSync } from 'node:fs';
|
|
2
|
+
import { homedir } from 'node:os';
|
|
3
|
+
import { join } from 'node:path';
|
|
4
|
+
export class ConfigError extends Error {
|
|
5
|
+
configPath;
|
|
6
|
+
constructor(message, configPath) {
|
|
7
|
+
super(message);
|
|
8
|
+
this.name = 'ConfigError';
|
|
9
|
+
this.configPath = configPath;
|
|
10
|
+
}
|
|
11
|
+
}
|
|
12
|
+
const LOG_LEVELS = ['debug', 'info', 'warn', 'error'];
|
|
13
|
+
const DEFAULTS = {
|
|
14
|
+
timeoutMs: 15_000,
|
|
15
|
+
maxRetries: 2,
|
|
16
|
+
cacheTtlSeconds: 300,
|
|
17
|
+
locale: 'en-US',
|
|
18
|
+
logLevel: 'info',
|
|
19
|
+
};
|
|
20
|
+
export function defaultConfigPath(env = process.env) {
|
|
21
|
+
const base = env.XDG_CONFIG_HOME?.trim() || join(homedir(), '.config');
|
|
22
|
+
return join(base, 'pexels-mcp', 'config.json');
|
|
23
|
+
}
|
|
24
|
+
function readFileConfig(path) {
|
|
25
|
+
let raw;
|
|
26
|
+
try {
|
|
27
|
+
raw = readFileSync(path, 'utf8');
|
|
28
|
+
}
|
|
29
|
+
catch (error) {
|
|
30
|
+
const code = error.code;
|
|
31
|
+
if (code === 'ENOENT')
|
|
32
|
+
return {};
|
|
33
|
+
throw new ConfigError(`cannot read config file ${path}: ${error.message}`, path);
|
|
34
|
+
}
|
|
35
|
+
let parsed;
|
|
36
|
+
try {
|
|
37
|
+
parsed = JSON.parse(raw);
|
|
38
|
+
}
|
|
39
|
+
catch (error) {
|
|
40
|
+
throw new ConfigError(`config file ${path} is not valid JSON (${error.message})`, path);
|
|
41
|
+
}
|
|
42
|
+
if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
|
|
43
|
+
throw new ConfigError(`config file ${path} must contain a JSON object`, path);
|
|
44
|
+
}
|
|
45
|
+
return parsed;
|
|
46
|
+
}
|
|
47
|
+
function intFrom(value, name, { min, max, configPath, source }) {
|
|
48
|
+
const parsed = typeof value === 'string' ? Number(value.trim()) : value;
|
|
49
|
+
if (typeof parsed !== 'number' || !Number.isInteger(parsed)) {
|
|
50
|
+
throw new ConfigError(`${source} must be an integer, got ${JSON.stringify(value)}`, configPath);
|
|
51
|
+
}
|
|
52
|
+
if (parsed < min || parsed > max) {
|
|
53
|
+
throw new ConfigError(`${source} must be between ${min} and ${max}, got ${parsed}`, configPath);
|
|
54
|
+
}
|
|
55
|
+
return parsed;
|
|
56
|
+
}
|
|
57
|
+
export function loadConfig(options = {}) {
|
|
58
|
+
const env = options.env ?? process.env;
|
|
59
|
+
const configPath = options.configPath ?? defaultConfigPath(env);
|
|
60
|
+
const file = readFileConfig(configPath);
|
|
61
|
+
const rawKey = (typeof env.PEXELS_API_KEY === 'string' && env.PEXELS_API_KEY.trim() !== ''
|
|
62
|
+
? env.PEXELS_API_KEY
|
|
63
|
+
: undefined) ??
|
|
64
|
+
(typeof file.apiKey === 'string' ? file.apiKey : undefined);
|
|
65
|
+
const apiKey = typeof rawKey === 'string' ? rawKey.trim() : '';
|
|
66
|
+
if (apiKey === '') {
|
|
67
|
+
throw new ConfigError(`missing Pexels API key. Set the environment variable PEXELS_API_KEY, or create ${configPath} with:\n {"apiKey": "your_pexels_api_key"}`, configPath);
|
|
68
|
+
}
|
|
69
|
+
const timeoutMs = env.PEXELS_MCP_TIMEOUT_MS !== undefined
|
|
70
|
+
? intFrom(env.PEXELS_MCP_TIMEOUT_MS, 'PEXELS_MCP_TIMEOUT_MS', {
|
|
71
|
+
min: 1000,
|
|
72
|
+
max: 60000,
|
|
73
|
+
configPath,
|
|
74
|
+
source: 'PEXELS_MCP_TIMEOUT_MS',
|
|
75
|
+
})
|
|
76
|
+
: intFrom(file.timeoutMs ?? DEFAULTS.timeoutMs, 'timeoutMs', {
|
|
77
|
+
min: 1000,
|
|
78
|
+
max: 60000,
|
|
79
|
+
configPath,
|
|
80
|
+
source: 'timeoutMs',
|
|
81
|
+
});
|
|
82
|
+
const maxRetries = env.PEXELS_MCP_MAX_RETRIES !== undefined
|
|
83
|
+
? intFrom(env.PEXELS_MCP_MAX_RETRIES, 'PEXELS_MCP_MAX_RETRIES', {
|
|
84
|
+
min: 0,
|
|
85
|
+
max: 5,
|
|
86
|
+
configPath,
|
|
87
|
+
source: 'PEXELS_MCP_MAX_RETRIES',
|
|
88
|
+
})
|
|
89
|
+
: intFrom(file.maxRetries ?? DEFAULTS.maxRetries, 'maxRetries', {
|
|
90
|
+
min: 0,
|
|
91
|
+
max: 5,
|
|
92
|
+
configPath,
|
|
93
|
+
source: 'maxRetries',
|
|
94
|
+
});
|
|
95
|
+
const cacheTtlSeconds = env.PEXELS_MCP_CACHE_TTL_S !== undefined
|
|
96
|
+
? intFrom(env.PEXELS_MCP_CACHE_TTL_S, 'PEXELS_MCP_CACHE_TTL_S', {
|
|
97
|
+
min: 0,
|
|
98
|
+
max: 3600,
|
|
99
|
+
configPath,
|
|
100
|
+
source: 'PEXELS_MCP_CACHE_TTL_S',
|
|
101
|
+
})
|
|
102
|
+
: intFrom(file.cacheTtlSeconds ?? DEFAULTS.cacheTtlSeconds, 'cacheTtlSeconds', {
|
|
103
|
+
min: 0,
|
|
104
|
+
max: 3600,
|
|
105
|
+
configPath,
|
|
106
|
+
source: 'cacheTtlSeconds',
|
|
107
|
+
});
|
|
108
|
+
const rawLevel = env.PEXELS_MCP_LOG_LEVEL ?? file.logLevel ?? DEFAULTS.logLevel;
|
|
109
|
+
if (typeof rawLevel !== 'string' || !LOG_LEVELS.includes(rawLevel)) {
|
|
110
|
+
throw new ConfigError(`logLevel must be one of ${LOG_LEVELS.join(', ')}, got ${JSON.stringify(rawLevel)}`, configPath);
|
|
111
|
+
}
|
|
112
|
+
const locale = typeof env.PEXELS_MCP_LOCALE === 'string' && env.PEXELS_MCP_LOCALE.trim() !== ''
|
|
113
|
+
? env.PEXELS_MCP_LOCALE.trim()
|
|
114
|
+
: typeof file.locale === 'string' && file.locale.trim() !== ''
|
|
115
|
+
? file.locale.trim()
|
|
116
|
+
: DEFAULTS.locale;
|
|
117
|
+
return {
|
|
118
|
+
apiKey,
|
|
119
|
+
timeoutMs,
|
|
120
|
+
maxRetries,
|
|
121
|
+
cacheTtlSeconds,
|
|
122
|
+
locale,
|
|
123
|
+
logLevel: rawLevel,
|
|
124
|
+
configPath,
|
|
125
|
+
};
|
|
126
|
+
}
|
|
127
|
+
//# sourceMappingURL=config.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}
|
package/dist/errors.js
ADDED
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A failure the agent can act on. Always rendered as a tool result with
|
|
3
|
+
* `isError: true`, never as a protocol error.
|
|
4
|
+
*/
|
|
5
|
+
export class ToolError extends Error {
|
|
6
|
+
code;
|
|
7
|
+
hint;
|
|
8
|
+
status;
|
|
9
|
+
constructor(code, message, options = {}) {
|
|
10
|
+
super(message);
|
|
11
|
+
this.name = 'ToolError';
|
|
12
|
+
this.code = code;
|
|
13
|
+
this.hint = options.hint;
|
|
14
|
+
this.status = options.status;
|
|
15
|
+
}
|
|
16
|
+
}
|
|
17
|
+
export function isToolError(value) {
|
|
18
|
+
return value instanceof ToolError;
|
|
19
|
+
}
|
|
20
|
+
function textOf(error) {
|
|
21
|
+
if (isToolError(error))
|
|
22
|
+
return error.message;
|
|
23
|
+
if (error instanceof Error)
|
|
24
|
+
return error.message;
|
|
25
|
+
return String(error);
|
|
26
|
+
}
|
|
27
|
+
export function toolErrorResult(error) {
|
|
28
|
+
const err = isToolError(error)
|
|
29
|
+
? error
|
|
30
|
+
: new ToolError('INTERNAL', textOf(error), {
|
|
31
|
+
hint: 'this is a bug in pexels-mcp — report it with the tool name and arguments',
|
|
32
|
+
});
|
|
33
|
+
const body = {
|
|
34
|
+
code: err.code,
|
|
35
|
+
message: err.message,
|
|
36
|
+
};
|
|
37
|
+
if (err.hint !== undefined)
|
|
38
|
+
body.hint = err.hint;
|
|
39
|
+
if (err.status !== undefined)
|
|
40
|
+
body.status = err.status;
|
|
41
|
+
const text = err.hint ? `error: ${err.message}\nhint: ${err.hint}` : `error: ${err.message}`;
|
|
42
|
+
return {
|
|
43
|
+
content: [{ type: 'text', text }],
|
|
44
|
+
isError: true,
|
|
45
|
+
structuredContent: { error: body },
|
|
46
|
+
};
|
|
47
|
+
}
|
|
48
|
+
export function textResult(text, structured, images = []) {
|
|
49
|
+
return {
|
|
50
|
+
content: [
|
|
51
|
+
{ type: 'text', text },
|
|
52
|
+
...images.map((image) => ({ type: 'image', data: image.data, mimeType: image.mimeType })),
|
|
53
|
+
],
|
|
54
|
+
structuredContent: structured,
|
|
55
|
+
};
|
|
56
|
+
}
|
|
57
|
+
//# sourceMappingURL=errors.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAiBA;;;GAGG;AACH,MAAM,OAAO,SAAU,SAAQ,KAAK;IACzB,IAAI,CAAY;IAChB,IAAI,CAAqB;IACzB,MAAM,CAAqB;IAEpC,YAAY,IAAe,EAAE,OAAe,EAAE,UAA4B,EAAE;QAC1E,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAC/B,CAAC;CACF;AAED,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAO,KAAK,YAAY,SAAS,CAAC;AACpC,CAAC;AAED,SAAS,MAAM,CAAC,KAAc;IAC5B,IAAI,WAAW,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,OAAO,CAAC;IAC7C,IAAI,KAAK,YAAY,KAAK;QAAE,OAAO,KAAK,CAAC,OAAO,CAAC;IACjD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,MAAM,GAAG,GAAG,WAAW,CAAC,KAAK,CAAC;QAC5B,CAAC,CAAC,KAAK;QACP,CAAC,CAAC,IAAI,SAAS,CAAC,UAAU,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE;YACvC,IAAI,EAAE,0EAA0E;SACjF,CAAC,CAAC;IAEP,MAAM,IAAI,GAA4B;QACpC,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,OAAO,EAAE,GAAG,CAAC,OAAO;KACrB,CAAC;IACF,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS;QAAE,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;IACjD,IAAI,GAAG,CAAC,MAAM,KAAK,SAAS;QAAE,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;IAEvD,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,GAAG,CAAC,OAAO,WAAW,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,UAAU,GAAG,CAAC,OAAO,EAAE,CAAC;IAE7F,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;QACjC,OAAO,EAAE,IAAI;QACb,iBAAiB,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE;KACjB,CAAC;AACtB,CAAC;AAQD,MAAM,UAAU,UAAU,CACxB,IAAY,EACZ,UAAmC,EACnC,SAAqC,EAAE;IAEvC,OAAO;QACL,OAAO,EAAE;YACP,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;YACtB,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,OAAgB,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;SACnG;QACD,iBAAiB,EAAE,UAAU;KACZ,CAAC;AACtB,CAAC"}
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { McpServer } from '@modelcontextprotocol/server';
|
|
3
|
+
import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
|
|
4
|
+
import { RequestCache } from './cache.js';
|
|
5
|
+
import { ConfigError, loadConfig } from './config.js';
|
|
6
|
+
import { log, redactKey, setLogLevel } from './log.js';
|
|
7
|
+
import { PEXELS_BASE_URL, PexelsClient } from './pexels/client.js';
|
|
8
|
+
import { registerTools } from './tools/index.js';
|
|
9
|
+
import { SERVER_NAME, VERSION } from './version.js';
|
|
10
|
+
const INSTRUCTIONS = [
|
|
11
|
+
'Pexels stock photos and videos, with compact results and honest pagination.',
|
|
12
|
+
'',
|
|
13
|
+
'Workflow:',
|
|
14
|
+
'1. Start with search_photos or search_videos using a short, concrete query. Keep per_page small (5–15).',
|
|
15
|
+
'2. Choose by aspect_ratio, orientation, width/height and duration_seconds.',
|
|
16
|
+
'3. Call get_photo or get_video only when you need a specific id or every rendition.',
|
|
17
|
+
'4. Add detail="full" only when you need all renditions or all video qualities; it is much larger.',
|
|
18
|
+
'5. Need an exact size (a 1600x900 hero, a 1200x630 social card)? Call photo_url instead of guessing CDN parameters.',
|
|
19
|
+
'6. Set preview=true on get_photo/get_video only when you must literally see the image to choose it — it costs context.',
|
|
20
|
+
'',
|
|
21
|
+
'Rules that matter:',
|
|
22
|
+
'- Pagination is always page numbers (pagination.next_page / prev_page), never URLs. Do not construct Pexels URLs yourself.',
|
|
23
|
+
'- Empty results are not errors: read the hints and relax a filter.',
|
|
24
|
+
'- When you use an asset, credit the photographer/creator and link page_url.',
|
|
25
|
+
].join('\n');
|
|
26
|
+
function fail(message) {
|
|
27
|
+
process.stderr.write(`${SERVER_NAME}: ${message}\n`);
|
|
28
|
+
process.exit(1);
|
|
29
|
+
}
|
|
30
|
+
function buildClient(config) {
|
|
31
|
+
return new PexelsClient({
|
|
32
|
+
apiKey: config.apiKey,
|
|
33
|
+
baseUrl: PEXELS_BASE_URL,
|
|
34
|
+
timeoutMs: config.timeoutMs,
|
|
35
|
+
maxRetries: config.maxRetries,
|
|
36
|
+
cache: new RequestCache({ ttlMs: config.cacheTtlSeconds * 1000 }),
|
|
37
|
+
});
|
|
38
|
+
}
|
|
39
|
+
async function main() {
|
|
40
|
+
let config;
|
|
41
|
+
try {
|
|
42
|
+
config = loadConfig();
|
|
43
|
+
}
|
|
44
|
+
catch (error) {
|
|
45
|
+
if (error instanceof ConfigError)
|
|
46
|
+
fail(error.message);
|
|
47
|
+
throw error;
|
|
48
|
+
}
|
|
49
|
+
setLogLevel(config.logLevel);
|
|
50
|
+
log('info', 'startup', {
|
|
51
|
+
version: VERSION,
|
|
52
|
+
configPath: config.configPath,
|
|
53
|
+
apiKey: redactKey(config.apiKey),
|
|
54
|
+
timeoutMs: config.timeoutMs,
|
|
55
|
+
maxRetries: config.maxRetries,
|
|
56
|
+
cacheTtlSeconds: config.cacheTtlSeconds,
|
|
57
|
+
locale: config.locale,
|
|
58
|
+
});
|
|
59
|
+
const server = new McpServer({ name: SERVER_NAME, version: VERSION }, { instructions: INSTRUCTIONS });
|
|
60
|
+
registerTools(server, { client: buildClient(config), config });
|
|
61
|
+
const transport = new StdioServerTransport();
|
|
62
|
+
await server.connect(transport);
|
|
63
|
+
log('info', 'ready', { transport: 'stdio' });
|
|
64
|
+
const shutdown = (signal) => {
|
|
65
|
+
log('info', 'shutdown', { signal });
|
|
66
|
+
void server.close().finally(() => {
|
|
67
|
+
process.exit(0);
|
|
68
|
+
});
|
|
69
|
+
};
|
|
70
|
+
process.once('SIGINT', () => shutdown('SIGINT'));
|
|
71
|
+
process.once('SIGTERM', () => shutdown('SIGTERM'));
|
|
72
|
+
}
|
|
73
|
+
main().catch((error) => {
|
|
74
|
+
log('error', 'fatal', { message: error instanceof Error ? error.message : String(error) });
|
|
75
|
+
process.exit(1);
|
|
76
|
+
});
|
|
77
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
|
package/dist/log.js
ADDED
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Structured logging to stderr only.
|
|
3
|
+
*
|
|
4
|
+
* stdout belongs to JSON-RPC: anything written there corrupts the protocol,
|
|
5
|
+
* so every log line goes to stderr as a single JSON object.
|
|
6
|
+
*/
|
|
7
|
+
const RANK = {
|
|
8
|
+
debug: 10,
|
|
9
|
+
info: 20,
|
|
10
|
+
warn: 30,
|
|
11
|
+
error: 40,
|
|
12
|
+
};
|
|
13
|
+
let threshold = RANK.info;
|
|
14
|
+
let sink = (line) => {
|
|
15
|
+
process.stderr.write(line);
|
|
16
|
+
};
|
|
17
|
+
export function setLogLevel(level) {
|
|
18
|
+
threshold = RANK[level];
|
|
19
|
+
}
|
|
20
|
+
/** Test hook: capture log lines instead of writing to stderr. Returns a restore function. */
|
|
21
|
+
export function captureLogs() {
|
|
22
|
+
const lines = [];
|
|
23
|
+
const previous = sink;
|
|
24
|
+
sink = (line) => {
|
|
25
|
+
lines.push(line);
|
|
26
|
+
};
|
|
27
|
+
return {
|
|
28
|
+
lines,
|
|
29
|
+
restore: () => {
|
|
30
|
+
sink = previous;
|
|
31
|
+
},
|
|
32
|
+
};
|
|
33
|
+
}
|
|
34
|
+
export function log(level, event, fields = {}) {
|
|
35
|
+
if (RANK[level] < threshold)
|
|
36
|
+
return;
|
|
37
|
+
const line = `${JSON.stringify({
|
|
38
|
+
ts: new Date().toISOString(),
|
|
39
|
+
level,
|
|
40
|
+
event,
|
|
41
|
+
...fields,
|
|
42
|
+
})}\n`;
|
|
43
|
+
sink(line);
|
|
44
|
+
}
|
|
45
|
+
/**
|
|
46
|
+
* Never let an API key reach a log line, an error message, or a tool result.
|
|
47
|
+
* The length is enough to tell two keys apart without exposing any characters.
|
|
48
|
+
*/
|
|
49
|
+
export function redactKey(key) {
|
|
50
|
+
if (!key)
|
|
51
|
+
return '<missing>';
|
|
52
|
+
return `*** (${key.length} chars)`;
|
|
53
|
+
}
|
|
54
|
+
//# sourceMappingURL=log.js.map
|
package/dist/log.js.map
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"log.js","sourceRoot":"","sources":["../src/log.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,IAAI,GAA6B;IACrC,KAAK,EAAE,EAAE;IACT,IAAI,EAAE,EAAE;IACR,IAAI,EAAE,EAAE;IACR,KAAK,EAAE,EAAE;CACV,CAAC;AAEF,IAAI,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC;AAC1B,IAAI,IAAI,GAA2B,CAAC,IAAI,EAAE,EAAE;IAC1C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC,CAAC;AAEF,MAAM,UAAU,WAAW,CAAC,KAAe;IACzC,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;AAC1B,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,WAAW;IACzB,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,QAAQ,GAAG,IAAI,CAAC;IACtB,IAAI,GAAG,CAAC,IAAI,EAAE,EAAE;QACd,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnB,CAAC,CAAC;IACF,OAAO;QACL,KAAK;QACL,OAAO,EAAE,GAAG,EAAE;YACZ,IAAI,GAAG,QAAQ,CAAC;QAClB,CAAC;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,GAAG,CACjB,KAAe,EACf,KAAa,EACb,SAAkC,EAAE;IAEpC,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,SAAS;QAAE,OAAO;IACpC,MAAM,IAAI,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC;QAC7B,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QAC5B,KAAK;QACL,KAAK;QACL,GAAG,MAAM;KACV,CAAC,IAAI,CAAC;IACP,IAAI,CAAC,IAAI,CAAC,CAAC;AACb,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,GAAuB;IAC/C,IAAI,CAAC,GAAG;QAAE,OAAO,WAAW,CAAC;IAC7B,OAAO,QAAQ,GAAG,CAAC,MAAM,SAAS,CAAC;AACrC,CAAC"}
|