@orchyn/mcp 1.4.1 → 1.6.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 (4) hide show
  1. package/README.md +6 -3
  2. package/dist/shared/tools-def.js +9 -9
  3. package/dist/shared/tools.js +11 -11
  4. package/package.json +1 -1
package/README.md CHANGED
@@ -53,7 +53,9 @@ npx @orchyn/mcp login # one-time sign-in (Google)
53
53
 
54
54
  All tools require a connected orchyn account and are billed against your orchyn credit balance (`POST /billing/mcp-credits/checkout` tops up).
55
55
 
56
- `*` `analyze_post` bills against **workspace** credits (first free grant); the other tools bill against **per-user MCP** credits (never tied to an app/workspace).
56
+ **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.
57
+
58
+ `*` `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).
57
59
 
58
60
  ## Images in Claude / ChatGPT chat
59
61
 
@@ -262,8 +264,9 @@ All tools accept these hosts and handle **video, image, carousel and slideshow**
262
264
  - **`Not authenticated with orchyn` / 401**: run `npx @orchyn/mcp login` or set
263
265
  `ORCHYN_ACCESS_TOKEN`.
264
266
  - **402 paywall / `insufficient MCP credits`**: your orchyn account is out of
265
- credits for this tool. Each call costs: `get_social_media` 1,
266
- `discover_social_posts` / `get_user_posts` / `get_post_comments` / `search_creators` /
267
+ credits for this tool. Every tool has **one free first use per user**; after
268
+ that each call costs: `get_social_media` 1, `discover_social_posts` /
269
+ `get_user_posts` / `get_post_comments` / `search_creators` /
267
270
  `get_similar_creators` / `discover_sounds` 2 each, `understand_social_post` 10,
268
271
  `analyze_creator_profile` 15, `analyze_post` first-call free* (see Tools). Top up
269
272
  via `buy_orchyn_credits`, `check_orchyn_credits`, or the orchyn dashboard at
package/dist/shared/tools-def.js CHANGED
@@ -9,55 +9,55 @@ export const TOOL_DEFINITIONS = [
9
9
  {
10
10
  name: "get_social_media",
11
11
  title: "Get Social Media",
12
- 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.",
12
+ 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.",
13
13
  inputSchema: z.object({ url: z.string().describe("Full public post URL.") }).strict(),
14
14
  },
15
15
  {
16
16
  name: "discover_social_posts",
17
17
  title: "Discover Social Posts",
18
- 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.",
18
+ 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.",
19
19
  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(),
20
20
  },
21
21
  {
22
22
  name: "get_user_posts",
23
23
  title: "Get User Posts",
24
- 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.",
24
+ 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.",
25
25
  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(),
26
26
  },
27
27
  {
28
28
  name: "analyze_creator_profile",
29
29
  title: "Analyze Creator Profile",
30
- 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.",
30
+ 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.",
31
31
  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(),
32
32
  },
33
33
  {
34
34
  name: "get_post_comments",
35
35
  title: "Get Post Comments",
36
- 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.",
36
+ 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.",
37
37
  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(),
38
38
  },
39
39
  {
40
40
  name: "search_creators",
41
41
  title: "Search Creators",
42
- 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.",
42
+ 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.",
43
43
  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(),
44
44
  },
45
45
  {
46
46
  name: "get_similar_creators",
47
47
  title: "Get Similar Creators",
48
- 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.",
48
+ 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.",
49
49
  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(),
50
50
  },
51
51
  {
52
52
  name: "discover_sounds",
53
53
  title: "Discover Sounds",
54
- 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.",
54
+ 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.",
55
55
  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(),
56
56
  },
57
57
  {
58
58
  name: "understand_social_post",
59
59
  title: "Understand Social Post",
60
- 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.",
60
+ 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.",
61
61
  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(),
62
62
  },
63
63
  {
package/dist/shared/tools.js CHANGED
@@ -27,13 +27,13 @@ function toolError(prefix, err) {
27
27
  export function createMcpServer(makeClient) {
28
28
  const server = new McpServer({
29
29
  name: "orchyn-mcp",
30
- version: "1.3.4",
30
+ version: "1.5.0",
31
31
  });
32
32
  server.registerTool("analyze_post", {
33
33
  title: "Analyze Post",
34
34
  description: "Analyze a social post (video, image, carousel/slideshow) from its link — " +
35
35
  "imports the media and runs AI analysis over the actual content (video frames, carousel images, caption). " +
36
- "Supports TikTok, Instagram, YouTube, X/Twitter, Douyin, Xiaohongshu and Bilibili. Returns the full analysis once finished.",
36
+ "Supports TikTok, Instagram, YouTube, X/Twitter, Douyin, Xiaohongshu and Bilibili. Returns the full analysis once finished. First use free per user.",
37
37
  inputSchema: z
38
38
  .object({
39
39
  url: z.string().describe("Public post URL (TikTok/Instagram/YouTube/X, Douyin, Xiaohongshu or Bilibili)."),
@@ -76,7 +76,7 @@ export function createMcpServer(makeClient) {
76
76
  title: "Get Social Media",
77
77
  description: "Fetch a social post's media from a TikTok, Instagram, YouTube, X/Twitter, Douyin, Xiaohongshu or Bilibili URL: " +
78
78
  "contentType (video/image/carousel/slideshow), title, caption, author, stats and direct media URLs. " +
79
- "Returns an inline thumbnail image. Consumes 1 orchyn credit.",
79
+ "Returns an inline thumbnail image. Consumes 1 orchyn credit. First use free per user.",
80
80
  inputSchema: z
81
81
  .object({
82
82
  url: z.string().describe("Full public post URL."),
@@ -95,7 +95,7 @@ export function createMcpServer(makeClient) {
95
95
  title: "Discover Social Posts",
96
96
  description: "Discover recent posts (video, image, carousel, slideshow) for a niche on YouTube, TikTok, Instagram, Douyin, Xiaohongshu, X/Twitter or Bilibili via TikHub. " +
97
97
  "Each post includes title/caption, thumbnailUrl, externalUrl, views/likes/comments and inline thumbnails (up to 4) so they show in chat. " +
98
- 'Say "next" to paginate (offset), or "analyze the 2nd one" / "analyze all" for batch analysis. Consumes 2 orchyn credits.',
98
+ 'Say "next" to paginate (offset), or "analyze the 2nd one" / "analyze all" for batch analysis. Consumes 2 orchyn credits. First use free per user.',
99
99
  inputSchema: z
100
100
  .object({
101
101
  niche: z.string().describe("Niche/topic, e.g. 'fitness'."),
@@ -121,7 +121,7 @@ export function createMcpServer(makeClient) {
121
121
  title: "Get User Posts",
122
122
  description: "List recent posts by a creator handle (e.g. @zoundsapp) via TikHub on TikTok, Instagram, YouTube, Douyin, Xiaohongshu, X/Twitter or Bilibili. " +
123
123
  "Each post includes title/caption, thumbnailUrl, externalUrl, views/likes/comments and inline thumbnails (up to 4) so they show in chat. " +
124
- "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.",
124
+ "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.",
125
125
  inputSchema: z
126
126
  .object({
127
127
  username: z.string().describe("Creator handle, e.g. 'zoundsapp' or '@zoundsapp'."),
@@ -145,7 +145,7 @@ export function createMcpServer(makeClient) {
145
145
  title: "Analyze Creator Profile",
146
146
  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, " +
147
147
  "then synthesize a profile report — creator summary, niche, content themes, hook styles, strengths/weaknesses, " +
148
- "engagement patterns, audience insights, variation ideas, collaboration fit. Consumes 15 orchyn credits.",
148
+ "engagement patterns, audience insights, variation ideas, collaboration fit. Consumes 15 orchyn credits. First use free per user.",
149
149
  inputSchema: z
150
150
  .object({
151
151
  username: z.string().describe("Creator handle, e.g. 'zoundsapp'."),
@@ -169,7 +169,7 @@ export function createMcpServer(makeClient) {
169
169
  server.registerTool("get_post_comments", {
170
170
  title: "Get Post Comments",
171
171
  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 " +
172
- "when available — audience sentiment/audience-signal analysis. Consumes 2 orchyn credits.",
172
+ "when available — audience sentiment/audience-signal analysis. Consumes 2 orchyn credits. First use free per user.",
173
173
  inputSchema: z
174
174
  .object({
175
175
  url: z.string().describe("Full public post URL (TikTok/Instagram/YouTube/Douyin/X/Bilibili)."),
@@ -188,7 +188,7 @@ export function createMcpServer(makeClient) {
188
188
  server.registerTool("search_creators", {
189
189
  title: "Search Creators",
190
190
  description: "Search creators by niche/keyword via TikHub on TikTok, Instagram, Xiaohongshu, YouTube or Douyin — username, nickname, follower count, " +
191
- "signature, verified status. Use to find influencers to vet or analyze. Consumes 2 orchyn credits.",
191
+ "signature, verified status. Use to find influencers to vet or analyze. Consumes 2 orchyn credits. First use free per user.",
192
192
  inputSchema: z
193
193
  .object({
194
194
  keyword: z.string().describe("Niche/keyword, e.g. 'fitness' or a creator name."),
@@ -211,7 +211,7 @@ export function createMcpServer(makeClient) {
211
211
  server.registerTool("get_similar_creators", {
212
212
  title: "Get Similar Creators",
213
213
  description: "Find lookalike creators for a given handle via TikHub — TikTok similar-user recommendations or Instagram " +
214
- "similar users. Useful for scaling: 'if this creator works, here are more like them'. Consumes 2 orchyn credits.",
214
+ "similar users. Useful for scaling: 'if this creator works, here are more like them'. Consumes 2 orchyn credits. First use free per user.",
215
215
  inputSchema: z
216
216
  .object({
217
217
  username: z.string().describe("Seed creator handle, e.g. 'zoundsapp'."),
@@ -230,7 +230,7 @@ export function createMcpServer(makeClient) {
230
230
  server.registerTool("discover_sounds", {
231
231
  title: "Discover Sounds",
232
232
  description: "Discover trending sounds/music for a keyword on TikTok or Instagram via TikHub — the sound is a huge ranking " +
233
- "signal for TikTok virality. Returns title, artist, duration, play/cover URLs. Consumes 2 orchyn credits.",
233
+ "signal for TikTok virality. Returns title, artist, duration, play/cover URLs. Consumes 2 orchyn credits. First use free per user.",
234
234
  inputSchema: z
235
235
  .object({
236
236
  keyword: z.string().describe("Niche/keyword, e.g. 'gym'."),
@@ -277,7 +277,7 @@ export function createMcpServer(makeClient) {
277
277
  title: "Understand Social Post",
278
278
  description: "Import a social post URL AND understand it with multimodal AI over the actual video/images: " +
279
279
  "summary, hook strength, viral triggers, format breakdown and variation ideas. Includes the thumbnail. " +
280
- "Supports TikTok, Instagram, YouTube, X/Twitter, Douyin, Xiaohongshu and Bilibili. Consumes 10 orchyn credits.",
280
+ "Supports TikTok, Instagram, YouTube, X/Twitter, Douyin, Xiaohongshu and Bilibili. Consumes 10 orchyn credits. First use free per user.",
281
281
  inputSchema: z
282
282
  .object({
283
283
  url: z.string().describe("Full public post URL (TikTok/Instagram/YouTube/X/Douyin/Xiaohongshu/Bilibili)."),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@orchyn/mcp",
3
- "version": "1.4.1",
3
+ "version": "1.6.0",
4
4
  "description": "MCP server for orchyn - fetch, discover and understand TikTok/Instagram/YouTube/X posts with AI (media metadata, niche discovery, hook & viral analysis)",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",