viralhunt-mcp 0.2.1 → 1.1.11

package/README.md

@@ -5,7 +5,7 @@ all-in-one platform to **discover what's trending, curate it with your team, and
 A BuzzSumo alternative with a built-in cross-network scheduler and an API that AI agents can drive
 end to end.
 
-Get a free token: **https://viralhunt.io** → Account → API Access (7-day trial, no card). Full API
+Get a free token: **https://viralhunt.io/claude** → create the free account (free forever, no card, 24 content queries a day), then Account → API Access → Create access. Every token has a **permission group** (reader, writer, reviewer, publisher, full): a tool outside the group answers `403 insufficient_scope` naming what it lacks, and `viralhunt_account` shows the token its own group. Give an agent that writes a writer token and the one that reviews a reviewer token. Full API
 docs: **https://viralhunt.io/api**.
 
 ## What an agent can do through this MCP server
@@ -16,18 +16,34 @@ much to trust it:
 
 | Tool | What it does |
 |------|--------------|
-| `viralhunt_trending` | **Find topics** — what's going viral on TikTok, Instagram, X, Facebook, Pinterest, Bluesky, Douyin, Reddit, Mastodon, Tumblr, Hacker News and news RSS, ranked by viral score, each post with `growth_24h` (how much it moved between our two most distant readings) |
+| `viralhunt_account` | **Who is this key** — plan, daily quota left, credits, per-endpoint rules (call first) |
+| `viralhunt_trending` | **Find topics** — what's going viral on TikTok, Instagram, X, Facebook, Pinterest, Bluesky, Douyin, Reddit, Mastodon, Tumblr, Hacker News and news RSS, ranked by viral score, each post with `growth_24h` (how much it moved between our two most distant readings); `author` narrows to one page or account |
+| `viralhunt_search` | **One keyword, every network** — merged and ranked, with per-network totals |
 | `viralhunt_best_time` | **When to post** — best weekday + hour per network from the posts that went viral there (365-day sample, hit rate, sample size, your time zone, optional niche keyword) |
 | `viralhunt_top_hashtags` | **Which hashtags** — top tags per network or across all, by engagement, posts or per-post; one tag's breakdown by network |
 | `viralhunt_trending_sounds` | **Which sound** — trending audio on TikTok, Instagram Reels and Douyin, cross-network sounds first, with the posts that used it |
 | `viralhunt_best_communities` | **Where to post** — best subreddits (peak per 1,000 members, timing, top posts, similar) and Bluesky custom feeds for a topic |
