@refreshagent/mcp 0.1.0

package/README.md

@@ -0,0 +1,29 @@
+# Refresh Agent MCP
+
+Connect Claude Code to Refresh Agent without exposing Google setup details.
+
+```bash
+claude mcp add refreshagent npx -y @refreshagent/mcp --key=ra_live_...
+```
+
+The bridge reads `--key`, `REFRESHAGENT_API_KEY`, or `~/.config/refreshagent/.env`, and proxies Claude tool calls to the Refresh Agent API.
+
+The `live-search-console-data` skill can create that local config file automatically through the browser login flow.
+
+For clients that accept an MCP JSON configuration:
+
+```json
+{
+  "mcpServers": {
+    "refreshagent": {
+      "command": "npx",
+      "args": ["-y", "@refreshagent/mcp"],
+      "env": { "REFRESHAGENT_API_KEY": "YOUR_REFRESHAGENT_API_KEY" }
+    }
+  }
+}
+```
+
+Requires Node.js 18 or newer and a RefreshAgent account with Google data connected.
+Tools: `list_connected_sites`, `check_website_traffic`, `get_keyword_rankings`.
+Pricing and data-access limits: https://refreshagent.com/plans.

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@refreshagent/mcp",
+  "version": "0.1.0",
+  "description": "Refresh Agent MCP bridge for Claude Code",
+  "type": "commonjs",
+  "bin": {
+    "refreshagent-mcp": "src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dunctk/seo-ai-agent-web.git",
+    "directory": "mcp-package"
+  },
+  "mcpName": "io.github.dunctk/refreshagent",
+  "scripts": {
+    "test": "node --test test/*.test.cjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.js

@@ -0,0 +1,299 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const args = parseArgs(process.argv.slice(2));
+const config = readRefreshAgentConfig();
+const apiKey = args.key || process.env.REFRESHAGENT_API_KEY || config.REFRESHAGENT_API_KEY || "";
+const baseUrl = (args["base-url"] || process.env.REFRESHAGENT_BASE_URL || config.REFRESHAGENT_BASE_URL || "https://refreshagent.com").replace(/\/+$/, "");
+
+let inputBuffer = Buffer.alloc(0);
+
+process.stdin.resume();
+process.stdin.on("data", (chunk) => {
+  inputBuffer = Buffer.concat([inputBuffer, chunk]);
+  drainMessages();
+});
+
+function parseArgs(argv) {
+  const parsed = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (!arg.startsWith("--")) continue;
+    const trimmed = arg.slice(2);
+    const eq = trimmed.indexOf("=");
+    if (eq >= 0) {
+      parsed[trimmed.slice(0, eq)] = trimmed.slice(eq + 1);
+    } else {
+      parsed[trimmed] = argv[i + 1] && !argv[i + 1].startsWith("--") ? argv[++i] : "true";
+    }
+  }
+  return parsed;
+}
+
+function readRefreshAgentConfig() {
+  const file = path.join(os.homedir(), ".config", "refreshagent", ".env");
+  const parsed = {};
+  let text = "";
+  try {
+    text = fs.readFileSync(file, "utf8");
+  } catch (_) {
+    return parsed;
+  }
+
+  for (const line of text.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#") || !trimmed.includes("=")) continue;
+    const [rawKey, ...rawValue] = trimmed.split("=");
+    const key = rawKey.trim();
+    const value = rawValue.join("=").trim().replace(/^['"]|['"]$/g, "");
+    if (key) parsed[key] = value;
+  }
+
+  return parsed;
+}
+
+function drainMessages() {
+  while (true) {
+    const lineEnd = inputBuffer.indexOf("\n");
+    if (lineEnd < 0) return;
+    const body = inputBuffer.slice(0, lineEnd).toString("utf8").trim();
+    inputBuffer = inputBuffer.slice(lineEnd + 1);
+    if (!body) continue;
+
+    let message;
+    try {
+      message = JSON.parse(body);
+    } catch (error) {
+      writeResponse(null, null, rpcError(-32700, `Invalid JSON: ${error.message}`));
+      continue;
+    }
+
+    handleMessage(message).catch((error) => {
+      writeResponse(message.id, null, rpcError(-32603, error.message || String(error)));
+    });
+  }
+}
+
+async function handleMessage(message) {
+  if (!message || !message.method) return;
+
+  if (message.method.startsWith("notifications/")) return;
+
+  switch (message.method) {
+    case "initialize":
+      writeResponse(message.id, {
+        protocolVersion: message.params?.protocolVersion || "2024-11-05",
+        capabilities: { tools: {} },
+        serverInfo: { name: "Refresh Agent", version: require("../package.json").version }
+      });
+      return;
+    case "ping":
+      writeResponse(message.id, {});
+      return;
+    case "tools/list":
+      writeResponse(message.id, { tools: toolDefinitions() });
+      return;
+    case "tools/call": {
+      const name = message.params?.name;
+      const toolArgs = message.params?.arguments || {};
+      const result = await callTool(name, toolArgs);
+      writeResponse(message.id, result);
+      return;
+    }
+    default:
+      writeResponse(message.id, null, rpcError(-32601, `Unknown method: ${message.method}`));
+  }
+}
+
+function writeResponse(id, result, error = null) {
+  const payload = JSON.stringify({
+    jsonrpc: "2.0",
+    id,
+    ...(error ? { error } : { result })
+  });
+  process.stdout.write(`${payload}\n`);
+}
+
+function rpcError(code, message) {
+  return { code, message };
+}
+
+function toolDefinitions() {
+  return [
+    {
+      name: "list_connected_sites",
+      description: "List the websites Refresh Agent can access for this account.",
+      inputSchema: {
+        type: "object",
+        properties: {},
+        additionalProperties: false
+      }
+    },
+    {
+      name: "check_website_traffic",
+      description: "Check recent website traffic and top pages from connected Google Analytics and Search Console data.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          date_range: {
+            type: "string",
+            enum: ["7d", "30d", "90d"],
+            description: "Time window to check. Defaults to 7d."
+          },
+          site_url: {
+            type: "string",
+            description: "Optional Search Console site URL. If omitted, Refresh Agent uses the first connected site."
+          },
+          property_id: {
+            type: "string",
+            description: "Optional GA4 property ID. If omitted, Refresh Agent uses the first connected GA4 property."
+          }
+        },
+        additionalProperties: false
+      }
+    },
+    {
+      name: "get_keyword_rankings",
+      description: "Get top Search Console queries with clicks, impressions, CTR, and average position.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          date_range: {
+            type: "string",
+            enum: ["7d", "30d", "90d"],
+            description: "Time window to check. Defaults to 30d."
+          },
+          site_url: {
+            type: "string",
+            description: "Optional Search Console site URL."
+          }
+        },
+        additionalProperties: false
+      }
+    }
+  ];
+}
+
+async function callTool(name, toolArgs) {
+  if (!apiKey) {
+    return toolError("Refresh Agent secure key missing. In Claude Code, run the live-search-console-data skill once; it will open Google login and save the key locally.");
+  }
+
+  switch (name) {
+    case "list_connected_sites":
+      return toolText(await refreshJson("/api/v1/clients"));
+    case "check_website_traffic":
+      return checkWebsiteTraffic(toolArgs);
+    case "get_keyword_rankings":
+      return getKeywordRankings(toolArgs);
+    default:
+      return toolError(`Unknown Refresh Agent tool: ${name}`);
+  }
+}
+
+async function checkWebsiteTraffic(toolArgs) {
+  const dateRange = toolArgs.date_range || "7d";
+  const defaults = await connectedDefaults();
+  const siteUrl = toolArgs.site_url || defaults.site_url;
+  const propertyId = toolArgs.property_id || defaults.property_id;
+
+  const output = {
+    date_range: dateRange,
+    site_url: siteUrl || null,
+    property_id: propertyId || null,
+    traffic_summary: null,
+    top_pages: null,
+    notes: []
+  };
+
+  if (propertyId) {
+    output.traffic_summary = await refreshJson("/api/v1/ga4/summary", { property_id: propertyId, date_range: dateRange });
+  } else {
+    output.notes.push("No connected GA4 property was found.");
+  }
+
+  if (siteUrl) {
+    output.top_pages = await refreshJson("/api/v1/sc/pages", { site_url: siteUrl, date_range: dateRange });
+  } else {
+    output.notes.push("No connected Search Console site was found.");
+  }
+
+  return toolText(output);
+}
+
+async function getKeywordRankings(toolArgs) {
+  const dateRange = toolArgs.date_range || "30d";
+  const defaults = await connectedDefaults();
+  const siteUrl = toolArgs.site_url || defaults.site_url;
+  if (!siteUrl) return toolError("No connected Search Console site was found.");
+
+  const rankings = await refreshJson("/api/v1/sc/query", { site_url: siteUrl, date_range: dateRange });
+  return toolText({ date_range: dateRange, site_url: siteUrl, rankings });
+}
+
+async function connectedDefaults() {
+  const clients = await refreshJson("/api/v1/clients");
+  const list = Array.isArray(clients) ? clients : clients.clients || clients.sites || [];
+  const firstGsc = list.find((site) => site.gsc_site_url || site.site_url);
+  const firstGa4 = list.find((site) => site.ga4_property_id || site.property_id);
+  return {
+    site_url: firstGsc?.gsc_site_url || firstGsc?.site_url || null,
+    property_id: firstGa4?.ga4_property_id || firstGa4?.property_id || null
+  };
+}
+
+async function refreshJson(path, params = {}) {
+  const url = new URL(`${baseUrl}${path}`);
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== undefined && value !== null && value !== "") {
+      url.searchParams.set(key, String(value));
+    }
+  }
+
+  const response = await fetch(url, {
+    headers: {
+      "Accept": "application/json",
+      "X-API-Key": apiKey
+    }
+  });
+
+  const text = await response.text();
+  let payload;
+  try {
+    payload = text ? JSON.parse(text) : {};
+  } catch (_) {
+    payload = { raw: text };
+  }
+
+  if (!response.ok) {
+    throw new Error(payload.error || payload.message || `Refresh Agent request failed with ${response.status}`);
+  }
+
+  return payload;
+}
+
+function toolText(data) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(data, null, 2)
+      }
+    ]
+  };
+}
+
+function toolError(message) {
+  return {
+    isError: true,
+    content: [
+      {
+        type: "text",
+        text: message
+      }
+    ]
+  };
+}