@stophy/mcp 1.0.0 → 1.0.2

package/README.md

@@ -1,20 +1,59 @@
 # @stophy/mcp
 
-YouTube for AI Agents. Search, transcripts, comments, channels, playlists. All as MCP tool calls.
+MCP server for Stophy's YouTube API.
 
-## Quick start
+Use it to search YouTube, get transcripts, read comments, inspect channels, fetch playlists, get suggestions, and check credits from any MCP-compatible client.
+
+You can connect in two ways:
+
+- **Hosted HTTP MCP**: no install; connect directly to Stophy's hosted MCP server.
+- **Local stdio MCP**: run `@stophy/mcp` locally with your API key in the environment.
+
+## Hosted HTTP MCP
+
+Use the hosted endpoint when your MCP client supports remote HTTP servers:
+
+```text
+https://mcp.stophy.dev/st_YOUR_API_KEY/mcp
+```
+
+Example client config:
+
+```json
+{
+  "mcpServers": {
+    "stophy": {
+      "url": "https://mcp.stophy.dev/st_YOUR_API_KEY/mcp"
+    }
+  }
+}
+```
+
+Your API key is included in the URL path. Get a key from [stophy.dev/dashboard](https://stophy.dev/dashboard).
+
+## Local stdio MCP
+
+Use the local server when your MCP client expects a command instead of a remote URL.
 
 ```bash
 env STOPHY_API_KEY=st_YOUR_API_KEY npx -y @stophy/mcp
 ```
 
-## Setup
+Manual installation:
 
-Get an API key at [stophy.dev/dashboard](https://stophy.dev/dashboard).
+```bash
+npm install -g @stophy/mcp
+env STOPHY_API_KEY=st_YOUR_API_KEY stophy-mcp
+```
+
+## Client setup
 
 ### Claude Desktop
 
-`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows:
+Config file locations:
+
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
 
 ```json
 {
@@ -22,21 +61,33 @@ Get an API key at [stophy.dev/dashboard](https://stophy.dev/dashboard).
     "stophy": {
       "command": "npx",
       "args": ["-y", "@stophy/mcp"],
-      "env": { "STOPHY_API_KEY": "your_api_key_here" }
+      "env": {
+        "STOPHY_API_KEY": "your_api_key_here"
+      }
     }
   }
 }
 ```
 
+If Claude Desktop shows `spawn npx ENOENT`, Node.js is not installed or is not in your PATH. Install the LTS release from [nodejs.org](https://nodejs.org), then fully restart Claude Desktop.
+
 ### Claude Code
 
+Local stdio server:
+
 ```bash
 claude mcp add stophy -e STOPHY_API_KEY=your_api_key -- npx -y @stophy/mcp
 ```
 
+Hosted HTTP server, if your Claude Code version supports remote HTTP MCP:
+
+```bash
+claude mcp add --transport http stophy https://mcp.stophy.dev/st_YOUR_API_KEY/mcp
+```
+
 ### Cursor
 
-`.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` globally:
+Add this to `.cursor/mcp.json` in your project or `~/.cursor/mcp.json` globally:
 
 ```json
 {
@@ -44,7 +95,9 @@ claude mcp add stophy -e STOPHY_API_KEY=your_api_key -- npx -y @stophy/mcp
     "stophy": {
       "command": "npx",
       "args": ["-y", "@stophy/mcp"],
-      "env": { "STOPHY_API_KEY": "your_api_key_here" }
+      "env": {
+        "STOPHY_API_KEY": "your_api_key_here"
+      }
     }
   }
 }
@@ -52,7 +105,7 @@ claude mcp add stophy -e STOPHY_API_KEY=your_api_key -- npx -y @stophy/mcp
 
 ### Windsurf
 
-`~/.codeium/windsurf/mcp_config.json`:
+Add this to `~/.codeium/windsurf/mcp_config.json`:
 
 ```json
 {
@@ -60,7 +113,9 @@ claude mcp add stophy -e STOPHY_API_KEY=your_api_key -- npx -y @stophy/mcp
     "stophy": {
       "command": "npx",
       "args": ["-y", "@stophy/mcp"],
-      "env": { "STOPHY_API_KEY": "your_api_key_here" }
+      "env": {
+        "STOPHY_API_KEY": "your_api_key_here"
+      }
     }
   }
 }
@@ -68,252 +123,147 @@ claude mcp add stophy -e STOPHY_API_KEY=your_api_key -- npx -y @stophy/mcp
 
 ## Tools
 
-### stophy_search_videos
+| Tool | What it does |
+|------|-------------|
+| `stophy_search_videos` | Search YouTube by keyword with optional filters |
+| `stophy_get_video` | Get video details, transcript, comments, or comment replies |
+| `stophy_get_channel` | Browse a channel's videos, Shorts, playlists, or about page |
+| `stophy_get_playlist` | Fetch videos in a playlist |
+| `stophy_get_suggestions` | Get YouTube autocomplete suggestions |
+| `stophy_get_credits` | Check remaining Stophy credits |
 
-Search YouTube by keyword. If you already have a video URL, use `stophy_get_video` instead.
+Each tool call costs one credit. `stophy_get_credits` is free.
 
-**Arguments:**
+## Tool reference
 
-- `q` (required): search query
-- `type`: `"video"` | `"short"` | `"channel"` | `"playlist"`
-- `uploadDate`: `"hour"` | `"today"` | `"week"` | `"month"` | `"year"`
-- `duration`: `"short"` (under 4 min) | `"medium"` (4-20 min) | `"long"` (over 20 min)
-- `sortBy`: `"relevance"` | `"popularity"` | `"date"` | `"rating"`
-- `continuationToken`: from the previous response to get the next page
+### `stophy_search_videos`
 
-**Example:**
+Search YouTube by keyword. Use this when you need to discover videos, channels, playlists, or Shorts for a topic.
 
-```json
-{
-  "name": "stophy_search_videos",
-  "arguments": {
-    "q": "typescript tutorial",
-    "uploadDate": "week",
-    "type": "video"
-  }
-}
-```
+Arguments:
 
-**Returns:**
+- `q` (required): search query
+- `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 a previous response for the next page
+
+Example:
 
 ```json
 {
-  "items": [
-    {
-      "type": "video",
-      "id": "zxRUQ9foH5w",
-      "videoUrl": "https://youtube.com/watch?v=zxRUQ9foH5w",
-      "title": "Running JavaScript in TypeScript React",
-      "author": "Nexion Analytics",
-      "viewCount": 6,
-      "duration": "4:41",
-      "publishedAt": "2026-05-30T13:52:55.499Z"
-    }
-  ],
-  "continuationToken": "4qmFsgJ..."
+  "q": "typescript tutorial",
+  "uploadDate": "week",
+  "type": "video"
 }
 ```
 
----
+Returns search results with `items[]` and an optional `continuationToken`.
 
-### stophy_get_video
+### `stophy_get_video`
 
-Get details, transcript, or comments for a video. If you're looking for videos on a topic, use `stophy_search_videos` instead.
+Get details, transcript, comments, or replies for a known YouTube video.
 
-**Arguments:**
+Arguments:
 
-- `videoUrl` (required): YouTube video URL
-- `type` (required): `"details"` | `"transcript"` | `"comments"`
-- `sortBy`: `"top"` | `"latest"` — for comments only
-- `continuationToken`: next page of comments, or a comment's `repliesToken` to fetch its replies
+- `videoUrl` (required): YouTube video URL or ID
+- `type` (required): `"details"`, `"transcript"`, or `"comments"`
+- `sortBy`: `"top"` or `"latest"` for comments
+- `continuationToken`: next comments page, or a comment `repliesToken` to fetch replies
 
-**Example:**
+Transcript example:
 
 ```json
 {
-  "name": "stophy_get_video",
-  "arguments": {
-    "videoUrl": "https://youtube.com/watch?v=d56mG7DezGs",
-    "type": "transcript"
-  }
+  "videoUrl": "https://youtube.com/watch?v=d56mG7DezGs",
+  "type": "transcript"
 }
 ```
 
-**Returns (transcript):**
+Comments example:
 
 ```json
 {
-  "videoId": "d56mG7DezGs",
-  "language": { "code": "en", "name": "en", "isAutoGenerated": true },
-  "segments": [
-    { "text": "welcome to the ultimate typescript", "start": 2.08, "duration": 3.6 }
-  ]
+  "videoUrl": "https://youtube.com/watch?v=d56mG7DezGs",
+  "type": "comments",
+  "sortBy": "top"
 }
 ```
 
-**Returns (comments):**
+To read replies, call `stophy_get_video` again with `type: "comments"` and set `continuationToken` to the comment's `repliesToken`.
 
-```json
-{
-  "videoId": "d56mG7DezGs",
-  "sortBy": "top",
-  "items": [
-    {
-      "id": "UgwfjLGxYnE9fEmwwxR4AaABAg",
-      "text": "This was honestly just the right amount of information...",
-      "author": "@Ramkatral",
-      "likeCount": 145,
-      "replyCount": 5,
-      "repliesToken": "Eg0SC2Q1Nm1HN0RlekdzGA..."
-    }
-  ],
-  "continuationToken": "4qmFsgJ..."
-}
-```
+### `stophy_get_channel`
 
-To read replies, call again with `type: "comments"` and `continuationToken` set to the comment's `repliesToken`.
+Browse a channel's content or profile.
 
----
+Arguments:
 
-### stophy_get_channel
+- `channelUrl` (required): channel URL, handle, or channel ID
+- `tab`: `"video"`, `"short"`, `"playlist"`, or `"about"`; defaults to `"video"`
+- `sortBy`: `"latest"`, `"popular"`, or `"oldest"` for the video tab
+- `continuationToken`: token from a previous response for the next page
 
-Browse a channel's content. If you have a specific video URL, use `stophy_get_video` instead.
-
-**Arguments:**
-
-- `channelUrl` (required): `youtube.com/@handle` or `youtube.com/channel/UCxxx`
-- `tab`: `"video"` (default) | `"short"` | `"playlist"` | `"about"`
-- `sortBy`: `"latest"` | `"popular"` | `"oldest"` — video tab only
-- `continuationToken`: from the previous response to get the next page
-
-**Example:**
+Example:
 
 ```json
 {
-  "name": "stophy_get_channel",
-  "arguments": {
-    "channelUrl": "https://youtube.com/@t3dotgg",
-    "tab": "video",
-    "sortBy": "latest"
-  }
-}
-```
-
-**Returns:**
-
-```json
-{
-  "channel": {
-    "name": "Theo - t3.gg",
-    "handle": "@t3dotgg",
-    "subscriberCount": "539K subscribers",
-    "isVerified": true
-  },
+  "channelUrl": "https://youtube.com/@t3dotgg",
   "tab": "video",
-  "items": [
-    {
-      "videoUrl": "https://youtube.com/watch?v=_goOUJkkxUk",
-      "title": "Anthropic fights back",
-      "viewCount": 119000,
-      "duration": "28:03"
-    }
-  ],
-  "continuationToken": "4qmFsgLdCBIYVUNiUlAzYzc1N2xXZz..."
+  "sortBy": "latest"
 }
 ```
 
-The `about` tab returns the full profile — `country`, `joinedDate`, `viewCount`, `links[]` — but no `items` or `continuationToken`.
-
----
-
-### stophy_get_playlist
-
-Get all videos in a playlist.
+The `about` tab returns profile details such as country, joined date, view count, and links.
 
-**Arguments:**
+### `stophy_get_playlist`
 
-- `playlistUrl` (required): `youtube.com/playlist?list=PLxxx`
-- `continuationToken`: from the previous response to get the next page
+Fetch videos from a playlist.
 
-**Example:**
+Arguments:
 
-```json
-{
-  "name": "stophy_get_playlist",
-  "arguments": {
-    "playlistUrl": "https://youtube.com/playlist?list=PLTjRvDozrdlxEIuOBZkMAK5uiqp8rHUax"
-  }
-}
-```
+- `playlistUrl` (required): playlist URL or ID
+- `continuationToken`: token from a previous response for the next page
 
-**Returns:**
+Example:
 
 ```json
 {
-  "playlist": {
-    "title": "JavaScript Tutorials",
-    "author": "Programming with Mosh",
-    "videoCount": "25"
-  },
-  "items": [
-    {
-      "videoUrl": "https://youtube.com/watch?v=upDLs1sn7g4",
-      "title": "What is JavaScript?",
-      "duration": "5:12",
-      "viewCount": 987000
-    }
-  ],
-  "continuationToken": "4qmFsgJ..."
+  "playlistUrl": "https://youtube.com/playlist?list=PLTjRvDozrdlxEIuOBZkMAK5uiqp8rHUax"
 }
 ```
 
----
-
-### stophy_get_suggestions
+### `stophy_get_suggestions`
 
-YouTube autocomplete for a partial query.
+Get YouTube autocomplete suggestions for a partial query.
 
-**Arguments:**
+Arguments:
 
 - `q` (required): partial query
-- `hl`: language code, e.g. `en`, `fr`. Defaults to `en`
-- `gl`: country code, e.g. `US`, `GB`. Defaults to `US`
+- `hl`: language code, for example `en`; defaults to `en`
+- `gl`: region code, for example `US`; defaults to `US`
 
-**Example:**
+Example:
 
 ```json
 {
-  "name": "stophy_get_suggestions",
-  "arguments": { "q": "react hooks", "hl": "en", "gl": "US" }
+  "q": "react hooks",
+  "hl": "en",
+  "gl": "US"
 }
 ```
 
-**Returns:**
+### `stophy_get_credits`
 
-```json
-{
-  "suggestions": [
-    "react hooks",
-    "react hooks explained",
-    "react hooks tutorial"
-  ]
-}
-```
-
----
-
-### stophy_get_credits
+Check your remaining credit balance. This tool does not consume a credit.
 
-Check your credit balance. Doesn't cost a credit.
+Example:
 
 ```json
-{
-  "name": "stophy_get_credits",
-  "arguments": {}
-}
+{}
 ```
 
-**Returns:**
+Returns:
 
 ```json
 {
@@ -321,15 +271,13 @@ Check your credit balance. Doesn't cost a credit.
 }
 ```
 
----
-
 ## Pagination
 
-Any tool that returns `continuationToken` can be paged. Pass it back in the next call with the same arguments. When it's `null`, you're at the end.
+Tools that return `continuationToken` can be paged. Pass the token back in the next call with the same arguments. When the token is missing or `null`, there is no next page.
 
-## When there's no data
+## Empty results
 
-If a video has no transcript, comments are turned off, or there are no replies, you get a `200` with `empty` instead of items:
+If a video has no transcript, comments are turned off, or a comment has no replies, Stophy returns an `empty` object instead of items:
 
 ```json
 {
@@ -340,25 +288,29 @@ If a video has no transcript, comments are turned off, or there are no replies,
 }
 ```
 
-Possible codes: `EMPTY_TRANSCRIPT_SEGMENTS`, `EMPTY_COMMENTS`, `EMPTY_COMMENT_REPLIES`.
+Possible empty-result codes:
+
+- `EMPTY_TRANSCRIPT_SEGMENTS`
+- `EMPTY_COMMENTS`
+- `EMPTY_COMMENT_REPLIES`
 
 ## Errors
 
-Errors come back as plain text in the tool response:
+Errors are returned as text in the MCP tool response:
 
-```
+```text
 Stophy error (UNAUTHORIZED): Invalid API key.
 ```
 
-```
-Stophy error (MISSING_API_KEY): STOPHY_API_KEY environment variable is not set. Get a key at https://stophy.dev/dashboard.
+```text
+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.
 ```
 
 ## Environment variables
 
 | Variable | Required | Description |
 |----------|----------|-------------|
-| `STOPHY_API_KEY` | Yes | Your Stophy API key from stophy.dev/dashboard |
+| `STOPHY_API_KEY` | Local stdio only | Your Stophy API key. Not needed for the hosted endpoint because the key is included in the URL path. |
 
 ## License