@stophy/mcp 1.0.0

package/README.md

@@ -0,0 +1,365 @@
+# @stophy/mcp
+
+YouTube for AI Agents. Search, transcripts, comments, channels, playlists. All as MCP tool calls.
+
+## Quick start
+
+```bash
+env STOPHY_API_KEY=st_YOUR_API_KEY npx -y @stophy/mcp
+```
+
+## Setup
+
+Get an API key at [stophy.dev/dashboard](https://stophy.dev/dashboard).
+
+### Claude Desktop
+
+`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows:
+
+```json
+{
+  "mcpServers": {
+    "stophy": {
+      "command": "npx",
+      "args": ["-y", "@stophy/mcp"],
+      "env": { "STOPHY_API_KEY": "your_api_key_here" }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add stophy -e STOPHY_API_KEY=your_api_key -- npx -y @stophy/mcp
+```
+
+### Cursor
+
+`.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` globally:
+
+```json
+{
+  "mcpServers": {
+    "stophy": {
+      "command": "npx",
+      "args": ["-y", "@stophy/mcp"],
+      "env": { "STOPHY_API_KEY": "your_api_key_here" }
+    }
+  }
+}
+```
+
+### Windsurf
+
+`~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "stophy": {
+      "command": "npx",
+      "args": ["-y", "@stophy/mcp"],
+      "env": { "STOPHY_API_KEY": "your_api_key_here" }
+    }
+  }
+}
+```
+
+## Tools
+
+### stophy_search_videos
+
+Search YouTube by keyword. If you already have a video URL, use `stophy_get_video` instead.
+
+**Arguments:**
+
+- `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
+
+**Example:**
+
+```json
+{
+  "name": "stophy_search_videos",
+  "arguments": {
+    "q": "typescript tutorial",
+    "uploadDate": "week",
+    "type": "video"
+  }
+}
+```
+
+**Returns:**
+
+```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..."
+}
+```
+
+---
+
+### 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.
+
+**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
+
+**Example:**
+
+```json
+{
+  "name": "stophy_get_video",
+  "arguments": {
+    "videoUrl": "https://youtube.com/watch?v=d56mG7DezGs",
+    "type": "transcript"
+  }
+}
+```
+
+**Returns (transcript):**
+
+```json
+{
+  "videoId": "d56mG7DezGs",
+  "language": { "code": "en", "name": "en", "isAutoGenerated": true },
+  "segments": [
+    { "text": "welcome to the ultimate typescript", "start": 2.08, "duration": 3.6 }
+  ]
+}
+```
+
+**Returns (comments):**
+
+```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..."
+}
+```
+
+To read replies, call again with `type: "comments"` and `continuationToken` set to the comment's `repliesToken`.
+
+---
+
+### stophy_get_channel
+
+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:**
+
+```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
+  },
+  "tab": "video",
+  "items": [
+    {
+      "videoUrl": "https://youtube.com/watch?v=_goOUJkkxUk",
+      "title": "Anthropic fights back",
+      "viewCount": 119000,
+      "duration": "28:03"
+    }
+  ],
+  "continuationToken": "4qmFsgLdCBIYVUNiUlAzYzc1N2xXZz..."
+}
+```
+
+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.
+
+**Arguments:**
+
+- `playlistUrl` (required): `youtube.com/playlist?list=PLxxx`
+- `continuationToken`: from the previous response to get the next page
+
+**Example:**
+
+```json
+{
+  "name": "stophy_get_playlist",
+  "arguments": {
+    "playlistUrl": "https://youtube.com/playlist?list=PLTjRvDozrdlxEIuOBZkMAK5uiqp8rHUax"
+  }
+}
+```
+
+**Returns:**
+
+```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..."
+}
+```
+
+---
+
+### stophy_get_suggestions
+
+YouTube autocomplete for a partial query.
+
+**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`
+
+**Example:**
+
+```json
+{
+  "name": "stophy_get_suggestions",
+  "arguments": { "q": "react hooks", "hl": "en", "gl": "US" }
+}
+```
+
+**Returns:**
+
+```json
+{
+  "suggestions": [
+    "react hooks",
+    "react hooks explained",
+    "react hooks tutorial"
+  ]
+}
+```
+
+---
+
+### stophy_get_credits
+
+Check your credit balance. Doesn't cost a credit.
+
+```json
+{
+  "name": "stophy_get_credits",
+  "arguments": {}
+}
+```
+
+**Returns:**
+
+```json
+{
+  "credits": 39152
+}
+```
+
+---
+
+## 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.
+
+## When there's no data
+
+If a video has no transcript, comments are turned off, or there are no replies, you get a `200` with `empty` instead of items:
+
+```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 plain text in the tool response:
+
+```
+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.
+```
+
+## Environment variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `STOPHY_API_KEY` | Yes | Your Stophy API key from stophy.dev/dashboard |
+
+## License
+
+MIT