-| `viralhunt_targets` | List your **brands/projects** and the connected accounts you can post to |
-| `viralhunt_schedule` | **Publish now or schedule** a post (text + media) across your connected accounts |
-| `viralhunt_get_post` | Check a post's status + per-network permalinks |
-| `viralhunt_update_post` | Edit a still-scheduled post (body / media / networks / time) |
-| `viralhunt_cancel_post` | Cancel the not-yet-published targets of a scheduled post |
-| `viralhunt_list_templates` | Browse the **content template** library (on-brand layouts you fill) |
-| `viralhunt_get_template` | Get one template's full spec (html + css + variable manifest) to render |
+| `viralhunt_targets` | List your **brands/projects** and the connected accounts you can post to, with `needs_reconnect`, per-network `media_limits` and the projects linked in another language |
+| `viralhunt_schedule` | **Publish now, schedule, or leave a draft** (text + media, per-network copy, a first comment, or a `design` on a template the app renders when a person approves) |
+| `viralhunt_drafts` | **The drafts waiting** for a review and an approval, with their reviews |
+| `viralhunt_review_draft` | **Review a draft** — verdict, score, per-network warnings, a note (an agent as the team's checker) |
+| `viralhunt_policy` | **The content rule** a reviewer applies before any OK: block and fix lists with codes, six scores and thresholds, per-network notes (read it first, every pass) |
+| `viralhunt_review_queue` | **What needs a review**: posts in Review with no verdict on their current content |
+| `viralhunt_calendar` | **The days worth a post**: international days and science/tech/space/health anniversaries with why, by window and category |
+| `viralhunt_news_categories` | **The news categories** with counts; pass one as `category` to `viralhunt_trending` (rss) |
+| `viralhunt_review_stats` | **Flags per collaborator** by week, fortnight or month: reviews, ok / fix / block, rule codes, average risk10 |
+| `viralhunt_approve_draft` | **Send a draft** (owner/admin token, with the user's yes), optionally with its translations |
+| `viralhunt_translate_post` | **The same post in another language** — the app adapts the copy and the template's texts for a linked project |
+| `viralhunt_edit_log` | **Learn from the edits** — what people changed in drafts after the agent left them |
+| `viralhunt_get_post` | Check a post's status + per-network results, permalinks and each network's own reason when it refused |
+| `viralhunt_sync_post` | Refresh statuses from the networks |
+| `viralhunt_update_post` | Edit a draft (anything, incl. the rendered `png`) or a still-scheduled post (body / media / networks / time) |
+| `viralhunt_cancel_post` | Cancel the not-yet-published targets of a scheduled post, or drop a draft |
+| `viralhunt_stats` | **What performed** — engagement of the published posts by network, by brand, top posts |
+| `viralhunt_quotes` / `viralhunt_mark_quote_used` | The **quotes base** for daily-quote series (public domain by default, author context, portraits) |
+| `viralhunt_recipes` / `viralhunt_recipe_ran` | **Standing orders** a person saved in the app: source, template, cadence; stamp a run |
+| `viralhunt_list_templates` | Browse the **content template** library (on-brand layouts you fill; favourites first) |
+| `viralhunt_get_template` | Get one template's full spec (html + css + variable manifest, what is `static` and what is `dynamic`, what it `suits`, the owner's `instructions`) to render |
 | `viralhunt_upsert_template` | **Author or edit a template** — editing a curated one clones it into your copy (owner/admin) |
 | `viralhunt_assign_template` | Assign a template to a project so its agents can use it (owner/admin) |
 | `viralhunt_board_context` | The team's **Editorial Board** in one call: members (with ids), columns, categories |
@@ -36,8 +52,34 @@ much to trust it:
 | `viralhunt_my_cards` | The cards assigned to you (when the token belongs to an agent member of the team) |
 | `viralhunt_card_comments` | Read or add comments on a card (notifies the assignee, mirrors to team chat) |
 
-Guardrails baked in: it won't post to the wrong brand, only schedules in the future, and is told not to
-repost fake news / copyrighted media / spam.
+Guardrails baked in: it won't post to the wrong brand, only schedules in the future, drafts by default
+unless the user asked to publish now, never uses another page's text or branded picture, checks each
+network's media ceilings, and is told not to repost fake news / copyrighted media / spam.
+
+## Changelog
+
+- **1.1.11 (2026-10-08)** — approve by a member token on its own graded post (when ticked on Team); review_stats carries avg_score, self_published, published_over_fix.
+- **1.1.10 (2026-10-07)** — the reviewer's edit boundary (overrides and kind only, when trusted); text_limit per account.
+- **1.1.9 (2026-10-07)** — `kind` on create and update (fact | meme | quote | opinion | promo): the reviewer applies only that kind's rules.
+- **1.1.8 (2026-10-07)** — `overrides[account]` takes `first_comment` and `thread` per account; Bluesky/Mastodon threads as a reply chain.
+- **1.1.7 (2026-10-07)** — `author_notes` on create and update: the source link for the reviewer, never published.
+- **1.1.6 (2026-10-07)** — the safety catch on a trusted reviewer's OK (risk_threshold), project_lang on drafts, review_stats for trusted reviewers.
+- **1.1.5 (2026-10-07)** — `viralhunt_calendar`: the calendar base (international days and anniversaries, with why), mark_used.
+- **1.1.4 (2026-10-07)** — `viralhunt_news_categories` and `category` on `viralhunt_trending` (rss); unknown parameters are a 422 on the API.
+- **1.1.3 (2026-10-07)** — the policy describes the kinds (fact, meme, quote, opinion, promo): a meme or a quote never gets a source or DOI demand.
+- **1.1.2 (2026-10-06)** — `content_hash` on `viralhunt_review_draft` (409 content_changed when the post moved under the reviewer); self review is by user, not token.
+- **1.1.1 (2026-10-06)** — the reviewer's four extra checks (picture against text, spelling, AI-written, facts with the DOI rule), `risk10` 1 to 10 on every review, `viralhunt_review_stats` (flags per collaborator).
+- **1.1.0 (2026-10-05)** — the reviewer job: `viralhunt_policy`, `viralhunt_review_queue`, `needs_review` on drafts; the server recalculates the verdict and names in `sent.skipped` the rule that kept an OK from sending.
+- **0.3.0 (2026-09-28)** — drafts and review (`viralhunt_drafts`, `viralhunt_review_draft`,
+  `viralhunt_approve_draft`, `viralhunt_edit_log`), translation into a linked project's language
+  (`viralhunt_translate_post`), `design` on a post and `png` on update, `viralhunt_search`,
+  `viralhunt_account`, `viralhunt_stats`, `viralhunt_quotes`, `viralhunt_recipes`, `viralhunt_sync_post`;
+  `author` and free-form `time_range` on trending; `media_limits`, `needs_reconnect` and language links on
+  targets; templates say what is static, dynamic and what they suit; honest post statuses with each
+  network's reason.
+- **0.2.x (2026-09-08)** — best time to post, top hashtags, trending sounds, best communities, the editorial
+  board; Reddit, Mastodon, Tumblr and Hacker News on trending; `growth_24h` documented.
+- **0.1.x (2026-08)** — trending, targets, publish/schedule, get, update, cancel, content templates.
 
 ## What ViralHunt the platform does (beyond this MCP)
 

package/index.d.ts

@@ -0,0 +1,63 @@
+/**
+ * viralhunt-mcp — type declarations.
+ *
+ * The package is a command-line MCP server (`npx viralhunt-mcp`, speaking the Model Context Protocol over
+ * stdio); it exposes no programmatic API. These declarations exist so TypeScript consumers that import the
+ * module for its side effects, and the package registries that look for types, find them.
+ */
+export {};
+
+/** Environment the server reads at start-up. */
+export interface ViralHuntMcpEnv {
+  /** A ViralHunt API token (vhk_…) from Account → API Access. Required. */
+  VIRALHUNT_API_KEY: string;
+  /** API base URL. Default: https://viralhunt.io/tool/api/v1 */
+  VIRALHUNT_API_BASE?: string;
+}
+
+/** The tools the server registers, by name. */
+export type ViralHuntTool =
+  | 'viralhunt_account'
+  | 'viralhunt_approve_draft'
+  | 'viralhunt_assign_template'
+  | 'viralhunt_best_communities'
+  | 'viralhunt_best_time'
+  | 'viralhunt_board_context'
+  | 'viralhunt_cancel_post'
+  | 'viralhunt_card_comments'
+  | 'viralhunt_create_card'
+  | 'viralhunt_drafts'
+  | 'viralhunt_edit_log'
+  | 'viralhunt_get_post'
+  | 'viralhunt_get_template'
+  | 'viralhunt_list_templates'
+  | 'viralhunt_mark_quote_used'
+  | 'viralhunt_move_card'
+  | 'viralhunt_my_cards'
+  | 'viralhunt_policy'
+  | 'viralhunt_quotes'
+  | 'viralhunt_recipe_ran'
+  | 'viralhunt_recipes'
+  | 'viralhunt_review_draft'
+  | 'viralhunt_review_queue'
+  | 'viralhunt_calendar'
+  | 'viralhunt_news_categories'
+  | 'viralhunt_review_stats'
+  | 'viralhunt_schedule'
+  | 'viralhunt_search'
+  | 'viralhunt_stats'
+  | 'viralhunt_submit_draft'
+  | 'viralhunt_sync_post'
+  | 'viralhunt_targets'
+  | 'viralhunt_top_hashtags'
+  | 'viralhunt_translate_post'
+  | 'viralhunt_trending'
+  | 'viralhunt_trending_sounds'
+  | 'viralhunt_update_post'
+  | 'viralhunt_upsert_template';
+
+/** Where a post sits before it is sent: being worked on, or complete and waiting for an owner or admin. */
+export type PostStage = 'draft' | 'review';
+
+/** The status of a scheduled post as the API reports it. */
+export type PostStatus = PostStage | 'scheduled' | 'processing' | 'published' | 'partial' | 'failed' | 'canceled';

package/index.js

@@ -68,59 +68,245 @@ tool(server, "viralhunt_trending",
     "Sources: tiktok, instagram, x, facebook, pinterest, bluesky, douyin, reddit, mastodon, tumblr, hackernews, and rss (news articles",
     "from 230 feeds plus articles discovered through social links, each with Facebook/Reddit/Bluesky/Hacker News/comment signals).",
     "Each post carries growth_24h when we hold at least two readings of it: {from, to, delta, percent, hours, measured_at, samples}.",
-    "Read it carefully: growth_24h null means 'we cannot say', NOT zero (Facebook and Pinterest never carry it); `hours` is the REAL",
-    "window between the two readings and is not always 24, so quote it; `percent` is null when the post started from zero while",
-    "`delta` still holds the absolute change. A high delta over few hours is what 'going viral right now' looks like.",
+    "Read it carefully: growth_24h null means 'we cannot say', NOT zero (Facebook and Pinterest never carry it); delta 0 with",
+    "samples >= 2 means measured and unchanged (flat), not missing; `hours` is the REAL window between the two readings (the newest",
+    "reading at least 20h older than the latest, or the oldest one when the post is younger than that), so it is often under 24:",
+    "quote it, never assume 24, and say 'in 24h' only when `full_window` is true; `percent` is null when `from` is under 100 (from zero or from a handful of interactions a percentage",
+    "is noise) while `delta` always holds the absolute change. A high delta over few hours is what 'going viral right now' looks like.",
   ].join(" "),
   {
     source: z.enum(["tiktok", "instagram", "x", "facebook", "pinterest", "bluesky", "douyin", "reddit", "mastodon", "tumblr", "hackernews", "rss"]).describe("Which network to pull trending from."),
     sort: z.string().optional().describe("viral (default), engagement, newest, oldest, plus per network: most_liked, most_viewed, most_commented, most_retweeted, most_reposted, most_saved, most_upvoted (reddit), most_boosted (mastodon), most_noted (tumblr), most_points (hackernews); rss: trending, engagement, growth, bluesky, mentions, coverage, hn, comments."),
-    time_range: z.enum(["6h", "12h", "24h", "7d", "30d", "3m", "all"]).optional().describe("Time window on the post's own publish date (default 7d). Tumblr's corpus fills slowly: use 30d or all for tumblr, 7d is often empty there."),
+    time_range: z.string().optional().describe("Time window on the post's own publish date: any number with a unit (24h, 7d, 30d, 2w, 3m, 1y), a bare number of days, or all (default 7d). An unknown value is a 422. Tumblr's corpus fills slowly: use 30d or all there."),
     keyword: z.string().optional().describe("Filter by keyword/niche (matched in title, text, hashtags or author)."),
+    category: z.string().optional().describe("rss only: ONE news category, a name or id from viralhunt_news_categories (exact name, case-insensitive; unknown = 422 with the valid names). Technology and Artificial Intelligence are two categories: for AI content call twice."),
+    author: z.string().optional().describe("ONE page or account only (facebook page name, x handle or name, tiktok or instagram username; contains-match). 'The most viral posts of the page X in 2025' = source + author + time_range=1y."),
     subreddit: z.string().optional().describe("reddit only: restrict to one subreddit (with or without r/)."),
     min_engagement: z.number().int().min(0).optional().describe("Minimum engagement on the network's main metric."),
     per_page: z.number().int().min(1).max(100).optional().describe("How many results (max 100)."),
     page: z.number().int().min(1).optional().describe("Page number for more results."),
   },
-  (a) => vh("/trending.php", { query: { source: a.source, sort: a.sort || "viral", time_range: a.time_range || "7d", keyword: a.keyword, subreddit: a.subreddit, min_engagement: a.min_engagement, per_page: a.per_page || 20, page: a.page } })
+  (a) => vh("/trending.php", { query: { source: a.source, sort: a.sort || "viral", time_range: a.time_range || "7d", keyword: a.keyword, category: a.category, author: a.author, subreddit: a.subreddit, min_engagement: a.min_engagement, per_page: a.per_page || 20, page: a.page } })
+);
+
+tool(server, "viralhunt_news_categories",
+  "The categories of the news corpus (source rss), with how many feeds carry each and how many articles arrived in the last 7 and 30 days. Read it once before asking for news on a subject, then pass a name as category on viralhunt_trending (source rss). Not the Editorial Board categories. Technology and Artificial Intelligence are separate categories.",
+  {},
+  () => vh("/news-categories.php")
+);
+
+// ── Who is this key: plan, quota, credits ──
+tool(server, "viralhunt_account",
+  "Who this key is: plan (free/creator/studio/agency), requests per hour, whether it can publish, today's daily content-query quota (free plan: 24 shared across trending, search, best-time, hashtags, sounds, communities), credits balance, and per-endpoint rules. Call it once at the start and again on a 429 or 402, and set expectations from it (free plan: trending is 72h delayed and numbers are withheld, never print 0).",
+  {},
+  () => vh("/account.php")
+);
+
+// ── One keyword, every network ──
+tool(server, "viralhunt_search",
+  [
+    "Search one keyword across every network at once (or a chosen subset) and get one merged, ranked list: each row normalized to",
+    "platform, id, title, description, post_url, thumbnail_url, author_name, author_handle, engagement_score, stats, growth_24h,",
+    "created_at, plus the network's full row under raw. sources[] says per network how many posts matched (total), so you can tell the",
+    "user where the topic lives and where the corpus holds nothing (total 0 = say so, never invent posts). All words must appear, in any order.",
+    "Use viralhunt_trending when the user wants ONE network with its own sorts and paging.",
+  ].join(" "),
+  {
+    keyword: z.string().describe("The words to find (all must appear)."),
+    sources: z.string().optional().describe("all (default) or a comma list: pinterest,x,reddit,tiktok,instagram,facebook,bluesky,douyin,mastodon,tumblr,hackernews,rss."),
+    time_range: z.string().optional().describe("Window on the post's own date (default 30d): a number with a unit, a bare number of days, or all."),
+    per_source: z.number().int().min(1).max(50).optional().describe("Rows per network (default 10)."),
+    sort: z.enum(["engagement", "recent"]).optional(),
+    min_engagement: z.number().int().min(0).optional(),
+  },
+  (a) => vh("/search.php", { query: { keyword: a.keyword, sources: a.sources, time_range: a.time_range, per_source: a.per_source, sort: a.sort, min_engagement: a.min_engagement } })
 );
 
 // ── Where can I publish (projects + connected accounts) ──
 tool(server, "viralhunt_targets",
-  "List the user's projects/brands and the connected social accounts you can publish to in each.",
+  [
+    "List the user's projects/brands and the connected social accounts you can publish to in each. Also returns needs_reconnect",
+    "(expired connections: not targets until a person reconnects them in the app; name the network before publishing), media_limits",
+    "per network (image bytes: bigger ones are re-encoded to fit; video bytes and seconds: a bigger or longer video is refused for that",
+    "network only, with the numbers; text length), each project's lang and translates_to (linked projects in another language), and",
+    "must_draft: '' = this token may publish directly; 'role' = a member or agent token: every post waits in Drafts for an owner or admin",
+    "whatever draft says; 'review_mode' = the organization reviews every post. Read it before promising 'published'.",
+  ].join(" "),
   { project: z.string().optional().describe("Project name to scope the accounts to (optional).") },
   (a) => vh("/schedule.php", { query: { action: "targets", project: a.project } })
 );
 
