@orchyn/mcp 1.1.2 → 1.2.1

package/README.md

@@ -38,16 +38,25 @@ npx @orchyn/mcp login   # one-time sign-in (Google)
 
 | Tool | Credits | Description |
 |------|---------|-------------|
-| `analyze_video` | first free | Start an AI analysis of a TikTok/Instagram/YouTube video; polls until done and returns the full analysis. |
-| `get_social_media` | 1 | Fetch a post's media from a URL: contentType, title, caption, author, stats, direct media URLs + inline thumbnail image. |
-| `discover_social_videos` | 2 | Find recent videos for a niche (YouTube search; TikTok/Instagram via Apify). |
-| `understand_social_post` | 10 | Import a post URL AND analyze it with multimodal AI over the actual video/images: summary, hook strength, viral triggers, format breakdown, variation ideas. |
+| `analyze_post` | first free* | **Preferred.** Analyze any post (video, image, carousel/slideshow) from a TikTok/Instagram/YouTube/X-Twitter URL — imports the media and runs AI analysis over the actual content (video frames, carousel images, caption). Returns a `jobId` to poll via `GET /ai/analyze-post`. *First analysis free per workspace via the dashboard free grant.* |
+| `analyze_video` | first free* | **Deprecated alias of `analyze_post`** — kept for backwards compatibility. Use `analyze_post` for new integrations. |
+| `get_social_media` | 1 | Fetch a post's media from a URL: `contentType` (video/image/carousel/slideshow), title, caption, author, stats, direct media URLs **+ inline thumbnail image in chat**. |
+| `discover_social_videos` | 2 | Find recent posts for a niche (YouTube via `yt-dlp` search; TikTok/Instagram via Apify). Returns up to 6 posts with stats **and inline thumbnails** — see *Images in chat* below. |
+| `understand_social_post` | 10 | Import a post URL **and** analyze it with multimodal AI over the actual video/images: factual `whatHappens` description, hook strength, viral triggers, format breakdown, variation ideas, suggested hook/hashtags. Includes inline thumbnails. |
 
-All tools require a connected orchyn account and are billed against your
-orchyn credit balance (`POST /billing/mcp-credits/checkout` tops up).
+All tools require a connected orchyn account and are billed against your orchyn credit balance (`POST /billing/mcp-credits/checkout` tops up).
 
-The server starts the analysis on the orchyn backend, polls until the analysis
-finishes, and returns the full result (analysis, job metadata, cost) as JSON.
+`*` `analyze_post`/`analyze_video` bill against **workspace** credits (first free grant); the other three bill against **per-user MCP** credits (never tied to an app/workspace).
+
+## Images in Claude / ChatGPT chat
+
+Every tool that returns posts also renders **inline thumbnails** directly in the chat:
+
+- `get_social_media` / `understand_social_post` / `analyze_post` — up to 4 frames inline (poster + carousel slides). The full `mediaItems[].preview_url` + `thumbnailUrl` stay in `structuredContent` for the model to reason over.
+- `discover_social_videos` — each discovered post shows its thumbnail inline (up to 4 of the 6 results at once). Say **"next"** or **"show more"** — Claude will re-call `discover_social_videos` with a larger `limit` or paginate. Say **"analyze the 2nd one"** — Claude calls `analyze_post` or `understand_social_post` on that URL.
+- **Batch analysis** — ask "analyze all 4" or "understand these 3 in batch" and Claude will call `analyze_post`/`understand_social_post` once per URL in parallel and summarize. For large batches, `discover_social_videos` + a follow-up `analyze_post` per URL is the recommended flow.
+
+> The backend's `analyze_post` now watches the **actual video/images** (direct MP4, YouTube `fileUri`, or 6 carousel frames via Gemini multimodal) — not just the caption. The analysis includes a `whatHappens` field describing exactly what is seen.
 
 ## Prerequisites
 
@@ -229,15 +238,14 @@ per the MCP 2025-03-26 spec):
   orchyn session (valid 1 hour)
 - every MCP RPC validates the Bearer token against the session map
 
-## Supported video URLs
+## Supported URLs
 
 - TikTok: `tiktok.com/*`, `vm.tiktok.com/*` (and `www.`/`m.` subdomains)
-- Instagram: `instagram.com/*` (reels, posts), `instagr.am/*`
+- Instagram: `instagram.com/*` (reels, posts, carousels), `instagr.am/*`
 - YouTube: `youtube.com/*` (including `/shorts/`), `youtu.be/*`, `m.youtube.com/*`
-- X/Twitter: `x.com/*`, `twitter.com/*` — supported by `get_social_media` and
-  `understand_social_post` (`analyze_video` covers TikTok/Instagram/YouTube only)
+- X/Twitter: `x.com/*`, `twitter.com/*`
 
