VarynForge MCP Server

Add a bare article suggestion to a content plan (title + optional intent and reasoning). For richer input that produces a brief-ready suggestion, use create_article_suggestion_with_input.

Create a brief-ready article suggestion from the operator's own input. Auto-resolves a default content plan; creates/links search-query rows for the keywords; returns suggestionId + contentPlanId. Free-tier compatible (no research run required).

Delete an article suggestion and its associated brief. Cascades to keyword and cluster links.

Get the full content brief for an article suggestion. A suggestion holds one brief per channel — pass `channel` (article default | reels | youtube | x | linkedin) to pick which. Every brief carries hookStatement (one verbatim-usable hook sentence naming the reader payoff); article briefs also carry keyStats (a stat bank of { claim, value, source, sourceUrl } entries for evidence blocks and data slides). Pass compact=true to drop referenceArticles (informational only). internalLinks, curatedTargetQueries, and targetKeywords always populate. When the requested channel's brief does not exist yet, returns { hasBrief: false, briefStatus: 'queued' | 'forging' | 'none', queuedUntil } — 'queued' means the forge is waiting for the free daily cap to reset at queuedUntil; poll after that moment.

Get article suggestion details — metadata, cluster context, brief availability, registered derived assets (carousels, social posts), target keywords with volumes. Call get_article_brief for the full brief. Status semantics: generating_brief with briefQueuedAt set means the brief is QUEUED behind the free daily cap (forges automatically at reset); briefQueuedAt null means actively forging.

List article suggestions for a project — title, status, priority, cluster, intent, source, publishedAt, scheduledFor, and a per-channel distributions rollup ({ channel, count, latestAt, scheduledFor } per channel the content went out on). Use distributions to spot gaps from the list alone — e.g. items with no linkedin entry have no LinkedIn post yet — without per-item reads. Page through suggestions; call get_article_suggestion for the full record. Status semantics: generating_brief with briefQueuedAt set means the brief is QUEUED behind the free daily cap and forges automatically at cap reset (get_article_brief returns queuedUntil); generating_brief with briefQueuedAt null means it is actively forging — re-check within a minute.

Move an article through the production pipeline. Statuses: planned, generating_brief, brief_ready, drafting, draft_ready, reviewing, ready_to_publish, published. For the published transition use mark_article_published instead — it records the live URL, which Search Console outcome tracking keys off; setting status to published here records no URL. When the article is scheduled to go live later (CMS/external scheduler), pass scheduledFor with the planned date — it shows in the app and holds the "stalled at ready_to_publish" flag until the schedule lapses; do NOT call mark_article_published before the URL is live, publish auto-detect attests it (and pings IndexNow) when it actually appears.

Create a new project — pass either a website URL or a niche description (or both). Returns projectId immediately; niche analysis and asset mapping run async. Poll get_project until niche.analysisStatus is ready.

Get one project — its niche profile, target audience, and current research status.

Get the asset (website/product) associated with a project — URL, name, description, solution profile.

Get the at-a-glance read on a project — niche summary, keyword stats, nextActions (the ranked queue of what to do next in this project — offer its first entry when the operator asks "what now?"), and topPriorities: the ranked queue of article suggestions (best first — priorityScore desc; radar-born suggestions carry no score until briefed and rank oldest-first below scored ones; source tells you why score/cluster may be null). Entries already at ready_to_publish or published are done, not next — "do the next piece" = the first entry whose status still needs work (planned, brief_ready, drafting, draft_ready, reviewing).

Add a competitor to a project by domain (e.g. example.com). Marks the competitor as important or ignored on creation.

Get a competitor company detail in a project context — domain, name, importance, top pages in the project SERPs, and top keywords they rank for.

Mark a competitor important, default, or ignored. Important applies a 1.25× boost on opportunity scores for clusters where the competitor ranks top-10. Scores are then normalized 0-100 against the highest-scoring cluster, so other clusters may appear to drop in relative ranking even when their absolute (raw) scores did not change — cross-check via get_opportunity_detail.rawOpportunityScore. Ignored hides the competitor from competitor surfaces and the editorial-score pipeline.

Score a raw article idea against the project's niche without writing anything to the plan. Returns a title, angle, search intent, related queries, a coarse demand estimate, and a 0-100 niche-fit score. Pass the returned fields to accept_idea to commit the idea as a brief-ready suggestion.

Expand one radar topic (by signalObservationId + topicIndex from list_radar_topics) into 3-6 candidate article angles with title, intent, and editorial positioning; each angle is flagged when a near-duplicate already exists in the content plan. Optionally pass customPov for angles from a specific point of view. No writes — pass chosen angles to add_radar_topic.

