rankcontrol 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Infowick
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# rankcontrol
+
+RankControl from the terminal or any AI agent. One package, two faces:
+
+- **CLI** — `npx rankcontrol <command>` (or the short alias `rctrl` once installed)
+- **MCP server** — `npx rankcontrol mcp` (stdio, for Claude Code, Claude Desktop, Cursor, Codex)
+
+Every command calls the same authed, rate-limited, org-scoped API the RankControl dashboard uses. Quotas and approval gates apply server-side no matter which client calls.
+
+## Auth
+
+Create an API key in **RankControl → Settings → API**, then:
+
+```bash
+export RANKCONTROL_API_KEY=rctrl_pk_...
+```
+
+Scopes are set per key. Read-only keys work for all `get_*`/`list_*` tools.
+
+## CLI
+
+```bash
+npx rankcontrol funnel                 # AI crawls / AI visits / AI leads (30d)
+npx rankcontrol visibility --days 60   # daily AI visibility score trend
+npx rankcontrol citations --model chatgpt
+npx rankcontrol capacity               # remaining content-plan slots
+npx rankcontrol plan-content --topics "bus travel" --max-difficulty 40
+npx rankcontrol commit-titles --file titles.json
+npx rankcontrol publish <contentId>            # dry run
+npx rankcontrol publish <contentId> --confirm  # actually publish
+npx rankcontrol jobs                   # async job status (agent runs)
+```
+
+## MCP
+
+Claude Code:
+
+```bash
+claude mcp add rankcontrol --env RANKCONTROL_API_KEY=rctrl_pk_... -- npx rankcontrol mcp
+```
+
+Or in `.mcp.json` / Cursor `mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "rankcontrol": {
+      "command": "npx",
+      "args": ["rankcontrol", "mcp"],
+      "env": { "RANKCONTROL_API_KEY": "rctrl_pk_..." }
+    }
+  }
+}
+```
+
+### Tools
+
+| Tool | What it does |
+|---|---|
+| `get_overview_funnel` | AI crawls / AI visits / AI leads, last 30 days |
+| `get_visibility_trend` | Daily visibility score from stored weekly citation checks |
+| `list_citations` | Recent citation checks per AI model |
+| `get_visibility_score` | Current overall AI visibility score |
+| `get_planning_capacity` | Remaining calendar slots (check before planning) |
+| `plan_content` | Generate candidate titles (capacity-gated, nothing scheduled) |
+| `commit_planned_titles` | Approve reviewed titles onto the calendar |
+| `publish_content` | Dry run by default; `confirm: true` publishes |
+| `list_content` | Content pages with status |
+| `list_jobs` | Async job status (agent runs) |
+
+The plan→commit split is intentional: `plan_content` proposes, a human (or a supervising agent) reviews, `commit_planned_titles` approves. `publish_content` is dry-run-first for the same reason.

package/bin/rankcontrol.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runCli } from "../src/cli.mjs";
+
+runCli(process.argv);

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "rankcontrol",
+  "version": "0.1.0",
+  "description": "RankControl CLI + MCP server: drive your SEO/AI-visibility workspace from the terminal or any AI agent",
+  "license": "MIT",
+  "homepage": "https://rctrl.com",
+  "type": "module",
+  "bin": {
+    "rankcontrol": "bin/rankcontrol.mjs",
+    "rctrl": "bin/rankcontrol.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "commander": "^12.1.0",
+    "zod": "^3.24.0"
+  },
+  "keywords": [
+    "seo",
+    "aeo",
+    "ai-visibility",
+    "mcp",
+    "model-context-protocol",
+    "rankcontrol"
+  ]
+}

package/src/cli.mjs

