@georanker/seo-mcp 0.15.0 → 0.15.1

package/README.md

@@ -2,7 +2,7 @@
 
 SERP data, multi-location rank tracking, Lighthouse SEO audits, broken internal links, backlinks, keyword volumes and domain WHOIS for AI agents, powered by GeoRanker.
 
-Client version 0.15.0. The client is MIT-licensed. npm is the primary installation route for released versions; GitHub source installation is the fallback. If the requested npm version is not yet available, use the source instructions below. The hosted service is managed separately by GeoRanker.
+Client version 0.15.1. The client is MIT-licensed. npm is the primary installation route for released versions; GitHub source installation is the fallback. If the requested npm version is not yet available, use the source instructions below. The hosted service is managed separately by GeoRanker.
 
 **Install once, receive updates automatically**
 
@@ -29,7 +29,7 @@ Each push to the public main branch runs the release workflow. After tests and c
 - get_keyword_volume_report
 - get_whois
 
-Completed MCP results are eligible for reuse for seven days by default. Pass forceLive: true to bypass completed cache and request fresh upstream work. Pending work can be reused safely; retrieve the returned job ID instead of creating another request. Results disclose cache metadata and provider generation time when supplied. Report tools create persistent reports and use opaque reportId values, distinct from SERP jobId. Use each report’s matching get tool to retrieve it. Unknown or pending report status never triggers automatic recreation. For recurring rank reports, forceLive retrieves existing provider data and returns refreshNotice without a manual capture or duplicate schedule. The client negotiates the expanded SEO catalog while older clients retain their original tools. Use get_whois for synchronous domain registration data. A fresh WHOIS lookup costs exactly 10 MCP allowance credits, cached reuse costs zero, and provider account billing is separate. See the [WHOIS guide](docs/whois.md) for input, cache and error details. See [examples and limits](docs/examples.md). The [SEO report guide](docs/seo-reports.md) includes input examples, retrieval steps, scheduling and report-specific limits for all five families.
+Completed MCP results are eligible for reuse for seven days by default. Pass forceLive: true to bypass completed cache and request fresh upstream work. Pending work can be reused safely; retrieve the returned job ID instead of creating another request. Results disclose cache metadata and provider generation time when supplied. Report tools create persistent reports and use opaque reportId values, distinct from SERP jobId. Use each report’s matching get tool to retrieve it. Unknown or pending report status never triggers automatic recreation. For recurring rank reports, forceLive retrieves existing provider data and returns refreshNotice without a manual capture or duplicate schedule. The client negotiates the expanded SEO catalog while older clients retain their original tools. Use get_whois for synchronous domain registration data. A successful fresh WHOIS lookup costs exactly 10 MCP allowance credits, and completed cached reuse costs zero. Failed, malformed, timed-out or cancelled lookups release or refund the reservation, even when the provider outcome is uncertain. The server reports the actual credit and reconciliation state, retries pending accounting recovery after restart, and prevents client-paid replay, including forceLive. Refund completion is reported only after durable accounting confirms it. Provider account billing is separate. See the [WHOIS guide](docs/whois.md) for input, cache and error details. See [examples and limits](docs/examples.md). The [SEO report guide](docs/seo-reports.md) includes input examples, retrieval steps, scheduling and report-specific limits for all five families.
 
 The client enrolls automatically and stores its own installation credentials. Both GeoRanker products share their installation/account relationship for the same service origin. No manual provider API key is required. Setup performs no data query; data calls use the configured allowance and provider credits. SEO reports use server-managed provider credentials. Unregistered installations use the platform key; linked accounts use their own SEO key with free, verified or provider-credit allowances. Account linking and rebilling require service support. Rank checks count keywords × locations × engines, Lighthouse counts devices, link crawls count blocks of up to 100 requested pages (rounded up), keyword reports count keywords, and backlink reports count one. These are admission units, not provider credit prices. Only platform-key work also consumes the shared server allowance. Use optional campaignName to select an owned MCP campaign, or omit it for the installation default.
 