Get the verification rubric for an article suggestion: the submission format for the channel (markdown | --- separated thread | post-with-slides | production script), required vs advisory checks, the exact numeric limits each check grades against (checkParams), plus the brief fields lint_draft reads (keywords, outline, FAQ, channel payload). Pass `channel` to read the rubric of that channel's brief (article default) — use the same channel you will pass to lint_draft. Fetch this before writing so the draft passes on the first submission.

Submit a draft for verification against its brief. Returns a pass/flag verdict with per-check detail. Pass moves the article to ready_to_publish; flag moves it to draft_ready for revision. `channel` (article | reels | youtube | x | linkedin) declares WHICH of the suggestion's per-channel briefs the draft is graded against AND the submission shape — always pass it for non-article content; when omitted, the channel is inferred from `format`. Submission shapes (get_lint_rubric returns the same spec + the numeric limits): article = markdown draft; x = thread text with one post per --- separated section, NO links in post bodies (put links in a reply); linkedin = post/caption text first, optional --- separated carousel slides after, NO links in the body (put links in the first comment); reels/youtube = the production SCRIPT — the process is brief -> script -> video, this gate validates the script, and the video is produced after it passes (published URL is recorded at publish time, not here). `format` labels the storage destination: prefer one of the project's destination type ids (see list_destinations) so receipts and drafts group per destination — re-submitting the same `format` replaces that destination's draft, a different `format` keeps both. The response reports the suggestion's post-lint `status` and a `nextAction` hint; `thresholds` is the article ratio block on the article channel and null otherwise (channel limits live in get_lint_rubric checkParams). Daily-capped; re-submitting an unchanged draft is served from cache.

Add selected angles from a radar topic to the content plan as radar-born article suggestions (provenance preserved; exact-title duplicates skipped). Angles come from expand_radar_topic; call list_radar_topics first to get signalObservationId + topicIndex. Auto-creates the content plan when the project has none. Each added suggestion lands in generating_brief and its brief forges automatically (free tier: queues past the daily cap and forges at reset) — do not also call generate_article_brief. Returns the created suggestionIds.

List the latest emergent-topic radar snapshot for a project: rising narrative topics (label, summary, momentum, novelty, drivers, evidence) with per-topic index and how many article suggestions were already added from each. Returns null when the project has no radar snapshot yet. Use expand_radar_topic to turn a topic into article angles.

Commit an expanded idea (from expand_idea) to the content plan as a brief-ready article suggestion. Stores the verbatim idea as provenance, lands the suggestion in generating_brief, and forges its brief automatically (free tier: queues past the daily cap). Returns the new suggestionId.

Get the operator account status — current plan, available credits, brief quota state, locked paid tools, the upgrade URL, and next_actions: the ranked cross-project queue of what to do next. Read on session start and after a wall hit.

List companies for a project — marked competitors (important / default / ignored) and SERP-discovered companies (unmarked). Sorted important → default → unmarked → ignored, then by domain. Pass `importance` to filter to one bucket. Capped at 100.

Create a content plan by harvesting the top-30 opportunity clusters from a completed research run. Auto-creates article suggestions linked to each cluster.

List the project's destinations — where the operator publishes (website, youtube_channel, tiktok, instagram, x, linkedin, local_business). Destination type ids are the `format` labels lint_draft stores drafts under, and they map onto brief channels (website/local_business → article, tiktok/instagram → reels, youtube_channel → youtube, x → x, linkedin → linkedin). `state` distinguishes live destinations (detected/discovered) from planned ones. An empty list means the operator has not configured destinations — fall back to the brief channel name as the lint_draft `format` label.

Get a brief as inline markdown the host agent can use as a writing prompt. Pass format=markdown_inline, and `channel` (article default) to pick which of the suggestion’s per-channel briefs to render. Returns the brief assembled into a single markdown string capped at ~8K chars — markdown only; the structured fields are get_article_brief’s job and are omitted here.

Forge a writer-ready brief from an article suggestion. `channel` picks the brief template: article (default, SEO article outline), reels (hook/beats/shot list), youtube (retention beats/chapters), x (thread posts), linkedin (carousel slide deck: cover hook, one-idea slides, recap, CTA). A suggestion holds one brief per channel — generating a second channel adds a brief without touching the others. When the suggestion already has an article brief, channel briefs DERIVE from it (its key points, hook, and keyStats flow into the channel shape) and are free — they do not consume a daily brief slot. Idempotent per channel: if that channel already has a brief, returns it without consuming a slot; pass `force: true` to regenerate it. Free tier: 10/day for article briefs and non-derived channel briefs. Returns `{ entitlement }` when the daily cap is reached.

