@stophy/mcp 1.0.5 → 2.0.0

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,111 +1,84 @@
-# @stophy/mcp
+# Stophy MCP
 
-YouTube data for AI agents. Transcripts, comments, search, channels, playlists — all as structured JSON through the Model Context Protocol.
+Give your AI agent public web data: web search, YouTube, Reddit, TikTok, Instagram, LinkedIn, maps, shopping, jobs, real estate, finance, and more. Your agent reaches every Stophy endpoint through three MCP tools.
 
-## How to connect
+## Connect to the hosted server
 
-Two ways. Pick one.
+Most apps can connect to the hosted server directly. There is nothing to install.
 
-### Option 1: hosted HTTP (zero install)
+| URL | How you connect | What your agent can use |
+| --- | --- | --- |
+| `https://api.stophy.dev/mcp` | No key | The free endpoints: web search, YouTube search, and YouTube transcripts |
+| `https://api.stophy.dev/mcp` | `Authorization: Bearer <key>` header | Every endpoint |
+| `https://api.stophy.dev/mcp-oauth` | Sign in with your browser | Every endpoint |
 
-Give your MCP client this URL. Your API key goes in the path.
+Get an API key at [stophy.dev/signup](https://stophy.dev/signup).
 
-```
-https://mcp.stophy.dev/$STOPHY_API_KEY/mcp
-```
+### Claude Code
 
-MCP client config:
+To sign in with your browser, add the server, then run `/mcp` and choose **Authenticate**:
 
-```json
-{
-  "mcpServers": {
-    "stophy": {
-      "url": "https://mcp.stophy.dev/$STOPHY_API_KEY/mcp"
-    }
-  }
-}
+```bash
+claude mcp add --transport http stophy https://api.stophy.dev/mcp-oauth
 ```
 
-No install. No Node.js. Works anywhere that speaks HTTP MCP.
+To use an API key:
 
-Get an API key at [stophy.dev/dashboard](https://stophy.dev/dashboard).
-
-### Option 2: run it locally (stdio)
+```bash
+claude mcp add --transport http stophy https://api.stophy.dev/mcp --header "Authorization: Bearer <key>"
+```
 
-Your MCP client runs `@stophy/mcp` as a local process. The API key goes in the environment.
+To start without a key:
 
 ```bash
-env STOPHY_API_KEY=$STOPHY_API_KEY npx -y @stophy/mcp
+claude mcp add --transport http stophy https://api.stophy.dev/mcp
 ```
 
-Or install it once:
+### Codex
+
+To use the key in your `STOPHY_API_KEY` environment variable:
 
 ```bash
-npm install -g @stophy/mcp
-env STOPHY_API_KEY=$STOPHY_API_KEY stophy-mcp
+codex mcp add stophy --url https://api.stophy.dev/mcp --bearer-token-env-var STOPHY_API_KEY
 ```
 
-## Client configs
+To sign in with your browser instead, add the sign-in URL, then log in:
 
-Pick your MCP client.
+```bash
+codex mcp add stophy --url https://api.stophy.dev/mcp-oauth
+codex mcp login stophy
+```
 
-### Claude Desktop
+### Cursor
 
-File: `claude_desktop_config.json`
-- macOS: `~/Library/Application Support/Claude/`
-- Windows: `%APPDATA%\Claude\`
+Add this to `.cursor/mcp.json`:
 
 ```json
 {
   "mcpServers": {
     "stophy": {
-      "command": "npx",
-      "args": ["-y", "@stophy/mcp"],
-      "env": {
-        "STOPHY_API_KEY": "your_api_key_here"
-      }
+      "url": "https://api.stophy.dev/mcp",
+      "headers": { "Authorization": "Bearer <key>" }
     }
   }
 }
 ```
 
-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.
+To start without a key, leave out `headers`.
 
-### Claude Code
+## Run it as a local server
 
-Stdio:
+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.
 
 ```bash
-claude mcp add stophy -e STOPHY_API_KEY=$STOPHY_API_KEY -- npx -y @stophy/mcp
+npx -y @stophy/mcp
 ```
 
-HTTP (if your Claude Code version supports remote MCP):
-
-```bash
-claude mcp add --transport http stophy https://mcp.stophy.dev/$STOPHY_API_KEY/mcp
-```
-
-### Cursor
-
-File: `.cursor/mcp.json` (per project) or `~/.cursor/mcp.json` (global)
+With `STOPHY_API_KEY` set, your agent can use every endpoint. Without it, your agent gets the free endpoints.
 
-```json
-{
-  "mcpServers": {
-    "stophy": {
-      "command": "npx",
-      "args": ["-y", "@stophy/mcp"],
-      "env": {
-        "STOPHY_API_KEY": "$STOPHY_API_KEY"
-      }
-    }
-  }
-}
-```
-
-### Windsurf
+### Claude Desktop
 
-File: `~/.codeium/windsurf/mcp_config.json`
+Add this to `claude_desktop_config.json`, then restart Claude Desktop:
 
 ```json
 {
@@ -113,185 +86,36 @@ File: `~/.codeium/windsurf/mcp_config.json`
     "stophy": {
       "command": "npx",
       "args": ["-y", "@stophy/mcp"],
-      "env": {
-        "STOPHY_API_KEY": "$STOPHY_API_KEY"
-      }
+      "env": { "STOPHY_API_KEY": "<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
+To start without a key, leave out `env`.
 
-If your client takes a command + args + env block, use the pattern above. If it takes a URL, use the hosted endpoint.
+The package needs Node.js 18 or later.
 
-## Available tools
+| 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`. |
 
-Six tools. Each call costs one credit except `stophy_get_credits` which is free.
+## Tools
 
 | 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
-
-Get details, transcript, comments, comment replies, or live chat for a known video.
+| --- | --- |
+| `stophy_search_endpoints` | Finds the endpoint for a task, with its cost |
+| `stophy_describe_endpoint` | Shows the input an endpoint takes and whether it has more pages |
+| `stophy_call` | Runs an endpoint and returns markdown, or JSON when you ask for it |
 
-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
+Your agent usually searches, then describes, then calls. Each result says how many credits it used.
 
-Transcript:
+## More
 
-```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"
-}
-```
-
-The `about` tab returns the channel's country, join date, view count, and links.
-
-### stophy_get_playlist
-
-All videos in a playlist.
-
-Arguments:
-- `playlistUrl` (required): playlist URL or ID
-- `continuationToken`: next page
-
-```json
-{
-  "playlistUrl": "https://youtube.com/playlist?list=PLTjRvDozrdlxEIuOBZkMAK5uiqp8rHUax"
-}
-```
-
-### 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"
-}
-```
-
-
-## Pagination
-
-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.
-
-## Empty results
-
-When a video has no transcript, comments are off, or a comment has no replies, Stophy returns an `empty` object:
-
-```json
-{
-  "empty": {
-    "code": "EMPTY_TRANSCRIPT_SEGMENTS",
-    "message": "No transcript segments found."
-  }
-}
-```
-
-Possible codes: `EMPTY_TRANSCRIPT_SEGMENTS`, `EMPTY_COMMENTS`, `EMPTY_COMMENT_REPLIES`.
-
-## Errors
-
-Errors come back as text in the MCP tool response:
-
-```
-Stophy error (UNAUTHORIZED): Invalid API key.
-```
-
-```
-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