Skip to content

Open source alternative to Semrush and Ahrefs

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.json
index 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.json
index 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.json
index 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.tsx
index 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>
<QueryState
diff --git a/src/client/features/rank-tracking/RankTrackingDomainDetail.tsx b/src/client/features/rank-tracking/RankTrackingDomainDetail.tsx
index 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.tsx
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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}`;
+}