@orchyn/mcp 1.4.0 → 1.5.0

package/README.md

@@ -41,20 +41,28 @@ npx @orchyn/mcp login   # one-time sign-in (Google)
 | `analyze_post` | first free* | **Preferred.** Analyze any post (video, image, carousel/slideshow) from a TikTok/Instagram/YouTube/X-Twitter/Douyin/Xiaohongshu/Bilibili 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.* |
 | `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_posts` | 2 | **Preferred.** Find recent posts (video/image/carousel/slideshow) for a niche on YouTube, TikTok, Instagram, Douyin, Xiaohongshu, X/Twitter or Bilibili (via TikHub). Each post includes title/caption, views/likes/comments, author, `externalUrl` + **inline thumbnails (4 at a time)** — see *Images in chat* below. Supports `limit`/`offset` pagination (“next”). |
+| `get_user_posts` | 2 | List recent posts by a creator handle (e.g. `@zoundsapp`) on TikTok, Instagram, YouTube, Douyin, Xiaohongshu, X/Twitter or Bilibili — title/caption, `thumbnailUrl`, `externalUrl`, views/likes/comments, **inline thumbnails (up to 4)**. Use to scan a whole profile or spot patterns across an account. |
+| `analyze_creator_profile` | 15 | Deep-dive a whole creator profile on TikTok, Instagram, YouTube, Douyin, Xiaohongshu, X/Twitter or Bilibili: fetches recent posts, runs multimodal Gemini on up to 3, then synthesizes a profile report — creator summary, niche, content themes, hook styles, strengths/weaknesses, engagement patterns, audience insights, variation ideas, collaboration fit. |
+| `get_post_comments` | 2 | Fetch top comments for a post URL on TikTok, Instagram, YouTube, Douyin, X/Twitter or Bilibili, plus keyword clusters from TikTok Analytics when available — audience sentiment/audience-signal analysis. |
+| `search_creators` | 2 | Search creators by niche/keyword via TikHub on TikTok, Instagram, Xiaohongshu, YouTube or Douyin — username, nickname, follower count, signature, verified status. Use to find influencers to vet or analyze. |
+| `get_similar_creators` | 2 | Find lookalike creators for a given handle (TikTok similar-user recommendations or Instagram similar users) — “if this creator works, here are more like them”. |
+| `discover_sounds` | 2 | Discover trending sounds/music for a keyword on TikTok or Instagram — sound choice is a huge ranking signal for TikTok virality. Returns title, artist, duration, play/cover URLs. |
 | `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. |
 | `check_orchyn_credits` | free | Check your MCP credit balance, billing URL and pack size — no cost. |
 | `buy_orchyn_credits` | free | Get a Stripe Checkout URL to buy a credit pack — open it to pay; credits are added automatically. No cost to call. Also at `https://orchyn.com/settings?tab=billing`. |
 
 All tools require a connected orchyn account and are billed against your orchyn credit balance (`POST /billing/mcp-credits/checkout` tops up).
 
-`*` `analyze_post` bills against **workspace** credits (first free grant); the other tools bill against **per-user MCP** credits (never tied to an app/workspace).
+**Every tool's first use is free per user** — try any tool once before paying. After the free first use, each call bills your credit balance. **Platform admins always bypass credit debiting** (free calls). `check_orchyn_credits` lists which tools still have a free first use.
+
+`*` `analyze_post` also bills against **workspace** credits (first free grant); the other tools 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_posts` — each discovered post shows its thumbnail inline (up to 4 of the 6 results at once) together with its title/caption + views/likes/comments. Say **"next"** or **"show more"** — Claude will re-call `discover_social_posts` with `offset` pagination. Say **"analyze the 2nd one"** — Claude calls `analyze_post` or `understand_social_post` on that URL.
+- `discover_social_posts` / `get_user_posts` / `analyze_creator_profile` — each returned post shows its thumbnail inline (up to 4 at once) together with its title/caption + views/likes/comments. Say **"next"** or **"show more"** — Claude will re-call with `offset`/`limit` pagination. 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_posts` + 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.
@@ -256,10 +264,13 @@ All tools accept these hosts and handle **video, image, carousel and slideshow**
 - **`Not authenticated with orchyn` / 401**: run `npx @orchyn/mcp login` or set
   `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_posts` 2, `understand_social_post` 10, `analyze_post`
