wordtube
README.md
# wordtube
Learn a language from real video, without leaving your MCP client. wordtube is a small local forwarding client for the hosted LingoDew service: it answers `tools/list` on your own machine from the captured tool definitions and forwards every lookup upstream, returning the results exactly as the service sends them back.
The surface is read-only catalogue data for Japanese and English learners: videos matched by level, topic and keywords, statistics on how a word is actually used across a video corpus, measured stats for YouTube channels in the library, and basic product facts. Nothing is cached or computed locally — the package is a pipe, not a catalogue.
## The tools
- **`find_videos`** — Find real YouTube videos for learning Japanese or English. `language` is required (`"japanese"` or `"english"`). Optional filters: `level` (JLPT N5–N1 for Japanese, CEFR A1–C2 for English), `topic` such as Food or Travel, `query` matched against video titles and channel names, and `limit` (1–25, default 10). Results include titles, channels, levels and links to video pages with tappable subtitles.
- **`word_in_videos`** — How often a word is heard across the video corpus: number of videos, total occurrences, coverage, frequency rank and level, plus a word page with native-audio examples. Both `language` and `word` are required; for Japanese the word may be a headword, kana reading or romaji.
- **`channel_stats`** — Measured stats for a YouTube channel in the library: its video count, and per level its speaking speed, rank among channels at that level, share of its videos and main topics. Both `language` and `channel` are required; the channel may be given as a name, channel id or URL.
- **`about_lingodew`** — Product facts about LingoDew itself: features, platforms, pricing and the free tier. Takes no arguments.
## Install and run
As an MCP server via npm:
```bash
npx -y @reneturcios/wordtube mcp
```
MCP client configuration:
```json
{
"mcpServers": {
"wordtube": {
"command": "npx",
"args": ["-y", "@reneturcios/wordtube", "mcp"]
}
}
}
```
As a container:
```bash
docker run -i ghcr.io/cloudcorprecords/wordtube
docker run --rm ghcr.io/cloudcorprecords/wordtube find_videos '{"language":"japanese","level":"N5"}'
```
## CLI
One binary serves both the command line and the MCP server. Each tool is a subcommand taking a single JSON string with that tool's arguments:
```bash
wordtube find_videos '{"language":"english","topic":"Food"}'
wordtube word_in_videos '{"language":"japanese","word":"食べる"}'
wordtube channel_stats '{"language":"english","channel":"Some Channel"}'
wordtube about_lingodew '{}'
wordtube --version
```
Exit codes: `0` when the forwarded call succeeds, `1` when the upstream result is an error, and `2` for usage problems such as an unknown subcommand or a malformed JSON argument.
## Configuration
- `LINGODEW_MCP_URL` — Overrides the upstream endpoint. The default is the pinned hosted endpoint, `https://www.lingodew.com/mcp`. (The override variable is a reconstruction added by this rebuild.)
The LingoDew registry record declares no headers on its remote, so wordtube sends no authentication header of any kind — lookups are keyless.
Upstream failures — a JSON-RPC error from the service, a non-2xx response, an unreadable body, or a request that fails outright — are reported to the caller as an error result whose text starts with `wordtube error:`.
## How forwarding works
The first forwarded call opens a session: an `initialize` request (protocol version `2025-03-26`), followed by a `notifications/initialized` notification, then the `tools/call` itself. If the service answers the initialize request with an `Mcp-Session-Id` header, that value is carried on every later request, and the open session is reused for the rest of the process. Replies are accepted either as plain JSON or as server-sent events. Successful results pass through verbatim, including any `isError` flag and any extra fields the service includes.
## Development
```bash
npm install
npm run build # tsc -> dist/ (dist/cli.js is the bin)
npm test # tsx --test test/*.test.ts — stubbed upstream, no network
npm run dev # run the CLI from source
```
The test suite checks the served tool list against the captured surface, exercises the session handshake and its reuse, asserts that no `Authorization` header is sent under any environment, and verifies that arguments go upstream untouched and results come back untouched.
## License
MIT — see `LICENSE`. Copyright (c) 2026 Rene Turcios.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues