@tday-com/mcp 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,36 @@
+tday MCP Package License
+
+Copyright (c) 2026 tday.com. All rights reserved.
+
+This package is proprietary software owned by tday.com.
+
+Subject to these terms, tday.com grants you a limited, revocable,
+non-exclusive, non-transferable license to download, install, and run the
+unmodified npm package solely for the purpose of connecting supported AI agent
+software to your tday.com account and using tday.com services.
+
+You may not, except as expressly permitted by applicable law:
+
+1. copy this package except as strictly necessary to install and run it;
+2. modify, adapt, translate, or create derivative works from this package;
+3. redistribute, sublicense, sell, rent, lease, lend, publish, or otherwise
+   make this package available to third parties;
+4. reverse engineer, decompile, disassemble, or attempt to derive source code,
+   protocols, internal implementation details, or trade secrets from this
+   package;
+5. remove, alter, or obscure any proprietary notices; or
+6. use this package to build or assist a competing service.
+
+No ownership rights are transferred to you. All rights not expressly granted
+are reserved by tday.com.
+
+This package is provided "as is" and without warranties of any kind, whether
+express, implied, statutory, or otherwise, including warranties of
+merchantability, fitness for a particular purpose, title, and non-infringement.
+To the maximum extent permitted by law, tday.com will not be liable for any
+indirect, incidental, special, consequential, exemplary, or punitive damages,
+or for lost profits, data, goodwill, or business interruption arising out of or
+related to this package.
+
+Your use of tday.com services remains subject to the applicable tday.com terms
+and policies.

package/README.md