One-call writer handoff: returns a compact writing payload for an article suggestion (brief essentials, keywords, acceptance criteria, lint instructions). Compact by design — FAQs cap at 6 and long sections degrade to fit a deep-link budget; the FULL brief is get_article_brief and the full check list is get_lint_rubric, so verify against those, not this. deepLinks (ChatGPT/Claude URLs embedding the payload) is null over MCP — it exists for web users without a connected agent.

Get the VarynForge agent guide — workflow paths (free vs paid), token-economy rules, walls and upgrade conversation conventions. Read this at session start.

Get a keyword detail — pages ranking for it with positions and ownership, plus related keywords already tracked in the project.

List keywords tracked for a project — text, difficulty, intent, volume bucket (no_traffic | long_tail | average | high). Paginated; supports sorting and intent filter.

Record that an article went live at a URL. Flips the suggestion to published, writes the distribution ledger row, stamps the Passport, and pings IndexNow. Call it only once the URL actually resolves — the IndexNow ping fires immediately, and a ping for a dead URL is wasted (search engines crawl, hit the 404, drop it; nothing re-pings later). For a CMS-scheduled article, set scheduledFor via update_article_status and stay in ready_to_publish: publish auto-detect attests it (and pings IndexNow) when it appears. Use this instead of update_article_status for the published transition — a status flip alone records no URL, and without a URL the article is invisible to Search Console outcome tracking (clicks/impressions on the Earnings page). Also works on an already-published suggestion to attach a missing or corrected URL.

Update a niche profile — name, industry, language, country. Use after the operator refines their market definition.

Diagnose where the operator is in their VarynForge journey and get a guided setup path. Call when the operator asks to set up VarynForge, get started, or seems unsure what to do next — and always when list_projects returns empty. Returns the server-derived stage, a stage-tailored pitch to relay to the operator, a setup checklist with done/pending status per step, and the ranked next_actions queue. Diagnose before prescribing: never run the welcome pitch on an operator whose stage says producing.

List content opportunity clusters sorted by opportunity score. Goal filters: fast_wins, high_intent, authority_building, competitor_gap.

Get a cluster detail — top-20 keywords by score, top-10 ranked pages by position, top-5 competitor podium, linked article suggestions, and rawOpportunityScore (un-normalized; list_opportunities returns the 0-100 normalized version).

Get a page dossier — URL, title, project rankings, ownership. `headingOutline`, `targetKeywords`, and `contentAnalysis` populate for owned (asset-mapped) pages only.

List ranked pages tracked for a project — URL, title, company, query count, ownership. Filter by ownership or company domain.

List all projects for the authenticated operator — paginated, sortable by createdAt, niche, or industry. lastActivityAt is the most recent change to the project or any of its content pieces — when the operator says "my project" without naming one, the highest lastActivityAt is the right pick.

Register a derived asset (LinkedIn carousel PDF, social post, video, image) produced from an article suggestion. Appends a distribution-ledger row so the suggestion shows everything it produced — the article plus its derivatives — for content-ROI reporting (get_article_suggestion returns them as derivedAssets). Pass `channel` (reels | youtube | x | linkedin) so the app can show per-channel distribution status; register again with a new URL for repeat posts on the same channel — every registration is kept. `scheduledFor` records a future post date from an external scheduler (Buffer etc.) for display only — VarynForge never posts on your behalf. Derivative rows never affect publish status or Search Console attribution; use mark_article_published for the article itself.

Re-crawl the project website and refresh its owned pages. Use when get_project_asset shows mappingStatus "error" or owned pages look stale. Rate-limited per site; returns an error naming the wait time if the cooldown is active.

Poll the latest research run for a project — runId, status, progress percent, elapsed seconds, and last error if failed. Token-light: returns a small fixed shape, no step payloads.

File a note to the VarynForge team: a bug, a missing capability, a friction point, or an operator idea. Call when you hit something VarynForge cannot do, a confusing tool result, or the operator voices frustration or a wish. Do NOT file entitlement walls (PAYMENT_REQUIRED / RATE_LIMITED / FEATURE_LOCKED payloads) — those are working as designed. Feedback is a note to the team, never a ticket: do not promise the operator it will be fixed.

Start a research run for a project — discovers keywords, evaluates competitors, and writes opportunity clusters. Consumes one credit. Returns `{ runId }`; poll get_research_status for progress. Returns `{ entitlement }` instead when the operator is on the free plan.

Get the writer system prompt for drafting one content type from its brief. Pass `channel` (article | x | linkedin | reels | youtube) — each channel has its own methodology: article covers voice adaptation, structure rules, and the acceptance checklist; x covers thread mechanics; linkedin covers post + carousel slides; reels and youtube cover the production script (brief -> script -> video). Load the prompt for the channel you are about to draft; article is the default.