Open source alternative to Semrush and Ahrefs
TypeScript backlink-analysisgoogle-search-console-mcpkeyword-researchmcpseoseo-agentseo-auditseo-automationseo-skillsseo-toolssite-audit
Open the live Google SERP from rank tracking (EVE-70) (#806)
Carter Smith36975556588f
diff --git a/plugins/openseo/.claude-plugin/plugin.json b/plugins/openseo/.claude-plugin/plugin.jsonindex 2cfc2486..7d28c40e 100644--- a/plugins/openseo/.claude-plugin/plugin.json+++ b/plugins/openseo/.claude-plugin/plugin.json@@ -1,7 +1,7 @@{"name": "openseo","displayName": "OpenSEO",- "version": "1.0.10",+ "version": "1.0.11","description": "Research keywords and competitors, audit sites, track rankings, and use connected Search Console data from your AI assistant.","author": {"name": "OpenSEO",diff --git a/plugins/openseo/.codex-plugin/plugin.json b/plugins/openseo/.codex-plugin/plugin.jsonindex 7b34e330..180afce0 100644--- a/plugins/openseo/.codex-plugin/plugin.json+++ b/plugins/openseo/.codex-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "openseo",- "version": "1.0.10",+ "version": "1.0.11","description": "Research keywords and competitors, audit sites, track rankings, and use connected Search Console data from your AI assistant.","author": {"name": "OpenSEO",diff --git a/plugins/openseo/.cursor-plugin/plugin.json b/plugins/openseo/.cursor-plugin/plugin.jsonindex e99f76cb..4cd47daa 100644--- a/plugins/openseo/.cursor-plugin/plugin.json+++ b/plugins/openseo/.cursor-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "openseo",- "version": "1.0.10",+ "version": "1.0.11","description": "Research keywords and competitors, audit sites, track rankings, and use connected Search Console data from your AI assistant.","author": {"name": "Every App, Inc",diff --git a/src/client/features/rank-tracking/KeywordTrendModal.tsx b/src/client/features/rank-tracking/KeywordTrendModal.tsxindex 7bbb59e4..99e4ef06 100644--- a/src/client/features/rank-tracking/KeywordTrendModal.tsx+++ b/src/client/features/rank-tracking/KeywordTrendModal.tsx@@ -1,5 +1,5 @@import { useMemo, useState } from "react";-import { Copy, Download } from "lucide-react";+import { Copy, Download, ExternalLink } from "lucide-react";import { reverse, sortBy } from "remeda";import { toast } from "sonner";import { useQuery } from "@tanstack/react-query";@@ -29,6 +29,7 @@ import { getRankKeywordHistory } from "@/serverFunctions/rank-tracking";import type { RankKeywordHistoryPoint } from "@/serverFunctions/rank-tracking";import { LOCATIONS } from "@/client/features/keywords/locations";import { formatLocationLabel } from "@/shared/keyword-locations";+import { googleSerpUrl } from "@/shared/google-serp-url";import { csvChange, DeviceRankCell } from "./RankTrackingTableParts";import {RankTrendChart,@@ -56,6 +57,7 @@ export function KeywordTrendModal({configId,domain,locationCode,+ languageCode,locationName,serpDepth,onClose,@@ -65,6 +67,7 @@ export function KeywordTrendModal({configId: string;domain: string;locationCode: number;+ languageCode: string;locationName?: string;serpDepth: number;onClose: () => void;@@ -172,7 +175,29 @@ export function KeywordTrendModal({· Position over time</DialogDescription></div>- <TrendRangeToggle value={sinceDays} onChange={setSinceDays} />+ <div className="flex items-center gap-2">+ <Button+ variant="outline"+ size="sm"+ nativeButton={false}+ title="Search this keyword on Google with the tracked language, country, and city"+ render={+ <a+ href={googleSerpUrl(target.keyword, {+ locationCode,+ languageCode,+ locationName,+ })}+ target="_blank"+ rel="noopener noreferrer"+ />+ }+ >+ <ExternalLink data-icon="inline-start" />+ Open on Google+ </Button>+ <TrendRangeToggle value={sinceDays} onChange={setSinceDays} />+ </div></DialogHeader><QueryStatediff --git a/src/client/features/rank-tracking/RankTrackingDomainDetail.tsx b/src/client/features/rank-tracking/RankTrackingDomainDetail.tsxindex 416b3516..600a17ac 100644--- a/src/client/features/rank-tracking/RankTrackingDomainDetail.tsx+++ b/src/client/features/rank-tracking/RankTrackingDomainDetail.tsx@@ -388,6 +388,7 @@ export function RankTrackingDomainDetail({configId={config.id}projectId={projectId}locationCode={config.locationCode}+ languageCode={config.languageCode}locationName={config.locationName}serpDepth={config.serpDepth}onAddKeywords={() => setShowAddKeywords(true)}diff --git a/src/client/features/rank-tracking/RankTrackingTable.tsx b/src/client/features/rank-tracking/RankTrackingTable.tsxindex af5c7f68..531f74a9 100644--- a/src/client/features/rank-tracking/RankTrackingTable.tsx+++ b/src/client/features/rank-tracking/RankTrackingTable.tsx@@ -32,6 +32,7 @@ export function RankTrackingTable({configId,projectId,locationCode,+ languageCode,locationName,serpDepth,onAddKeywords,@@ -47,6 +48,7 @@ export function RankTrackingTable({configId: string;projectId: string;locationCode: number;+ languageCode: string;locationName?: string | null;serpDepth: number;onAddKeywords: () => void;@@ -180,6 +182,7 @@ export function RankTrackingTable({configId={configId}domain={domain}locationCode={locationCode}+ languageCode={languageCode}locationName={locationName ?? undefined}serpDepth={serpDepth}onClose={() => setTrendTarget(null)}diff --git a/src/server/mcp/tools/get-rank-tracker.ts b/src/server/mcp/tools/get-rank-tracker.tsindex 698ba5c3..0e2ec504 100644--- a/src/server/mcp/tools/get-rank-tracker.ts+++ b/src/server/mcp/tools/get-rank-tracker.ts@@ -13,6 +13,7 @@ import {type McpTableColumn,} from "@/server/mcp/table";import { projectIdSchema } from "@/server/mcp/schemas";+import { googleSerpUrl } from "@/shared/google-serp-url";const RANK_RESULT_COLUMNS: McpTableColumn<unknown>[] = [{ header: "keyword", value: (row) => readPath(row, "keyword") },@@ -26,6 +27,7 @@ const RANK_RESULT_COLUMNS: McpTableColumn<unknown>[] = [header: "prev (mobile)",value: (row) => readPath(row, "mobile", "previousPosition"),},+ { header: "google serp", value: (row) => readPath(row, "googleSerpUrl") },];/**@@ -67,7 +69,7 @@ export const getRankTrackerTool = {config: {title: "Get rank tracker",description:- "Read-only access to rank tracker configs and their latest results. With `trackerId`, returns config + latest snapshot per keyword, including `trackingKeywordId` for removals. Without it, lists all trackers in the project. Uses no credits. Use create_rank_tracker when no tracker exists; then use add_rank_tracking_keywords, remove_rank_tracking_keywords, estimate_rank_tracker_cost, or run_rank_tracker to manage it. `lastCheckedAt` shows position freshness.",+ "Read-only access to rank tracker configs and their latest results. With `trackerId`, returns config + latest snapshot per keyword, including `trackingKeywordId` for removals and `googleSerpUrl`, a live Google search for the tracked keyword, language, country, and city. Without it, lists all trackers in the project. Uses no credits. Use create_rank_tracker when no tracker exists; then use add_rank_tracking_keywords, remove_rank_tracking_keywords, estimate_rank_tracker_cost, or run_rank_tracker to manage it. `lastCheckedAt` shows position freshness.",inputSchema,outputSchema: z.object({@@ -128,6 +130,10 @@ export const getRankTrackerTool = {args.trackerId,args.projectId,);+ const rows = results.rows.map((row) => ({+ ...row,+ googleSerpUrl: googleSerpUrl(row.keyword, config),+ }));const text = [`Tracker ${config.id} (${config.domain}${config.locationName ? `, ${config.locationName}` : ""}):`,`Schedule: ${config.scheduleInterval}, devices: ${config.devices}, depth: ${config.serpDepth}`,@@ -135,7 +141,7 @@ export const getRankTrackerTool = {`Keywords (${results.rows.length}):`,results.rows.length === 0? "No keywords tracked yet."- : formatMcpTable(results.rows, RANK_RESULT_COLUMNS),+ : formatMcpTable(rows, RANK_RESULT_COLUMNS),].join("\n");return mcpResponse({text,@@ -144,7 +150,7 @@ export const getRankTrackerTool = {args.projectId,`/p/${args.projectId}/rank-tracking/${args.trackerId}`,),- structuredContent: { config, results },+ structuredContent: { config, results: { ...results, rows } },});}),};diff --git a/src/server/mcp/tools/rank-tracking-management-tools.test.ts b/src/server/mcp/tools/rank-tracking-management-tools.test.tsindex ca28c019..08a98564 100644--- a/src/server/mcp/tools/rank-tracking-management-tools.test.ts+++ b/src/server/mcp/tools/rank-tracking-management-tools.test.ts@@ -2,6 +2,7 @@ import { beforeEach, describe, expect, it, vi } from "vitest";import { z } from "zod";import { addRankTrackingKeywordsTool } from "./add-rank-tracking-keywords";import { createRankTrackerTool } from "./create-rank-tracker";+import { getRankTrackerTool } from "./get-rank-tracker";import { runRankTrackerTool } from "./run-rank-tracker";import { makeToolContext, textContent } from "./tool-test-support";@@ -95,6 +96,30 @@ describe("rank tracking management MCP tools", () => {});});+ it("returns the live Google SERP link in both the text and the structured rows", async () => {+ mocks.getTracker.mockResolvedValue({+ config: {+ ...createdConfig,+ serpDepth: 40,+ locationCode: 2276,+ languageCode: "de",+ locationName: null,+ },+ results: { rows: [{ keyword: "seo tool" }], run: null },+ });++ const result = await getRankTrackerTool.handler(+ { projectId, trackerId },+ toolContext,+ );++ const url = "https://www.google.com/search?q=seo+tool&hl=de&gl=de&pws=0";+ expect(textContent(result)).toContain(url);+ expect(result.structuredContent).toMatchObject({+ results: { rows: [{ googleSerpUrl: url }] },+ });+ });+it("requires maxCostCredits to run a rank tracker", () => {expect(z.object(runRankTrackerTool.config.inputSchema).safeParse({diff --git a/src/shared/google-serp-url.test.ts b/src/shared/google-serp-url.test.tsnew file mode 100644index 00000000..5e177b01--- /dev/null+++ b/src/shared/google-serp-url.test.ts@@ -0,0 +1,22 @@+import { describe, expect, it } from "vitest";+import { googleSerpUrl } from "./google-serp-url";++describe("googleSerpUrl", () => {+ it("targets the tracked city with uule", () => {+ expect(+ googleSerpUrl("best seo tool", {+ locationCode: 2840,+ languageCode: "en",+ locationName: "Austin,Texas,United States",+ }),+ ).toBe(+ "https://www.google.com/search?q=best+seo+tool&hl=en&gl=us&pws=0&uule=w+CAIQICIaQXVzdGluLFRleGFzLFVuaXRlZCBTdGF0ZXM%3D",+ );+ });++ it("uses only the country for a national tracker", () => {+ expect(+ googleSerpUrl("café", { locationCode: 2826, languageCode: "en" }),+ ).toBe("https://www.google.com/search?q=caf%C3%A9&hl=en&gl=gb&pws=0");+ });+});diff --git a/src/shared/google-serp-url.ts b/src/shared/google-serp-url.tsnew file mode 100644index 00000000..3f612143--- /dev/null+++ b/src/shared/google-serp-url.ts@@ -0,0 +1,40 @@+import { getIsoCountryCode } from "@/shared/keyword-locations";++type SerpMarket = {+ locationCode: number;+ languageCode: string;+ locationName?: string | null;+};++/**+ * Google's `uule` location parameter: a base64 protobuf that carries the+ * canonical location name ("Austin,Texas,United States"). DataForSEO's+ * location_name uses the same canonical names.+ */+function encodeUule(canonicalName: string): string {+ const name = new TextEncoder().encode(canonicalName);+ // Protobuf varint length; two bytes cover any real location name.+ const n = name.length;+ const length = n < 0x80 ? [n] : [(n & 0x7f) | 0x80, n >> 7];+ const bytes = [0x08, 0x02, 0x10, 0x20, 0x22, ...length, ...name];+ return btoa(String.fromCharCode(...bytes));+}++/**+ * A google.com search URL for the SERP a rank check fetches: same keyword,+ * interface language, country, and city. `pws=0` turns off personalised+ * results. Google can still vary results by device, account, and time.+ */+export function googleSerpUrl(keyword: string, market: SerpMarket): string {+ const params = new URLSearchParams({+ q: keyword,+ hl: market.languageCode,+ gl: getIsoCountryCode(market.locationCode),+ pws: "0",+ });+ // URLSearchParams would escape the "w+" prefix that Google expects as is.+ const uule = market.locationName+ ? `&uule=w+${encodeURIComponent(encodeUule(market.locationName))}`+ : "";+ return `https://www.google.com/search?${params.toString()}${uule}`;+}