@georanker/seo-mcp 0.14.0

package/dist/src/updater.js

@@ -0,0 +1,390 @@
+// Only signed release artifacts from the fixed public main workflow may be installed.
+import { execFile } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { access, mkdir, mkdtemp, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { homedir, devNull } from 'node:os';
+import { delimiter, dirname, join, resolve } from 'node:path';
+import { promisify } from 'node:util';
+const exec = promisify(execFile);
+const SHA = /^[a-f0-9]{40}$/;
+const DIGEST = /^[a-f0-9]{64}$/;
+const WORKFLOW = '.github/workflows/client-release.yml';
+const ARTIFACT = 'client-update.tgz';
+export const UPDATE_CHECK_INTERVAL_MS = 5 * 60 * 1000;
+const REPOSITORIES = new Map([
+    ['georanker/georanker-seo-mcp', '@georanker/seo-mcp'],
+    ['georanker/georanker-web-scraping-mcp', '@georanker/web-scraping-mcp'],
+]);
+export function updateDirectory(options) {
+    if (!REPOSITORIES.has(options.repository))
+        throw new Error('Unsupported update repository');
+    return join(options.env.GEORANKER_MCP_UPDATE_DIR || join(homedir(), '.config', 'georanker-mcp-updates'), options.repository.split('/')[1]);
+}
+function enabled(options) { return options.env.GEORANKER_MCP_AUTO_UPDATE !== '0'; }
+function older(candidate, bundled) {
+    if (!/^\d+\.\d+\.\d+$/.test(candidate) || !/^\d+\.\d+\.\d+$/.test(bundled))
+        throw new Error('Unsupported client version');
+    const a = candidate.split('.').map(Number), b = bundled.split('.').map(Number);
+    for (let i = 0; i < 3; i++) {
+        if (a[i] !== b[i])
+            return a[i] < b[i];
+    }
+    return false;
+}
+async function readPointer(directory) {
+    try {
+        const value = JSON.parse(await readFile(join(directory, 'current.json'), 'utf8'));
+        return SHA.test(value.current) && (!value.previous || SHA.test(value.previous)) ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function ready(options, commit) {
+    if (!SHA.test(commit))
+        return undefined;
+    try {
+        const root = join(updateDirectory(options), 'releases', commit);
+        const value = JSON.parse(await readFile(join(root, '.ready.json'), 'utf8'));
+        if (value.repository !== options.repository || value.commit !== commit || older(value.version, options.version))
+            return undefined;
+        await access(join(root, 'dist/src/runtime.js'));
+        await access(join(root, 'dist/src/cli.js'));
+        return value;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function selectRelease(options) {
+    if (enabled(options)) {
+        const pointer = await readPointer(updateDirectory(options));
+        for (const commit of [pointer?.current, pointer?.previous]) {
+            if (commit && await ready(options, commit))
+                return { root: join(updateDirectory(options), 'releases', commit), commit };
+        }
+    }
+    return { root: options.bundledRoot };
+}
+async function writePointer(directory, pointer) {
+    const temp = join(directory, 'pointer-' + randomUUID() + '.tmp');
+    await writeFile(temp, JSON.stringify(pointer) + '\n', { mode: 0o600 });
+    await rename(temp, join(directory, 'current.json'));
+}
+export async function rollbackRelease(options, commit) {
+    try {
+        const directory = updateDirectory(options), pointer = await readPointer(directory);
+        if (pointer?.current !== commit)
+            return;
+        await writeFile(join(directory, 'rejected.json'), JSON.stringify({ commit, retryAfter: Date.now() + 15 * 60 * 1000 }), { mode: 0o600 });
+        if (pointer.previous && await ready(options, pointer.previous))
+            await writePointer(directory, { current: pointer.previous });
+        else
+            await rm(join(directory, 'current.json'), { force: true });
+    }
+    catch {
+        options.log?.('Could not record rollback; the bundled client remains available.');
+    }
+}
+// This policy is evaluated only after Sigstore verifies the certificate, signature,
+// transparency inclusion and exact workflow identity. No statement field is trusted first.
+export function releaseFromStatement(repository, statement) {
+    if (!REPOSITORIES.has(repository))
+        throw new Error('Unsupported update repository');
+    const s = statement;
+    const definition = s?.predicate?.buildDefinition;
+    const workflow = definition?.externalParameters?.workflow;
+    const source = 'https://github.com/' + repository;
+    const subject = s?.subject;
+    if (s?._type !== 'https://in-toto.io/Statement/v1' || s?.predicateType !== 'https://slsa.dev/provenance/v1' ||
+        definition?.buildType !== 'https://actions.github.io/buildtypes/workflow/v1' ||
+        workflow?.repository !== source || workflow?.ref !== 'refs/heads/main' || workflow?.path !== WORKFLOW ||
+        !Array.isArray(subject) || subject.length !== 1 || subject[0]?.name !== ARTIFACT || !DIGEST.test(subject[0]?.digest?.sha256)) {
+        throw new Error('Release provenance does not match the approved product workflow');
+    }
+    const dependency = definition?.resolvedDependencies?.find((item) => item.uri === 'git+' + source + '@refs/heads/main');
+    const commit = dependency?.digest?.gitCommit;
+    if (!SHA.test(commit))
+        throw new Error('Release provenance lacks an immutable source commit');
+    return { commit, sha256: subject[0].digest.sha256 };
+}
+async function download(url, limit, signal) {
+    const timeout = AbortSignal.timeout(30000);
+    const response = await fetch(url, { signal: signal ? AbortSignal.any([signal, timeout]) : timeout, credentials: 'omit' });
+    if (!response.ok || !response.body || !response.url.startsWith('https://'))
+        throw new Error('Update download unavailable');
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of response.body) {
+        size += chunk.length;
+        if (size > limit)
+            throw new Error('Update exceeds size limit');
+        chunks.push(Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks);
+}
+// The cache stores only the most recent fully verified bundle per product. Reusing
+// identical signed bytes avoids repeated Sigstore trust-root requests during polling.
+// Verification failures never enter the cache; the cache does not survive a restart.
+export function createReleaseVerifier(verify = verifyReleaseBundle) {
+    const verified = new Map();
+    return async (repository, bytes) => {
+        if (!REPOSITORIES.has(repository))
+            throw new Error('Unsupported update repository');
+        const digest = createHash('sha256').update(bytes).digest('hex');
+        const cached = verified.get(repository);
+        if (cached?.digest === digest)
+            return { ...cached.release };
+        const release = await verify(repository, JSON.parse(bytes.toString('utf8')));
+        verified.set(repository, { digest, release: { ...release } });
+        return { ...release };
+    };
+}
+const verifyLatest = createReleaseVerifier();
+async function signedLatest(options) {
+    const bytes = await download('https://github.com/' + options.repository + '/releases/latest/download/client-update.sigstore.json', 1024 * 1024, options.signal);
+    return verifyLatest(options.repository, bytes);
+}
+export async function verifyReleaseBundle(repository, bundle) {
+    if (!REPOSITORIES.has(repository))
+        throw new Error('Unsupported update repository');
+    if (!bundle?.verificationMaterial?.certificate && !bundle?.verificationMaterial?.x509CertificateChain)
+        throw new Error('Expected a signed workflow certificate');
+    if (!bundle.dsseEnvelope || bundle.dsseEnvelope.payloadType !== 'application/vnd.in-toto+json')
+        throw new Error('Expected signed provenance');
+    const { verify } = await import('sigstore');
+    const identity = 'https://github.com/' + repository + '/' + WORKFLOW + '@refs/heads/main';
+    await verify(bundle, {
+        certificateIssuer: 'https://token.actions.githubusercontent.com',
+        certificateIdentityURI: '^' + identity.replace(/[.*+?^$()|[\]\\]/g, '\\$&') + '$',
+        tlogThreshold: 1, ctLogThreshold: 1,
+    });
+    return releaseFromStatement(repository, JSON.parse(Buffer.from(bundle.dsseEnvelope.payload, 'base64').toString('utf8')));
+}
+export function verifyArtifactDigest(bytes, sha256) {
+    if (!DIGEST.test(sha256) || createHash('sha256').update(bytes).digest('hex') !== sha256)
+        throw new Error('Release digest mismatch');
+}
+function installEnvironment(options) {
+    // No provider keys or installation credentials reach dependency installation.
+    const env = {};
+    for (const name of ['PATH', 'HOME', 'USERPROFILE', 'SystemRoot', 'SYSTEMROOT', 'WINDIR', 'TEMP', 'TMP', 'TMPDIR', 'LOCALAPPDATA']) {
+        if (options.env[name])
+            env[name] = options.env[name];
+    }
+    env.PATH = dirname(process.execPath) + delimiter + (env.PATH || '');
+    env.npm_config_userconfig = join(updateDirectory(options), 'empty-user.npmrc');
+    env.npm_config_globalconfig = devNull;
+    return env;
+}
+async function npmCli() {
+    const nodeDirectory = dirname(process.execPath);
+    for (const candidate of [resolve(nodeDirectory, 'node_modules/npm/bin/npm-cli.js'), resolve(nodeDirectory, '../lib/node_modules/npm/bin/npm-cli.js')]) {
+        try {
+            await access(candidate);
+            return candidate;
+        }
+        catch { }
+    }
+    throw new Error('npm is unavailable beside Node');
+}
+async function prepareSigned(options, release, target) {
+    const bytes = await download('https://github.com/' + options.repository + '/releases/download/client-' + release.commit + '/' + ARTIFACT, 20 * 1024 * 1024, options.signal);
+    verifyArtifactDigest(bytes, release.sha256);
+    // Signature + digest checks precede archive parsing and any code/dependency execution.
+    const file = join(target, ARTIFACT);
+    await writeFile(file, bytes, { mode: 0o600 });
+    const tar = await import('tar');
+    let safe = true;
+    await tar.t({ file, onReadEntry: entry => {
+            const path = entry.path;
+            if (!['File', 'Directory'].includes(entry.type) || !path.startsWith('package/') || path.includes('\\') || path.split('/').includes('..'))
+                safe = false;
+        } });
+    if (!safe)
+        throw new Error('Unsafe release archive');
+    await tar.x({ file, cwd: target, strip: 1, strict: true, preservePaths: false });
+    await rm(file);
+    await access(join(target, 'npm-shrinkwrap.json'));
+}
+async function validateInstalled(options, target) {
+    const env = installEnvironment(options);
+    await writeFile(env.npm_config_userconfig, '', { mode: 0o600 });
+    const npm = await npmCli();
+    await exec(process.execPath, [npm, 'ci', '--omit=dev', '--ignore-scripts', '--no-audit', '--no-fund', '--cache', join(updateDirectory(options), 'npm-cache')], { cwd: target, env, timeout: 120000, maxBuffer: 4 * 1024 * 1024, signal: options.signal, windowsHide: true });
+    await validateConnection(options, target);
+}
+async function validateConnection(options, target) {
+    // Disable BOTH selection and background checks to validate this exact candidate.
+    // Setup checks enrollment/schemas, never a provider data query.
+    await exec(process.execPath, [join(target, 'dist/src/cli.js'), '--setup'], { cwd: target, env: { ...options.env, PATH: installEnvironment(options).PATH, GEORANKER_MCP_AUTO_UPDATE: '0' }, timeout: 30000, maxBuffer: 1024 * 1024, signal: options.signal, windowsHide: true });
+}
+async function acquire(directory) {
+    const lock = join(directory, 'update.lock'), token = randomUUID();
+    try {
+        await mkdir(lock);
+    }
+    catch {
+        try {
+            if (Date.now() - (await stat(lock)).mtimeMs < 600000)
+                return undefined;
+            let owner;
+            try {
+                owner = JSON.parse(await readFile(join(lock, 'owner.json'), 'utf8'));
+            }
+            catch { }
+            if (owner && Number.isSafeInteger(owner.pid) && owner.pid > 0) {
+                try {
+                    process.kill(owner.pid, 0);
+                    return undefined;
+                }
+                catch (error) {
+                    if (error.code !== 'ESRCH')
+                        return undefined;
+                }
+            }
+            await rm(lock, { recursive: true, force: true });
+            await mkdir(lock);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    await writeFile(join(lock, 'owner.json'), JSON.stringify({ token, pid: process.pid, createdAt: Date.now() }), { mode: 0o600 });
+    return {
+        async assertHeld() {
+            const owner = JSON.parse(await readFile(join(lock, 'owner.json'), 'utf8'));
+            if (owner.token !== token)
+                throw new Error('Update lock ownership changed');
+        },
+        async release() {
+            const owner = JSON.parse(await readFile(join(lock, 'owner.json'), 'utf8'));
+            if (owner.token === token)
+                await rm(lock, { recursive: true, force: true });
+        },
+    };
+}
+export async function checkForUpdate(options, fixture) {
+    if (!enabled(options))
+        return { status: 'disabled' };
+    let lock, staging;
+    try {
+        const directory = updateDirectory(options);
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        await mkdir(join(directory, 'releases'), { recursive: true, mode: 0o700 });
+        lock = await acquire(directory);
+        if (!lock)
+            return { status: 'busy' };
+        const now = Date.now();
+        if (!options.force) {
+            try {
+                const previous = JSON.parse(await readFile(join(directory, 'last-check.json'), 'utf8'));
+                if (Number.isSafeInteger(previous.checkedAt) && previous.checkedAt <= now &&
+                    now - previous.checkedAt < UPDATE_CHECK_INTERVAL_MS)
+                    return { status: 'deferred' };
+            }
+            catch { }
+        }
+        // Record attempts before network work, including failures, so reconnects and
+        // simultaneous hosts cannot multiply release-feed requests.
+        await lock.assertHeld();
+        await writeFile(join(directory, 'last-check.json'), JSON.stringify({ checkedAt: now }) + '\n', { mode: 0o600 });
+        const backend = fixture || {
+            latest: () => signedLatest(options),
+            prepare: (release, target) => prepareSigned(options, release, target),
+            validate: target => validateInstalled(options, target),
+        };
+        const release = await backend.latest(), commit = release.commit;
+        if (!SHA.test(commit) || !DIGEST.test(release.sha256))
+            throw new Error('Invalid signed release');
+        const pointer = await readPointer(directory);
+        if (pointer?.current === commit && await ready(options, commit))
+            return { status: 'current', commit };
+        let retryRejected = false;
+        try {
+            const rejected = JSON.parse(await readFile(join(directory, 'rejected.json'), 'utf8'));
+            if (rejected.commit === commit) {
+                if (rejected.retryAfter > Date.now())
+                    return { status: 'failed', commit };
+                retryRejected = true;
+            }
+        }
+        catch { }
+        const existing = await ready(options, commit);
+        let version = existing?.version;
+        const currentVersion = pointer?.current ? (await ready(options, pointer.current))?.version : undefined;
+        const versionFloor = currentVersion && !older(currentVersion, options.version) ? currentVersion : options.version;
+        if (version && older(version, versionFloor))
+            throw new Error('Cached update is older than the active client');
+        // A temporary hosted outage must not blacklist a valid signed release forever.
+        // Revalidate after cooldown without changing its immutable dependency tree.
+        if (existing && retryRejected) {
+            const candidate = join(directory, 'releases', commit);
+            if (fixture)
+                await fixture.validate(candidate);
+            else
+                await validateConnection(options, candidate);
+        }
+        if (!existing) {
+            staging = await mkdtemp(join(directory, 'staging-'));
+            await backend.prepare(release, staging);
+            const manifest = JSON.parse(await readFile(join(staging, 'package.json'), 'utf8'));
+            if (manifest.name !== REPOSITORIES.get(options.repository))
+                throw new Error('Update product mismatch');
+            version = manifest.version;
+            if (typeof version !== 'string' || older(version, versionFloor))
+                throw new Error('Update is older than the active client');
+            await backend.validate(staging);
+            await access(join(staging, 'dist/src/runtime.js'));
+            await access(join(staging, 'dist/src/cli.js'));
+            await writeFile(join(staging, '.ready.json'), JSON.stringify({ repository: options.repository, commit, version, sha256: release.sha256 }), { mode: 0o600 });
+            await lock.assertHeld();
+            await rename(staging, join(directory, 'releases', commit));
+            staging = undefined;
+        }
+        await lock.assertHeld();
+        const active = await readPointer(directory);
+        const activeVersion = active?.current ? (await ready(options, active.current))?.version : undefined;
+        if (activeVersion && version && older(version, activeVersion))
+            throw new Error('A newer client was activated during this update');
+        await lock.assertHeld();
+        await writePointer(directory, { current: commit, ...(active?.current && active.current !== commit ? { previous: active.current } : {}) });
+        options.log?.('Verified client update ' + version + ' is ready to apply when idle.');
+        return { status: 'prepared', commit, version };
+    }
+    catch {
+        return { status: 'failed' };
+    }
+    finally {
+        if (staging)
+            await rm(staging, { recursive: true, force: true }).catch(() => { });
+        if (lock)
+            await lock.release().catch(() => { });
+    }
+}
+export function startUpdateChecks(options, onChecked) {
+    if (!enabled(options))
+        return () => { };
+    const controller = new AbortController();
+    let running = false;
+    const check = async () => {
+        if (running || controller.signal.aborted)
+            return;
+        running = true;
+        try {
+            const result = await checkForUpdate({ ...options, signal: controller.signal, force: false, log: undefined });
+            if (!controller.signal.aborted)
+                await onChecked?.(result);
+        }
+        catch {
+            // Optional background housekeeping must not interrupt the MCP or log checks.
+        }
+        finally {
+            running = false;
+        }
+    };
+    void check();
+    const timer = setInterval(() => { void check(); }, UPDATE_CHECK_INTERVAL_MS);
+    timer.unref();
+    return () => { clearInterval(timer); controller.abort(); };
+}

package/dist/src/worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/worker.js

@@ -0,0 +1,10 @@
+// Internal worker entry. A supervisor owns the host's stdio connection.
+import { run } from './runtime.js';
+run().catch((error) => {
+    const value = error;
+    if (['REMOTE_SCHEMA_MISMATCH', 'REMOTE_PROFILE_MISMATCH', 'REMOTE_VERSION_MISMATCH', 'CLIENT_VERSION_MISMATCH'].includes(String(value?.code)) && typeof value?.message === 'string') {
+        // A bounded protocol diagnostic for the parent, never routine user-facing logs.
+        process.stderr.write('GEORANKER_WORKER_ERROR ' + JSON.stringify({ code: value.code, message: value.message.slice(0, 8192) }) + '\n');
+    }
+    process.exitCode = 1;
+});

package/docs/examples.md

@@ -0,0 +1,23 @@
+**SEO & SERP MCP by GeoRanker: first workflow**
+
+Show up to 20 Google organic results for car insurance in Bucharest, Romania, with positions, source URLs and freshness.
+
+Call search_serps with this input to request live fetching:
+
+```json
+{
+  "query": "car insurance",
+  "region": "Bucharest,Romania",
+  "searchEngine": "google",
+  "pages": 2,
+  "forceLive": true
+}
+```
+
+Omit forceLive or set it to false to allow seven-day completed-cache reuse. Live fetching bypasses the MCP cache, not the provider's own processing rules. If pending, call get_serp_result with the same jobId. Lookups never start another data job.
+
+Requested depth is at most 100 organic results; returned coverage may be lower. An absent domain is not found within the returned results, not a measured position beyond them. Use create_rank_tracking_report for multi-keyword/multi-location domain tracking and optional explicit recurring schedules. Lighthouse audits, internal-link crawls, backlink reports and keyword-volume reports have separate create/get tools. Recurring runs require operator enablement and can consume future credits. For an existing recurring rank report, forceLive or expired ready cache retrieves the same report and returns refreshNotice; it does not request a manual capture or create another schedule. Lighthouse output is a labeled summary without screenshots or detailed resource/audit tables. Report completion and provider coverage are returned as supplied; unknown completion is not a successful result claim.
+
+Display cached, cachedAt and generatedAt when available. A missing provider generation timestamp must not be invented. The default does not mean background refresh every seven days.
+
+Request independent tasks in parallel. The hosted service applies shared and per-installation limits and may briefly queue a call. Clients sharing an installation share its limits; the operator controls slots centrally. Keep pending job or report IDs and retrieve existing results. Cancelling a call does not guarantee that submitted work stopped. Completed-result reuse remains seven days by default.

package/docs/install.md

@@ -0,0 +1,160 @@
+**Install SEO & SERP MCP by GeoRanker**
+
+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.
+
+**Primary installation: npm**
+
+Use Node.js and npm, including npx. Supported Node.js versions are 22.22.2+ on the 22 release line, 24.15.0+ on the 24 release line, or 26.0.0+. Git and a TypeScript build are not required for the npm route.
+
+Run the setup check before configuring your host:
+
+```sh
+npx --yes @georanker/seo-mcp@0.14.0 --setup
+```
+
+These commands require @georanker/seo-mcp@0.14.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.
+
+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.
+
+The host examples below use the same npm bootstrap version. If a graphical application cannot find npx, use the absolute path to its executable and follow the host's platform-specific launch instructions. Preserve unrelated configuration entries. Reconnect the host after changes, enable/trust the tools when requested, then run the sample prompt.
+
+**GitHub source installation (fallback)**
+
+Use Git and the supported Node.js/npm runtime to build once:
+
+```sh
+git clone https://github.com/georanker/georanker-seo-mcp.git georanker-seo-mcp
+cd georanker-seo-mcp
+npm ci
+npm run build
+node dist/src/cli.js --setup
+```
+
+For a source installation, replace each npx command and its package arguments in the host examples with node and the absolute path to this checkout's dist/src/cli.js. For example, use "command": "node" and "args": ["/ABSOLUTE/PATH/dist/src/cli.js"] in an mcpServers entry. If the application cannot find Node, set command to the absolute node executable path. Keep that launcher path stable for future updates.
+
+**Automatic updates**
+
+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.14.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.
+
+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.
+
+The launcher verifies the package's signed provenance against the expected public repository, main-branch release workflow and commit, then checks its artifact checksum. It prepares the verified package in a separate cache and installs its locked production dependencies without lifecycle scripts. It does not download and execute an unverified branch checkout. A stable supervisor keeps the host MCP connection open and runs tools through an internal worker. A verified candidate replaces the worker when no tool calls are active and 60 seconds have passed without tool activity. This idle period concerns the MCP connection, not the whole AI host or existing provider jobs. Calls are never replayed as part of a swap. If the candidate fails, the current worker continues. The prepared version is also available on later launches when GitHub is unavailable.
+
+Updates require a supported Node.js version and npm on the MCP process's PATH, access to GitHub, the npm registry and the signature verification service, and write access to the update cache. Git and a TypeScript build are only needed for the source fallback, not for npm installation or automatic updates. The default cache is ~/.config/georanker-mcp-updates/georanker-seo-mcp. Set GEORANKER_MCP_UPDATE_DIR to choose another cache root. This is separate from your existing identity and credentials, which are preserved.
+
+With automatic updates enabled, prepare the latest signed release immediately:
+
+```sh
+npx --yes @georanker/seo-mcp@0.14.0 --update
+```
+
+For the source fallback, use:
+
+```sh
+node dist/src/cli.js --update
+```
+
+A running 0.13.0+ supervisor applies a prepared compatible worker during the next idle period. After a cancelled or timed-out worker request, automatic worker swaps wait for a normal host reconnect because completion is uncertain. Changes to supervisor code itself take effect on a normal host restart or MCP reconnect. Set GEORANKER_MCP_AUTO_UPDATE=0 in the host's MCP environment to disable automatic updates. A failed release workflow, download, signature verification or setup check leaves the available client version in place. Automatic checks are quiet when no update is available or a check cannot complete. An applied update is reported on stderr, separate from the MCP protocol.
+
+**Migration for existing installations**
+
+Existing 0.12.0 installations can prepare a current signed release automatically and load its 0.13.0+ supervisor on the next host restart or MCP reconnect. After that one reconnect, compatible worker updates apply inside the session during idle periods. Future changes to the supervisor itself still require a normal restart.
+
+To switch an existing source installation to npm, run the npm setup command above once the package version is published, replace the host's node/source-path command with the matching npx command below, and reconnect. Keep the same GEORANKER_STATE_DIR, service origin and environment settings. Both routes reuse the existing installation identity and credentials; do not delete state or create a second installation to migrate.
+
+Clients older than 0.12.0 cannot update themselves. Switch to npm as above, or update the existing source checkout of the public repository and run this once:
+
+```sh
+git pull --ff-only
+npm ci
+npm run build
+node dist/src/cli.js --setup
+```
+
+Then restart or reconnect the MCP in your host. Keep the existing launcher path and credentials. Subsequent compatible worker updates that pass the public main release workflow are prepared and applied during idle periods, without another reinstall.
+
+**Codex**
+
+```sh
+codex mcp add georanker-seo -- npx --yes @georanker/seo-mcp@0.14.0
+```
+
+Use /mcp to inspect the connection. [Official guide](https://developers.openai.com/codex/mcp).
+
+**Claude Code**
+
+```sh
+claude mcp add --scope user --transport stdio georanker-seo -- npx --yes @georanker/seo-mcp@0.14.0
+```
+
+Use /mcp to inspect the connection. [Official guide](https://code.claude.com/docs/en/mcp).
+
+**Hosts using an mcpServers object**
+
+```json
+{
+  "mcpServers": {
+    "georanker-seo": {
+      "command": "npx",
+      "args": ["--yes", "@georanker/seo-mcp@0.14.0"]
+    }
+  }
+}
+```
+
+| Host | Where to add the entry | Extra step |
+| --- | --- | --- |
+| [Claude Desktop](https://claude.com/docs/connectors/building/mcpb) | Developer MCP configuration opened through application settings | Restart/reconnect; a tested .mcpb installer is planned, not supplied in this release |
+| [Cursor](https://prod.cursor.com/docs/mcp) | ~/.cursor/mcp.json or project .cursor/mcp.json | Add type: stdio to the server entry; enable it |
+| [Windsurf](https://docs.windsurf.com/windsurf/cascade/mcp) | Cascade MCP configuration, normally ~/.codeium/windsurf/mcp_config.json | Verify the current app/version path, then refresh tools |
+| [Cline](https://docs.cline.bot/mcp/mcp-overview) | MCP Servers > Configure > Configure MCP Servers | Save and reconnect |
+| [Continue](https://docs.continue.dev/customize/deep-dives/mcp) | .continue/mcpServers/mcp.json | Use Agent mode |
+| [Gemini CLI](https://geminicli.com/docs/tools/mcp-server/) | Merge into ~/.gemini/settings.json | Inspect /mcp; user scope shown |
+| [OMP / Oh My Pi](https://github.com/can1357/oh-my-pi/blob/main/docs/mcp-config.md) | ~/.omp/agent/mcp.json or project .omp/mcp.json | Add type: stdio; inspect /mcp and avoid duplicate imported entries |
+
+**VS Code / GitHub Copilot**
+
+Use “MCP: Add Server,” or .vscode/mcp.json with a servers object:
+
+```json
+{
+  "servers": {
+    "georanker-seo": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["--yes", "@georanker/seo-mcp@0.14.0"]
+    }
+  }
+}
+```
+
+Start/trust the server and enable its tools. [Official guide](https://code.visualstudio.com/docs/agent-customization/mcp-servers).
+
+**OpenCode**
+
+Merge into opencode.json:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "georanker-seo": {
+      "type": "local",
+      "command": ["npx", "--yes", "@georanker/seo-mcp@0.14.0"],
+      "enabled": true
+    }
+  }
+}
+```
+
+Run --setup before adding the entry to avoid first-enrollment work during the host's short discovery timeout. [Official guide](https://opencode.ai/docs/mcp-servers/).
+
+**First prompt**
+
+> Show up to 20 Google organic results for car insurance in Bucharest, Romania, with positions, source URLs and freshness.
+
+By default, eligible completed data can be reused for up to seven days. Add “Force a live fetch” to request forceLive: true. That bypasses the MCP's completed cache; pending work can be reused and should be retrieved using get_serp_result. It does not schedule automatic refreshes or guarantee instant completion.
+
+Host configuration formats above are documented compatibility routes. Local protocol fixtures do not prove each host or operating system has been exercised. Cloud-only connections require a separately tested remote authentication path; do not assume the current endpoint URL is sufficient.

package/docs/privacy.md

@@ -0,0 +1,21 @@
+**Client data flow and storage**
+
+This package runs a local MCP process that connects over HTTPS to GeoRanker's hosted service. It sends the requested search arguments or public page URL, an installation identifier, a revocable access token and a persisted device signal. GeoRanker processes requests with its upstream infrastructure. The client contains no reusable provider API key, admin interface or hosted-service implementation.
+
+On first enrollment, the client generates an Ed25519 signing identity and saves it with its installation credential. Both GeoRanker products reuse the existing directory under ~/.config/georanker-search-mcp/client/ for the same service origin. Private directories use mode 0700 and credential/identity files use mode 0600 where the operating system supports these modes. GEORANKER_STATE_DIR can select a different private storage location. The device signal is self-reported, not hardware attestation.
+
+Keep this state private. Do not commit it, share it or delete it to evade allowances. A saved identity can recover a lost token without creating a new allowance. Revocation and account association are managed by the hosted service. Removing the MCP configuration stops the host from launching it; it does not automatically erase credentials or revoke an installation.
+
+The MCP cache defaults to seven days, subject to operator configuration. It is shared according to the service's account and request isolation, and should not be used for secret URLs or sensitive page content. forceLive: true requests fresh upstream work instead of a completed MCP cache hit. Source results remain untrusted content for the host AI to interpret.
+
+Automatic enrollment is not OAuth. The hosted endpoint and public protocol can be inspected even though the service source is private. This file describes client behavior and does not replace GeoRanker's privacy policy or service terms.
+
+**Automatic client updates**
+
+Installing or launching through npx can contact the public npm registry to download the bootstrap package and dependencies. npm receives ordinary network request metadata, not the GeoRanker installation credential or signing key. A version in the npx command pins that npm bootstrap package; it does not disable the separate GeoRanker updater described below.
+
+From version 0.13.0, the launcher checks for releases from the corresponding public GeoRanker GitHub repository at startup and every five minutes while running. Update downloads contact GitHub, signed-provenance verification can contact Sigstore services, and locked production dependency installation contacts the npm registry. These services receive ordinary network request metadata. The update check does not send your GeoRanker installation credential, signing key, provider data or request history to GitHub, Sigstore or npm.
+
+Verified release packages, dependencies and compiled client files are stored separately under ~/.config/georanker-mcp-updates/, in a directory for each product. GEORANKER_MCP_UPDATE_DIR selects another update cache root. Updating preserves the installation state described above. The updater verifies signed provenance for the designated public repository, release workflow and main-branch commit before installing a package. It installs locked production dependencies without lifecycle scripts. Its setup check contacts the existing GeoRanker service using the installation's existing enrollment path and does not create provider data jobs.
+
+The supervisor maintains the host's MCP connection while an internal worker runs tool calls. A verified worker update becomes active when no tool calls are active and the connection has had no tool activity for 60 seconds. This concerns MCP activity; it does not inspect the whole host or wait for persistent provider jobs to finish. Calls are not replayed, and a failed candidate leaves the current worker in place. Worker replacement preserves installation state and does not create provider data jobs. Automatic update checks stay quiet unless an update is applied. Supervisor code changes take effect on the next normal client start; existing 0.12.0 clients load a current release's 0.13.0+ supervisor on their next reconnect after preparing it. Set GEORANKER_MCP_AUTO_UPDATE=0 in the host's MCP environment to disable automatic updates and run the configured bootstrap version, then restart or reconnect. Because enabled updates run future client releases published by GeoRanker's verified public main release workflow, users who need to review and pin each release should set this variable to 0 and manage their installation explicitly.