npm - @orchyn/mcp - Versions diffs - 1.1.0 - Mend

@orchyn/mcp 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/dist/oauth.js ADDED Viewed

@@ -0,0 +1,303 @@
+/**
+ * Hand-rolled OAuth 2.0 authorization server (RFC 6749 + RFC 7636 PKCE)
+ * implementing the MCP 2025-03-26 OAuth spec subset needed by Claude
+ * Desktop, Cursor, and OpenAI Agents SDK:
+ *
+ *   GET  /.well-known/oauth-authorization-server
+ *   GET  /.well-known/oauth-protected-resource
+ *   GET  /authorize            (Authorization Code + PKCE S256)
+ *   POST /token                (public client, no client auth)
+ *   GET  /oauth/callback       (our own loopback: orchyn Google sign-in result)
+ *
+ * The MCP access tokens issued at /token are opaque random strings bound to
+ * the orchyn JWT obtained through the Google sign-in flow.
+ */
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+export const SCOPE = "analyze:video";
+export const TOKEN_TTL_SECONDS = 3600;
+export function verifyPkce(codeVerifier, codeChallenge) {
+    if (!codeVerifier || !codeChallenge)
+        return false;
+    const digest = createHash("sha256").update(codeVerifier).digest("base64url");
+    return digest === codeChallenge;
+}
+export function isLoopbackUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    if (parsed.protocol !== "http:")
+        return false;
+    const host = parsed.hostname;
+    return (host === "localhost" ||
+        host === "127.0.0.1" ||
+        host === "[::1]" ||
+        host === "::1");
+}
+/** redirect_uri must be loopback (http://localhost|127.0.0.1|[::1]) or any https URL. */
+export function isAllowedRedirectUri(uri) {
+    let parsed;
+    try {
+        parsed = new URL(uri);
+    }
+    catch {
+        return false;
+    }
+    if (parsed.protocol === "https:")
+        return true;
+    if (parsed.protocol === "http:" && isLoopbackUrl(uri))
+        return true;
+    return false;
+}
+function base64Url(bytes) {
+    return bytes.toString("base64url");
+}
+function newToken() {
+    return base64Url(randomBytes(32));
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on("data", (c) => chunks.push(Buffer.from(c)));
+        req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+        req.on("error", reject);
+    });
+}
+function sendJson(res, status, body) {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, {
+        "content-type": "application/json",
+        "content-length": Buffer.byteLength(payload),
+        "cache-control": "no-store",
+    });
+    res.end(payload);
+}
+function sendRedirect(res, location) {
+    res.writeHead(302, {
+        location,
+        "cache-control": "no-store",
+    });
+    res.end();
+}
+function sendHtml(res, status, title, body) {
+    const payload = `<!doctype html><html><head><meta charset="utf-8"><title>${title}</title></head><body>${body}</body></html>`;
+    res.writeHead(status, { "content-type": "text/html; charset=utf-8" });
+    res.end(payload);
+}
+export class OAuthManager {
+    publicUrl;
+    client;
+    onSession;
+    pendingByOrchynState = new Map();
+    pendingByMcpCode = new Map();
+    sessions = new Map();
+    constructor(opts) {
+        this.publicUrl = opts.publicUrl.replace(/\/+$/, "");
+        this.client = opts.client;
+        this.onSession = opts.onSession;
+    }
+    /** GET /.well-known/oauth-authorization-server */
+    authorizationServerMetadata() {
+        return {
+            issuer: this.publicUrl,
+            authorization_endpoint: `${this.publicUrl}/authorize`,
+            token_endpoint: `${this.publicUrl}/token`,
+            response_types_supported: ["code"],
+            code_challenge_methods_supported: ["S256"],
+            token_endpoint_auth_methods_supported: ["none"],
+            scopes_supported: [SCOPE],
+            grant_types_supported: ["authorization_code"],
+        };
+    }
+    /** GET /.well-known/oauth-protected-resource */
+    protectedResourceMetadata() {
+        return {
+            resource: `${this.publicUrl}/mcp`,
+            authorization_servers: [this.publicUrl],
+        };
+    }
+    /** Verifies an MCP access token; returns the bound session or undefined. */
+    verifyToken(token) {
+        const session = this.sessions.get(token);
+        if (!session)
+            return undefined;
+        if (Date.now() > session.expiresAt) {
+            this.sessions.delete(token);
+            return undefined;
+        }
+        return session;
+    }
+    async handleAuthorize(req, res) {
+        const url = new URL(req.url ?? "/", this.publicUrl);
+        const params = url.searchParams;
+        if (params.get("response_type") !== "code") {
+            return this.sendAuthorizeError(res, params, "unsupported_response_type", "The authorization server only supports response_type=code.");
+        }
+        const codeChallenge = params.get("code_challenge") ?? "";
+        const method = params.get("code_challenge_method") ?? "";
+        if (!codeChallenge || method !== "S256") {
+            return this.sendAuthorizeError(res, params, "invalid_request", "PKCE is required: code_challenge and code_challenge_method=S256 must be provided.");
+        }
+        const clientId = params.get("client_id") ?? "";
+        if (!clientId) {
+            return this.sendAuthorizeError(res, params, "invalid_request", "Missing client_id.");
+        }
+        const redirectUri = params.get("redirect_uri") ?? "";
+        if (!redirectUri || !isAllowedRedirectUri(redirectUri)) {
+            return this.sendAuthorizeError(res, params, "invalid_request", "redirect_uri must be a loopback http://localhost, http://127.0.0.1, http://[::1] URL or an https URL.");
+        }
+        const scope = params.get("scope") ?? SCOPE;
+        const scopes = scope.split(/\s+/).filter(Boolean);
+        const unsupported = scopes.filter((s) => s !== SCOPE);
+        if (unsupported.length > 0) {
+            return this.sendAuthorizeError(res, params, "invalid_scope", `Unsupported scope(s): ${unsupported.join(", ")}. Supported: ${SCOPE}.`);
+        }
+        const orchynState = newToken();
+        const mcpAuthCode = newToken();
+        const pending = {
+            orchynState,
+            clientId,
+            redirectUri,
+            codeChallenge,
+            scopes,
+            mcpAuthCode,
+            clientState: params.get("state") ?? undefined,
+            createdAt: Date.now(),
+        };
+        this.pendingByOrchynState.set(orchynState, pending);
+        this.pendingByMcpCode.set(mcpAuthCode, pending);
+        // Ask the orchyn server to start a Google sign-in. We pre-seed ?state=
+        // with our own pending-request id; orchyn appends
+        // ?code=<completion>&redirect=... when it redirects back to us.
+        const ourCallback = `${this.publicUrl}/oauth/callback?state=${encodeURIComponent(orchynState)}`;
+        let redirectUrl;
+        try {
+            const res = await this.client.startGoogleSignIn(ourCallback);
+            redirectUrl = res.redirectUrl;
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return sendHtml(res, 502, "orchyn-mcp: sign-in unavailable", `<p>Could not reach the orchyn server to start sign-in: ${escapeHtml(msg)}</p>`);
+        }
+        return sendRedirect(res, redirectUrl);
+    }
+    /** GET /oauth/callback?state=<ours>&code=<orchyn completion code>&redirect=<path> */
+    async handleCallback(req, res) {
+        const url = new URL(req.url ?? "/", this.publicUrl);
+        const orchynState = url.searchParams.get("state") ?? "";
+        const completionCode = url.searchParams.get("code") ?? "";
+        const pending = this.pendingByOrchynState.get(orchynState);
+        if (!pending) {
+            return sendHtml(res, 400, "orchyn-mcp: sign-in failed", "<p>Unknown or expired sign-in request. Please close this tab and try again.</p>");
+        }
+        if (!completionCode) {
+            return sendHtml(res, 400, "orchyn-mcp: sign-in failed", "<p>The orchyn sign-in did not return a completion code. Please close this tab and try again.</p>");
+        }
+        let session;
+        try {
+            session = await this.client.exchangeCompletionCode(completionCode);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return sendHtml(res, 502, "orchyn-mcp: sign-in failed", `<p>Could not complete sign-in with the orchyn server: ${escapeHtml(msg)}</p>`);
+        }
+        pending.completed = true;
+        pending.orchynAccessToken = session.accessToken;
+        pending.orchynRefreshToken = session.refreshToken;
+        pending.orchynUser = session.user
+            ? { id: session.user.id, email: session.user.email, displayName: session.user.displayName }
+            : undefined;
+        // Courtesy persistence so stdio/CLI runs can reuse this session.
+        try {
+            await this.onSession?.(session);
+        }
+        catch {
+            // Non-fatal: the in-memory session still works.
+        }
+        // Redirect the browser back to the MCP client with our one-time code.
+        const clientRedirect = new URL(pending.redirectUri);
+        clientRedirect.searchParams.set("code", pending.mcpAuthCode);
+        if (pending.clientState) {
+            clientRedirect.searchParams.set("state", pending.clientState);
+        }
+        return sendRedirect(res, clientRedirect.toString());
+    }
+    /** POST /token (form-encoded, public client, PKCE verified) */
+    async handleToken(req, res) {
+        let bodyText;
+        try {
+            bodyText = await readBody(req);
+        }
+        catch {
+            return sendJson(res, 400, { error: "invalid_request" });
+        }
+        const params = new URLSearchParams(bodyText);
+        const grantType = params.get("grant_type");
+        if (grantType !== "authorization_code") {
+            return sendJson(res, 400, {
+                error: "unsupported_grant_type",
+                error_description: "Only grant_type=authorization_code is supported.",
+            });
+        }
+        const code = params.get("code") ?? "";
+        const pending = this.pendingByMcpCode.get(code);
+        if (!pending || !pending.completed) {
+            return sendJson(res, 400, { error: "invalid_grant", error_description: "Unknown or incomplete authorization code." });
+        }
+        const clientId = params.get("client_id") ?? "";
+        if (pending.clientId !== clientId) {
+            return sendJson(res, 400, { error: "invalid_grant", error_description: "client_id does not match the authorization request." });
+        }
+        const redirectUri = params.get("redirect_uri");
+        if (redirectUri !== null && redirectUri !== pending.redirectUri) {
+            return sendJson(res, 400, { error: "invalid_grant", error_description: "redirect_uri does not match the authorization request." });
+        }
+        const codeVerifier = params.get("code_verifier") ?? "";
+        if (!verifyPkce(codeVerifier, pending.codeChallenge)) {
+            return sendJson(res, 400, { error: "invalid_grant", error_description: "PKCE verification failed." });
+        }
+        this.pendingByMcpCode.delete(code);
+        this.pendingByOrchynState.delete(pending.orchynState);
+        const accessToken = newToken();
+        this.sessions.set(accessToken, {
+            orchynAccessToken: pending.orchynAccessToken ?? "",
+            orchynRefreshToken: pending.orchynRefreshToken,
+            orchynUser: pending.orchynUser,
+            clientId: pending.clientId,
+            scopes: pending.scopes,
+            expiresAt: Date.now() + TOKEN_TTL_SECONDS * 1000,
+        });
+        return sendJson(res, 200, {
+            access_token: accessToken,
+            token_type: "Bearer",
+            expires_in: TOKEN_TTL_SECONDS,
+            scope: pending.scopes.join(" "),
+        });
+    }
+    sendAuthorizeError(res, params, error, description) {
+        const redirectUri = params.get("redirect_uri") ?? "";
+        if (redirectUri && isAllowedRedirectUri(redirectUri)) {
+            const target = new URL(redirectUri);
+            target.searchParams.set("error", error);
+            target.searchParams.set("error_description", description);
+            const state = params.get("state");
+            if (state)
+                target.searchParams.set("state", state);
+            return sendRedirect(res, target.toString());
+        }
+        return sendHtml(res, 400, "orchyn-mcp: bad request", `<p>${escapeHtml(description)}</p>`);
+    }
+}
+function escapeHtml(input) {
+    return input
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+export function generateState() {
+    return randomUUID();
+}

package/dist/orchyn.js ADDED Viewed

@@ -0,0 +1,164 @@
+/**
+ * Typed client for the orchyn REST API.
+ *
+ * All API errors are normalized to `OrchynError`. 402 responses are
+ * detected specifically and exposed via the `paywall` property.
+ */
+export class OrchynError extends Error {
+    status;
+    code;
+    paywall;
+    body;
+    constructor(status, message, opts = {}) {
+        super(message);
+        this.name = "OrchynError";
+        this.status = status;
+        this.code = opts.code;
+        this.paywall = opts.paywall;
+        this.body = opts.body;
+    }
+}
+export class OrchynClient {
+    baseUrl;
+    tokenProvider;
+    constructor(baseUrl, tokenProvider) {
+        this.baseUrl = baseUrl.replace(/\/+$/, "");
+        this.tokenProvider = tokenProvider;
+    }
+    async request(method, path, opts = {}) {
+        const doRequest = async (accessToken) => {
+            const headers = {};
+            if (opts.body !== undefined) {
+                headers["content-type"] = "application/json";
+            }
+            if (accessToken) {
+                headers.authorization = `Bearer ${accessToken}`;
+            }
+            return fetch(`${this.baseUrl}${path}`, {
+                method,
+                headers,
+                body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+            });
+        };
+        let token = opts.token;
+        if (opts.auth && !token) {
+            token = await this.tokenProvider.getAccessToken();
+        }
+        if (opts.auth && !token) {
+            throw new OrchynError(401, "No orchyn access token available.");
+        }
+        let res = await doRequest(token);
+        if (res.status === 401 &&
+            opts.auth &&
+            this.tokenProvider.onUnauthorized) {
+            const refreshed = await this.tokenProvider.onUnauthorized();
+            if (refreshed) {
+                token = await this.tokenProvider.getAccessToken();
+                res = await doRequest(token);
+            }
+        }
+        return this.normalizeResponse(res, path);
+    }
+    async normalizeResponse(res, path) {
+        const text = await res.text();
+        let body;
+        try {
+            body = text ? JSON.parse(text) : undefined;
+        }
+        catch {
+            body = undefined;
+        }
+        const json = (body ?? {});
+        const errorMessage = typeof json.error === "string" ? json.error : `orchyn API error (${res.status})`;
+        if (res.status >= 200 && res.status < 300) {
+            return body;
+        }
+        if (res.status === 402) {
+            throw new OrchynError(402, errorMessage, {
+                paywall: {
+                    reason: typeof json.reason === "string" ? json.reason : undefined,
+                    used: typeof json.used === "number" ? json.used : undefined,
+                    max: typeof json.max === "number" ? json.max : undefined,
+                    cost: typeof json.cost === "number" ? json.cost : undefined,
+                },
+                body,
+            });
+        }
+        throw new OrchynError(res.status, errorMessage, {
+            code: typeof json.code === "string" ? json.code : undefined,
+            body,
+        });
+    }
+    async startVideoAnalysis(url, appId) {
+        return this.request("POST", "/mcp/analyze-video", {
+            auth: true,
+            body: appId !== undefined ? { url, appId } : { url },
+        });
+    }
+    /**
+     * Proxies a generic orchyn backend MCP tool (`get_social_media`,
+     * `discover_social_videos`, `understand_social_post`, …) through
+     * `POST /mcp` JSON-RPC. The backend enforces per-user credit billing;
+     * tool-level failures surface as OrchynError with the backend message.
+     */
+    async callTool(name, args) {
+        const rpc = await this.request("POST", "/mcp", {
+            auth: true,
+            body: {
+                jsonrpc: "2.0",
+                id: Date.now(),
+                method: "tools/call",
+                params: { name, arguments: args },
+            },
+        });
+        if (rpc && typeof rpc === "object" && rpc.error !== undefined && rpc.error !== null) {
+            const err = rpc.error;
+            throw new OrchynError(err.code === -32002 ? 402 : 400, typeof err.message === "string" ? err.message : "orchyn MCP tool call failed");
+        }
+        const result = (rpc.result ?? {});
+        if (result.isError) {
+            const text = result.content
+                ?.filter((c) => c.type === "text")
+                .map((c) => String(c.text ?? ""))
+                .join("\n");
+            throw new OrchynError(400, text || "orchyn MCP tool call failed");
+        }
+        return {
+            contentBlocks: result.content ?? [],
+            structured: result.structuredContent,
+        };
+    }
+    async getJob(jobId) {
+        return this.request("GET", `/ai/analyze-post?jobId=${encodeURIComponent(jobId)}`, {
+            auth: true,
+        });
+    }
+    async me() {
+        return this.request("GET", "/auth/me", { auth: true });
+    }
+    async exchangeCompletionCode(code, workspaceId) {
+        return this.request("POST", "/auth/oauth/complete", {
+            auth: false,
+            body: workspaceId !== undefined ? { code, workspaceId } : { code },
+        });
+    }
+    /** Starts a Google sign-in for the given redirect URL; returns the Google redirectUrl. */
+    async startGoogleSignIn(redirect) {
+        return this.request("POST", "/auth/google/start", {
+            auth: false,
+            body: { redirect },
+        });
+    }
+    async login(email, password) {
+        return this.request("POST", "/auth/login", {
+            auth: false,
+            body: { email, password },
+        });
+    }
+    async refresh(refreshToken) {
+        return this.request("POST", "/auth/refresh", {
+            auth: false,
+            body: { refreshToken },
+        });
+    }
+}

package/dist/video.js ADDED Viewed

@@ -0,0 +1,129 @@
+/**
+ * URL validation + the analyze_video workflow: start the job, then poll until
+ * the analysis is done (or fails).
+ */
+export const POLL_INTERVAL_MS = 2000;
+export const POLL_TIMEOUT_MS = 300_000;
+const SUPPORTED_HOSTS = new Set([
+    "tiktok.com",
+    "vm.tiktok.com",
+    "instagram.com",
+    "instagr.am",
+    "youtube.com",
+    "youtu.be",
+    "m.youtube.com",
+    "youtube-nocookie.com",
+    "m.tiktok.com",
+]);
+export function validateVideoUrl(rawUrl) {
+    if (typeof rawUrl !== "string" || rawUrl.trim() === "") {
+        return { ok: false, error: "url must be a non-empty string." };
+    }
+    let parsed;
+    try {
+        parsed = new URL(rawUrl.trim());
+    }
+    catch {
+        return { ok: false, error: "url is not a valid URL." };
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        return { ok: false, error: "url must use http or https." };
+    }
+    let host = parsed.hostname.toLowerCase();
+    if (host.startsWith("www."))
+        host = host.slice(4);
+    if (host === "youtube.com" || host === "youtu.be") {
+        // accept all youtube.com paths, incl. /shorts/<id>
+        return { ok: true, url: parsed.toString() };
+    }
+    if (SUPPORTED_HOSTS.has(host)) {
+        return { ok: true, url: parsed.toString() };
+    }
+    return {
+        ok: false,
+        error: "url host is not supported. Supported: tiktok.com, vm.tiktok.com, instagram.com, instagr.am, youtube.com, youtu.be, m.youtube.com (and /shorts).",
+    };
+}
+export class JobTimeoutError extends Error {
+    constructor(jobId, elapsedMs, lastStatus) {
+        super(`Timed out after ${Math.round(elapsedMs / 1000)}s waiting for analysis job ${jobId} to finish.` +
+            (lastStatus?.contentPreview ? ` Partial content: ${lastStatus.contentPreview}` : ""));
+        this.name = "JobTimeoutError";
+    }
+}
+/**
+ * Polls a job until state is "done" or "error".
+ */
+export async function pollUntilDone(client, jobId, opts = {}) {
+    const pollIntervalMs = opts.pollIntervalMs ?? POLL_INTERVAL_MS;
+    const timeoutMs = opts.timeoutMs ?? POLL_TIMEOUT_MS;
+    const startedAt = Date.now();
+    let last;
+    for (;;) {
+        const elapsedMs = Date.now() - startedAt;
+        if (elapsedMs >= timeoutMs) {
+            throw new JobTimeoutError(jobId, elapsedMs, last);
+        }
+        const status = await client.getJob(jobId);
+        last = status;
+        opts.onPoll?.(status);
+        if (status.state === "done")
+            return status;
+        if (status.state === "error")
+            return status;
+        await new Promise((r) => setTimeout(r, pollIntervalMs));
+    }
+}
+/**
+ * Full tool workflow: start the analysis, poll until done, return a
+ * JSON-serializable result. Throws OrchynError on API-level failures
+ * (e.g. 402 paywall).
+ */
+export async function runVideoAnalysis(client, url, opts = {}) {
+    const job = await client.startVideoAnalysis(url, opts.appId);
+    const status = await pollUntilDone(client, job.jobId, opts);
+    const result = {
+        ok: status.state === "done",
+        jobId: status.jobId,
+        state: status.state,
+        platform: job.platform,
+        provider: status.provider ?? job.provider,
+        analysis: status.analysis,
+        contentPreview: status.contentPreview,
+        error: status.error,
+        elapsedMs: status.elapsedMs,
+    };
+    if (result.ok) {
+        result.job = {
+            ok: job.ok,
+            jobId: job.jobId,
+            state: job.state,
+            platform: job.platform,
+            provider: job.provider,
+            appId: job.appId,
+            workspaceId: job.workspaceId,
+            cost: job.cost,
+            freeGrant: job.freeGrant,
+            post: job.post,
+        };
+    }
+    return result;
+}
+export function formatPaywallError(err) {
+    const p = err.paywall;
+    const parts = [];
+    if (p?.reason)
+        parts.push(`reason: ${p.reason}`);
+    if (p?.used !== undefined && p?.max !== undefined) {
+        parts.push(`credits used: ${p.used}/${p.max}`);
+    }
+    else if (p?.used !== undefined) {
+        parts.push(`credits used: ${p.used}`);
+    }
+    if (p?.cost !== undefined)
+        parts.push(`cost: ${p.cost}`);
+    const detail = parts.length > 0 ? ` (${parts.join(", ")})` : "";
+    return (`Your orchyn account has no credits left for this analysis${detail}. ` +
+        `Top up or check your usage in the orchyn dashboard, then try again. ` +
+        `Note: the first analysis is covered by the free grant.`);
+}

package/package.json ADDED Viewed

@@ -0,0 +1,37 @@
+{
+  "name": "@orchyn/mcp",
+  "version": "1.1.0",
+  "description": "MCP server for orchyn - AI video analysis for TikTok, Instagram, and YouTube links",
+  "type": "module",
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "orchyn-mcp": "dist/index.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc -w",
+    "start": "node dist/index.js",
+    "login": "node dist/index.js login",
+    "test": "vitest run",
+    "prepare": "npm run build"
+  },
+  "keywords": ["mcp", "orchyn", "video", "analysis", "tiktok", "instagram", "youtube"],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.16.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^3.1.0"
+  }
+}