-// ── Publish now or schedule ──
+// ── Publish now, schedule, or leave a draft ──
 tool(server, "viralhunt_schedule",
-  "Publish now or schedule a post (text + media URLs) to a project's connected accounts. Verify content before posting — never publish fake news, copyrighted media, or spam.",
+  [
+    "Publish now, schedule, or (default when the user did not ask to publish right now) leave a DRAFT of a post on a project's",
+    "connected accounts. Ask the user before publishing or scheduling: it posts to real accounts. Verify content first: never fake",
+    "news, copyrighted media or spam. Never use another page's text as the copy or its branded picture as the post's picture: the",
+    "picture comes from the organization's templates (viralhunt_get_template), either rendered by you and passed in media, or passed",
+    "as `design` with draft=true so the app renders it when a person approves. Returns {id, status, results, warnings, review_url}:",
+    "status processing|scheduled|review|draft|partial|failed; results keyed by account id carry each network's own reason when it refused.",
+    "Two stages sit before sending: Drafts (being worked on) and Review (complete, dated, waiting for an owner or admin). Say which one the post is in.",
+  ].join(" "),
   {
     project: z.string().optional().describe("Project name — REQUIRED if the org has more than one project."),
     project_id: z.number().int().optional().describe("Project id — alternative to project name."),
-    body: z.string().optional().describe("Caption/text. Optional if media is provided."),
-    media: z.array(z.string()).optional().describe("Public image/video URLs."),
+    body: z.string().optional().describe("Caption/text. Optional if media or design is provided."),
+    media: z.array(z.string()).optional().describe("Public image/video URLs. Check media_limits (viralhunt_targets) before a big video."),
     networks: z.array(z.string()).optional().describe('Post to every account on these networks, e.g. ["instagram","facebook"].'),
     target_account_ids: z.array(z.number().int()).optional().describe("Exact account ids (from viralhunt_targets). Omit = all accounts in the project."),
-    scheduled_at: z.string().optional().describe("ISO-8601 UTC, e.g. 2026-08-01T15:30:00Z. Omit = publish now."),
+    scheduled_at: z.string().optional().describe("ISO-8601 UTC, e.g. 2026-08-01T15:30:00Z. Omit = publish now (or, with draft, the tentative time is 'when approved')."),
     first_comment: z.string().optional().describe("Optional first comment (link-in-comments)."),
+    author_notes: z.string().optional().describe("For the reviewer, never published: the source link, the picture's origin, what you verified. Put the source link HERE, never in the body (the networks cut the reach)."),
+    kind: z.enum(["fact", "meme", "quote", "opinion", "promo"]).optional().describe("What the post IS. The reviewer applies only that kind's rules (a meme is never asked for a source). A post from a card takes the card's category when omitted."),
+    draft: z.boolean().optional().describe("true = a working copy in Drafts you still mean to edit (viralhunt_update_post, then viralhunt_submit_draft). Without it, a member or agent token lands the complete post in Review, where an owner or admin authorizes it; nothing is sent either way. An owner token publishes directly."),
+    overrides: z.object({}).passthrough().optional().describe('Per network (or per account id), only what that account needs to differ: {"bluesky": {"body": "the 300-character version", "thread": [{"body": "part 2"}]}, "12": {"media": ["…"], "first_comment": "its own first comment"}}. body, media, first_comment, thread. X 280, Bluesky 300, Threads 500, Mastodon 500. A thread on Bluesky/Mastodon is a reply chain posted after the post is live.'),
+    card_id: z.number().int().optional().describe("The Editorial Board card this post comes from (optional)."),
+    design: z.object({}).passthrough().optional().describe('The picture as a filled template instead of a rendered file: {"template": "<slug or id>", "format": "feed", "variables": {"text": "…", "highlight": "…", "image": "https://…", "caption": "…"}}. Needs draft=true when media is empty; the app renders it when a person approves.'),
   },
   (a) => vh("/schedule.php", { method: "POST", query: { action: "create" }, body: {
     project: a.project, project_id: a.project_id, body: a.body, media: a.media,
-    networks: a.networks, target_account_ids: a.target_account_ids, scheduled_at: a.scheduled_at, first_comment: a.first_comment,
+    networks: a.networks, target_account_ids: a.target_account_ids, scheduled_at: a.scheduled_at, first_comment: a.first_comment, author_notes: a.author_notes, kind: a.kind,
+    draft: a.draft ? true : undefined, overrides: a.overrides, card_id: a.card_id, design: a.design,
   } })
 );
 
