rankcontrol 0.8.3 → 0.13.0

package/README.md

@@ -39,11 +39,12 @@ npx rankcontrol citations --model chatgpt
 npx rankcontrol crawler-access         # can AI crawlers reach your site (daily probe)
 npx rankcontrol queries                # tracked queries checked weekly across AI engines
 npx rankcontrol query-add "best crm for agencies"
+npx rankcontrol query-add "Do luggage trackers work abroad?" --covered-by <contentId>  # an article already answers it
 npx rankcontrol query-edit <queryId> "new text"
 npx rankcontrol query-track <queryId> off      # pause weekly checks (frees a slot)
 npx rankcontrol query-remove <queryId>
 npx rankcontrol competitors
-npx rankcontrol competitor-add "Acme" https://acme.com
+npx rankcontrol competitor-add "Acme"                 # site resolved from the name; pass a URL to override
 npx rankcontrol competitor-remove <competitorId>
 
 # Content pipeline
@@ -52,8 +53,9 @@ npx rankcontrol content                # pages with status
 npx rankcontrol plan-content --topics "bus travel" --max-difficulty 40
 npx rankcontrol commit-titles --file titles.json
 npx rankcontrol ideas                  # scored content-idea backlog
+npx rankcontrol idea-hide <queryId>    # hide an idea; a tracked query keeps its checks
 npx rankcontrol plan-idea "query text" # put an idea on the calendar
-npx rankcontrol delete-planned <contentId>     # title returns to the idea pool
+npx rankcontrol delete-planned <contentId>     # its keyword returns to Content Ideas
 npx rankcontrol generate <contentId> --confirm # write a planned article now
 npx rankcontrol publish <contentId> --confirm  # dry run without --confirm
 npx rankcontrol archive <contentId>
@@ -61,14 +63,15 @@ npx rankcontrol reschedule <contentId> 2026-08-04
 npx rankcontrol settings               # article policy (auto-write, auto-publish, images, ...)
 npx rankcontrol settings-set --auto-generate off --auto-publish off
 npx rankcontrol topics                 # pillar list (topic clusters)
-npx rankcontrol topics-set "Topic A" "Topic B"  # replaces the FULL list
+npx rankcontrol topics-set "Topic A" "Topic B"  # replaces the FULL list; up to 20 topics
 npx rankcontrol internal-links <contentId>     # who links here / links out
 npx rankcontrol site-pages             # pages used for internal links
 npx rankcontrol detect-links https://example.com/sitemap.xml
 npx rankcontrol add-pages https://example.com/pricing
 
-# Leads and analytics
+# Analytics
 npx rankcontrol traffic --days 30      # page views, visitors, bounce rate, time on page
+npx rankcontrol rankings               # Verified Google + Bing positions, GSC clicks/impressions/average, AI Overview rate per keyword (--scope ours|site)
 npx rankcontrol engagement             # per-page views, citations, sparkline
 npx rankcontrol analytics-sources      # which source writes traffic/crawler data
 npx rankcontrol analytics-set-source <dataType> <source>
@@ -96,13 +99,15 @@ npx rankcontrol network-remove-placement <placementId> --confirm
 npx rankcontrol repurpose [contentId]  # published articles + social drafts (8 platforms)
 npx rankcontrol repurpose-generate <contentId> --platforms twitter --confirm
 npx rankcontrol repurpose-edit <draftId> --title "New hook"
-npx rankcontrol repurpose-channels     # Postiz channel ids
-npx rankcontrol repurpose-push <draftId> --channels <id> --confirm
+npx rankcontrol repurpose-channels     # Postiz and Buffer channel ids
+npx rankcontrol repurpose-push <draftId> --channels <id> --confirm            # --scheduler postiz|buffer when both are connected
 npx rankcontrol repurpose-mark-posted <draftId>
 npx rankcontrol social                 # Reddit/X threads where your articles fit
 npx rankcontrol social-stats
-npx rankcontrol social-status <threadId> <status>
+npx rankcontrol social-status <threadId> skipped
 npx rankcontrol social-draft-reply <threadId>
+npx rankcontrol social-open <threadId> [--text "<edited reply>"]
+npx rankcontrol social-x-handle <handle|clear>
 
 # Brand, team, workspace
 npx rankcontrol brand                  # brand profile, products, ICPs in one read
@@ -110,6 +115,8 @@ npx rankcontrol brand-set --industry "SaaS"    # name, industry, description, au
 npx rankcontrol brand-profile-set --json '{"tone":"confident"}'
 npx rankcontrol brand-product --json @product.json
 npx rankcontrol brand-icp --json @icp.json