@@ -0,0 +1,118 @@
+import { Command } from "commander";
+import { readFileSync } from "node:fs";
+import { api } from "./client.mjs";
+
+const out = (data) => console.log(JSON.stringify(data, null, 2));
+
+const fail = (err) => {
+  console.error(`Error: ${err?.message ?? String(err)}`);
+  process.exit(1);
+};
+
+const list = (val) => val.split(",").map((s) => s.trim()).filter(Boolean);
+
+export function runCli(argv) {
+  const program = new Command();
+  program
+    .name("rankcontrol")
+    .description(
+      "RankControl from the terminal. Auth: export RANKCONTROL_API_KEY=rctrl_pk_... (Settings → API)"
+    )
+    .version("0.1.0");
+
+  program
+    .command("mcp")
+    .description("Start the MCP server on stdio (for Claude, Cursor, and other agents)")
+    .action(async () => {
+      const { startMcpServer } = await import("./mcp.mjs");
+      await startMcpServer().catch(fail);
+    });
+
+  program
+    .command("funnel")
+    .description("AI pipeline last 30 days: crawls, AI visits, AI leads")
+    .action(() => api.overviewFunnel().then(out).catch(fail));
+
+  program
+    .command("visibility")
+    .description("Daily AI visibility score trend from the stored weekly citation checks")
+    .option("--days <n>", "30, 60 or 90", "30")
+    .action((opts) => api.visibilityTrend(Number(opts.days)).then(out).catch(fail));
+
+  program
+    .command("citations")
+    .description("Recent AI citation checks")
+    .option("--model <model>", "Filter by AI model (chatgpt, perplexity, ...)")
+    .option("--limit <n>", "Max rows", "50")
+    .action((opts) =>
+      api
+        .citations({ model: opts.model, limit: Number(opts.limit) })
+        .then(out)
+        .catch(fail)
+    );
+
+  program
+    .command("capacity")
+    .description("Remaining plan slots on the content calendar")
+    .action(() => api.planningCapacity().then(out).catch(fail));
+
+  program
+    .command("jobs")
+    .description("Recent agent runs (async job status)")
+    .option("--limit <n>", "Max rows", "20")
+    .action((opts) => api.jobs(Number(opts.limit)).then(out).catch(fail));
+
+  program
+    .command("content")
+    .description("List content pages with status")
+    .action(() => api.content().then(out).catch(fail));
+
+  program
+    .command("plan-content")
+    .description("Generate candidate titles (nothing is scheduled until commit-titles)")
+    .option("--topics <a,b,c>", "Focus topics")
+    .option("--content-types <a,b>", "Content types")
+    .option("--max-difficulty <n>", "Keyword-difficulty ceiling 0-100")
+    .option("--intents <a,b>", "informational,commercial,transactional")
+    .option("--citation-gaps", "Target queries where AI cites competitors but not us")
+    .option("--ranking-gaps", "Target keywords ranking page 2-3 or slipping")
+    .action((opts) =>
+      api
+        .planContent({
+          topics: opts.topics ? list(opts.topics) : undefined,
+          contentTypes: opts.contentTypes ? list(opts.contentTypes) : undefined,
+          maxDifficulty: opts.maxDifficulty ? Number(opts.maxDifficulty) : undefined,
+          intents: opts.intents ? list(opts.intents) : undefined,
+          useCitationGaps: opts.citationGaps || undefined,
+          useRankingGaps: opts.rankingGaps || undefined,
+        })
+        .then(out)
+        .catch(fail)
+    );
+
+  program
+    .command("commit-titles")
+    .description("Approve reviewed titles onto the calendar. Reads {titles:[...],discarded?:[...]} JSON")
+    .option("--file <path>", "JSON file (defaults to stdin)")
+    .action(async (opts) => {
+      try {
+        const raw = opts.file
+          ? readFileSync(opts.file, "utf8")
+          : readFileSync(0, "utf8");
+        const body = JSON.parse(raw);
+        out(await api.commitPlannedTitles(body));
+      } catch (err) {
+        fail(err);
+      }
+    });
+
+  program
+    .command("publish <contentId>")
+    .description("Publish an article to the connected CMS (dry run unless --confirm)")
+    .option("--confirm", "Actually publish (default is a dry run)")
+    .action((contentId, opts) =>
+      api.publishContent(contentId, !!opts.confirm).then(out).catch(fail)
+    );
+
+  program.parseAsync(argv);
+}

package/src/client.mjs

@@ -0,0 +1,58 @@
+const DEFAULT_BASE = "https://api.rctrl.com";
+
+export function getConfig() {
+  const apiKey = process.env.RANKCONTROL_API_KEY;
+  if (!apiKey) {
+    throw new Error(
+      "RANKCONTROL_API_KEY is not set. Create a key in RankControl → Settings → API, then export RANKCONTROL_API_KEY=rctrl_pk_..."
+    );
+  }
+  return {
+    apiKey,
+    baseUrl: (process.env.RANKCONTROL_API_URL || DEFAULT_BASE).replace(/\/$/, ""),
+  };
+}
+
+async function request(method, path, body) {
+  const { apiKey, baseUrl } = getConfig();
+  const res = await fetch(`${baseUrl}${path}`, {
+    method,
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
+    },
+    body: body !== undefined ? JSON.stringify(body) : undefined,
+  });
+  let json;
+  try {
+    json = await res.json();
+  } catch {
+    throw new Error(`RankControl API returned a non-JSON response (HTTP ${res.status})`);
+  }
+  if (!res.ok) {
+    throw new Error(json?.error || `RankControl API error (HTTP ${res.status})`);
+  }
+  return json.data ?? json;
+}
+
+export const api = {
+  overviewFunnel: () => request("GET", "/api/v1/overview/funnel"),
+  visibilityTrend: (days = 30) =>
+    request("GET", `/api/v1/visibility/trend?days=${days}`),
+  citations: (params = {}) => {
+    const q = new URLSearchParams();
+    if (params.model) q.set("model", params.model);
+    if (params.limit) q.set("limit", String(params.limit));
+    const qs = q.toString();
+    return request("GET", `/api/v1/citations${qs ? `?${qs}` : ""}`);
+  },
+  visibilityScore: () => request("GET", "/api/v1/visibility/score"),
+  planningCapacity: () => request("GET", "/api/v1/content/planning-capacity"),
+  jobs: (limit = 20) => request("GET", `/api/v1/jobs?limit=${limit}`),
+  content: () => request("GET", "/api/v1/content"),
+  planContent: (opts) => request("POST", "/api/v1/content/plan", opts),
+  commitPlannedTitles: (opts) =>
+    request("POST", "/api/v1/content/plan/commit", opts),
+  publishContent: (contentId, confirm = false) =>
+    request("POST", "/api/v1/content/publish", { contentId, confirm }),
+};