+// ── Drafts: the limbo before sending ──
+tool(server, "viralhunt_drafts",
+  "List the posts not yet sent (this project, or every project with all=true): stage 'draft' = being worked on, 'review' = complete and dated, waiting for an owner or admin. Each carries stage, body, media, targets, scheduled_at, overrides, card_id, submitted_via (api = from an agent), design, lang, translated_from_id, review {score, verdict, reviewed_at, entries[]}, needs_review (no verdict on its current content), valid_verdict, content_hash and updated_at.",
+  {
+    project: z.string().optional().describe("Project name (default: the org's first project)."),
+    project_id: z.number().int().optional(),
+    all: z.boolean().optional().describe("true = every project of the organization."),
+    stage: z.enum(["draft", "review"]).optional().describe("One stage only (default: both)."),
+    needs_review: z.boolean().optional().describe("true = only posts with no verdict on their current content (the reviewer's queue)."),
+  },
+  (a) => vh("/schedule.php", { query: { action: "drafts", project: a.project, project_id: a.project_id, all: a.all ? 1 : undefined, stage: a.stage, needs_review: a.needs_review ? 1 : undefined } })
+);
+
+tool(server, "viralhunt_policy",
+  "The content rule a reviewer applies before any OK, kept on the platform so it changes without a release: what blocks a post (policy_* codes), what sends it back to Drafts (fix_* codes), the six scores (tos_risk, rights, fake_news, sensationalism, brand, grammar; 100 = clean) with the thresholds the server recalculates the verdict with, the extra readings every review carries (risk10 1 safe to 10 breaks a network's terms, image_match, ai_written), the kinds (fact, meme, quote, opinion, promo: a meme or a quote never gets a source or DOI demand), what changes per network, and the server rules an OK cannot bypass. Read it at the start of every review pass; never judge from memory.",
+  {},
+  () => vh("/policy.php")
+);
+
+tool(server, "viralhunt_review_queue",
+  "The reviewer's queue: posts in Review, every project, with no verdict on their current content (never reviewed, or edited after the last verdict). Same rows as viralhunt_drafts. Read viralhunt_policy first, then one viralhunt_review_draft per post.",
+  {
+    project_id: z.number().int().optional().describe("One project only (default: every project)."),
+  },
+  (a) => vh("/schedule.php", { query: { action: "drafts", stage: "review", all: a.project_id ? undefined : 1, project_id: a.project_id, needs_review: 1 } })
+);
+
+tool(server, "viralhunt_review_stats",
+  "Flags per collaborator (owner, admin, or a reviewer marked 'Their OK publishes'): for the last days (7 = week, 14 = fortnight, 30 = month), per person or agent who authored posts: reviews, ok / fix / block, flags (a fix or block, or any policy_* / fix_* warning), codes (how many of each rule, e.g. fix_doi), avg_risk10 and last_flag_at. The Team page shows the same table.",
+  {
+    days: z.number().int().optional().describe("7, 14 or 30 (default 30)."),
+  },
+  (a) => vh("/schedule.php", { query: { action: "review_stats", days: a.days } })
+);
+
+tool(server, "viralhunt_submit_draft",
+  "Move a draft to Review once it is complete (a body or media, and at least one account): it waits there for an owner or admin to authorize it. now=true clears the time (it goes out when authorized); scheduled_at sets one; neither keeps the draft's own. Nothing is sent.",
+  {
+    id: z.number().int().describe("The draft id."),
+    now: z.boolean().optional(),
+    scheduled_at: z.string().optional().describe("ISO-8601 UTC."),
+  },
+  (a) => vh("/schedule.php", { method: "POST", query: { action: "submit" }, body: { id: a.id, now: a.now ? 1 : undefined, scheduled_at: a.scheduled_at } })
+);
+
+tool(server, "viralhunt_review_draft",
+  [
+    "Append your review to a post in Review: verdict ok|fix|block, a score 0-100, per-topic scores (tos_risk, rights, fake_news, sensationalism, brand, grammar; 100 = clean) plus risk10 (1 safe to 10 breaks a network's terms), image_match and ai_written (0-100),",
+    "one warning per issue with the policy's code (policy_* / fix_*), the network it concerns and the severity, and a short note on how to fix it, in the post's language.",
+    "Judge against viralhunt_policy (read it first), network by network; verify claims with viralhunt_search / trending rss. `fix` sends the post back to Drafts with your note",
+    "(returned: true). The server recalculates the verdict from your scores and warnings with the policy thresholds and keeps the more severe one (verdict, verdict_requested,",
+    "verdict_reason in the answer). An `ok` sends the post at its time only when the organization sends on OK AND this token may release (owner, admin, or 'their OK publishes' in Team);",
+    "The note carries the fix (the corrected sentence, the exact link, the short version); say which problem decided the verdict. The server refuses to send on a self review (same USER, not token: the reviewer is its own agent member), a post with no time or under 15 minutes, one edited after the review, or one whose scores sit outside the policy's auto_send thresholds (risk10 > 5, fake_news < 70, image_match < 60: risk_threshold, a person decides), and says why in sent.skipped. Report `sent` as it is. Drafts rows carry project_lang: a post in another language is fix_language.",
+    "Always pass content_hash from the row you read: if the post changed meanwhile the server answers 409 content_changed with the current hash and writes nothing; read it again.",
+  ].join(" "),
+  {
+    id: z.number().int().describe("The draft id."),
+    verdict: z.enum(["ok", "fix", "block"]),
+    content_hash: z.string().optional().describe("The content_hash of the drafts row when you read the post. Always send it."),
+    score: z.number().int().min(0).max(100).optional(),
+    scores: z.object({}).passthrough().optional().describe('{"tos_risk": 90, "fake_news": 70, "sensationalism": 80, "grammar": 95, "risk10": 3, "image_match": 85, "ai_written": 40}'),
+    warnings: z.array(z.object({ code: z.string().optional(), network: z.string().optional(), text: z.string(), severity: z.enum(["info", "warn", "block"]).optional() })).optional(),
+    note: z.string().optional().describe("How to fix it, and the source you verified against."),
+  },
+  (a) => vh("/schedule.php", { method: "POST", query: { action: "review" }, body: { id: a.id, verdict: a.verdict, score: a.score, scores: a.scores, warnings: a.warnings, note: a.note, content_hash: a.content_hash } })
+);
+
+tool(server, "viralhunt_approve_draft",
+  [
+    "Send a draft (owner or admin token only, and never without the user's explicit yes). A draft blocked by its last review cannot be",
+    "approved until it is fixed and reviewed again. `translations` makes the translated draft in each linked project in the same call",
+    "(see viralhunt_translate_post). Returns {status, results, warnings, translations[]}.",
+  ].join(" "),
+  {
+    id: z.number().int().describe("The draft id."),
+    translations: z.array(z.object({ project_id: z.number().int(), lang: z.string().optional(), account_ids: z.array(z.number().int()).optional(), image: z.string().optional(), send_mode: z.enum(["draft", "send"]).optional() })).optional(),
+  },
+  (a) => vh("/schedule.php", { method: "POST", query: { action: "approve" }, body: { id: a.id, translations: a.translations } })
+);
+
+tool(server, "viralhunt_translate_post",
+  [
+    "Make the translated draft of a post (a draft or one already sent) in a linked project that publishes in another language. The app",
+    "adapts the copy, the first comment, the per-network copies, the thread and the TEXT variables of a design (hashtags in the new",
+    "language; links, mentions, numbers and names kept): do not translate yourself. A design keeps its picture and the answer carries",
+    "needs_png=true with render {html, css, format}: render it, store the PNG with viralhunt_update_post {id, png}, then approve if wanted.",
+    "A plain picture (no template) stays unless `image` hands the translated one. The same translation twice is refused.",
+  ].join(" "),
+  {
+    id: z.number().int().describe("The source post id."),
+    project_id: z.number().int().describe("The target project (from translates_to on viralhunt_targets)."),
+    lang: z.string().optional().describe("Override the target language (es, en, pt, fr, de, it…)."),
+    account_ids: z.array(z.number().int()).optional().describe("Accounts of the target project (default: all postable)."),
+    image: z.string().optional().describe("https URL of the translated picture, for a post whose picture is not a template."),
+    send_mode: z.enum(["draft", "send"]).optional().describe("draft (default) waits in the target project; send (owner/admin) goes out at once when there is nothing to render."),
+  },
+  (a) => vh("/schedule.php", { method: "POST", query: { action: "translate" }, body: { id: a.id, project_id: a.project_id, lang: a.lang, account_ids: a.account_ids, image: a.image, send_mode: a.send_mode } })
+);
+
+tool(server, "viralhunt_edit_log",
+  "What people changed in drafts after an agent left them: one row per field (body, media, targets, scheduled_at, first_comment, overrides, thread, design) with before, after, who and when, plus by_field counts. Drafts with submitted_via=api came from an agent: those edits are what the person did not like. Read it at the start of each batch and apply the pattern (shorter captions, another picture, another hour).",
+  {
+    since: z.string().optional().describe("ISO-8601: only changes after this moment."),
+    id: z.number().int().optional().describe("Only one draft's changes."),
+    limit: z.number().int().min(1).max(500).optional(),
+  },
+  (a) => vh("/schedule.php", { query: { action: "edit_log", since: a.since, id: a.id, limit: a.limit } })
+);
+
+tool(server, "viralhunt_sync_post",
+  "Refresh the status of this organization's posts from the networks (call before viralhunt_get_post when the answer matters). Returns how many rows were re-read.",
+  {},
+  () => vh("/schedule.php", { method: "POST", query: { action: "sync" }, body: {} })
+);
+
 // ── Check status ──
 tool(server, "viralhunt_get_post",
-  "Get the current status and per-network results (incl. permalinks) of a post you created.",
+  [
+    "Get the current status and per-network results (incl. permalinks) of a post you created. Also events[] (the delivery log: created, accepted by PostProxy, published with its link, refused with the reason, retried, canceled, reviewed, approved) and support_text, the text to hand the user when they ask what happened to a post. Statuses: scheduled (queued), processing",
+    "(handed to the networks, or a target being retried), published (every target live), partial (some refused: each failed",
+    "results[account].error carries the network's own words and error_message sums it up), failed, draft, canceled. The app retries a",
+    "transient failure up to three times (results show retries, will_retry, retry_after); a final reason (dead connection, refused text,",
+    "oversized video) is not retried: tell the user what to fix. On a draft with a design the answer also carries render {html, css, format}.",
+  ].join(" "),
   { id: z.number().int().describe("The post id returned by viralhunt_schedule.") },
   (a) => vh("/schedule.php", { query: { action: "get", id: a.id } })
 );
 