+npx rankcontrol icp-suggest                    # up to 8 audiences for this site; saves nothing
+npx rankcontrol icp-draft --describe "Ops leads at 50-500 person logistics firms"  # one profile to review; save with brand-icp
 npx rankcontrol team
 npx rankcontrol team-invite user@company.com --perms content=write,analytics=read --confirm
 npx rankcontrol team-revoke <invitationId>
@@ -147,7 +154,7 @@ Or in `.mcp.json` / Cursor `mcp.json`:
 }
 ```
 
-### Tools (83)
+### Tools (80+)
 
 **Visibility and citations**
 
@@ -164,6 +171,7 @@ Or in `.mcp.json` / Cursor `mcp.json`:
 | `get_crawler_access` | Daily AI-crawler reachability probe (edge blocks, robots.txt) |
 | `list_tracked_queries` | The queries checked weekly across the AI engines |
 | `add_tracked_query` / `update_tracked_query` / `set_query_tracking` / `remove_tracked_query` | Manage the query pool and its plan slots |
+| `hide_content_idea` | Hide an idea from Content Ideas; a tracked query keeps its weekly checks and its slot |
 | `get_competitors` / `add_competitor` / `remove_competitor` | Manage share-of-voice competitors (max 10) |
 
 **Content pipeline**
@@ -180,16 +188,17 @@ Or in `.mcp.json` / Cursor `mcp.json`:
 | `archive_content` | Archive an article (reversible in the dashboard) |
 | `reschedule_article` | Move a planned article to another day (flexible schedule) |
 | `get_article_settings` / `update_article_settings` | Read / merge-patch the article policy |
-| `get_topics` / `set_topics` | Read / replace the pillar list (full-list replace) |
+| `get_topics` / `set_topics` | Read / replace the pillar list (full-list replace, up to 20 topics) |
 | `get_internal_links` | Who links to this article internally, and its outbound count |
 | `list_site_pages` / `add_site_pages` / `detect_site_links` | Pages used for in-article internal links |
 | `list_content` | Content pages with status |
 
-**Leads and analytics**
+**Analytics**
 
 | Tool | What it does |
 |---|---|
 | `get_traffic_overview` | Page views, visitors, sessions, bounce rate, time on page |
+| `get_rankings` | Verified Google and Bing positions per keyword, Search Console clicks, impressions and average position (never shown as a rank), which page earned each query and whether it is yours, how often Google's AI Overview shows and cites you; `scope` ours (default) or site |
 | `get_page_engagement` | Per-page views, citations, and a view sparkline |
 | `get_analytics_sources` / `set_analytics_source` | Which source writes traffic and crawler data |
 | `activate_analytics_screen` | One-time activation of the Analytics or Reports screen |
@@ -222,10 +231,10 @@ Or in `.mcp.json` / Cursor `mcp.json`:
 |---|---|
 | `list_repurpose_queue` / `get_repurpose_drafts` | Published articles + social drafts (8 platforms) |
 | `generate_repurpose_drafts` / `update_repurpose_draft` | Draft and edit platform-native posts |
-| `list_postiz_channels` / `push_repurpose_draft` | Push to Postiz; dry run by default |
+| `list_postiz_channels` / `push_repurpose_draft` | Push to Buffer or Postiz; dry run by default |
 | `mark_repurpose_posted` | Record a draft as posted manually |
 | `list_social_threads` / `get_social_stats` | Reddit/X threads where your articles fit |
-| `update_social_thread_status` / `draft_social_reply` | Work a thread; drafts never auto-post |
+| `update_social_thread_status` / `draft_social_reply` / `open_social_thread` / `set_social_x_handle` | Work a thread: draft, then open it to post yourself (X gets a pre-filled composer link); the thread marks itself Posted once your reply is found. Drafts never auto-post; Posted is never set by hand |
 
 **Brand, team, workspace**
 
@@ -235,6 +244,7 @@ Or in `.mcp.json` / Cursor `mcp.json`:
 | `update_brand_identity` | Name, industry, description, authors (EEAT bylines), style refs |
 | `update_brand_profile` | Voice, colors, meta fields, locale |
 | `write_brand_product` / `write_brand_icp` | Create/update/delete products and buyer profiles |
+| `suggest_brand_icps` / `draft_brand_icp` | Suggest audiences for this site and draft one buyer profile to review; nothing is saved until `write_brand_icp` |
 | `get_team` / `invite_team_member` / `revoke_team_invite` / `remove_team_member` | Seats, invites, per-screen permissions |
 | `contact_support` | Message the RankControl team with the workspace identified |
 

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "rankcontrol",
-  "version": "0.8.3",
+  "version": "0.13.0",
   "description": "RankControl CLI + MCP server: drive your SEO/AI-visibility workspace from the terminal or any AI agent",
   "license": "MIT",
+  "scripts": {
+    "prepublishOnly": "node ../../scripts/check-package-parity.mjs"
+  },
   "homepage": "https://rctrl.com",
   "type": "module",
   "bin": {

package/src/cli.mjs

@@ -58,6 +58,12 @@ export function runCli(argv) {
     .option("--days <n>", "7, 30 or 90", "30")
     .action((opts) => api.trafficOverview(Number(opts.days)).then(out).catch(fail));
 
+  program
+    .command("rankings")
+    .description("Verified Google and Bing positions per keyword, Search Console clicks, impressions and average position when connected (an average, never a rank), which page earned each query, and how often Google's AI Overview shows above it and cites you")
+    .option("--scope <scope>", '"ours" (default): queries your published articles appear for; "site": everything on the domain', "ours")
+    .action((opts) => api.rankings(opts.scope).then(out).catch(fail));
+
   program
     .command("score")
     .description("Composite visibility score blending AI citation rate with Google and Bing rank share, with subscores")
@@ -198,19 +204,26 @@ export function runCli(argv) {
 
   program
     .command("query-add")
-    .description("Add a query to the tracking pool (tracks immediately when a plan slot is free)")
+    .description("Add a query (tracks immediately when a tracking slot is free)")
     .argument("<queryText>", "The search/AI query to track")
-    .action((queryText) => api.addQuery(queryText).then(out).catch(fail));
+    .option("--covered-by <contentId>", "Article that already answers this query, so Content Ideas skips it")
+    .action((queryText, opts) => api.addQuery(queryText, opts.coveredBy).then(out).catch(fail));
+
+  program
+    .command("idea-hide")
+    .description("Hide an idea from Content Ideas. A tracked query keeps its weekly checks")
+    .argument("<queryId>", "Idea id (from the ideas command)")
+    .action((queryId) => api.hideIdea(queryId).then(out).catch(fail));
 
   program
     .command("query-remove")
-    .description("Delete a query from the tracking pool")
+    .description("Delete a query")
     .argument("<queryId>", "Query id (from the queries command)")
     .action((queryId) => api.removeQuery(queryId).then(out).catch(fail));
 
   program
     .command("query-track")
-    .description("Pause or resume weekly checks on a query. Tracking uses a plan slot; pausing frees it")
+    .description("Pause or resume weekly checks on a query. Tracking uses one of your tracking slots; pausing frees it")
     .argument("<queryId>", "Query id (from the queries command)")
     .argument("<state>", "on | off")
     .action((queryId, state) =>
@@ -228,14 +241,14 @@ export function runCli(argv) {
 
   program
     .command("competitors")
-    .description("Tracked competitors used in share-of-voice and visibility comparisons")
+    .description("Tracked competitors used in share-of-voice and visibility comparisons, with each one's AI visibility score, citations of checks over the last 30 days, domain metrics and positioning analysis")
     .action(() => api.competitors().then(out).catch(fail));
 
   program
     .command("competitor-add")
-    .description("Track a competitor (max 10)")
+    .description("Track a competitor (max 10); the site is resolved from the name when omitted")
     .argument("<name>", "Competitor name")
-    .argument("<websiteUrl>", "Competitor website URL")
+    .argument("[websiteUrl]", "Competitor website URL (optional)")
     .action((name, websiteUrl) =>
       api.addCompetitor(name, websiteUrl).then(out).catch(fail)
     );
@@ -255,7 +268,7 @@ export function runCli(argv) {
 
   program
     .command("topics-set")
-    .description("Replace the full pillar list (create/dedupe/safe-delete reconcile)")
+    .description("Replace the full pillar list (create/dedupe/safe-delete reconcile); up to 20 topics")
     .argument("<topics...>", "Topic names, space-separated (quote multi-word topics)")
     .action((topics) => api.setTopics(topics).then(out).catch(fail));
 
@@ -492,11 +505,10 @@ export function runCli(argv) {
 
   program
     .command("reschedule <contentId> <date>")
-    .description("Move a planned article to a day (YYYY-MM-DD, local time; needs the flexible schedule)")
+    .description("Move a planned article to a day (YYYY-MM-DD in the workspace's timezone; needs the flexible schedule)")
     .action((contentId, date) => {
-      const day = new Date(`${date}T00:00:00`);
-      if (Number.isNaN(day.getTime())) return fail(new Error("Date must be YYYY-MM-DD"));
-      return api.reschedule(contentId, day.getTime()).then(out).catch(fail);
+      if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) return fail(new Error("Date must be YYYY-MM-DD"));
+      return api.reschedule(contentId, date).then(out).catch(fail);
     });
 
   program
@@ -536,7 +548,7 @@ export function runCli(argv) {
 
   program
     .command("repurpose-generate <contentId>")
-    .description("Draft social posts for a published article (dry run unless --confirm; costly)")
+    .description("Draft social posts for a published article that has none yet (dry run unless --confirm; costly)")
     .option(
       "--platforms <a,b>",
       "Subset: linkedin,twitter,pinterest,instagram,facebook,threads,youtube,tiktok"
@@ -572,20 +584,22 @@ export function runCli(argv) {
 
   program
     .command("repurpose-channels")
-    .description("Connected Postiz channels (ids needed for repurpose-push)")
+    .description("Connected Postiz and Buffer channels (ids needed for repurpose-push)")
     .action(() => api.repurposeChannels().then(out).catch(fail));
 
   program
     .command("repurpose-push <draftId>")
-    .description("Send a draft to Postiz (dry run unless --confirm)")
-    .option("--channels <id1,id2>", "Postiz channel ids (see repurpose-channels)")
-    .option("--when <now|schedule|draft>", "Postiz mode", "now")
+    .description("Send a draft to Postiz or Buffer (dry run unless --confirm)")
+    .option("--scheduler <postiz|buffer>", "Which scheduler (required when both are connected)")
+    .option("--channels <id1,id2>", "Channel ids (see repurpose-channels)")
+    .option("--when <now|schedule|draft|queue>", "Mode; queue is Buffer only", "now")
     .option("--date <iso>", "ISO time for --when schedule")
     .option("--confirm", "Actually push (publicly visible)")
     .action((draftId, opts) =>
       api
         .repurposePush({
           draftId,
+          scheduler: opts.scheduler,
           integrationIds: opts.channels ? list(opts.channels) : undefined,
           scheduleType: opts.when,
           date: opts.date,
@@ -707,11 +721,28 @@ export function runCli(argv) {
 
   program
     .command("social-status <threadId> <status>")
-    .description("Move a social thread through the pipeline")
+    .description("Skip a thread (the only manual status; Posted is detected automatically)")
     .action((threadId, status) =>
       api.socialStatus(threadId, status).then(out).catch(fail)
     );
 
+  program
+    .command("social-open <threadId>")
+    .description(
+      "Take a drafted reply to the platform yourself: prints the thread URL (for X, a composer link with the reply filled in) and starts the checks that mark it Posted"
+    )
+    .option("--text <reply>", "Use an edited reply (X: 280 characters or fewer)")
+    .action((threadId, opts) =>
+      api.socialOpen(threadId, opts.text).then(out).catch(fail)
+    );
+
+  program
+    .command("social-x-handle <handle>")
+    .description("Save the X handle used to recognise your posted replies (\"clear\" removes it)")
+    .action((handle) =>
+      api.socialXHandle(handle === "clear" ? "" : handle).then(out).catch(fail)
+    );
+
   program
     .command("social-draft-reply <threadId>")
     .description("AI-draft a reply for a thread (nothing posts; the draft lands for review)")
@@ -773,5 +804,29 @@ export function runCli(argv) {
       api.brandIcpWrite(parseJson(opts.json, "brand-icp")).then(out).catch(fail)
     );
 
+  program
+    .command("icp-suggest")
+    .description("Suggest up to 8 audiences for this site from its brand, products, competitors and topics (saves nothing)")
+    .option("--exclude <titles...>", "Audience titles already shown, to get different ones")
+    .action((opts) => api.suggestIcps(opts.exclude ?? []).then(out).catch(fail));
+
+  program
+    .command("icp-draft")
+    .description("Draft one buyer profile from a sentence or a suggestion (saves nothing; save it with brand-icp)")
+    .option("--describe <sentence>", "Who the audience is, in one sentence")
+    .option("--title <title>", "Title of a suggestion from icp-suggest")
+    .option("--who <sentence>", "The suggestion's one-line description")
+    .option("--json <json>", "Fields to keep as written, JSON (or @file.json); a key you pass is kept, a key you leave out is filled")
+    .action((opts) =>
+      api
+        .draftIcp({
+          describe: opts.describe,
+          suggestion: opts.title ? { title: opts.title, who: opts.who } : undefined,
+          given: opts.json ? parseJson(opts.json, "icp-draft") : undefined,
+        })
+        .then(out)
+        .catch(fail)
+    );
+
   program.parseAsync(argv);
 }

package/src/client.mjs

@@ -124,8 +124,8 @@ export const api = {
   articleSettings: () => request("GET", "/api/v1/settings/articles"),
   updateArticleSettings: (opts) =>
     request("POST", "/api/v1/settings/articles", opts),
-  reschedule: (contentId, targetDayStartMs) =>
-    request("POST", "/api/v1/content/reschedule", { contentId, targetDayStartMs }),
+  reschedule: (contentId, date) =>
+    request("POST", "/api/v1/content/reschedule", { contentId, date }),
   sitePages: () => request("GET", "/api/v1/links/pages"),
   detectSiteLinks: (source, url) =>
     request("POST", "/api/v1/links/detect", { source, url }),
@@ -144,9 +144,12 @@ export const api = {
     request("POST", "/api/v1/repurpose/mark-posted", { draftId }),
   repurposePush: (opts) => request("POST", "/api/v1/repurpose/push", opts),
   trackedQueries: () => request("GET", "/api/v1/queries"),
-  addQuery: (queryText) => request("POST", "/api/v1/queries", { queryText }),
+  addQuery: (queryText, coveredByContentId) =>
+    request("POST", "/api/v1/queries", coveredByContentId ? { queryText, coveredByContentId } : { queryText }),
   removeQuery: (queryId) =>
     request("POST", "/api/v1/queries/remove", { queryId }),
+  hideIdea: (queryId) =>
+    request("POST", "/api/v1/content/ideas/hide", { queryId }),
   setQueryTracking: (queryId, tracked) =>
     request("POST", "/api/v1/queries/set-tracking", { queryId, tracked }),
   updateQuery: (queryId, queryText) =>
@@ -163,6 +166,8 @@ export const api = {
   crawlerAccess: () => request("GET", "/api/v1/crawler-access"),
   trafficOverview: (days = 30) =>
     request("GET", `/api/v1/analytics/traffic?days=${days}`),
+  rankings: (scope = "ours") =>
+    request("GET", `/api/v1/analytics/rankings?scope=${scope === "site" ? "site" : "ours"}`),
   analyticsSources: () => request("GET", "/api/v1/analytics/sources"),
   setAnalyticsSource: (dataType, source) =>
     request("POST", "/api/v1/analytics/sources", { dataType, source }),
@@ -232,10 +237,17 @@ export const api = {
     request("POST", "/api/v1/social/status", { threadId, status }),
   socialDraftReply: (threadId, mentionMode) =>
     request("POST", "/api/v1/social/draft-reply", { threadId, mentionMode }),
+  socialOpen: (threadId, text) =>
+    request("POST", "/api/v1/social/open", { threadId, text }),
+  socialXHandle: (handle) =>
+    request("POST", "/api/v1/social/x-handle", { handle }),
   support: (opts) => request("POST", "/api/v1/support", opts),
   brand: () => request("GET", "/api/v1/brand"),
   brandIdentitySet: (opts) => request("POST", "/api/v1/brand", opts),
   brandProfileSet: (opts) => request("POST", "/api/v1/brand/profile", opts),
   brandProductWrite: (opts) => request("POST", "/api/v1/brand/product", opts),
   brandIcpWrite: (opts) => request("POST", "/api/v1/brand/icp", opts),
+  suggestIcps: (exclude = []) =>
+    request("POST", "/api/v1/brand/icp/suggest", { exclude }),
+  draftIcp: (opts) => request("POST", "/api/v1/brand/icp/draft", opts),
 };

package/src/login.mjs

@@ -13,13 +13,10 @@ const DEFAULT_SCOPES = [
   "read:content",
   "read:analytics",
   "write:content",
-  "write:queries",
   "write:backlinks",
   "write:social",
   "write:publish",
-  "manage:integrations",
   "manage:org",
-  "trigger:agents",
 ];
 
 function openBrowser(url) {

package/src/mcp.mjs

@@ -29,7 +29,7 @@ const plannedTitle = z.object({
 });
 
 export async function startMcpServer() {
-  const server = new McpServer({ name: "rankcontrol", version: "0.8.3" });
+  const server = new McpServer({ name: "rankcontrol", version: "0.13.0" });
 
   server.tool(
     "get_overview_funnel",
@@ -195,21 +195,34 @@ export async function startMcpServer() {
 
   server.tool(
     "add_tracked_query",
-    "Add a query to the tracking pool. It starts weekly AI citation checks immediately when a plan slot is free; otherwise it joins the pool untracked.",
-    { queryText: z.string().describe("The search/AI query to track") },
-    run(({ queryText }) => api.addQuery(queryText))
+    "Add a query. Weekly AI citation checks start immediately when a tracking slot is free; otherwise it is saved untracked. Pass coveredByContentId when the query is a question an existing article already answers, so Content Ideas does not offer it again.",
+    {
+      queryText: z.string().describe("The search/AI query to track"),
+      coveredByContentId: z
+        .string()
+        .optional()
+        .describe("contentPage id of the article that already answers this query"),
+    },
+    run(({ queryText, coveredByContentId }) => api.addQuery(queryText, coveredByContentId))
+  );
+
+  server.tool(
+    "hide_content_idea",
+    "Hide an idea from Content Ideas. A tracked query keeps its weekly checks and its slot; use remove_tracked_query to delete a query outright.",
+    { queryId: z.string().describe("Idea id from get_content_ideas") },
+    run(({ queryId }) => api.hideIdea(queryId))
   );
 
   server.tool(
     "remove_tracked_query",
-    "Delete a query from the tracking pool. Frees its plan slot if it was tracking.",
+    "Delete a query. Frees its tracking slot if it was tracked.",
     { queryId: z.string().describe("Query id from get_tracked_queries") },
     run(({ queryId }) => api.removeQuery(queryId))
   );
 
   server.tool(
     "set_query_tracking",
-    "Pause or resume weekly AI citation checks on a pooled query. Tracking consumes one plan slot; pausing frees it. The query stays in the pool either way.",
+    "Pause or resume weekly AI citation checks on a saved query. Tracking uses one of the plan's tracking slots; pausing frees it. The query is kept either way.",
     {
       queryId: z.string().describe("Query id from get_tracked_queries"),
       tracked: z.boolean().describe("true to track weekly, false to pause"),
@@ -229,17 +242,20 @@ export async function startMcpServer() {
 
   server.tool(
     "get_competitors",
-    "Tracked competitors used in share-of-voice and visibility comparisons.",
+    "Tracked competitors used in share-of-voice and visibility comparisons, with each one's AI visibility score, citations of checks over the last 30 days, domain metrics and positioning analysis.",
     {},
     run(() => api.competitors())
   );
 
   server.tool(
     "add_competitor",
-    "Track a competitor (max 10). They enter weekly share-of-voice comparisons against the org's own citation rate.",
+    "Track a competitor (max 10). They enter weekly share-of-voice comparisons against the org's own citation rate. Omit websiteUrl to have the site resolved from the name.",
     {
       name: z.string().describe("Competitor name"),
-      websiteUrl: z.string().describe("Competitor website URL"),
+      websiteUrl: z
+        .string()
+        .optional()
+        .describe("Competitor website URL (optional; resolved from the name when omitted)"),
     },
     run(({ name, websiteUrl }) => api.addCompetitor(name, websiteUrl))
   );
@@ -260,7 +276,7 @@ export async function startMcpServer() {
 
   server.tool(
     "set_topics",
-    "Replace the FULL pillar list. Send every topic that should exist; missing ones are safe-deleted, new ones created, duplicates merged. Read get_topics first and modify that list.",
+    "Replace the FULL pillar list. Send every topic that should exist; missing ones are safe-deleted, new ones created, duplicates merged. Read get_topics first and modify that list. Up to 20 topics.",
     {
       topics: z.array(z.string()).describe("The complete list of topic names"),
     },
@@ -269,7 +285,7 @@ export async function startMcpServer() {
 
   server.tool(
     "delete_planned_title",
-    "Remove a planned title from the content calendar. The title returns to Content Ideas as a pool query (deduped), so the topic is not lost. Only planned rows qualify; use archive for generated articles.",
+    "Remove a planned title from the content calendar. The title's keyword returns to Content Ideas as a saved query, so the topic is not lost. Only planned rows qualify; use archive for generated articles.",
     { contentId: z.string().describe("Planned contentPage id") },
     run(({ contentId }) => api.deletePlanned(contentId))
   );
@@ -281,6 +297,18 @@ export async function startMcpServer() {
     run(({ days }) => api.trafficOverview(days ? Number(days) : 30))
   );
 
+  server.tool(
+    "get_rankings",
+    "Verified Google and Bing positions per keyword (top 30), with Search Console clicks, impressions and average position when connected (gscPosition is an average over the searches you appeared in, never a rank), which page earned each query and whether it is one of your articles (isOurs), and how often Google's AI Overview shows above each keyword and cites one of your pages (a rate over the last 8 weekly checks). Defaults to queries your published articles appear for.",
+    {
+      scope: z
+        .enum(["ours", "site"])
+        .optional()
+        .describe('"ours" (default): queries your published articles appear for. "site": everything on the domain.'),
+    },
+    run(({ scope }) => api.rankings(scope ?? "ours"))
+  );
+
   server.tool(
     "get_planning_capacity",
     "How many article titles can still be planned onto the content calendar within the scheduling horizon. Check before plan_content.",
@@ -360,7 +388,7 @@ export async function startMcpServer() {
 
   server.tool(
     "queue_outreach_email",
-    "Queue an outreach email to a prospect. It sends from the workspace's own connected mailbox, paced automatically with a daily cap. Uses the stored draft unless subject/body are given. Dry-run unless confirm is true — a confirmed queue leads to a REAL email being sent.",
+    "Queue an outreach email to a prospect. It sends from the workspace's own connected mailbox, paced automatically with a daily cap. Uses the stored draft unless subject/body are given; a \"[Your name]\" sign-off in the draft is replaced with the owner's profile name at send time. Dry-run unless confirm is true — a confirmed queue leads to a REAL email being sent.",
     {
       backlinkId: z.string().describe("Prospect id from list_outreach_prospects"),
       subject: z.string().optional().describe("Override the drafted subject"),
@@ -400,7 +428,7 @@ export async function startMcpServer() {
 
   server.tool(
     "commit_planned_titles",
-    "Approve reviewed titles onto the content calendar (the approval half of the plan→commit gate). Pass rejected candidates in `discarded` so their keywords recycle into the idea pool.",
+    "Approve reviewed titles onto the content calendar (the approval half of the plan→commit gate). Pass rejected candidates in `discarded` so their keywords recycle into Content Ideas.",
     {
       titles: z.array(plannedTitle).describe("Titles to schedule"),
       discarded: z.array(plannedTitle).optional().describe("Rejected candidates"),
@@ -410,7 +438,7 @@ export async function startMcpServer() {
 
   server.tool(
     "publish_content",
-    "Publish an article to the customer's connected CMS. Defaults to a DRY RUN describing what would happen; a human should approve before calling again with confirm=true.",
+    "Publish an article to the customer's connected CMS. Defaults to a DRY RUN describing what would happen; a human should approve before calling again with confirm=true. Delivery runs after this call returns. If the article does not go live, list_content shows its lastPublishError. Webhook receivers: https://rctrl.com/docs/webhook",
     {
       contentId: z.string().describe("The content page id"),
       confirm: z.boolean().optional().describe("Set true to actually publish (default: dry run)"),
@@ -446,7 +474,7 @@ export async function startMcpServer() {
 
   const articleSettingsShape = {
     autoPublish: z.boolean().optional(),
-    autoGenerate: z.boolean().optional().describe("Off = fully manual mode: articles are written only on demand (generate_article) and publish only from the editor"),
+    autoGenerate: z.boolean().optional().describe("Off = fully manual mode: articles are written only on demand (generate_article) and publish only from the editor. Turning it on needs a publishing destination that has already put at least one article live on the site."),
     includeInfographics: z.boolean().optional().describe("AI hero + section images"),
     titleInHeroImage: z.boolean().optional().describe("Write the post title into the hero image"),
     includeSectionInfographics: z.boolean().optional().describe("Informational panels in 2,000+ word articles"),
@@ -481,12 +509,12 @@ export async function startMcpServer() {
 
   server.tool(
     "reschedule_article",
-    "Move a PLANNED article to another day (requires the flexible schedule; max 5/day; the exact hour is placed automatically). Pass the target day as epoch ms of local midnight.",
+    "Move a PLANNED article to another day (requires the flexible schedule; max 5/day; the exact hour is placed automatically). Pass the target day as YYYY-MM-DD in the workspace's timezone.",
     {
       contentId: z.string(),
-      targetDayStartMs: z.number().describe("Epoch ms of the target day's local midnight"),
+      date: z.string().describe("Target day as YYYY-MM-DD in the workspace's timezone"),
     },
-    run(({ contentId, targetDayStartMs }) => api.reschedule(contentId, targetDayStartMs))
+    run(({ contentId, date }) => api.reschedule(contentId, date))
   );
 
   server.tool(
@@ -522,7 +550,7 @@ export async function startMcpServer() {
 
   server.tool(
     "list_repurpose_queue",
-    "Published articles with their social repurpose drafts per platform (platform + status chips). Shows which articles still need drafts and whether Postiz is connected.",
+    "Published articles with their social repurpose drafts per platform (platform + status chips). Shows which articles still need drafts and which scheduler is connected (Buffer or Postiz).",
     {},
     run(() => api.repurposeQueue())
   );
@@ -536,7 +564,7 @@ export async function startMcpServer() {
 
   server.tool(
     "generate_repurpose_drafts",
-    "Draft platform-native social posts for a published article. Regeneration replaces unposted drafts for the chosen platforms. Defaults to a DRY RUN; confirm=true generates (costly).",
+    "Draft platform-native social posts for a published article. Only for an article with no drafts yet; edit or dismiss existing drafts in the dashboard. Defaults to a DRY RUN; confirm=true generates (costly).",
     {
       contentId: z.string(),
       platforms: z
@@ -572,33 +600,37 @@ export async function startMcpServer() {
 
   server.tool(
     "mark_repurpose_posted",
-    "Mark a repurpose draft as posted — use after publishing its text manually (outside Postiz).",
+    "Mark a repurpose draft as posted — use after publishing its text manually (outside Buffer or Postiz).",
     { draftId: z.string() },
     run(({ draftId }) => api.repurposeMarkPosted(draftId))
   );
 
   server.tool(
     "list_postiz_channels",
-    "Connected Postiz social channels (id, name, platform). Channel ids are required by push_repurpose_draft.",
+    "Connected social channels across Postiz and Buffer (scheduler, id, name, platform). Channel ids are required by push_repurpose_draft.",
     {},
     run(() => api.repurposeChannels())
   );
 
   server.tool(
     "push_repurpose_draft",
-    "Send a repurpose draft to connected Postiz channels (post now, schedule, or save as a Postiz draft). PUBLICLY VISIBLE side effect: defaults to a DRY RUN; a human should approve before calling again with confirm=true.",
+    "Send a repurpose draft to a connected scheduler's channels: Postiz or Buffer (post now, schedule, save as a draft, or add to Buffer's queue). PUBLICLY VISIBLE side effect: defaults to a DRY RUN; a human should approve before calling again with confirm=true.",
     {
       draftId: z.string(),
+      scheduler: z
+        .enum(["postiz", "buffer"])
+        .optional()
+        .describe("Which scheduler; required when both are connected"),
       integrationIds: z
         .array(z.string())
         .optional()
         .describe(
-          "Postiz channel ids from list_postiz_channels (required with confirm)"
+          "Channel ids from list_postiz_channels (required with confirm)"
         ),
       scheduleType: z
-        .enum(["now", "schedule", "draft"])
+        .enum(["now", "schedule", "draft", "queue"])
         .optional()
-        .describe("Default now"),
+        .describe("Default now; queue is Buffer only"),
       date: z.string().optional().describe("ISO time for scheduleType=schedule"),
       confirm: z.boolean().optional(),
     },
@@ -662,13 +694,13 @@ export async function startMcpServer() {
 
   server.tool(
     "list_backlinks",
-    "The workspace's backlink table, newest first.",
+    "The workspace's backlink table, newest first. Each row carries its source (index, outreach, managed, network).",
     {
       status: z
         .string()
         .optional()
         .describe(
-          "Filter: discovered, verified, lost, identified, contacted, replied, link_placed, rejected"
+          "Filter: discovered, verified, lost, placed, identified, contacted, replied, link_placed, rejected"
         ),
     },
     run(({ status }) => api.backlinks(status))
@@ -732,11 +764,25 @@ export async function startMcpServer() {
 
   server.tool(
     "update_social_thread_status",
-    "Move a social thread through the pipeline (e.g. dismissed, replied).",
+    "Skip a social thread so it leaves the queue (the only manual status; Posted is set automatically once your reply is found in the thread).",
     { threadId: z.string(), status: z.string() },
     run(({ threadId, status }) => api.socialStatus(threadId, status))
   );
 
+  server.tool(
+    "open_social_thread",
+    "Open a drafted social thread to post the reply yourself: returns the thread URL (for X, a link that opens X's composer with the reply filled in) and starts four checks over 72 hours that mark the thread Posted once your reply is found there. Pass text to use an edited reply; X replies must be 280 characters or fewer.",
+    { threadId: z.string(), text: z.string().optional() },
+    run(({ threadId, text }) => api.socialOpen(threadId, text))
+  );
+
+  server.tool(
+    "set_social_x_handle",
+    "Save the X handle used to recognise your posted replies (optional; text matching covers the rest). Pass an empty handle to clear it.",
+    { handle: z.string() },
+    run(({ handle }) => api.socialXHandle(handle))
+  );
+
   server.tool(
     "draft_social_reply",
     "AI-draft a reply for a social thread. Nothing posts — the draft lands on the thread for human review. Subject to the same warm-up/pacing guards as the dashboard.",
@@ -849,6 +895,30 @@ export async function startMcpServer() {
     run((args) => api.brandIcpWrite(args))
   );
 
+  server.tool(
+    "suggest_brand_icps",
+    "Suggest up to 8 audiences for this site from its brand, products, competitors and topics. Saves nothing. Pick one and pass it to draft_brand_icp, or write your own with write_brand_icp.",
+    { exclude: z.array(z.string()).optional().describe("Audience titles already shown, to get different ones") },
+    run(({ exclude }) => api.suggestIcps(exclude ?? []))
+  );
+
+  server.tool(
+    "draft_brand_icp",
+    "Draft one buyer profile from a one-sentence description or a suggestion from suggest_brand_icps. Returns the fields to review; nothing is saved until write_brand_icp. Fields passed in given are kept as written.",
+    {
+      describe: z.string().optional().describe("Who the audience is, in one sentence"),
+      title: z.string().optional().describe("Title of a suggestion from suggest_brand_icps"),
+      who: z.string().optional().describe("The suggestion's one-line description"),
+      given: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .describe("Fields to keep as written (same keys as write_brand_icp, plus ageRange, seniority, department as strings). A key you pass is kept, empty included; a key you leave out is filled."),
+    },
+    run(({ describe, title, who, given }) =>
+      api.draftIcp({ describe, suggestion: title ? { title, who } : undefined, given })
+    )
+  );
+
   await server.connect(new StdioServerTransport());
   // Keep the process alive; the transport owns stdin/stdout from here
   console.error("rankcontrol MCP server running on stdio");