-Other hosts are rejected by the tools.
+All tools accept these hosts. `analyze_post` (and its `analyze_video` alias) additionally handles **image, carousel and slideshow** posts — not just video.
 
 ## Troubleshooting
 
@@ -245,9 +253,9 @@ Other hosts are rejected by the tools.
   `ORCHYN_ACCESS_TOKEN`.
 - **402 paywall / `insufficient MCP credits`**: your orchyn account is out of
   credits for this tool. Each call costs: `get_social_media` 1,
-  `discover_social_videos` 2, `understand_social_post` 10, `analyze_video`
-  first-call free. Top up via the orchyn dashboard billing page or
-  `POST /billing/mcp-credits/checkout`.
+  `discover_social_videos` 2, `understand_social_post` 10, `analyze_post`/
+  `analyze_video` first-call free* (see Tools). Top up via the orchyn dashboard
+  billing page or `POST /billing/mcp-credits/checkout`.
 - **Expired refresh token**: the stored refresh token was rejected by the
   orchyn server. Run `npx @orchyn/mcp login` again to re-authenticate.
 - **`Could not reach the orchyn server`**: `ORCHYN_BASE_URL` is unreachable or

package/dist/index.js

@@ -18,18 +18,7 @@ import { getBaseUrl, getPublicUrl, getPort, getCredentialsFile, getTransportMode
 import { AuthManager, OrchynAuthError, createHttpTokenProvider, createStdioTokenProvider } from "./auth.js";
 import { OrchynClient, OrchynError } from "./orchyn.js";
 import { OAuthManager } from "./oauth.js";
-import { formatPaywallError, runVideoAnalysis, validateVideoUrl } from "./video.js";
-const TOOL_NAME = "analyze_video";
-const TOOL_DESCRIPTION = "Start an AI analysis of a TikTok, Instagram, or YouTube video from its link. " +
-    "Requires a connected orchyn account; consumes orchyn credits (first analysis free). " +
-    "Returns the analysis result once finished.";
-const TOOL_INPUT_SCHEMA = z
-    .object({
-    url: z
-        .string()
-        .describe("Public video URL (tiktok.com, instagram.com, youtube.com, youtu.be, or common shortlinks)."),
-})
-    .strict();
+import { formatPaywallError, runVideoAnalysis, validatePostUrl } from "./video.js";
 function toToolResult(proxy) {
     const images = proxy.contentBlocks
         .filter((c) => c.type === "image")
@@ -48,19 +37,25 @@ function toolError(prefix, err) {
 export function createServer(opts) {
     const server = new McpServer({
         name: "orchyn-mcp",
-        version: "1.0.0",
+        version: "1.1.0",
     });
-    server.registerTool(TOOL_NAME, {
-        title: "Analyze Video",
-        description: TOOL_DESCRIPTION,
-        inputSchema: TOOL_INPUT_SCHEMA,
+    server.registerTool("analyze_post", {
+        title: "Analyze Post",
+        description: "Analyze a social post (video, image, carousel/slideshow) from its link — " +
+            "imports the media and runs AI analysis over the actual content (video frames, carousel images, caption). " +
+            "Supports TikTok, Instagram, YouTube and X/Twitter. Returns the full analysis once finished.",
+        inputSchema: z
+            .object({
+            url: z.string().describe("Public post URL (TikTok/Instagram/YouTube/X or shortlinks)."),
+        })
+            .strict(),
     }, async (args, extra) => {
         let session;
         if (extra.authInfo?.token && opts.resolveSession) {
             session = opts.resolveSession(extra.authInfo.token);
         }
         const client = opts.makeClient(session);
-        const validation = validateVideoUrl(args.url);
+        const validation = validatePostUrl(args.url);
         if (!validation.ok) {
             return {
                 content: [{ type: "text", text: `Invalid url: ${validation.error}` }],
@@ -69,33 +64,54 @@ export function createServer(opts) {
         }
         try {
             const result = await runVideoAnalysis(client, validation.url);
-            return {
-                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-            };
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
         }
         catch (err) {
             if (err instanceof OrchynError && err.paywall) {
                 return {
-                    content: [
-                        {
-                            type: "text",
-                            text: `Analysis blocked: ${formatPaywallError(err)}\n\nHTTP ${err.status}: ${err.message}`,
-                        },
-                    ],
+                    content: [{ type: "text", text: `Analysis blocked: ${formatPaywallError(err)}\n\nHTTP ${err.status}: ${err.message}` }],
                     isError: true,
                 };
             }
             const msg = err instanceof Error ? err.message : String(err);
+            return { content: [{ type: "text", text: `Analysis failed: ${msg}` }], isError: true };
+        }
+    });
+    server.registerTool("analyze_video", {
+        title: "Analyze Video",
+        description: "[Deprecated — use analyze_post] Alias of analyze_post — analyzes any post type.",
+        inputSchema: z
+            .object({
+            url: z.string().describe("Public post URL (TikTok/Instagram/YouTube/X or shortlinks)."),
+        })
+            .strict(),
+    }, async (args, extra) => {
+        let session;
+        if (extra.authInfo?.token && opts.resolveSession) {
+            session = opts.resolveSession(extra.authInfo.token);
+        }
+        const client = opts.makeClient(session);
+        const validation = validatePostUrl(args.url);
+        if (!validation.ok) {
             return {
-                content: [
-                    {
-                        type: "text",
-                        text: `Video analysis failed: ${msg}`,
-                    },
-                ],
+                content: [{ type: "text", text: `Invalid url: ${validation.error}` }],
                 isError: true,
             };
         }
+        try {
+            const result = await runVideoAnalysis(client, validation.url);
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            if (err instanceof OrchynError && err.paywall) {
+                return {
+                    content: [{ type: "text", text: `Analysis blocked: ${formatPaywallError(err)}\n\nHTTP ${err.status}: ${err.message}` }],
+                    isError: true,
+                };
+            }
+            const msg = err instanceof Error ? err.message : String(err);
+            return { content: [{ type: "text", text: `Analysis failed: ${msg}` }], isError: true };
+        }
     });
     server.registerTool("get_social_media", {
         title: "Get Social Media",
@@ -119,12 +135,14 @@ export function createServer(opts) {
     server.registerTool("discover_social_videos", {
         title: "Discover Social Videos",
         description: "Discover recent videos/posts for a niche. YouTube via search; TikTok & Instagram via Apify. " +
-            "Consumes 2 orchyn credits.",
+            "Returns inline thumbnails (up to 4) so they show in chat. Say \"next\" to paginate (offset), " +
+            "or \"analyze the 2nd one\" / \"analyze all\" for batch analysis. Consumes 2 orchyn credits.",
         inputSchema: z
             .object({
             niche: z.string().describe("Niche/topic, e.g. 'fitness'."),
             keywords: z.string().optional().describe("Optional extra keywords."),
             limit: z.number().int().optional().describe("Max results (default 6)."),
+            offset: z.number().int().optional().describe("Skip first N results — for 'next' pagination."),
             platform: z
                 .enum(["youtube", "tiktok", "instagram", "any"])
                 .optional()

package/dist/video.js

@@ -4,7 +4,7 @@
  */
 export const POLL_INTERVAL_MS = 2000;
 export const POLL_TIMEOUT_MS = 300_000;
-const SUPPORTED_HOSTS = new Set([
+const SUPPORTED_HOSTS_VIDEO = new Set([
     "tiktok.com",
     "vm.tiktok.com",
     "instagram.com",
@@ -15,7 +15,13 @@ const SUPPORTED_HOSTS = new Set([
     "youtube-nocookie.com",
     "m.tiktok.com",
 ]);
-export function validateVideoUrl(rawUrl) {
+const SUPPORTED_HOSTS_POST = new Set([
+    ...SUPPORTED_HOSTS_VIDEO,
+    "x.com",
+    "twitter.com",
+    "mobile.twitter.com",
+]);
+function validateUrl(rawUrl, allowed) {
     if (typeof rawUrl !== "string" || rawUrl.trim() === "") {
         return { ok: false, error: "url must be a non-empty string." };
     }
@@ -36,7 +42,7 @@ export function validateVideoUrl(rawUrl) {
         // accept all youtube.com paths, incl. /shorts/<id>
         return { ok: true, url: parsed.toString() };
     }
-    if (SUPPORTED_HOSTS.has(host)) {
+    if (allowed.has(host)) {
         return { ok: true, url: parsed.toString() };
     }
     return {
@@ -44,6 +50,12 @@ export function validateVideoUrl(rawUrl) {
         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 function validateVideoUrl(rawUrl) {
+    return validateUrl(rawUrl, SUPPORTED_HOSTS_VIDEO);
+}
+export function validatePostUrl(rawUrl) {
+    return validateUrl(rawUrl, SUPPORTED_HOSTS_POST);
+}
 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.` +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orchyn/mcp",
-  "version": "1.1.2",
+  "version": "1.2.1",
   "description": "MCP server for orchyn - fetch, discover and understand TikTok/Instagram/YouTube/X posts with AI (media metadata, niche discovery, hook & viral analysis)",
   "type": "module",
   "main": "dist/index.js",