@stophy/mcp 1.0.5 → 1.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stophy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,297 +1,140 @@
-# @stophy/mcp
+# Stophy MCP
 
-YouTube data for AI agents. Transcripts, comments, search, channels, playlists — all as structured JSON through the Model Context Protocol.
+[![smithery badge](https://smithery.ai/badge/stophy/mcp)](https://smithery.ai/servers/stophy/mcp)
 
-## How to connect
+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.
 
-Two ways. Pick one.
+[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=stophy&config=eyJ1cmwiOiJodHRwczovL21jcC5zdG9waHkuZGV2L21jcCJ9)
 
-### Option 1: hosted HTTP (zero install)
+## Connect to the hosted server
 
-Give your MCP client this URL. Your API key goes in the path.
+Most apps can connect to the hosted server directly. There is nothing to install.
 
-```
-https://mcp.stophy.dev/$STOPHY_API_KEY/mcp
-```
+| URL                          | How you connect                      | What your agent can use                                                                                                   |
+| ---------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
+| `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 |
+| `https://api.stophy.dev/mcp` | `Authorization: Bearer <key>` header | Every endpoint                                                                                                            |
+| `https://mcp.stophy.dev/mcp` | Sign in with your browser            | Every endpoint                                                                                                            |
 
-MCP client config:
-
-```json
-{
-  "mcpServers": {
-    "stophy": {
-      "url": "https://mcp.stophy.dev/$STOPHY_API_KEY/mcp"
-    }
-  }
-}
-```
+Get an API key at [stophy.dev/signup](https://stophy.dev/signup).
 
-No install. No Node.js. Works anywhere that speaks HTTP MCP.
+### Claude
 
-Get an API key at [stophy.dev/dashboard](https://stophy.dev/dashboard).
+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.
 
-### Option 2: run it locally (stdio)
+### Claude Code
 
-Your MCP client runs `@stophy/mcp` as a local process. The API key goes in the environment.
+To sign in with your browser, add the server, then run `/mcp` and choose **Authenticate**:
 
 ```bash
-env STOPHY_API_KEY=$STOPHY_API_KEY npx -y @stophy/mcp
+claude mcp add --transport http stophy https://mcp.stophy.dev/mcp
 ```
 
-Or install it once:
+To use an API key:
 
 ```bash
-npm install -g @stophy/mcp
-env STOPHY_API_KEY=$STOPHY_API_KEY stophy-mcp
+claude mcp add --transport http stophy https://api.stophy.dev/mcp --header "Authorization: Bearer <key>"
 ```
 
-## Client configs
-
-Pick your MCP client.
+To start without a key:
 
-### Claude Desktop
-
-File: `claude_desktop_config.json`
-- macOS: `~/Library/Application Support/Claude/`
-- Windows: `%APPDATA%\Claude\`
-
-```json
-{
-  "mcpServers": {
-    "stophy": {
-      "command": "npx",
-      "args": ["-y", "@stophy/mcp"],
-      "env": {
-        "STOPHY_API_KEY": "your_api_key_here"
-      }
-    }
-  }
-}
+```bash
+claude mcp add --transport http stophy https://api.stophy.dev/mcp
 ```
 
-If Claude Desktop says `spawn npx ENOENT`, Node.js is missing from PATH. Install the LTS from [nodejs.org](https://nodejs.org) and restart Claude Desktop completely.
+### Codex
 
-### Claude Code
-
-Stdio:
+To use the key in your `STOPHY_API_KEY` environment variable:
 
 ```bash
-claude mcp add stophy -e STOPHY_API_KEY=$STOPHY_API_KEY -- npx -y @stophy/mcp
+codex mcp add stophy --url https://api.stophy.dev/mcp --bearer-token-env-var STOPHY_API_KEY
 ```
 
-HTTP (if your Claude Code version supports remote MCP):
+To sign in with your browser instead, add the sign-in URL, then log in:
 
 ```bash
-claude mcp add --transport http stophy https://mcp.stophy.dev/$STOPHY_API_KEY/mcp
+codex mcp add stophy --url https://mcp.stophy.dev/mcp
+codex mcp login stophy
 ```
 
 ### Cursor
 
-File: `.cursor/mcp.json` (per project) or `~/.cursor/mcp.json` (global)
-
-```json
-{
-  "mcpServers": {
-    "stophy": {
-      "command": "npx",
-      "args": ["-y", "@stophy/mcp"],
-      "env": {
-        "STOPHY_API_KEY": "$STOPHY_API_KEY"
-      }
-    }
-  }
-}
-```
-
-### Windsurf
-
-File: `~/.codeium/windsurf/mcp_config.json`
+Use the **Add to Cursor** button above to sign in with your browser, or add this to `.cursor/mcp.json` to use a key:
 
 ```json
 {
   "mcpServers": {
     "stophy": {
-      "command": "npx",
-      "args": ["-y", "@stophy/mcp"],
-      "env": {
-        "STOPHY_API_KEY": "$STOPHY_API_KEY"
-      }
+      "url": "https://api.stophy.dev/mcp",
+      "headers": { "Authorization": "Bearer <key>" }
     }
   }
 }
 ```
 
-### Hermes Agent
-
-Add to `config.yaml` under `mcp_servers`:
-
-```yaml
-mcp_servers:
-  - name: stophy
-    command: npx
-    args: ["-y", "@stophy/mcp"]
-    env:
-      STOPHY_API_KEY: your_api_key_here
-```
-
-### Any other MCP client
-
-If your client takes a command + args + env block, use the pattern above. If it takes a URL, use the hosted endpoint.
-
-## Available tools
-
-Six tools. Each call costs one credit except `stophy_get_credits` which is free.
-
-| Tool | What it does |
-|------|-------------|
-| `stophy_search_videos` | Search YouTube by keyword. Returns videos, channels, playlists, or Shorts with pagination. |
-| `stophy_get_video` | Get details, transcript, comments, comment replies, or live chat for one video. |
-| `stophy_get_channel` | Browse a channel's videos, Shorts, playlists, or about page. |
-| `stophy_get_playlist` | Fetch every video in a playlist. |
-| `stophy_get_suggestions` | YouTube autocomplete for a partial query. |
-| `stophy_get_credits` | Your remaining credit balance. Free. |
-
-## Tool reference
-
-### stophy_search_videos
-
-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.
-
-Arguments:
-- `q` (required): what to search for
-- `type`: `"video"`, `"short"`, `"channel"`, or `"playlist"`
-- `uploadDate`: `"hour"`, `"today"`, `"week"`, `"month"`, or `"year"`
-- `duration`: `"short"`, `"medium"`, or `"long"`
-- `sortBy`: `"relevance"`, `"popularity"`, `"date"`, or `"rating"`
-- `continuationToken`: token from previous response for the next page
-
-```json
-{
-  "q": "typescript tutorial",
-  "uploadDate": "week",
-  "type": "video"
-}
-```
-
-Returns `items[]` and an optional `continuationToken`.
-
-### stophy_get_video
+To start without a key, leave out `headers`.
 
-Get details, transcript, comments, comment replies, or live chat for a known video.
+## Run it as a local server
 
-Arguments:
-- `videoUrl` (required): YouTube video URL or ID
-- `type` (required): `"details"`, `"transcript"`, `"comments"`, or `"livechat"`
-- `sortBy`: `"top"` or `"latest"` for comments
-- `chatType`: `"top"` or `"live"` for live chat
-- `continuationToken`: next page of comments, or a comment's `repliesToken` for replies
+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.
 
-Transcript:
-
-```json
-{
-  "videoUrl": "https://youtube.com/watch?v=d56mG7DezGs",
-  "type": "transcript"
-}
-```
-
-Comments:
-
-```json
-{
-  "videoUrl": "https://youtube.com/watch?v=d56mG7DezGs",
-  "type": "comments",
-  "sortBy": "top"
-}
-```
-
-For comment replies, call again with `type: "comments"` and set `continuationToken` to the comment's `repliesToken`.
-
-### stophy_get_channel
-
-Browse a channel.
-
-Arguments:
-- `channelUrl` (required): channel URL, handle (@username), or channel ID
-- `tab`: `"video"`, `"short"`, `"playlist"`, or `"about"` (default: `"video"`)
-- `sortBy`: `"latest"`, `"popular"`, or `"oldest"` for the video tab
-- `continuationToken`: next page
-
-```json
-{
-  "channelUrl": "https://youtube.com/@t3dotgg",
-  "tab": "video",
-  "sortBy": "latest"
-}
+```bash
+npx -y @stophy/mcp
 ```
 
-The `about` tab returns the channel's country, join date, view count, and links.
+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.
 
-### stophy_get_playlist
-
-All videos in a playlist.
+### Claude Desktop
 
-Arguments:
-- `playlistUrl` (required): playlist URL or ID
-- `continuationToken`: next page
+Add this to `claude_desktop_config.json`, then restart Claude Desktop:
 
 ```json
 {
-  "playlistUrl": "https://youtube.com/playlist?list=PLTjRvDozrdlxEIuOBZkMAK5uiqp8rHUax"
+  "mcpServers": {
+    "stophy": {
+      "command": "npx",
+      "args": ["-y", "@stophy/mcp"],
+      "env": { "STOPHY_API_KEY": "<key>" }
+    }
+  }
 }
 ```
 
-### stophy_get_suggestions
-
-YouTube autocomplete. Good for topic discovery and query expansion.
-
-Arguments:
-- `q` (required): partial query
-- `hl`: language code, default `en`
-- `gl`: region code, default `US`
-
-```json
-{
-  "q": "react hooks",
-  "hl": "en",
-  "gl": "US"
-}
-```
+To start without a key, leave out `env`.
 
+The package needs Node.js 18 or later.
 
-## Pagination
+| Variable         | What it does                                                           |
+| ---------------- | ---------------------------------------------------------------------- |
+| `STOPHY_API_KEY` | Your Stophy API key. Optional.                                         |
+| `STOPHY_MCP_URL` | The server to connect to. The default is `https://api.stophy.dev/mcp`. |
 
-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.
+## Tools
 
-## Empty results
+| Tool                       | What it does                                                                |
+| -------------------------- | --------------------------------------------------------------------------- |
+| `stophy_search_endpoints`  | Finds the endpoint for a task, with its cost                                |
+| `stophy_describe_endpoint` | Shows the input an endpoint takes and what it returns                       |
+| `stophy_call`              | Runs an endpoint with `id`, `input` and optional `fields`, and returns JSON |
 
-When a video has no transcript, comments are off, or a comment has no replies, Stophy returns an `empty` object:
+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.
 
-```json
-{
-  "empty": {
-    "code": "EMPTY_TRANSCRIPT_SEGMENTS",
-    "message": "No transcript segments found."
-  }
-}
-```
+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.
 
-Possible codes: `EMPTY_TRANSCRIPT_SEGMENTS`, `EMPTY_COMMENTS`, `EMPTY_COMMENT_REPLIES`.
+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.
 
-## Errors
+## Network and credentials
 
-Errors come back as text in the MCP tool response:
+- 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.
+- 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`.
+- 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.
+- No telemetry.
 
-```
-Stophy error (UNAUTHORIZED): Invalid API key.
-```
+## More
 
-```
-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.
-```
+- [Stophy docs](https://docs.stophy.dev)
+- [Dashboard and API keys](https://stophy.dev/dashboard)
 
-## Environment variables
+## License
 
-| Variable | Required | What it is |
-|----------|----------|-----------|
-| `STOPHY_API_KEY` | Stdio only | Your Stophy API key. Not needed for hosted — the key is in the URL path. |
+MIT