@stophy/mcp 1.0.5 → 1.2.0
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 +70 -227
- package/dist/index.js +35 -31
- package/package.json +26 -19
- package/dist/http.js +0 -54
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Stophy
|
|
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,111 +1,92 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Stophy MCP
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://smithery.ai/servers/stophy/mcp)
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Web scraping API for AI agents, as an MCP server. One API to search the web, read what people say, and look up products, places, jobs and homes. Pay only for answers. Your agent reaches every Stophy endpoint through three MCP tools.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
[](https://cursor.com/en/install-mcp?name=stophy&config=eyJ1cmwiOiJodHRwczovL21jcC5zdG9waHkuZGV2L21jcCJ9)
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
## Connect to the hosted server
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
Most apps can connect to the hosted server directly. There is nothing to install.
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
13
|
+
| URL | How you connect | What your agent can use |
|
|
14
|
+
| --- | --- | --- |
|
|
15
|
+
| `https://api.stophy.dev/mcp` | No key | The endpoints marked `keyless: true` in the [endpoint list](https://api.stophy.dev/v1/endpoints), within a free allowance |
|
|
16
|
+
| `https://api.stophy.dev/mcp` | `Authorization: Bearer <key>` header | Every endpoint |
|
|
17
|
+
| `https://mcp.stophy.dev/mcp` | Sign in with your browser | Every endpoint |
|
|
16
18
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
```json
|
|
20
|
-
{
|
|
21
|
-
"mcpServers": {
|
|
22
|
-
"stophy": {
|
|
23
|
-
"url": "https://mcp.stophy.dev/$STOPHY_API_KEY/mcp"
|
|
24
|
-
}
|
|
25
|
-
}
|
|
26
|
-
}
|
|
27
|
-
```
|
|
19
|
+
Get an API key at [stophy.dev/signup](https://stophy.dev/signup).
|
|
28
20
|
|
|
29
|
-
|
|
21
|
+
### Claude
|
|
30
22
|
|
|
31
|
-
|
|
23
|
+
In Claude on the web, Desktop or mobile, open [Customize > Connectors](https://claude.ai/customize/connectors), choose **Add custom connector**, and paste `https://mcp.stophy.dev/mcp`. Sign in when Claude asks.
|
|
32
24
|
|
|
33
|
-
###
|
|
25
|
+
### Claude Code
|
|
34
26
|
|
|
35
|
-
|
|
27
|
+
To sign in with your browser, add the server, then run `/mcp` and choose **Authenticate**:
|
|
36
28
|
|
|
37
29
|
```bash
|
|
38
|
-
|
|
30
|
+
claude mcp add --transport http stophy https://mcp.stophy.dev/mcp
|
|
39
31
|
```
|
|
40
32
|
|
|
41
|
-
|
|
33
|
+
To use an API key:
|
|
42
34
|
|
|
43
35
|
```bash
|
|
44
|
-
|
|
45
|
-
env STOPHY_API_KEY=$STOPHY_API_KEY stophy-mcp
|
|
36
|
+
claude mcp add --transport http stophy https://api.stophy.dev/mcp --header "Authorization: Bearer <key>"
|
|
46
37
|
```
|
|
47
38
|
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
Pick your MCP client.
|
|
39
|
+
To start without a key:
|
|
51
40
|
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
File: `claude_desktop_config.json`
|
|
55
|
-
- macOS: `~/Library/Application Support/Claude/`
|
|
56
|
-
- Windows: `%APPDATA%\Claude\`
|
|
57
|
-
|
|
58
|
-
```json
|
|
59
|
-
{
|
|
60
|
-
"mcpServers": {
|
|
61
|
-
"stophy": {
|
|
62
|
-
"command": "npx",
|
|
63
|
-
"args": ["-y", "@stophy/mcp"],
|
|
64
|
-
"env": {
|
|
65
|
-
"STOPHY_API_KEY": "your_api_key_here"
|
|
66
|
-
}
|
|
67
|
-
}
|
|
68
|
-
}
|
|
69
|
-
}
|
|
41
|
+
```bash
|
|
42
|
+
claude mcp add --transport http stophy https://api.stophy.dev/mcp
|
|
70
43
|
```
|
|
71
44
|
|
|
72
|
-
|
|
45
|
+
### Codex
|
|
73
46
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
Stdio:
|
|
47
|
+
To use the key in your `STOPHY_API_KEY` environment variable:
|
|
77
48
|
|
|
78
49
|
```bash
|
|
79
|
-
|
|
50
|
+
codex mcp add stophy --url https://api.stophy.dev/mcp --bearer-token-env-var STOPHY_API_KEY
|
|
80
51
|
```
|
|
81
52
|
|
|
82
|
-
|
|
53
|
+
To sign in with your browser instead, add the sign-in URL, then log in:
|
|
83
54
|
|
|
84
55
|
```bash
|
|
85
|
-
|
|
56
|
+
codex mcp add stophy --url https://mcp.stophy.dev/mcp
|
|
57
|
+
codex mcp login stophy
|
|
86
58
|
```
|
|
87
59
|
|
|
88
60
|
### Cursor
|
|
89
61
|
|
|
90
|
-
|
|
62
|
+
Use the **Add to Cursor** button above to sign in with your browser, or add this to `.cursor/mcp.json` to use a key:
|
|
91
63
|
|
|
92
64
|
```json
|
|
93
65
|
{
|
|
94
66
|
"mcpServers": {
|
|
95
67
|
"stophy": {
|
|
96
|
-
"
|
|
97
|
-
"
|
|
98
|
-
"env": {
|
|
99
|
-
"STOPHY_API_KEY": "$STOPHY_API_KEY"
|
|
100
|
-
}
|
|
68
|
+
"url": "https://api.stophy.dev/mcp",
|
|
69
|
+
"headers": { "Authorization": "Bearer <key>" }
|
|
101
70
|
}
|
|
102
71
|
}
|
|
103
72
|
}
|
|
104
73
|
```
|
|
105
74
|
|
|
106
|
-
|
|
75
|
+
To start without a key, leave out `headers`.
|
|
76
|
+
|
|
77
|
+
## Run it as a local server
|
|
107
78
|
|
|
108
|
-
|
|
79
|
+
Some apps can only start a local MCP server. For those, use this package. It runs on your computer and passes every request to the hosted server, so it always has the same tools.
|
|
80
|
+
|
|
81
|
+
```bash
|
|
82
|
+
npx -y @stophy/mcp
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
With `STOPHY_API_KEY` set, your agent can use every endpoint. Without it, your agent can use the endpoints that need no key, within a free allowance.
|
|
86
|
+
|
|
87
|
+
### Claude Desktop
|
|
88
|
+
|
|
89
|
+
Add this to `claude_desktop_config.json`, then restart Claude Desktop:
|
|
109
90
|
|
|
110
91
|
```json
|
|
111
92
|
{
|
|
@@ -113,185 +94,47 @@ File: `~/.codeium/windsurf/mcp_config.json`
|
|
|
113
94
|
"stophy": {
|
|
114
95
|
"command": "npx",
|
|
115
96
|
"args": ["-y", "@stophy/mcp"],
|
|
116
|
-
"env": {
|
|
117
|
-
"STOPHY_API_KEY": "$STOPHY_API_KEY"
|
|
118
|
-
}
|
|
97
|
+
"env": { "STOPHY_API_KEY": "<key>" }
|
|
119
98
|
}
|
|
120
99
|
}
|
|
121
100
|
}
|
|
122
101
|
```
|
|
123
102
|
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
Add to `config.yaml` under `mcp_servers`:
|
|
127
|
-
|
|
128
|
-
```yaml
|
|
129
|
-
mcp_servers:
|
|
130
|
-
- name: stophy
|
|
131
|
-
command: npx
|
|
132
|
-
args: ["-y", "@stophy/mcp"]
|
|
133
|
-
env:
|
|
134
|
-
STOPHY_API_KEY: your_api_key_here
|
|
135
|
-
```
|
|
136
|
-
|
|
137
|
-
### Any other MCP client
|
|
103
|
+
To start without a key, leave out `env`.
|
|
138
104
|
|
|
139
|
-
|
|
105
|
+
The package needs Node.js 18 or later.
|
|
140
106
|
|
|
141
|
-
|
|
107
|
+
| Variable | What it does |
|
|
108
|
+
| --- | --- |
|
|
109
|
+
| `STOPHY_API_KEY` | Your Stophy API key. Optional. |
|
|
110
|
+
| `STOPHY_MCP_URL` | The server to connect to. The default is `https://api.stophy.dev/mcp`. |
|
|
142
111
|
|
|
143
|
-
|
|
112
|
+
## Tools
|
|
144
113
|
|
|
145
114
|
| Tool | What it does |
|
|
146
|
-
|
|
147
|
-
| `
|
|
148
|
-
| `
|
|
149
|
-
| `
|
|
150
|
-
| `stophy_get_playlist` | Fetch every video in a playlist. |
|
|
151
|
-
| `stophy_get_suggestions` | YouTube autocomplete for a partial query. |
|
|
152
|
-
| `stophy_get_credits` | Your remaining credit balance. Free. |
|
|
153
|
-
|
|
154
|
-
## Tool reference
|
|
155
|
-
|
|
156
|
-
### stophy_search_videos
|
|
157
|
-
|
|
158
|
-
Search YouTube. Use this to discover videos on a topic or find recent uploads. Not for fetching a specific video you already have the URL for — use `stophy_get_video` instead.
|
|
159
|
-
|
|
160
|
-
Arguments:
|
|
161
|
-
- `q` (required): what to search for
|
|
162
|
-
- `type`: `"video"`, `"short"`, `"channel"`, or `"playlist"`
|
|
163
|
-
- `uploadDate`: `"hour"`, `"today"`, `"week"`, `"month"`, or `"year"`
|
|
164
|
-
- `duration`: `"short"`, `"medium"`, or `"long"`
|
|
165
|
-
- `sortBy`: `"relevance"`, `"popularity"`, `"date"`, or `"rating"`
|
|
166
|
-
- `continuationToken`: token from previous response for the next page
|
|
167
|
-
|
|
168
|
-
```json
|
|
169
|
-
{
|
|
170
|
-
"q": "typescript tutorial",
|
|
171
|
-
"uploadDate": "week",
|
|
172
|
-
"type": "video"
|
|
173
|
-
}
|
|
174
|
-
```
|
|
175
|
-
|
|
176
|
-
Returns `items[]` and an optional `continuationToken`.
|
|
177
|
-
|
|
178
|
-
### stophy_get_video
|
|
115
|
+
| --- | --- |
|
|
116
|
+
| `stophy_search_endpoints` | Finds the endpoint for a task, with its cost |
|
|
117
|
+
| `stophy_describe_endpoint` | Shows the input an endpoint takes and what it returns |
|
|
118
|
+
| `stophy_call` | Runs an endpoint with `id`, `input` and optional `fields`, and returns JSON |
|
|
179
119
|
|
|
180
|
-
|
|
120
|
+
Your agent usually searches, then describes, then calls. Endpoint ids are camelCase, such as `googleSearch` or `youtubeSearch`. Lists come back as `results`, and `fields` keeps only the keys you name on each row. Each result says how many credits it used.
|
|
181
121
|
|
|
182
|
-
|
|
183
|
-
- `videoUrl` (required): YouTube video URL or ID
|
|
184
|
-
- `type` (required): `"details"`, `"transcript"`, `"comments"`, or `"livechat"`
|
|
185
|
-
- `sortBy`: `"top"` or `"latest"` for comments
|
|
186
|
-
- `chatType`: `"top"` or `"live"` for live chat
|
|
187
|
-
- `continuationToken`: next page of comments, or a comment's `repliesToken` for replies
|
|
122
|
+
To point at one thing, send its link or its id, never both: `videoUrl` or `videoId`, `placeUrl` or `placeId`, `userUrl` or `username`. The endpoint description lists the pair.
|
|
188
123
|
|
|
189
|
-
|
|
124
|
+
One call returns one page from the site at the price shown for that endpoint. Most calls cost 1 credit, some cost 2, and long lists cost 1 credit per 10 results. Some list endpoints take `page` and return `page`: ask for the next number, and stop when `results` comes back empty. Others return a `cursor` when there is more: pass it back unchanged as `cursor` to get the next page.
|
|
190
125
|
|
|
191
|
-
|
|
192
|
-
{
|
|
193
|
-
"videoUrl": "https://youtube.com/watch?v=d56mG7DezGs",
|
|
194
|
-
"type": "transcript"
|
|
195
|
-
}
|
|
196
|
-
```
|
|
197
|
-
|
|
198
|
-
Comments:
|
|
199
|
-
|
|
200
|
-
```json
|
|
201
|
-
{
|
|
202
|
-
"videoUrl": "https://youtube.com/watch?v=d56mG7DezGs",
|
|
203
|
-
"type": "comments",
|
|
204
|
-
"sortBy": "top"
|
|
205
|
-
}
|
|
206
|
-
```
|
|
207
|
-
|
|
208
|
-
For comment replies, call again with `type: "comments"` and set `continuationToken` to the comment's `repliesToken`.
|
|
209
|
-
|
|
210
|
-
### stophy_get_channel
|
|
211
|
-
|
|
212
|
-
Browse a channel.
|
|
213
|
-
|
|
214
|
-
Arguments:
|
|
215
|
-
- `channelUrl` (required): channel URL, handle (@username), or channel ID
|
|
216
|
-
- `tab`: `"video"`, `"short"`, `"playlist"`, or `"about"` (default: `"video"`)
|
|
217
|
-
- `sortBy`: `"latest"`, `"popular"`, or `"oldest"` for the video tab
|
|
218
|
-
- `continuationToken`: next page
|
|
126
|
+
## Network and credentials
|
|
219
127
|
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
"sortBy": "latest"
|
|
225
|
-
}
|
|
226
|
-
```
|
|
227
|
-
|
|
228
|
-
The `about` tab returns the channel's country, join date, view count, and links.
|
|
229
|
-
|
|
230
|
-
### stophy_get_playlist
|
|
231
|
-
|
|
232
|
-
All videos in a playlist.
|
|
233
|
-
|
|
234
|
-
Arguments:
|
|
235
|
-
- `playlistUrl` (required): playlist URL or ID
|
|
236
|
-
- `continuationToken`: next page
|
|
237
|
-
|
|
238
|
-
```json
|
|
239
|
-
{
|
|
240
|
-
"playlistUrl": "https://youtube.com/playlist?list=PLTjRvDozrdlxEIuOBZkMAK5uiqp8rHUax"
|
|
241
|
-
}
|
|
242
|
-
```
|
|
128
|
+
- The hosted server lives at `https://mcp.stophy.dev/mcp` (sign in) and `https://api.stophy.dev/mcp` (no key or an API key). Your client sends requests only there.
|
|
129
|
+
- Credentials: browser sign-in handled by your MCP client, or an optional `STOPHY_API_KEY` that you set yourself. The local package also reads an optional `STOPHY_MCP_URL`.
|
|
130
|
+
- The plugin manifests (`.mcp.json`, `.grok-plugin/plugin.json`, `mcp.json`, `plugin.json`) only point at the hosted server. They run no code on your machine.
|
|
131
|
+
- No telemetry.
|
|
243
132
|
|
|
244
|
-
|
|
133
|
+
## More
|
|
245
134
|
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
Arguments:
|
|
249
|
-
- `q` (required): partial query
|
|
250
|
-
- `hl`: language code, default `en`
|
|
251
|
-
- `gl`: region code, default `US`
|
|
252
|
-
|
|
253
|
-
```json
|
|
254
|
-
{
|
|
255
|
-
"q": "react hooks",
|
|
256
|
-
"hl": "en",
|
|
257
|
-
"gl": "US"
|
|
258
|
-
}
|
|
259
|
-
```
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
## Pagination
|
|
263
|
-
|
|
264
|
-
Any tool that returns `continuationToken` supports pagination. Pass the token back with the same arguments to get the next page. A missing or null token means you've reached the end.
|
|
265
|
-
|
|
266
|
-
## Empty results
|
|
267
|
-
|
|
268
|
-
When a video has no transcript, comments are off, or a comment has no replies, Stophy returns an `empty` object:
|
|
269
|
-
|
|
270
|
-
```json
|
|
271
|
-
{
|
|
272
|
-
"empty": {
|
|
273
|
-
"code": "EMPTY_TRANSCRIPT_SEGMENTS",
|
|
274
|
-
"message": "No transcript segments found."
|
|
275
|
-
}
|
|
276
|
-
}
|
|
277
|
-
```
|
|
278
|
-
|
|
279
|
-
Possible codes: `EMPTY_TRANSCRIPT_SEGMENTS`, `EMPTY_COMMENTS`, `EMPTY_COMMENT_REPLIES`.
|
|
280
|
-
|
|
281
|
-
## Errors
|
|
282
|
-
|
|
283
|
-
Errors come back as text in the MCP tool response:
|
|
284
|
-
|
|
285
|
-
```
|
|
286
|
-
Stophy error (UNAUTHORIZED): Invalid API key.
|
|
287
|
-
```
|
|
288
|
-
|
|
289
|
-
```
|
|
290
|
-
Stophy error (MISSING_API_KEY): No Stophy API key provided. Set STOPHY_API_KEY (stdio) or include your key in the URL path (hosted). Get a key at https://stophy.dev/dashboard.
|
|
291
|
-
```
|
|
135
|
+
- [Stophy docs](https://docs.stophy.dev)
|
|
136
|
+
- [Dashboard and API keys](https://stophy.dev/dashboard)
|
|
292
137
|
|
|
293
|
-
##
|
|
138
|
+
## License
|
|
294
139
|
|
|
295
|
-
|
|
296
|
-
|----------|----------|-----------|
|
|
297
|
-
| `STOPHY_API_KEY` | Stdio only | Your Stophy API key. Not needed for hosted — the key is in the URL path. |
|
|
140
|
+
MIT
|