-// ── Edit a scheduled post ──
+// ── Edit a scheduled post or a draft ──
 tool(server, "viralhunt_update_post",
-  "Edit a still-scheduled post. Only works while status is 'scheduled' and >5 min before publish. Only the fields you send change; the project cannot be changed. Check status with viralhunt_get_post first; on a 409 error re-fetch instead of retrying.",
+  [
+    "Edit a post. A DRAFT can be changed freely by its author, an owner or an admin (body, media, overrides, first_comment, targets, scheduled_at, design, and png: the",
+    "a reviewer marked 'Their OK publishes' may change only overrides (a per-account short copy) and kind on someone else's post);",
+    "rendered picture of its design as a data:image/png;base64 URL, which becomes the post's first picture). A SCHEDULED post can be",
+    "edited only while status is 'scheduled' and more than 5 min before publish. Only the fields you send change; the project cannot",
+    "be changed. Check status with viralhunt_get_post first; on a 409 error re-fetch instead of retrying.",
+  ].join(" "),
   {
     id: z.number().int().describe("The post id."),
     body: z.string().optional().describe("New caption."),
@@ -128,12 +314,112 @@ tool(server, "viralhunt_update_post",
     networks: z.array(z.string()).optional().describe("New network set (adds/removes targets)."),
     target_account_ids: z.array(z.number().int()).optional().describe("New exact account-id set."),
     scheduled_at: z.string().optional().describe("New ISO-8601 UTC time (must be in the future)."),
+    first_comment: z.string().optional().describe("Drafts: the first comment."),
+    author_notes: z.string().optional().describe("Drafts: notes for the reviewer, never published (the source link goes here)."),
+    kind: z.enum(["fact", "meme", "quote", "opinion", "promo"]).optional().describe("Drafts: what the post is."),
+    overrides: z.object({}).passthrough().optional().describe("Drafts: per network or per account id: body, media, first_comment, thread."),
+    design: z.object({}).passthrough().optional().describe("Drafts: the filled template (see viralhunt_schedule)."),
+    png: z.string().optional().describe("Drafts: data:image/png;base64,… of the rendered design; stored and made the post's first picture."),
   },
   (a) => vh("/schedule.php", { method: "POST", query: { action: "update" }, body: {
     id: a.id, body: a.body, media: a.media, networks: a.networks, target_account_ids: a.target_account_ids, scheduled_at: a.scheduled_at,
+    first_comment: a.first_comment, author_notes: a.author_notes, kind: a.kind, overrides: a.overrides, design: a.design, png: a.png,
   } })
 );
 
+// ── What performed ──
+tool(server, "viralhunt_stats",
+  "Engagement of the published posts as the networks report it back: by_network, by_project and top_posts (with permalinks). ready=false means nothing collected yet. Use it to answer 'what worked' and to find more like the winners (viralhunt_search on the winning topic); never invent a number.",
+  {
+    project: z.string().optional(),
+    project_id: z.number().int().optional(),
+    network: z.string().optional(),
+    days: z.number().int().min(1).max(365).optional().describe("Window in days (default 30)."),
+    limit: z.number().int().min(1).max(100).optional(),
+  },
+  (a) => vh("/stats.php", { query: { project: a.project, project_id: a.project_id, network: a.network, days: a.days, limit: a.limit } })
+);
+
+// ── Quotes base ──
+tool(server, "viralhunt_calendar",
+  [
+    "The calendar base: the international days (UN, UNESCO, WHO) and the anniversaries of science, technology, space, health, the environment and civilization",
+    "in a window of days, each with `why` (what is celebrated or what happened, and why it matters: write the caption FROM it, never from memory),",
+    "kind (observance repeats every year; event, birth, death carry year and years_ago), category, origin, importance (3 = most brands can post about it,",
+    "2 = worth it inside its category, 1 = niche), image_url (a free Wikipedia thumbnail when there is one), source_url. Use days=7 or 31 to plan ahead;",
+    "post on the day. The vh-ephemeris template fits an event or a birth; the news frame fits an observance. mark_used=true with calendar_id records what you posted.",
+  ].join(" "),
+  {
+    date: z.string().optional().describe("YYYY-MM-DD or today (default today, UTC)."),
+    days: z.number().int().min(1).max(92).optional().describe("How many days from date (default 1)."),
+    category: z.string().optional().describe("One or several: science,technology,space,health,environment,humanity,civilization,education,culture,economy."),
+    kind: z.enum(["observance", "event", "birth", "death"]).optional(),
+    min_importance: z.number().int().min(1).max(3).optional().describe("3 = the big days only, 2 = worth a post (recommended), 1 = everything."),
+    lang: z.enum(["en", "es"]).optional(),
+    q: z.string().optional().describe("Keyword in the title, the text or the tags."),
+    unused: z.boolean().optional().describe("true = leave out what this organization already posted about this year."),
+    stats: z.boolean().optional().describe("true = how many rows per category and kind instead of the rows."),
+    mark_used: z.boolean().optional().describe("true with calendar_id = record that you posted about it this year."),
+    calendar_id: z.number().int().optional(),
+    note: z.string().optional(),
+  },
+  (a) => a.mark_used
+    ? vh("/calendar.php", { method: "POST", body: { action: "mark_used", calendar_id: a.calendar_id, note: a.note } })
+    : vh("/calendar.php", { query: { date: a.date, days: a.days, category: a.category, kind: a.kind, min_importance: a.min_importance, lang: a.lang, q: a.q, unused: a.unused ? 1 : undefined, stats: a.stats ? 1 : undefined } })
+);
+
+tool(server, "viralhunt_quotes",
+  [
+    "Quotes ranked by our popularity score, for daily-quote series: text, author, author_context (description, born, died), work,",
+    "categories, rights, popularity high|medium|low and author_image (portrait url, licence, credit). Default rights=public_domain",
+    "(authors dead more than 70 years): keep it unless the user asks for a modern author, and with rights=any tell the user a quote is",
+    "restricted before scheduling it under their brand. Write the caption's context FROM author_context and work, never from memory.",
+    "categories_list=true lists the categories held. unused=true leaves out what this organization already used.",
+  ].join(" "),
+  {
+    category: z.string().optional().describe("One category, e.g. stoicism."),
+    categories: z.string().optional().describe("Several mixed: stoicism,leadership."),
+    lang: z.enum(["en", "es"]).optional().describe("Language of the quote (default en)."),
+    max_chars: z.number().int().min(20).max(600).optional().describe("Default 180: what the quote templates fit."),
+    rights: z.enum(["public_domain", "any"]).optional(),
+    author: z.string().optional().describe("Part of an author's name."),
+    sort: z.enum(["score", "random"]).optional(),
+    unused: z.boolean().optional(),
+    categories_list: z.boolean().optional().describe("true = list the categories instead of quotes."),
+    per_page: z.number().int().min(1).max(50).optional(),
+    page: z.number().int().min(1).optional(),
+  },
+  (a) => vh("/quotes.php", { query: { category: a.category, categories: a.categories, lang: a.lang, max_chars: a.max_chars, rights: a.rights, author: a.author, sort: a.sort, unused: a.unused ? 1 : undefined, categories_list: a.categories_list ? 1 : undefined, per_page: a.per_page, page: a.page } })
+);
+
+tool(server, "viralhunt_mark_quote_used",
+  "After scheduling a quote, mark it used for this organization so the next pick (unused=true) is a different one.",
+  { quote_id: z.number().int(), note: z.string().optional().describe("e.g. 'scheduled 2026-09-20 09:00 instagram'.") },
+  (a) => vh("/quotes.php", { method: "POST", body: { action: "mark_used", quote_id: a.quote_id, note: a.note } })
+);
+
+// ── Recipes: standing orders a person saved in the app ──
+tool(server, "viralhunt_recipes",
+  [
+    "The standing orders of a brand, saved by a person in the app: each recipe says what to post from (source quotes|trending|manual with",
+    "source_params, and source_call = the exact request that fetches the content), which template (template.slug for viralhunt_get_template),",
+    "format, networks, cadence (daily|weekdays|weekly|manual), post_time in the project's timezone (null = the network's best time),",
+    "caption_brief and last_run_at. Nothing runs on the server: you do the loop (fetch, fill, render, schedule, mark the quote used,",
+    "then viralhunt_recipe_ran). daily with last_run_at older than today = due. Never run a paused recipe (is_active false).",
+  ].join(" "),
+  {
+    project_id: z.number().int().optional().describe("One brand (default: every active recipe of the organization)."),
+    active: z.boolean().optional(),
+  },
+  (a) => vh("/recipes.php", { query: { project_id: a.project_id, active: a.active === false ? 0 : 1 } })
+);
+
+tool(server, "viralhunt_recipe_ran",
+  "Stamp a recipe run so the person sees in the app that it happened.",
+  { recipe_id: z.number().int(), note: z.string().optional() },
+  (a) => vh("/recipes.php", { method: "POST", body: { action: "ran", recipe_id: a.recipe_id, note: a.note } })
+);
+
 // ── Content templates: browse the library ──
 tool(server, "viralhunt_list_templates",
   "List ViralHunt content templates (layouts you fill and render yourself). Lean by design — no html/css — so use viralhunt_get_template for the one you'll actually render.",
@@ -144,13 +430,20 @@ tool(server, "viralhunt_list_templates",
     project_id: z.number().int().optional().describe("With assigned=true, the project whose allowed templates you want."),
     assigned: z.boolean().optional().describe("true = only the templates assigned to project_id."),
     q: z.string().optional().describe("Search name/description."),
+    favorites: z.boolean().optional().describe("true = only the templates the brand starred. Favourites come first in every list: prefer them when several fit."),
   },
-  (a) => vh("/templates.php", { query: { category: a.category, media_type: a.media_type, network: a.network, q: a.q, assigned: a.assigned ? 1 : undefined, project_id: a.project_id } })
+  (a) => vh("/templates.php", { query: { category: a.category, media_type: a.media_type, network: a.network, q: a.q, assigned: a.assigned ? 1 : undefined, project_id: a.project_id, favorites: a.favorites ? 1 : undefined } })
 );
 
 // ── Content templates: the full layout to render ──
 tool(server, "viralhunt_get_template",
-  "Get one template's full spec: html, css, the variable manifest (with hard rules per variable), formats, palette tokens, embedded fonts and render_tech. Fill every {{variable}}, then render with headless Chrome at the chosen format's size and WAIT for [data-vh-ready='1'] before screenshotting .vh-card.",
+  [
+    "Get one template's full spec: html, css, the variable manifest (with hard rules per variable), formats, palette tokens, embedded fonts,",
+    "render_tech, plus what is `static` (the owner fixed it: logo, frame, signature, fixed texts; never move, cover or restyle it), what is",
+    "`dynamic` (the variables you fill: the picture, the headline, the caption that is the post body), what it `suits` (news, photo, quote,",
+    "number, tip, on_this_day, meme, any) and the owner's `instructions` (they override any general rule). Fill every dynamic {{variable}},",
+    "then render with headless Chrome at the chosen format's size and WAIT for [data-vh-ready='1'] before screenshotting .vh-card.",
+  ].join(" "),
   {
     slug: z.string().optional().describe("Template slug, e.g. vh-image-card."),
     id: z.number().int().optional().describe("Template id — alternative to slug."),

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "viralhunt-mcp",
   "mcpName": "io.github.rodvan/viralhunt-mcp",
-  "version": "0.2.1",
-  "description": "MCP server for ViralHunt.io: find trending/viral content across TikTok, Instagram, X, Facebook, Pinterest, Bluesky, Douyin, Reddit, Mastodon, Tumblr, Hacker News and news RSS; learn the best time to post per network from measured viral posts; get top hashtags, trending sounds and the best subreddits or Bluesky feeds for a topic; and schedule/publish/edit posts on your connected social accounts.",
+  "version": "1.1.11",
+  "description": "MCP server for ViralHunt.io: find trending/viral content across TikTok, Instagram, X, Facebook, Pinterest, Bluesky, Douyin, Reddit, Mastodon, Tumblr, Hacker News and news RSS; search one keyword on every network; learn the best time to post, top hashtags, trending sounds and the best communities; make on-brand images from the organization's templates; leave complete posts as drafts, review them, translate them into a linked project's language; and publish, schedule or edit posts on your connected social accounts.",
   "type": "module",
   "bin": {
     "viralhunt-mcp": "index.js"
   },
+  "types": "index.d.ts",
   "files": [
     "index.js",
+    "index.d.ts",
     "README.md"
   ],
   "engines": {
@@ -24,7 +26,18 @@
     "buzzsumo-alternative"
   ],
   "homepage": "https://viralhunt.io",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/viralhunt-io/viralhunt-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/viralhunt-io/viralhunt-mcp/issues"
+  },
+  "author": "ViralHunt (https://viralhunt.io)",
   "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.4",
     "zod": "^3.23.8"