package/src/mcp.mjs

@@ -0,0 +1,123 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { api } from "./client.mjs";
+
+const asText = (data) => ({
+  content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+});
+
+const asError = (err) => ({
+  content: [{ type: "text", text: `Error: ${err?.message ?? String(err)}` }],
+  isError: true,
+});
+
+const run = (fn) => async (args) => {
+  try {
+    return asText(await fn(args));
+  } catch (err) {
+    return asError(err);
+  }
+};
+
+const plannedTitle = z.object({
+  title: z.string(),
+  targetKeyword: z.string().optional(),
+  searchVolume: z.number().optional(),
+  keywordDifficulty: z.number().optional(),
+  searchIntent: z.string().optional(),
+});
+
+export async function startMcpServer() {
+  const server = new McpServer({ name: "rankcontrol", version: "0.1.0" });
+
+  server.tool(
+    "get_overview_funnel",
+    "AI pipeline overview for the last 30 days: AI crawler hits, visits referred by AI engines, and leads that came from AI search.",
+    {},
+    run(() => api.overviewFunnel())
+  );
+
+  server.tool(
+    "get_visibility_trend",
+    "Daily AI visibility score series (share of weekly citation checks where the brand was cited across the 6 tracked AI engines). Data comes from RankControl's stored weekly checks.",
+    { days: z.enum(["30", "60", "90"]).optional().describe("Window size in days, default 30") },
+    run(({ days }) => api.visibilityTrend(days ? Number(days) : 30))
+  );
+
+  server.tool(
+    "list_citations",
+    "Recent AI citation checks: which tracked queries were checked on which AI model and whether the brand was cited.",
+    {
+      model: z.string().optional().describe("Filter by AI model, e.g. chatgpt, perplexity"),
+      limit: z.number().max(200).optional(),
+    },
+    run((args) => api.citations(args))
+  );
+
+  server.tool(
+    "get_visibility_score",
+    "Current overall AI visibility score for the workspace.",
+    {},
+    run(() => api.visibilityScore())
+  );
+
+  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.",
+    {},
+    run(() => api.planningCapacity())
+  );
+
+  server.tool(
+    "list_jobs",
+    "Recent agent runs (job status feed). Async actions like content planning show up here with their outputs.",
+    { limit: z.number().max(100).optional() },
+    run(({ limit }) => api.jobs(limit ?? 20))
+  );
+
+  server.tool(
+    "list_content",
+    "List content pages in the workspace with their status (planned, draft, published).",
+    {},
+    run(() => api.content())
+  );
+
+  server.tool(
+    "plan_content",
+    "Generate candidate article titles (capacity-gated). This DOES NOT put anything on the calendar: review the returned titles, then call commit_planned_titles with the keepers. Costs an LLM call; capped at 5/min.",
+    {
+      topics: z.array(z.string()).optional().describe("Brand topics to focus on; omit for auto"),
+      contentTypes: z.array(z.string()).optional(),
+      maxDifficulty: z.number().min(0).max(100).optional().describe("Keyword-difficulty ceiling"),
+      intents: z.array(z.string()).optional().describe("informational / commercial / transactional"),
+      useCitationGaps: z.boolean().optional().describe("Target queries where AI cites competitors but not us"),
+      useRankingGaps: z.boolean().optional().describe("Target keywords ranking page 2-3 or slipping"),
+    },
+    run((args) => api.planContent(args))
+  );
+
+  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.",
+    {
+      titles: z.array(plannedTitle).describe("Titles to schedule"),
+      discarded: z.array(plannedTitle).optional().describe("Rejected candidates"),
+    },
+    run((args) => api.commitPlannedTitles(args))
+  );
+
+  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.",
+    {
+      contentId: z.string().describe("The content page id"),
+      confirm: z.boolean().optional().describe("Set true to actually publish (default: dry run)"),
+    },
+    run(({ contentId, confirm }) => api.publishContent(contentId, confirm === true))
+  );
+
+  await server.connect(new StdioServerTransport());
+  // Keep the process alive; the transport owns stdin/stdout from here
+  console.error("rankcontrol MCP server running on stdio");
+}