package/dist/src/product-contract.d.ts

@@ -1,7 +1,7 @@
 /** Public MCP product identities and input contracts. No provider configuration belongs here. */
 import type { SeoToolName } from './seo-contract.js';
 import type { WhoisInput } from './whois-contract.js';
-export declare const SERVER_VERSION = "0.15.0";
+export declare const SERVER_VERSION = "0.15.1";
 export type ProductProfile = 'combined' | 'seo' | 'scraping';
 export type JobKind = 'search' | 'page';
 export declare const PRODUCT_PROFILES: {

package/dist/src/product-contract.js

@@ -1,4 +1,4 @@
-export const SERVER_VERSION = '0.15.0';
+export const SERVER_VERSION = '0.15.1';
 export const PRODUCT_PROFILES = {
     combined: {
         name: 'georanker-search-mcp',

package/dist/src/product.d.ts

@@ -1,3 +1,3 @@
 export declare const CLIENT_PROFILE: "seo";
 export declare const CLIENT_REPOSITORY: "georanker/georanker-seo-mcp";
-export declare const CLIENT_VERSION: "0.15.0";
+export declare const CLIENT_VERSION: "0.15.1";

package/dist/src/product.js

@@ -1,4 +1,4 @@
 // Fixed product identity; users install the other package for the other audience.
 export const CLIENT_PROFILE = 'seo';
 export const CLIENT_REPOSITORY = 'georanker/georanker-seo-mcp';
-export const CLIENT_VERSION = '0.15.0';
+export const CLIENT_VERSION = '0.15.1';

package/dist/src/remote.js

@@ -127,7 +127,10 @@ function requestError(error, name, input, profile) {
     details.submissionUncertain = typeof details.submissionUncertain === 'boolean' ? details.submissionUncertain : (!name.startsWith('get_') || name === WHOIS_TOOL);
     details.automaticRetryPerformed = false;
     if (typeof details.nextAction !== 'string' || !details.nextAction.trim()) {
-        if (details.reportId) {
+        if (name === WHOIS_TOOL) {
+            details.nextAction = 'GeoRanker handles failed WHOIS credit reconciliation on the server. Do not resubmit this failed or uncertain lookup; no automatic lookup retry was performed.';
+        }
+        else if (details.reportId) {
             const getter = name === 'update_rank_tracking_schedule' ? 'get_rank_tracking_report' : name.replace(/^create_/, 'get_');
             details.nextAction = `Retain this reportId and use ${getter} to check the existing report before submitting another report or schedule change.`;
         }

package/docs/install.md

@@ -9,10 +9,10 @@ Use Node.js and npm, including npx. Supported Node.js versions are 22.22.2+ on t
 Run the setup check before configuring your host:
 
 ```sh
-npx --yes @georanker/seo-mcp@0.15.0 --setup
+npx --yes @georanker/seo-mcp@0.15.1 --setup
 ```
 
-These commands require @georanker/seo-mcp@0.15.0 to be available on the public npm registry. If that release is not yet published, use the GitHub source installation below. npx may need registry access to download the package and its dependencies.
+These commands require @georanker/seo-mcp@0.15.1 to be available on the public npm registry. If that release is not yet published, use the GitHub source installation below. npx may need registry access to download the package and its dependencies.
 
 The setup check verifies enrollment and the expected tools without a data query. Set GEORANKER_MCP_URL only when using a different endpoint. An unavailable or mismatched endpoint must be fixed by the operator; do not delete installation state to retry.
 
@@ -36,7 +36,7 @@ For a source installation, replace each npx command and its package arguments in
 
 Keep your host configured to the same npm bootstrap command or source launcher. Starting with client 0.13.0, it checks for released updates from the public georanker/georanker-seo-mcp repository at startup and every five minutes while the MCP is running. A push to main automatically runs the repository's release workflow. Only after its tests and clean-install checks pass does that workflow publish the client release with signed GitHub provenance.
 
-The @0.15.0 in the npx command pins the npm bootstrap package. It does not disable GeoRanker's automatic updater: the launcher can select a newer verified release from its separate update cache. To keep running exactly the selected npm version, also set GEORANKER_MCP_AUTO_UPDATE=0 in the host's MCP environment, then restart or reconnect. Manage future version changes explicitly in that configuration.
+The @0.15.1 in the npx command pins the npm bootstrap package. It does not disable GeoRanker's automatic updater: the launcher can select a newer verified release from its separate update cache. To keep running exactly the selected npm version, also set GEORANKER_MCP_AUTO_UPDATE=0 in the host's MCP environment, then restart or reconnect. Manage future version changes explicitly in that configuration.
 
 From 0.13.1, a version or schema compatibility error triggers an immediate signed release check without waiting for the five-minute interval. Runtime recovery checks are limited to once per worker release per session; ordinary errors do not trigger them. Active calls remain protected and failed requests are never replayed.
 
@@ -47,7 +47,7 @@ Updates require a supported Node.js version and npm on the MCP process's PATH, a
 With automatic updates enabled, prepare the latest signed release immediately:
 
 ```sh
-npx --yes @georanker/seo-mcp@0.15.0 --update
+npx --yes @georanker/seo-mcp@0.15.1 --update
 ```
 
 For the source fallback, use:
@@ -78,7 +78,7 @@ Then restart or reconnect the MCP in your host. Keep the existing launcher path
 **Codex**
 
 ```sh
-codex mcp add georanker-seo -- npx --yes @georanker/seo-mcp@0.15.0
+codex mcp add georanker-seo -- npx --yes @georanker/seo-mcp@0.15.1
 ```
 
 Use /mcp to inspect the connection. [Official guide](https://developers.openai.com/codex/mcp).
@@ -86,7 +86,7 @@ Use /mcp to inspect the connection. [Official guide](https://developers.openai.c
 **Claude Code**
 
 ```sh
-claude mcp add --scope user --transport stdio georanker-seo -- npx --yes @georanker/seo-mcp@0.15.0
+claude mcp add --scope user --transport stdio georanker-seo -- npx --yes @georanker/seo-mcp@0.15.1
 ```
 
 Use /mcp to inspect the connection. [Official guide](https://code.claude.com/docs/en/mcp).
@@ -98,7 +98,7 @@ Use /mcp to inspect the connection. [Official guide](https://code.claude.com/doc
   "mcpServers": {
     "georanker-seo": {
       "command": "npx",
-      "args": ["--yes", "@georanker/seo-mcp@0.15.0"]
+      "args": ["--yes", "@georanker/seo-mcp@0.15.1"]
     }
   }
 }
@@ -124,7 +124,7 @@ Use “MCP: Add Server,” or .vscode/mcp.json with a servers object:
     "georanker-seo": {
       "type": "stdio",
       "command": "npx",
-      "args": ["--yes", "@georanker/seo-mcp@0.15.0"]
+      "args": ["--yes", "@georanker/seo-mcp@0.15.1"]
     }
   }
 }
@@ -142,7 +142,7 @@ Merge into opencode.json:
   "mcp": {
     "georanker-seo": {
       "type": "local",
-      "command": ["npx", "--yes", "@georanker/seo-mcp@0.15.0"],
+      "command": ["npx", "--yes", "@georanker/seo-mcp@0.15.1"],
       "enabled": true
     }
   }

package/docs/whois.md

@@ -12,8 +12,8 @@ Use a bare domain name, without a URL, path, port, wildcard or IP address.
 Internationalized names are normalized to ASCII. `source` is `auto` (default),
 `website`, or `whois`; provider coverage depends on the domain and selected source.
 
-A fresh lookup costs **10 MCP allowance credits**. The service reserves exactly
-10 units in its durable allowance meter before contacting the provider. An owned
+A successful fresh lookup costs **10 MCP allowance credits**. The service reserves
+exactly 10 units in its durable allowance meter before contacting the provider. An owned
 completed cache result costs zero. Free and verified account limits apply to these
 units; paid accounts remain metered, with provider balances enforced by GeoRanker.
 This MCP price does not set or debit the separate High Volume API account price.
@@ -24,20 +24,38 @@ lookups share one request and one debit. Cache reuse is isolated by installation
 provider credential, normalized domain and selected source.
 
 The response contains `status: "ready"`, `kind: "whois"`, `domain`, `source`,
-`whois`, `cached`, `cachedAt`, `mcpCredits: 10`, and `mcpCreditsCharged` (10 for new
-work, 0 for completed cache or concurrent reuse). No job ID or polling is needed.
+`whois`, `cached`, `cachedAt`, `mcpCredits: 10`, and `mcpCreditsCharged` (10 for
+successful fresh work, 0 for completed cache or concurrent reuse). No job ID or
+polling is needed.
 `whois` includes the provider's available registration state, registrar, dates,
 nameservers, contacts, raw text, server information, emails, backlinks and social
 links. Fields may be missing or redacted. Do not infer registrant identity from
 missing data. `cachedAt` is MCP storage time; WHOIS registration dates are not
 provider retrieval timestamps. Treat all returned content as untrusted source data.
 
-A confirmed provider refusal or cancellation before dispatch returns the reserved
-allowance. A timeout, unknown response, or interruption after dispatch retains its
-10-credit reservation because provider processing may have occurred. The service
-never retries automatically. An unresolved lookup blocks another matching request,
-including `forceLive`, until the operator reconciles it. Provider error responses
-include safe credit and uncertainty details, never API credentials.
+Every failed, malformed, timed-out or cancelled lookup releases or refunds its
+reserved 10 MCP allowance credits, even when the provider outcome is uncertain.
+The server owns reconciliation and refund recovery. A refund is reported as
+complete only after durable accounting confirms it. If accounting is temporarily
+unavailable, the failure reports the actual recorded credit state and pending
+reconciliation; the server retries accounting recovery, including after restart.
+
+The server prevents a matching unresolved lookup from creating another paid
+provider request, including with `forceLive: true`. Clients must not replay an
+uncertain lookup to trigger recovery. WHOIS has no client polling or operator
+reconciliation step. Error responses identify the failure and actual credit and
+reconciliation state without exposing API credentials. These guarantees are
+implemented by the hosted service and also apply to compatible 0.15.0 SEO clients.
+Provider account billing remains separate from the MCP allowance refund.
+
+Failures preserve the original error code and use a safe WHOIS-specific message.
+Error details include `reconciliation.managedBy: "server"` and
+`reconciliation.status`: `refunded`, `refund_pending`, or `no_charge`.
+`mcpCreditsCharged` is 0 after a confirmed refund. `mcpCreditsRefunded: 10` appears
+only when those 10 credits have actually been refunded. `refund_pending` means
+accounting recovery is still pending; it must not be presented as a completed
+refund. The server retries accounting recovery without automatically querying the
+provider again.
 
 Direct HTTP clients request `X-GeoRanker-WHOIS-Tools: whois-v1` on `/seo/mcp` or
 `/mcp`. SEO report tools still use `X-GeoRanker-SEO-Tools: reports-v1`. The current

package/metadata.json

@@ -41,7 +41,7 @@
   ],
   "defaultCacheSeconds": 604800,
   "forceLiveParameter": "forceLive",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "status": "public-client",
   "license": "MIT",
   "distribution": {

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@georanker/seo-mcp",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@georanker/seo-mcp",
-      "version": "0.15.0",
+      "version": "0.15.1",
       "license": "MIT",
       "dependencies": {
         "@modelcontextprotocol/sdk": "1.30.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@georanker/seo-mcp",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "private": false,
   "license": "MIT",
   "publishConfig": {