ytb-tools 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aliildan
+
+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

@@ -0,0 +1,143 @@
+# 🎬 ytb-tools
+
+[![npm version](https://img.shields.io/npm/v/ytb-tools.svg)](https://www.npmjs.com/package/ytb-tools)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**Search YouTube, pull transcripts, and get AI summaries — right inside Claude and any other MCP client.**
+
+ytb-tools is a [Model Context Protocol](https://modelcontextprotocol.io) server that turns YouTube into something your AI assistant can actually work with. Ask it to find videos, grab a transcript, or summarize a talk — it just works.
+
+> ✨ **Zero setup.** No API keys. No Google account. No manual installs. ytb-tools provisions everything it needs on its own.
+
+---
+
+## What you can do
+
+- 🔎 **Search YouTube** — "find me the top React 19 talks" → ranked results with titles, channels, durations, and views.
+- 📝 **Get transcripts** — full transcripts in the video's language (or any available caption track), saved to a tidy local library.
+- 🧠 **Summarize videos** — TL;DR, structured notes, or a deep dive — written by Claude, in the video's own language.
+- 💾 **Builds your library** — every transcript and summary is auto-saved as clean files you can browse, search, and keep.
+
+---
+
+## Quick start
+
+### Any MCP client (Claude Desktop, Cursor, Cline, …)
+
+Add this to your client's MCP config — that's the whole install:
+
+```json
+{
+  "mcpServers": {
+    "ytb-tools": {
+      "command": "npx",
+      "args": ["-y", "ytb-tools"]
+    }
+  }
+}
+```
+
+Then just ask:
+
+> *"Search YouTube for the best intro to Rust, then summarize the top result."*
+
+### Claude Code (plugin)
+
+Install it as a plugin to get the slash commands. Run these inside Claude Code:
+
+```text
+/plugin marketplace add aliildan/ytb-tools
+/plugin install ytb-tools@ytb-tools
+```
+
+The first command registers this repo as a marketplace; the second installs the plugin (which pulls in the MCP server via `npx` and adds the slash commands). Prefer a menu? Just run `/plugin`.
+
+You then get three commands:
+
+| Command | What it does |
+|---|---|
+| `/yt-search <query>` | List ranked search results |
+| `/yt-transcript <url\|id> [lang]` | Fetch a transcript |
+| `/yt-summary <url\|id> [quick\|standard\|detailed]` | Summarize at the depth you want |
+
+`/yt-summary` automatically picks the right model for the job — **quick → Haiku**, **standard → Sonnet**, **detailed → Opus** — and writes the summary in the video's language.
+
+#### Updating the plugin
+
+When a new version ships, refresh the marketplace catalog and update:
+
+```text
+/plugin marketplace update ytb-tools
+/plugin update ytb-tools
+```
+
+#### Uninstalling
+
+```text
+/plugin uninstall ytb-tools@ytb-tools
+```
+
+> **Scripting it?** The same actions work non-interactively from your shell:
+> ```bash
+> claude plugin marketplace add aliildan/ytb-tools
+> claude plugin install ytb-tools@ytb-tools
+> ```
+
+---
+
+## Research a whole topic at once
+
+Installed in Claude Code, the **`yt-research`** skill chains everything together. Just ask in plain language:
+
+> *"Research the top 30 YouTube videos on 'rust async' and give me a digest."*
+
+It searches, pulls each transcript, summarizes each (defaulting to quick/Haiku to keep big batches cheap), and produces a **combined digest** — recurring themes, a ranked "start here" shortlist, and any videos it had to skip. For large runs it **confirms with you first** and processes in batches with progress updates.
+
+## Your library
+
+Everything is saved automatically (default `~/ytb-tools/`):
+
+```
+~/ytb-tools/
+├── transcripts/
+│   ├── dQw4w9WgXcQ.en.json      # timestamped segments
+│   └── dQw4w9WgXcQ.en.txt       # plain text
+└── summaries/
+    └── dQw4w9WgXcQ.standard.md  # Markdown with title, url, model, date
+```
+
+Want them somewhere else? Set `YT_OUTPUT_DIR`.
+
+---
+
+## The tools
+
+| Tool | Does |
+|---|---|
+| `youtube_search` | Search YouTube and return ranked video results |
+| `youtube_get_transcript` | Extract a transcript (with language selection), auto-saved |
+| `youtube_save_summary` | Save a generated summary to your library |
+
+---
+
+## Configuration
+
+All optional:
+
+| Variable | Purpose | Default |
+|---|---|---|
+| `YT_OUTPUT_DIR` | Where transcripts & summaries are saved | `~/ytb-tools` |
+| `YT_CACHE_DIR` | Cache location | OS cache dir |
+| `YT_DLP_PATH` | Use an existing yt-dlp instead of the bundled one | auto |
+
+---
+
+## How it works (the short version)
+
+Search runs entirely in-process via [`youtubei.js`](https://github.com/LuanRT/YouTube.js) — no key, no quotas. Transcripts are powered by [yt-dlp](https://github.com/yt-dlp/yt-dlp), which ytb-tools **downloads and manages for you automatically** the first time you need it (it reuses the Node runtime that's already running — no Python, no Deno). Summaries are written by your assistant's own model, so there's no extra API bill.
+
+---
+
+## License
+
+MIT © aliildan

package/dist/index.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { searchInput, handleSearch } from "./tools/search.js";
+import { transcriptInput, handleTranscript } from "./tools/transcript.js";
+import { saveSummaryInput, handleSaveSummary } from "./tools/saveSummary.js";
+function ok(data) {
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+function fail(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { content: [{ type: "text", text: message }], isError: true };
+}
+const server = new McpServer({ name: "ytb-tools", version: "0.1.0" });
+server.registerTool("youtube_search", { description: "Search YouTube and return ranked video results.", inputSchema: searchInput }, async (args) => {
+    try {
+        return ok(await handleSearch(args));
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+server.registerTool("youtube_get_transcript", {
+    description: "Fetch a video's transcript via yt-dlp (cache-aware) and auto-save it to the library. " +
+        "May trigger a one-time yt-dlp download on first use.",
+    inputSchema: transcriptInput,
+}, async (args) => {
+    try {
+        return ok(await handleTranscript(args));
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+server.registerTool("youtube_save_summary", {
+    description: "Persist a host-generated summary to the library as Markdown with frontmatter.",
+    inputSchema: saveSummaryInput,
+}, async (args) => {
+    try {
+        return ok(await handleSaveSummary(args));
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/library/cache.js

@@ -0,0 +1,20 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { cacheDir } from "./paths.js";
+function cacheFile(videoId, key, env) {
+    return path.join(cacheDir(env), "transcripts", `${videoId}.${key}.json`);
+}
+export async function readCachedTranscript(videoId, key, env = process.env) {
+    try {
+        const raw = await fs.readFile(cacheFile(videoId, key, env), "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeCachedTranscript(t, key, env = process.env) {
+    const file = cacheFile(t.videoId, key, env);
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.writeFile(file, JSON.stringify(t), "utf8");
+}

package/dist/library/paths.js

@@ -0,0 +1,29 @@
+import os from "node:os";
+import path from "node:path";
+import envPaths from "env-paths";
+export function expandHome(p) {
+    if (p === "~")
+        return os.homedir();
+    if (p.startsWith("~/") || p.startsWith("~\\")) {
+        return path.join(os.homedir(), p.slice(2));
+    }
+    return p;
+}
+export function outputDir(env = process.env) {
+    const override = env.YT_OUTPUT_DIR?.trim();
+    if (override)
+        return path.resolve(expandHome(override));
+    return path.join(os.homedir(), "ytb-tools");
+}
+export function cacheDir(env = process.env) {
+    const override = env.YT_CACHE_DIR?.trim();
+    if (override)
+        return path.resolve(expandHome(override));
+    return envPaths("ytb-tools", { suffix: "" }).cache;
+}
+export function transcriptsDir(env = process.env) {
+    return path.join(outputDir(env), "transcripts");
+}
+export function summariesDir(env = process.env) {
+    return path.join(outputDir(env), "summaries");
+}

package/dist/library/save.js

@@ -0,0 +1,41 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { transcriptsDir, summariesDir } from "./paths.js";
+export function slugify(s) {
+    const out = s
+        .toLowerCase()
+        .normalize("NFKD")
+        .replace(/[^\p{Letter}\p{Number}]+/gu, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 60);
+    return out || "untitled";
+}
+export async function saveTranscript(t, env = process.env) {
+    const dir = transcriptsDir(env);
+    await fs.mkdir(dir, { recursive: true });
+    const base = `${t.videoId}.${t.language}`;
+    const jsonPath = path.join(dir, `${base}.json`);
+    const txtPath = path.join(dir, `${base}.txt`);
+    await fs.writeFile(jsonPath, JSON.stringify(t, null, 2), "utf8");
+    await fs.writeFile(txtPath, t.fullText, "utf8");
+    return { jsonPath, txtPath };
+}
+export async function saveSummary(videoId, summary, meta, env = process.env) {
+    const dir = summariesDir(env);
+    await fs.mkdir(dir, { recursive: true });
+    const file = path.join(dir, `${videoId}.${meta.style}.md`);
+    const frontmatter = [
+        "---",
+        `title: ${JSON.stringify(meta.title)}`,
+        `url: ${meta.url}`,
+        `videoId: ${videoId}`,
+        `model: ${meta.model}`,
+        `style: ${meta.style}`,
+        `language: ${meta.language}`,
+        `date: ${new Date().toISOString()}`,
+        "---",
+        "",
+    ].join("\n");
+    await fs.writeFile(file, frontmatter + summary + "\n", "utf8");
+    return file;
+}

package/dist/tools/saveSummary.js

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import { saveSummary } from "../library/save.js";
+export const saveSummaryInput = {
+    videoId: z.string().min(1).describe("11-character video ID"),
+    summary: z.string().min(1).describe("The summary text produced by the host model"),
+    style: z.enum(["quick", "standard", "detailed"]).default("standard"),
+    title: z.string().default("").describe("Video title"),
+    url: z.string().default("").describe("Video URL"),
+    model: z.string().default("").describe("Model that produced the summary"),
+    language: z.string().default("").describe("Summary language (BCP-47)"),
+};
+export async function handleSaveSummary(args, env = process.env) {
+    const savedTo = await saveSummary(args.videoId, args.summary, {
+        title: args.title ?? "",
+        url: args.url ?? "",
+        model: args.model ?? "",
+        language: args.language ?? "",
+        style: args.style ?? "standard",
+    }, env);
+    return { savedTo };
+}

package/dist/tools/search.js

@@ -0,0 +1,11 @@
+import { z } from "zod";
+import { searchVideos } from "../youtube/search.js";
+export const searchInput = {
+    query: z.string().min(1).describe("Search query"),
+    limit: z.number().int().min(1).max(200).default(10).describe("Maximum results (paginated)"),
+    type: z.enum(["video", "channel", "playlist"]).default("video").describe("Result type"),
+};
+export async function handleSearch(args) {
+    const results = await searchVideos(args.query, { limit: args.limit, type: args.type });
+    return { count: results.length, results };
+}

package/dist/tools/transcript.js

@@ -0,0 +1,27 @@
+import { z } from "zod";
+import { parseVideoId } from "../youtube/url.js";
+import { fetchTranscript } from "../youtube/transcript.js";
+import { readCachedTranscript, writeCachedTranscript } from "../library/cache.js";
+import { saveTranscript } from "../library/save.js";
+export const transcriptInput = {
+    video: z.string().min(1).describe("YouTube URL or 11-character video ID"),
+    lang: z.string().optional().describe("BCP-47 language code, e.g. en, tr"),
+    fresh: z.boolean().default(false).describe("Bypass the transcript cache"),
+};
+export async function handleTranscript(args, deps = {}) {
+    const fetch = deps.fetch ?? fetchTranscript;
+    const readCache = deps.readCache ?? ((id, key) => readCachedTranscript(id, key));
+    const writeCache = deps.writeCache ?? ((t, key) => writeCachedTranscript(t, key));
+    const save = deps.save ?? ((t) => saveTranscript(t));
+    const videoId = parseVideoId(args.video);
+    const key = args.lang ?? "auto";
+    if (!args.fresh) {
+        const cached = await readCache(videoId, key);
+        if (cached)
+            return cached;
+    }
+    const t = await fetch(videoId, args.lang);
+    await writeCache(t, key);
+    await save(t);
+    return t;
+}

package/dist/youtube/client.js

@@ -0,0 +1,8 @@
+import { Innertube } from "youtubei.js";
+let instance = null;
+export function getInnertube() {
+    if (!instance) {
+        instance = Innertube.create();
+    }
+    return instance;
+}

package/dist/youtube/search.js

@@ -0,0 +1,72 @@
+import { watchUrl } from "./url.js";
+import { getInnertube } from "./client.js";
+function txt(v) {
+    if (!v)
+        return "";
+    if (typeof v === "string")
+        return v;
+    if ("text" in v && typeof v.text === "string")
+        return v.text;
+    if ("name" in v && typeof v.name === "string")
+        return v.name;
+    return "";
+}
+function parseViewCount(s) {
+    const m = s.replace(/,/g, "").match(/([\d.]+)\s*([KMB]?)/i);
+    if (!m)
+        return null;
+    const n = parseFloat(m[1]);
+    if (Number.isNaN(n))
+        return null;
+    const mult = { K: 1e3, M: 1e6, B: 1e9 };
+    return Math.round(n * (mult[m[2].toUpperCase()] ?? 1));
+}
+export function normalizeSearchResults(raw, limit) {
+    const out = [];
+    for (const v of raw) {
+        const videoId = v.id ?? v.video_id;
+        if (!videoId)
+            continue;
+        out.push({
+            videoId,
+            title: txt(v.title),
+            channel: txt(v.author),
+            durationSeconds: v.duration?.seconds ?? null,
+            viewCount: parseViewCount(txt(v.view_count) || txt(v.short_view_count)),
+            publishedAt: txt(v.published) || null,
+            url: watchUrl(videoId),
+            descriptionSnippet: txt(v.description_snippet),
+        });
+        if (out.length >= limit)
+            break;
+    }
+    return out;
+}
+export async function searchVideos(query, opts = {}) {
+    const limit = opts.limit ?? 10;
+    const yt = await getInnertube();
+    let page = (await yt.search(query, { type: opts.type ?? "video" }));
+    const out = [];
+    const seen = new Set();
+    // Page through continuations until we have `limit` results or run out.
+    for (let guard = 0; page && guard < 30; guard++) {
+        const items = page.results ?? page.videos ?? [];
+        for (const r of normalizeSearchResults(items, items.length)) {
+            if (seen.has(r.videoId))
+                continue;
+            seen.add(r.videoId);
+            out.push(r);
+            if (out.length >= limit)
+                return out;
+        }
+        if (!page.has_continuation || typeof page.getContinuation !== "function")
+            break;
+        try {
+            page = await page.getContinuation();
+        }
+        catch {
+            break;
+        }
+    }
+    return out.slice(0, limit);
+}

package/dist/youtube/transcript.js

@@ -0,0 +1,96 @@
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { watchUrl } from "./url.js";
+import { ensureYtDlp, jsRuntimeArg } from "../ytdlp/provision.js";
+export function parseJson3(data) {
+    const events = data?.events ?? [];
+    const segs = [];
+    for (const ev of events) {
+        const text = (ev.segs ?? []).map((s) => s.utf8 ?? "").join("").trim();
+        if (!text)
+            continue;
+        segs.push({ startSeconds: Math.round((ev.tStartMs ?? 0) / 1000), text });
+    }
+    return segs;
+}
+export function buildFullText(segments) {
+    return segments
+        .map((s) => s.text)
+        .join(" ")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+export function pickLanguage(requested, metaLang, available) {
+    const match = (l) => available.find((a) => a === l) ??
+        available.find((a) => !!l && (a.startsWith(l + "-") || a === l + "-orig"));
+    return match(requested) ?? match(metaLang) ?? match("en") ?? available[0];
+}
+function run(bin, args) {
+    return new Promise((resolve, reject) => {
+        const p = spawn(bin, args);
+        let stdout = "";
+        let stderr = "";
+        p.on("error", reject);
+        p.stdout.on("data", (d) => (stdout += d));
+        p.stderr.on("data", (d) => (stderr += d));
+        p.on("close", (code) => resolve({ code: code ?? -1, stdout, stderr }));
+    });
+}
+export async function fetchTranscript(videoId, lang, env = process.env) {
+    const bin = await ensureYtDlp(env);
+    const url = watchUrl(videoId);
+    const jsRt = jsRuntimeArg();
+    // 1. Metadata: title + available caption languages.
+    const meta = await run(bin, ["-J", "--skip-download", "--no-warnings", "--js-runtimes", jsRt, url]);
+    if (meta.code !== 0)
+        throw new Error(`yt-dlp metadata failed for ${videoId}: ${meta.stderr.slice(-200)}`);
+    const info = JSON.parse(meta.stdout);
+    const available = Array.from(new Set([...Object.keys(info.subtitles ?? {}), ...Object.keys(info.automatic_captions ?? {})]));
+    if (available.length === 0)
+        throw new Error(`No transcript available for video ${videoId}`);
+    const chosen = pickLanguage(lang, info.language, available);
+    // 2. Download the chosen track as json3 into a temp dir, then parse.
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "ytb-tr-"));
+    try {
+        const dl = await run(bin, [
+            "--skip-download",
+            "--write-subs",
+            "--write-auto-subs",
+            "--sub-langs",
+            chosen,
+            "--sub-format",
+            "json3",
+            "--no-warnings",
+            "--js-runtimes",
+            jsRt,
+            "-o",
+            path.join(dir, "t.%(ext)s"),
+            url,
+        ]);
+        if (dl.code !== 0)
+            throw new Error(`yt-dlp subtitle download failed for ${videoId}: ${dl.stderr.slice(-200)}`);
+        const files = (await fs.readdir(dir)).filter((f) => f.endsWith(".json3"));
+        if (files.length === 0)
+            throw new Error(`No transcript track produced for ${videoId} (lang ${chosen})`);
+        const file = files.find((f) => f.includes(`.${chosen}.`)) ?? files[0];
+        const json = JSON.parse(await fs.readFile(path.join(dir, file), "utf8"));
+        const segments = parseJson3(json);
+        if (segments.length === 0)
+            throw new Error(`Empty transcript for ${videoId}`);
+        const m = file.match(/\.([^.]+)\.json3$/);
+        const language = m ? m[1] : chosen;
+        return {
+            videoId,
+            title: info.title ?? "",
+            language,
+            availableLanguages: available,
+            segments,
+            fullText: buildFullText(segments),
+        };
+    }
+    finally {
+        await fs.rm(dir, { recursive: true, force: true });
+    }
+}

package/dist/youtube/types.js

@@ -0,0 +1 @@
+export {};

package/dist/youtube/url.js

@@ -0,0 +1,29 @@
+const ID_RE = /^[a-zA-Z0-9_-]{11}$/;
+export function parseVideoId(input) {
+    const s = input.trim();
+    if (ID_RE.test(s))
+        return s;
+    try {
+        const u = new URL(s);
+        if (u.hostname === "youtu.be") {
+            const id = u.pathname.slice(1);
+            if (ID_RE.test(id))
+                return id;
+        }
+        if (u.hostname.endsWith("youtube.com")) {
+            const v = u.searchParams.get("v");
+            if (v && ID_RE.test(v))
+                return v;
+            const m = u.pathname.match(/\/(shorts|embed|v)\/([a-zA-Z0-9_-]{11})/);
+            if (m)
+                return m[2];
+        }
+    }
+    catch {
+        /* not a URL — fall through */
+    }
+    throw new Error(`Could not parse a YouTube video ID from: ${input}`);
+}
+export function watchUrl(videoId) {
+    return `https://www.youtube.com/watch?v=${videoId}`;
+}

package/dist/ytdlp/provision.js

@@ -0,0 +1,91 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { spawn } from "node:child_process";
+import { cacheDir } from "../library/paths.js";
+const RELEASE_BASE = "https://github.com/yt-dlp/yt-dlp/releases/latest/download";
+export function assetName(platform = process.platform, arch = process.arch) {
+    if (platform === "win32")
+        return "yt-dlp.exe";
+    if (platform === "darwin")
+        return "yt-dlp_macos";
+    if (platform === "linux")
+        return arch === "arm64" ? "yt-dlp_linux_aarch64" : "yt-dlp_linux";
+    return "yt-dlp_linux";
+}
+export function jsRuntimeArg() {
+    return `node:${process.execPath}`;
+}
+function binPath(env = process.env) {
+    return path.join(cacheDir(env), "bin", assetName());
+}
+function commandExists(cmd) {
+    return new Promise((resolve) => {
+        const p = spawn(cmd, ["--version"]);
+        p.on("error", () => resolve(false));
+        p.on("close", (code) => resolve(code === 0));
+    });
+}
+async function fileExists(p) {
+    try {
+        await fs.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function verifyChecksum(buf, asset) {
+    // Best-effort: if SUMS is unreachable, skip rather than break provisioning.
+    let sums;
+    try {
+        const res = await fetch(`${RELEASE_BASE}/SHA2-256SUMS`);
+        if (!res.ok)
+            return;
+        sums = await res.text();
+    }
+    catch {
+        return;
+    }
+    const line = sums.split("\n").find((l) => l.trim().endsWith(asset));
+    if (!line)
+        return;
+    const expected = line.trim().split(/\s+/)[0].toLowerCase();
+    const actual = createHash("sha256").update(buf).digest("hex");
+    if (expected && actual !== expected) {
+        throw new Error(`yt-dlp checksum mismatch for ${asset}: expected ${expected}, got ${actual}`);
+    }
+}
+async function download(env) {
+    const asset = assetName();
+    const dest = binPath(env);
+    await fs.mkdir(path.dirname(dest), { recursive: true });
+    const res = await fetch(`${RELEASE_BASE}/${asset}`);
+    if (!res.ok)
+        throw new Error(`Failed to download yt-dlp (${asset}): HTTP ${res.status}`);
+    const buf = Buffer.from(await res.arrayBuffer());
+    await verifyChecksum(buf, asset);
+    await fs.writeFile(dest, buf);
+    if (process.platform !== "win32")
+        await fs.chmod(dest, 0o755);
+    return dest;
+}
+export async function ensureYtDlp(env = process.env) {
+    const override = env.YT_DLP_PATH?.trim();
+    if (override)
+        return override;
+    if (await commandExists("yt-dlp"))
+        return "yt-dlp";
+    const cached = binPath(env);
+    if (await fileExists(cached))
+        return cached;
+    try {
+        return await download(env);
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        throw new Error(`Could not provision yt-dlp automatically (${msg}). Install it manually — ` +
+            `macOS: 'brew install yt-dlp'; Linux: 'pipx install yt-dlp'; ` +
+            `Windows: 'winget install yt-dlp' — or set YT_DLP_PATH to an existing binary.`);
+    }
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "ytb-tools",
+  "version": "0.1.0",
+  "description": "Keyless MCP server for YouTube search, transcript extraction (auto-provisioned yt-dlp), and host-driven summarization.",
+  "type": "module",
+  "license": "MIT",
+  "author": "aliildan",
+  "homepage": "https://github.com/aliildan/ytb-tools#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aliildan/ytb-tools.git"
+  },
+  "bugs": {
+    "url": "https://github.com/aliildan/ytb-tools/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "youtube",
+    "transcript",
+    "captions",
+    "summarize",
+    "claude",
+    "yt-dlp"
+  ],
+  "bin": {
+    "ytb-tools": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "env-paths": "^4.0.0",
+    "youtubei.js": "^17.2.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.1",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  }
+}