@@ -1,3 +1,125 @@
-# Temporary Holding Version
+# @tday-com/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Official local MCP server and installer for [tday.com](https://tday.com). Connect Claude Code, Cursor, VS Code, Gemini CLI, Codex, and any MCP-compatible AI agent to your tday.com account so you can generate designs, make launch videos, manage brands, and query your workspace directly from chat.
+
+## Install
+
+```bash
+npx -y @tday-com/mcp install
+```
+
+Alternatives:
+
+```bash
+bunx @tday-com/mcp install
+pnpm dlx @tday-com/mcp install
+curl -fsSL https://tday.com/install.sh | bash
+```
+
+The installer opens your browser, lets you sign in or sign up on tday.com, asks you to authorize this machine, then automatically configures supported agents. Claude Code, Cursor, Gemini CLI and VS Code (stable and Insiders, user `mcp.json`) get MCP config entries; Codex gets a TOML block to paste (the Codex app reads the same file). No manual key copying is needed.
+
+One install sets up everything your account can use, with one sign-in:
+
+- `tday`: this server (your account, brands, designs, launch videos).
+- `tday-capture`: [`@tday-com/capture`](https://www.npmjs.com/package/@tday-com/capture), which captures real UI from the app running on your machine for tday. Added when your account can capture. It reads the same `~/.tday/config.json`, so it needs no token of its own.
+
+Run `install` again whenever you want to update either, or after your account gains access to something new.
+
+## Slash commands
+
+Claude Code users get:
+
+- `/tday` - general tday.com assistant
+- `/tday-design` - generate a design
+- `/tday-brand` - create/list/view brands
+- `/tday-credits` - check your plan and credit balance
+- `/tday-ideas` - brainstorm brand-specific design ideas
+- `/tday-launch-video` - make a launch video of a feature: the one you name, or the newest one without a launch video (when your plan includes launch videos)
+
+## MCP tools
+
+- `tday_whoami` - current user, plan and credit balance
+- `tday_list_brands` / `tday_get_brand` - lightweight list summaries with API-backed `limit`/`offset`
+- `tday_create_brand` - create a brand from a website
+- `tday_list_designs` / `tday_get_design` - lightweight list summaries with API-backed `limit`/`offset`
+- `tday_generate_design` - prompt + brandId
+- `tday_poll_generation` - poll until completed/failed
+- `tday_download_image` - save a completed image locally
+- `tday_list_features` - a brand's features, newest first, with the launch videos each already has (`without: "launch_video"` lists the ones with none)
+- `tday_create_launch_video` - make a launch video of a feature (`featureId` from `tday_list_features`) or of a new subject (brandId, title, description)
+- `tday_poll_launch_video` / `tday_get_launch_video_mp4` / `tday_revise_launch_video` - follow a film until it is ready, get its MP4, or make a new cut from notes
+
+Generating a design spends credits from your organisation's balance, at the same price as in the app, and a failed generation gives them back. When the balance cannot cover a request, tday answers with a 402 and spends nothing; `tday_whoami` shows the balance and when it refreshes.
+
+Making a launch video spends credits the same way; `tday_get_credit_prices` lists every price.
+
+## MCP prompts
+
+Clients that list MCP prompts (Claude Code as `/mcp__tday__<name>`, VS Code as `/mcp.tday.<name>`) get:
+
+- `launch-video` - a launch video of the feature you name, or of the newest feature without one, quoted before it starts
+- `features` - the newest features and which already have a launch video
+
+All tools return structured content for modern MCP clients. They also accept optional `response_format: "json" | "markdown"` for the text payload; JSON remains the default for backward compatibility.
+
+## One-shot CLI calls
+
+Non-MCP integrations can call the same tool handlers directly:
+
+```bash
+npx -y @tday-com/mcp call tday_whoami '{}'
+npx -y @tday-com/mcp call tday_list_brands '{"limit":10,"response_format":"markdown"}'
+```
+
+This is useful for smoke tests and scripted integrations.
+
+## Claude connector
+
+For Claude's remote connector/custom connector flow, use the hosted MCP endpoint:
+
+```text
+https://tday.com/api/mcp
+```
+
+The hosted connector uses OAuth + PKCE with refresh-token rotation. Users sign in on tday.com, Claude receives a scoped bearer token, and the connection can be revoked from tday Settings - Integrations.
+
+## Security and privacy
+
+- **What a connection can do.** The token an MCP connection holds only reaches the routes the tools above use. It cannot delete or transfer a brand, manage members, or see payment details.
+- **Links expire.** A link made by `install` lasts 90 days; run `install` again to renew it. A hosted connector's access token lasts an hour and renews itself for as long as the connection is used; one left unused for 30 days disconnects.
+- **Disconnect** any connection from tday Settings - Integrations.
+- **No telemetry.** The server talks only to tday, and to tday's file storage when you ask it to download an image or video.
+
+## Manual MCP config
+
+```json
+{
+  "mcpServers": {
+    "tday": {
+      "command": "npx",
+      "args": ["-y", "@tday-com/mcp", "serve"]
+    }
+  }
+}
+```
+
+If you add this block yourself, run `npx -y @tday-com/mcp install` once afterward so the browser sign-in flow can link the server to your tday account automatically. `install` writes the entry pinned to its own version (`@tday-com/mcp@<version>`), so an agent never picks up a new release on its own; run `install` again to update. Pin the version in a block you write by hand too.
+
+For Gemini CLI, put the same `mcpServers.tday` object in `~/.gemini/settings.json`. VS Code's user `mcp.json` keys entries by `servers` and names the transport: `{ "servers": { "tday": { "type": "stdio", "command": "npx", "args": ["-y", "@tday-com/mcp", "serve"] } } }`.
+
+## Claude Code slash commands
+
+The installer writes user-level Claude Code slash commands to `~/.claude/commands`. After restarting Claude Code, typing `/` shows `/tday`, `/tday-design`, `/tday-brand`, `/tday-credits`, `/tday-ideas` and, where your plan includes launch videos, `/tday-launch-video` in the slash-command autocomplete list. A command your account no longer has is removed the next time you run `install`.
+
+## Security model
+
+- Uses local stdio transport; the MCP server runs on your machine.
+- Browser authorization requires signing in or signing up on tday.com.
+- The installer uses a loopback callback bound to `127.0.0.1` plus a random `state` nonce.
+- The local connection is revocable from tday.com settings.
+- Local config is written to `~/.tday/config.json` with `0600` permissions.
+- File downloads are restricted to HTTPS image URLs on an allowlist, re-check redirect targets, cap size at 50MB, and write only inside the current working directory.
+
+## License
+
+Proprietary. See `LICENSE`.

package/dist/api-client.js

@@ -0,0 +1,170 @@
+export async function api(config, path, init = {}) {
+    if (!config.token) {
+        throw new Error("Not authenticated. Run `npx -y @tday-com/mcp install` to link this MCP server to your tday account in the browser, then restart your AI agent.");
+    }
+    const controller = new AbortController();
+    const timeoutMs = init.method === "POST" ? 120_000 : 30_000;
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    if (typeof timeout === "object" && "unref" in timeout)
+        timeout.unref();
+    const callerSignal = init.signal;
+    if (callerSignal?.aborted)
+        controller.abort(callerSignal.reason);
+    callerSignal?.addEventListener("abort", () => controller.abort(callerSignal.reason), {
+        once: true,
+    });
+    try {
+        const res = await fetch(`${config.apiBaseUrl}${path}`, {
+            ...init,
+            signal: controller.signal,
+            headers: {
+                accept: "application/json",
+                "content-type": "application/json",
+                authorization: `Bearer ${config.token}`,
+                ...init.headers,
+            },
+        });
+        const text = await res.text();
+        if (!res.ok) {
+            throw new Error(formatHttpError(res.status, path, text, res.statusText));
+        }
+        if (!text)
+            return null;
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === "AbortError") {
+            if (callerSignal?.aborted)
+                throw err;
+            throw new Error(`tday request timed out after ${timeoutMs / 1000}s: ${path}`);
+        }
+        throw err;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function formatHttpError(status, path, text, statusText) {
+    if (status >= 500) {
+        return `tday ${status} ${path}. tday is temporarily unable to complete the request; retry shortly. If a design or launch video was already queued, keep polling it (tday_poll_generation or tday_poll_launch_video) rather than starting another.`;
+    }
+    const body = formatErrorBody(text) || statusText;
+    const prefix = `tday ${status} ${path}: ${body}`;
+    const code = errorCode(text);
+    const links = refusalLinks(text);
+    const linkLine = [
+        links.usage ? `See what the organisation has spent: ${links.usage}` : null,
+        links.billing ? `The organisation's owner can change the plan at ${links.billing}` : null,
+    ]
+        .filter(Boolean)
+        .join(" ");
+    if (code && PLAN_CODES.has(code) && status !== 402) {
+        return `${prefix}. ${PLAN_REFUSAL_LEADS[code] ?? "The organisation's plan does not include this."}${linkLine ? ` ${linkLine}` : ""} Run tday_whoami to see what the plan includes and who owns it.`;
+    }
+    switch (status) {
+        case 400:
+            return `${prefix}. Check the tool arguments and retry with values returned by tday list/get tools.`;
+        case 401:
+            return `${prefix}. This MCP server's tday link is missing, expired (links last 90 days) or was disconnected. Run \`npx -y @tday-com/mcp install\` to sign in and relink this machine, then restart your AI agent and retry tday_whoami.`;
+        case 402:
+            return `${prefix}. Nothing was started and no credits were spent. Do not retry until the balance changes.${linkLine ? ` ${linkLine}` : ""} Run tday_whoami for each organisation's balance and who owns it; tday_get_credit_prices has what things cost.`;
+        case 403:
+            return `${prefix}. The linked tday account, or this connection, is not allowed to do that. Use tday_whoami to verify the account, then list brands/designs again.`;
+        case 404:
+            return `${prefix}. Check that the ID came from a tday_* list/get tool and belongs to the linked account.`;
+        case 429:
+            return `${prefix}. MCP/API generation is rate limited per account. Wait for the limit window to pass (see the Retry-After time), then retry. Do not retry in a loop. Run tday_whoami to check the plan and credit balance.`;
+        default:
+            return prefix;
+    }
+}
+const PLAN_CODES = new Set(["insufficient_credits", "plan_locked", "brand_plan_locked", "format_locked", "brand_limit_reached"]);
+const PLAN_REFUSAL_LEADS = {
+    plan_locked: "This brand is locked by the organisation's plan.",
+    brand_plan_locked: "This brand is locked by the organisation's plan.",
+    format_locked: "The organisation's plan does not include this size; name another or omit it.",
+    brand_limit_reached: "The organisation's plan does not include another brand.",
+};
+function refusalLinks(text) {
+    try {
+        const parsed = JSON.parse(text);
+        return { usage: tdayUrl(parsed.links?.usage), billing: tdayUrl(parsed.links?.billing) };
+    }
+    catch {
+        return { usage: null, billing: null };
+    }
+}
+function tdayUrl(value) {
+    if (typeof value !== "string" || value.length > 500)
+        return null;
+    try {
+        const url = new URL(value);
+        const local = url.hostname === "localhost" || url.hostname === "127.0.0.1";
+        const tday = url.protocol === "https:" && (url.hostname === "tday.com" || url.hostname.endsWith(".tday.com"));
+        return tday || local ? url.toString() : null;
+    }
+    catch {
+        return null;
+    }
+}
+function errorCode(text) {
+    if (!text)
+        return null;
+    try {
+        const parsed = JSON.parse(text);
+        return typeof parsed.code === "string" ? parsed.code : null;
+    }
+    catch {
+        return null;
+    }
+}
+function formatErrorBody(text) {
+    if (!text)
+        return "";
+    try {
+        const parsed = JSON.parse(text);
+        const message = parsed.error ?? parsed.message;
+        if (typeof message === "string")
+            return message.slice(0, 300);
+    }
+    catch {
+    }
+    return "";
+}
+export function normalizeWebsite(raw) {
+    const candidate = raw.match(/^https?:\/\//i) ? raw : `https://${raw}`;
+    let url;
+    try {
+        url = new URL(candidate);
+    }
+    catch {
+        throw new Error(`Invalid website URL: "${raw}"`);
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new Error(`Website URL must use http or https (got ${url.protocol})`);
+    }
+    if (!url.hostname || !url.hostname.includes(".")) {
+        throw new Error("Website must include a valid domain, for example stripe.com");
+    }
+    return url.href;
+}
+export function firstImageUrl(generation) {
+    return (generation?.imageUrl ??
+        generation?.masterImageUrl ??
+        generation?.panels?.find((panel) => panel.imageUrl)?.imageUrl ??
+        null);
+}
+export function query(params) {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined)
+            search.set(key, String(value));
+    }
+    const encoded = search.toString();
+    return encoded ? `?${encoded}` : "";
+}

package/dist/cli.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+import { packageVersion } from "./package-info.js";
+import { runServer } from "./server.js";
+import { loadConfig } from "./config.js";
+import { callTool, stringifyResult } from "./tools.js";
+const [, , cmd, ...rest] = process.argv;
+async function main() {
+    switch (cmd) {
+        case "serve":
+        case undefined:
+            await runServer();
+            return;
+        case "install":
+            const { runInstaller } = await import("./installer.js");
+            await runInstaller(rest);
+            return;
+        case "call":
+            await callToolFromCli(rest);
+            return;
+        case "version":
+        case "-v":
+        case "--version": {
+            console.log(packageVersion());
+            return;
+        }
+        case "help":
+        case "-h":
+        case "--help":
+            printHelp();
+            return;
+        default:
+            console.error(`Unknown command: ${cmd}`);
+            printHelp();
+            process.exit(1);
+    }
+}
+function printHelp() {
+    console.log(`tday - MCP server and installer for tday.com
+
+Usage:
+  tday install         Configure your AI agent (Claude Code, Cursor, Gemini CLI, Codex)
+  tday serve           Run the MCP server over stdio (invoked by agents)
+  tday call <tool> [json]
+                       Call one tday tool once and print JSON
+  tday version         Print version
+  tday help            Show this message
+
+Install from npm:
+  npx -y @tday-com/mcp install
+`);
+}
+async function callToolFromCli(args) {
+    const [toolName, ...jsonParts] = args;
+    if (!toolName) {
+        throw new Error("Usage: tday call <toolName> [jsonArgs]");
+    }
+    const jsonArgs = jsonParts.join(" ").trim() || "{}";
+    let parsed;
+    try {
+        parsed = JSON.parse(jsonArgs);
+    }
+    catch (err) {
+        throw new Error(`Invalid JSON arguments for ${toolName}: ${err.message}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("Tool arguments must be a JSON object.");
+    }
+    const config = await loadConfig();
+    const result = await callTool(toolName, parsed, config);
+    console.log(stringifyResult(result));
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/config.js

@@ -0,0 +1,62 @@
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const CONFIG_PATH = join(homedir(), ".tday", "config.json");
+const DEFAULT_WEB_URL = "https://tday.com";
+export async function loadConfig() {
+    const envApiBaseUrl = process.env.TDAY_API_URL;
+    const envWebBaseUrl = process.env.TDAY_WEB_URL;
+    const envToken = process.env.TDAY_TOKEN ?? null;
+    const defaultApiBaseUrl = normalizeBaseUrl(envApiBaseUrl ?? DEFAULT_WEB_URL);
+    const defaultWebBaseUrl = normalizeBaseUrl(envWebBaseUrl ?? deriveWebBaseUrl(defaultApiBaseUrl));
+    if (envToken) {
+        return {
+            apiBaseUrl: defaultApiBaseUrl,
+            webBaseUrl: defaultWebBaseUrl,
+            token: envToken,
+        };
+    }
+    const fileConfig = await readFirstConfig([CONFIG_PATH]);
+    const apiBaseUrl = normalizeBaseUrl(fileConfig?.apiBaseUrl ?? defaultApiBaseUrl);
+    const webBaseUrl = normalizeBaseUrl(fileConfig?.webBaseUrl ?? envWebBaseUrl ?? deriveWebBaseUrl(apiBaseUrl));
+    return {
+        apiBaseUrl,
+        webBaseUrl,
+        token: fileConfig?.token ?? null,
+    };
+}
+export function configPath() {
+    return CONFIG_PATH;
+}
+async function readFirstConfig(paths) {
+    for (const path of paths) {
+        try {
+            const raw = await readFile(path, "utf8");
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed === "object")
+                return parsed;
+        }
+        catch {
+        }
+    }
+    return null;
+}
+function normalizeBaseUrl(raw) {
+    const trimmed = raw.trim().replace(/\/+$/, "");
+    return trimmed.replace(/\/api$/i, "");
+}
+function deriveWebBaseUrl(apiBaseUrl) {
+    try {
+        const url = new URL(apiBaseUrl);
+        if (url.hostname.startsWith("api.")) {
+            url.hostname = url.hostname.slice(4);
+        }
+        url.pathname = "";
+        url.search = "";
+        url.hash = "";
+        return normalizeBaseUrl(url.toString());
+    }
+    catch {
+        return DEFAULT_WEB_URL;
+    }
+}

package/dist/download-safety.js

@@ -0,0 +1,73 @@
+import { lstat, mkdir, realpath } from "node:fs/promises";
+import { dirname, isAbsolute, resolve, relative, sep } from "node:path";
+export const ALLOWED_IMAGE_HOSTS = new Set([
+    "cdn.tday.com",
+    "video-cdn.communities.one",
+    "communities.one",
+    "media.brand.dev",
+    "asset.brandfetch.io",
+    "cdn.brandfetch.io",
+    "tday.com",
+    "www.tday.com",
+    "app.tday.com",
+]);
+export const MAX_IMAGE_BYTES = 50 * 1024 * 1024;
+export function validateImageUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error(`Invalid image URL: "${raw}"`);
+    }
+    if (url.protocol !== "https:") {
+        throw new Error(`Image URL must use HTTPS (got ${url.protocol})`);
+    }
+    if (!ALLOWED_IMAGE_HOSTS.has(url.hostname)) {
+        throw new Error(`Image host "${url.hostname}" is not allowed. Expected one of: ${[...ALLOWED_IMAGE_HOSTS].join(", ")}`);
+    }
+    return url;
+}
+export function sandboxFilePath(raw) {
+    const cwd = process.cwd();
+    const resolved = resolve(cwd, raw);
+    const rel = relative(cwd, resolved);
+    if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel) || resolve(cwd, rel) !== resolved) {
+        throw new Error(`File path must be inside the working directory. "${raw}" resolves outside of ${cwd}`);
+    }
+    return resolved;
+}
+export async function prepareOutputFilePath(raw, options = {}) {
+    const filePath = sandboxFilePath(raw);
+    const parentDir = dirname(filePath);
+    await mkdir(parentDir, { recursive: true });
+    const cwdReal = await realpath(process.cwd());
+    const parentReal = await realpath(parentDir);
+    if (!isInsideDirectory(cwdReal, parentReal)) {
+        throw new Error(`File path parent directory must stay inside the working directory and cannot traverse symlinks outside of ${process.cwd()}`);
+    }
+    try {
+        const existing = await lstat(filePath);
+        if (existing.isSymbolicLink()) {
+            throw new Error("Refusing to write to a symbolic link.");
+        }
+        if (!existing.isFile()) {
+            throw new Error("Refusing to write because the target path exists and is not a regular file.");
+        }
+        if (!options.overwrite) {
+            throw new Error("File already exists. Choose a new filePath or pass overwrite: true.");
+        }
+    }
+    catch (err) {
+        if (!isNodeError(err) || err.code !== "ENOENT")
+            throw err;
+    }
+    return filePath;
+}
+function isInsideDirectory(base, target) {
+    const rel = relative(base, target);
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+function isNodeError(err) {
+    return err instanceof Error && "code" in err;
+}