-  first-call free* (see Tools). Top up via `buy_orchyn_credits`, `check_orchyn_credits`,
-  or the orchyn dashboard at `https://orchyn.com/settings?tab=billing`.
+  credits for this tool. Every tool has **one free first use per user**; after
+  that each call costs: `get_social_media` 1, `discover_social_posts` /
+  `get_user_posts` / `get_post_comments` / `search_creators` /
+  `get_similar_creators` / `discover_sounds` 2 each, `understand_social_post` 10,
+  `analyze_creator_profile` 15, `analyze_post` first-call free* (see Tools). Top up
+  via `buy_orchyn_credits`, `check_orchyn_credits`, or the orchyn dashboard at
+  `https://orchyn.com/settings?tab=billing`.
 - **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/shared/tools-def.js

@@ -9,55 +9,55 @@ export const TOOL_DEFINITIONS = [
     {
         name: "get_social_media",
         title: "Get Social Media",
-        description: "Fetch a social post's media from a TikTok, Instagram, YouTube, X/Twitter, Douyin, Xiaohongshu or Bilibili URL: contentType (video/image/carousel/slideshow), title, caption, author, stats and direct media URLs. Returns an inline thumbnail image. Consumes 1 orchyn credit.",
+        description: "Fetch a social post's media from a TikTok, Instagram, YouTube, X/Twitter, Douyin, Xiaohongshu or Bilibili URL: contentType (video/image/carousel/slideshow), title, caption, author, stats and direct media URLs. Returns an inline thumbnail image. Consumes 1 orchyn credit. First use free per user.",
         inputSchema: z.object({ url: z.string().describe("Full public post URL.") }).strict(),
     },
     {
         name: "discover_social_posts",
         title: "Discover Social Posts",
-        description: "Discover recent posts (video, image, carousel, slideshow) for a niche on YouTube, TikTok, Instagram, Douyin, Xiaohongshu, X/Twitter or Bilibili via TikHub. Each post includes title/caption, thumbnailUrl, externalUrl, views/likes/comments and 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.",
+        description: "Discover recent posts (video, image, carousel, slideshow) for a niche on YouTube, TikTok, Instagram, Douyin, Xiaohongshu, X/Twitter or Bilibili via TikHub. Each post includes title/caption, thumbnailUrl, externalUrl, views/likes/comments and 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. First use free per user.",
         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", "douyin", "xiaohongshu", "twitter", "bilibili", "any"]).optional().describe("Platform to search (default youtube).") }).strict(),
     },
     {
         name: "get_user_posts",
         title: "Get User Posts",
-        description: "List recent posts by a creator handle (e.g. @zoundsapp) via TikHub on TikTok, Instagram, YouTube, Douyin, Xiaohongshu, X/Twitter or Bilibili. Each post includes title/caption, thumbnailUrl, externalUrl, views/likes/comments and inline thumbnails (up to 4) so they show in chat. Use this when Claude needs to pull more posts from the same account to spot a pattern, or to scan a whole profile. Consumes 2 orchyn credits.",
+        description: "List recent posts by a creator handle (e.g. @zoundsapp) via TikHub on TikTok, Instagram, YouTube, Douyin, Xiaohongshu, X/Twitter or Bilibili. Each post includes title/caption, thumbnailUrl, externalUrl, views/likes/comments and inline thumbnails (up to 4) so they show in chat. Use this when Claude needs to pull more posts from the same account to spot a pattern, or to scan a whole profile. Consumes 2 orchyn credits. First use free per user.",
         inputSchema: z.object({ username: z.string().describe("Creator handle, e.g. 'zoundsapp' or '@zoundsapp'."), platform: z.enum(["tiktok", "instagram", "youtube", "douyin", "xiaohongshu", "twitter", "bilibili"]).optional().describe("Which platform (default tiktok)."), limit: z.number().int().optional().describe("Max posts (default 6).") }).strict(),
     },
     {
         name: "analyze_creator_profile",
         title: "Analyze Creator Profile",
-        description: "Deep-dive a whole creator profile via TikHub on TikTok, Instagram, YouTube, Douyin, Xiaohongshu, X/Twitter or Bilibili: fetch recent posts, run multimodal Gemini on up to 3, then synthesize a profile report — creator summary, niche, content themes, hook styles, strengths/weaknesses, engagement patterns, audience insights, variation ideas, collaboration fit. Consumes 15 orchyn credits.",
+        description: "Deep-dive a whole creator profile via TikHub on TikTok, Instagram, YouTube, Douyin, Xiaohongshu, X/Twitter or Bilibili: fetch recent posts, run multimodal Gemini on up to 3, then synthesize a profile report — creator summary, niche, content themes, hook styles, strengths/weaknesses, engagement patterns, audience insights, variation ideas, collaboration fit. Consumes 15 orchyn credits. First use free per user.",
         inputSchema: z.object({ username: z.string().describe("Creator handle, e.g. 'zoundsapp'."), platform: z.enum(["tiktok", "instagram", "youtube", "douyin", "xiaohongshu", "twitter", "bilibili"]).optional().describe("Which platform (default tiktok)."), limit: z.number().int().optional().describe("Posts to fetch (default 6; first 3 analyzed)."), focus: z.string().optional().describe("Extra instruction for the profile synthesis.") }).strict(),
     },
     {
         name: "get_post_comments",
         title: "Get Post Comments",
-        description: "Fetch top comments for a post URL via TikHub on TikTok, Instagram, YouTube, Douyin, X/Twitter or Bilibili (plus keyword clusters from TikTok Analytics when available) — audience sentiment/audience-signal analysis. Consumes 2 orchyn credits.",
+        description: "Fetch top comments for a post URL via TikHub on TikTok, Instagram, YouTube, Douyin, X/Twitter or Bilibili (plus keyword clusters from TikTok Analytics when available) — audience sentiment/audience-signal analysis. Consumes 2 orchyn credits. First use free per user.",
         inputSchema: z.object({ url: z.string().describe("Full public post URL (TikTok/Instagram/YouTube/Douyin/X/Bilibili)."), limit: z.number().int().optional().describe("Max comments (default 20).") }).strict(),
     },
     {
         name: "search_creators",
         title: "Search Creators",
-        description: "Search creators by niche/keyword via TikHub on TikTok, Instagram, Xiaohongshu, YouTube or Douyin — username, nickname, follower count, signature, verified status. Use to find influencers to vet or analyze. Consumes 2 orchyn credits.",
+        description: "Search creators by niche/keyword via TikHub on TikTok, Instagram, Xiaohongshu, YouTube or Douyin — username, nickname, follower count, signature, verified status. Use to find influencers to vet or analyze. Consumes 2 orchyn credits. First use free per user.",
         inputSchema: z.object({ keyword: z.string().describe("Niche/keyword, e.g. 'fitness' or a creator name."), platform: z.enum(["tiktok", "instagram", "xiaohongshu", "youtube", "douyin"]).optional().describe("Which platform (default tiktok)."), count: z.number().int().optional().describe("Max creators (default 8).") }).strict(),
     },
     {
         name: "get_similar_creators",
         title: "Get Similar Creators",
-        description: "Find lookalike creators for a given handle via TikHub — TikTok similar-user recommendations or Instagram similar users. Useful for scaling: 'if this creator works, here are more like them'. Consumes 2 orchyn credits.",
+        description: "Find lookalike creators for a given handle via TikHub — TikTok similar-user recommendations or Instagram similar users. Useful for scaling: 'if this creator works, here are more like them'. Consumes 2 orchyn credits. First use free per user.",
         inputSchema: z.object({ username: z.string().describe("Seed creator handle, e.g. 'zoundsapp'."), platform: z.enum(["tiktok", "instagram"]).optional().describe("Which platform (default tiktok).") }).strict(),
     },
     {
         name: "discover_sounds",
         title: "Discover Sounds",
-        description: "Discover trending sounds/music for a keyword on TikTok or Instagram via TikHub — the sound is a huge ranking signal for TikTok virality. Returns title, artist, duration, play/cover URLs. Consumes 2 orchyn credits.",
+        description: "Discover trending sounds/music for a keyword on TikTok or Instagram via TikHub — the sound is a huge ranking signal for TikTok virality. Returns title, artist, duration, play/cover URLs. Consumes 2 orchyn credits. First use free per user.",
         inputSchema: z.object({ keyword: z.string().describe("Niche/keyword, e.g. 'gym'."), platform: z.enum(["tiktok", "instagram"]).optional().describe("Which platform (default tiktok)."), count: z.number().int().optional().describe("Max sounds (default 6).") }).strict(),
     },
     {
         name: "understand_social_post",
         title: "Understand Social Post",
-        description: "Import a social post URL AND understand it with multimodal AI over the actual video/images: summary, hook strength, viral triggers, format breakdown and variation ideas. Includes the thumbnail. Supports TikTok, Instagram, YouTube, X/Twitter, Douyin, Xiaohongshu and Bilibili. Consumes 10 orchyn credits.",
+        description: "Import a social post URL AND understand it with multimodal AI over the actual video/images: summary, hook strength, viral triggers, format breakdown and variation ideas. Includes the thumbnail. Supports TikTok, Instagram, YouTube, X/Twitter, Douyin, Xiaohongshu and Bilibili. Consumes 10 orchyn credits. First use free per user.",
         inputSchema: z.object({ url: z.string().describe("Full public post URL (TikTok/Instagram/YouTube/X/Douyin/Xiaohongshu/Bilibili)."), focus: z.string().optional().describe("Extra instruction, e.g. 'focus on the CTA'.") }).strict(),
     },
     {

package/dist/shared/tools.js

@@ -27,13 +27,13 @@ function toolError(prefix, err) {
 export function createMcpServer(makeClient) {
     const server = new McpServer({
         name: "orchyn-mcp",
-        version: "1.3.4",
+        version: "1.5.0",
     });
     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, X/Twitter, Douyin, Xiaohongshu and Bilibili. Returns the full analysis once finished.",
+            "Supports TikTok, Instagram, YouTube, X/Twitter, Douyin, Xiaohongshu and Bilibili. Returns the full analysis once finished. First use free per user.",
         inputSchema: z
             .object({
             url: z.string().describe("Public post URL (TikTok/Instagram/YouTube/X, Douyin, Xiaohongshu or Bilibili)."),
@@ -76,7 +76,7 @@ export function createMcpServer(makeClient) {
         title: "Get Social Media",
         description: "Fetch a social post's media from a TikTok, Instagram, YouTube, X/Twitter, Douyin, Xiaohongshu or Bilibili URL: " +
             "contentType (video/image/carousel/slideshow), title, caption, author, stats and direct media URLs. " +
-            "Returns an inline thumbnail image. Consumes 1 orchyn credit.",
+            "Returns an inline thumbnail image. Consumes 1 orchyn credit. First use free per user.",
         inputSchema: z
             .object({
             url: z.string().describe("Full public post URL."),
@@ -95,7 +95,7 @@ export function createMcpServer(makeClient) {
         title: "Discover Social Posts",
         description: "Discover recent posts (video, image, carousel, slideshow) for a niche on YouTube, TikTok, Instagram, Douyin, Xiaohongshu, X/Twitter or Bilibili via TikHub. " +
             "Each post includes title/caption, thumbnailUrl, externalUrl, views/likes/comments and 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.',
+            'Say "next" to paginate (offset), or "analyze the 2nd one" / "analyze all" for batch analysis. Consumes 2 orchyn credits. First use free per user.',
         inputSchema: z
             .object({
             niche: z.string().describe("Niche/topic, e.g. 'fitness'."),
@@ -121,7 +121,7 @@ export function createMcpServer(makeClient) {
         title: "Get User Posts",
         description: "List recent posts by a creator handle (e.g. @zoundsapp) via TikHub on TikTok, Instagram, YouTube, Douyin, Xiaohongshu, X/Twitter or Bilibili. " +
             "Each post includes title/caption, thumbnailUrl, externalUrl, views/likes/comments and inline thumbnails (up to 4) so they show in chat. " +
-            "Use this when Claude needs to pull more posts from the same account to spot a pattern, or to scan a whole profile. Consumes 2 orchyn credits.",
+            "Use this when Claude needs to pull more posts from the same account to spot a pattern, or to scan a whole profile. Consumes 2 orchyn credits. First use free per user.",
         inputSchema: z
             .object({
             username: z.string().describe("Creator handle, e.g. 'zoundsapp' or '@zoundsapp'."),
@@ -145,7 +145,7 @@ export function createMcpServer(makeClient) {
         title: "Analyze Creator Profile",
         description: "Deep-dive a whole creator profile via TikHub on TikTok, Instagram, YouTube, Douyin, Xiaohongshu, X/Twitter or Bilibili: fetch recent posts, run multimodal Gemini on up to 3, " +
             "then synthesize a profile report — creator summary, niche, content themes, hook styles, strengths/weaknesses, " +
-            "engagement patterns, audience insights, variation ideas, collaboration fit. Consumes 15 orchyn credits.",
+            "engagement patterns, audience insights, variation ideas, collaboration fit. Consumes 15 orchyn credits. First use free per user.",
         inputSchema: z
             .object({
             username: z.string().describe("Creator handle, e.g. 'zoundsapp'."),
@@ -169,7 +169,7 @@ export function createMcpServer(makeClient) {
     server.registerTool("get_post_comments", {
         title: "Get Post Comments",
         description: "Fetch top comments for a post URL via TikHub on TikTok, Instagram, YouTube, Douyin, X/Twitter or Bilibili, plus keyword clusters from TikTok Analytics " +
-            "when available — audience sentiment/audience-signal analysis. Consumes 2 orchyn credits.",
+            "when available — audience sentiment/audience-signal analysis. Consumes 2 orchyn credits. First use free per user.",
         inputSchema: z
             .object({
             url: z.string().describe("Full public post URL (TikTok/Instagram/YouTube/Douyin/X/Bilibili)."),
@@ -188,7 +188,7 @@ export function createMcpServer(makeClient) {
     server.registerTool("search_creators", {
         title: "Search Creators",
         description: "Search creators by niche/keyword via TikHub on TikTok, Instagram, Xiaohongshu, YouTube or Douyin — username, nickname, follower count, " +
-            "signature, verified status. Use to find influencers to vet or analyze. Consumes 2 orchyn credits.",
+            "signature, verified status. Use to find influencers to vet or analyze. Consumes 2 orchyn credits. First use free per user.",
         inputSchema: z
             .object({
             keyword: z.string().describe("Niche/keyword, e.g. 'fitness' or a creator name."),
@@ -211,7 +211,7 @@ export function createMcpServer(makeClient) {
     server.registerTool("get_similar_creators", {
         title: "Get Similar Creators",
         description: "Find lookalike creators for a given handle via TikHub — TikTok similar-user recommendations or Instagram " +
-            "similar users. Useful for scaling: 'if this creator works, here are more like them'. Consumes 2 orchyn credits.",
+            "similar users. Useful for scaling: 'if this creator works, here are more like them'. Consumes 2 orchyn credits. First use free per user.",
         inputSchema: z
             .object({
             username: z.string().describe("Seed creator handle, e.g. 'zoundsapp'."),
@@ -230,7 +230,7 @@ export function createMcpServer(makeClient) {
     server.registerTool("discover_sounds", {
         title: "Discover Sounds",
         description: "Discover trending sounds/music for a keyword on TikTok or Instagram via TikHub — the sound is a huge ranking " +
-            "signal for TikTok virality. Returns title, artist, duration, play/cover URLs. Consumes 2 orchyn credits.",
+            "signal for TikTok virality. Returns title, artist, duration, play/cover URLs. Consumes 2 orchyn credits. First use free per user.",
         inputSchema: z
             .object({
             keyword: z.string().describe("Niche/keyword, e.g. 'gym'."),
@@ -277,7 +277,7 @@ export function createMcpServer(makeClient) {
         title: "Understand Social Post",
         description: "Import a social post URL AND understand it with multimodal AI over the actual video/images: " +
             "summary, hook strength, viral triggers, format breakdown and variation ideas. Includes the thumbnail. " +
-            "Supports TikTok, Instagram, YouTube, X/Twitter, Douyin, Xiaohongshu and Bilibili. Consumes 10 orchyn credits.",
+            "Supports TikTok, Instagram, YouTube, X/Twitter, Douyin, Xiaohongshu and Bilibili. Consumes 10 orchyn credits. First use free per user.",
         inputSchema: z
             .object({
             url: z.string().describe("Full public post URL (TikTok/Instagram/YouTube/X/Douyin/Xiaohongshu/Bilibili)."),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orchyn/mcp",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "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",