@unpuzzle/viddy-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Muscled
+
+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,119 @@
+# @unpuzzle/viddy-mcp
+
+The Model Context Protocol server for [Viddy](https://viddy.lol).
+
+Ask Claude about your screen recordings: pull transcripts, find the moment you
+said something, and read the timestamped notes people left on a share link.
+
+> If you're on **claude.ai**, you don't need this package — add
+> `https://viddy.lol/mcp` as a Connector instead.
+> See [viddy.lol/install/mcp](https://viddy.lol/install/mcp).
+
+## Install
+
+```sh
+npm install -g @unpuzzle/viddy-mcp
+```
+
+Then register it with your MCP client:
+
+### Claude Code
+
+```sh
+claude mcp add viddy -- viddy-mcp
+```
+
+### Cursor / Claude Desktop
+
+Add this to your MCP config (usually `~/.cursor/mcp.json` or your client's
+settings file):
+
+```json
+{
+  "mcpServers": {
+    "viddy": {
+      "command": "viddy-mcp"
+    }
+  }
+}
+```
+
+## First-run sign-in
+
+The first time Claude calls a tool that needs your account, the MCP opens your
+browser to the Viddy consent screen. Sign in, click **Allow**, and you're done.
+Tokens are saved locally and refreshed automatically:
+
+- macOS / Linux: `~/.config/viddy-mcp/auth.json`
+- Windows: `%APPDATA%\viddy-mcp\auth.json`
+
+The file is written `chmod 600` (owner-only). Nothing is stored anywhere else,
+and the package never sees your Google password.
+
+To revoke access later, visit
+[Settings → Connected Apps](https://viddy.lol/settings/connected-apps) on
+viddy.lol. To just forget the credentials on this machine, ask Claude to
+disconnect.
+
+## Tools
+
+Claude picks the right tool from what you ask — you don't need the names.
+
+**Videos** — `list_videos`, `get_video`
+
+**Transcripts** — `get_transcript`, `search_transcripts`
+
+**Feedback** — `list_notes`
+
+**Connection** — `ping`, `connect`, `disconnect`, `whoami`
+
+## What you can ask
+
+- "What videos did I record this week?"
+- "Summarize my latest Viddy recording."
+- "When did I talk about pricing in my recordings?"
+- "What feedback did people leave on the onboarding walkthrough?"
+- "Pull the transcript between 10 and 20 minutes of that demo and turn it into release notes."
+
+Transcripts come from the Viddy desktop app, which transcribes on-device after
+a recording finishes. Videos uploaded through the web app aren't transcribed,
+so `get_transcript` returns status `none` for those.
+
+## Permissions
+
+The MCP requests three read-only scopes and nothing else:
+
+| Scope | What it reads |
+| --- | --- |
+| `videos.read` | Your video list and metadata |
+| `transcripts.read` | Transcript text and timestamps |
+| `annotations.read` | Timestamped notes on your videos |
+
+There is no write scope. This package cannot record, delete, rename, or
+re-share anything.
+
+## Pointing at a different Viddy
+
+Set `VIDDY_BASE_URL` to target a non-production instance. Credentials are
+stored per base URL, so a local dev connection won't disturb your production
+one.
+
+```sh
+VIDDY_BASE_URL=http://localhost:3140 viddy-mcp
+```
+
+## Troubleshooting
+
+**"Not connected to Viddy"** — the grant was revoked or the credentials file
+was removed. Ask Claude to connect again.
+
+**A tool says it needs a scope you don't have** — the scope list grew since you
+connected. Revoke the grant under Settings → Connected Apps, then reconnect to
+consent to the new list.
+
+**The browser never opens** — the consent URL is also printed to stderr; paste
+it in yourself. Set `VIDDY_BROWSER_CMD` to override the browser command.
+
+## License
+
+MIT. See `LICENSE`.

package/dist/api.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Authenticated HTTP helper for the Viddy API, and the ApiClient that
+ * @viddy/mcp-core tools run against.
+ *
+ * apiFetch(path, init?):
+ *   1. Load stored tokens; with none, run the OAuth flow (first-run consent).
+ *   2. Refresh proactively when the access token is near expiry.
+ *   3. Send `Authorization: Bearer <access_token>`.
+ *   4. On 401, refresh once and replay the request.
+ *   5. On 403 insufficient_scope, explain how to re-consent.
+ *   6. Return parsed JSON, or throw with a message worth showing the user.
+ */
+import type { ApiClient } from "@viddy/mcp-core";
+export interface ApiOptions extends Omit<RequestInit, "headers"> {
+    /** Surface "not connected" instead of opening a browser. */
+    noAutoAuth?: boolean;
+    headers?: Record<string, string>;
+}
+export declare class ApiError extends Error {
+    status: number;
+    body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+export declare class NotConnectedError extends Error {
+    constructor();
+}
+/**
+ * Make an authenticated request. `path` is rooted at the Viddy origin
+ * (e.g. "/api/v1/videos?limit=5"). Returns the parsed JSON body.
+ */
+export declare function apiFetch<T = unknown>(path: string, init?: ApiOptions): Promise<T>;
+/** The ApiClient handed to @viddy/mcp-core tool handlers. */
+export declare const apiClient: ApiClient;
+//# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAWH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,MAAM,WAAW,UAAW,SAAQ,IAAI,CAAC,WAAW,EAAE,SAAS,CAAC;IAC9D,4DAA4D;IAC5D,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,qBAAa,QAAS,SAAQ,KAAK;IAGxB,MAAM,EAAE,MAAM;IACd,IAAI,EAAE,OAAO;gBAFpB,OAAO,EAAE,MAAM,EACR,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO;CAKvB;AAED,qBAAa,iBAAkB,SAAQ,KAAK;;CAO3C;AA0BD;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,UAAe,GAAG,OAAO,CAAC,CAAC,CAAC,CAgE3F;AAED,6DAA6D;AAC7D,eAAO,MAAM,SAAS,EAAE,SAGvB,CAAC"}

package/dist/api.js

@@ -0,0 +1,121 @@
+/**
+ * Authenticated HTTP helper for the Viddy API, and the ApiClient that
+ * @viddy/mcp-core tools run against.
+ *
+ * apiFetch(path, init?):
+ *   1. Load stored tokens; with none, run the OAuth flow (first-run consent).
+ *   2. Refresh proactively when the access token is near expiry.
+ *   3. Send `Authorization: Bearer <access_token>`.
+ *   4. On 401, refresh once and replay the request.
+ *   5. On 403 insufficient_scope, explain how to re-consent.
+ *   6. Return parsed JSON, or throw with a message worth showing the user.
+ */
+import { getBaseUrl } from "./config.js";
+import { accessTokenIsFresh, clearTokens, loadTokens, } from "./auth.js";
+import { refreshTokens, runAuthorizationFlow } from "./oauth.js";
+import { log } from "./log.js";
+export class ApiError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = "ApiError";
+    }
+}
+export class NotConnectedError extends Error {
+    constructor() {
+        super("Not connected to Viddy. Run the `connect` tool to sign in — or just ask for your videos again and consent will open in your browser.");
+        this.name = "NotConnectedError";
+    }
+}
+async function ensureTokens(opts) {
+    let tokens = await loadTokens();
+    if (!tokens) {
+        if (opts.noAutoAuth)
+            throw new NotConnectedError();
+        log("info", "no tokens found; starting OAuth flow");
+        tokens = await runAuthorizationFlow();
+    }
+    if (!accessTokenIsFresh(tokens)) {
+        log("info", "access token near expiry; refreshing");
+        try {
+            tokens = await refreshTokens(tokens.refreshToken);
+        }
+        catch (e) {
+            // Usually means the grant was revoked. Drop the dead tokens, re-consent.
+            log("warn", "refresh failed; clearing tokens", {
+                error: e instanceof Error ? e.message : String(e),
+            });
+            await clearTokens();
+            if (opts.noAutoAuth)
+                throw new NotConnectedError();
+            tokens = await runAuthorizationFlow();
+        }
+    }
+    return tokens;
+}
+/**
+ * Make an authenticated request. `path` is rooted at the Viddy origin
+ * (e.g. "/api/v1/videos?limit=5"). Returns the parsed JSON body.
+ */
+export async function apiFetch(path, init = {}) {
+    const { noAutoAuth, headers: extraHeaders, ...rest } = init;
+    const tokens = await ensureTokens({ noAutoAuth: noAutoAuth ?? false });
+    const doRequest = (token) => fetch(`${getBaseUrl()}${path}`, {
+        ...rest,
+        headers: {
+            ...extraHeaders,
+            Authorization: `Bearer ${token}`,
+            Accept: "application/json",
+        },
+    });
+    let res = await doRequest(tokens.accessToken);
+    // 401 → one refresh + replay. A second 401 is a real failure, not a stale token.
+    if (res.status === 401) {
+        log("info", "got 401; attempting refresh + replay");
+        let refreshed;
+        try {
+            refreshed = await refreshTokens(tokens.refreshToken);
+        }
+        catch {
+            await clearTokens();
+            throw new NotConnectedError();
+        }
+        res = await doRequest(refreshed.accessToken);
+    }
+    if (!res.ok) {
+        let body = null;
+        try {
+            body = await res.json();
+        }
+        catch {
+            body = await res.text().catch(() => null);
+        }
+        if (res.status === 403 && typeof body === "object" && body !== null && "reason" in body) {
+            const b = body;
+            if (b.reason === "insufficient_scope") {
+                throw new ApiError(`This tool needs the "${b.required_scope}" scope, which the current connection doesn't have. ` +
+                    "Revoke Viddy MCP under Settings → Connected Apps on viddy.lol, then run `connect` again to grant it.", 403, body);
+            }
+        }
+        // Lead with the human sentence (error_description) — Claude shows this to
+        // the user. The machine code only appears when there is no description.
+        const code = typeof body === "object" && body !== null && "error" in body
+            ? String(body.error)
+            : `HTTP ${res.status}`;
+        const description = typeof body === "object" && body !== null && "error_description" in body
+            ? String(body.error_description)
+            : "";
+        throw new ApiError(description || `${code} (${res.status})`, res.status, body);
+    }
+    if (res.status === 204)
+        return undefined;
+    return (await res.json());
+}
+/** The ApiClient handed to @viddy/mcp-core tool handlers. */
+export const apiClient = {
+    fetch: (path, init) => apiFetch(path, init),
+};
+//# sourceMappingURL=api.js.map

package/dist/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}

package/dist/auth.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Token storage — load/save the OAuth tokens to disk.
+ *
+ * Storage path (env-paths, so it's right on every platform):
+ *   macOS/Linux: ~/.config/viddy-mcp/auth.json
+ *   Windows:     %APPDATA%\viddy-mcp\auth.json
+ *
+ * The file holds a bearer token for the user's Viddy account, so it is written
+ * chmod 600. On Windows, user-profile ACLs already make it owner-only and
+ * POSIX modes are meaningless, so chmod failures are ignored.
+ *
+ * One file holds tokens per base URL, so someone pointing VIDDY_BASE_URL at a
+ * local dev server does not clobber their production connection.
+ */
+export interface StoredTokens {
+    accessToken: string;
+    refreshToken: string;
+    /** Unix ms at which the access token expires. */
+    expiresAt: number;
+    /** Granted scopes, space-separated, as returned by /api/oauth/token. */
+    scope: string;
+    /** When the grant was first issued (ms). */
+    grantedAt: number;
+}
+/** Tokens for the current base URL, or null if not connected. */
+export declare function loadTokens(): Promise<StoredTokens | null>;
+/** Save tokens for the current base URL, preserving entries for other hosts. */
+export declare function saveTokens(tokens: StoredTokens): Promise<void>;
+/** Forget tokens for the current base URL. Does not revoke server-side. */
+export declare function clearTokens(): Promise<void>;
+/** Where the auth file lives — surfaced in help/debug output. */
+export declare function authFilePath(): string;
+/** Is the access token still usable? 30s safety margin for clock skew + flight time. */
+export declare function accessTokenIsFresh(tokens: StoredTokens): boolean;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAcH,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAC;IACd,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;CACnB;AA+CD,iEAAiE;AACjE,wBAAsB,UAAU,IAAI,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAI/D;AAED,gFAAgF;AAChF,wBAAsB,UAAU,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAIpE;AAED,2EAA2E;AAC3E,wBAAsB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAKjD;AAED,iEAAiE;AACjE,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,wFAAwF;AACxF,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAEhE"}

package/dist/auth.js

@@ -0,0 +1,95 @@
+/**
+ * Token storage — load/save the OAuth tokens to disk.
+ *
+ * Storage path (env-paths, so it's right on every platform):
+ *   macOS/Linux: ~/.config/viddy-mcp/auth.json
+ *   Windows:     %APPDATA%\viddy-mcp\auth.json
+ *
+ * The file holds a bearer token for the user's Viddy account, so it is written
+ * chmod 600. On Windows, user-profile ACLs already make it owner-only and
+ * POSIX modes are meaningless, so chmod failures are ignored.
+ *
+ * One file holds tokens per base URL, so someone pointing VIDDY_BASE_URL at a
+ * local dev server does not clobber their production connection.
+ */
+import { mkdir, readFile, writeFile, chmod, rename, unlink } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import envPaths from "env-paths";
+import { getBaseUrl } from "./config.js";
+import { log } from "./log.js";
+const PATHS = envPaths("viddy-mcp", { suffix: "" });
+const AUTH_PATH = join(PATHS.config, "auth.json");
+async function readFileOrNull() {
+    try {
+        const parsed = JSON.parse(await readFile(AUTH_PATH, "utf8"));
+        if (parsed?.schemaVersion !== 1) {
+            log("warn", "auth.json schemaVersion mismatch; ignoring stored tokens", {
+                path: AUTH_PATH,
+            });
+            return null;
+        }
+        return parsed;
+    }
+    catch (e) {
+        if (e?.code === "ENOENT")
+            return null;
+        log("warn", "failed to read auth.json; treating as no stored tokens", {
+            path: AUTH_PATH,
+            error: e instanceof Error ? e.message : String(e),
+        });
+        return null;
+    }
+}
+/**
+ * Write via temp file + rename so a crash mid-write can't leave a truncated
+ * auth.json. chmod happens on the temp file, before it is visible under the
+ * real name, so the token is never briefly world-readable.
+ */
+async function writeAtomic(file) {
+    await mkdir(dirname(AUTH_PATH), { recursive: true, mode: 0o700 });
+    const tmp = `${AUTH_PATH}.${process.pid}.tmp`;
+    try {
+        await writeFile(tmp, JSON.stringify(file, null, 2), { encoding: "utf8", mode: 0o600 });
+        try {
+            await chmod(tmp, 0o600);
+        }
+        catch {
+            // Best-effort: Windows has no POSIX modes.
+        }
+        await rename(tmp, AUTH_PATH);
+    }
+    catch (e) {
+        await unlink(tmp).catch(() => { });
+        throw e;
+    }
+}
+/** Tokens for the current base URL, or null if not connected. */
+export async function loadTokens() {
+    const file = await readFileOrNull();
+    if (!file)
+        return null;
+    return file.byBaseUrl[getBaseUrl()] ?? null;
+}
+/** Save tokens for the current base URL, preserving entries for other hosts. */
+export async function saveTokens(tokens) {
+    const file = (await readFileOrNull()) ?? { schemaVersion: 1, byBaseUrl: {} };
+    file.byBaseUrl[getBaseUrl()] = tokens;
+    await writeAtomic(file);
+}
+/** Forget tokens for the current base URL. Does not revoke server-side. */
+export async function clearTokens() {
+    const file = await readFileOrNull();
+    if (!file)
+        return;
+    delete file.byBaseUrl[getBaseUrl()];
+    await writeAtomic(file);
+}
+/** Where the auth file lives — surfaced in help/debug output. */
+export function authFilePath() {
+    return AUTH_PATH;
+}
+/** Is the access token still usable? 30s safety margin for clock skew + flight time. */
+export function accessTokenIsFresh(tokens) {
+    return tokens.expiresAt - Date.now() > 30_000;
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AACrF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,QAAQ,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAmB/B,MAAM,KAAK,GAAG,QAAQ,CAAC,WAAW,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC;AACpD,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;AAElD,KAAK,UAAU,cAAc;IAC3B,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,CAAa,CAAC;QACzE,IAAI,MAAM,EAAE,aAAa,KAAK,CAAC,EAAE,CAAC;YAChC,GAAG,CAAC,MAAM,EAAE,0DAA0D,EAAE;gBACtE,IAAI,EAAE,SAAS;aAChB,CAAC,CAAC;YACH,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,CAAU,EAAE,CAAC;QACpB,IAAK,CAA2B,EAAE,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QACjE,GAAG,CAAC,MAAM,EAAE,wDAAwD,EAAE;YACpE,IAAI,EAAE,SAAS;YACf,KAAK,EAAE,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;SAClD,CAAC,CAAC;QACH,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,WAAW,CAAC,IAAc;IACvC,MAAM,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAClE,MAAM,GAAG,GAAG,GAAG,SAAS,IAAI,OAAO,CAAC,GAAG,MAAM,CAAC;IAC9C,IAAI,CAAC;QACH,MAAM,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QACvF,IAAI,CAAC;YACH,MAAM,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC1B,CAAC;QAAC,MAAM,CAAC;YACP,2CAA2C;QAC7C,CAAC;QACD,MAAM,MAAM,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;IAC/B,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAClC,MAAM,CAAC,CAAC;IACV,CAAC;AACH,CAAC;AAED,iEAAiE;AACjE,MAAM,CAAC,KAAK,UAAU,UAAU;IAC9B,MAAM,IAAI,GAAG,MAAM,cAAc,EAAE,CAAC;IACpC,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,OAAO,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,CAAC,IAAI,IAAI,CAAC;AAC9C,CAAC;AAED,gFAAgF;AAChF,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,MAAoB;IACnD,MAAM,IAAI,GAAG,CAAC,MAAM,cAAc,EAAE,CAAC,IAAI,EAAE,aAAa,EAAE,CAAU,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC;IACtF,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,CAAC,GAAG,MAAM,CAAC;IACtC,MAAM,WAAW,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,2EAA2E;AAC3E,MAAM,CAAC,KAAK,UAAU,WAAW;IAC/B,MAAM,IAAI,GAAG,MAAM,cAAc,EAAE,CAAC;IACpC,IAAI,CAAC,IAAI;QAAE,OAAO;IAClB,OAAO,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,CAAC,CAAC;IACpC,MAAM,WAAW,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,YAAY;IAC1B,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,kBAAkB,CAAC,MAAoB;IACrD,OAAO,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC;AAChD,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Compile-time configuration for the Viddy MCP server.
+ *
+ * CLIENT_ID is a public, hardcoded value that must match the `viddy-mcp` row
+ * seeded into the oauth_client table by the Viddy web app's migration. It is
+ * not a secret — this is a public PKCE client (RFC 8252), where the proof of
+ * possession is the code verifier, not a client secret.
+ */
+export declare const CLIENT_ID = "viddy-mcp";
+export declare const DEFAULT_BASE_URL = "https://viddy.lol";
+/** Resolve the Viddy base URL: VIDDY_BASE_URL override → production default. */
+export declare function getBaseUrl(): string;
+/**
+ * Scopes requested at install. Must be a subset of the scopes registered on
+ * the oauth_client row. Changing this list means existing users have to
+ * re-consent on their next connect.
+ */
+export declare const REQUESTED_SCOPES: readonly ["videos.read", "transcripts.read", "annotations.read"];
+export declare const PACKAGE_NAME = "@unpuzzle/viddy-mcp";
+/** Sent in the MCP `serverInfo`. Keep in sync with package.json `version`. */
+export declare const PACKAGE_VERSION = "0.1.0";
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,eAAO,MAAM,SAAS,cAAc,CAAC;AAErC,eAAO,MAAM,gBAAgB,sBAAsB,CAAC;AAEpD,gFAAgF;AAChF,wBAAgB,UAAU,IAAI,MAAM,CAInC;AAED;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,kEAInB,CAAC;AAEX,eAAO,MAAM,YAAY,wBAAwB,CAAC;AAElD,8EAA8E;AAC9E,eAAO,MAAM,eAAe,UAAU,CAAC"}

package/dist/config.js

@@ -0,0 +1,31 @@
+/**
+ * Compile-time configuration for the Viddy MCP server.
+ *
+ * CLIENT_ID is a public, hardcoded value that must match the `viddy-mcp` row
+ * seeded into the oauth_client table by the Viddy web app's migration. It is
+ * not a secret — this is a public PKCE client (RFC 8252), where the proof of
+ * possession is the code verifier, not a client secret.
+ */
+export const CLIENT_ID = "viddy-mcp";
+export const DEFAULT_BASE_URL = "https://viddy.lol";
+/** Resolve the Viddy base URL: VIDDY_BASE_URL override → production default. */
+export function getBaseUrl() {
+    const fromEnv = process.env["VIDDY_BASE_URL"];
+    if (fromEnv && fromEnv.length > 0)
+        return fromEnv.replace(/\/+$/, "");
+    return DEFAULT_BASE_URL;
+}
+/**
+ * Scopes requested at install. Must be a subset of the scopes registered on
+ * the oauth_client row. Changing this list means existing users have to
+ * re-consent on their next connect.
+ */
+export const REQUESTED_SCOPES = [
+    "videos.read",
+    "transcripts.read",
+    "annotations.read",
+];
+export const PACKAGE_NAME = "@unpuzzle/viddy-mcp";
+/** Sent in the MCP `serverInfo`. Keep in sync with package.json `version`. */
+export const PACKAGE_VERSION = "0.1.0";
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,CAAC,MAAM,SAAS,GAAG,WAAW,CAAC;AAErC,MAAM,CAAC,MAAM,gBAAgB,GAAG,mBAAmB,CAAC;AAEpD,gFAAgF;AAChF,MAAM,UAAU,UAAU;IACxB,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAC9C,IAAI,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACtE,OAAO,gBAAgB,CAAC;AAC1B,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,aAAa;IACb,kBAAkB;IAClB,kBAAkB;CACV,CAAC;AAEX,MAAM,CAAC,MAAM,YAAY,GAAG,qBAAqB,CAAC;AAElD,8EAA8E;AAC9E,MAAM,CAAC,MAAM,eAAe,GAAG,OAAO,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * @unpuzzle/viddy-mcp — MCP server for Viddy, spoken over stdio.
+ *
+ * The host (Claude Code, Claude Desktop, Cursor) spawns this process and talks
+ * to it on stdin/stdout. Every diagnostic goes to stderr via ./log.js, because
+ * anything on stdout corrupts the protocol framing.
+ *
+ * Tool definitions live in @viddy/mcp-core so the hosted /mcp endpoint on
+ * viddy.lol serves exactly the same surface. The three connection tools below
+ * (connect/disconnect/whoami) are package-only: they manage tokens on this
+ * machine, which a remote Connector has no equivalent of.
+ *
+ * Usage:
+ *   npm install -g @unpuzzle/viddy-mcp
+ *   claude mcp add viddy -- viddy-mcp
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;GAeG"}